ArgMap Utilities

ArgMap's are designed to serve as a convenient and efficient means of storing variables that are shared by different processes. The following utilities exist for converting them to and from various intermediate forms. The intermediate forms (referred to as ``external'' hereafter) include:

Parfile format
Environment variables
Command line options
Many other ascii string-based protocols and formats

Each of these has corresponding extended ArgMap class (class ArgMap_par, ArgMap_env, ArgMap_opt, and ArgMap_stream) with load(), save(), and possibly save_changes() members.

a.load( source, Regex match, String prefix );
a.save( dest, Regex match, String prefix );
a.save_changes( dest, Regex match, String prefix );

These functions all follow a general pattern:

``a'' is your existing ArgMap_xxx class
``source'' is some kind of pointer the the external format (parfile name, environment pointer, command line argument pointer, etc.)
``match'' is pointer to an emacs regular expression matching for names. If omitted, or set to NULL, regex filtering will be turned off.

``prefix'' is a String that is tacked on only to the "external format" copy of the argument. Defaults to the nil string.

In the case of a save(), all names in the ArgMap that match the regular expression will be written to the external format with the prefix string pre-pended to their names.
In the case of a load(), all the names in the external format that match both the regular expression and start with prefix will be merged into the ArgMap, but with the prefix stripped off. If a prefix is given, and names that don't start with it will be ignored.

Here are the actual prototypes:

ArgMap_opt::load( char** argv, Regex* match=0, String prefix="" );
ArgMap_opt::save( char** argv, Regex* match=0, String prefix="" );
ArgMap_env::load( char** envp, Regex* match=0, String prefix="" );
ArgMap_env::save( char** envp, Regex* match=0, String prefix="" );
ArgMap_par::load( String& filename, Regex* match=0, String prefix="" );
ArgMap_par::save( String& filename, Regex* match=0, String prefix="" );
ArgMap_stream ... see below.

Only parameter 1. is required, but if you want to specify 3, you must also specify 2.

ArgMap_stream::load()

This routine is a general purpose text file parser. If the text can somehow be represented as an ArgMap then this routine can probably read into an ArgMap data structure. Here is example code that uses the routine:

Instead of fstreams, any kind of already opened input stream can be passed to the routine. For example, pass `cin' instead of `global_var_str' and it will parse input from standard input, or pass it a strstream into which you have printed a string, and it will parse a character string that's already in core. See also, information on C++ streams.

The fmt_xxx argument must be a 10 character array that specifies how to parse the input. The ten characters needed are:

start -- skip to this character and read next token as "ident"/tagname
pair -- the character that sits between the name and the value. eg '='
sep -- the character that separates one pair from another. eg ','
end -- the character that indicates the end of the input. eg '\n'
trim -- a character to trim off the front and back of a name or value. eg ' '
strip -- use this instead of trim if you NEVER want to see a character. eg '\r'
open -- the open quote character for a name or value string. eg '"'
close -- the close quote character for a name or value string. eg '"'
esc -- the escape character for inserting a literal character. eg '\\'
com -- everything including this line and the next 'sep' is a comment eg ';'

If any of these could be multiple characters (sequences are not allowed, but it is possible to allow either a " or a ' as the open quote character for example) then the following special values should be used instead of a single character.

Cna -- Character is not applicable, CEQ() will always return 0
Cws -- "white space" as defined by isspace
Cpo -- Accept both a \" and a \{ as an open quote
Cpc -- for parsing par file value fields

The file ArgMap_util.h automatically defines the following types

fmt_type	start	pair	sep	end	trim	strip	open	close	esc	com
fmt_mime_hdr	Cna	':'	'\n'	'\n'	' '	'\r'	Cna	Cna	Cna	Cna
fmt_html_post	Cna	'='	'&'	Cws	Cna	Cna	Cna	Cna	Cna	Cna
fmt_duck_stat	Cna	'='	'\n'	Cna	' '	'\r'	Cna	Cna	Cna	Cna
fmt_html	'<'	'='	' '	'>'	Cws	'\r'	'\"'	'\"'	Cna	Cna
fmt_rpm	Cna	'='	' '	'}'	Cws	'\r'	'('	')'	'\\'	Cna
fmt_parfile	Cna	'='	'\n'	Cna	Cws	'\r'	Cpo	Cpc	'\\'	'#'

Special notes for creating a new "fmt" type

Specify Cna for any of the above that don't apply
An end-of-file condition is always treated as 'end' so specify Cna for 'end' if all of the input should be parsed.
Specify Cws instead of a ' ' if you want all isspace() characters for a particular field.
If the 'open' and 'close' characters are different, then nested quoting is allowed, and will be treated correctly.
If the 'sep' and 'end' characters are the same then a zero length name, or two 'sep's (eg a blank line if 'sep' is a newline) will terminate the list.
The 'esc' character causes the next single character that is read to lose any special meaning that it might have had.
Unescaped comment characters are allowed within quotes