Description

Parses program command line switches and arguments.

Definitions

A program command line is the vector of strings passed to a program by the operating system or runtime.
A commmand line argument is one element of the program command line vector.
A switch is a named command line argument, usually introduced with a special character sequence followed by a name, such as --color. The "--" is the switch prefix, "color" is the switch name, and "--color" is the switch string.
A switch argument is an optional value specified on the program command line and associated with a switch, such as the word "grey" in --color=grey or --color grey (as two command-line arguments).
A switch value is a switch argument that has been converted to a value within a program, such as the enumeration constant GRAY, whether the string on the command line was "grey" or "gray".
A non-switch is a program argument that doesn't appear to be a switch. Another name for the same thing is positional program argument.

The major parts of the API

Program command-line parsing consists of the following major components:

The Switch class declares a switch and specifies such things as the switch name and its arguments.
The SwitchGroup class groups related switches into collections.
The Parser class parses a program command line to produce a ParserResult.
The ParserResult class holds information about how a program command line was parsed by storing, among other things, a list of ParsedValue objects.
The ParsedValue class holds details about each value parsed from a program command line, including the value's string from the command line and information about the associated switch.

Description

The library is used in three phases: first, the command line is described in terms of switches and their arguments; then a parser is constructed and applied to the command line to obtain a result; and finally, the result is used by querying or pushing results into variables.

Some of our goals in designing this library were influenced by other libraries. We wanted to take the good ideas of others but avoid the same pitfalls. Our goals are:

Keep the switch declaration API as simple and terse as reasonably possible without the loss of self-documenting code. Our approach is to use small, optional property-setting functions that can be chained together rather than excessive function overloading or magical strings.
The switch declaration API should be able to describe all the situations that routinely occur in command-line parsing including things like optional arguments and multiple arguments, various ways to handle multiple occurrences of the same switch, short and long switch names, various switch prefixes and value separators, nestling of short switches and their arguments, standard switch actions, etc. We accomplish this by using a consistent API of switch properties.
Parsing of the command line should not only recognize the syntax of the command line, but also parse switch arguments into a form that is easy to use within the program. E.g., a string like "1234" should become an int in the program.
Provide an extension mechanism that is easy for beginning programmers to grasp. One way we accomplish this is by avoiding excessive use of templates for generic programming and instead rely on polymorphic classes and smart pointers, both of which are common in other object oriented languages. Parsing command-line arguments is not typically a performance bottleneck, and when we were faced with the alternatives of performance versus features we chose features.
The library should provide an API that is suitable for both library writers and application programmers. In other words, a library that expects to be configured from the command line should provide a description of its command-line in a way that allows the application to augment it with its own switches, even to the extent that the application can rename library switches if it desires.
The parser results should have a rich query API since this is the point at which it primarily interfaces with the program. A program should not have to work hard to use the parsing results. The library provides both pull and push capabilities for the results: the user can query results or the library can write them directly into user-supplied variables.
Documentation should appear next to the thing it documents, and it should not be necessary to have more than one source-level copy of documentation. The library is able to generate complete Unix manual pages as plain text or POD, the latter which can be converted to to a variety of other formats with standard tools.

An example

Here's an example to give the basic flavor of the library. The description of the command-line and the parsing of the command-line are combined in a single function, parseCommandLine:

Sawyer::CommandLine::ParserResult
parseCommandLine(int argc, char *argv[], Settings &settings) {
    using namespace Sawyer::CommandLine;

We'll divide the command-line into two groups of switches: switches that are common to all our tools, and switches that are specific to this particular tool. In real life, the common switches would be returned from some other function defined in a library that all the tools share. Each switch group may have its own documentation, which causes its switches to be grouped together in the manual page. Documentation is free-flowing and automatically wrapped to the width of the terminal window in which the command runs, so there is no need to have line feeds within the source code string literals, although they are allowed. A double line feed in the documentation string is a paragraph separator.

SwitchGroup standard;

standard.doc("The following switches are recognized by all tools in this package.");

Now we can declare a couple switches inside our standard switch group. We'll declare one that will show the manual page, and another that shows the version number. The man page is shown with –help, -h, or -?, and the version is shown with –version or -V. Switch actions occur only when switch parsing is all done (i.e., the man page won't be emitted unless the command-line is parsable).

    standard.insert(Switch("help", 'h')
                    .shortName('?')
                    .action(showHelpAndExit(0))
                    .doc("Show this documentation."));
 
    standard.insert(Switch("version", 'V')
                    .action(showVersionAndExit("1.2.3", 0))
                    .doc("Show version number."));

