comparison 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;