h5gen - generate HDF5 files from Data Description Language (DDL) files

h5gen -o output.h5 input.ddl
h5gen input.ddl         # take name of output file from DDL itself
some_source | h5gen     # read DDL text from stdin

h5gen takes as input text written in Data Description Language (DDL) syntax, and generates Hierarchical Data Format version 5 (HDF5) files from it. In a sense, it is the reverse operation of h5dump, a tool bundled with the HDF5 distribution that takes HDF5 files and converts them to DDL.

This software is beta quality and comes without any warranty (see the license for the full details). It was written to solve a particular problem, and may not be suitable for your purpose(s).

Do not use this tool in production. In particular, this tool

• is unfinished
• relies on an informal specification that may change without prior notice
• has not been tested exhaustively (there are tests, but they are not waterproof; the external utilities used for comparing may fail to detect differences)
• is not designed for high performance

• -o output.h5

  Optional. Specify the name of the output HDF5 file (usually ends in .h5, but it need not). By default, the name inside the DDL text is used (the text string that follows the HDF5 keyword).

• input.ddl

  Optional. Specify the name of the input file containing DDL text. By default, h5gen reads from stdin.

I wrote this tool because I needed small HDF5 files as test input files in another project. At the time, there didn't seem to be a quick and easy way to generate HDF5 files without using the C/C++/Fortran/... API; in short, without writing a program. But the syntax of DDL is so simple to understand and write, that the idea of writing a parser for DDL seemed very appealing. So I wrote one.

It's perhaps necessary to say what this tool is not. I wrote this tool only to solve my immediate problem. Many features are lacking, many valid DDL constructs are not recognized, and it is entirely possible there are serious problems I have not yet discovered. It is not a general or recommended means of generating HDF5. You should really use the C (or C++/Fortran/Java/...) API for that. Those interfaces are likely much better tested, and much more performant. This tool is not meant to be a DDL validator; it may accepts constructs that do not represent the DDL that would be generated by h5dump. Also, please note that the DDL specification is by no means official; it is informative at best, and may change at any time without prior notice. As far as I know, there are no regression tests for the output of the h5dump tool (the principal producer of DDL), so h5gen may break at any future update of the HDF5 library.

That said, if you need a tool to quickly hack together HDF5 files for testing (as I did), here it is. If you want to know which features are supported, or if you want to understand how much you can trust this tool, have a look at the tests (the test data files reside in ddl/ and h5/).

h5gen can be found at https://github.com/ebaudrez/h5gen.

./configure --with-hdf5=DIR
make
make check              # perform the self-tests; recommended
make install

h5gen is managed using Autoconf and Automake. Installation is fairly straightforward. The options of configure are standard, with one package-specific option of note:

• --with-hdf5=DIR

  Optional. Specifies the path where the HDF5 library is to be found (executables, include files, library). By default, looks into your system's default paths.

I recommend you run the self-tests by issuing make check after compilation. Even though they take a while to run, they may alert you of possible problems (e.g., when you are using another version of the HDF5 library than the one I have tested against). Any self-test failure should be considered a bug.

For more detailed installation instructions, please refer to the file INSTALL inside the distribution.

• version 0.1, 18 June 2015

  First public release.

None known. Feedback and bug reports welcome.

The HDF5 library and its documentation at http://www.hdfgroup.org/HDF5. In particular, the syntax of the Data Description Language (DDL) is documented at http://www.hdfgroup.org/HDF5/doc/ddl.html.

Copyright (C) 2015 Edward Baudrez edward.baudrez@gmail.com

h5gen is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

h5gen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with h5gen; if not, see http://www.gnu.org/licenses/.