ArgParseOption - SeqAn API Documentation

# Spec ArgParseOption
Store information for a specific command line option.

Extends | ArgParseArgument
All Extended | ArgParseArgument
All Impl'd | AssignableConcept
Defined in | <seqan/arg_parse.h>
Signature | `class ArgParseOption : ArgParseArgument;`

## Member Function Overview

- `ArgParseOption::ArgParseOption(shortName, longName, helpText, argumentType[, argumentLabel[, isList[, numValues]]]);`
  Constructor.

### Member Functions Inherited From ArgParseArgument

- `ArgParseArgument`

### Member Functions Inherited From AssignableConcept

- `operator=`

## Interface Function Overview

- `void setDefaultValue(option, v);`
  Adds/appends a new value to the list of default values.
- `std::string getArgumentLabel(option);`
  Returns the argument label.
- `std::string getOptionName(option);`
  Returns the name of the ArgParseOption in a well-formatted way.
- `void hideOption(option[, hide]);`
  Hides the ArgParseOption from the help screen (or shows it again).
- `bool isAdvanced(option);`
  Return whether an option is only shown in the full help screen.
- `bool isFlagOption(option);`
  Returns whether an option is a flag.
- `bool isHidden(option);`
  Return whether an option is hidden on the help screen.
- `bool isRequired(option);`
  Returns whether the option is mandatory.
- `void setAdvanced(option[, advanced]);`
  Shows the ArgParseOption only on the full help screen.
- `void setDefaultValue(option, v);`
  Set the default value for the given option.
- `void setRequired(option, required);`
  Sets whether or not the option is mandatory.
- `void write(stream, option);`
  Writes the basic informationa bout the ArgParseOption to the provided stream.

### Interface Functions Inherited From ArgParseArgument

- `getArgumentLabel`
- `getArgumentType`
- `getArgumentTypeAsString`
- `getArgumentValue`
- `getArgumentValues`
- `getFileExtension`
- `hasArgumentValue`
- `hasDefault`
- `isBooleanArgument`
- `isDirectoryArgument`
- `isDoubleArgument`
- `isInputFileArgument`
- `isInputPrefixArgument`
- `isInt64Argument`
- `isIntegerArgument`
- `isListArgument`
- `isOutputFileArgument`
- `isOutputPrefixArgument`
- `isSet`
- `isStringArgument`
- `isUInt64Argument`
- `numberOfAllowedValues`
- `setHelpText`
- `setMaxValue`
- `setMinValue`
- `setValidValues`

### Interface Functions Inherited From AssignableConcept

- `assign`
- `set`
- `move`

## Detailed Description

You can use the shortcut addOption for adding options to ArgumentParser object.

## Member Functions Detail

### `ArgParseOption::ArgParseOption(shortName, longName, helpText, argumentType[, argumentLabel[, isList[, numValues]]]);`

Constructor.

#### Parameters

`shortName` | The short name of the argument.
`longName` | The long name of the argument (`std::string`).
`helpText` | The text to display as help (`std::string`).
`argumentType` | The type of the argument (ArgParseArgument::ArgumentType).
`argumentLabel` | The label for the value to use in the help display, e.g. 'INT' in '--value INT' (`std::string`).
`isList` | Flag for whether this option can be given multiple times (`bool`, `true` for allowing multiple values).
`numValues` | Number of command line arguments that each option should bind (`unsigned`).

#### Short and Long Option Names

Short option names are passed to the program following one dash (e.g. '-i', '-e'). Long optiongs are passed following two dashes (e.g. '--num-threads', '--error-rate'). The leading one or two dashes are not passed to the constructor of ArgParseOption, however.

#### Naming Conventions

- Keep the short name short, ideally to one character.
- Only use lower-case characters in the long name, use dashes to separate words, only use alphanumeric characters and dashes, no underline characters
.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

## Interface Functions Detail

### `void setDefaultValue(option, v);`

Adds/appends a new value to the list of default values.

#### Parameters

`option` | The ArgParseOption to appen the default value for.
`v` | The value to append, (any type that can be streamed into an `std::stringstream`).

#### Remarks

This function does not check any length restrictions for this value.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `std::string getArgumentLabel(option);`

Returns the argument label.

#### Parameters

`option` | The ArgParseOption object to query.

#### Returns

