utilities/gengetopt/cmdline.ggo

   1 # Copyright (C) 1999-2010  Free Software Foundation, Inc.
   2 #
   3 # This file is part of GNU gengetopt
   4 #
   5 # GNU gengetopt is free software; you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 2, or (at your option)
   8 # any later version.
   9 #
  10 # GNU gengetopt is distributed in the hope that it will be useful, but
  11 # WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
  13 # Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License along
  16 # with gengetopt; see the file COPYING. If not, write to the Free Software
  17 # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  18
  19
  20 # Specification file format:
  21 #
  22 # This file consist in lines of sentences with the following format:
  23 #
  24 #         package <packname>
  25 #         version <version>
  26 #         purpose <string>
  27 #         option <long> <short> <desc> <argtype> <required>
  28 #         option <long> <short> <desc> flag      <onoff>
  29 #         option <long> <short> <desc> <required>
  30 #         ... # ...
  31 #
  32 # Where:
  33 #
  34 # <packname> = Double quoted string.
  35 # <version>  = Double quoted string.
  36 # <purpose>  = What the program does
  37 #              Double quoted string (even on more than one line)
  38 # <long>     = Double quoted string with upper and lower case chars, digits,
  39 #              '-' and '.'.  No spaces allowed.
  40 # <short>    = A single upper or lower case char, or a digit.
  41 # <desc>     = String with upper and lower case chars, digits, '-', '.' and
  42 #              spaces.
  43 # <argtype>  = string, int, short, long, float, double, longdouble or longlong.
  44 # <required> = required or optional.
  45 # <onoff>    = on or off.
  46 # Comments begins with '#' in any place of the line and ends in the
  47 # end of line.
  48 # The third form of option is used if the option does not take an argument;
  49 # it must not be required.
  50
  51
  52 # Name of our program
  53 #package "gengetopt"       # we don't use it: we're using automake
  54 # Version of our program
  55 #version "1.0.1"           # we don't use it: we're using automake
  56
  57 purpose "This program generates a C function that uses getopt_long function
  58 to parse the command line options, validate them and fill a struct."
  59
  60 # options that will be added to command line options of gengetopt
  61 args "--no-handle-version --no-handle-help --no-handle-error --string-parser"
  62
  63 # Options
  64
  65 section "Main options"
  66
  67 text ""
  68
  69 option  "input"         i "input file (default std input)"  string typestr="filename"     optional
  70 option  "func-name"     f "name of generated function" string typestr="name"  default="cmdline_parser"   optional
  71 option  "arg-struct-name" a "name of generated args info struct" string typestr="name"  default="gengetopt_args_info"   optional
  72 option  "file-name"     F "name of generated file"  string typestr="name"  default="cmdline"     optional
  73 option  "output-dir"     - "output directory"  string typestr="path"  optional
  74         details="\nif this option is not specified, the \
  75 files are generated in the current directory.\n"
  76 option  "header-output-dir"     - "header output directory"  string typestr="path" optional
  77 option  "src-output-dir"     - "source output directory"  string typestr="path" optional
  78 option  "c-extension"   c "extension of c file" string typestr="ext" default="c" optional
  79 option  "header-extension"   H "extension of header file" string typestr="ext" default="h" optional
  80 option  "long-help"     l "long usage line in help" optional
  81         details="\nThe usage line will print all the options, e.g.,
  82
  83 sample1 -iINT|--int-opt=INT [-h|--help]\n"
  84 option  "default-optional"     - "by default, an option is considered optional if not specified otherwise" optional
  85 option  "unamed-opts"   u "accept options without names (e.g., file names)" string default="FILES" optional argoptional
  86
  87 text "\nThe parser generated is thought to be used to parse the command line arguments. "
  88 text "However, you can also generate parsers for configuration files, or strings "
  89 text "that contain the arguments to parse, by using the following two options.\n"
  90
  91 option  "conf-parser" C "generate a config file parser" optional
  92 option  "string-parser" S "generate a string parser (the string contains the command line)" optional
  93
  94 text ""
  95
  96 section "Additional options"
  97
  98 option  "include-getopt" G "adds the code for getopt_long in the generated C file" optional
  99
 100 option  "no-handle-help"   n "do not handle --help|-h automatically" optional
 101         details="\nIf --no-handle-help is specified, the command line option \
 102 --help|-h will not be handled automatically, so the programmer will be able \
 103 to print some \
 104 other information; then the function for printing the standard help \
 105 output can be used; this function is called \
 106 <parser-name>_print_help.\n\nNotice \
 107 that, although the programmer can handle --help|-h manually, the \
 108 parser will return after finding such option: the other command \
 109 line options, if any, will be ignored.  In case you want to have full \
 110 control on --help|-h, you should use --ho-help.\n"
 111
 112 option  "no-help"   - "do not add --help|-h automatically" optional
 113         details="\nWith this option you can disable the \
 114 automatic addition of options --help|-h. The programmer \
 115 will then be able to add this option in \
 116 the input file and handle it as he sees fit.  Notice that \
 117 --no-help will also disable the automatic options \
 118 --detailed-help and --full-help.
 119
 120 The programmer can still \
 121 define options with short character h as he wants, \
 122 but he cannot define options help, unless he \
 123 specifies --no-help \
 124 (otherwise an error will be printed).\n"
 125
 126 option  "no-handle-version"  N  "do not handle --version|-V automatically" optional
 127 option  "no-version"  -  "do not add --version|-V automatically" optional
 128         details="\nSee above the details about \
 129 --no-handle-help and --no-help, respectively.\n"
 130
 131 option  "no-handle-error" e "do not exit on errors" optional
 132         details="\nWith this option, if the generated parser encounters an error \
 133 (e.g., an unknown option) it does not make the main program exit; instead, the parser \
 134 function returns a value different 0, and the main program can print a help message.\n"
 135
 136 option  "show-required"   - "in the output of help will specify which options are mandatory, \
 137 by using the optional passed string" string default="(mandatory)" optional argoptional
 138
 139 option  "gen-version" g "put gengetopt version in the generated file" flag on
 140 option  "set-package" - "set the package name (override package defined in the .ggo file)" string optional
 141 option  "set-version" - "set the version number (override version defined in the .ggo file)" string optional
 142 option  "show-help" - "show the output of --help instead of generating code" optional
 143 option  "show-full-help" - "show the output of --full-help (i.e., including hidden options) instead of generating code" optional
 144 option  "show-detailed-help" - "show the output of --detailed-help (i.e., including details and hidden options) instead of generating code" optional
 145 option  "show-version" - "show the output of --version instead of generating code" optional
 146
 147 text "\nPlease refer to the info manual for further explanations."