Argument Parser Introduction |

The argument library gives you the ability to parse the command line arguments that are passed to your application. It is a feature-rich library that tries to achieve the maximum comfort for the developer and for the user of the application at the same time.

## About arguments

Arguments normally come in two different forms: options and parameters. Parameters (sometimes also called operands) are the main inputs to the program, for example the filename to be edited in a text editor or the URL that a web-browser should open on startup.

    myprog parameter1 parameter2 ... parameterX

Options - on the other hand - are normally not mandatory for the proper operation of the application. They are introduced with the - (minus) character.

There are short options and there are long options. Short options are introduced by a - (a single minus) followed by a single character. Long options are introduced by -- (two minus) and the name of the option.

    myprog -o --foo --bar=HALLO

In the given example, -o and --foo are so-called flags to the program. Flags are options that do not take any argument. The option --bar is an option that takes an argument, in this case the string HALLO.

Options and parameters can be mixed together and there are ways to combine options. This can create complex command lines. The following is an example call of the GNU ls command available on most Linux systems:

    /bin/ls -Al /tmp -I '*~' -I*.bak --color=always

Here, /tmp is the only parameter. The flags -A and -l have been merged into a single option. The option -I is set twice with the argument '*~' and '*.bak' and the option --color is set with the argument 'always' (note that the command line parser does not care whether the arguments to a short options are introduced by a space or follow directly).

## Design decisions and goals

The main focus of a developer is to create a program that provides a functionality. Comfortable command line parsing is difficult. Many programmers regard it as dispensable and few invest the necessary time to get it right.

As a consequence, the command line behavior of tools varies a lot. There are probably as many ways to parse the command line as there are developers writing applications. Help text is bad or missing.

The Gobo Eiffel Argument Library makes it simple to do proper command line parsing. You define a number of options that the application should have, call the parser and check which options were supplied and what the applications parameters are.

It should be easier to parse the command line of the application with the library than to write a manual parser, even if the application only has one or two options. Only this can motivate developers to use the library for their applications. At the same time, the library should provide a maximum in comfort for the user of the application, including support for many option styles, abbreviation facilities, and a useful, automatically generated help text.

With these goals in mind, the library will not satisfy every need you might have for parsing. Specially, the library imposes a certain standard way of command line parsing onto the application. If you want a very different way of command line parsing, perhaps because you want to be 'backward compatible' with another application, the argument parsing library might not be the best choice for you. Also, if you have a very large application that requires complex argument patterns, then you will need a significant amount of extra work to parse them using this library.

This being said, it is my firm belief that the library should be suited for most application needs. And it enforces a consistent behavior of different applications, something that your users will appreciate.

## Feature overview

- Different types of options: flags, strings, integers, booleans ...
- Long (--make-love) and short (-l) options are supported.
- Short form can be joined (-abc instead of -a -b -c), assuming that every one but the last is a flag (does not require an argument).
- Arguments to the short form can be added with or without space (-ltoday or -l today).
- Arguments to the long form can be added with '=' or with a space (--make-love=today or --make-love today)
- Option termination introduced by '--'.
- Usage instructions and a help text will be generated automatically from the options.
- Good default values, minimal code is required for standard applications.
- No special 'option description language' is required. It is all just plain Eiffel code.

## Usage strategy

The general usage strategy of the argument parser library involves the following four steps:

1. Create an instance of `AP_PARSER` and configure it (for example setting up a descriptions of the application).
2. Create instances of options types, that is of the classes that inherit from `AP_OPTION`. Configure these instances (for example with a help text for this option). Register these options at the parser.
3. Parse the command line, most of the time by just calling `parse_arguments` on the parser.
4. See if options were found by calling `was_found` in its instances. Get the parameters (non-option arguments) from the parser itself by querying it for `parameters`.

## An example

Let's go for an example that shows how to apply these four steps in practice. The example is rather lengthy, but it shows most of the possibilities of the library. The different steps in the usage strategy above have been marked by comments.

As an example we look again at the GNU ls and implement command line parsing for only the four options we already used above.

    feature -- Options and Flags

       almost_all_flag: AP_FLAG
       long_format_flag: AP_FLAG
       color_option: AP_ENUMERATION_OPTION
       ignore_option: AP_STRING_OPTION

    feature -- Main

       make
             -- Main routine, called when the program is executed.
          local
             parser: AP_PARSER
          do
                -- STEP 1: Creation and configuration of the parser

             create parser.make
             parser.set_application_description
                ("List information about the FILEs (the current directory by default).")
             parser.set_parameters_description ("[file] ...")

                -- STEP 2: Creation and configuration of the flags

             create almost_all_flag.make ('A', "almost-all")
             almost_all_flag.set_description ("do not list implied . and ..")
             parser.options.force_last (almost_all_flag)

             create long_format_flag.make_with_short_form ('l')
             long_format_flag.set_description ("use a long listing format")
             parser.options.force_last (long_format_flag)

             create color_option.make_with_long_form ("color")
             color_option.set_description ("control whether color is used to distinguish file types.")
             color_option.extend ("never")
             color_option.extend ("always")
             color_option.extend ("auto")
             parser.options.force_last (color_option)

             create ignore_option.make ('I', "ignore")
             ignore_option.set_description ("do not list implied entries matching shell PATTERN")
             ignore_option.set_parameter_description ("PATTERN")
             parser.options.force_last (ignore_option)

                -- STEP 3: Parse the arguments

             parser.parse_arguments

                -- STEP 4: Read results

             if almost_all_flag.was_found then
                print ("list almost all%N")
             end
             if long_format_flag.was_found then
                print ("use long format%N")
             end
             if color_option.was_found then
                print ("use coloring " + color_option.parameter + "%N")
             end

             if ignore_option.was_found then
                from
                   ignore_option.parameters.start
                until ignore_option.parameters.off loop
                   print ("ignore pattern: " +
                          ignore_option.parameters.item_for_iteration+"%N")
                   ignore_option.parameters.forth
                end
             end
             from
                parser.parameters.start
             until parser.parameters.off loop
                print ("parameter: " +
                       parser.parameters.item_for_iteration+"%N")
                parser.parameters.forth
             end
          end

If we now call the application with the arguments which are given in the example above, we get the following output:

    $ ./my_ls -Al /tmp -I '*~' -I*.bak --color=always
    list almost all
    use long format
    use coloring always
    ignore pattern: *~
    ignore pattern: *.bak
    parameter: /tmp

Also, we get a full help text for free (!). See what happens when we call the application with '-h'.

    $ ./my_ls -h
    usage: ls_example [-A] [-l] [--color=never|always|auto] [-I PATTERN] [file] ...
           ls_example --help

    List information about the FILEs (the current directory by default).

    Options:
    -A, --almost-all              do not list implied . and ..
        --color=never|always|auto control whether color is used to distinguish
                                  file types.
    -h, --help                    Display this help text.
    -I, --ignore=PATTERN          do not list implied entries matching shell
                                  PATTERN
    -l                            use a long listing format

A second example is provided in the `$GOBO/library/argument/example` directory.