From 40bec131d23ddb065427e965c609a88defa13d5d Mon Sep 17 00:00:00 2001 From: Guillaume Marcais Date: Thu, 3 Sep 2015 19:06:45 -0400 Subject: [PATCH] Improved man page. --- lib/yaggo/man_page.rb | 95 +++++++++++++++++++++++++++++++++---------- 1 file changed, 74 insertions(+), 21 deletions(-) diff --git a/lib/yaggo/man_page.rb b/lib/yaggo/man_page.rb index 1a2b106..39287eb 100644 --- a/lib/yaggo/man_page.rb +++ b/lib/yaggo/man_page.rb @@ -57,10 +57,16 @@ def display_man_page out Display a short help text .PP -.SH EXAMPLES -Here is a fully working example. Consider the description -files 'example_args.yaggo' which defines two switches (-i and -s) -and arguments (first and the optional rest). +.SH EXAMPLE + +Consider the description files 'example_args.yaggo' which defines a +switch "-i" (or "--int") that takes an unsigned integer and defaults +to 42; a switch "-s" (or "--string") that takes a string and can be +given multiple times; a switch "--flag" which does not take any +argument; a switch "--severity" which can take only 3 values: "low", +"middle" and "high". + +It takes the following arguments: a string followed by zero or more floating point numbers. .nf purpose "Example of yaggo usage" @@ -193,12 +199,50 @@ def display_man_page out boolean indicating whether or not the switch was given on the command line. -In addition to the switch created by 'option', the following switches are defined: +For example, the statement: + +.nf +option("integer", "i") { + int; default 5 +} +.fi + +will add the following members to the C++ class: + +.nf +int integer_arg; +bool integer_given; +.fi + +where "integer_arg" is initialized to 5 and "integer_given" is +initialized to "false". If the switch "--integer 10" or "-i 10" is +passed on the command line "integer_arg" is set to 10 and +integer_given is set to "true". + +The statement: + +.nf +option("verbose") { + off +} +.fi + +will add the following member to the C++ class: + +.nf +bool verbose_flag; +.fi + +where "verbose_flag" is initialized to "false". Passing the switch +"--verbose" on the command line sets "verbose_flag" to true". + + +In addition to the switch created by 'option', the following switches +are defined by default (unless some option statement overrides them): .TP \-h, \-\-help -Display the help message. \-h is not defined if it conflicts with an -option statement. +Display the help message. .TP \-\-full\-help Display hidden options as well. @@ -270,11 +314,20 @@ def display_man_page out This switch is a flag and does not take an argument. .TP on, off -The default state for a flag switch. Implies flag. +The default state for a flag switch. Implies flag. Unless the 'no' +option is used (see below), with 'off', the default value of the flag +is "false" and passing --flag sets it to true. With 'on', the default +value of the flag is "true" and passing --flag sets it to false. +.TP +no +A flag with two switches. If the switch is named "flag", two switches +are generated: --flag and --noflag, respectively setting it to "true" +and "false". The 'on' and 'off' options define the default value. .TP default "val" -The default value for this switch. It must be passed as a string -(i.e. surrounded by quotes), even for numerical types. +The default value for this switch. It can be a string or a valid +number. SI suffixes are supported as well (for example "1M" means 1 +m`illion). .TP typestr "str" In the help message, by default, the type of the option is @@ -284,7 +337,6 @@ def display_man_page out The given switch must be given at least n times. Implies multiple. .TP access "type" - Make sure that the string passed is a path to which we have access. "type" is a comma separated list of "read", "write" or "exec". It is checked with access(2). The same warning applies: @@ -300,11 +352,12 @@ def display_man_page out .PP -A 'arg' statement defines an arg passed nnto the command line. The +A 'arg' statement defines an arg passed to the command line. The statement takes a single argument, the name of the arg, and a block of statements. The block of statements are similar to the option block, -except that hidden, flag, on and off are not allowed. At most one arg -can have the 'multiple' statement, and it must be the last one. +except that "hidden", "flag", "on", "off" and "no" are not allowed. At +most one arg can have the 'multiple' statement, and it must be the +last one. .SH EXAMPLE USAGE @@ -339,13 +392,13 @@ class behave like an output stream, it can be used to create .fi An error object prints an error message and terminate the program with -exit upon destruction. Make sure that the error message is properly -scoped to be destroyed where the program should terminate. In -practice, as in the example above, the error class is created in an if -statement and therefore destructed right away. +exit upon destruction. An exit code can be passed to error. By default +the exit code (passed to exit) is the constant EXIT_FAILURE (normally +1). For example: -An exit code can be passed to error. By default the exit code (passed -to exit) is the constant EXIT_FAILURE (normally 1). For example: +.nf + example_args::error(77) << "Failed with return code 77"; +.fi .SH LICENSE @@ -373,7 +426,7 @@ class behave like an output stream, it can be used to create .SH AUTHOR Guillaume Marcais (gmarcais@umd.edu) .SH SEE ALSO -getopt_long(3), gengetopt(1) +getopt_long(3), gengetopt(1), exit(2) EOS if !out && STDOUT.isatty