We place all the tool-specific switches in another switch group we call tool. The –isa switch will accept an argument that can be anything and is stored in std::string settings.isaName. If the argument is the word "list" then the function that eventually parses it will generate a list (this function is part of the tool source code and is not part of Sawyer).

    SwitchGroup tool;
    tool.doc("The following switches are specific to this command.");
 
    tool.insert(Switch("isa")
                .argument("architecture", anyParser(settings.isaName))
                .doc("Instruction set architecture. Specify \"list\" to see "
                     "a list of possible ISAs."));

The next two switches are similar except they expect arguments that are non-negative integers. The argument will be parsed by Sawyer, which accepts decimal, octal, and hexadecimal using C syntax, and eventually assigned to the specified settings data member, both of which are of type unsigned long. The parser function, nonNegativeIntegerParser, is overloaded to accept a variety of integer types and a parsing exception will be thrown if the argument string parses to a value which doesn't fit in the specified variable.

    tool.insert(Switch("at")
                .argument("virtual-address", nonNegativeIntegerParser(settings.startVa))
                .doc("The first byte of the file is mapped at the specified "
                     "@v{virtual-address}, which defaults to " +
                     boost::lexical_cast<std::string>(settings.startVa) + "."));
 
    tool.insert(Switch("alignment")
                .argument("align", nonNegativeIntegerParser(settings.alignment))
                .doc("Alignment for instructions.  The default is 1 (no alignment).  Values "
                     "larger than one will cause each candidate address to be rounded up to "
                     "the next multiple of @v{align}.  If this rounding up causes addresses "
                     "after a valid instruction to be skipped then a warning is printed. "
                     "No warning is printed if the alignment skips addresses after a "
                     "disassembly failure."));

Now that the command-line switches are described, we can create a parser. The parser also controls the non-switch aspects of the manual page, such as the heading and footer, purpose, synopsis, and other sections.

    Parser parser;
    parser
        .purpose("disassembles files one address at a time")
        .doc("synopsis",
             "@prop{programName} [@v{switches}] @v{specimen_name}")
        .doc("description",
             "This program is a very simple disassembler that tries to disassemble an "
             "instruction at each address of the specimen file.");

Finally we can do the actual parsing. We could split this statement into multiple statements, but one of Sawyer's idioms is to chain things together in a functional programming style. The with method inserts our switch declarations from above into the parser; the parse method, of which there are multiple overloaded varieties, does the real work; and the apply method applies the results of a successful parse by copying values into the variabiables we specified, and running switch actions (e.g., "help" and "version") if necessary.

return parser.with(standard).with(tool).parse(argc, argv).apply();

}

