annotate glib/options.h @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

/*
    Copyright (c) Applied Psychology Unit, Medical Research Council. 1988, 1989
    ===========================================================================

    Permission to use, copy, modify, and distribute this software without fee 
    is hereby granted for research purposes, provided that this copyright 
    notice appears in all copies and in all supporting documentation, and that 
    the software is not redistributed for any fee (except for a nominal shipping 
    charge). Anyone wanting to incorporate all or part of this software in a
    commercial product must obtain a license from the Medical Research Council.

    The MRC makes no representations about the suitability of this 
    software for any purpose.  It is provided "as is" without express or implied 
    warranty.
 
    THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
    ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE
    A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 
    DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN 
    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/

/* ---------------------------------------------------------------------------------

                                            *
   The Leanest Resource Manager in the West
   -----------------------------------------
                                           

                                   (*) is no more! The gallant <getopts.[ch]> has
                                       given way to a new daring duo! Henceforth,
                                       read "options" for "getopts". The new features
                                       include classified options and user-supplied
                                       "Help" information. See <options.c> for edit
                                       history.

   Copyright (c), 1989  The Medical Research Council of the United Kingdom.

   Author  :    Paul Manson
   Written :    March 1st 1989  [See options.c for modifications history]

   Options may be supplied as defaults (actually in the code), as command line
   arguments, and in an option file. The default arguments may be overridden by
   the option-file contents, which may be overridden in turn by command line
   arguments. The syntax of a option file is as follows:

   <option file> ::= { <option line> <linefeed> }

   <option line> ::= <option specification> | <comment line> | <blank line>

   <option specification> ::= <name> "=" <option value> [ <comment line> ]

   <option value> ::= <contiguous character string> | 
                        """ <any printable chars except """> """

   <comment line> ::= "#" <absolutely anything>

   where spaces are not considered significant except that the <value> ought to
   be a quoted string if it contains spaces. On Unix, the OPTIONSPATH path in the
   users' environment is used to search for a option file, but if this path is
   absent, the current working directory will still be searched. On an IBM PC, the
   the directory in which the application program was found is searched for the
   option file. [In the future, this will be modified so that the current directory
   is searched first].

   Command line arguments may take any of the following forms;

   1.     -name
   
   2.     -name=value

   3.     name=value

   where it should be noted that spaces ARE significant, and that the first of these
   formats effects a set/toggle operation on the named option, by setting its 
   value to some system-defined default value (at present, this is "1").

   If a user specifies -help on the command line then getopts uses the "help" option
   (if there is one) to print a message detailing the options available to the
   user. Specifying -update on the command line causes a new version of the currently
   read option file to be written, incorporating any alterations which have been
   effected by previous command line options.

   Abbreviations are permitted for options, but it must be noted that only
   unambiguous option specifications will have any effect (ambiguous specifications
   are rejected with a warning message). If a option specification uses a name which
   is an abbreviation for two options, but matches one of these options EXACTLY,
   this is not considered to be ambiguous (the exact match being taken as the intended
   one). Abbreviations are NOT permitted in option headers (see readopts and writeopts
   below).

   --------------------------------------------------------------------------------- */

#include <stdio.h>

#define InputOption (1)
#define OutputOption (2)
#define InOutOption (0)
#define SilentOption (3)

typedef struct {
  char *name          ;    /* The name of the option,                      */
  char *defaultValue  ;    /* its default value,                             */
  char **value        ;    /* The place where its current value is stored    */
  char *comment       ;    /* Something to print when the user types "-help" */
  short classification;    /* What form of option it is.                     */
} Option, *OptionPtr;

/* ---------------------------------------------------------------------------------

   This structure may be used to build a database of option handles, as indicated
   in the following sample program;

   static char *samplerate, *inputfile;

   static Option res[] = {
        { "Sample Rate", "10000.0",    &samplerate, "The Rate of Sampling", InOutOption },
        { "Input File ", "input.data", &inputfile , "A File to Read From ", InOutOption }};

   which declares two options, <samplerate> and <inputfile>, and gives them 
   default values. These defaults may later be overwritten by the function
   getopts(), either from the option file or from the command line.

   --------------------------------------------------------------------------------- */


#define NumOptions(res) (sizeof(res) / ((sizeof(char *) + (sizeof(char **)))))

/* ---------------------------------------------------------------------------------

   Provides a macro for determining how many options are present in a res[]
   declaration such as that shown above. eg. NumOptions(res) == 2. This macro
   should be used on calls to getopts, etc.

   --------------------------------------------------------------------------------- */


extern void getnopts(); /* (options, numOptions, &argc, &argv) */

/* ---------------------------------------------------------------------------------

   This function should be called before an application program examines its arguments
   (this is because it butchers them!). First of all, it reads the appropriate option
   file and interprets the options specified therein (the name of the option file
   is given by the name of the application, ie. argv[0]). After redefining the options
   specified by the option file, it examines the arguments (given by argc and argv) 
   and scans them for additional options. Finally, it resets argc and argv for the
   remainder of the program (if any) to deal with. NOTE THAT argc AND argv _MUST_ BE
   PASSED AS POINTERS TO THIS ROUTINE!.

   --------------------------------------------------------------------------------- */


extern void getopts();          /* (options, &argc, &argv) */
extern void cmd_line_opts() ;   /* (options, &argc, &argv) */

