<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Class Poco::Util::Option</title> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/> <meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/> <meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/> <meta name="language" content="en"/> <meta name="date" content="2009-11-24"/> <meta name="generator" content="PocoDoc"/> <link rel="stylesheet" href="css/styles.css" type="text/css"/> </head> <body bgcolor="#ffffff" leftmargin="0" topmargin="0"> <div class="header"> <h1 class="namespace"><a href="Poco.Util.html" class="namespace">Poco::Util</a></h1> <h1 class="symbol">class Option</h1> </div> <div class="body"> <p> <b>Library:</b> Util<br /> <b>Package:</b> Options<br /> <b>Header:</b> Poco/Util/Option.h</p> <h2>Description</h2> <div class="description"> <p>This class represents and stores the properties of a command line option. </p> <p>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. </p> <p>An option can be part of an option group. At most one option of each group may be specified on the command line. </p> <p>An option can be bound to a configuration property. In this case, a configuration property will automatically receive the option's argument value. </p> <p>A callback method can be specified for options. This method is called whenever an option is specified on the command line. </p> <p><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> argument values can be automatically validated using a <a href="Poco.Util.Validator.html" title="class Poco::Util::Validator">Validator</a>. </p> <p><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> instances are value objects. </p> <p>Typcally, after construction, an <a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> object is immediately passed to an Options object. </p> <p>An <a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> object can be created by chaining the constructor with any of the setter methods, as in the following example: </p> <p></p> <pre>Option versionOpt("include", "I", "specify an include directory") .required(false) .repeatable(true) .argument("directory"); </pre> </div> <h2>Member Summary</h2> <p><b>Member Functions: </b><a href="Poco.Util.Option.html#16815" title="Poco::Util::Option::argument()">argument</a>, <a href="Poco.Util.Option.html#16837" title="Poco::Util::Option::argumentName()">argumentName</a>, <a href="Poco.Util.Option.html#16836" title="Poco::Util::Option::argumentRequired()">argumentRequired</a>, <a href="Poco.Util.Option.html#16821" title="Poco::Util::Option::binding()">binding</a>, <a href="Poco.Util.Option.html#16826" title="Poco::Util::Option::callback()">callback</a>, <a href="Poco.Util.Option.html#16842" title="Poco::Util::Option::config()">config</a>, <a href="Poco.Util.Option.html#16809" title="Poco::Util::Option::description()">description</a>, <a href="Poco.Util.Option.html#16807" title="Poco::Util::Option::fullName()">fullName</a>, <a href="Poco.Util.Option.html#16819" title="Poco::Util::Option::group()">group</a>, <a href="Poco.Util.Option.html#16845" title="Poco::Util::Option::matchesFull()">matchesFull</a>, <a href="Poco.Util.Option.html#16847" title="Poco::Util::Option::matchesPartial()">matchesPartial</a>, <a href="Poco.Util.Option.html#16843" title="Poco::Util::Option::matchesShort()">matchesShort</a>, <a href="Poco.Util.Option.html#16818" title="Poco::Util::Option::noArgument()">noArgument</a>, <a href="Poco.Util.Option.html#16801" title="Poco::Util::Option::operator =()">operator =</a>, <a href="Poco.Util.Option.html#16849" title="Poco::Util::Option::process()">process</a>, <a href="Poco.Util.Option.html#16813" title="Poco::Util::Option::repeatable()">repeatable</a>, <a href="Poco.Util.Option.html#16811" title="Poco::Util::Option::required()">required</a>, <a href="Poco.Util.Option.html#16805" title="Poco::Util::Option::shortName()">shortName</a>, <a href="Poco.Util.Option.html#16803" title="Poco::Util::Option::swap()">swap</a>, <a href="Poco.Util.Option.html#16835" title="Poco::Util::Option::takesArgument()">takesArgument</a>, <a href="Poco.Util.Option.html#16828" title="Poco::Util::Option::validator()">validator</a></p> <h2>Constructors</h2> <h3><a name="16782">Option</a></h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a>();</p> <div class="description"> <p>Creates an empty <a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a>. </p> </div> <h3><a name="16783">Option</a></h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a>(<br /> const <a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & option<br />);</p> <div class="description"> <p>Creates an option from another one. </p> </div> <h3><a name="16785">Option</a></h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a>(<br /> const std::string & fullName,<br /> const std::string & shortName<br />);</p> <div class="description"> <p>Creates an option with the given properties. </p> </div> <h3><a name="16788">Option</a></h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a>(<br /> const std::string & fullName,<br /> const std::string & shortName,<br /> const std::string & description,<br /> bool required = false<br />);</p> <div class="description"> <p>Creates an option with the given properties. </p> </div> <h3><a name="16793">Option</a></h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a>(<br /> const std::string & fullName,<br /> const std::string & shortName,<br /> const std::string & description,<br /> bool required,<br /> const std::string & argName,<br /> bool argRequired = false<br />);</p> <div class="description"> <p>Creates an option with the given properties. </p> </div> <h2>Destructor</h2> <h3><a name="16800">~Option</a></h3> <p class="decl">~<a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a>();</p> <div class="description"> <p>Destroys the <a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a>. </p> </div> <h2>Member Functions</h2> <h3><a name="16815">argument</a></h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & argument(<br /> const std::string & name,<br /> bool required = true<br />);</p> <div class="description"> <p>Specifies that the option takes an (optional or required) argument. </p> </div> <h3><a name="16837">argumentName</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">const std::string & argumentName() const;</p> <div class="description"> <p>Returns the argument name, if specified. </p> </div> <h3><a name="16836">argumentRequired</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">bool argumentRequired() const;</p> <div class="description"> <p>Returns true if the argument is required. </p> </div> <h3><a name="16821">binding</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & binding(<br /> const std::string & propertyName<br />);</p> <div class="description"> <p>Binds the option to the configuration property with the given name. </p> <p>The configuration will automatically receive the option's argument. </p> </div> <h3><a name="16823">binding</a></h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & binding(<br /> const std::string & propertyName,<br /> <a href="Poco.Util.AbstractConfiguration.html" title="class Poco::Util::AbstractConfiguration">AbstractConfiguration</a> * pConfig<br />);</p> <div class="description"> <p>Binds the option to the configuration property with the given name, using the given <a href="Poco.Util.AbstractConfiguration.html" title="class Poco::Util::AbstractConfiguration">AbstractConfiguration</a>. </p> <p>The configuration will automatically receive the option's argument. </p> </div> <h3><a name="16839">binding</a></h3> <p class="decl">const std::string & binding() const;</p> <div class="description"> <p>Returns the property name the option is bound to, or an empty string in case it is not bound. </p> </div> <h3><a name="16826">callback</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & callback(<br /> const <a href="Poco.Util.AbstractOptionCallback.html" title="class Poco::Util::AbstractOptionCallback">AbstractOptionCallback</a> & cb<br />);</p> <div class="description"> <p>Binds the option to the given method. </p> <p>The callback method will be called when the option has been specified on the command line. </p> <p>Usage: </p> <pre>callback(OptionCallback<MyApplication>(this, &MyApplication::myCallback)); </pre> </div> <h3><a name="16840">callback</a></h3> <p class="decl"><a href="Poco.Util.AbstractOptionCallback.html" title="class Poco::Util::AbstractOptionCallback">AbstractOptionCallback</a> * callback() const;</p> <div class="description"> <p>Returns a pointer to the callback method for the option, or NULL if no callback has been specified. </p> </div> <h3><a name="16842">config</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.AbstractConfiguration.html" title="class Poco::Util::AbstractConfiguration">AbstractConfiguration</a> * config() const;</p> <div class="description"> <p>Returns the configuration, if specified, or NULL otherwise. </p> </div> <h3><a name="16809">description</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & description(<br /> const std::string & text<br />);</p> <div class="description"> <p>Sets the description of the option. </p> </div> <h3><a name="16832">description</a></h3> <p class="decl">const std::string & description() const;</p> <div class="description"> <p>Returns the description of the option. </p> </div> <h3><a name="16807">fullName</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & fullName(<br /> const std::string & name<br />);</p> <div class="description"> <p>Sets the full name of the option. </p> </div> <h3><a name="16831">fullName</a></h3> <p class="decl">const std::string & fullName() const;</p> <div class="description"> <p>Returns the full name of the option. </p> </div> <h3><a name="16819">group</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & group(<br /> const std::string & group<br />);</p> <div class="description"> <p>Specifies the option group the option is part of. </p> </div> <h3><a name="16838">group</a></h3> <p class="decl">const std::string & group() const;</p> <div class="description"> <p>Returns the option group the option is part of, or an empty string, if the option is not part of a group. </p> </div> <h3><a name="16845">matchesFull</a></h3> <p class="decl">bool matchesFull(<br /> const std::string & option<br />) const;</p> <div class="description"> <p>Returns true if the given option string matches the full name. </p> <p>The option string must match the full name (case insensitive). </p> </div> <h3><a name="16847">matchesPartial</a></h3> <p class="decl">bool matchesPartial(<br /> const std::string & option<br />) const;</p> <div class="description"> <p>Returns true if the given option string partially matches the full name. </p> <p>The option string must partially match the full name (case insensitive). </p> </div> <h3><a name="16843">matchesShort</a></h3> <p class="decl">bool matchesShort(<br /> const std::string & option<br />) const;</p> <div class="description"> <p>Returns true if the given option string matches the short name. </p> <p>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). </p> </div> <h3><a name="16818">noArgument</a></h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & noArgument();</p> <div class="description"> <p>Specifies that the option does not take an argument (default). </p> </div> <h3><a name="16801">operator =</a></h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & operator = (<br /> const <a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & option<br />);</p> <div class="description"> <p>Assignment operator. </p> </div> <h3><a name="16849">process</a></h3> <p class="decl">void process(<br /> const std::string & option,<br /> std::string & arg<br />) const;</p> <div class="description"> <p>Verifies that the given option string matches the requirements of the option, and extracts the option argument, if present. </p> <p>If the option string is okay and carries an argument, the argument is returned in arg. </p> <p>Throws a <a href="Poco.Util.MissingArgumentException.html" title="class Poco::Util::MissingArgumentException">MissingArgumentException</a> if a required argument is missing. Throws an <a href="Poco.Util.UnexpectedArgumentException.html" title="class Poco::Util::UnexpectedArgumentException">UnexpectedArgumentException</a> if an argument has been found, but none is expected. </p> </div> <h3><a name="16813">repeatable</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & repeatable(<br /> bool flag<br />);</p> <div class="description"> <p>Sets whether the option can be specified more than once (flag == true) or at most once (flag == false). </p> </div> <h3><a name="16834">repeatable</a></h3> <p class="decl">bool repeatable() const;</p> <div class="description"> <p>Returns true if the option can be specified more than once, or false if at most once. </p> </div> <h3><a name="16811">required</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & required(<br /> bool flag<br />);</p> <div class="description"> <p>Sets whether the option is required (flag == true) or optional (flag == false). </p> </div> <h3><a name="16833">required</a></h3> <p class="decl">bool required() const;</p> <div class="description"> <p>Returns true if the option is required, false if not. </p> </div> <h3><a name="16805">shortName</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & shortName(<br /> const std::string & name<br />);</p> <div class="description"> <p>Sets the short name of the option. </p> </div> <h3><a name="16830">shortName</a></h3> <p class="decl">const std::string & shortName() const;</p> <div class="description"> <p>Returns the short name of the option. </p> </div> <h3><a name="16803">swap</a></h3> <p class="decl">void swap(<br /> <a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & option<br />);</p> <div class="description"> <p>Swaps the option with another one. </p> </div> <h3><a name="16835">takesArgument</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">bool takesArgument() const;</p> <div class="description"> <p>Returns true if the options takes an (optional) argument. </p> </div> <h3><a name="16828">validator</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl"><a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> & validator(<br /> <a href="Poco.Util.Validator.html" title="class Poco::Util::Validator">Validator</a> * pValidator<br />);</p> <div class="description"> <p>Sets the validator for the given option. </p> <p>The <a href="Poco.Util.Option.html" title="class Poco::Util::Option">Option</a> takes ownership of the <a href="Poco.Util.Validator.html" title="class Poco::Util::Validator">Validator</a> and deletes it when it's no longer needed. </p> </div> <h3><a name="16841">validator</a></h3> <p class="decl"><a href="Poco.Util.Validator.html" title="class Poco::Util::Validator">Validator</a> * validator() const;</p> <div class="description"> <p>Returns the option's <a href="Poco.Util.Validator.html" title="class Poco::Util::Validator">Validator</a>, if one has been specified, or NULL otherwise. </p> </div> <p class="footer">POCO C++ Libraries 1.3.6-all<br /> Copyright © 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p> </div> </body> </html>