Here's the whole example in one shot (the docs/examples/commandLineEx1.C file):

 #include <Sawyer/CommandLine.h>
 #include <iostream>
  
 struct Disassembler {};
 struct DisassemblerArm: Disassembler {};
 struct DisassemblerPowerpc: Disassembler {};
 struct DisassemblerMips: Disassembler {};
 struct DisassemblerI386: Disassembler {};
 struct DisassemblerAmd64: Disassembler {};
 struct DisassemblerM68k: Disassembler {};
 struct DisassemblerColdFire: Disassembler {};
  
 // Convenient struct to hold settings from the command-line all in one place.
 struct Settings {
     std::string isaName;
     unsigned long startVa;
     unsigned long alignment;
     Settings(): startVa(0), alignment(1) {}
 };
  
 static Disassembler *
 getDisassembler(const std::string &name)
 {
     if (0==name.compare("list")) {
         std::cout <<"The following ISAs are supported:\n"
                   <<"  amd64\n"
                   <<"  arm\n"
                   <<"  coldfire\n"
                   <<"  i386\n"
                   <<"  m68040\n"
                   <<"  mips\n"
                   <<"  ppc\n";
         exit(0);
     } else if (0==name.compare("arm")) {
         return new DisassemblerArm();
     } else if (0==name.compare("ppc")) {
         return new DisassemblerPowerpc();
     } else if (0==name.compare("mips")) {
         return new DisassemblerMips();
     } else if (0==name.compare("i386")) {
         return new DisassemblerI386();
     } else if (0==name.compare("amd64")) {
         return new DisassemblerAmd64();
     } else if (0==name.compare("m68040")) {
         return new DisassemblerM68k();
     } else if (0==name.compare("coldfire")) {
         return new DisassemblerColdFire();
     } else {
         throw std::runtime_error("invalid ISA name \""+name+"\"; use --isa=list");
     }
 }
  
 Sawyer::CommandLine::ParserResult
 parseCommandLine(int argc, char *argv[], Settings &settings) {
     using namespace Sawyer::CommandLine;
  
     SwitchGroup standard;
     standard.doc("The following switches are recognized by all tools in this package.");
  
     standard.insert(Switch("help", 'h')
                     .shortName('?')
                     .action(showHelpAndExit(0))
                     .doc("Show this documentation."));
  
     standard.insert(Switch("version", 'V')
                     .action(showVersionAndExit("1.2.3", 0))
                     .doc("Show version number."));
     
  
     SwitchGroup tool;
     tool.doc("The following switches are specific to this command.");
  
     tool.insert(Switch("isa")
                 .argument("architecture", anyParser(settings.isaName))
                 .doc("Instruction set architecture. Specify \"list\" to see "
                      "a list of possible ISAs."));
  
     tool.insert(Switch("at")
                 .argument("virtual-address", nonNegativeIntegerParser(settings.startVa))
                 .doc("The first byte of the file is mapped at the specified "
                      "@v{virtual-address}, which defaults to " +
                      boost::lexical_cast<std::string>(settings.startVa) + "."));
  
     tool.insert(Switch("alignment")
                 .argument("align", nonNegativeIntegerParser(settings.alignment))
                 .doc("Alignment for instructions.  The default is 1 (no alignment).  Values "
                      "larger than one will cause each candidate address to be rounded up to "
                      "the next multiple of @v{align}.  If this rounding up causes addresses "
                      "after a valid instruction to be skipped then a warning is printed. "
                      "No warning is printed if the alignment skips addresses after a "
                      "disassembly failure."));
  
     Parser parser;
     parser
         .purpose("disassembles files one address at a time")
         .doc("synopsis",
              "@prop{programName} [@v{switches}] @v{specimen_name}")
         .doc("description",
              "This program is a very simple disassembler that tries to disassemble an "
              "instruction at each address of the specimen file.");
  
     return parser.with(standard).with(tool).parse(argc, argv).apply();
 }
  
 int main(int argc, char *argv[])
 {
     // Parse the command-line
     Settings settings;
     Sawyer::CommandLine::ParserResult cmdline = parseCommandLine(argc, argv, settings);
     std::vector<std::string> positionalArgs = cmdline.unreachedArgs();
  
     // Obtain a disassembler (do this before opening the specimen so "--isa=list" has a chance to run)
     Disassembler *disassembler = getDisassembler(settings.isaName);
     ASSERT_always_not_null(disassembler);
  
     // Open the file that needs to be disassembled
     if (positionalArgs.empty())
         throw std::runtime_error("no file name specified; see --help");
     if (positionalArgs.size()>1)
         throw std::runtime_error("too many files specified; see --help");
     std::string specimenName = positionalArgs[0];
  
     return 0;
 }

And here's the output from the –help switch:

COMMANDLINEEX1(1)                User Commands               COMMANDLINEEX1(1)



Name
       commandLineEx1 - disassembles files one address at a time

Synopsis
       commandLineEx1 [switches] specimen_name

Description
       This program is a very simple disassembler that tries to disassemble an
       instruction at each address of the specimen file.

Options
       The following switches are recognized by all tools in this package.

       --help; -h; -?
           Show this documentation.

       --version; -V
           Show version number.

       The following switches are specific to this command.

       --alignment align
           Alignment for instructions.  The default is 1 (no alignment).
           Values larger than one will cause each candidate address to be
           rounded up to the next multiple of align.  If this rounding up
           causes addresses after a valid instruction to be skipped then a
           warning is printed. No warning is printed if the alignment skips
           addresses after a disassembly failure.

       --at virtual-address
           The first byte of the file is mapped at the specified virtual-
           address, which defaults to 0.

       --isa architecture
           Instruction set architecture. Specify "list" to see a list of
           possible ISAs.



