path: root/doc/libopts.texi

@node libopts procedures
@subsection libopts External Procedures

These are the routines that libopts users may call directly from their
code.  There are several other routines that can be called by code
generated by the libopts option templates, but they are not to be
called from any other user code.  The @file{options.h} header is
fairly clear about this, too.

@menu
* libopts-ao_string_tokenize:: ao_string_tokenize
* libopts-configFileLoad::    configFileLoad
* libopts-optionFileLoad::    optionFileLoad
* libopts-optionFindNextValue:: optionFindNextValue
* libopts-optionFindValue::   optionFindValue
* libopts-optionFree::        optionFree
* libopts-optionGetValue::    optionGetValue
* libopts-optionLoadLine::    optionLoadLine
* libopts-optionNextValue::   optionNextValue
* libopts-optionOnlyUsage::   optionOnlyUsage
* libopts-optionProcess::     optionProcess
* libopts-optionRestore::     optionRestore
* libopts-optionSaveFile::    optionSaveFile
* libopts-optionSaveState::   optionSaveState
* libopts-optionUnloadNested:: optionUnloadNested
* libopts-optionVersion::     optionVersion
* libopts-pathfind::          pathfind
* libopts-strequate::         strequate
* libopts-streqvcmp::         streqvcmp
* libopts-streqvmap::         streqvmap
* libopts-strneqvcmp::        strneqvcmp
* libopts-strtransform::      strtransform
@end menu

This subsection was automatically generated by AutoGen
using extracted information and the aginfo3.tpl template.

@node libopts-ao_string_tokenize
@subsubsection ao_string_tokenize
@findex ao_string_tokenize

tokenize an input string

@noindent
Usage:
@example
token_list_t* res = ao_string_tokenize( string );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab string @tab @code{char const*}
@tab string to be tokenized
@item @tab returns @tab token_list_t*
@tab pointer to a structure that lists each token
@end multitable

This function will convert one input string into a list of strings.
The list of strings is derived by separating the input based on
white space separation.  However, if the input contains either single
or double quote characters, then the text after that character up to
a matching quote will become the string in the list.

The returned pointer should be deallocated with @code{free(3C)} when
are done using the data.  The data are placed in a single block of
allocated memory.  Do not deallocate individual token/strings.

The structure pointed to will contain at least these two fields:
@table @samp
@item tkn_ct
The number of tokens found in the input string.
@item tok_list
An array of @code{tkn_ct + 1} pointers to substring tokens, with
the last pointer set to NULL.
@end table

