Home Page ] [ Eiffel Archive ] [ Eiffel Classes and Clusters ]

Arc de Triomphe clipart (2486 bytes)

Command-line Arguments Processing


Written by Neil Wilson

argu-1_3.tar.zip (22,604 bytes) - Eiffel/S version
argu-1_3i.tar.zip (22,364 bytes) - ISE Eiffel version adapted by Jan Sandquist


Licence

GNU Library GPL - see file README.LIB

Requirements

Either:

Or:

Abstract

This cluster allows you to process your command line arguments (or any other set of strings for that matter) and match them against a prepared list of options.

Usage

The system is quite flexible and will allow you to specify the identification marker ('-', '+', '/', etc) and whether you want character or word options. As usual with Eiffel you can easily derive your own if the provided facilities are not sufficient.

The primary class of this cluster is the PREPARED_ENVIRONMENT which, after creation, provides two lists: 'options' and 'arguments'. Since the class inherits from ENVIRONMENT, you should be able to plug it into your current applications with little difficulty.

To use: select the Option Matchers and create them, using an Option Identifier if required. Prime the Matchers with option strings using the 'add' facilities - the option marker should not be included. Note that CHARACTER_MATCHERs will register each character in the option string as an individual option.

Create an option processor using the primed matcher(s). This option processor can then be used to create the prepared environment. The included class TEST_ENV gives an example of how to use a multiple option matcher.

Identification Lattice

       OPTION_IDENTIFIER*
               ^
               |
    FRONT_OPTION_IDENTIFIER* <-- DOS_IDENTIFIER
       ^               ^
       |               |
GNU_IDENTIFIER UNIX_IDENTIFIER

This lattice identifies strings as options. The provided classes identify options by checking the beginning of the string for the option marker. There is nothing to stop new classes being derived which identify anywhere else in the string.

Matcher Lattice

  OPTION_MATCHER*
        ^
        |
ALTERABLE_MATCHER* <------------ CHARACTER_MATCHER*
        ^                ^               ^
        |                |               |
PARTIAL_MATCHER*  FULL_MATCHER* <-- UNIX_MATCHER --> UNIX_IDENTIFIER
        ^                |
        |                |
   GNU_MATCHER     VARIABLE_MATCHER
        |
        v
  GNU_IDENTIFIER

This lattice maintains the list of options. An option may be a simple switch, have an optional parameter or require a parameter.

OPTION_MATCHER
provides the facilities to match strings against these lists.
ALTERABLE_MATCHERs
allow you to add into the matcher's list of options.
CHARACTER_MATCHERs
register each character in their 'add' strings as a separate option.
PARTIAL_MATCHER
can deal with strings that match only the beginning of a valid option.
FULL_MATCHER
will only accept strings that match a valid option in its entirety.

Processor Lattice

      OPTION_ATTRIBUTES*
              ^
              |
      OPTION_PROCESSOR*
        ^           ^
        |           |
SINGLE_OPTION   MULTIPLE_OPTION

The option processor processes a series of strings and separates them into two lists: 'options' and 'arguments'. SINGLE_OPTION is a processor implementation that uses only a single OPTION_MATCHER during its processing. MULTIPLE_OPTION uses a COLLECTION of OPTION_MATCHERs. These matchers are applied in the iteration order of the particular collection you choose to use (usually the order in which the matchers were inserted)

An option processor will only check strings passed to 'process' after 'start' has been called and before 'stop'. Outside these times the 'process'ed string is simply placed on the argument list. The processor will 'stop' matching options automatically if it is passed a string which exactly matches the End Marker of one of the Option Identifiers you are using.

'reset' puts the processor back into its initial state. Essentially it is the same as 'make' but keeps the current MATCHER configuration.

Restrictions

The matched options list is currently an associative array (DICTIONARY). This prevents multiple occurrences of the same option from being stored in the list. The last one found takes precedence.

The order in which the options were found is not maintained.

With a MULTIPLE_OPTION processor errors will occur if an option matcher's identifier is a substring of a subsequent option matcher's identifier (e.g. '-' is a substring of '--'). To prevent this, ensure that the matcher's with the longest identifiers come first in the matcher list.

The processor system is currently passive providing only a couple of simple string lists as its output. It would be nice if you could register features to be called when an option is located. I haven't thought of a good way of doing this yet :-)

Technical Notes

The processor is a simple finite state machine using four states. The transitions are restricted and the whole machine kept in check using Eiffel's delightful assertion mechanism.

The indexing clauses of the classes follow a set scheme. The 'type' label is assigned as follows:

Comments and suggestions for improvements always welcomed, particularly about the indexing scheme.

Neil Wilson (neil@aldur.demon.co.uk)
6 Spring View
Towngate
Ossett
West Yorkshire
WF5 0QB
UK

Home Page ] [ Eiffel Archive ] [ Eiffel Classes and Clusters ]