molib documentation

Languages Available: français español

CLASS

moOption

NAME

Constructors - create an option object

VERSION

Version: 1.2.0

SYNOPSIS

moOption(const moWCString& name, bool isdefault = false,
unsigned long identifier = 0);

PARAMETERS

name - the name of this option
isdefault - whether this option is given a default value
identifier - the identifier of the option

DESCRIPTION

Options found on the command line are saved in an moOption object. This object has a name (the option name as described in the moGetOpt object), a value (the value found on the command line or the default value), a flag determining whether the default value is used or not and an identifier (MO_GETOPT_NO_IDENTIFIER by default).

All of these can be tested by the end programmers using the following read-only fields:

f_name f_identifier f_default

The value of the option is saved in a read-write set of values, a string and when necessary in a list defined as follow:

f_integer f_float f_result f_list -- option used several times

The result & value can be modified at any time so as to provide the necessary behavior. The f_integer is a 'long' value and the f_float is a 'double'. The f_result is the same value defined in a string. f_integer and f_float will usually be set to -1 or 0 when f_result doesn't represent a value. The f_list will be used when the option can be accepted more than once (see the '*'/multiple flags). The objects in the f_list are only moWCString objects.

Internally, the moOption() objects are sorted by name and identifiers.

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moGetOpt::moAccept

NAME

Compare - compare accepted options to sort them for fast access

VERSION

Version: 1.2.0

SYNOPSIS

virtual compare_t Compare(const moBase& object) const;
compare_t CompareID(const moAccept& object) const;

PARAMETERS

object - another moAccept object

DESCRIPTION

Determine whether an accepted option is larger, smaller or equal to another accepted option.

RETURN VALUE

These functions will return the comparison result as one of:

MO_BASE_COMPARE_EQUAL
MO_BASE_COMPARE_SMALLER
MO_BASE_COMPARE_GREATER

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moGetOpt::moAccept

NAME

HasIdentifier -- check whether the identifier was defined
HasReference -- check whether the reference was defined

VERSION

Version: 1.2.0

SYNOPSIS

bool HasIdentifier(void) const;
bool HasReference(void) const;

DESCRIPTION

This function returns true if the accept object has a non-zero identifier.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moGetOpt::moAccept

NAME

Name -- return the name of the of the moAccept object

VERSION

Version: 1.2.0

SYNOPSIS

const moWCString& Name(void) const;
const unsigned long Identifier(void) const;
const unsigned long Reference(void) const;
void Referenced(moAccept *accept);
moAccept *Referenced(void) const;

DESCRIPTION

These functions return the name, identifier and reference of the moAccept object respectively.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moGetOpt::moOption

NAME

Compare - compare options to sort them for fast access

VERSION

Version: 1.2.0

SYNOPSIS

virtual compare_t Compare(const moBase& object) const;
compare_t CompareID(const moOption& option) const;

PARAMETERS

object - an moOption object
option - an option object

DESCRIPTION

Determine whether an option is larger, smaller or equal to another option.

RETURN VALUE

These function return one of:

MO_BASE_COMPARE_EQUAL
MO_BASE_COMPARE_SMALLER
MO_BASE_COMPARE_GREATER

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moGetOpt::moAccept

NAME

Constructor - parse the accepted string

VERSION

Version: 1.2.0

SYNOPSIS

moAccept(const moWCString& what, bool optional);

PARAMETERS

what - the option to be parsed now
optional - force the optional flag to true if true

DESCRIPTION

This class is used internally to manage options.

Please, see the moGetOpt constructor for more information about the strings.

NOTES

When this object is created, the input strings have no semi-colons (;).

SEE ALSO

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moAccept

NAME

Matches - check to know whether an option entry matches

VERSION

Version: 1.2.0

SYNOPSIS

int Matches(const char *introducer, long length, const char *option) const;

PARAMETERS

option - the command line option to compare with

DESCRIPTION

This function will try to match the option to the moAccept object entry.

