Yagol: Another Getopt Library
 
News
1.5 Released

Thursday, 06 February 2003 1.5 has been released. Multi-value options now terminate with --end. Values from rc file are retained in the order in which they were read. Library can be compiled to use sstream, instead of strstream, by defining HAVE_SSTREAM. Previously, an option that happened to be a substring of another option would result in an "ambiguous option" error message. This has been fixed.

News
1.4 Released

Thursday, 2 May 2002 1.4 has been released.

Description

Yagol is a C++ library that processes configuration input: command-line options, environment variables, and resource files. It handles data conversion and validation with primitive C++ types (and std::string and std::vector). Descriptions are closely tied with the variables they represent. The main idea is to have a single point of representation for variables within an application, and to make option processing as simple and non-instrusive as possible.

The user interface is also designed with simplicity and intuitiveness in mind. Of special note is the --end-of- tag, which allows the user to provide arguments such as:

    % app --headers *.h --end-of-headers --doc *.info --end-of-doc --src *.cpp --end-of-src

Yagol is mostly compliant with POSIX. Where it is not compliant is in the processing of multiple values for a single option.

Minimal usage of Yagol is straightforward and simple. However, it has the ability to perform fairly complicated behavior associated with a function, via the usage of callbacks.

See the applications in the test directory for examples, primarily the file Features.t.cpp, which contains tests of all of the features available. A simpler example can be found in Minimal.cpp, which is documented here.


Example

Yagol is a C++ library that processes configuration input: command-line options, environment variables, and resource files. Its usage is as follows:

    string user("jrandom");
    int    size(17);
    bool   readonly(false);
    vector dimensions;
    dimensions.push_back(0);
    dimensions.push_back(10);
    dimensions.push_back(0);
    dimensions.push_back(20);
    
    const int appSettings = yagol::AppOptionSet::STRICT_ARGUMENTS | yagol::AppOptionSet::HELP_ON_ERROR;
    yagol::AppOptionSet opts(appSettings, "myapp", "my interesting application.");
    opts.addOption("user",       "The user of the software",       &user);
    opts.addOption("size",       "The size of the something",      &size);
    opts.addOption("readonly",   "Whether to read, and not write", &readonly);
    opts.addOption("dimensions", "The geometrical dimensions",     &dimensions);

    opts.process(argc, argv);

    // unused arguments
    vector unused = options.getUnprocessedArgs();

That block of code:

  • sets default values for application variables
  • creates the Yagol option processor, saying that command-line arguments that look like options should be treated as errors if not found; and that in the event of user error (invalid data, bad option), the help/usage statement should be displayed.
  • creates a list of options, each with their tag (e.g., "--user"), their description, and the variable to which they are tied
  • processes the options. At the end of this, the user, size, etc., variables will have the values provided in the command-line arguments, or they will retain their default values.
  • gets the unprocessed ("unconsumed") command-line arguments

The user interface would then be as follows. To get the help/usage statement:

    % myapp --help

    Usage: myapp 
        My interesting application.
    
    Options:
        --user          The user of the software (default = "jrandom")
        --size          The size of the something (default = 17)
        --readonly      Whether to read, and not write (default = false)
        --dimensions    The geometrical dimensions (default = 0, 10, 0, 20)

Setting the variables:

    % myapp --user george --size 4 --readonly --dimensions 100 24000 400 48000 --end-of-dimensions

Setting the same values, but using shorter names. Options may be abbreviated to the point that they are unique, compared to any other option.

    % myapp  --u george --s 4 --r --dim 100 24000 400 48000 --end-of-dim

Boolean options may be given 'false' values by using the form --no<name>:

    % myapp --noreadonly

See intro.html for more.

Documentation

The man page is not yet written.

Download
Current version
Version Notes
yagol-1.5-1.i386.rpm
yagol-1.5-1.src.rpm
yagol-1.5.tar.gz
Contact

Feedback is very appreciated.

Bug reports and feature requests should be submitted via the project page at SourceForge.

email: Jeff Pace.

SourceForge Logo

To Do / In Progress
  • add a "hello, world" program
  • add shortcuts for the most common setup(s)