`std::string` | The argument label string.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `std::string getOptionName(option);`

Returns the name of the ArgParseOption in a well-formatted way.

#### Parameters

`option` | The ArgParseOption object to query.

#### Returns

`std::string` | The option name string.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void hideOption(option[, hide]);`

Hides the ArgParseOption from the help screen (or shows it again).

#### Parameters

`option` | The ArgParseOption object to set the hidden flag of.
`hide` | `bool` that indicates whether to hide the flag (default: `true`)

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool isAdvanced(option);`

Return whether an option is only shown in the full help screen.

#### Parameters

`option` | The ArgParseOption object to query.

#### Returns

`bool` | `true` if it is hidden, `false` otherwise.

By default, options are not marked as advanced.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool isFlagOption(option);`

Returns whether an option is a flag.

#### Parameters

`option` | The ArgParseOption object to query.

#### Returns

`bool` | `true` if `option` is a flag/switch and `false` otherwise.

Flags are given without arguments, e.g. the `-l` flag in the Unix `ls` command.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool isHidden(option);`

Return whether an option is hidden on the help screen.

#### Parameters

`option` | The ArgParseOption object to query.

#### Returns

`bool` | `true` if it is hidden, `false` otherwise.

By default, options are not hidden.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool isRequired(option);`

Returns whether the option is mandatory.

#### Parameters

`option` | The ArgParseOption object to query.

#### Returns

`bool` | `true` if the option is mandatory and `false` if it not.

By default, options are not mandatory.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void setAdvanced(option[, advanced]);`

Shows the ArgParseOption only on the full help screen.

#### Parameters

`option` | The ArgParseOption object to set the advanced flag of.
`advanced` | `bool` that indicates whether to hide the flag (default: `true`)

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void setDefaultValue(option, v);`

Set the default value for the given option.

#### Parameters

`option` | The ArgParseOption to set the default value for.
`v` | The value to set, (any type that can be streamed into an `std::stringstream`).

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void setRequired(option, required);`

Sets whether or not the option is mandatory.

#### Parameters

`option` | The ArgParseOption to modify.
`required` | Flag whether the option is mandatory (`bool`).

