This file documents  Version 26.0

libopts copyright (C) 1992-2005 Bruce Korb

libopts is free software.

You may redistribute it and/or modify it under the terms of the GNU
General Public License, as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later
version.

libopts is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with libopts.  If not, write to: 	The Free Software Foundation,
Inc., 	51 Franklin Street, Fifth Floor 	Boston, MA  02110-1301, USA.

libopts - GNU Option Parsing Library
************************************

This file documents libopts version 26.0.

This edition documents version 26.0, October 2005.

1 Introduction
**************

This manual is only partial documentation for the libopts library.
The complete documentation is incorporated into the documentation for
the AutoOpts option parsing suite incorporated into the AutoGen
documentation.  However, because this library can support stand alone
configuration file parsing, this document covers that part of the
interface.

The libopts library is also useful for projects that use the AutoOpts
option parser code generation, but do not wish to install the entire
AutoGen + Guile development suite on their production target
machines.  With this library pre-installed, AutoOpts client projects
can be installed and even compiled on destination machines.
(Assuming that the parsing code has been generated and distributed
with the project source.)

To use libopts as an configuration file parser, first include the
option header in your program:

     #include "autoopts/options.h"

Then find and examine the named values you are interested in:

     const tOptionValue* pOV   = configFileLoad( "hello.conf" );
     const tOptionValue* pGetV = optionGetValue( pOV, "greeting" );
     while (pGetV && (strcmp(pGetV->pzName, "greeting") == 0))
         pGetV = optionNextValue( pOV, pGetV );

Finally, free the config file data structures:

     optionUnloadNested( pOV );

2 libopts External Procedures
*****************************

These are the routines that libopts users may call directly from
their code.  These routines will parse and find configuration data in
configuration files.  There are several other routines that can be
called by AutoOpts client code, but you must have AutoGen installed
to use them and so they are documented in the AutoOpts section of the
AutoGen documentation.

2.1 configFileLoad
==================

parse a configuration file

Usage:
     const tOptionValue* res = configFileLoad( pzFile );
Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pzFile      `const char*'  the file to load
     returns     const          An allocated, compound value structure
                 tOptionValue*  

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
"`OPARG_TYPE_HIERARCHY'".  It may be used in calls to
`optionGetValue()', `optionNextValue()' and `optionUnloadNested()'.

If the file cannot be loaded or processed, `NULL' is returned and
ERRNO is set.  It may be set by a call to either `open(2)' `mmap(2)'
or other file system calls, or it may be:
   * `ENOENT' - the file was empty.

   * `EINVAL' - the file contents are invalid - not properly formed.

   * `ENOMEM' - not enough memory to allocate the needed structures.

2.2 optionGetValue
==================

get a specific value from a hierarcical list

Usage:
     const tOptionValue* res = optionGetValue( pOptValue, valueName );
Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOptValue   `const         a hierarchcal value
                 tOptionValue*' 
     valueName   `const char*'  name of value to get
     returns     const          a compound value structure
                 tOptionValue*  

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.

The returned result is NULL and errno is set:
   * `EINVAL' - the `pOptValue' does not point to a valid
     hierarchical option value.

   * `ENOENT' - no entry matched the given name.

2.3 optionNextValue
===================

get the next value from a hierarchical list

Usage:
     const tOptionValue* res = optionNextValue( pOptValue, pOldValue );
Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOptValue   `const         a hierarchcal list value
                 tOptionValue*' 
     pOldValue   `const         a value from this list
                 tOptionValue*' 
     returns     const          a compound value structure
                 tOptionValue*  

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 "ERRNO" will be set to
EINVAL.  The "POLDVALUE" must have been gotten from a prior call to
this routine or to "`opitonGetValue()'".

The returned result is NULL and errno is set:
   * `EINVAL' - the `pOptValue' does not point to a valid
     hierarchical option value or `pOldValue' does not point to a
     member of that option value.

   * `ENOENT' - the supplied `pOldValue' pointed to the last entry.

2.4 optionUnloadNested
======================

Deallocate the memory for a nested value

Usage:
     optionUnloadNested( pOptVal );
Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOptVal     `const         the hierarchical value
                 tOptionValue*' 

A nested value needs to be deallocated.  The pointer passed in should
have been gotten from a call to `configFileLoad()' (See *note
libopts-configFileLoad::).

3 Config file example
*********************

If for some reason it is difficult or unworkable to integrate
configuration file processing with command line option parsing, the
`libopts' (*note libopts procedures::) library can still be used to
process configuration files.  Below is a "Hello, World!" greeting
program that tries to load a configuration file `hello.conf' to see
if it should use an alternate greeting or to personalize the
salutation.

     #include <sys/types.h>
     #include <pwd.h>
     #include <string.h>
     #include <unistd.h>
     #include <autoopts/options.h>
     int main( int argc, char** argv ) {
       char* greeting = "Hello";
       char* greeted  = "World";
       const tOptionValue* pOV = configFileLoad( "hello.conf" );

       if (pOV != NULL) {
         const tOptionValue* pGetV = optionGetValue( pOV, "greeting" );

         if (  (pGetV != NULL)
            && (pGetV->valType == OPARG_TYPE_STRING))
           greeting = strdup( pGetV->v.strVal );

         pGetV = optionGetValue( pOV, "personalize" );
         if (pGetV != NULL) {
           struct passwd* pwe = getpwuid( getuid() );
           if (pwe != NULL)
             greeted = strdup( pwe->pw_gecos );
         }

         optionUnloadNested( pOV ); /* deallocate config data */
       }
       printf( "%s, %s!\n", greeting, greeted );
       return 0;
     }

With that text in a file named "hello.c", this short script:

     cc -o hello hello.c `autoopts-config cflags ldflags`
     ./hello
     echo 'greeting Buzz off' > hello.conf
     ./hello
     echo personalize > hello.conf
     ./hello

will produce the following output (for me):

     Hello, World!
     Buzz off, World!
     Hello, Bruce Korb!

Table of Contents
*****************

libopts - GNU Option Parsing Library
1 Introduction
2 libopts External Procedures
  2.1 configFileLoad
  2.2 optionGetValue
  2.3 optionNextValue
  2.4 optionUnloadNested
3 Config file example


