packages icon



 argtable.h(3)                    Argtable                     argtable.h(3)
                                 21 Dec 2001



 NAME
      argtable.h -

 SYNOPSIS
      #include <stdio.h>

    Data Structures
      struct arg_rec

    Defines
      #define ARGTABLE_VERSION  1.3

    Enumerations
      enum arg_type { arg_int = 0, arg_dbl, arg_str, arg_bool, arg_lit }

    Functions
      int arg_scanargv (int argc, char **argv, arg_rec *argtable, int n, char
          *CmdLine, char *ErrMsg, char *ErrMark)
          Parse the command line as per a given argument table.
      int arg_scanstr (char *str, arg_rec *argtable, int n, char *ErrMsg,
          char *ErrMark)
          Parse a string as per a given argument table.
      const char* arg_syntax (const arg_rec *argtable, int n)
          Generates a 'usage' syntax string from an argument table.
      const char* arg_glossary (const arg_rec *argtable, int n, const char
          *prefix)
          Generate a glossary string from an argument table.
      void arg_catargs (int argc, char **argv, char *str)
          Concatenate all argv[] arguments into a single string.
      arg_rec arg_record (char *tagstr, char *argname, arg_type argtype, void
          *valueptr, char *defaultstr, char *argdescrip)
          Builds and returns an argument table record.
      void arg_dump (FILE *fp, const arg_rec *argtable, int n)
          Print the contents of an argument table.

    Variables
      const char* arg_typestr []

 DEFINE DOCUMENTATION
    #define ARGTABLE_VERSION 1.3
 ENUMERATION TYPE DOCUMENTATION
    enum arg_type
      arg_type enums are used in the argument table to define the data type
      of a command line argument.

      Enumeration values:

      arg_int
           Integer value.





                                    - 1 -      Formatted:  December 12, 2019






 argtable.h(3)                    Argtable                     argtable.h(3)
                                 21 Dec 2001



      arg_dbl
           Double value.

      arg_str
           Ascii string; may be quoted or un-quoted.

      arg_bool
           Boolean; accepts the keywords yes, no, true, false, on , or off
           and converts them into an integer value of 0 (negative) or 1
           (affirmative) accordingly.

      arg_lit
           Literal; returns 1 if a given literal string was present on the
           command line otherwise returns the default value.

 FUNCTION DOCUMENTATION
    int arg_scanargv (int argc, char **
       Attempts to resolve the argv[] command line arguments (ignoring
      argv[0]) with the specifications given in the argument table. The
      values scanned from the command line are written directly into the
      program variables nominated by each argument table entry.

      During the process, a copy of the command line is written (as a single
      line of space separated arguments) into the user-supplied string at
      *CmdLine in case it is needed in future for error reporting.

      Should there be any conflict between the command line arguments and
      the argument table specifications, an error message and corresponding
      error marker are written into the user-supplied strings at *ErrMsg and
      *ErrMark respectively, after which the function returns zero. The
      error marker string is used to store a string of tilde characters
      formated in such a way that the tildes underscore the exact location
      of the error in *CmdLine when the strings are aligned one above the
      other. This can be useful for including in on-line error messages to
      help the user quickly pinpoint the cause of the error.

      If, on the other hand, all arguments were resolved successfully then
      *ErrMsg and *ErrMark are set to empty strings and the function returns
      1. Either way, CmdLine, ErrMsg, or ErrMark can be safely ignored by
      passing them as NULL.

      Returns:
          1 upon success, 0 upon failure.

      Parameters:

      argc number of entries in argv[].

      argv command line arguments.





                                    - 2 -      Formatted:  December 12, 2019






 argtable.h(3)                    Argtable                     argtable.h(3)
                                 21 Dec 2001



      argtable
           pointer to the argument table.

      n    number of entries in argtable[].

      CmdLine
           pointer to storage for command line (may be NULL).

      ErrMsg
           pointer to storage for error message (may be NULL).

      ErrMark
           pointer to storage for error marker (may be NULL).

    int arg_scanstr (char * str, arg_rec
       This function is much like arg_scanargv() except that is scans the
      arguments from the string at *str rather than from argv[]. The string
      is expected to contain a single line, space separated list of
      arguments, like that generated by arg_catargs().

      In a departure from arg_scanargv, this function erases the scanned
      arguments from *str by overwriting them with spaces once they have
      been successfully scanned. Furthermore, this function does not throw
      an error if there are still arguments remaining in *str after the
      argtable has been fully processed. Thus, complicated argument usages
      can be achieved by invoking this function multiple times on the same
      command line string, each time applying a different argument table
      until the arguments have been exhausted, or an error has been
      detected.

      Returns:
          1 upon success, 0 upon failure.

      Parameters:

      str  pointer to command line string.

      argtable
           pointer to the argument table.

      n    number of array elements in argtable[].

      ErrMsg
           pointer to storage for error message (may be NULL).

      ErrMark
           pointer to storage for error marker (may be NULL).

    const char * arg_syntax (const arg_rec
       Builds a syntactical description of the allowable command line
      arguments specified by the 'argtable' array. The resulting string is



                                    - 3 -      Formatted:  December 12, 2019






 argtable.h(3)                    Argtable                     argtable.h(3)
                                 21 Dec 2001



      stored in static data within the local scope of this function. Its
      contents are overwritten by subsequent calls.

      The syntactical description is generated as a single line of space
      separated argument descriptors, each comprising of the argument's tag
      string and name string concatenated together. For example,

      "myprog x y [z] [-r <double>] [-o <outfile>] [-verbose] <infile>
      [debug=<on/off>]"

      If an argument is optional (has a non-NULL default value) then its
      descriptor is enclosed in square brackets. NULL name strings are
      substituted with the argument's data type enclosed in angled brackets,
      as in <int>, <double>, or <string>. If both the tag and the name are
      empty strings ("") then the argument is omitted from the description
      altogether. This allows the suppression of individual arguments that
      you do not want to appear.

      Returns:
          a pointer to the internal string.

      Parameters:

      argtable
           pointer to the argument table

      n    number of array elements in argtable[]

    const char * arg_glossary (const arg_rec
       Returns a pointer to an internal 'glossary' string which contains a
      multi-line description of each of the argument table entres that have
      a non-NULL <description> field. The contents of the glossary string
      remain unaltered up until the next invocation of this function. Each
      line of the glossary string is formatted as

      "<prefix><tag><name><description>"

      The 'prefix' string is useful for adding indenting spaces before each
      line in the description to improve the look of the glossary string, or
      it can be given as NULL in which case it is ignored.

      Any NULL <tag> fields in the argument table will appear in the
      glosssary as empty strings.

      Any NULL <name> fields will be substituted by a description of that
      argument's data type, enclosed in angled brackets, as in <int> and
      <double>. A name can effectively be suppressed from the glossary by
      defining it as an empty string in the argument table.

      Returns:
          a pointer to the internal string.



                                    - 4 -      Formatted:  December 12, 2019






 argtable.h(3)                    Argtable                     argtable.h(3)
                                 21 Dec 2001



      Parameters:

      argtable
           pointer to the argument table

      n    number of array elements in argtable[]

      prefix
           a string to be prefixed to each line of the output

    void arg_catargs (int argc, char **
       Concatenates all of the arguments in the argv[] array and writes the
      result into *str as a single line, space separated string.

      Any argv[] entries that contain whitespace are automatically
      encapsulated by single quotes prior to the concatenation to preserve
      their word grouping. A trailing space is always appended to the
      resulting string as a safety precaution in lieu of scanning for string
      literals that expect trailing space. It is assumed that *str is big
      enough to store the result.

      Parameters:

      argc number of arguments in argv[]

      argv command line arguments

      str  pointer to destination string

    arg_rec arg_record (char * tagstr, char
       Returns an arg_rec structure containing the values passed to the
      function. It is useful for building argument tables dynamically.

      Parameters:

      tagstr
           argument tag string

      argname
           argument name string

      argtype
           argument data type

      valueptr
           pointer to user-supplied storage location

      defaultstr
           default argument value, as a string





                                    - 5 -      Formatted:  December 12, 2019






 argtable.h(3)                    Argtable                     argtable.h(3)
                                 21 Dec 2001



      argdescrip
           argument description string

    void arg_dump (FILE * fp, const
       The contents of the argument table, and the user-supplied variables
      it references, are printed to the stream 'fp'. This can be useful for
      debugging argument tables.

      Parameters:

      fp   output stream

      argtable
           pointer to the argument table

      n    number of array elements in argtable[]

 VARIABLE DOCUMENTATION
    const char * arg_typestr
      A fixed array of strings that are used when arguments are given NULL
      names. The array is indexed by arg_type, with each name describing the
      corresponding data type.

       arg_str[arg_int]  = "<int>";
       arg_str[arg_dbl]  = "<double>";
       arg_str[arg_str]  = "<string>";
       arg_str[arg_bool] = "<bool>";
       arg_str[arg_lit]  = "";


 AUTHOR
      Generated automatically by Doxygen for Argtable from the source






















                                    - 6 -      Formatted:  December 12, 2019