FreeBSD Manual Pages
yaggo(1) USER COMMANDS yaggo(1) NAME yaggo - command line switch parser generator SYNOPSIS yaggo [-o|--output FILE] [-l|--license PATH] [-s|--stub] [--zc PATH] [-e|--extended-syntax] [--man] [-h|--help] DESCRIPTION Yaggo stands for Yet Another GenGetOpt. It is inspired by gengetopt soft- ware from the FSF. Yaggo generates a C++ class to parse command line switches (usually argc and argv passed to main) using getopt_long. The switches and arguments to the program are specified in a description file. To each description file, yaggo generates one C++ header file containing the parsing code. See the EXAMPLES section for a complete and simple example. OPTIONS -l|--license Display the file at the top of the generated headers. It usually contains the license governing the distribution of the headers. -m|--man Display this man page -s|--stub Generate a stub: a simple yaggo file that can be modified for one's use. -e|--extended-syntax Use the extended syntax: blocks can be defined on the next line of a command. -h|--help Display a short help text 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 float- ing point numbers. purpose "Example of yaggo usage" package "example" description "This is just an example. And a multi-line description." option("int", "i") { description "Integer switch" uint32; default "42" } option("string", "s") { description "Many strings" string; multiple } option("flag") { description "A flag switch" flag; off } option("severity") { description "An enum switch" enum "low", "middle", "high" } arg("first") { description "First arg" c_string } arg("rest") { description "Rest of'em" double; multiple } The associated simple C++ program 'examples.cpp' which display information about the switches and arguments passed: #include <iostream> #include "example_args.hpp" int main(int argc, char *argv[]) { example_args args(argc, argv); std::cout << "Integer switch: " << args.int_arg << "\n"; if(args.string_given) std::cout << "Number of string(s): " << args.string_arg.size() << "\n"; else std::cout << "No string switch\n"; std::cout << "Flag is " << (args.flag_flag ? "on" : "off") << "\n"; std::cout << "First arg: " << args.first_arg << "\n"; std::cout << "Severity arg: " << args.severity_arg << " " << example_args::severity::strs[args.severity_arg] << "\n"; if(args.severity_arg == example_args::severity::high) std::cout << "Warning: severity is high\n"; std::cout << "Rest:"; for(example_args::rest_arg_it it = args.rest_arg.begin(); it != args.rest_arg.end(); ++it) std::cout << " " << *it; std::cout << std::endl; return 0; } This can be compiled with the following commands: % yaggo example_args.yaggo % g++ -o example example.cpp The yaggo command above will create by default the file file name can be changed with the 'output' keyword explained below. DESCRIPTION FORMAT A description file is a sequence of statements. A statement is a keyword followed by some arguments. Strings must be surrounded by quotes ("" or '') and can span multiple lines. The order of the statements is irrelevant. Statements are separated by new lines or semi-colons ';'. * Technically speaking, yaggo is implemented as a DSL (Domain Specific Language) using ruby. The description file is a valid ruby script and the keywords are ruby functions. The following statements are global, not attached to a particular option or argument. purpose A one line description of the program. package The name of the package for the usage string. Defaults to the name of the class. usage The usage string. If none given a standard one is generated by yaggo. description A longer description of the program displayed before the list of switch. Displayed by the help. text Some text to be displayed after the list of switches. Displayed by the help. version The version string of the software. license The license and copyright string of the software. name The name of the class generated. Defaults to the name of the de- scription file minus the .yaggo extension. posix Posix correct behavior (instead of GNU behavior): switch processing stops at the first non-option argument output The name of the output file. Defaults to the name of the description file with the .yaggo extension changed to .hpp. The 'option' statement takes one or two arguments, which must be in paren- theses, and a block of statements surrounded by curly braces ({...}). The arguments are the long and short version of the option. Either one of the long or short version can be omitted. The block of statements describe the option in more details, as described below. A switch is named after the long version, or the short version if no long version. An 'option' statement for an option named 'switch' defines one or two public members in the class. For a flag, it creates 'switch_flag' as a boolean. Otherwise, it creates 'switch_arg', with a type as specified, and 'switch_given', a boolean indicating whether or not the switch was given on the command line. For example, the statement: option("integer", "i") { int; default 5 } will add the following members to the C++ class: int integer_arg; bool integer_given; 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 com- mand line "integer_arg" is set to 10 and integer_given is set to "true". The statement: option("verbose") { off } will add the following member to the C++ class: bool verbose_flag; where "verbose_flag" is initialized to "false". Passing the switch "--ver- bose" 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): -h, --help Display the help message. --full-help Display hidden options as well. --version Display version string. The following statement are recognized in an option block: description "str" A short description for this switch. int32, int64, uint32, uint64, double, int, long This switch is parsed as a number with the corresponding type int32_t, int64_t, uint32_t, uint64_t, double, int and long. suffix Valid for numerical type switches as above. It can be appended with a SI suffix (e.g. 1M mean 1000000). The suffixes k, M, G, T, P, and E are supported for all the numerical types. The suffixes m, u, n, p, f, and a are supported for the double type. c_string, string This switch is taken as a C string (const char *) or a C++ string (inherits from std::string). The C++ string type has the extra meth- ods '<type> as_<type>(bool suffix)', where <type> is any numerical type as above, to convert the string into that type. If the 'suffix' boolean is true, parsing is done using SI suffixes. enum This statement must be followed by a comma separated list of strings (as in 'enum "choice0", "choice1", "choice2"'). This switch takes value a string in the list and is converted to int. C enum type named "switchname::enum" is defined with the same choices in the given order. required This switch is required. An error is generated if not given on the command line. conflict Specify a comma separated list of switches that conflicts with this one. imply Specify a comma separated list of switches (of type flag) which are implied by this one. hidden This switch is not shown with --help. Use --full-help to see the hidden switches, if any. secret This switch is not shown in any help message. Neither --help nor --full-help. multiple This switch can be passed multiple times. The values are stored in a std::vector. A type for the iterator is also defined in the class with the name 'switch_arg_it', where 'switch' is the name of the op- tion. flag This switch is a flag and does not take an argument. on, off 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. 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. default "val" 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). typestr "str" In the help message, by default, the type of the option is dis- played. It can be replaced by the string given to 'typestr'. at_least n The given switch must be given at least n times. Implies multiple. 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: "Warning: Using access() to check if a user is authorized to, for example, open a file before actually doing so using open(2) creates a security hole, because the user might exploit the short time in- terval between checking and opening the file to manipulate it. For this reason, the use of this system call should be avoided. (In the example just described, a safer alternative would be to temporarily switch the process's effective user ID to the real ID and then call open(2).)" 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 "hid- den", "flag", "on", "off" and "no" are not allowed. At most one arg can have the 'multiple' statement, and it must be the last one. EXAMPLE USAGE The argument object parses the switches on construction or later on using the parse method. For example, the two pieces code show these two different usage. Using parse method: example_args args; // Global variable with switches int main(int argc, char* argv[]) { args.parse(argc, argv); } Parse on construction: int main(int argc, char* argv[]) { example_args args(argc, argv); } The subclass error can be used to output error messsage (and terminate pro- gram). It output an error message, the usage string, etc. The error class behave like an output stream, it can be used to create complicated error message. For example: if(false_condition) example_args::error() << "Failed to open file '" << args.file_arg << "'"; An error object prints an error message and terminate the program with 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 exam- ple: example_args::error(77) << "Failed with return code 77"; LICENSE There are 2 parts to the software: the yaggo ruby script itself, and the header files generated by yaggo from the description files. The licenses are as follow: yaggo the ruby script This software is licensed under the GNU General Public License ver- sion 3 or any later version. Copyright (c) 2011 Guillaume Marcais. copyright that you, the user of yaggo, assign with the 'license' keyword. .PP In short: only yaggo the software is GPL. The gener- ated header files are considered derivative of your work (e.g. the description), and you define the copyright and license of those as you see fit. BUGS * The error message returned by ruby can be a little confusing. AUTHOR Guillaume Marcais (gmarcais@umd.edu) SEE ALSO getopt_long(3), gengetopt(1), exit(2) version 1.5.11 2015-06-24 yaggo(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLE | DESCRIPTION FORMAT | EXAMPLE USAGE | LICENSE | BUGS | AUTHOR | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=yaggo&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>