Copyright © 2003,2004,2005,2006,2009,2011,2012 Michael E. Smoot
Table of Contents
Table of Contents
+
Copyright © 2003,2004,2005,2006,2009,2011,2012 Michael E. Smoot
Table of Contents
Table of Contents
TCLAP has a few key classes to be aware of.
The first is the
CmdLine (command line) class. This class parses
@@ -14,15 +12,15 @@ argument classes are: ValueArg,
MultiArg and
UnlabeledMultiArg.
These classes are templatized, which means they can be defined to parse
-a value of any type. Once you add the
+a value of any type. Once you add the
arguments to the CmdLine 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 getValue() methods of the
argument objects.
-
-Here is a simple example ... +
+Here is a simple example ...
#include <string>
@@ -137,11 +135,11 @@ Where:
Command description message
-
+
This example shows a number of different properties of the library... -
help, version
+help, version
and --SwitchArgs
are specified automatically. Using either the -h or
--help flag will cause the USAGE message to be displayed,
@@ -150,31 +148,31 @@ any version information to
be displayed, and -- or
--ignore_rest will cause the
remaining labeled arguments to be ignored. These switches are
-included by default on every command line. You can disable this functionality if desired (although we don't recommend it).
+included by default on every command line. You can disable this functionality if desired (although we don't recommend it).
How we generate the behavior behind these flags is described
- later.
--s=asdf instead of
--s asdf, you can do so.-s asdf, you can do so.CmdLine, constructing the Args,
or parsing the command line will throw an
ArgException.-
Arguments, whatever their type, have a few common properties. These properties are set in the constructors of the arguments. -
getopt_long()].getopt_long()].-
+
+
TCLAP is implemented entirely in header files which means you only need to include CmdLine.h to use the library.
@@ -204,7 +202,7 @@ 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! -+
As we understand things, Visual C++ does not have the file
config.hwhich is used to make platform specific definitions. In this situation, we assume that you @@ -217,7 +215,7 @@ then simply tell your compiler to define the variable should work. We think. Alternatively, just edit the filesValueArg.handMultiArg.h.-
The
CmdLineclass contains the arguments that define the command line and manages the parsing of the command line. TheCmdLinedoesn't parse the command line itself it only manages the parsing. The actual parsing of individual arguments occurs within the arguments themselves. TheCmdLinekeeps track of -of the required arguments, relationships -between arguments, and output generation. -
SwitchArgs are what the name implies: +of the required arguments, relationships +between arguments, and output generation. +
SwitchArgs are what the name implies: simple, on/off, boolean switches. UseSwitchArgs anytime you want to turn some sort of system property on or off.SwitchArgs don't parse a value. They returnTRUEorFALSE, depending on whether the switch has been found -on the command line and what the default value was defined as.
ValueArgs are arguments that read a +on the command line and what the default value was defined as.
ValueArgs are arguments that read a value of some type from the command line. Any time you need a file name, a number, etc. use aValueArgor one of its variants. AllValueArgs are - templatized and will attempt to parse + templatized and will attempt to parse the string its flag matches on the command line as the type it is specified as.ValueArg<int>will attempt to parse an @@ -256,7 +254,7 @@ parse a float, etc. Ifoperator>>for the specified type doesn't recognize the string on the command line as its defined type, then an exception will be thrown. -A
MultiArgis aValueArgthat can be specified more than once on a command line and instead of returning a single value, returns avectorof values. @@ -285,8 +283,8 @@ aValueArg:Note that
MultiArgs can be added to theCmdLinein any order (unlike - UnlabeledMultiArg). -+ UnlabeledMultiArg). +
A
MultiSwitchArgis aSwitchArgthat can be specified more than once on a command line. This can be useful @@ -307,7 +305,7 @@ Alternatively, you can specify your own initial value: MultiSwitchArg quiet("q","quiet","Reduce the volume of output",5); cmd.add( quiet );-
An
UnlabeledValueArgis aValueArgthat is not identified by a flag on the command line. InsteadUnlabeledValueArgs are identified by their position in the argv array. @@ -316,7 +314,7 @@ To this point all of our arguments have had labels (flags) identifying 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 copy. All copy does is +call copy. All copy does is copy the file specified in the first argument to the file specified in the second argument. We can do this usingUnlabeledValueArgs which are pretty @@ -327,7 +325,7 @@ The code would look like this:- UnlabeledValueArg<float> nolabel( "name", "unlabeled test", 3.14, + UnlabeledValueArg<float> nolabel( "name", "unlabeled test", true, 3.14, "nameString" ); cmd.add( nolabel ); @@ -348,7 +346,7 @@ args (SwitchArgs and ValueArgs) in between or in the declaration), but theUnlabeledValueArgswill still be parsed in the order they are added. Just remember that order is important for unlabeled arguments. -An
UnlabeledMultiArgis anUnlabeledValueArgthat allows more than one value to be specified. Only oneUnlabeledMultiArgcan be specified per command line. TheUnlabeledMultiArgsimply reads the remaining @@ -356,7 +354,7 @@ values from argv up until -- or the end of the array is reached.Say you want a strange command that searches each file specified for a given string (let's call it -grep), but you don't want to have to type in all of the file +grep), 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,
@@ -364,7 +362,7 @@ names or write a script to do it for you. Say,First remember that the * is handled by the shell and -expanded accordingly, so what the program grep sees is +expanded accordingly, so what the program grep sees is really something like:
@@ -413,11 +411,11 @@ be multiple args of multiple types (stings, ints, floats, etc.) then just declare theUnlabeledMultiArgas typestringand parse the different values yourself or use severalUnlabeledValueArgs. -Table of Contents
- I want to combine multiple switches into one argument...
- I want one argument or the other, but not both...
- I have more arguments than single flags make sense for...
- I want to constrain the values allowed for a particular argument...
- I want the Args to add themselves to the CmdLine...
- I want different output than what is provided...
- I don't want the --help and --version switches to be created automatically...
- I want to ignore certain arguments...
- I want to ignore unmatched arguments...
- I want to read hex integers as arguments...
- I want to use different types...
- I want to use Windows-style flags like "/x" and "/y"...
Naturally, what we have seen to this point doesn't satisfy all of our needs. -
+
Multiple
SwitchArgs 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: @@ -440,7 +438,7 @@ it is valid to do either: This is to make this library more in line with the POSIX and GNU standards (as I understand them). -Suppose you have a command that must read input from one of two possible locations, either a local file or a URL. The command must read something, so one @@ -518,7 +516,7 @@ requires additional information.
-
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
Args using only long options. This one is easy to @@ -534,7 +532,7 @@ option on the command line. The help output is updated accordingly. SwitchArg caseSwitch("","upperCase","Print in upper case",false);-
Interface Change!!! Sorry folks, but we've changed the interface since version 1.0.X for constraining
Args. @@ -587,7 +585,7 @@ implements theConstraint<int>interface an checks whether the value parsed is greater than 0 (done in thecheck()method) and create yourArgwith your newConstraint. -New constructors have been added for each
Argthat take aCmdLineobject as an argument. EachArgthen @@ -618,7 +616,7 @@ is an example: cmd.parse(argc,argv);-
It is straightforward to change the output generated by TCLAP. Either subclass the
StdOutputclass and re-implement the methods you choose, @@ -671,7 +669,7 @@ could lead to a (very small) memory leak if you don't take care of the object yourself. Also note that thefailuremethod is now responsible for exiting the application (assuming that is the desired behavior). -Help and version information is useful for nearly all command line applications and as such we generate flags that provide those options automatically. However, there are situations when these flags are undesirable. For these @@ -681,7 +679,7 @@ false will disable automatic help and version generation.
CmdLine cmd("this is a message", ' ', "0.99", false );-
The
--flag is automatically included in theCmdLine. As (almost) per POSIX and GNU standards, any argument specified @@ -702,8 +700,8 @@ Of course, this isn't how POSIX/GNU handle things, they explicitly ignore arguments after the--. To accommodate this, we can make bothUnlabeledValueArgs andUnlabeledMultiArgs ignoreable in their constructors. -See the API Documentation for details. -+See the API Documentation for details. +
By default, if TCLAP sees an argument that doesn't match a specified
Arg, it will produce an exception. This strict handling provides some assurance that all input to a program @@ -754,7 +752,7 @@ parser. is set to true and anUnlabeledMultiArgis added to the command line, then theUnlabeledMultiArgwill "win" and all extra arguments will be added to it rather than be ignored. -Sometimes it's desirable to read integers formatted in decimal, hexadecimal, and octal format. This is now possible by #defining the
TCLAP_SETBASE_ZEROdirective. Simply define this directive in your code and integer arguments will be parsed @@ -800,7 +798,7 @@ The reason that this behavior is not the default behavior for setbase() is meant to be used. So while we're making this functionality available, we're not turning it on by default for fear of bad things happening in different compilers. If you know otherwise, please let us know. -The usual C++ types (int, long, bool, etc.) are supported by TCLAP out of the box. As long as operator>> and operator<< are supported, other types should work fine @@ -826,7 +824,7 @@ To accomplish this, add the following declaration to your file: For complete examples see the files
test11.cppandtest12.cppin the examples directory. -It is traditional in Posix environments that the "-" and "--" strings are used to signify the beginning of argument flags and long argument names. However, other environments, namely Windows, use different strings. TCLAP allows you to @@ -857,14 +855,14 @@ int main(int argc, char** argv)
-
Table of Contents
Like all good rules, there are many exceptions.... -
+
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 +least for g++, the names returned aren't particularly useful. -
Disclaimer: Almost no one will have any use for
Visitors, they were added to provide special handling for default arguments. Nothing @@ -933,8 +931,8 @@ Now, any time the-aor the program will print the author name, Homer J. Simpson and exit without processing any further (as specified in thevisit()method). --For more information, look at the +
+For more information, look at the API Documentation and the examples included with the distribution.