From patchwork Wed Jul 7 02:19:14 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 12816 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 0FE6BBD794 for ; Wed, 7 Jul 2021 02:20:40 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id AB30768516; Wed, 7 Jul 2021 04:20:36 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="aTQu08I/"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id ADC5668502 for ; Wed, 7 Jul 2021 04:20:32 +0200 (CEST) Received: from pendragon.lan (62-78-145-57.bb.dnainternet.fi [62.78.145.57]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 2E4F9DEF for ; Wed, 7 Jul 2021 04:20:32 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1625624432; bh=nW8FIUz/LlqWAxKMSXMbQy2iNp4Y62/GLykP65KiCn8=; h=From:To:Subject:Date:In-Reply-To:References:From; b=aTQu08I/+XyLjIKuv1Vk/0n6nSpcMVCxOecWBBfUrw4BxjRHzIAHcO7+sPd8RDONd F4+3L+bmGgLSvnR1TS5ZnkTRSGDQD795t/Qgzfen/zhsDlJbRrZYPk8IJLZsbp4cxK Bs7OW533+KLoeyV6DmV0UK7a+FVfh8QsNjNJMdeg= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Date: Wed, 7 Jul 2021 05:19:14 +0300 Message-Id: <20210707021941.20804-4-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210707021941.20804-1-laurent.pinchart@ideasonboard.com> References: <20210707021941.20804-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 03/30] cam: options: Document the options parser API X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Before extending the option parser, document its existing API. Signed-off-by: Laurent Pinchart --- src/cam/options.cpp | 399 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 399 insertions(+) diff --git a/src/cam/options.cpp b/src/cam/options.cpp index 41968caa0ccb..da218c4644d3 100644 --- a/src/cam/options.cpp +++ b/src/cam/options.cpp @@ -13,10 +13,80 @@ #include "options.h" +/** + * \enum OptionArgument + * \brief Indicate if an option takes an argument + * + * \var OptionArgument::ArgumentNone + * \brief The option doesn't accept any argument + * + * \var OptionArgument::ArgumentRequired + * \brief The option requires an argument + * + * \var OptionArgument::ArgumentOptional + * \brief The option accepts an optional argument + */ + +/** + * \enum OptionType + * \brief The type of argument for an option + * + * \var OptionType::OptionNone + * \brief No argument type, used for options that take no argument + * + * \var OptionType::OptionInteger + * \brief Integer argument type, with an optional base prefix (`0` for base 8, + * `0x` for base 16, none for base 10) + * + * \var OptionType::OptionString + * \brief String argument + * + * \var OptionType::OptionKeyValue + * \brief key=value list argument + */ + /* ----------------------------------------------------------------------------- * Option */ +/** + * \struct Option + * \brief Store metadata about an option + * + * \var Option::opt + * \brief The option identifier + * + * \var Option::type + * \brief The type of the option argument + * + * \var Option::name + * \brief The option name + * + * \var Option::argument + * \brief Whether the option accepts an optional argument, a mandatory + * argument, or no argument at all + * + * \var Option::argumentName + * \brief The argument name used in the help text + * + * \var Option::help + * \brief The help text (may be a multi-line string) + * + * \var Option::keyValueParser + * \brief For options of type OptionType::OptionKeyValue, the key-value parser + * to parse the argument + * + * \var Option::isArray + * \brief Whether the option can appear once or multiple times + * + * \fn Option::hasShortOption() + * \brief Tell if the option has a short option specifier (e.g. `-f`) + * \return True if the option has a short option specifier, false otherwise + * + * \fn Option::hasLongOption() + * \brief Tell if the option has a long option specifier (e.g. `--foo`) + * \return True if the option has a long option specifier, false otherwise + */ struct Option { int opt; OptionType type; @@ -32,6 +102,10 @@ struct Option { const char *typeName() const; }; +/** + * \brief Retrieve a string describing the option type + * \return A string describing the option type + */ const char *Option::typeName() const { switch (type) { @@ -55,24 +129,65 @@ const char *Option::typeName() const * OptionBase */ +/** + * \class template OptionBase + * \brief Container to store the values of parsed options + * \tparam T The type through which options are identified + * + * + * The OptionsBase class is generated by a parser (either OptionsParser or + * KeyValueParser) when parsing options. It stores values for all the options + * found, and exposes accessor functions to retrieve them. The options are + * accessed through an identifier to type \a T, which is an int referencing an + * Option::opt for OptionsParser, or a std::string referencing an Option::name + * for KeyValueParser. + */ + +/** + * \fn OptionsBase::OptionsBase() + * \brief Construct an OptionsBase instance + * + * The constructed instance is initially invalid, and will be populated by the + * options parser. + */ + +/** + * \brief Tell if the stored options list is empty + * \return True if the container is empty, false otherwise + */ template bool OptionsBase::empty() const { return values_.empty(); } +/** + * \brief Tell if the options parsing completed successfully + * \return True if the container is returned after successfully parsing + * options, false if it is returned after an error was detected during parsing + */ template bool OptionsBase::valid() const { return valid_; } +/** + * \brief Tell if the option \a opt is specified + * \param[in] opt The option to search for + * \return True if the \a opt option is set, false otherwise + */ template bool OptionsBase::isSet(const T &opt) const { return values_.find(opt) != values_.end(); } +/** + * \brief Retrieve the value of option \a opt + * \param[in] opt The option to retrieve + * \return The value of option \a opt if found, an empty OptionValue otherwise + */ template const OptionValue &OptionsBase::operator[](const T &opt) const { @@ -84,6 +199,13 @@ const OptionValue &OptionsBase::operator[](const T &opt) const return empty; } +/** + * \brief Mark the container as invalid + * + * This function can be used in a key-value parser's override of the + * KeyValueParser::parse() function to mark the returned options as invalid if + * a validation error occurs. + */ template void OptionsBase::invalidate() { @@ -144,9 +266,46 @@ template class OptionsBase; * KeyValueParser */ +/** + * \class KeyValueParser + * \brief A specialized parser for list of key-value pairs + * + * The KeyValueParser is an options parser for comma-separated lists of + * `key=value` pairs. The supported keys are added to the parser with + * addOption(). A given key can only appear once in the parsed list. + * + * Instances of this class can be passed to the OptionsParser::addOption() + * function to create options that take key-value pairs as an option argument. + * Specialized versions of the key-value parser can be created by inheriting + * from this class, to pre-build the options list in the constructor, and to add + * custom validation by overriding the parse() function. + */ + +/** + * \class KeyValueParser::Options + * \brief An options list generated by the key-value parser + * + * This is a specialization of OptionsBase with the option reference type set to + * std::string. + */ + KeyValueParser::KeyValueParser() = default; KeyValueParser::~KeyValueParser() = default; +/** + * \brief Add a supported option to the parser + * \param[in] name The option name, corresponding to the key name in the + * key=value pair. The name shall be unique. + * \param[in] type The type of the value in the key=value pair + * \param[in] help The help text + * \param[in] argument Whether the value is optional, mandatory or not allowed. + * Shall be ArgumentNone if \a type is OptionNone. + * + * \sa OptionsParser + * + * \return True if the option was added successfully, false if an error + * occurred. + */ bool KeyValueParser::addOption(const char *name, OptionType type, const char *help, OptionArgument argument) { @@ -166,6 +325,17 @@ bool KeyValueParser::addOption(const char *name, OptionType type, return true; } +/** + * \brief Parse a string containing a list of key-value pairs + * \param[in] arguments The key-value pairs string to parse + * + * If a parsing error occurs, the parsing stops and the function returns an + * invalid container. The container is populated with the options successfully + * parsed so far. + * + * \return A valid container with the list of parsed options on success, or an + * invalid container otherwise + */ KeyValueParser::Options KeyValueParser::parse(const char *arguments) { Options options; @@ -278,31 +448,98 @@ void KeyValueParser::usage(int indent) * OptionValue */ +/** + * \class OptionValue + * \brief Container to store the value of an option + * + * The OptionValue class is a variant-type container to store the value of an + * option. It supports empty values, integers, strings, key-value lists, as well + * as arrays of those types. For array values, all array elements shall have the + * same type. + */ + +/** + * \enum OptionValue::ValueType + * \brief The option value type + * + * \var OptionValue::ValueType::ValueNone + * \brief Empty value + * + * \var OptionValue::ValueType::ValueInteger + * \brief Integer value (int) + * + * \var OptionValue::ValueType::ValueString + * \brief String value (std::string) + * + * \var OptionValue::ValueType::ValueKeyValue + * \brief Key-value list value (KeyValueParser::Options) + * + * \var OptionValue::ValueType::ValueArray + * \brief Array value + */ + +/** + * \brief Construct an empty OptionValue instance + * + * The value type is set to ValueType::ValueNone. + */ OptionValue::OptionValue() : type_(ValueNone), integer_(0) { } +/** + * \brief Construct an integer OptionValue instance + * \param[in] value The integer value + * + * The value type is set to ValueType::ValueInteger. + */ OptionValue::OptionValue(int value) : type_(ValueInteger), integer_(value) { } +/** + * \brief Construct a string OptionValue instance + * \param[in] value The string value + * + * The value type is set to ValueType::ValueString. + */ OptionValue::OptionValue(const char *value) : type_(ValueString), integer_(0), string_(value) { } +/** + * \brief Construct a string OptionValue instance + * \param[in] value The string value + * + * The value type is set to ValueType::ValueString. + */ OptionValue::OptionValue(const std::string &value) : type_(ValueString), integer_(0), string_(value) { } +/** + * \brief Construct a key-value OptionValue instance + * \param[in] value The key-value list + * + * The value type is set to ValueType::ValueKeyValue. + */ OptionValue::OptionValue(const KeyValueParser::Options &value) : type_(ValueKeyValue), integer_(0), keyValues_(value) { } +/** + * \brief Add an entry to an array value + * \param[in] value The entry value + * + * This function can only be called if the OptionValue type is + * ValueType::ValueNone or ValueType::ValueArray. Upon return, the type will be + * set to ValueType::ValueArray. + */ void OptionValue::addValue(const OptionValue &value) { assert(type_ == ValueNone || type_ == ValueArray); @@ -311,26 +548,57 @@ void OptionValue::addValue(const OptionValue &value) array_.push_back(value); } +/** + * \fn OptionValue::type() + * \brief Retrieve the value type + * \return The value type + */ + +/** + * \brief Cast the value to an int + * \return The option value as an int, or 0 if the value type isn't + * ValueType::ValueInteger + */ OptionValue::operator int() const { return toInteger(); } +/** + * \brief Cast the value to a std::string + * \return The option value as an std::string, or an empty string if the value + * type isn't ValueType::ValueString + */ OptionValue::operator std::string() const { return toString(); } +/** + * \brief Cast the value to a key-value list + * \return The option value as a KeyValueParser::Options, or an empty list if + * the value type isn't ValueType::ValueKeyValue + */ OptionValue::operator KeyValueParser::Options() const { return toKeyValues(); } +/** + * \brief Cast the value to an array + * \return The option value as a std::vector of OptionValue, or an empty vector + * if the value type isn't ValueType::ValueArray + */ OptionValue::operator std::vector() const { return toArray(); } +/** + * \brief Retrieve the value as an int + * \return The option value as an int, or 0 if the value type isn't + * ValueType::ValueInteger + */ int OptionValue::toInteger() const { if (type_ != ValueInteger) @@ -339,6 +607,11 @@ int OptionValue::toInteger() const return integer_; } +/** + * \brief Retrieve the value as a std::string + * \return The option value as a std::string, or an empty string if the value + * type isn't ValueType::ValueString + */ std::string OptionValue::toString() const { if (type_ != ValueString) @@ -347,6 +620,11 @@ std::string OptionValue::toString() const return string_; } +/** + * \brief Retrieve the value as a key-value list + * \return The option value as a KeyValueParser::Options, or an empty list if + * the value type isn't ValueType::ValueKeyValue + */ KeyValueParser::Options OptionValue::toKeyValues() const { if (type_ != ValueKeyValue) @@ -355,6 +633,11 @@ KeyValueParser::Options OptionValue::toKeyValues() const return keyValues_; } +/** + * \brief Retrieve the value as an array + * \return The option value as a std::vector of OptionValue, or an empty vector + * if the value type isn't ValueType::ValueArray + */ std::vector OptionValue::toArray() const { if (type_ != ValueArray) @@ -367,9 +650,91 @@ std::vector OptionValue::toArray() const * OptionsParser */ +/** + * \class OptionsParser + * \brief A command line options parser + * + * The OptionsParser class is an easy to use options parser for POSIX-style + * command line options. Supports short (e.g. `-f`) and long (e.g. `--foo`) + * options, optional and mandatory arguments, automatic parsing arguments for + * integer types and comma-separated list of key=value pairs, and multi-value + * arguments. It handles help text generation automatically. + * + * An OptionsParser instance is initialized by adding supported options with + * addOption(). Options are specified by an identifier and a name. If the + * identifier is an alphanumeric character, it will be used by the parser as a + * short option identifier (e.g. `-f`). The name, if specified, will be used as + * a long option identifier (e.g. `--foo`). It should not include the double + * dashes. The name is optional if the option identifier is an alphanumeric + * character and mandatory otherwise. + * + * An options has a mandatory help text, which is used to print the full options + * list with the usage() function. The help text may be a multi-line string. + * Correct indentation of the help text is handled automatically. + * + * Options accept arguments when created with OptionArgument::ArgumentRequired + * or OptionArgument::ArgumentOptional. If the argument is required, it can be + * specified as a positional argument after the option (e.g. `-f bar`, + * `--foo bar`), collated with the short option (e.g. `-fbar`) or separated from + * the long option by an equal sign (e.g. `--foo=bar`'). When the argument is + * optional, it must be collated with the short option or separated from the + * long option by an equal sign. + * + * If an option has a required or optional argument, an argument name must be + * set when adding the option. The argument name is used in the help text as a + * place holder for an argument value. For instance, a `--write` option that + * takes a file name as an argument could set the argument name to `filename`, + * and the help text would display `--write filename`. This is only used to + * clarify the help text and has no effect on option parsing. + * + * The option type tells the parser how to process the argument. Arguments for + * string options (OptionType::OptionString) are stored as-is without any + * processing. Arguments for integer options (OptionType::OptionInteger) are + * converted to an integer value, using an optional base prefix (`0` for base 8, + * `0x` for base 16, none for base 10). Arguments for key-value options are + * parsed by a KeyValueParser given to addOption(). + * + * By default, a given option can appear once only in the parsed command line. + * If the option is created as an array option, the parser will accept multiple + * instances of the option. The order in which identical options are specified + * is preserved in the values of an array option. + * + * After preparing the parser, it can be used any number of times to parse + * command line options with the parse() function. The function returns an + * Options instance that stores the values for the parsed options. The + * Options::isSet() function can be used to test if an option has been found, + * and is the only way to access options that take no argument (specified by + * OptionType::OptionNone and OptionArgument::ArgumentNone). For options that + * accept an argument, the option value can be access by Options::operator[]() + * using the option identifier as the key. The order in which different options + * are specified on the command line isn't preserved. + */ + +/** + * \class OptionsParser::Options + * \brief An options list generated by the options parser + * + * This is a specialization of OptionsBase with the option reference type set to + * int. + */ + OptionsParser::OptionsParser() = default; OptionsParser::~OptionsParser() = default; +/** + * \brief Add an option to the parser + * \param[in] opt The option identifier + * \param[in] type The type of the option argument + * \param[in] help The help text (may be a multi-line string) + * \param[in] name The option name + * \param[in] argument Whether the option accepts an optional argument, a + * mandatory argument, or no argument at all + * \param[in] argumentName The argument name used in the help text + * \param[in] array Whether the option can appear once or multiple times + * + * \return True if the option was added successfully, false if an error + * occurred. + */ bool OptionsParser::addOption(int opt, OptionType type, const char *help, const char *name, OptionArgument argument, const char *argumentName, bool array) @@ -395,6 +760,19 @@ bool OptionsParser::addOption(int opt, OptionType type, const char *help, return true; } +/** + * \brief Add a key-value pair option to the parser + * \param[in] opt The option identifier + * \param[in] parser The KeyValueParser for the option value + * \param[in] help The help text (may be a multi-line string) + * \param[in] name The option name + * \param[in] array Whether the option can appear once or multiple times + * + * \sa Option + * + * \return True if the option was added successfully, false if an error + * occurred. + */ bool OptionsParser::addOption(int opt, KeyValueParser *parser, const char *help, const char *name, bool array) { @@ -406,6 +784,19 @@ bool OptionsParser::addOption(int opt, KeyValueParser *parser, const char *help, return true; } +/** + * \brief Parse command line arguments + * \param[in] argc The number of arguments in the \a argv array + * \param[in] argv The array of arguments + * + * If a parsing error occurs, the parsing stops, the function prints an error + * message that identifies the invalid argument, prints usage information with + * usage(), and returns an invalid container. The container is populated with + * the options successfully parsed so far. + * + * \return A valid container with the list of parsed options on success, or an + * invalid container otherwise + */ OptionsParser::Options OptionsParser::parse(int argc, char **argv) { OptionsParser::Options options; @@ -485,6 +876,14 @@ OptionsParser::Options OptionsParser::parse(int argc, char **argv) return options; } +/** + * \brief Print usage text to std::cerr + * + * The usage text list all the supported option with their arguments. It is + * generated automatically from the options added to the parser. Caller of this + * function may print additional usage information for the application before + * the list of options. + */ void OptionsParser::usage() { std::cerr << "Options:" << std::endl;