Stroika::Foundation::Execution::CommandLine Class Reference

#include <CommandLine.h>

Classes
struct	Option

Public Types
enum class	WrapInShell
enum class	StringShellQuoting

Public Member Functions
	CommandLine ()=delete
nonvirtual void	Validate (Iterable< Option > options) const
nonvirtual optional< String >	GetArgument (const Option &o) const
nonvirtual Sequence< String >	GetArguments () const
template<Common::IAnyOf< String > T, typename... ARGS>
nonvirtual T	As (ARGS... args) const

Detailed Description

Take in a 'command line' specification (typically from 'main', but also used as arguments to ProcessRunner), and define 'Option' objects and lookup if given arguments are 'present' in the commandline (and grab associated arguments).

Supports repeated option elements. Supports -o and –output-file formats Supports -o ARG and -o=ARG formats

inspired partly by https://man7.org/linux/man-pages/man3/getopt.3.html

Example Usage (in application main)

uint16_t portNumber = 8080;
 
const CommandLine::Option kPortO_{
    .fLongName = "port"sv, .fSupportsArgument = true, .fHelpOptionText = "specify webserver listen port (default {})"_f(portNumber)};
const CommandLine::Option kQuitAfterO_{
    .fLongName = "quit-after"sv, .fSupportsArgument = true, .fHelpOptionText = "automatically quit after <argument> seconds"sv};
const Sequence<CommandLine::Option> kAllOptions_{StandardCommandLineOptions::kHelp, kPortO_, kQuitAfterO_};
 
try {
    cmdLine.Validate (kAllOptions_);
}
catch (const InvalidCommandLineArgument&) {
    cerr << Characters::ToString (current_exception ()).AsNarrowSDKString () << endl;
    cerr << cmdLine.GenerateUsage (kAllOptions_).AsNarrowSDKString () << endl;
    return EXIT_FAILURE;
}
if (cmdLine.Has (StandardCommandLineOptions::kHelp)) {
    cerr << cmdLine.GenerateUsage (kAllOptions_).AsNarrowSDKString () << endl;
    return EXIT_SUCCESS;
}

Example Usage (args to ProcessRunner)

ProcessRunner p{CommandLine{WrapInShell::eBash, "echo $USER"}};

TODO: o

Definition at line 82 of file CommandLine.h.

Member Enumeration Documentation

WrapInShell

enum class Stroika::Foundation::Execution::CommandLine::WrapInShell

strong

Used as optional CTOR argument, to create a CommandLine with bash -c "actual string arg" or cmd /C "actual string arg"

Definition at line 90 of file CommandLine.h.

StringShellQuoting

enum class Stroika::Foundation::Execution::CommandLine::StringShellQuoting

strong

Strategy/rules used when converting between a list of arguments to a single string.

Definition at line 262 of file CommandLine.h.

Constructor & Destructor Documentation

CommandLine()

Stroika::Foundation::Execution::CommandLine::CommandLine ( )

delete

Unlike most other Stroika APIs, plain 'char' here for char*, is interpreted as being in the SDK code page (current locale - like SDKChar if narrow).

CommandLine{STRING} parsing the string into individual components the way a generic shell would (space separation) and respecting quote characters).

CommandLine{WrapInShell, STRING} really doesn't parse the string (except to add quotes as needed), but creates a CommandLine that will allow the argument shell to parse the command (e.g. bash -c "arguments").

CommandLine{Sequence<String>} just captures that sequence of arguments and does not processing/parsing.

CommandLine{argc,argv} are meant for being called from main, and also do no processing (besides treating the char* strings as SDKChar and mapping them from the OS codepage to UNICODE).

Member Function Documentation

Validate()

void CommandLine::Validate

(

Iterable< Option >

options

)

const

Throw InvalidCommandLineArgument if arguments not fit with options. This checks for unrecognized arguments.

Example Usage

const initializer_list<Execution::CommandLine::Option> kAllOptions_{StandardCommandLineOptions::kHelp, ...others...};
cmdLine.Validate (kAllOptions_);        // throws InvalidCommandLineArgument if bad args so catch/report usage

Definition at line 319 of file CommandLine.cpp.

GetArgument()

optional< String > Stroika::Foundation::Execution::CommandLine::GetArgument

(

const Option &

o

)

const

Precondition

o.fSupportsArgument

Example Usage

constexpr CommandLine::Option   kOutFileOption_ = CommandLine::Option{.fSingleCharName = 'o', .fSupportsArgument = true };
CommandLine cmdLine {argc, argv};
String file2Use = cmdLine.GetArgument (kOutFileOption_).value_or ("default-file-name.xml");

Definition at line 35 of file CommandLine.inl.

GetArguments()

Sequence< String > Stroika::Foundation::Execution::CommandLine::GetArguments

(

)

const

overload with no arguments /0 - returns all commandline arguments.

Precondition

o.fSupportsArgument

Definition at line 41 of file CommandLine.inl.

As()

template<Common::IAnyOf< String > T, typename... ARGS>

nonvirtual T Stroika::Foundation::Execution::CommandLine::As

(

ARGS...

args

)

const

Example Usage (use default StringShellQuoting)

String cmdLineText = cmdLine.As<String> ();

Example Usage (use no StringShellQuoting)

String cmdLineText = cmdLine.As<String> (nullopt);

Example Usage (use bash style quoting)

String cmdLineText = cmdLine.As<String> (StringShellQuoting::eBash);

---

The documentation for this class was generated from the following files:

• CommandLine.h
• CommandLine.cpp
• CommandLine.inl