/*
* Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
* University Research and Technology
* Corporation. All rights reserved.
* Copyright (c) 2004-2005 The University of Tennessee and The University
* of Tennessee Research Foundation. All rights
* reserved.
* Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
* University of Stuttgart. All rights reserved.
* Copyright (c) 2004-2005 The Regents of the University of California.
* All rights reserved.
* Copyright (c) 2012 Cisco Systems, Inc. All rights reserved.
* $COPYRIGHT$
*
* Additional copyrights may follow
*
* $HEADER$
*/
/**
* @file
*
* General command line parsing facility for use throughout Open MPI.
*
* This scheme is inspired by the GNU getopt package. Command line
* options are registered. Each option can have up to three different
* matching tokens: a "short" name, a "single dash" name, and a "long"
* name. Each option can also take 0 or more arguments. Finally,
* each option can be repeated on the command line an arbitrary number
* of times.
*
* The "short" name can only be a single letter, and will be found
* after a single dash (e.g., "-a"). Multiple "short" names can be
* combined into a single command line argument (e.g., "-abc" can be
* equivalent to "-a -b -c").
*
* The "single dash" name is a multi-character name that only
* requires a single dash. This only exists to provide backwards
* compatibility for some well-known command line options in prior
* MPI implementations (e.g., "mpirun -np 3"). It should be used
* sparingly.
*
* The "long" name is a multi-character name that is found after a
* pair of dashes. For example, "--some-option-name".
*
* A command line option is a combination of 1 or more of a short
* name, single dash name, and a long name. Any of the names may be
* used on the command line; they are treated as synonyms. For
* example, say the following was used in for an executable named
* "foo":
*
* \code
* opal_cmd_line_make_opt3(cmd, 'a', NULL, 'add', 1, "Add a user");
* \endcode
*
* In this case, the following command lines are exactly equivalent:
*
* \verbatim
* shell$ foo -a jsmith
* shell$ foo --add jsmith
* \endverbatim
*
* Note that this interface can also track multiple invocations of the
* same option. For example, the following is both legal and able to
* be retrieved through this interface:
*
* \verbatim
* shell$ foo -a jsmith -add bjones
* \endverbatim
*
* The caller to this interface creates a command line handle
* (opal_cmd_line_t) with OBJ_NEW() and then uses it to register the
* desired parameters via opal_cmd_line_make_opt3(). Once all the
* parameters have been registered, the user invokes
* opal_cmd_line_parse() with the command line handle and the argv/argc
* pair to be parsed (typically the arguments from main()). The parser
* will examine the argv and find registered options and parameters.
* It will stop parsing when it runs into an recognized string token or
* the special "--" token.
*
* After the parse has occurred, various accessor functions can be
* used to determine which options were selected, what parameters were
* passed to them, etc.:
*
* - opal_cmd_line_get_usage_msg() returns a string suitable for "help"
* kinds of messages.
* - opal_cmd_line_is_taken() returns a true or false indicating
* whether a given command line option was found on the command
* line.
* - opal_cmd_line_get_argc() returns the number of tokens parsed on
* the handle.
* - opal_cmd_line_get_argv() returns any particular string from the
* original argv.
* - opal_cmd_line_get_ninsts() returns the number of times a
* particular option was found on a command line.
* - opal_cmd_line_get_param() returns the Nth parameter in the Mth
* instance of a given parameter.
* - opal_cmd_line_get_tail() returns an array of tokens not parsed
* (i.e., if the parser ran into "--" or an unrecognized token).
*
* Note that a shortcut to creating a large number of options exists
* -- one can make a table of opal_cmd_line_init_t instances and the
* table to opal_cmd_line_create(). This creates an opal_cmd_line_t
* handle that is pre-seeded with all the options from the table
* without the need to repeatedly invoke opal_cmd_line_make_opt3() (or
* equivalent). This opal_cmd_line_t instance is just like any other;
* it is still possible to add more options via
* opal_cmd_line_make_opt3(), etc.
*/
#ifndef OPAL_CMD_LINE_H
#define OPAL_CMD_LINE_H
#include "opal_config.h"
#include "opal/class/opal_object.h"
#include "opal/class/opal_list.h"
#include "opal/threads/mutex.h"
BEGIN_C_DECLS
/**
* \internal
*
* Main top-level handle. This interface should not be used by users!
*/
struct opal_cmd_line_t {
/** Make this an OBJ handle */
opal_object_t super;
/** Thread safety */
opal_mutex_t lcl_mutex;
/** List of cmd_line_option_t's (defined internally) */
opal_list_t lcl_options;
/** Duplicate of argc from opal_cmd_line_parse() */
int lcl_argc;
/** Duplicate of argv from opal_cmd_line_parse() */
char **lcl_argv;
/** Parsed output; list of cmd_line_param_t's (defined internally) */
opal_list_t lcl_params;
/** List of tail (unprocessed) arguments */
int lcl_tail_argc;
/** List of tail (unprocessed) arguments */
char **lcl_tail_argv;
};
/**
* \internal
*
* Convenience typedef
*/
typedef struct opal_cmd_line_t opal_cmd_line_t;
/**
* Data types supported by the parser
*/
enum opal_cmd_line_type_t {
OPAL_CMD_LINE_TYPE_NULL,
OPAL_CMD_LINE_TYPE_STRING,
OPAL_CMD_LINE_TYPE_INT,
OPAL_CMD_LINE_TYPE_SIZE_T,
OPAL_CMD_LINE_TYPE_BOOL,
OPAL_CMD_LINE_TYPE_MAX
};
/**
* \internal
*
* Convenience typedef
*/
typedef enum opal_cmd_line_type_t opal_cmd_line_type_t;
/**
* Datatype used to construct a command line handle; see
* opal_cmd_line_create().
*/
struct opal_cmd_line_init_t {
/** If want to set an MCA parameter, set its parameter name
here. */
const char *ocl_mca_param_name;
/** "Short" name (i.e., "-X", where "X" is a single letter) */
char ocl_cmd_short_name;
/** "Single dash" name (i.e., "-foo"). The use of these are
discouraged. */
const char *ocl_cmd_single_dash_name;
/** Long name (i.e., "--foo"). */
const char *ocl_cmd_long_name;
/** Number of parameters that this option takes */
int ocl_num_params;
/** If this parameter is encountered, its *first* parameter it
saved here. If the parameter is encountered again, the
value is overwritten. */
void *ocl_variable_dest;
/** If an ocl_variable_dest is given, its datatype must be
supplied as well. */
opal_cmd_line_type_t ocl_variable_type;
/** Description of the command line option, to be used with
opal_cmd_line_get_usage_msg(). */
const char *ocl_description;
};
/**
* \internal
*
* Convenience typedef
*/
typedef struct opal_cmd_line_init_t opal_cmd_line_init_t;
/**
* Top-level command line handle.
*
* This handle is used for accessing all command line functionality
* (i.e., all opal_cmd_line*() functions). Multiple handles can be
* created and simultaneously processed; each handle is independant
* from others.
*
* The opal_cmd_line_t handles are [simplisticly] thread safe;
* processing is guaranteed to be mutually exclusive if multiple
* threads invoke functions on the same handle at the same time --
* access will be serialized in an unspecified order.
*
* Once finished, handles should be released with OBJ_RELEASE(). The
* destructor for opal_cmd_line_t handles will free all memory
* associated with the handle.
*/
OPAL_DECLSPEC OBJ_CLASS_DECLARATION(opal_cmd_line_t);
/**
* Make a command line handle from a table of initializers.
*
* @param cmd OPAL command line handle.
* @param table Table of opal_cmd_line_init_t instances for all
* the options to be included in the resulting command line
* handler.
*
* @retval OPAL_SUCCESS Upon success.
*
* This function takes a table of opal_cmd_line_init_t instances
* to pre-seed an OPAL command line handle. The last instance in
* the table must have '\0' for the short name and NULL for the
* single-dash and long names. The handle is expected to have
* been OBJ_NEW'ed or OBJ_CONSTRUCT'ed already.
*
* Upon return, the command line handle is just like any other. A
* sample using this syntax:
*
* \code
* opal_cmd_line_init_t cmd_line_init[] = {
* { NULL, NULL, NULL, 'h', NULL, "help", 0,
* &orterun_globals.help, OPAL_CMD_LINE_TYPE_BOOL,
* "This help message" },
*
* { NULL, NULL, NULL, '\0', NULL, "wd", 1,
* &orterun_globals.wd, OPAL_CMD_LINE_TYPE_STRING,
* "Set the working directory of the started processes" },
*
* { NULL, NULL, NULL, '\0', NULL, NULL, 0,
* NULL, OPAL_CMD_LINE_TYPE_NULL, NULL }
* };
* \endcode
*/
OPAL_DECLSPEC int opal_cmd_line_create(opal_cmd_line_t *cmd,
opal_cmd_line_init_t *table);
/**
* Create a command line option.
*
* @param cmd OPAL command line handle.
* @param entry Command line entry to add to the command line.
*
* @retval OPAL_SUCCESS Upon success.
*
*/
OPAL_DECLSPEC int opal_cmd_line_make_opt_mca(opal_cmd_line_t *cmd,
opal_cmd_line_init_t entry);
/**
* Create a command line option.
*
* @param cmd OPAL command line handle.
* @param short_name "Short" name of the command line option.
* @param sd_name "Single dash" name of the command line option.
* @param long_name "Long" name of the command line option.
* @param num_params How many parameters this option takes.
* @param dest Short string description of this option.
*
* @retval OPAL_ERR_OUT_OF_RESOURCE If out of memory.
* @retval OPAL_ERR_BAD_PARAM If bad parameters passed.
* @retval OPAL_SUCCESS Upon success.
*
* Adds a command line option to the list of options that an OPAL
* command line handle will accept. The short_name may take the
* special value '\0' to not have a short name. Likewise, the
* sd_name and long_name may take the special value NULL to not have
* a single dash or long name, respectively. However, one of the
* three must have a name.
*
* num_params indicates how many parameters this option takes. It
* must be greater than or equal to 0.
*
* Finally, desc is a short string description of this option. It is
* used to generate the output from opal_cmd_line_get_usage_msg().
*
*/
OPAL_DECLSPEC int opal_cmd_line_make_opt3(opal_cmd_line_t *cmd,
char short_name,
const char *sd_name,
const char *long_name,
int num_params,
const char *desc);
/**
* Parse a command line according to a pre-built OPAL command line
* handle.
*
* @param cmd OPAL command line handle.
* @param ignore_unknown Whether to print an error message upon
* finding an unknown token or not
* @param argc Length of the argv array.
* @param argv Array of strings from the command line.
*
* @retval OPAL_SUCCESS Upon success.
* @retval OPAL_ERR_SILENT If an error message was printed. This
* value will only be returned if the command line was not
* successfully parsed.
*
* Parse a series of command line tokens according to the option
* descriptions from a OPAL command line handle. The OPAL command line
* handle can then be queried to see what options were used, what
* their parameters were, etc.
*
* If an unknown token is found in the command line (i.e., a token
* that is not a parameter or a registered option), the parsing will
* stop (see below). If ignore_unknown is false, an error message
* is displayed. If ignore_unknown is true, the error message is
* not displayed.
*
* Error messages are always displayed regardless of the value
* of ignore_unknown (to stderr, and OPAL_ERR_SILENT is
* returned) if:
*
* 1. A token was encountered that required N parameters, but <N
* parameters were found (e.g., "cmd --param foo", but --param was
* registered to require 2 option tokens).
*
* 2. An unknown token beginning with "-" is encountered. For
* example, if "--fo" is specified, and no "fo" option is
* registered (e.g., perhaps the user meant to type "--foo"), an
* error message is always printed, UNLESS this unknown token
* happens after a "--" token (see below).
*
* The contents of argc and argv are not changed during parsing.
* argv[0] is assumed to be the executable name, and is ignored during
* parsing, except when printing error messages.
*
* Parsing will stop in the following conditions:
*
* - all argv tokens are processed
* - the token "--" is found
* - an unrecognized token is found
* - a parameter registered with an integer type option finds a
* non-integer option token
* - a parameted registered N option tokens, but finds less then
* <N tokens available
*
* Upon any of these conditions, any remaining tokens will be placed
* in the "tail" (and therefore not examined by the parser),
* regardless of the value of ignore_unknown. The set of tail
* tokens is available from the opal_cmd_line_get_tail() function.
*
* Note that "--" is ignored if it is found in the middle an expected
* number of arguments. For example, if "--foo" is expected to have 3
* arguments, and the command line is:
*
* executable --foo a b -- other arguments
*
* This will result in an error, because "--" will be parsed as the
* third parameter to the first instance of "foo", and "other" will be
* an unrecognized option.
*
* Note that -- can be used to allow unknown tokens that begin
* with "-". For example, if a user wants to mpirun an executable
* named "-my-mpi-program", the "usual" way:
*
* mpirun -my-mpi-program
*
* will cause an error, because mpirun won't find single-letter
* options registered for some/all of those letters. But two
* workarounds are possible:
*
* mpirun -- -my-mpi-program
* or
* mpirun ./-my-mpi-program
*
* Finally, note that invoking this function multiple times on
* different sets of argv tokens is safe, but will erase any
* previous parsing results.
*/
OPAL_DECLSPEC int opal_cmd_line_parse(opal_cmd_line_t *cmd,
bool ignore_unknown,
int argc, char **argv);
/**
* Return a consolidated "usage" message for a OPAL command line handle.
*
* @param cmd OPAL command line handle.
*
* @retval str Usage message.
*
* Returns a formatted string suitable for printing that lists the
* expected usage message and a short description of each option on
* the OPAL command line handle. Options that passed a NULL
* description to opal_cmd_line_make_opt3() will not be included in the
* display (to allow for undocumented options).
*
* This function is typically only invoked internally by the
* opal_show_help() function.
*
* This function should probably be fixed up to produce prettier
* output.
*
* The returned string must be freed by the caller.
*/
OPAL_DECLSPEC char *opal_cmd_line_get_usage_msg(opal_cmd_line_t *cmd) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__;
/**
* Test if a given option was taken on the parsed command line.
*
* @param cmd OPAL command line handle.
* @param opt Short or long name of the option to check for.
*
* @retval true If the command line option was found during
* opal_cmd_line_parse().
*
* @retval false If the command line option was not found during
* opal_cmd_line_parse(), or opal_cmd_line_parse() was not invoked on
* this handle.
*
* This function should only be called after opal_cmd_line_parse().
*
* The function will return true if the option matching opt was found
* (either by its short or long name) during token parsing.
* Otherwise, it will return false.
*/
OPAL_DECLSPEC bool opal_cmd_line_is_taken(opal_cmd_line_t *cmd,
const char *opt) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(2);
/**
* Return the number of arguments parsed on a OPAL command line handle.
*
* @param cmd A pointer to the OPAL command line handle.
*
* @retval OPAL_ERROR If cmd is NULL.
* @retval argc Number of arguments previously added to the handle.
*
* Arguments are added to the handle via the opal_cmd_line_parse()
* function.
*/
OPAL_DECLSPEC int opal_cmd_line_get_argc(opal_cmd_line_t *cmd) __opal_attribute_unused__;
/**
* Return a string argument parsed on a OPAL command line handle.
*
* @param cmd A pointer to the OPAL command line handle.
* @param index The nth argument from the command line (0 is
* argv[0], etc.).
*
* @retval NULL If cmd is NULL or index is invalid
* @retval argument String of original argv[index]
*
* This function returns a single token from the arguments parsed
* on this handle. Arguments are added bia the
* opal_cmd_line_parse() function.
*
* What is returned is a pointer to the actual string that is on
* the handle; it should not be modified or freed.
*/
OPAL_DECLSPEC char *opal_cmd_line_get_argv(opal_cmd_line_t *cmd,
int index);
/**
* Return the number of instances of an option found during parsing.
*
* @param cmd OPAL command line handle.
* @param opt Short or long name of the option to check for.
*
* @retval num Number of instances (to include 0) of a given potion
* found during opal_cmd_line_parse().
*
* @retval OPAL_ERR If the command line option was not found during
* opal_cmd_line_parse(), or opal_cmd_line_parse() was not invoked on
* this handle.
*
* This function should only be called after opal_cmd_line_parse().
*
* The function will return the number of instances of a given option
* (either by its short or long name) -- to include 0 -- or OPAL_ERR if
* either the option was not specified as part of the OPAL command line
* handle, or opal_cmd_line_parse() was not invoked on this handle.
*/
OPAL_DECLSPEC int opal_cmd_line_get_ninsts(opal_cmd_line_t *cmd,
const char *opt) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(2);
/**
* Return a specific parameter for a specific instance of a option
* from the parsed command line.
*
* @param cmd OPAL command line handle.
* @param opt Short or long name of the option to check for.
* @param instance_num Instance number of the option to query.
* @param param_num Which parameter to return.
*
* @retval param String of the parameter.
* @retval NULL If any of the input values are invalid.
*
* This function should only be called after opal_cmd_line_parse().
*
* This function returns the Nth parameter for the Ith instance of a
* given option on the parsed command line (both N and I are
* zero-indexed). For example, on the command line:
*
* executable --foo bar1 bar2 --foo bar3 bar4
*
* The call to opal_cmd_line_get_param(cmd, "foo", 1, 1) would return
* "bar4". opal_cmd_line_get_param(cmd, "bar", 0, 0) would return
* NULL, as would opal_cmd_line_get_param(cmd, "foo", 2, 2);
*
* The returned string should \em not be modified or freed by the
* caller.
*/
OPAL_DECLSPEC char *opal_cmd_line_get_param(opal_cmd_line_t *cmd,
const char *opt,
int instance_num,
int param_num);
/**
* Return the entire "tail" of unprocessed argv from a OPAL
* command line handle.
*
* @param cmd A pointer to the OPAL command line handle.
* @param tailc Pointer to the output length of the null-terminated
* tail argv array.
* @param tailv Pointer to the output null-terminated argv of all
* unprocessed arguments from the command line.
*
* @retval OPAL_ERROR If cmd is NULL or otherwise invalid.
* @retval OPAL_SUCCESS Upon success.
*
* The "tail" is all the arguments on the command line that were
* not processed for some reason. Reasons for not processing
* arguments include:
*
* \sa The argument was not recognized
* \sa The argument "--" was seen, and therefore all arguments
* following it were not processed
*
* The output tailc parameter will be filled in with the integer
* length of the null-terminated tailv array (length including the
* final NULL entry). The output tailv parameter will be a copy
* of the tail parameters, and must be freed (likely with a call
* to opal_argv_free()) by the caller.
*/
OPAL_DECLSPEC int opal_cmd_line_get_tail(opal_cmd_line_t *cmd, int *tailc,
char ***tailv) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(2);
END_C_DECLS
#endif /* OPAL_CMD_LINE_H */