It first compares the option introducer to the moAccept introducers. If one matches, then the option name is checked. If both, the option and the moAccept have no introducer, the name is directly matched.

The function returns the number of characters which matched in the name. This shall be used to know which option matched better (more letters) as -r and -restore are distinct and the second one should be used over the first one if it matched.

Unless the stick bit is set, the returned length is the length of the option minus the introducer. This length is always equal to the length of the name moAccept object.

RETURN VALUE

returns the length of the argument name if it matches and
-1 if it doesn't match

SEE ALSO

Option

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moAccept

NAME

Option - create an option entry from the command line option

VERSION

Version: 1.2.0

SYNOPSIS

moOptionSPtr Option(moOption *option, int argc, const char *argv[],
long& idx, const char *left, long& max) const;

PARAMETERS

option - the current option to set
argc - the number arguments in argv
argv - the list of command line arguements
idx - the index within argv
left - what's left on the current command line option
max - set to -1 when the remainder of the argv is used by the option
or the error number when 0 is returned

DESCRIPTION

This function parses the parameters used for this arguement and generates a corresponding moObject.

RETURN VALUE

When the function is successful, then an option pointer is returned.
Otherwise, 0 is returned and the max parameter will be set to the
error number.

The idx parameter will be incremented as much as necessary whenever
additional entries can be used up to satisfy the option (for instance
an option of type INTEGER and MULTIPLE will get all the integers
following the option and increase idx accordingly).

The max parameter will be unchanged if the option was not followed by
anything. It is set to -1 if the current argv[idx] entry was fully
used. It is set to an error number if the function returns 0.

SEE ALSO

Matches

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moAccept

NAME

Default - create an option entry from the defaults

VERSION

Version: 1.2.0

SYNOPSIS

moOptionSPtr Default(void) const;

DESCRIPTION

This function creates an option object and initializes it with the default values as defined in the Accept() object.

RETURN VALUE

An option pointer is returned.

ERRORS

When the new option can't be allocated, a memory error is thrown.

SEE ALSO

Option

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moGetOpt

NAME

Constructor - create a parser of command line options

VERSION

Version: 1.2.0

SYNOPSIS

moGetOpt(const moWCString& accept);

PARAMETERS

accept - a string of accepted command line options

DESCRIPTION

Create an moGetOpt object used to parse command line options.

This will be created in a main() function or as a global object.

The accept string defines the list of options accepted by this object. The syntax is a set of names separated by semi-colons. The exact syntax is:

[ <id> ] [ '->' <id> [ ',' ... ] [ '[' ] [ <introducer> ] <name> [ '=' <value> ] [ <extra> ] [ ']' ] ';' ...

where only the name is required.

The optional <id> is a value used as an identifier to distinguish entries and quickly search for these entries. When no id is given, the default value MO_GETOPT_NO_IDENTIFIER is given. Users can only use values from MO_GETOPT_USER_IDENTIFIER (1000 up).

The identifier can be followed by references. This is used for equivalent options. That is, when an option such as -v as a long equivalent --verbose, only one should be set whichever one is used on the command line. This is done by referencing one in the other as in:

"11 -v; 12 -> 11 --verbose"

(note that the spaces are optional). An option can have one and only one reference.

When an option is written between square brackets, it is optional to the end user (i.e. one doesn't need to type it on the command line, non optional entries generate errors whenever a Main() command is called). If all the following commands are optional, one can use the special name asterisk as in "...; [*]; ..." (in this case, spaces are accepted before and after the square brackets, but not within.) The extra 'optional' keyword can also be used.

The introducer can be any number of + and - separated by / or |. To accept one or two dashes (- or --) then write the option as: "-/--name". If the option can receive a plus or a minus: "+/-opt". Note that if the +/- have an effect on the value (i.e. - turns on the option and + turns if off) then you may want to use two entries as in: "1111 -opt set to 1;1112->1111 +opt set to 0". The reference in the second option makes sure only the first one is set to 1 or 0. It is still necessary to use the identifier to search option 1111 to know which of -opt or +opt was used on the command line.

A default value can be given to any of the options.

The <extra> part includes information on the command line option. There needs to be a space between what comes before and an extra entry. These include the following:

++, inc, increment, incremental incremental flag

file, no flag accept entries without any option ("-f <file>" uses the option '-f' and "<file>" doesn't use any option); when such an option is used, the name of the option is only for the programmer to reference the option; it will not be used by the system

numeric accept a value as entry; if the entry is not a value, test with the following entries; like file otherwise

min <value> max <value> the minimum and maximum number of file entries for a given file; once a file entry has reached the maximum, the following one is used; at the end, the minimum is checked to make sure it was reached, if not an error is generated

on, 1, true, use, yes turn the flag on (true); this is the default when nothing else is specified

off, 0, false, don't use, no turn the flag off (false); usually used to remove a default or with a reference to an ON flag

equal <value> set to <value> like on and off except a specific value is given (i.e. "set to 1" is equivalent to "on" and "set to 0" is equivalent to "off"); the end user can't specify a value

[ '[' '=' ':' ']' ] [ '[' ] <what> [ 's' ] [ ']' ]

Integers: <what> = value, values, int, ints, integer, integers

Floating points: <what> = float, floats, double, doubles, real, reals

Strings: <what> = string, strings

expect one (singular) or several (plurial) integers, floats or strings to follow; when an equal sign is specified, the option is expected to use the equal sign; put the equal sign between square brackets if you want to enable both syntaxes; the colon (:) can be used to specify that the value(s) must be stuck to the option; use the colon between square brackets if you want to enable both syntaxes; when both the equal and colon are used between square brackets then all the possibilities are accepted; (note the equal and colon can be given in any order) the value(s) and string(s) can be defined between square brackets in which case these are mandatory and then the option can be used without them; the floats will possibly include a decimal point and an exponent as defined in C (see the strtod(3) function call); values can be signed; when several integers, floats or strings are defined as stuck or with a non-mandatory equal sign, these will be expected to be listed in a single argv entry and separated by commas (i.e. --file=a,b,c)

Examples:

Option definition Command line option

"--debug=0 integer" --debug 5

"--debug=0 =integer" --debug=5

"--debug=0 [=]integer" --debug 5 "--debug=0 [=]integer" --debug=5

"--debug=0 :integer" --debug5 "--debug=0 [:]integer" --debug5 "--debug=0 [:]integer" --debug 5

"--debug=0 [=:]integer" --debug5 "--debug=0 [=:]integer" --debug 5 "--debug=0 [=:]integer" --debug=5

"--debug=0 :[integer] set to 1" --debug "--debug=0 :[integer] set to 1" --debug5

In the last case, the --debug value is set to zero (=0) by default. If the --debug is used as is on the command line, then it is "set to 1". It can also be followed by a value as in --debug5 in which case it will be set to 5.

'*' repeat enables the option to be entered several times on the command line and each entry is kept in the f_list parameter of the option; the f_list only includes moWCString objects

optional make this entry optional (equivalent to square brackets around the option)

required makes this entry required (this can be used after a [*] was found to force some entries)

Internally, this object automatically defines the following:

"1 -h", "2->1 --help",

"11 -v ++", "12->11 --verbose ++",

"21 -V set to -1", "22->21 -V0 set to 0", "23->21 -V1 set to 1", "24->21 --version [=]integer set to -1",

"31 --copyright",

The Main() functions also understand these parameters automatically and therefore there is no need for the user to handle them at all. See Main() for explaination about these options.

The following functions will also be called whenever one of these options is used:

OnHelp() the -h or --help was used

OnVersion() the -V, -V0, -V1 or --version was used;

OnCopyright() the --copyright has been used

OnError() an error occured

EXAMPLES

1. Options and defaults

In the following accepts -o or --output and the -c flag. Only
the options 1001 and 1003 will be defined:

"[*]; 1001 -o=a.out; 1002->1001 --output=a.out; 1003 -c;"

Use the Option() instruction with 1001 and 1003 to get
the result. The -o and --output get a.out as the default
name.

2. Filenames

If you need a list of filenames as input and the -q flag,
one can use this:

"2000 -f=. file repeat; 1001 -q=1; 1002->1002 -k=0"

Here the option 2000 will have it's f_list defined with a
list of moWCString's objects. One string per filename found
on the command line. Note that the -f flag itself is ignored.
By default, the -q flag will be set to 1 and -k is ignored.
If the user specifies -k, then the value of option 1002 will
be 0.

WARNING: the repeat flag means that you will get options
starting at the specified index (2000 in this example);
because you can't tell how many entries you will get, you
should use an index larger than any other flag. Also, to
retrieve the values, you will need to call the Option()
with, in this example, 2000, 2001, 2002, etc. until you get
a NULL pointer (if the parameter is optional, then the
very first entry can already be a NULL pointer).

3. Values (integers or strings)

The following offers the user to specify a value following
an option:

"1001 --max=0 [:=]integer"

In this case, the max option is set to 0 by default. The
end user can set it to any integer using one of:

--max3 or --max=3 or --max 3

The ':' in means that the value can be stuck with the option.
The '=' means you need to use an equal sign, but the '[' and
']' means it is optional. When the ':' is marked optional,
the integer can be written seperated. If no ':' and no '='
were specified ("1001 --max=0 integer"), then only a spaced
value can be specified.

"1001 --max=0 integer" allows for --max 3 only
"1001 --max=0 =integer" allows for --max=3 only
"1001 --max=0 :integer" allows for --max3 only

See the --debug for more examples on these options.

ERRORS

When an invalid parameter definition is found in the string, an invalid error is thrown as long(MO_ERROR_INVALID). A message is also printed. These errors will only occur if the input string(s) are invalid. Programmers will always detect these unless they don't even try to start their program.

SEE ALSO

Main, Option, operator [], OnError, OnVersion, OnCopyright, OnHelp

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moGetOpt

NAME

Option - get/set options
operator [] - get options with their identifier

VERSION

Version: 1.2.0

SYNOPSIS

moOptionSPtr Option(const moWCString& name) const;
moOptionSPtr Option(int identifier) const;

moOptionSPtr operator [] (const moWCString& name) const;
moOptionSPtr operator [] (int identifier) const;

void AddOption(const moOption& option);

PARAMETERS

name - name of the option to search
identifier - identifier of the option to search
option - the option to insert

DESCRIPTION

These functions are used to insert new options in a GetOpt() object and retrieve existing options.

Options can be search with their name. If more than one entry uses the same name, however, it will be necessary to give them different identifier numbers and search them using that identifier. (See the Constructor for more information about how to define identifiers).

Options can be search using their identifiers. In this case, the array ([]) operator can be used. The identifiers are these specified before the option in the list of options string.

Usually, options are set to the defaults specified in the string given to the GetOpt() constructor. If some of the options depend on dynamic defaults (say &x24;HOME/.vimrc) then these can be set before one of the Main() function is called. Others can be set after knowing that it may mean they will override the options entered by the end user.

EXAMPLES

moGetOpt command_line("-/--rcfile='.vimrc'");
moWCString home(getenv("HOME"));
moFilename name = home + ".vimrc";
moOption rcfile("rcfile", name, true);
command_line.Option(rcfile);
moOption *filename = command_line.Option("rcfile");

// here one can use filename->f_value as the rcfile name

NOTES

It is possible to use the "set option" function member to add options not available on the command line (which could be available through other means like a configuration file, environment variables, etc.). If you use an identifier then create an moOptionIdentifier instead of an moOption otherwise it won't be found properly.

SEE ALSO

Main

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moGetOpt

NAME

Main - parses command line (like) arguments

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Main(int argc, const char *argv[]);

PARAMETERS

argc - number of arguments in argv
argv - array of arguments

DESCRIPTION

This function will match the given command line arguments to the one defined in the moGetOpt() object.

It will create options one can retrieve with the Option() function members and the array operator ([]) of the moGetOpt object.

The previous set of options will be lost.

Note that an moApp class could also be created as a derived version of moGetOpt() which gives you a chance to (1) overload the Main() function and the different events (errors, help, version and copyrights).

EXAMPLES

int main(int argc, char *argv[])
{
moGetOpt getopt("[-c]; [-d]; <filename>");

command_line.Main(argc, argv);

moGetOpt::moOption *opt = command_line.Option("c");
if(opt != 0) {
// the -c option was given on the command line!
}

...
}

SEE ALSO

Option, operator []

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moGetOpt

NAME

SetVersion - defines the software version
SetProgname - defines the program name
SetCopyright - defines the copyright (one line)

VERSION

Version: 1.2.0

SYNOPSIS

void SetVersion(const moWCString& version);
void SetProgname(const moWCString& progname);
void SetCopyright(const moWCString& copyright);

PARAMETERS

version - the software version (i.e. 1.0)
progname - the software name (i.e. argv[0])
copyright - the software copyright (one line)

DESCRIPTION

These functions are expected to be called to setup the moGetOpt object before calling the Main() function. These setup the options as expected by the different error and similar functions.

The SetProgname() call is optional since the argv[0] parameter can be used in the Main() function to define the name of the program.

The SetVersion() and SetCopyright() can be skipped if you overwrite the OnVersion() and OnCopyright() functions. In that case, your functions can display whatever you want.

NOTES

If you use the moApplication class, call that class SetVersion() and SetCopyright() functions and then the

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moGetOpt

NAME

Messages: OnError, OnHelp, OnVersion, OnCopyright
- called whenever the corresponding option is selected

VERSION

Version: 1.2.0

SYNOPSIS

virtual bool OnError(const moWCString& argv, const moWCString& message);
virtual void OnHelp(void);
virtual void OnVersion(long count);
virtual void OnCopyright(void);

PARAMETERS

argv - the argument which generates the given error
message - the error message
count - the number following the -V option

DESCRIPTION

The OnError() virtual function member will be called whenever an unrecognized command line option was used. This function should print out a message in some way and return. It is possible to exit(3) as well in which case other options won't generate errors. Though the error counter will already be increased, it is also possible to interpret the argv argument in a way not available in the moGetOpt object. In this case, the function must return 'true'. In all other cases it needs to return 'false'.

It can be useful to catch errors for options which accept values but need to also accept one or two special keywords as in the following:

"-d=0 [=]integer set to 1"

If you want this option to also accept -d=off to set it to the default then the OnError() will have to test whether the following option is OFF. If so, it should set the option to zero and make sure the OnError() function returns 'true'.

The OnHelp() virtual function prints out the command line options as defined in the moGetOpt() string argument. It also prints the version (as it is printed by default with the -V option). If extraneous help information is available, once can overwrite this function which should still be called to print out the options defined in moGetOpt() - unless some or many of the options printed that way should remain invisible to the end users.

The OnVersion() virtual function prints out the name of the program and its version. The count parameter will be used to know which of -V, -V1 or -V0 was used (or the corresponding --version). The -V should print a human readable version. The -V1 should print out the name of the program and the version preceeded by the letter 'V'. The -V2 should only print out the version number (no program name and no extraneous letter).

The version must be set with SetVersion() or the OnVersion() function overwritten.

The OnCopyright() virtual function prints out a copyright for the given program. The default function prints out the string set with SetCopyright(). If a more complete copyright is required, overwrite this function.

RETURN VALUE

Only OnError() returns a value. It needs to return 'false'
when the argv argument couldn't be used and a real error
occured (the default). It will return 'true' if the argv
argument was used in some special manner by the system.

Note: the default OnError() function always returns 'false'.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox