96
96
* Basic Usage:: How to run Gengetopt; syntax of .ggo files
97
97
* Invoking gengetopt:: gengetopt command line options
98
98
* Terminology:: Definitions of options, values, and so forth.
99
* Group options:: Mutual exclusive options
99
* Options with enumerated values:: Options accepting only a list of values
100
* Group options:: Groups of mutual exclusive options
101
* Mode options:: Mutual exclusive group of options
100
102
* Parser function additional parameters::
101
103
* Configuration files:: Parsing a configuration file
102
104
* Multiple Options:: Multiple options
424
428
The short option, a single upper or lower case char, or a digit. If
425
429
a @code{-} is specified, then no short option is considered for the long
426
430
option (thus long options with no associated short options are allowed).
431
Since version 2.22 you can also specify @code{?} as the short option.
433
437
This description will be printed during the output of
434
438
@code{--help}. Wrapping will be automatically performed.
442
@cindex @code{--detailed-help}
444
This is an extended description string for the option that will be
445
printed (after the option) during the output of
446
@code{--detailed-help}@footnote{Since version 2.22.}, which will be
447
automatically generated. Thus, these further details will NOT be
448
printed with @code{--help}. Wrapping will be automatically performed.
439
454
@code{string}, @code{int}, @code{short}, @code{long}, @code{float},
440
@code{double}, @code{longdouble} or @code{longlong}. If no type is
441
specified the option does not accept an argument.
455
@code{double}, @code{longdouble} or @code{longlong}. If the option is
456
an enumerated one (see @ref{Options with enumerated values}) the type
457
can also be @code{enum}. If no type is specified the option does not
509
529
@code{required} flag. See @ref{Multiple Options}.
512
533
@cindex @code{--full-help}
534
@cindex @code{--detailed-help}
515
@anchor{hidden}If an option is ``hidden'' it will not
516
appear in the output of @code{--help} but it can still be specified at
517
command line@footnote{Since version 2.15.}. In case hidden options
518
are used, the command line option @code{--full-help} will also be
519
generated. This will print also the hidden options@footnote{Since
539
If an option is ``hidden'' it will not appear in the
540
output of @code{--help} but it can still be specified at command
541
line@footnote{Since version 2.15.}. In case hidden options are used,
542
the command line option @code{--full-help} will also be generated. This
543
will print also the hidden options@footnote{Since version 2.16.}. If
544
there's an option with @code{details}, then also
545
@code{--detailed-help}@footnote{Since version 2.22.} will be
546
automatically generated; if one then specifies @code{--detailed-help}
547
also hidden options will be printed (besides the details for options).
583
610
@cindex @code{-h,--help}
584
611
@cindex @code{-V,--version}
585
@anchor{addedoptions}
586
Notice that the options @code{-h,--help} and @code{-V,--version} are
587
added automatically; however, if you specify an option yourself that has
588
@code{h} as short form or @code{help} as long form, then
589
@code{-h,--help} is not added (and you have to handle the help option
590
manually). The same holds for @code{-V,--version}.
612
@anchor{addedoptions} Notice that the options @code{-h,--help} and
613
@code{-V,--version} are added automatically; however, if you specify an
614
option yourself that has @code{h} as short form, then only @code{--help}
615
is added@footnote{Before version 2.22 neither @code{--help} was added
616
and you had to handle the help option manually}. The same holds for
592
619
@cindex @code{--full-help}
593
620
In case hidden options are used, @xref{hidden,,Hidden options}, the
594
621
command line option @code{--full-help} will also be generated. This
595
622
will print also the hidden options@footnote{Since version 2.16.}.
624
@cindex @code{--detailed-help}
625
If there's at least one option with @code{details}, the command line
626
option @code{--detailed-help} will also be generated. This will print
627
also the details for options and hidden options@footnote{Since version
598
631
Options can be part of sections, that provide a more meaningful
599
632
descriptions of the options. A @emph{section} can be defined with the
633
666
You can also specify the list of @code{values} that can be passed to an
634
option (in that case the option has type @code{string}). If a value
635
that is not in the list is passed, an error is raised. You can think of
636
such options as @emph{enumerated} options. It is not necessary to pass
637
the complete value at the command line option: a non ambiguous prefix
638
will do. For instance, if the accepted values are
639
@code{"foo","bar","foobar"}, then you can pass at the command line the
640
value @code{"b"} and the value @code{"bar"} will be selected, or the
641
value @code{"foob"} and the value @code{"foobar"} will be selected;
642
instead, passing the value @code{"fo"} will raise an ambiguity error.
667
option (if the type is not specified, the option has type
668
@code{string}). More on this feature can be found in @ref{Options with
669
enumerated values}. If a value that is not in the list is passed, an
670
error is raised. You can think of such options as @emph{enumerated}
671
options. It is not necessary to pass the complete value at the command
672
line option: a non ambiguous prefix will do. For instance, if the
673
accepted values are @code{"foo","bar","foobar"}, then you can pass at
674
the command line the value @code{"b"} and the value @code{"bar"} will be
675
selected, or the value @code{"foob"} and the value @code{"foobar"} will
676
be selected; instead, passing the value @code{"fo"} will raise an
644
679
Here's an example of such a file (the file is called @file{sample1.ggo})
646
681
@include sample1.ggo.texinfo
649
The simplest way to use gengetopt is to pass this file as the standard input, i.e.:
683
The simplest way to use gengetopt is to pass this file as the standard
652
687
gengetopt < sample1.ggo
673
708
@include cmdline1.h.texinfo
675
The @code{<option>_given} field is set to a value different from 0 when
676
an argument for @code{<option>} has been specified. If the option
677
accepts an argument and it is not of @code{flag} type The
678
@code{<option>_arg} field is set to the value passed at the command
679
line. The @code{<option>_arg} field has the corresponding C type
680
specified in the file passed to gengetopt.
710
The @code{<option>_given} field is set to 1 when an argument for
711
@code{<option>} has been specified (otherwise it is 0)@footnote{Since
712
version 2.22 this field is of type @code{unsigned int} instead of
713
@code{int} for uniformity with multiple options.}. This fields also
714
counts the times a multiple option is specified (see @ref{Multiple
715
Options}). If the option accepts an argument and it is not of
716
@code{flag} type The @code{<option>_arg} field is set to the value
717
passed at the command line. The @code{<option>_arg} field has the
718
corresponding C type specified in the file passed to gengetopt.
682
720
Notice that if an option has a default value, then the corresponding
683
721
@code{<option>_arg} will be initialized with that value but the
719
757
printed when @code{--help} command line is given (this array is
720
758
terminated by a null string element). If hidden options are used also
721
759
the @code{cmdline_parser_full_help} array is available (containing also
722
help strings concerning hidden options). All these strings can be used
723
by the programmer to build a customized help output@footnote{These
724
strings and the @code{<option>_help} were introduced in the release
760
help strings concerning hidden options). If at least one option has
761
@code{details}, then the @code{cmdline_parser_detailed_help} array is
762
available (containing also help strings concerning hidden options and
763
details for options). All these strings can be used by the programmer
764
to build a customized help output@footnote{These strings and the
765
@code{<option>_help} were introduced in the release 2.17.}.
727
767
Even if @code{<option>_given} is 0, the corresponding
728
768
@code{<option>_arg} is set to default value (if one has been specified
756
796
files (@ref{Configuration files}). Notice that if an option has a
757
797
default value, this option will be saved into the file only if it was
758
798
passed explicitly at command line (or read from a configuration file),
759
i.e., default values will not be saved into the file.
799
i.e., default values will not be saved into the file. Alternatively,
800
you can use @code{cmdline_parser_dump}@footnote{Introduced in version
801
2.22, thanks to Papp Gyozo.} that takes as the first parameter an
802
already open stream (@code{FILE *}) instead of a file name.
761
804
And here's how these functions can be used inside the main program:
862
907
an hidden option (@xref{hidden,,Hidden options}.) it is not printed;
863
908
@cindex @code{--full-help}
864
909
if you wanted that to be printed, you should use @code{--full-help}.
911
The option @code{--func-opt} has also the @code{details}, but they are
912
not printed with @code{--help}.
866
914
Finally, notice how the @code{text} strings are printed in the help
867
915
output (and the empty line after the ``more involved options'' section
868
916
achieved with an empty @code{text} string).
918
@cindex @code{-h,--detailed-help}
919
Instead, here is the output of @code{--detailed-help} of the parser
920
generated from @file{sample1.ggo}. You may want to compare this output
921
with the one produced by @code{--help} (@xref{helpoutput,,Output of
922
@code{--help}}.); in particular, you may notice that the hidden option
923
@code{--secret} is actually printed and the details of @code{--func-opt}
927
@include sample1_2.output.texinfo
870
930
If you're curious you may want to take a look at the generated C file
871
931
@file{cmdline1.c}.
932
992
(version) response can be used; this function is called
933
993
@code{<parser-name>_print_help} (@code{<parser-name>_print_version}),
934
994
where @code{<parser-name>} is the name specified with @code{--func-name}
935
or the default, @code{cmdline_parser}.
995
or the default, @code{cmdline_parser}. In case hidden options are used,
996
@xref{hidden,,Hidden options}, also the function
997
@code{<parser-name>_print_full_help} will be generated; if
998
@code{details} are used for at least one option, then also the function
999
@code{<parser-name>_print_detailed_help} will be generated. Notice
1000
that, although the programmer can handle these options manually, the
1001
parser will return after finding one of these options: the other command
1002
line options, if any, will be ignored. In case you want to have full
1003
control on @code{--help|-h}, @code{--version|-V}, you should use the
1008
@cindex @code{--no-help}
1009
@cindex @code{--no-version}
1010
With these options@footnote{Since version 2.22.} you can disable the
1011
automatic addition of options @code{--help|-h} and @code{--version|-V},
1012
respectively. The programmer will then be able to add these options in
1013
the input file and handle them as he sees fit. Notice that
1014
@code{--no-help} will also disable the automatic options
1015
@code{--detailed-help} and @code{--full-help}. The programmer can still
1016
define options with short character @code{h} and @code{V} as he wants,
1017
but he cannot define options @code{help} and @code{version}, unless he
1018
specifies @code{--no-help} and @code{--no-version}, respectively
1019
(otherwise an error will be printed). An example using these options
1020
and manually handles @code{--help} and @code{--version} can be found in
1021
@file{test_manual_help_cmd.ggo} and @file{test_manual_help.c} in the
1022
@file{examples} directory.
937
1024
@item --no-handle-error
938
1025
@cindex @code{--no-handle-error}
1172
1259
options (see @ref{Multiple Options}, for further details about dealing
1173
1260
with multiple options).
1175
@node Group options, Parser function additional parameters, Terminology, Top
1262
@node Options with enumerated values, Group options, Terminology, Top
1263
@chapter Options with enumerated values
1265
@cindex enumerated options
1267
You can also specify the list of @code{values} that can be passed to an
1268
option (if the type is not specified, the option has type
1269
@code{string}). If a value that is not in the list is passed, an error
1270
is raised. You can think of such options as @emph{enumerated} options.
1271
It is not necessary to pass the complete value at the command line
1272
option: a non ambiguous prefix will do. For instance, if the accepted
1273
values are @code{"foo","bar","foobar"}, then you can pass at the command
1274
line the value @code{"b"} and the value @code{"bar"} will be selected,
1275
or the value @code{"foob"} and the value @code{"foobar"} will be
1276
selected; instead, passing the value @code{"fo"} will raise an ambiguity
1279
Since version 2.22 options with values can be given a specific type (the
1280
default is string). If you give a numeric type to such options,
1281
gengetopt will check that the enumerated values are actually valid
1282
values for that numeric type.
1284
As for other options, the @code{<option>_arg} field will have the
1285
specified type, while the @code{<option>_orig} field will always be a
1286
string (@code{char *}) storing the (non-ambiguous) prefix specified at
1289
For such an option, no matter what its type is, an array of strings,
1290
@code{<parser-name>_<option>_values}, will be generated that contains
1291
all the strings representing the possible accepted values.
1294
An option with enumerated values can also be given the type @code{enum};
1295
in that case, a C @code{enum} type is also generated with name
1296
@code{enum_<option>}; the values of such C enum will be generated
1297
according this pattern: @code{<option>_arg_<value>}, where @code{value}
1298
is the value specified in the input file. For instance, if we specify
1299
in the input file the following option
1302
option "myopt" ... ... values="FOO","180","BAR" enum ...
1306
then the following C enum will be generated:
1309
enum enum_myopt @{ myopt_arg_FOO, myopt_arg_180, myopt_arg_BAR @};
1312
@node Group options, Mode options, Options with enumerated values, Top
1176
1313
@chapter Group options
1177
1314
@cindex group options
1222
1359
test_groups: 2 options of group my grp2 were given. At most one is required
1225
@node Parser function additional parameters, Configuration files, Group options, Top
1362
@node Mode options, Parser function additional parameters, Group options, Top
1363
@chapter Mode options
1364
@cindex mode options
1366
It is also possible to specify ``mode options''; options belonging to a
1367
@emph{mode} are considered @emph{in mutual exclusion} with options of a
1368
different mode. Thus, you can specify more options belonging to the
1369
same mode, but you cannot specify, on the same command line, two options
1370
belonging to two different modes (thus, modes are different from groups,
1371
@ref{Group options}).
1373
These sets of options are called modes, since they represent the
1374
different modes (modalities), in which a program can be run.
1376
In order to use this feature, first the @code{mode} has to be defined,
1377
and then a @code{modeoption} can be defined. A modeoption has basically
1378
the same syntax of a standard option, and it can be given the required
1379
flag must not be specified (with a slightly different semantics, see
1380
below) and the group to which the option belongs has to be specified.
1383
defmode "<mode name>" @{modedesc="<mode description>"@}
1384
modeoption <long> <short> "<desc>" <argtype> mode="<mode name>" \
1385
@{argoptional@} @{multiple@} @{required@}
1388
If a mode option is specified as @code{required}, then it will be
1389
required only if other options of the same mode are specified; this
1390
makes it possible to specify options of different modes as required.
1392
Options not belonging to any mode are not in conflict with mode options.
1394
For instance, let us consider the file @file{test_modes_cmd.ggo}:
1396
@include test_modes_cmd.ggo.texinfo
1399
Now, we use the program @file{test_modes} (that uses the generated
1400
parser for the input file above) to demonstrate how the parser generated
1401
by gengetopt perform checks on mode options.
1408
This execution generates no errors (although there are required options
1409
which are not specified, these required options are part of modes and
1410
they are required only if that mode is used).
1414
./test_modes: '--optA' ('-A') option required
1418
Since an option of a mode is specified, then required options of that
1419
mode must be provided, but, in this execution, we forgot to specify a
1420
required option of the mode that is being used.
1427
This execution is correct: we specified two options of the same mode, in
1428
particular we also specified the required option of that mode. Notice
1429
that we use also an option not belonging to any mode, which does not
1430
interfere with mode options.
1433
test_modes -a -A -N --optc
1434
test_modes: option --optc conflicts with option --opta
1435
test_modes: option --optc conflicts with option --optA
1436
test_modes: '--optd' ('-d') option required
1440
Here we see a conflict, (actually two), since the last option we
1441
specified belongs to a mode that is different from the one of the first
1444
If you require gengetopt to generate @code{--full-help}
1445
(@xref{fullhelp,,@code{--full-help}}.), the usage string will be
1446
generated so that it will show the modes of the program; for instance,
1447
this is the output of @code{--help} of the generated parser for the
1451
@include help_modes.output.texinfo
1454
@node Parser function additional parameters, Configuration files, Mode options, Top
1226
1455
@chapter Parser function additional parameters
1227
1456
@cindex parser parameters
1228
1457
@cindex parameters
1252
1481
args_info struct, see, e.g., @ref{Configuration files} and@ref{String
1253
1482
Parsers and Multiple Parsers}).
1255
@item int check_required
1484
@item int check_required (default = 1)
1256
1485
@cindex check_required
1257
1486
tells whether the check for required options must be performed or not.
1259
@item int check_ambiguity
1488
@item int check_ambiguity (default = 0)
1260
1489
@cindex check_ambiguity
1261
1490
tells whether the check whether options that are parsed are not
1262
1491
already present in the passed args_info struct; this is performed only
1263
1492
for NON multiple options (see also @ref{Multiple Options}).
1494
@item int print_errors (default = 1)
1495
@cindex print_errors
1496
tells@footnote{Introduced in version 2.22} whether @code{getopt_long}
1497
must print error messages to the standard error stream if it encounters
1498
an unknown option character or an option with a missing required
1499
argument. This is the default behavior. If you set this variable to
1500
zero, @code{getopt_long} does not print any messages, but the generated
1501
parser will still return with error.
1266
For instance, internally, the standard command line parser function is
1267
invoked with @code{initialize} and @code{check_required} set to 1 and
1268
@code{override} set to 0.
1270
Gengetopt also generates an initialization function for such structures,
1271
called @code{<cmd_parser_name>_params_init}, which returns a dynamically
1272
allocated structure with all fields initialized to 0.
1274
We strongly advise to use such function for creating such a structure,
1275
since this will make your code scalable to future releases of gengetopt
1276
where such structure might contain additional fields. Otherwise, you
1277
might risk to use a structure where some fields are not initialized,
1278
with unpredictable results. Furthermore, since the function returns a
1279
pointer to a dynamically allocated structure (with @code{malloc}), it is
1280
up to you to deallocate that structure when you no longer need it (with
1504
Gengetopt also generates an initialization function for such
1505
structures@footnote{The @code{<cmd_parser_name>_params_init} was
1506
introduced in version 2.21, but it used to initialize all its fields to
1507
0, which does not make much sense, since it's more helpful to have the
1508
fields initialized to their default values; in order not to silently
1509
break the semantics of previous code, the (void argument) creation
1510
function is now called @code{<cmd_parser_name>_params_create} and
1511
@code{<cmd_parser_name>_params_init} is now a procedure that initializes
1512
a passed pointer to the structure. This will make previous code not
1513
compilable, since the signature of @code{<cmd_parser_name>_params_init}
1514
has changed; hopefully, this will force the programmer to realize that
1515
something has changed. I'm sorry for the (hopefully little) problems
1516
this change might imply.}, called @code{<cmd_parser_name>_params_init},
1517
which takes as argument a pointer to such structure and initialize all
1518
its fields to their default values; it also generates a function called
1519
@code{<cmd_parser_name>_params_create} that returns a dynamically
1520
allocated structure with all fields initialized to their default values.
1522
We strongly advise to use such functions for creating and initializing
1523
such a structure, since this will make your code scalable to future
1524
releases of gengetopt where such structure might contain additional
1525
fields. Otherwise, you might risk to use a structure where some fields
1526
are not initialized, with unpredictable results. Furthermore, since the
1527
@code{<cmd_parser_name>_params_create} function returns a pointer to a
1528
dynamically allocated structure (with @code{malloc}), it is up to you to
1529
deallocate that structure when you no longer need it (with @code{free}).
1283
1531
Some examples of usage of this parameters struct are shown in
1284
1532
@ref{Configuration files}.
2008
2259
@ref{Configuration files}) and multiple parsers (see @ref{String Parsers
2009
2260
and Multiple Parsers}).
2011
To deal with this problem, in case one uses configuration parsers
2012
(@code{-C,--conf-parser}) or string parsers
2013
(@code{-S,--string-parser}) a customized version of
2014
@code{getopt_long}, called indeed
2015
@cindex @code{custom_getopt_long}
2016
@code{custom_getopt_long} is
2017
inserted in the generated C file. This version does not suffer from
2018
the problem above (and of course does not interfere with the standard
2019
@code{getopt_long}, which will be used to parse the actual command
2022
Of course this is transparent to the programmer, and we report this
2023
detail here only because the inserted @code{custom_getopt_long} will
2024
add about 20k of C code in the generated file, so don't panic if you
2025
start to use configuration or string parsers and your program gets a
2026
little bigger than before :-).
2262
The parser generated by gengetopt checks whether the program name was
2263
actually considered a command line option, and in that case it removes
2264
it from the collected command line options; thus, this @code{optind}
2265
issue should not come up anyway. In case you still don't feel
2266
comfortable, you can include a correct @code{getopt_long} implementation
2267
in the generated parser, so that you can be sure you will always use the
2268
same implementation of @code{getopt_long} (@ref{Include the getopt_long
2269
code into the parser}).
2028
2271
@node Mailing Lists, Index, Bugs, Top
2029
2272
@chapter Mailing Lists
added
removed
doc/gengetopt.texinfo