There are two types of quoted strings: single quoted (@code{'}) and
double quoted (@code{"}).  Singly quoted strings are fairly raw in that
escape characters (@code{\\}) are simply another character, except when
preceding the following characters:
@example
@code{\\}  double backslashes reduce to one
@code{'}   incorporates the single quote into the string
@code{\n}  suppresses both the backslash and newline character
@end example

Double quote strings are formed according to the rules of string
constants in ANSI-C programs.

NULL is returned and @code{errno} will be set to indicate the problem:
@itemize @bullet
@item
@code{EINVAL} - There was an unterminated quoted string.
@item
@code{ENOENT} - The input string was empty.
@item
@code{ENOMEM} - There is not enough memory.
@end itemize


@node libopts-configFileLoad
@subsubsection configFileLoad
@findex configFileLoad

parse a configuration file

@noindent
Usage:
@example
const tOptionValue* res = configFileLoad( pzFile );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pzFile @tab @code{char const*}
@tab the file to load
@item @tab returns @tab const tOptionValue*
@tab An allocated, compound value structure
@end multitable

This routine will load a named configuration file and parse the
text as a hierarchically valued option.  The option descriptor
created from an option definition file is not used via this interface.
The returned value is "named" with the input file name and is of
type "@code{OPARG_TYPE_HIERARCHY}".  It may be used in calls to
@code{optionGetValue()}, @code{optionNextValue()} and
@code{optionUnloadNested()}.

If the file cannot be loaded or processed, @code{NULL} is returned and
@var{errno} is set.  It may be set by a call to either @code{open(2)}
@code{mmap(2)} or other file system calls, or it may be:
@itemize @bullet
@item
@code{ENOENT} - the file was not found.
@item
@code{ENOMSG} - the file was empty.
@item
@code{EINVAL} - the file contents are invalid -- not properly formed.
@item
@code{ENOMEM} - not enough memory to allocate the needed structures.
@end itemize


@node libopts-optionFileLoad
@subsubsection optionFileLoad
@findex optionFileLoad

Load the locatable config files, in order

@noindent
Usage:
@example
int res = optionFileLoad( pOpts, pzProg );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOpts @tab @code{tOptions*}
@tab program options descriptor

@item @tab pzProg @tab @code{char const*}
@tab program name
@item @tab returns @tab int
@tab 0 -> SUCCESS, -1 -> FAILURE
@end multitable

This function looks in all the specified directories for a configuration
file ("rc" file or "ini" file) and processes any found twice.  The first
time through, they are processed in reverse order (last file first).  At
that time, only "immediate action" configurables are processed.  For
example, if the last named file specifies not processing any more
configuration files, then no more configuration files will be processed.
Such an option in the @strong{first} named directory will have no effect.

Once the immediate action configurables have been handled, then the
directories are handled in normal, forward order.  In that way, later
config files can override the settings of earlier config files.

See the AutoOpts documentation for a thorough discussion of the
config file format.

Configuration files not found or not decipherable are simply ignored.

Returns the value, "-1" if the program options descriptor
is out of date or indecipherable.  Otherwise, the value "0" will
always be returned.


@node libopts-optionFindNextValue
@subsubsection optionFindNextValue
@findex optionFindNextValue

find a hierarcicaly valued option instance

@noindent
Usage:
@example
const tOptionValue* res = optionFindNextValue( pOptDesc, pPrevVal, name, value );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOptDesc @tab @code{const tOptDesc*}
@tab an option with a nested arg type

@item @tab pPrevVal @tab @code{const tOptionValue*}
@tab the last entry

@item @tab name @tab @code{char const*}
@tab name of value to find

@item @tab value @tab @code{char const*}
@tab the matching value
@item @tab returns @tab const tOptionValue*
@tab a compound value structure
@end multitable

This routine will find the next entry in a nested value option or
configurable.  It will search through the list and return the next entry
that matches the criteria.

The returned result is NULL and errno is set:
@itemize @bullet
@item
@code{EINVAL} - the @code{pOptValue} does not point to a valid
hierarchical option value.
@item
@code{ENOENT} - no entry matched the given name.
@end itemize


@node libopts-optionFindValue
@subsubsection optionFindValue
@findex optionFindValue

find a hierarcicaly valued option instance

@noindent
Usage:
@example
const tOptionValue* res = optionFindValue( pOptDesc, name, value );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOptDesc @tab @code{const tOptDesc*}
@tab an option with a nested arg type

@item @tab name @tab @code{char const*}
@tab name of value to find

@item @tab value @tab @code{char const*}
@tab the matching value
@item @tab returns @tab const tOptionValue*
@tab a compound value structure
@end multitable

This routine will find an entry in a nested value option or configurable.
It will search through the list and return a matching entry.

The returned result is NULL and errno is set:
@itemize @bullet
@item
@code{EINVAL} - the @code{pOptValue} does not point to a valid
hierarchical option value.
@item
@code{ENOENT} - no entry matched the given name.
@end itemize


@node libopts-optionFree
@subsubsection optionFree
@findex optionFree

free allocated option processing memory

@noindent
Usage:
@example
optionFree( pOpts );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOpts @tab @code{tOptions*}
@tab program options descriptor
@end multitable

AutoOpts sometimes allocates memory and puts pointers to it in the
option state structures.  This routine deallocates all such memory.

As long as memory has not been corrupted,
this routine is always successful.


@node libopts-optionGetValue
@subsubsection optionGetValue
@findex optionGetValue

get a specific value from a hierarcical list

@noindent
Usage:
@example
const tOptionValue* res = optionGetValue( pOptValue, valueName );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOptValue @tab @code{const tOptionValue*}
@tab a hierarchcal value

@item @tab valueName @tab @code{char const*}
@tab name of value to get
@item @tab returns @tab const tOptionValue*
@tab a compound value structure
@end multitable

This routine will find an entry in a nested value option or configurable.
If "valueName" is NULL, then the first entry is returned.  Otherwise,
the first entry with a name that exactly matches the argument will be
returned.  If there is no matching value, NULL is returned and errno is
set to ENOENT. If the provided option value is not a hierarchical value,
NULL is also returned and errno is set to EINVAL.

The returned result is NULL and errno is set:
@itemize @bullet
@item
@code{EINVAL} - the @code{pOptValue} does not point to a valid
hierarchical option value.
@item
@code{ENOENT} - no entry matched the given name.
@end itemize


@node libopts-optionLoadLine
@subsubsection optionLoadLine
@findex optionLoadLine

process a string for an option name and value

@noindent
Usage:
@example
optionLoadLine( opts, line );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab opts @tab @code{tOptions*}
@tab program options descriptor

@item @tab line @tab @code{char const*}
@tab NUL-terminated text
@end multitable

This is a client program callable routine for setting options from, for
example, the contents of a file that they read in.  Only one option may
appear in the text.  It will be treated as a normal (non-preset) option.

When passed a pointer to the option struct and a string, it will find
the option named by the first token on the string and set the option
argument to the remainder of the string.  The caller must NUL terminate
the string.  The caller need not skip over any introductory hyphens.
Any embedded new lines will be included in the option
argument.  If the input looks like one or more quoted strings, then the
input will be "cooked".  The "cooking" is identical to the string
formation used in AutoGen definition files (@pxref{basic expression}),
except that you may not use backquotes.

Invalid options are silently ignored.  Invalid option arguments
will cause a warning to print, but the function should return.


@node libopts-optionNextValue
@subsubsection optionNextValue
@findex optionNextValue

get the next value from a hierarchical list

@noindent
Usage:
@example
const tOptionValue* res = optionNextValue( pOptValue, pOldValue );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOptValue @tab @code{const tOptionValue*}
@tab a hierarchcal list value

@item @tab pOldValue @tab @code{const tOptionValue*}
@tab a value from this list
@item @tab returns @tab const tOptionValue*
@tab a compound value structure
@end multitable

This routine will return the next entry after the entry passed in.  At the
end of the list, NULL will be returned.  If the entry is not found on the
list, NULL will be returned and "@var{errno}" will be set to EINVAL.
The "@var{pOldValue}" must have been gotten from a prior call to this
routine or to "@code{opitonGetValue()}".

The returned result is NULL and errno is set:
@itemize @bullet
@item
@code{EINVAL} - the @code{pOptValue} does not point to a valid
hierarchical option value or @code{pOldValue} does not point to a
member of that option value.
@item
@code{ENOENT} - the supplied @code{pOldValue} pointed to the last entry.
@end itemize


@node libopts-optionOnlyUsage
@subsubsection optionOnlyUsage
@findex optionOnlyUsage

Print usage text for just the options

@noindent
Usage:
@example
optionOnlyUsage( pOpts, ex_code );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOpts @tab @code{tOptions*}
@tab program options descriptor

@item @tab ex_code @tab @code{int}
@tab exit code for calling exit(3)
@end multitable

This routine will print only the usage for each option.
This function may be used when the emitted usage must incorporate
information not available to AutoOpts.


@node libopts-optionProcess
@subsubsection optionProcess
@findex optionProcess

this is the main option processing routine

@noindent
Usage:
@example
int res = optionProcess( pOpts, argc, argv );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOpts @tab @code{tOptions*}
@tab program options descriptor

@item @tab argc @tab @code{int}
@tab program arg count

@item @tab argv @tab @code{char**}
@tab program arg vector
@item @tab returns @tab int
@tab the count of the arguments processed
@end multitable

This is the main entry point for processing options.  It is intended
that this procedure be called once at the beginning of the execution of
a program.  Depending on options selected earlier, it is sometimes
necessary to stop and restart option processing, or to select completely
different sets of options.  This can be done easily, but you generally
do not want to do this.

The number of arguments processed always includes the program name.
If one of the arguments is "--", then it is counted and the processing
stops.  If an error was encountered and errors are to be tolerated, then
the returned value is the index of the argument causing the error.
A hyphen by itself ("-") will also cause processing to stop and will
@emph{not} be counted among the processed arguments.  A hyphen by itself
is treated as an operand.  Encountering an operand stops option
processing.

Errors will cause diagnostics to be printed.  @code{exit(3)} may
or may not be called.  It depends upon whether or not the options
were generated with the "allow-errors" attribute, or if the
ERRSKIP_OPTERR or ERRSTOP_OPTERR macros were invoked.


@node libopts-optionRestore
@subsubsection optionRestore
@findex optionRestore

restore option state from memory copy

@noindent
Usage:
@example
optionRestore( pOpts );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOpts @tab @code{tOptions*}
@tab program options descriptor
@end multitable

Copy back the option state from saved memory.
The allocated memory is left intact, so this routine can be
called repeatedly without having to call optionSaveState again.
If you are restoring a state that was saved before the first call
to optionProcess(3AO), then you may change the contents of the
argc/argv parameters to optionProcess.

If you have not called @code{optionSaveState} before, a diagnostic is
printed to @code{stderr} and exit is called.


@node libopts-optionSaveFile
@subsubsection optionSaveFile
@findex optionSaveFile

saves the option state to a file

@noindent
Usage:
@example
optionSaveFile( pOpts );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOpts @tab @code{tOptions*}
@tab program options descriptor
@end multitable

This routine will save the state of option processing to a file.  The name
of that file can be specified with the argument to the @code{--save-opts}
option, or by appending the @code{rcfile} attribute to the last
@code{homerc} attribute.  If no @code{rcfile} attribute was specified, it
will default to @code{.@i{programname}rc}.  If you wish to specify another
file, you should invoke the @code{SET_OPT_SAVE_OPTS(@i{filename})} macro.

The recommend usage is as follows:
@example
optionProcess(&progOptions, argc, argv);
if (i_want_a_non_standard_place_for_this)
SET_OPT_SAVE_OPTS("myfilename");
optionSaveFile(&progOptions);
@end example

If no @code{homerc} file was specified, this routine will silently return
and do nothing.  If the output file cannot be created or updated, a message
will be printed to @code{stderr} and the routine will return.


@node libopts-optionSaveState
@subsubsection optionSaveState
@findex optionSaveState

saves the option state to memory

@noindent
Usage:
@example
optionSaveState( pOpts );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOpts @tab @code{tOptions*}
@tab program options descriptor
@end multitable

This routine will allocate enough memory to save the current option
processing state.  If this routine has been called before, that memory
will be reused.  You may only save one copy of the option state.  This
routine may be called before optionProcess(3AO).  If you do call it
before the first call to optionProcess, then you may also change the
contents of argc/argv after you call optionRestore(3AO)

In fact, more strongly put: it is safest to only use this function
before having processed any options.  In particular, the saving and
restoring of stacked string arguments and hierarchical values is
disabled.  The values are not saved.

If it fails to allocate the memory,
it will print a message to stderr and exit.
Otherwise, it will always succeed.


@node libopts-optionUnloadNested
@subsubsection optionUnloadNested
@findex optionUnloadNested

Deallocate the memory for a nested value

@noindent
Usage:
@example
optionUnloadNested( pOptVal );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab pOptVal @tab @code{tOptionValue const *}
@tab the hierarchical value
@end multitable

A nested value needs to be deallocated.  The pointer passed in should
have been gotten from a call to @code{configFileLoad()} (See
@pxref{libopts-configFileLoad}).


@node libopts-optionVersion
@subsubsection optionVersion
@findex optionVersion

return the compiled AutoOpts version number

@noindent
Usage:
@example
char const* res = optionVersion();
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab returns @tab char const*
@tab the version string in constant memory
@end multitable

Returns the full version string compiled into the library.
The returned string cannot be modified.


@node libopts-pathfind
@subsubsection pathfind
@findex pathfind

fild a file in a list of directories

@noindent
Usage:
@example
char* res = pathfind( path, file, mode );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab path @tab @code{char const*}
@tab colon separated list of search directories

@item @tab file @tab @code{char const*}
@tab the name of the file to look for

@item @tab mode @tab @code{char const*}
@tab the mode bits that must be set to match
@item @tab returns @tab char*
@tab the path to the located file
@end multitable

pathfind looks for a a file with name "FILE" and "MODE" access
along colon delimited "PATH", and returns the full pathname as a
string, or NULL if not found.  If "FILE" contains a slash, then
it is treated as a relative or absolute path and "PATH" is ignored.

@strong{NOTE}: this function is compiled into @file{libopts} only if
it is not natively supplied.

The "MODE" argument is a string of option letters chosen from the
list below:
@example
Letter    Meaning
r         readable
w         writable
x         executable
f         normal file       (NOT IMPLEMENTED)
b         block special     (NOT IMPLEMENTED)
c         character special (NOT IMPLEMENTED)
d         directory         (NOT IMPLEMENTED)
p         FIFO (pipe)       (NOT IMPLEMENTED)
u         set user ID bit   (NOT IMPLEMENTED)
g         set group ID bit  (NOT IMPLEMENTED)
k         sticky bit        (NOT IMPLEMENTED)
s         size nonzero      (NOT IMPLEMENTED)
@end example

returns NULL if the file is not found.


@node libopts-strequate
@subsubsection strequate
@findex strequate

map a list of characters to the same value

@noindent
Usage:
@example
strequate( ch_list );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab ch_list @tab @code{char const*}
@tab characters to equivalence
@end multitable

Each character in the input string get mapped to the first character
in the string.
This function name is mapped to option_strequate so as to not conflict
with the POSIX name space.

none.


@node libopts-streqvcmp
@subsubsection streqvcmp
@findex streqvcmp

compare two strings with an equivalence mapping

@noindent
Usage:
@example
int res = streqvcmp( str1, str2 );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab str1 @tab @code{char const*}
@tab first string

@item @tab str2 @tab @code{char const*}
@tab second string
@item @tab returns @tab int
@tab the difference between two differing characters
@end multitable

Using a character mapping, two strings are compared for "equivalence".
Each input character is mapped to a comparison character and the
mapped-to characters are compared for the two NUL terminated input strings.
This function name is mapped to option_streqvcmp so as to not conflict
with the POSIX name space.

none checked.  Caller responsible for seg faults.


@node libopts-streqvmap
@subsubsection streqvmap
@findex streqvmap

Set the character mappings for the streqv functions

@noindent
Usage:
@example
streqvmap( From, To, ct );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab From @tab @code{char}
@tab Input character

@item @tab To @tab @code{char}
@tab Mapped-to character

@item @tab ct @tab @code{int}
@tab compare length
@end multitable

Set the character mapping.  If the count (@code{ct}) is set to zero, then
the map is cleared by setting all entries in the map to their index
value.  Otherwise, the "@code{From}" character is mapped to the "@code{To}"
character.  If @code{ct} is greater than 1, then @code{From} and @code{To}
are incremented and the process repeated until @code{ct} entries have been
set. For example,
@example
streqvmap('a', 'A', 26);
@end example
@noindent
will alter the mapping so that all English lower case letters
will map to upper case.

This function name is mapped to option_streqvmap so as to not conflict
with the POSIX name space.

none.


@node libopts-strneqvcmp
@subsubsection strneqvcmp
@findex strneqvcmp

compare two strings with an equivalence mapping

@noindent
Usage:
@example
int res = strneqvcmp( str1, str2, ct );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab str1 @tab @code{char const*}
@tab first string

@item @tab str2 @tab @code{char const*}
@tab second string

@item @tab ct @tab @code{int}
@tab compare length
@item @tab returns @tab int
@tab the difference between two differing characters
@end multitable

Using a character mapping, two strings are compared for "equivalence".
Each input character is mapped to a comparison character and the
mapped-to characters are compared for the two NUL terminated input strings.
The comparison is limited to @code{ct} bytes.
This function name is mapped to option_strneqvcmp so as to not conflict
with the POSIX name space.

none checked.  Caller responsible for seg faults.


@node libopts-strtransform
@subsubsection strtransform
@findex strtransform

convert a string into its mapped-to value

@noindent
Usage:
@example
strtransform( dest, src );
@end example
@noindent
Where the arguments are:
@multitable @columnfractions .05 .15 .20 .55
@item @tab Name @tab Type @tab Description
@item @tab ----- @tab ----- @tab -------------
@item @tab dest @tab @code{char*}
@tab output string

@item @tab src @tab @code{char const*}
@tab input string
@end multitable

Each character in the input string is mapped and the mapped-to
character is put into the output.
This function name is mapped to option_strtransform so as to not conflict
with the POSIX name space.

The source and destination may be the same.

none.