/* ---------------------------------------------------------------------------------

   Some fussy people don't like to count their own option lists, so this routine
   does the necessary dirty-work before passing the result(s) to getnopts(). You MUST
   remember to null-terminate your options array; ie.

   static char *samplerate, *inputfile;

   static Option res[] = {
        { "Sample Rate", "10000.0",    &samplerate, "The Rate of Sampling", InOutOption },
        { "Input File ", "input.data", &inputfile , "A File to Read From ", InOutOption },
	NULL};

   and upon your own head (or lesser, more sensitive, appendages) be it if you forget
   to do this!

   --------------------------------------------------------------------------------- */


extern void readnopts(); /* (options, numOptions, filePointer) */
extern void readopts() ; /* (options, filePointer)               */

/* ---------------------------------------------------------------------------------

   Try to read a options header from the specified <file>, with reference to the
   array of <options>. The header layout is specified below (see writenopts), and
   the operation, if successful, will leave the filePointer set to the first byte
   after the (padded) option header. Unsuccessful readnopts will cause en error
   message and will terminate the program. If there does not appear to be a header
   on the file at all, readnopts does nothing. The routine readopts counts the
   options in <options> for you, and you MUST null-terminate your options
   array if you use this routine. 

   WARNING: readopts and readnopts do NOT require that a option name found in a 
   header be an actual option of the calling program, and will IGNORE any such 
   option assignments.

   --------------------------------------------------------------------------------- */


extern void writenopts(); /* (options, numOptions, filePointer) */
extern void writeopts() ; /* (options, filePointer)               */

/* ---------------------------------------------------------------------------------

   Write the current option settings as specified by <options> into the 
   specified file. The options are written as an ASCII header, in the same form
   as is required by getopts (and consequently, readopts). This header will begin
   with some suitable comment (line beginning with a # character) to indicate that
   it is in fact a option header. Following this comment will be information 
   concerning the size of the option file header. This information is used to tell
   subsequent calls to readnopts the length of the option header; this header will 
   actually be padded to a block boundary to avoid disturbing the following data
   unnecessarily. As might be expected, writeopts is a counting version of writenopts;
   remember to NULL-terminate your option array if you use this routine.
   
   --------------------------------------------------------------------------------- */


extern FILE *fileopts();   /* (options, &argc, &argv ) */

/* ---------------------------------------------------------------------------------

   A packaging function which performs getopts(options, &argc, &argv), then fopens
   the next argument and does readopts on it. It returns a file handle to this file
   with the header removed (ie. it points at the first byte of data).
   
   --------------------------------------------------------------------------------- */

extern FILE *optoutput(); /* (String) */

/* ---------------------------------------------------------------------------------

   Simply open a file for output (depending on the value of String)... a NULL string
   returns NULL, the default String (at present this is "1") sends to stdout, and
   anything else is taken as being a path name for a file to create for writing.
   
   --------------------------------------------------------------------------------- */

extern void helpnopts(); /* (options, numOptions, program_name) */
extern void helpopts(); /* (options, program_name) */

/* ---------------------------------------------------------------------------------

   Allows application programs to invoke the online help (ie. usage) information at
   any point. The helpopts call counts the number of options for you, BUT ONLY IF
   you remember to NULL-TERMINATE IT!
      
   --------------------------------------------------------------------------------- */

typedef void helpRoutine( /* (options, numOptions, program_name) */ );

extern helpRoutine *helpOptsHandler(); /* (helpRoutine) */

/* ---------------------------------------------------------------------------------

   Allows an application program to install its very own helpHandler routine to
   override the default help-message handler. The behaviour of such a routine is
   implicitly trusted by <options>, so you should only install your own handler 
   when you are quite familiar with the Options structure format. This routine
   returns the address of the previously installed handler (which is initially the
   default handler) so that this may be reinstated at a later point.

   ---------------------------------------------------------------------------------- */


#define isON(_STR) (!isOFF(_STR))

extern int isOFF();
     /* char *optionStr; */

/* ---------------------------------------------------------------------------------

   A convenience call which returns TRUE (1) if the optionStr is what options thinks
   of as "ON", "YES", "TRUE", or "1".... This merely allows us to hide the actual
   implementation of "ON" from the application programs.
      
   --------------------------------------------------------------------------------- */

extern int isNULL();
     /* char *optionStr; */

/* ---------------------------------------------------------------------------------

   A convenience call which returns TRUE (1) if the optionStr is what options thinks
   of as "NULL", "NONE", nothing, zip, etc... This merely allows us to hide the actual
   implementation of "NULL" from the application programs.
      
   --------------------------------------------------------------------------------- */

#define ON_OPTION "on"
#define OFF_OPTION "off"
#define NULL_OPTION "none"

/* ---------------------------------------------------------------------------------

  NOTE: The above definitions allow the expression of constant option settings
  via static option[] arrays... they do so at the risk of allowing some klutz
  to alter them... the only solution to this problem (other than forcing
  application programmers to read .h files) is to return copies of these
  strings via procedure calls, and this precludes static initialisation.
      
   --------------------------------------------------------------------------------- */

extern int OptionStringsEqual();
     /* char *str1, *str2; */

/* ---------------------------------------------------------------------------------

   A routine to reduce the load on the application programmer by providing a simple
   boolean check for string equality WITHOUT CASE SIGNIFICANCE. This allows applications
   to leave case and typing problems within "options" reliably.
      
   --------------------------------------------------------------------------------- */

extern char *versionstr;