Class Poco::Util::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

const std::string & argumentName() const;

Returns the argument name, if specified.

argumentRequired

bool argumentRequired() const;

Returns true if the argument is required.

binding

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

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

AbstractConfiguration::Ptr config() const;

Returns the configuration, if specified, or NULL otherwise.

description

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

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

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).

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.

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.