alpha                              July 2014                 COMMANDLINEEX1(1)

Namespaces
	Boost
	Drop-in replacement to help boost users.

Classes
class	AnyParser
	Parses any argument as plain text. More...

class	BooleanParser
	Parses a boolean value and converts it to numeric type `T`. More...

class	ConfigureDiagnostics
	Functor to configure diagnostics. More...

class	ConfigureDiagnosticsQuiet
	Function to configure diagnostics to quiet mode. More...

class	Cursor
	Input stream for command line arguments. More...

class	EnumParser
	Parses an enumerated constant. More...

class	ExcursionGuard
	Guards a cursor and restores it when the guard is destroyed. More...

class	IntegerParser
	Parses an integer and converts it to numeric type `T`. More...

struct	LexicalCast

struct	LexicalCast< boost::any >

struct	LexicalCast< boost::filesystem::path >

struct	LexicalCast< boost::regex >

struct	LexicalCast< Optional< T > >

struct	LexicalCast< Sawyer::Container::Map< std::string, T > >

struct	LexicalCast< Sawyer::Container::Set< T > >

struct	LexicalCast< std::list< T > >

struct	LexicalCast< std::map< std::string, T > >

struct	LexicalCast< std::regex >

struct	LexicalCast< std::set< T > >

struct	LexicalCast< std::vector< T > >

class	ListParser
	Parses a list of values. More...

struct	Location
	Position within a command-line. More...

class	NonNegativeIntegerParser
	Parses a non-negative integer and converts it to numeric type `T`. More...

struct	NumericCast

struct	NumericCast< Optional< Target >, Source >

struct	NumericCast< Sawyer::Container::Map< std::string, Target >, Source >

struct	NumericCast< Sawyer::Container::Set< Target >, Source >

struct	NumericCast< std::list< Target >, Source >

struct	NumericCast< std::map< std::string, Target >, Source >

struct	NumericCast< std::set< Target >, Source >

struct	NumericCast< std::vector< Target >, Source >

class	ParsedValue
	Information about a parsed switch value. More...

class	Parser
	The parser for a program command line. More...

class	ParserResult
	The result from parsing a command line. More...

struct	ParsingProperties

class	PositiveIntegerParser
	Parses a positive integer and converts it to numeric type `T`. More...

class	RealNumberParser
	Parses a real number and converts it to numeric type `T`. More...

class	ShowHelp
	Functor to print the Unix man page. More...

class	ShowHelpAndExit
	Functor to print the Unix man page and exit. More...

class	ShowVersion
	Functor to print a version string. More...

class	ShowVersionAndExit
	Functor to print a version string and exit. More...

class	StringSetParser
	Parses any one of a set of strings. More...

class	Sum
	Sums all previous and current values. More...

class	Switch
	Describes one command-line switch. More...

class	SwitchAction
	Base class for switch actions. More...

class	SwitchArgument
	Describes one argument of a command-line switch. More...

class	SwitchGroup
	A collection of related switch declarations. More...

class	TypedSaver

class	TypedSaver< BitFlags< T > >

class	TypedSaver< Optional< T > >

class	TypedSaver< Sawyer::Container::IntervalSet< Interval > >

class	TypedSaver< Sawyer::Container::Map< std::string, T > >

class	TypedSaver< Sawyer::Container::Set< T > >

class	TypedSaver< std::list< T > >

class	TypedSaver< std::map< std::string, T > >

class	TypedSaver< std::set< T > >

class	TypedSaver< std::vector< T > >

class	UserAction
	Wrapper around a user functor. More...

class	ValueAugmenter
	Base class for value agumentors. More...

class	ValueParser
	Base class parsing a value from input. More...

class	ValueSaver

Typedefs
typedef std::vector< ParsedValue >	ParsedValues
	A vector of parsed values.

typedef Container::Map< const SwitchGroup , std::set< const Switch > >	GroupedSwitches
	Subset of switches grouped by their switch groups.

typedef Container::Map< std::string, GroupedSwitches >	NamedSwitches
	Subset of switches indexed by their command-line representation.

Enumerations
enum	SortOrder { INSERTION_ORDER, DOCKEY_ORDER }
	The order in which things are sorted in the documentation. More...

enum	Canonical { CANONICAL, NONCANONICAL, ALL_STRINGS }
	Format of a switch string. More...

