OptionVar Class Reference
[Command line options library]

The OptionVar class is an obsolete predecessor of Options. More...

#include <optionvar.h>

Collaboration diagram for OptionVar:

[legend]List of all members.

Public Member Functions
	OptionVar ()
	Default constructor.
	OptionVar (const char *n, unsigned int &var)
	Constructor: creates a new option called n and referring to an unsigned int.
	OptionVar (const char *n, int &var)
	Constructor: creates a new option called n and referring to a signed int.
	OptionVar (const char *n, double &var)
	Constructor: creates a new option called n and referring to a double.
	OptionVar (const char *n, char *var)
	Constructor: creates a new option called n and referring to an C string.
	OptionVar (const char *n, bool &var)
	Constructor: creates a new option called n and referring to an boolean.
	~OptionVar ()
	Destructor.
OptionVar *	tail ()
	Returns a pointer to the last node in the list.
OptionVar *	GetOptionPtr (const char *n)
	Searches the list for the first node named n and returns its address, or NULL if not found.
OptionVar *	AddOption (const char *n, unsigned int &var)
	Append a new node to the list, called n and referring to an unsigned int.
OptionVar *	AddOption (const char *n, int &var)
	Append a new node to the list, called n and referring to a signed int.
OptionVar *	AddOption (const char *n, double &var)
	Append a new node to the list, called n and referring to a double.
OptionVar *	AddOption (const char *n, bool &var)
	Append a new node to the list, called n and referring to a boolean.
OptionVar *	AddOption (const char *n, char *var)
	Append a new node to the list, called n and referring to a C string.
OptionVar *	SetOption (const char *n, char *var)
	Searches the list for the first node named n and assigns it a value parsed from var. Returns a pointer to the changed node, or NULL if not found.
OptionVar *	SetOption (const char *n, double var)
	Searches the list for the first node named n, and assigns the value var. Returns a pointer to the changed node, or NULL if not found.
OptionVar *	ParseOption (char *str)
	Parses a C string of the form "name=value", finds a node with the parsed name, assigns it the parsed value, and returns a pointer to it.
int	ParseOptionList (char **str, int n)
	Parses an array of n strings, using ParseOption().
int	ParseOptionStream (std::istream &is)
	Parses a sequence of "name=value" tokens from an istream, using ParseOption().
void *	GetOption (char *n, void *var=NULL, int maxl=0)
	Seaches the list for the first node named n, and returns a void* pointer to the variable to which it refers. Not sure what optional parameters do (6/06).
void	Print (std::ostream &os=std::cout, bool chain=0)
	Prints this node to a stream. If chain is set, then all succeeding nodes are printed as well.
Public Attributes
VarType	type
	What type of variable this option refers to.
void *	ptr
	A pointer to the variable.
char *	name
	The variable's name.
OptionVar *	next
	Pointer to the next node in the list.

---

Detailed Description

The OptionVar class is an obsolete predecessor of Options.

To use the OptionVar class, declare a variable of type OptionVar, with an optional constructor.

• STRUCTURE: An OptionVar is a node in a singly linked list. Thus, when you declare an OptionVar, you're actually declaring an expandable list of nodes. However, access is transparent through the head node which you declared.

• DECLARING: The OptionVar variable can be declared either with no constructor parameters, in which case the head node is empty, or with a constructor syntax that is identical to the AddOption functions. The AddOption functions construct a new node at the end of the chain, with the given parameters.

• ADDING: Variables can be associated with Names using AddOption. Syntax is simple: from the head node (or any node in the chain, actually), the AddOption() member function is called. This is actually a family of overloaded functions. The first parameter is the Name, while the second parameter is the variable itself. That's it. A new OptionVar is added at the end of the chain, associating that Name with that Variable.

• PARSING: Once the chain has been defined, and all the Names to be recognized are in the OptionVar list, the head OptionVar can read in options from several sources (all associations in the chain are checked):
  • ParseOption( char *): Reads a single string. If the string is a valid option of the form "Name=Value", then the variable associated with Name is set to Value. If not, nothing happens.
  • ParseOptionStream( istream & ): Reads all the strings from an istream, until EOF is reached. ParseOption( char * ) is used for each.
  • ParseOptionList( char **, int ): Reads all the strings in a list of strings, up to the number given.

• NOTES on formatting:
  • On the command line, option strings of the form "Name=Value" should be separated by one or more spaces.
  • When reading from a stream or a file, option strings are separated by newlines.
  • Spaces should NOT be included on the command line; use `N=2', not `N = 2'. This is because it will screw up the argv processing.
  • Strings may be quoted or not: `name=Fluffy' is equivalent to `name="Fluffy"'.
  • Spaces may always be included within strings: i.e., `title="Big Bone"' will work.
  • Boolean (bool) variables may be initialized with any string beginning with {t,T,f,F}, with the obvious results. Any other input ("0" or "1", for instance) will be discarded, and the option will be ignored (its variable will be left unchanged)
  • When reading from a stream or file, any name may be preceded by its type: `int N = 5' is equivalent to `N=5'.
  • As a consequence of the previous note, OptionVar can always read its own printed output (see below).

• SOURCING: There is one special option: _source. Including a string of the form `_source=filename' will cause `filename' to be opened as a text file and parsed for options. Such files may be chained; a file may include a _source directive itself.

• PRINTING: At any time, an OptionVar node can be commanded to print out its data in the form "[type] Name = Value \n" with the .Print() member function. This takes two parameters: the first is an ostream to print to (i.e., std::cout); the second is a boolean which determines whether or not output is CHAINED -- that is, does the node then tell its downstream neighbor to Print as well? Default values are std::cout and FALSE. In general, you'll want to print either to std::cout, std::cerr, or to a file, and you'll want to enable chaining from the head node, thus printing the entire option list. Note that OptionVar always prints out a format that it can itself read, so if options are printed out _after_ they're completely set up, then you can duplicate the setup precisely by simply `_source'ing the output file!

• MISC: There are a couple of rarely used functionalities as well.
  • GetOptionPtr( char *Name)can be used to get a pointer to the downstream node which associates Name with a variable (or NULL if no such node exists).
  • SetOption( Name, ValueString ) can be used to set the value of the variable associated with Name, as can SetOption( Name, ValueDouble).
  • GetOption( Name, VariablePtr, maxlength) is a very non-type-safe (i.e., uses void*) method which stores the Value that Name is associated with in VariablePtr (strings are copied only up to maxlength). I strongly recommmend not using this unless you REALLY know what you're doing, since it's possible to innocently cause segmentation faults and that sort of thing!

---

The documentation for this class was generated from the following files:

• optionvar.h
• optionvar.cpp

---