Poco::Util

class Option

File Information

Library: Util
Package: Options
Header: Poco/Util/Option.h

Description

This class represents and stores the properties of a command line option.

An option has a full name, an optional short name, a description (used for printing a usage statement), and an optional argument name. An option can be optional or required. An option can be repeatable, which means that it can be given more than once on the command line.

An option can be part of an option group. At most one option of each group may be specified on the command line.

An option can be bound to a configuration property. In this case, a configuration property will automatically receive the option's argument value.

A callback method can be specified for options. This method is called whenever an option is specified on the command line.

Option argument values can be automatically validated using a Validator.

Option instances are value objects.

Typically, after construction, an Option object is immediately passed to an Options object.

An Option object can be created by chaining the constructor with any of the setter methods, as in the following example: 

Option versionOpt("include", "I", "specify an include directory")
   .required(false)
   .repeatable(true)
   .argument("directory");

Member Summary

Member Functions: argument, argumentName, argumentRequired, binding, callback, config, description, fullName, group, matchesFull, matchesPartial, matchesShort, noArgument, operator =, process, repeatable, required, shortName, swap, takesArgument, validator

Constructors

Option

Option();

Creates an empty Option.

Option

Option(
    const Option & option
);

Creates an option from another one.

Option

Option(
    const std::string & fullName,
    const std::string & shortName
);

Creates an option with the given properties.

Option

Option(
    const std::string & fullName,
    const std::string & shortName,
    const std::string & description,
    bool required = false
);

Creates an option with the given properties.

Option

Option(
    const std::string & fullName,
    const std::string & shortName,
    const std::string & description,
    bool required,
    const std::string & argName,
    bool argRequired = false
);

Creates an option with the given properties.

Destructor

~Option

~Option();

Destroys the Option.

Member Functions

argument

Option & argument(
    const std::string & name,
    bool required = true
);

Specifies that the option takes an (optional or required) argument.

argumentName inline

const std::string & argumentName() const;

Returns the argument name, if specified.

argumentRequired inline

bool argumentRequired() const;

Returns true if the argument is required.

binding inline

Option & binding(
    const std::string & propertyName
);

Binds the option to the configuration property with the given name.

The configuration will automatically receive the option's argument.

binding

Option & binding(
    const std::string & propertyName,
    AbstractConfiguration::Ptr pConfig
);

Binds the option to the configuration property with the given name, using the given AbstractConfiguration.

The configuration will automatically receive the option's argument.

binding

const std::string & binding() const;

Returns the property name the option is bound to, or an empty string in case it is not bound.

callback inline

Option & callback(
    const AbstractOptionCallback & cb
);

Binds the option to the given method.

The callback method will be called when the option has been specified on the command line.

Usage: 

callback(OptionCallback<MyApplication>(this, &MyApplication::myCallback));

callback

AbstractOptionCallback * callback() const;

Returns a pointer to the callback method for the option, or NULL if no callback has been specified.

config inline

AbstractConfiguration::Ptr config() const;

Returns the configuration, if specified, or NULL otherwise.

description inline

Option & description(
    const std::string & text
);

Sets the description of the option.

description

const std::string & description() const;

Returns the description of the option.

fullName inline

Option & fullName(
    const std::string & name
);

Sets the full name of the option.

fullName

const std::string & fullName() const;

Returns the full name of the option.

group inline

Option & group(
    const std::string & group
);

Specifies the option group the option is part of.

group

const std::string & group() const;

Returns the option group the option is part of, or an empty string, if the option is not part of a group.

matchesFull

bool matchesFull(
    const std::string & option
) const;

Returns true if the given option string matches the full name.

The option string must match the full name (case insensitive).

matchesPartial

bool matchesPartial(
    const std::string & option
) const;

Returns true if the given option string partially matches the full name.

The option string must partially match the full name (case insensitive).

matchesShort

bool matchesShort(
    const std::string & option
) const;

Returns true if the given option string matches the short name.

The first characters of the option string must match the short name of the option (case sensitive), or the option string must partially match the full name (case insensitive).

noArgument

Option & noArgument();

Specifies that the option does not take an argument (default).

operator =

Option & operator = (
    const Option & option
);

Assignment operator.

process

void process(
    const std::string & option,
    std::string & arg
) const;

Verifies that the given option string matches the requirements of the option, and extracts the option argument, if present.

If the option string is okay and carries an argument, the argument is returned in arg.

Throws a MissingArgumentException if a required argument is missing. Throws an UnexpectedArgumentException if an argument has been found, but none is expected.

repeatable inline

Option & repeatable(
    bool flag
);

Sets whether the option can be specified more than once (flag == true) or at most once (flag == false).

repeatable

bool repeatable() const;

Returns true if the option can be specified more than once, or false if at most once.

required inline

Option & required(
    bool flag
);

Sets whether the option is required (flag == true) or optional (flag == false).

required

bool required() const;

Returns true if the option is required, false if not.

shortName inline

Option & shortName(
    const std::string & name
);

Sets the short name of the option.

shortName

const std::string & shortName() const;

Returns the short name of the option.

swap

void swap(
    Option & option
) noexcept;

Swaps the option with another one.

takesArgument inline

bool takesArgument() const;

Returns true if the options takes an (optional) argument.

validator inline

Option & validator(
    Validator * pValidator
);

Sets the validator for the given option.

The Option takes ownership of the Validator and deletes it when it's no longer needed.

validator

Validator * validator() const;

Returns the option's Validator, if one has been specified, or NULL otherwise.