enum	ShowGroupName { SHOW_GROUP_OPTIONAL, SHOW_GROUP_REQUIRED, SHOW_GROUP_NONE, SHOW_GROUP_INHERIT }
	How to show group names in switch synopsis. More...

enum	SwitchSkipping { SKIP_NEVER, SKIP_WEAK, SKIP_STRONG }
	Whether to skip a switch. More...

enum	WhichValue { SAVE_NONE, SAVE_ONE, SAVE_LAST, SAVE_FIRST, SAVE_ALL, SAVE_AUGMENTED }
	Describes how to handle switches that occur multiple times. More...

Functions
std::ostream &	operator<< (std::ostream &, const Location &)
	Print a location. More...

std::ostream &	operator<< (std::ostream &, const ParsedValue &)
	Print some information about a parsed value.

Variables
const std::string	STR_NONE

const Location	NOWHERE
	Indicates an invalid location. More...

Enumeration Type Documentation

◆ SortOrder

enum Sawyer::CommandLine::SortOrder

The order in which things are sorted in the documentation.

Enumerator

INSERTION_ORDER

Entities appear in the documentation in the same order they are inserted into the container.

For instance, manual page sections will appear in the order of the Parser::doc calls, or switches are sorted within a switch group according to the order they were inserted into the group.

DOCKEY_ORDER

Entities are sorted according to their documentation keys.

Documentation keys, which default to lower-case entity names, are used to sort the entities within their container. This is the default.

Definition at line 173 of file util/Sawyer/CommandLine.h.

◆ Canonical

enum Sawyer::CommandLine::Canonical

Format of a switch string.

Enumerator
CANONICAL	Switch strings that are qualified with the switch group name or which belong to a group that has no name.
NONCANONICAL	Switch strings that are not CANONICAL.
ALL_STRINGS	The union of CANONICAL and NONCANONICAL.

Definition at line 186 of file util/Sawyer/CommandLine.h.

◆ ShowGroupName

enum Sawyer::CommandLine::ShowGroupName

How to show group names in switch synopsis.

Enumerator
SHOW_GROUP_OPTIONAL	Show name as being optional, like "--[group-]switch".
SHOW_GROUP_REQUIRED	Show name as being required, like "--group-switch".
SHOW_GROUP_NONE	Never show the group name.
SHOW_GROUP_INHERIT	Group inherits value from the parser.

Definition at line 194 of file util/Sawyer/CommandLine.h.

◆ SwitchSkipping

enum Sawyer::CommandLine::SwitchSkipping

Whether to skip a switch.

Enumerator
SKIP_NEVER	Treat the switch normally.
SKIP_WEAK	Process switch normally, but also add to skipped list.
SKIP_STRONG	Skip switch and its argument(s) without saving any value.

Definition at line 202 of file util/Sawyer/CommandLine.h.

◆ WhichValue

enum Sawyer::CommandLine::WhichValue

Describes how to handle switches that occur multiple times.

Enumerator
SAVE_NONE	The switch is disabled. Any occurrence will be an error.
SAVE_ONE	The switch cannot occur more than once.
SAVE_LAST	Use only the last occurrence and ignore all previous.
SAVE_FIRST	Use only the first occurrence and ignore all previous.
SAVE_ALL	Save all values as a vector.
SAVE_AUGMENTED	Save the first value, or modify previously saved value.

Definition at line 2010 of file util/Sawyer/CommandLine.h.

Function Documentation

◆ operator<<()

std::ostream& Sawyer::CommandLine::operator<<	(	std::ostream &	,
		const Location &
	)

Print a location.

Prints a location as the dotted pair idx.offset.

Variable Documentation

◆ NOWHERE

const Location Sawyer::CommandLine::NOWHERE

Indicates an invalid location.

The library uses this to indicate that a string came from somewhere other than the command-line. The constant NOWHERE compares equal to itself but unequal to (less than) all valid locations.

Referenced by Sawyer::CommandLine::Switch::intrinsicValue(), and Sawyer::CommandLine::SwitchArgument::SwitchArgument().

Description

Definitions

The major parts of the API

Description

An example

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ SortOrder

◆ Canonical

◆ ShowGroupName

◆ SwitchSkipping

◆ WhichValue

Function Documentation

◆ operator<<()

Variable Documentation

◆ NOWHERE