You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
175 lines
8.0 KiB
175 lines
8.0 KiB
#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
|