Parsley: a Command-Line Parser for Astronomical Applications

William Deich

Netherlands Foundation for Research in Astronomy, P.O. Box 2, 7990 AA Dwingeloo, The Netherlands

Abstract:

1. Introduction

Parsing command lines and interpreting optional and required arguments is a mundane but essential part of many programs. Parsley is a library of routines that aims to provide a consistent user interface across applications, good command-line help, and plenty of convenience features to aid both the user and programmer.

Both simple and complex command-line parsers have been written in the past. Perhaps the most familiar of these is getopt(3), a routine that parses single-letter option strings, including options that require a single argument. Of growing popularity is the GNU version of the same routine, which allows long option names. Yet neither of these handles vectors of data, and they don't address the common problems of providing help information or simple argument-validation checking (such as verifying that an argument is an integer). Public-domain packages have been written which do address some of these problems, but they are generally written for C or C++ applications, and are not easily called from Fortran programs.

2. Design Goals

Parsley was designed with two goals in mind: to make it easier for users to enter arguments on the command line, and to make it easier for programs to collect and validate the arguments. In its very first incarnation (an afternoon's programming), the goal was modest: to provide support for vectors, and to provide builtin help.

Parsley has grown greatly since then, in order to provide many more user-friendly features. Unfortunately, some of this growth has required a larger programming interface, which takes away from the goal of programming ease. However, by carefully maintaining sensible defaults, parsley makes sure that programs never have to call any but the basic interface. Access to the special features is obtained through ancillary function calls.

3. Consistency and Convenience for Users

The emphasis on ease of use has endowed parsley with a very large number of features which cannot all be covered in this brief space, so below are listed just some of its user-interface capabilities.

• A standard command-line interface across programs.

• The command-line interface handles vectors as easily as scalars; copying the values to an array (that can be provided by the programmer or dynamically allocated by parsley).

• Good help information is provided for every key ( -h always gets help).

• Convenient default rules are used when keys aren't given, so that values can often be assigned to the correct keys without naming them.

• Long names are used for keys, but unique abbreviations are accepted.

• A wide variety of date, time and angle formats are accepted.

• Arguments used on one invocation of a program can be automatically used as the default values for the next.

• It is as easy to read data from files as from the command line: typing @ file causes the named file to be interpolated at that point.

• The syntax for numbers is usefully extended, allowing integers such as 2e3 (2000), 2e3x5 (), 2K (2048), and '13616 (65536).

• Floating-point values are similarly extended.

• Dates and angles get thorough support. For example, the xdate (extended date) type is a specifies a complete date plus time. Its format is one of:
  • Any reasonable day, month, and year combination (the month can be given as a number or its abbreviated English name), with an optional comma and/or whitespace-separated h:m:s value (example: 1988-mar-13,18:12:34.567);

  • one of xxx.x [jmft], where the suffix means JD, MJD, FUT, or truncated JD, respectively; a good guess is made if no suffix is given (example: 2447234.258733414352);

  • yyyy,ddd.d, specifying a year plus decimal day value (example:
    1988,73.758733414352);

  • yyyy,ddd[,]hms, specifying a year, day number, and time (example: 1988,73,18:12:34.567).

• Many shortcuts are provided for entering vectors of data: means m repetitions of x; m-n means ; is similar, but changes the step to s; and several others.

• Simple entry of column or row data. Since parsley is designed around command-line input, it reads row-vectors by default. However, it is possible to tell parsley to read values in a cycle, in which case it assigns values cyclically to the n keys. If there are n columns in the input stream, the effect is to read one column for each key.

• Dozens of built-in options (invisible unless the user uses the alternate help key -H) give detailed customization of the input processing.

4. Files and Commands with Parsley Input

Parsley goes to some effort to make sure it can read files as easily as command lines. At any point, you may place an argument of the form @ filename (the whitespace is optional), in which case the file contents are ``interpolated'' into the input. The effect is much the same as if you typed the contents of the file in place of the @ filename string. Some special strings that may be used in place of the filename are:

 
 -- 	        read standard input;

 < d  or <& d 		
		read from file descriptor  d (a digit).

 | command	interpolate the output of the given shell  command.

Otherwise, if the filename isn't an existing file, parsley will apply its smart filename guessing rules. Frequently, a series of files will be named something like scan499050001.dat, scan499050002.dat, etc. A typical parsley program will receive the correct filename if the user simply enters 1.dat, 2.dat, etc. (or even just types `` 1,'' `` 2,'' etc.).

5. Consistency and Convenience for Programmers

Parsley not only makes the user's life a bit easier, it also simplifies the programmer's task through a variety of mechanisms.

Again, only a subset of parsley's features can be summarized here.

• Programs that have simple argument lists are simple to write--- parsley's special features stay out of the way until needed.

• Each kind of data (such as dates, angles, times) is accepted in a wide variety of formats, but parsley always converts each type to a single internal representation (for example, angles are always returned as radians, regardless of input format).

• The Fortran and C calling interfaces are as nearly identical as can be accommodated.

• When a key is declared, the programmer specifies its name, address where the values are to be stored, data type, help text, number of permitted values, and whether the space is to be dynamically allocated by parsley or provided by the caller. Thereafter parsley takes care of parsing the command line, validating the data type, allocating space, and storing values.

• A single input file can contain parameters for multiple, related programs. Each program can declare the keywords that it doesn't need---but knows are in the file---as ignored. The extraneous keys and values will then be ignored by parsley instead of generating errors.

• If event-driven processing is required, or if some peculiar processing is necessary when a certain key is seen, the programmer can register a function to be called each time that key or a value for it is encountered. A function may also be registered to call at the end of all input.

• Inter-key dependencies get good checking: parsley can be told that certain keys must appear together, or may never appear together. For instance, one can state that options -ra and -dec must always appear together, but never with options -l and -b. Two keys can be required to be given the same number of values (for example, -ra and -dec must come in pairs). Finally, it can be required that a key has the same number of values as the value of another key (for example, keys -gain and -Tsys must both have the same number of values as is indicated by the value of the key -nbands).

6. Future Directions

Parsley's most important evolution for the near future is to provide a graphical user interface. It already knows enough to automatically generate a good menu-based interface, and it is requires only a few more routines to give the programmer more detailed control over the presentation of the graphical interface to the user. The user will be presented a window with a nicely (nested) menus, and a ``go'' button to start the program running; standard output and standard error can either go to a subwindow or to the original location from which the program was started.

Two less-visible changes are also in the works. First, parsley's design makes it inefficient when reading large arrays, and its internal design must be overhauled so that it can process these many times faster than it currently does. Second, parsley will be modified so that it can handle arbitrarily complex structures of data, not merely arrays of atomic types.

Parsley is available for anonymous ftp from
ftp.nfra.nl:pub/outgoing/will/parsley- version.tar.gz.