diff options
Diffstat (limited to 'libplatform/prog/option.h')
| -rw-r--r-- | libplatform/prog/option.h | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/libplatform/prog/option.h b/libplatform/prog/option.h new file mode 100644 index 0000000..9f7a82a --- /dev/null +++ b/libplatform/prog/option.h @@ -0,0 +1,174 @@ +#ifndef MP4V2_PLATFORM_PROG_OPTION_H +#define MP4V2_PLATFORM_PROG_OPTION_H + +/////////////////////////////////////////////////////////////////////////////// +/// +/// @namespace mp4v2::platform::prog Command-line argument parsing. +/// <b>WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.</b> +/// +/// This namespace provides a mechanism to parse command-line arguments and +/// options for executables. +/// It is identical in behavior to <b>getopt_long</b> functions available +/// with many popular posix-platforms such as Darwin, FreeBSD and Linux. +/// Virtually any OS which has getopt_long will adequately document this +/// functionality. However, to avoid symbol ambiguity with the popular +/// posix implementation, the following identifiers have been renamed: +/// @li getopt_long() -> getOption() +/// @li getopt_long_only() -> getOptionSingle() +/// @li option -> Option +/// @li option.has_arg -> Option.type +//! +/////////////////////////////////////////////////////////////////////////////// +namespace mp4v2 { namespace platform { namespace prog { + +//! On return from getOption() or getOptionSingle(), +//! points to an option argument, if it is anticipated. +MP4V2_EXPORT extern const char* optarg; + +//! On return from getOption() or getOptionSingle(), +//! contains the index to the next argv argument for a subsequent call to +//! getOption() or getOptionSingle(). +//! Initialized to 1 and must be set manually to 1 prior to invoking +//! getOption() or getOptionSingle() to evaluate multiple sets of arguments. +MP4V2_EXPORT extern int optind; + +//! On return from getOption() or getOptionSingle(), +//! saves the last known option character returned by +//! getOption() or getOptionSingle(). +//! On error, contains the character/code of option which caused error. +MP4V2_EXPORT extern int optopt; + +//! Initialized to 1 and may be set to 0 to disable error messages. +MP4V2_EXPORT extern int opterr; + +//! Must be set to 1 before evaluating the 2nd or each additional set +//! of arguments. +MP4V2_EXPORT extern int optreset; + +//! Structure describing a single option. +//! An instance of Option is required for each program option and is +//! initialized before use with getOption() or getOptionWord(). +struct MP4V2_EXPORT Option +{ + //! expectation-type indicating number of arguments expected + //! on the command-line following the option-argument itself + enum Type { + //! indicates exactly 0 arguments follow option + NO_ARG, + //! indicates exactly 1 argument follow option + REQUIRED_ARG, + //! indicates 0 or 1 arguments follow option + OPTIONAL_ARG, + }; + + //! contains the option name without leading double-dash + const char* name; + + //! option expectation-type + Type type; + + //! If not NULL, then the integer pointed to by it will be set to + //! the value in the val field. If the flag field is NULL, then the + //! <b>val</b> field will be returned. + int* flag; + + //! Constant value representing option. This is usually a single-char + //! ASCII value but in case of long-options without a corresponding + //! single-char value it can be a unique integer (beyond ASCII range) + //! which represents the long-option. + int val; +}; + +/////////////////////////////////////////////////////////////////////////////// +//! +//! Get option character from command line argument list. +//! +//! getOption() is similar to posix getopt() but it accepts options in two +//! forms: words and characters. The getOption() function provides a +//! superset of the functionality of getopt(). The getOption() function can +//! be used in two ways. In the first way, every long-option understood by +//! the program has a corresponding short-option, and the Option structure +//! is only used to translate from long-options to short-options. When used +//! in this fashion, getOption() behaves identically to getopt(). This is +//! a good way to add long-option processing to an esxisting program with +//! a minimum of rewriting. +//! +//! In the second mechanism, a long-option sets a flag in the Option +//! structure structure passed, or will store a pointer to the command line +//! argument in the Option structure passed to it for options that take +//! arguments. Additionally, the long-option's argument may be specified as +//! a single argument with an equal sign, eg: +//! @code myprogram --myoption=somevalue +//! @endcode +//! +//! When a long-option is processed, the call to getOption() will return 0. +//! For this reason, long-option processing without shortcuts is not +//! backwards compatible with getopt(). +//! +//! It is possible to combine these methods, providing for long-options +//! processing with short-option equivalents for some options. Less +//! frequently used options would be processed as long-options only. +//! +//! @param argc number of arguments. +//! @param argv argument array of strings. +//! @param optstr string containing the following elements: +//! individual characters, and characters followed by a colon to indicate +//! an option argument is to follow. For example, an option string "x" +//! recognizes an option "-x", and an option string "x:" recognizes an +//! option and argument "-x argument". +//! @param longopts array of Option entries. The last element must be filled +//! with zeroes to indicate end-of-array. +//! @param idx If not NULL, then the integer pointed to it will be set to +//! the index of the long-option relative to <b>longops</b>. +//! +//! @return If the <b>flag</b> field is NULL, <b>val</b> field is returned, +//! which is usually just the corresponding short-option. +//! If <b>flag</b> is not NULL, 0 is returned and <b>val</b> is +//! stored in the location pointed to by <b>flag</b> field. +//! A ':' will be returned if there was a missing option argument. +//! A '?' will be returned if an unknown or ambiguous option was used. +//! A -1 will be returned when the argument list has been exhausted. +//! +/////////////////////////////////////////////////////////////////////////////// +MP4V2_EXPORT +int getOption( int argc, char* const* argv, const char* optstr, const Option* longopts, int* idx ); + +/////////////////////////////////////////////////////////////////////////////// +//! +//! Get option character from command line argument list and allow +//! long-options with single-hyphens. +//! +//! Behaves identically to getOption() with the exception that long-options +//! may start with '-' in addition to '--'. +//! If an option starting with '-' does not match a long option but does match +//! a single-character option, the single-character option is returned. +//! +//! @param argc number of arguments. +//! @param argv argument array of strings. +//! @param optstr string containing the following elements: +//! individual characters, and characters followed by a colon to indicate +//! an option argument is to follow. For example, an option string "x" +//! recognizes an option "-x", and an option string "x:" recognizes an +//! option and argument "-x argument". +//! @param longopts array of Option entries. The last element must be filled +//! with zeroes to indicate end-of-array. +//! @param idx If not NULL, then the integer pointed to it will be set to +//! the index of the long-option relative to <b>longops</b>. +//! +//! @return If the <b>flag</b> field is NULL, <b>val</b> field is returned, +//! which is usually just the corresponding short-option. +//! If <b>flag</b> is not NULL, 0 is returned and <b>val</b> is +//! stored in the location pointed to by <b>flag</b> field. +//! A ':' will be returned if there was a missing option argument. +//! A '?' will be returned if an unknown or ambiguous option was used. +//! A -1 will be returned when the argument list has been exhausted. +//! +/////////////////////////////////////////////////////////////////////////////// +MP4V2_EXPORT +int getOptionSingle( int argc, char* const* argv, const char* optstr, const Option* longopts, int* idx ); + +/////////////////////////////////////////////////////////////////////////////// + +}}} // namespace mp4v2::platform::prog + +#endif // MP4V2_PLATFORM_PROG_OPTION_H |