By default, options are not mandatory.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void write(stream, option);`

Writes the basic informationa bout the ArgParseOption to the provided stream.

#### Parameters

`stream` | The stream to write to.
`option` | The ArgParseOption object to write to `stream`.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### Dox Sources

    /*!
     * @class ArgParseOption
     *
     * @extends ArgParseArgument
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Store information for a specific command line option.
     *
     * @signature class ArgParseOption : ArgParseArgument;
     *
     * You can use the shortcut @link ArgumentParser#addOption @endlink for adding
     * options to @link ArgumentParser @endlink object.
     *
     * @fn ArgParseOption::ArgParseOption
     *
     * @brief Constructor.
     *
     * @signature ArgParseOption::ArgParseOption(shortName, longName, helpText,
     *            argumentType[, argumentLabel[, isList[, numValues]]]);
     *
     * @param[in] shortName The short name of the argument.
     * @param[in] longName The long name of the argument (<tt>std::string</tt>).
     * @param[in] helpText The text to display as help (<tt>std::string</tt>).
     * @param[in] argumentType The type of the argument (@link
     *                         ArgParseArgument::ArgumentType @endlink).
     * @param[in] argumentLabel The label for the value to use in the help display,
     *                          e.g. 'INT' in '--value INT' (<tt>std::string</tt>).
     * @param[in] isList Flag for whether this option can be given multiple times
     *                   (<tt>bool</tt>, <tt>true</tt> for allowing multiple
     *                   values).
     * @param[in] numValues Number of command line arguments that each option should
     *                      bind (<tt>unsigned</tt>).
     *
     * @section Short and Long Option Names
     *
     * Short option names are passed to the program following one dash (e.g. '-i',
     * '-e'). Long optiongs are passed following two dashes (e.g. '--num-threads', '
     * --error-rate'). The leading one or two dashes are not passed to the
     * constructor of ArgParseOption, however.
     *
     * @section Naming Conventions
     *
     * <ul> <li>Keep the short name short, ideally to one character.</li> <li>Only
     * use lower-case characters in the long name, use dashes to separate words,
     * only use alphanumeric characters and dashes, no underline characters</li>.
     * </ul>
     *
     * @fn ArgParseOption#isFlagOption
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Returns whether an option is a flag.
     *
     * @signature bool isFlagOption(option);
     *
     * @param[in] option The ArgParseOption object to query.
     *
     * @return bool <tt>true</tt> if <tt>option</tt> is a flag/switch and
     *              <tt>false</tt> otherwise.
     *
     * Flags are given without arguments, e.g. the <tt>-l</tt> flag in the Unix
     * <tt>ls</tt> command.
     *
     * @fn ArgParseOption#isHidden
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Return whether an option is hidden on the help screen.
     *
     * @signature bool isHidden(option);
     *
     * @param[in] option The ArgParseOption object to query.
     *
     * @return bool <tt>true</tt> if it is hidden, <tt>false</tt> otherwise.
     *
     * By default, options are not hidden.
     *
     * @fn ArgParseOption#hideOption
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Hides the ArgParseOption from the help screen (or shows it again).
     *
     * @signature void hideOption(option[, hide]);
     *
     * @param[in,out] option The ArgParseOption object to set the hidden flag of.
     * @param[in] hide <tt>bool</tt> that indicates whether to hide the flag
     *                 (default: <tt>true</tt>)
     *
     * @fn ArgParseOption#isAdvanced
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Return whether an option is only shown in the full help screen.
     *
     * @signature bool isAdvanced(option);
     *
     * @param[in] option The ArgParseOption object to query.
     *
     * @return bool <tt>true</tt> if it is hidden, <tt>false</tt> otherwise.
     *
     * By default, options are not marked as advanced.
     *
     * @fn ArgParseOption#setAdvanced
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Shows the ArgParseOption only on the full help screen.
     *
     * @signature void setAdvanced(option[, advanced]);
     *
     * @param[in,out] option The ArgParseOption object to set the advanced flag of.
     * @param[in] advanced <tt>bool</tt> that indicates whether to hide the flag
     *                     (default: <tt>true</tt>)
     *
     * @fn ArgParseOption#isRequired
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Returns whether the option is mandatory.
     *
     * @signature bool isRequired(option);
     *
     * @param[in] option The ArgParseOption object to query.
     *
     * @return bool <tt>true</tt> if the option is mandatory and <tt>false</tt> if
     *              it not.
     *
     * By default, options are not mandatory.
     *
     * @fn ArgParseOption#setDefaultValue
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set the default value for the given option.
     *
     * @signature void setDefaultValue(option, v);
     *
     * @param[in,out] option The ArgParseOption to set the default value for.
     * @param[in] v The value to set, (any type that can be streamed into an
     *              <tt>std::stringstream</tt>).
     *
     * @fn ArgParseOption#addDefaultValue
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Adds/appends a new value to the list of default values.
     *
     * @signature void setDefaultValue(option, v);
     *
     * @param[in,out] option The ArgParseOption to appen the default value for.
     * @param[in] v The value to append, (any type that can be streamed into an
     *              <tt>std::stringstream</tt>).
     *
     * @section Remarks
     *
     * This function does not check any length restrictions for this value.
     *
     * @fn ArgParseOption#setRequired
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Sets whether or not the option is mandatory.
     *
     * @signature void setRequired(option, required);
     *
     * @param[in,out] option The ArgParseOption to modify.
     * @param[in] required Flag whether the option is mandatory (<tt>bool</tt>).
     *
     * By default, options are not mandatory.
     *
     * @fn ArgParseOption#getArgumentLabel
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Returns the argument label.
     *
     * @signature std::string getArgumentLabel(option);
     *
     * @param[in] option The ArgParseOption object to query.
     *
     * @return std::string The argument label string.
     *
     * @fn ArgParseOption#getOptionName
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Returns the name of the ArgParseOption in a well-formatted way.
     *
     * @signature std::string getOptionName(option);
     *
     * @param[in] option The ArgParseOption object to query.
     *
     * @return std::string The option name string.
     *
     * @fn ArgParseOption#write
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Writes the basic informationa bout the ArgParseOption to the provided
     *        stream.
     *
     * @signature void write(stream, option);
     *
     * @param[in,out] stream The @link StreamConcept stream @endlink to write to.
     * @param[out] option The ArgParseOption object to write to <tt>stream</tt>.
     */