ucw/doc/opt.txt

   1 Option parser
   2 =============
   3
   4 Libucw contains a parser of command-line options, more versatile and
   5 easier to use than the usual `getopt()` and `getopt_long()`. It follows the
   6 traditional UNIX conventions of option syntax, but the options are defined in
   7 a declarative way, similar in spirit to our <<conf:,configuration file
   8 parser>>.
   9
  10 - <<example,Example>>
  11 - <<anatomy,Anatomy of options>>
  12 - <<opt_h,ucw/opt.h>>
  13   * <<classes,Option classes>>
  14   * <<opt_item,Option definitions>>
  15   * <<flags,Option flags>>
  16   * <<macros,Macros for declaration of options>>
  17   * <<positional,Positional arguments>>
  18   * <<func,Functions>>
  19   * <<conf,Cooperating with configuration file parser>>
  20   * <<hooks,Hooks>>
  21
  22 [[example]]
  23 Example
  24 -------
  25 Let us start with a simple example: a program with several options and
  26 one mandatory positional argument.
  27
  28   #include <ucw/lib.h>
  29   #include <ucw/opt.h>
  30
  31   int english;
  32   int sugar;
  33   int verbose;
  34   char *tea_name;
  35
  36   static struct opt_section options = {
  37     OPT_ITEMS {
  38       OPT_HELP("A simple tea boiling console."),
  39       OPT_HELP("Usage: teapot [options] name-of-the-tea"),
  40       OPT_HELP(""),
  41       OPT_HELP("Options:"),
  42       OPT_HELP_OPTION,
  43       OPT_BOOL('e', "english-style", english, 0, "\tEnglish style (with milk)"),
  44       OPT_INT('s', "sugar", sugar, OPT_REQUIRED_VALUE, "<spoons>\tAmount of sugar (in teaspoons)"),
  45       OPT_INC('v', "verbose", verbose, 0, "\tVerbose (the more -v, the more verbose)"),
  46       OPT_STRING(OPT_POSITIONAL(1), NULL, tea_name, OPT_REQUIRED, ""),
  47       OPT_END
  48     }
  49   };
  50
  51   int main(int argc, char **argv)
  52   {
  53     opt_parse(&options, argv+1);
  54     return 0;
  55   }
  56
  57 [[anatomy]]
  58 Anatomy of options
  59 ------------------
  60 Most options have the following properties:
  61
  62 - <<classes,Option class>> defining overall behavior of the option
  63 - Short name: one character. Set to 0 if the option has no short form.
  64   Alternatively, the short name can refer to a <<positional,positional argument>>.
  65 - Long name: an arbitrary string. Set to NULL if the option has no long form.
  66 - Variable, where the value of the option shall be stored, together with
  67   its <<conf:enum_cf_type,data type>>. The type is either one of the conventional
  68   types (`int`, `uns`, etc.), or a user-defined type providing its own parser
  69   function via <<conf:struct_cf_user_type,`cf_user_type`>>.
  70 - <<flags,Flags>> further specifying behavior of the option (whether it is mandatory,
  71   whether it carries a value, whether it can be set repeatedly, etc.).
  72 - Help text, from which the help displayed to the user is constructed.
  73 - Extra data specific for the particular class.
  74
  75 The help is generated in a three-column format. The first column contains the
  76 short names, then come the long names, and finally option descriptions.
  77 The help text starts in column 2 (where it can describe the option's argument);
  78 you can use the tab character to advance to the next column. When a newline
  79 character appears, the text continues on the next line in column 1.
  80
  81 [[opt_h]]
  82 ucw/opt.h
  83 ---------
  84
  85 This header file contains the public interface of the option parser module.
  86
  87 !!ucw/opt.h