Dilettante Habits

Knowing nothing about everything

• Home
  • Research
  • Impressum
• Software
• Blog
  • Recent
  • Topics

Abstract: A small library for parsing command line options.

Topics: software engineering/options, libraries, downloads, open source

© Copyright Daniel Krajzewicz, 07.08.2021 19:50, cc by

Command line applications are still a valid technology, especially for writing software that is meant to be processed in batch. Usually, each command line application needs some parameters or information about what has to be processed and how. There are some rules or common practices regarding the syntax for passing these parameters on the command line.

While working on the SUMO package I missed a proper object oriented solution in C++. Therefore, I have developed a library for handling of a command line application's options in a common way, including methods for things such as type checking or pretty printing a help screen. For simplicity, the libraries' name is “optionslib”. You may find it at github, the C++ version at optionslib_cpp, and the Java version at optionslib_java. It is meant to be a replacement for C's getopt function or Java's commons-cli. The library assumes that your options are split and given as the case on Linux/UNIX and works on Microsoft Windows command shell as well. The library is licensed under the Eclipse Public License — v 2.0.

In the following, you will find some information about standards, conventions and common practices for defining a command line application's parameters, first. Then, I will briefly outline why I designed this library. Then, the library itself is presented. Finally, you may find some further references as well as the list of changes.

There are some conventions for command line options^[1]:

• Often, the same option can be defined in two different ways, on the one hand via its full name, e.g. --set-first-parameter-to <VALUE>, and on the other hand using an abbreviation, e.g. -1 <VALUE>. On Linux/UNIX systems, one-char abbreviations of option names are preceded by a ‘-’ while full option names are preceded by ‘--’, usually. The Java style is to use one ‘-’ in any case. On Microsoft Windows often a ‘/’ is used instead of a ‘-’;
• Options can be concatenated. For example the “tar” application can be started with -xvf <FILE>. This forces the verbose mode (-v), tells the application to extract (-x), and defines the file to process (-f <FILE>).

I have designed this library because of being annoyed by the getopt function that is usually used in applications written in C. When using getopt, your application has to deal with every single option one by one. You have to store them in a container or static (sic!) variables, do type checking for each option individually, maybe even multiple times, and stuff like that. It is not really nice.

The option is solving these issues by storing the given options in a single container. While being filled, it is checked whether the supported values can be converted into the type of the respective option. In addition, the library supports configuration files.

The library should have the following features:

• type checking: when entering a parameter, its type shall be checked. So, if an integer value (number) is required, one shall not be able to give something like “hello”;
• boolean options: Every boolean option (yes / no) is assumed to be “false” on default. A boolean option shall thereby not get any argument, but just set the option's value (parameter) to “true”;
• load options files: Besides reading options from the command line, the library should be as well capable to read them from files;
• check for double definition: It should not be allowed to set an option twice on the command line or within a single configuration file;
• exception handling: When a mistake has been done in using the library (e.g., the same abbreviation is set for two options), a specific exception, which does not have to be handled by the application for making it appear in the first Debug run, shall be raised;

The library uses a very basic object oriented approach. Every single option is represented by a single instance of a class that is derived from Option. The derived classes represent the realised types — Option_Bool, Option_Int, Option_Double, Option_String, Option_FileName. The options are stored in an OptionsCont — options container. Basically, that's all. Some further classes are given for parsing the application's parameters and storing them or for loading them from files.

The library is located at optionslib_cpp. The current release is v1.2:

• optionslib_cpp-1.2.zip;
• optionslib_cpp-1.2.tar.gz.

You may as well find a verbose documentation of the optionslib_cpp library at github. A doxygen class documentation for optionslib_cpp exists as well.

The library is located at optionslib_java. The current release is v1.2:

• optionslib-1.2.jar
• optionslib_java-1.2.zip
• optionslib_java-1.2.tar.gz

You may as well find a verbose documentation of the optionslib_java library at github. A doxygen class documentation for optionslib_java exists as well.

I personally use optparse. It comes with almost all the features that were put into requirements for this library.

I do not know any. If you have any issues, please let me know.

You may find current extension requests — and add own ones — at the respective issues page:

• optionslib_cpp issues;
• optionslib_java issues.

Both, the C++ as well as the Java versions are licensed under the Eclipse Public License v2.0.

In the following, you may find some further references to additional information.

• [1] Wikipedia article about the Command-line interface;
• [2] Conventions for Command Line Options by Chris Wellons;
• [3] Command-Line Options — default meanings of command line options.

Changes:

• Added methods for saving XML-configurations and XML-templates;
• Improved error reporting;
• Moved printHelp to OptionsIO.

A first version was released on the 8^th of October 2019.