mirror of
https://github.com/cuberite/TCLAP.git
synced 2025-08-04 18:27:19 -04:00
798 lines
30 KiB
XML
798 lines
30 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<!--
|
|
"/usr/share/sgml/docbook/xml-dtd-4.2/docbookx.dtd">
|
|
-->
|
|
|
|
<!--
|
|
-
|
|
- file: manual.html
|
|
-
|
|
- Copyright (c) 2003, 2004 Michael E. Smoot .
|
|
- All rights reverved.
|
|
-
|
|
- See the file COPYING in the top directory of this distribution for
|
|
- more information.
|
|
-
|
|
- THE SOFTWARE IS PROVIDED _AS IS_, WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
|
- THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
- FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
|
- DEALINGS IN THE SOFTWARE.
|
|
-
|
|
-->
|
|
<book>
|
|
<bookinfo>
|
|
<title>Templatized C++ Command Line Parser Manual</title>
|
|
<author>
|
|
<firstname>Michael</firstname>
|
|
<surname>Smoot</surname>
|
|
<othername role='mi'>E</othername>
|
|
</author>
|
|
<copyright>
|
|
<year>2003,2004</year>
|
|
<holder>Michael E. Smoot</holder>
|
|
</copyright>
|
|
</bookinfo>
|
|
|
|
<chapter>
|
|
<title>Basic Usage</title>
|
|
<para>
|
|
<emphasis>TCLAP</emphasis> has a few key classes to be aware of. The first is the
|
|
<classname>CmdLine</classname> (command line) class. This class parses
|
|
the command line passed to it according to the arguments that it
|
|
contains. Arguments are separate objects that are added to the
|
|
<classname>CmdLine</classname> object one at a time. The five
|
|
argument classes are: <classname>ValueArg</classname>, <classname>UnlabeledValueArg</classname>,
|
|
<classname>SwitchArg</classname>, <classname>MultiArg</classname> and <classname>UnlabeledMultiArg</classname>.
|
|
These classes are templatized, which means they can be defined to parse
|
|
a value of any <link linkend="FOOTNOTES"> type**</link>. Once you add the
|
|
arguments to the <classname>CmdLine</classname> object, it parses the command line
|
|
and assigns the data it finds to the specific argument objects it
|
|
contains. Your program accesses the values parsed by
|
|
calls to the <methodname>getValue()</methodname> methods of the argument objects.
|
|
</para>
|
|
|
|
<para>
|
|
Here is a simple <ulink url="test1.cpp"> example</ulink> ...
|
|
</para>
|
|
|
|
<programlisting>
|
|
#include <string>
|
|
#include <iostream>
|
|
#include <algorithm>
|
|
#include <tclap/CmdLine.h>
|
|
|
|
using namespace TCLAP;
|
|
using namespace std;
|
|
|
|
int main(int argc, char** argv)
|
|
{
|
|
// Wrap everything in a try block. Do this every time,
|
|
// because exceptions will be thrown for problems.
|
|
try {
|
|
|
|
// Define the command line object.
|
|
CmdLine cmd("Command description message", ' ', "0.9");
|
|
|
|
// Define a value argument and add it to the command line.
|
|
ValueArg<string> nameArg("n","name","Name to print",true,"homer","string");
|
|
cmd.add( nameArg );
|
|
|
|
// Define a switch and add it to the command line.
|
|
SwitchArg reverseSwitch("r","reverse","Print name backwards", false);
|
|
cmd.add( reverseSwitch );
|
|
|
|
// Parse the args.
|
|
cmd.parse( argc, argv );
|
|
|
|
// Get the value parsed by each arg.
|
|
string name = nameArg.getValue();
|
|
bool reverseName = reverseSwitch.getValue();
|
|
|
|
// Do what you intend too...
|
|
if ( reverseName )
|
|
{
|
|
reverse(name.begin(),name.end());
|
|
cout << "My name (spelled backwards) is: " << name << endl;
|
|
}
|
|
else
|
|
cout << "My name is: " << name << endl;
|
|
|
|
|
|
} catch (ArgException &e) // catch any exceptions
|
|
{ cerr << "error: " << e.error() << " for arg " << e.argId() << endl; }
|
|
}
|
|
</programlisting>
|
|
|
|
<para>
|
|
The output should look like:
|
|
</para>
|
|
|
|
<para>
|
|
<programlisting>
|
|
|
|
% test1 -n mike
|
|
My name is: mike
|
|
|
|
% test1 -n mike -r
|
|
My name (spelled backwards) is: ekim
|
|
|
|
% test1 -r -n mike
|
|
My name (spelled backwards) is: ekim
|
|
|
|
% test1 -r
|
|
PARSE ERROR:
|
|
One or more required arguments missing!
|
|
|
|
Brief USAGE:
|
|
test1 [-r] -n <string> [--] [-v] [-h]
|
|
|
|
For complete USAGE and HELP type:
|
|
test1 --help
|
|
|
|
|
|
% test1 --help
|
|
|
|
USAGE:
|
|
|
|
test1 [-r] -n <string> [--] [-v] [-h]
|
|
|
|
|
|
Where:
|
|
|
|
-r, --reverse
|
|
Print name backwards
|
|
|
|
-n <string> --name <string>
|
|
(required) (value required) Name to print
|
|
|
|
--, --ignore_rest
|
|
Ignores the rest of the labeled arguments following this flag.
|
|
|
|
-v, --version
|
|
Displays version information and exits.
|
|
|
|
-h, --help
|
|
Displays usage information and exits.
|
|
|
|
|
|
Command description message
|
|
|
|
</programlisting>
|
|
</para>
|
|
|
|
|
|
<para>
|
|
This example shows a number of different properties of the
|
|
library...
|
|
<itemizedlist>
|
|
<listitem>Arguments can appear in any order (...mostly, <link linkend="COMPLICATIONS"> more</link> on this later).</listitem>
|
|
|
|
<listitem>The <parameter>help</parameter>, <parameter>version</parameter> and <parameter>--</parameter> <classname>SwitchArg</classname>s
|
|
are specified automatically. Using either the <parameter>-h</parameter> or
|
|
<parameter>--help</parameter> flag will cause the USAGE message to be displayed,
|
|
<parameter>-v</parameter> or <parameter>--version</parameter> will cause any version information to
|
|
be displayed, and <parameter>--</parameter> or <parameter>--ignore_rest</parameter> will cause the
|
|
remaining labeled arguments to be ingored. These switches are
|
|
included automatically on every command line and there is no way to
|
|
turn this off (unless you change <filename>CmdLine.h</filename> yourself). More
|
|
<link linkend="VISITORS"> later</link> on how we get this to
|
|
work.</listitem>
|
|
|
|
<listitem>If there is an error parsing the command line (e.g. a required
|
|
argument isn't provided), the program exits and displays a brief
|
|
USAGE and an error message.</listitem>
|
|
|
|
<listitem>The program name is assumed to always be argv[0], so it isn't
|
|
specified directly.</listitem>
|
|
|
|
<listitem>A delimiter character can be specified. This means that if you
|
|
prefer arguments of the style "-s=asdf" instead of "-s asdf", you
|
|
can do so.</listitem>
|
|
|
|
<listitem><emphasis>Always wrap everything in a try block that catches
|
|
ArgExceptions!</emphasis> Any problems found in constructing the
|
|
<classname>CmdLine</classname> or the <classname>Arg</classname>s will throw an
|
|
<classname>ArgException</classname>.</listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<sect1 id="ARG_PROPERTIES">
|
|
<title>Argument Properties</title>
|
|
Arguments, whatever their type, have a few common basic properties.
|
|
These properties are set in the constructors of the arguments.
|
|
<itemizedlist>
|
|
<listitem>First is the flag or the character preceeded by a dash(-) that
|
|
signals the beginning of the argument on the command line.</listitem>
|
|
<listitem>Arguments also have names, which can, if desired also be used
|
|
as a flag on the command line, this time preceeded by two dashes
|
|
(--) [like the familiar getopt_long()].</listitem>
|
|
<listitem>Next is the description of the argument. This is a short
|
|
description of the argument displayed in the help/usage message
|
|
when needed.</listitem>
|
|
<listitem>The boolean value in <classname>ValueArg</classname>s indicates whether the
|
|
argument is required to be present (<classname>SwitchArg</classname>s can't be
|
|
required, as that would defeat the purpose).</listitem>
|
|
<listitem>Next, the default value the arg should assume if the arg isn't
|
|
required or entered on the command line.</listitem>
|
|
<listitem>Last, for <classname>ValueArg</classname>s is a short description of the type
|
|
that the argument expects (yes its an ugly Note that the order of
|
|
arguments on the command line (so far) doesn't matter. Any argument
|
|
not matching an <classname>Arg</classname> added to the command line will cause an
|
|
exception to be thrown (<link linkend="COMPLICATIONS"> for the
|
|
most part</link>, with some <link linkend="EXCEPTIONS"> exceptions</link>). <link linkend="DESCRIPTION_EXCEPTIONS"> hack</link>).</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="ARGUMENT_TYPES">
|
|
<title>Types of Arguments</title>
|
|
There are two primary types of arguments:
|
|
<itemizedlist>
|
|
<listitem><classname>SwitchArg</classname>s are what the name implies: simple, on/off,
|
|
boolean switches. Use <classname>SwitchArg</classname>s anytime you want to turn
|
|
some sort of system property on or off. <classname>SwitchArg</classname>s don't
|
|
parse a value. They return <constant>true</constant> or <constant>false</constant>, depending
|
|
on whether the switch has been found on the command line and what
|
|
the default value was defined as.</listitem>
|
|
|
|
<listitem><classname>ValueArg</classname>s are arguments that read a value of some type
|
|
from the command line. Any time you need a file name, a number,
|
|
etc. use a <classname>ValueArg</classname> or one of its variants. <link linkend="UNLABELED_VALUE_ARG"> UnlabedValueArg</link>, <link linkend="MULTI_ARG"> MultiArg</link>, and <link linkend="UNLABELED_MULTI_ARG"> UnlabeledMultiArg</link> are
|
|
special cases of <classname>ValueArg</classname>s and are described below. All
|
|
<classname>ValueArg</classname>s are <link linkend="FOOTNOTES"> templatized**</link> and will attempt to parse
|
|
the string its flag matches on the command line as the type it is
|
|
specified as. <classname>ValueArg<int></classname> will attempt to parse an
|
|
int, <classname>ValueArg<float></classname> will attempt to parse a float,
|
|
etc. If <methodname>operator>></methodname> for the specified type doesn't
|
|
recognize the string on the command line as its defined type, then
|
|
an exception will be thrown.</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="COMPILING">
|
|
<title>Compiling</title>
|
|
<para>
|
|
<emphasis>TCLAP</emphasis> is implemented entirely in header files which means you only
|
|
need to include CmdLine.h to use the library.
|
|
</para>
|
|
<programlisting>
|
|
#include <tclap/CmdLine.h>
|
|
</programlisting>
|
|
<para>
|
|
You'll need to make sure that your compiler can see the header
|
|
files. If you do the usual "make install" then your compiler should
|
|
see the files by default. Alternatively, you can use the -I
|
|
complier argument to specify the exact location of the libraries.
|
|
</para>
|
|
<programlisting>
|
|
c++ -o my_program -I /some/place/tclap-1.X/include my_program.cpp
|
|
</programlisting>
|
|
<para>
|
|
Where /some/place/tclap-1.X is the place you have unpacked the
|
|
distribution.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, if you want to include <emphasis>TCLAP</emphasis> as part of your software
|
|
(which is perfectly OK, even encouraged) then simply copy the
|
|
contents of /some/place/tclap-1.X/include (the tclap directory and
|
|
all of the header files it contains) into your include
|
|
directory.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>TCLAP</emphasis> was developed on Linux and MacOSX systems. It is also known
|
|
to work on Windows, Sun and Alpha platforms. We've made every
|
|
effort to keep the library compliant with the ANSI C++ standard so
|
|
if your compiler meets the standard, then this library should work
|
|
for you. Please let us know if this is not the case!
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="COMPLICATIONS">
|
|
<title>Complications</title>
|
|
<para>
|
|
Naturally, what we have seen to this point doesn't satisfy all of
|
|
our needs.
|
|
</para>
|
|
|
|
<sect1 id="COMBINE_SWITCHES">
|
|
<title>I want to combine multiple switches into one argument...</title>
|
|
<para>
|
|
Multiple <classname>SwitchArg</classname>s can be combined into a single argument
|
|
on the command line. If you have switches -a, -b and -c it is valid
|
|
to do either:
|
|
</para>
|
|
<programlisting>
|
|
% command -a -b -c
|
|
</programlisting>
|
|
|
|
<para>
|
|
<emphasis>or</emphasis>
|
|
</para>
|
|
|
|
<programlisting>
|
|
% command -abc
|
|
</programlisting>
|
|
|
|
<para>
|
|
<emphasis>or</emphasis>
|
|
</para>
|
|
|
|
<programlisting>
|
|
% command -ba -c
|
|
</programlisting>
|
|
<para>
|
|
This is to make this library more in line with the POSIX and GNU
|
|
standards (as I understand them).
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="MULTI_ARG">
|
|
<title>I tried passing multiple values on the command line with the
|
|
same flag and it didn't work...</title>
|
|
<para>
|
|
Correct. You can neither specify mulitple <classname>ValueArg</classname>s or
|
|
<classname>SwitchArg</classname>s with the same flag in the code nor on the command
|
|
line. Exceptions will occur in either case. For <classname>SwitchArg</classname>s
|
|
it simply doesn't make sense to allow a particular flag to be
|
|
turned on or off repeatedly on the command line. All you should
|
|
ever need is to set your state <emphasis>once</emphasis> by specifying the flag
|
|
or not (<link linkend="EXCEPTIONS"> yeah but...</link>).
|
|
</para>
|
|
|
|
<para>
|
|
However, there <emphasis>are</emphasis> situations where you might want multiple
|
|
values for the same flag to be specified. Imagine a compiler that
|
|
allows you to specify multiple directories to search for
|
|
libraries...
|
|
</para>
|
|
|
|
<programlisting>
|
|
% fooCompiler -L /dir/num1 -L /dir/num2 file.foo
|
|
</programlisting>
|
|
|
|
<para>
|
|
In situations like this, you will want to use a <classname>MultiArg</classname>. A
|
|
<classname>MultiArg</classname> is essentially a <classname>ValueArg</classname> that appends any
|
|
value that it matches and parses onto a vector of values. When the
|
|
<methodname>getValue()</methodname> method is called, a vector of values, instead of
|
|
a single value is returned. A <classname>MultiArg</classname> is declared much like
|
|
a <classname>ValueArg</classname>:
|
|
</para>
|
|
|
|
<programlisting>
|
|
|
|
MultiArg<int> itest("i", "intTest", "multi int test", false,"int" );
|
|
cmd.add( itest );
|
|
|
|
</programlisting>
|
|
<para>
|
|
Note that <classname>MultiArg</classname>s can be added to the <classname>CmdLine</classname> in
|
|
any order (unlike <link linkend="UNLABELED_MULTI_ARG"> UnlabeledMultiArg</link>).
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="UNLABELED_VALUE_ARG">
|
|
<title>I don't like labelling all of my arguments...</title>
|
|
<para>
|
|
To this point all of our arguments have had labels (flags)
|
|
indentifying them on the command line, but there are some
|
|
situations where flags are burdensome and not worth the effort. One
|
|
example might be if you want to implement a magical command we'll
|
|
call <command>copy</command>. All <command>copy</command> does is copy the file specified
|
|
in the first argument to the file specified in the second argument.
|
|
We can do this using <classname>UnlabeledValueArg</classname>s which are pretty
|
|
much just <classname>ValueArg</classname>s without the flag specified, which tells
|
|
the <classname>CmdLine</classname> object to treat them accordingly. The code would
|
|
look like this:
|
|
</para>
|
|
|
|
<programlisting>
|
|
|
|
UnlabeledValueArg<float> nolabel( "name", "unlabeled test", 3.14,
|
|
"nameString" );
|
|
cmd.add( nolabel );
|
|
|
|
</programlisting>
|
|
<para>
|
|
Everything else is handled identically to what is seen above. The
|
|
only difference to be aware of, and this is important: <emphasis>the order
|
|
that UnlabeledValueArgs are added to the <classname>CmdLine</classname> is the
|
|
order that they will be parsed!!!!</emphasis> This is <emphasis>not</emphasis> the case
|
|
for normal <classname>SwitchArg</classname>s and <classname>ValueArg</classname>s. What happens
|
|
internally is the first argument that the <classname>CmdLine</classname> doesn't
|
|
recognize is assumed to be the first <classname>UnlabeledValueArg</classname> and
|
|
parses it as such. Note that you are allowed to intersperse labeled
|
|
args (SwitchArgs and ValueArgs) in between
|
|
<classname>UnlabeledValueArgs</classname> (either on the command line or in the
|
|
declaration), but the <classname>UnlabeledValueArgs</classname> will still be
|
|
parsed in the order they are added. Just remember that order is
|
|
important for unlabeled arguments.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="UNLABELED_MULTI_ARG">
|
|
<title>I want an arbitrary number of unlabeled arguments to be accepted...</title>
|
|
|
|
<para>
|
|
Don't worry, we've got you covered. Say you want a strange command
|
|
that searches each file specified for a given string (let's call it
|
|
<command>grep</command>), but you don't want to have to type in all of the file
|
|
names or write a script to do it for you. Say,
|
|
</para>
|
|
|
|
<para>
|
|
<programlisting>
|
|
% grep pattern *.txt
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
First remember that the <emphasis>*</emphasis> is handled by the shell and
|
|
expanded accordingly, so what the program <command>grep</command> sees is
|
|
really something like:
|
|
<programlisting>
|
|
% grep pattern file1.txt file2.txt fileZ.txt
|
|
</programlisting>
|
|
To handle situations where multiple, unlabled arguments are needed,
|
|
we provide the <classname>UnlabeledMultiArg</classname>. <classname>UnlabeledMultiArg</classname>s
|
|
are declared much like everything else, but with only a description
|
|
of the arguments. By default, if an <classname>UnlabeledMultiArg</classname> is
|
|
specified, then at least one is required to be present or an
|
|
exception will be thrown. The most important thing to remember is,
|
|
that like <classname>UnlabeledValueArg</classname>s: order matters! In fact, <emphasis>an UnlabeledMultiArg must be the last argument added to the
|
|
CmdLine!</emphasis>. Here is what a declaration looks like:
|
|
</para>
|
|
|
|
<para>
|
|
<programlisting>
|
|
|
|
//
|
|
// UnlabeledMultiArg must be the LAST argument added!
|
|
//
|
|
UnlabeledMultiArg<string> multi("file names");
|
|
cmd.add( multi );
|
|
cmd.parse(argc, argv);
|
|
|
|
vector<string> fileNames = multi.getValue();
|
|
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
You must only ever specify one (1) <classname>UnlabeledMultiArg</classname>. One
|
|
<classname>UnlabeledMultiArg</classname> will read every unlabeled Arg that wasn't
|
|
already processed by a <classname>UnlabeledValueArg</classname> into a
|
|
<classname>vector</classname> of type T. Any <classname>UnlabeledValueArg</classname> or other
|
|
<classname>UnlabeledMultiArg</classname> specified after the first
|
|
<classname>UnlabeledMultiArg</classname> will be ignored, and if they are required,
|
|
exceptions will be thrown. When you call the <methodname>getValue()</methodname>
|
|
method of the <classname>UnlabeledValueArg</classname> argument, a <classname>vector</classname>
|
|
will be returned. If you can imagine a situation where there will
|
|
be multiple args of multiple types (stings, ints, floats, etc.)
|
|
then just declare the <classname>UnlabeledMultiArg</classname> as type
|
|
<classname>string</classname> and parse the different values yourself or use
|
|
several <classname>UnlabeledValueArg</classname>s.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="XOR">
|
|
<title>I want one argument or the other, but not both...</title>
|
|
<para>
|
|
Suppose you have a command that must read input from one of two
|
|
possible locations, either a local file or a URL. The command
|
|
<emphasis>must</emphasis> read something, so <emphasis>one</emphasis> argument is required, but
|
|
not both, yet neither argument is strictly necessary by itself.
|
|
This is called "exclusive or" or "XOR". To accomodate this
|
|
situation, there is now an option to add two or more <classname>Arg</classname>s to
|
|
a <classname>CmdLine</classname> that are exclusively or'd with one another:
|
|
xorAdd(). This means that exactly one of the <classname>Arg</classname>s must be
|
|
set and no more.
|
|
</para>
|
|
|
|
<para>
|
|
xorAdd() comes in two flavors, either xorAdd(Arg& a, Arg&
|
|
b) to add just two <classname>Arg</classname>s to be xor'd and xorAdd( vector<Arg*>
|
|
xorList ) to add more than two <classname>Arg</classname>s.
|
|
</para>
|
|
<programlisting>
|
|
|
|
|
|
ValueArg<string> fileArg("f","file","File name to read",true,"homer",
|
|
"filename");
|
|
ValueArg<string> urlArg("u","url","URL to load",true,
|
|
"http://example.com", "URL");
|
|
|
|
cmd.xorAdd( fileArg, urlArg );
|
|
cmd.parse(argc, argv);
|
|
|
|
</programlisting>
|
|
<para>
|
|
Once one <classname>Arg</classname> in the xor list is matched on the
|
|
<classname>CmdLine</classname> then the others in the xor list will be marked as
|
|
set. The question then, is how to determine which of the
|
|
<classname>Arg</classname>s has been set? This is accomplished by calling the
|
|
isSet() method for each <classname>Arg</classname>. If the <classname>Arg</classname> has been
|
|
matched on the command line, the isSet() will return <constant>TRUE</constant>,
|
|
whereas if the <classname>Arg</classname> has been set as a result of matching the
|
|
other <classname>Arg</classname> that was xor'd isSet() will return <constant>FALSE</constant>.
|
|
(Of course, if the <classname>Arg</classname> was not xor'd and wasn't matched, it
|
|
will also return <constant>FALSE</constant>.)
|
|
</para>
|
|
|
|
<para>
|
|
<programlisting>
|
|
|
|
|
|
if ( fileArg.isSet() )
|
|
readFile( fileArg.getValue() );
|
|
else if ( urlArg.isSet() )
|
|
readURL( urlArg.getValue() );
|
|
else
|
|
// Should never get here because TCLAP will note that one of the
|
|
// required args above has not been set.
|
|
throw("Very bad things...");
|
|
|
|
|
|
</programlisting>
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="NO_FLAG">
|
|
<title>I have more arguments than single flags make sense for...</title>
|
|
<para>
|
|
Some commands have so many options that single flags no longer map
|
|
sensibly to the available options. In this case, it is desirable to
|
|
specify <classname>Arg</classname>s using only long options. This one is easy to
|
|
accomplish, just make the flag value blank in the <classname>Arg</classname>
|
|
constructor. This will tell the <classname>Arg</classname> that only the long
|
|
option should be matched and will force users to specify the long
|
|
option on the command line. The help output is updated accordingly.
|
|
</para>
|
|
<para>
|
|
<programlisting>
|
|
|
|
|
|
ValueArg<string> fileArg("","file","File name",true,"homer","filename");
|
|
|
|
SwitchArg caseSwitch("","upperCase","Print in upper case",false);
|
|
|
|
|
|
</programlisting>
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="ALLOWED_LIST">
|
|
<title>I want to constrain the values allowed for a particular argument...</title>
|
|
<para>
|
|
There are now constructors for all of the <classname>Arg</classname>s that parse
|
|
values that allow a list of values to be specified for that
|
|
particular <classname>Arg</classname>. When the value for the <classname>Arg</classname> is parsed,
|
|
it is checked against the list of values specified in the
|
|
constructor. If the value is in the list then it is accepted. If
|
|
not, then an exception is thrown. Here is a simple example:
|
|
</para>
|
|
<programlisting>
|
|
|
|
vector<string> allowed;
|
|
allowed.push_back("homer");
|
|
allowed.push_back("marge");
|
|
allowed.push_back("bart");
|
|
allowed.push_back("lisa");
|
|
allowed.push_back("maggie");
|
|
|
|
ValueArg<string> nameArg("n","name","Name to print",true,"homer",allowed);
|
|
cmd.add( nameArg );
|
|
|
|
</programlisting>
|
|
<para>
|
|
Instead of a type description being specified in the <classname>Arg</classname>, a
|
|
type description is created by concatenating the values in the
|
|
allowed list using the operator<< for the specified type. The
|
|
help/usage for the <classname>Arg</classname> therefore lists the allowable values.
|
|
Because of this, it is assumed that list should be relatively
|
|
small, although there is no limit on this.
|
|
</para>
|
|
|
|
<para>
|
|
Obviously, a list of allowed values isn't always the best way to
|
|
constrain things. For instance, one might wish to allow only
|
|
integers greater than 0. In this case, the best strategy is for you
|
|
to evaluate the value returned from the getValue() call and if it
|
|
isn't valid, throw an <classname>ArgException</classname>. Be sure that the
|
|
description provided with the <classname>Arg</classname> reflects the constraint
|
|
you choose.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="ARG_ADD_CMDLINE">
|
|
<title>I want the Args to add themselves to the CmdLine...</title>
|
|
<para>
|
|
New constructors have beed added for each <classname>Arg</classname> that take a
|
|
<classname>CmdLine</classname> object as an argument. Each <classname>Arg</classname> then
|
|
<methodname>add</methodname>s itself to the <classname>CmdLine</classname> object. There is no
|
|
difference in how the <classname>Arg</classname> is handled between this method and
|
|
calling the <methodname>add()</methodname> method directly. At the moment, there is
|
|
no way to do an <methodname>xorAdd()</methodname> from the constructor. Here is an
|
|
example:
|
|
</para>
|
|
<programlisting>
|
|
|
|
// Create the command line.
|
|
CmdLine cmd("this is a message", '=', "0.99" );
|
|
|
|
// Note that the following args take the "cmd" object as arguments.
|
|
SwitchArg btest("B","existTestB", "exist Test B", false, cmd );
|
|
|
|
ValueArg<string> stest("s", "stringTest", "string test", true, "homer",
|
|
"string", cmd );
|
|
|
|
UnlabeledValueArg<string> utest("unTest1","unlabeled test one",
|
|
"default","string", cmd );
|
|
|
|
// NO add() calls!
|
|
|
|
// Parse the command line.
|
|
cmd.parse(argc,argv);
|
|
|
|
</programlisting>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="EXCEPTIONS">
|
|
<title>Exceptions to the Rules</title>
|
|
<para>
|
|
Like all good rules, there are many exceptions....
|
|
</para>
|
|
|
|
<sect1 id="IGNORE_ARGS">
|
|
<title>Ignoring arguments</title>
|
|
<para>
|
|
The <parameter>--</parameter> flag is automatically included in the <classname>CmdLine</classname>.
|
|
As (almost) per POSIX and GNU standards, any argument specified
|
|
after the <parameter>--</parameter> flag is ignored. <emphasis>Almost</emphasis> because if an
|
|
<classname>UnlabeledValueArg</classname> that has not been set or an
|
|
<classname>UnlabeledMultiArg</classname> has been specified, by default we will
|
|
assign any arguments beyond the <parameter>--</parameter> to the those arguments as
|
|
per the rules above. This is primarily useful if you want to pass
|
|
in arguments with a dash as the first character of the argument. It
|
|
should be noted that even if the <parameter>--</parameter> flag is passed on the
|
|
command line, the <classname>CmdLine</classname> will <emphasis>still</emphasis> test to make
|
|
sure all of the required arguments are present.
|
|
</para>
|
|
|
|
<para>
|
|
Of course, this isn't how POSIX/GNU handle things, they explicitly
|
|
ignore arguments after the <parameter>--</parameter>. To accomodate this, we can
|
|
make both <classname>UnlabeledValueArg</classname>s and <classname>UnlabeledMultiArg</classname>s
|
|
ignoreable in their constructors. See the <ulink url="html/index.html">
|
|
API Documentation</ulink> for details.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="COMBINED_SWITCHES">
|
|
<title>Multiple Identical Switches</title>
|
|
<para>
|
|
If you absolutely must allow for multiple, identical switches, then
|
|
don't use a <classname>SwitchArg</classname>, instead use a <classname>MultiArg</classname> of type
|
|
<classname>bool</classname>. This means you'll need to specify a 1 or 0 on the
|
|
command line with the switch (as values are required), but this
|
|
should allow you to turn your favorite switch on and off to your
|
|
heart's content.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="DESCRIPTION_EXCEPTIONS">
|
|
<title>Type Descriptions</title>
|
|
<para>
|
|
Ideally this library would use RTTI to return a human readable name
|
|
of the type declared for a particular argument. Unfortunately, at
|
|
least for g++, the names returned aren't particularly useful.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="VISITORS">
|
|
<title>Visitors</title>
|
|
<sect1>
|
|
<para>
|
|
Disclaimer: Almost no one will have any use for Visitors, they were
|
|
added to provide special handling for default arguments. Nothing
|
|
that Visitors do couldn't be accomplished by the user after the
|
|
command line has been parsed. If you're still interested, keep
|
|
reading...
|
|
</para>
|
|
|
|
<para>
|
|
Some of you may be wondering how we get the <parameter>--help</parameter>,
|
|
<parameter>--version</parameter> and <parameter>--</parameter> arguments to do their thing without
|
|
mucking up the <classname>CmdLine</classname> code with lots of <emphasis>if</emphasis>
|
|
statements and type checking. This is accomplished by using a
|
|
variation on the Visitor Pattern. Actually, it may not be a Visitor
|
|
Pattern at all, but that's what inspired me.
|
|
</para>
|
|
|
|
<para>
|
|
If we want some argument to do some sort of special handling,
|
|
besides simply parsing a value, then we add a <classname>Visitor</classname>
|
|
pointer to the <classname>Arg</classname>. More specifically, we add a
|
|
<emphasis>subclass</emphasis> of the <classname>Visitor</classname> class. Once the argument has
|
|
been successfully parsed, the <classname>Visitor</classname> for that argument is
|
|
called. Any data that needs to be operated on is declared in the
|
|
<classname>Visitor</classname> constructor and then operated on in the
|
|
<methodname>visit()</methodname> method. A <classname>Visitor</classname> is added to an <classname>Arg</classname>
|
|
as the last argument in its declaration. This may sound
|
|
complicated, but it is pretty straightforward. Let's see an
|
|
example.
|
|
</para>
|
|
|
|
<para>
|
|
Say you want to add an <parameter>--authors</parameter> flag to a program that
|
|
prints the names of the authors when present. First subclass
|
|
<classname>Visitor</classname>:
|
|
<programlisting>
|
|
#include "Visitor.h"
|
|
#include <string>
|
|
#include <iostream>
|
|
|
|
class AuthorVisitor : public Visitor
|
|
{
|
|
protected:
|
|
string _author;
|
|
public:
|
|
AuthorVisitor(const string& name ) : Visitor(), _author(name) {} ;
|
|
void visit() { cout << "AUTHOR: " << _author << endl; exit(0); };
|
|
};
|
|
</programlisting>
|
|
Now include this class definition somewhere and go about creating
|
|
your command line. When you create the author switch, add the
|
|
<classname>AuthorVisitor</classname> pointer as follows:
|
|
<programlisting>
|
|
|
|
SwitchArg author("a","author","Prints author name", false,
|
|
new AuthorVisitor("Homer J. Simpson") );
|
|
cmd.add( author );
|
|
|
|
</programlisting>
|
|
Now, any time the <parameter>-a</parameter> or <parameter>--author</parameter> flag is specified,
|
|
the program will print the author name, Homer J. Simpson and exit
|
|
without processing any further (as specified in the <methodname>visit()</methodname>
|
|
method).
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="MORE_INFO">
|
|
<title>More Information</title>
|
|
<para>
|
|
For more information, look at the <ulink url="html/index.html"> API
|
|
Documentation</ulink> and the examples included with the
|
|
distribution.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>Happy coding!</emphasis>
|
|
</para>
|
|
|
|
<para id="FOOTNOTES">
|
|
** In theory, any type that supports operator>> and
|
|
operator<< should work, although I've really only tried
|
|
things with basic types like int, float, string, etc.
|
|
</para>
|
|
</chapter>
|
|
</book>
|