From 8be8e45e4408c5cb3db9eb1c4c3215b3577b110e Mon Sep 17 00:00:00 2001 From: mes5k Date: Tue, 6 Jul 2004 02:02:17 +0000 Subject: [PATCH] updated for allowed --- docs/manual.html | 79 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 66 insertions(+), 13 deletions(-) diff --git a/docs/manual.html b/docs/manual.html index 7c46936..6b9c584 100644 --- a/docs/manual.html +++ b/docs/manual.html @@ -32,11 +32,14 @@

Basic usage

There are a few key classes to be aware of. The first is the CmdLine -or command line class. This is the class that parses the command line +(command line) class. This is the class that parses the command line passed to it according to the arguments that it contains. Arguments are -separate objects that are added to CmdLine object one at a time. There +separate objects that are added to the CmdLine object one at a time. +There are five types of arguments, ValueArg, UnlabeledValueArg, -SwitchArg, MultiArg and UnlabeledMultiArg. +SwitchArg, MultiArg and UnlabeledMultiArg. These +are templatized classes meaning they can be defined to parse a value of any +type**. Once the arguments are added to the command line object, the command line is parsed which assigns the data on the command line to the specific argument objects. The values are accessed by calls to @@ -138,21 +141,23 @@ Command description message


This example shows a number of different properties of the library...

Basic Properties

-Arguments, whatever their type, have a few common basic properties. First +Arguments, whatever their type, have a few common basic properties. These +properties are set in the constructors of the arguments. First is the flag or the character preceeded by a dash(-) that signals the beginning -of the argument. Arguments also have names, which can, if desired also be +of the argument on the command line. +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()]. Next is the description of the argument. This is a short description of @@ -174,15 +179,15 @@ valid to do either: 
 		% command -a -b -c
-

+
or -

+
 		% command -abc
-

+
or -

+
 		% command -ba -c
@@ -426,6 +431,48 @@ The help output is updated accordingly.

+

I want to constrain the values allowed for a particular argument...

+New Feature! There are new constructors for all of the Args that +take values that allow a list of values to be specified for that particular +Arg. When the value for the Arg 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: + +
+
+	...
+
+	vector allowed;
+	allowed.push_back("homer");
+	allowed.push_back("marge");
+	allowed.push_back("bart");
+	allowed.push_back("lisa");
+	allowed.push_back("maggie");
+	
+	ValueArg nameArg("n","name","Name to print",true,"homer",allowed);
+	cmd.add( nameArg );
+
+	...
+
+
+ + +Instead of a type description being specified in the Arg, 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 Arg therefore lists the allowable values. +Because of this, it is assumed that list should be relatively small, +although there is no limit on this. +

+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 ArgException. +Be sure that the description provided with the Arg reflects the +constraint you choose. +

+

Visitors

@@ -526,5 +573,11 @@ the API Documentation and the examples included with the distribution.

Happy coding! + +

+ +
+** 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. +