Skip to content

Home

Jump to bottom
rockdoc edited this page Nov 22, 2012 · 17 revisions

About cdlparser

The cdlparser module implements a Python-based parser for reading files encoded in netCDF-3 Common Data form Language, a.k.a. CDL. The parser logic is based upon the tokens and rules defined in the flex and yacc files as used by the ncgen3 utility that ships with the standard netCDF distribution.

If all you want to do is convert a CDL file to a netCDF file, then ncgen is still the command to use. If, however, you are wanting to incorporate CDL-reading capability into an existing or new Python-based workflow - and you don't want to drop out to a shell to invoke ncgen - then cdlparser may work for you.

One potentially useful application of cdlparser is to generate netCDF files on-the-fly from CDL text files as part of a Python unit test suite. In this way you don't need to maintain a collection of netCDF binary files; instead you can simply keep the equivalent CDL text files in your repository and use those with your unit tests.

Package Dependencies

The cdlparser module depends upon the following Python packages. If you don't already have these then you'll need to download and install them.

The latter package has its own multiple dependencies, of course (e.g. netCDF4, HDF5, NumPy, and so on). These too will need to be installed. Please refer to the respective documentation. I'm rather assuming that if you're interested in parsing CDL files then you're probably working with these packages already.

Basic Usage

The basic usage idiom is as follows:

from cdlparser import CDL3Parser
myparser = CDL3Parser(...)
ncdataset = myparser.parse_file(cdlfilename, ...)

If the input CDL file is valid then the above code should result in a netCDF-3 file being generated, either in the same directory as the CDL file (and with the .cdl extension replaced with .nc), or else in the location specified via the (optional) ncfile keyword argument to the parse_file() method.

The ncdataset variable returned by the parse_file() method is a handle to a netCDF4.Dataset object, which you can then query and manipulate as you wish. By default the Dataset.close() method is invoked when the parsing has completed. You can skip that call by setting the close_on_completion keyword argument to False when the parser object is created, thus:

myparser = CDL3Parser(..., close_on_completion=False)
ncdataset = myparser.parse_file(cdlfilename, ...)

By default the name of the netCDF file produced by the parse_file() method is taken from the name defined in the first line of the CDL file, just as the ncgen command does. You can supply a different filename, however, via the optional ncfile keyword argument, e.g.:

ncdataset = myparser.parse_file(cdlfilename, ncfile="/my/nc/folder/stuff.nc", ...)

Unsupported Features

The following CDL v3 features are not supported by cdlparser:

  • Use of the 'l' or 'L' suffix to indicate integer constants. This feature has been deprecated.
  • Use of the lexical tokens DoubleInf, NaN, +/-Infinity, FloatInf, +/-Inff. These tokens were used to indicate fill values prior to netCDF 2.4 (according to the ncgen.l file).

Enjoy!

-- rockdoc

Clone this wiki locally