openmpi/src/util/cmd_line.h

/*
 * $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
 * compatability 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
 * ompi_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
 * (ompi_cmd_line_t) with OBJ_NEW() and then uses it to register the
 * desired parameters via ompi_cmd_line_make_opt3() (or the deprecated
 * ompi_cmd_line_make_opt()).  Once all the parameters have been
 * registered, the user invokes ompi_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.:
 *
 * - ompi_cmd_line_get_usage_msg() returns a string suitable for "help"
 *   kinds of messages.
 * - ompi_cmd_line_is_taken() returns a true or false indicating
 *   whether a given command line option was found on the command
 *   line.
 * - ompi_cmd_line_get_argc() returns the number of tokens parsed on
 *   the handle.
 * - ompi_cmd_line_get_argv() returns any particular string from the
 *   original argv.
 * - ompi_cmd_line_get_ninsts() returns the number of times a
 *   particular option was found on a command line.
 * - ompi_cmd_line_get_param() returns the Nth parameter in the Mth
 *   instance of a given parameter.
 * - ompi_cmd_line_get_tail() returns an array of tokens not parsed
 *   (i.e., if the parser ran into "--" or an unrecognized token).
 */

#ifndef OMPI_CMD_LINE_H
#define OMPI_CMD_LINE_H

#include "ompi_config.h"

#include "class/ompi_object.h"
#include "class/ompi_list.h"
#include "threads/mutex.h"

/**
 * \internal
 *
 * Main top-level handle.  This interface should not be used by users!
 */
struct ompi_cmd_line_t {
    /** Make this an OBJ handle */
    ompi_object_t super;

    /** Thread safety */
    ompi_mutex_t lcl_mutex;

    /** List of cmd_line_option_t's (defined internally) */
    ompi_list_t lcl_options;

    /** Duplicate of argc from ompi_cmd_line_parse() */
    int lcl_argc;
    /** Duplicate of argv from ompi_cmd_line_parse() */
    char **lcl_argv;

    /** Parsed output; list of cmd_line_param_t's (defined internally) */
    ompi_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 ompi_cmd_line_t ompi_cmd_line_t;


/**
 * Top-level command line handle.
 *
 * This handle is used for accessing all command line functionality
 * (i.e., all ompi_cmd_line*() functions).  Multiple handles can be
 * created and simultaneously processed; each handle is independant
 * from others.
 *
 * The ompi_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 ompi_cmd_line_t handles will free all memory
 * associated with the handle.
 */
OBJ_CLASS_DECLARATION(ompi_cmd_line_t);


#ifdef __cplusplus
extern "C" {
#endif

  /**
   * Create a command line option.
   *
   * This function is an older [deprecated] form of
   * ompi_cmd_line_make_opt3().  It is exactly equivalent to
   * ompi_cmd_line_make_opt3(cmd, short_name, NULL, long_name,
   * num_params, desc).
   */
  int ompi_cmd_line_make_opt(ompi_cmd_line_t *cmd, char short_name, 
                            const char *long_name, int num_params, 
                            const char *desc);

  /**
   * Create a command line option.
   *
   * @param cmd OMPI 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 OMPI_ERR_OUT_OF_RESOURCE If out of memory.
   * @retval OMPI_ERR_BAD_PARAM If bad parameters passed.
   * @retval OMPI_SUCCESS Upon success.
   *
   * Adds a command line option to the list of options that a a OMPI
   * 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 ompi_cmd_line_get_usage_msg().
   *
   */
  int ompi_cmd_line_make_opt3(ompi_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 OMPI command line
   * handle.
   *
   * @param cmd OMPI command line handle.
   * @param ignore_unknown Whether to ignore unknown tokens in the
   * middle of the command line or not.
   * @param argc Length of the argv array.
   * @param argv Array of strings from the command line.
   *
   * @retval OMPI_SUCCESS Upon success.
   *
   * Parse a series of command line tokens according to the option
   * descriptions from a OMPI command line handle.  The OMPI command line
   * handle can then be queried to see what options were used, what
   * their parameters were, etc.
   *
   * 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.  It can later be retrieved with
   *
   * Parsing will stop in the following conditions:
   *
   * - all argv tokens are processed
   * - the token "--" is found
   * - an unrecognized token is found and ignore_unknown is false
   *
   * 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.
   *
   * Unprocessed tokens are known as the "tail."  Any unprocessed tokens
   * can be obtained from the ompi_cmd_line_get_tail() function.
   *
   * Invoking this function multiple times on different sets of argv
   * tokens is safe, but will erase any previous parsing results.
   */
  int ompi_cmd_line_parse(ompi_cmd_line_t *cmd, bool ignore_unknown,
                         int argc, char **argv);

  /**
   * Return a consolidated "usage" message for a OMPI command line handle.
   *
   * @param cmd OMPI 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 OMPI command line handle.  Options that passed a NULL
   * description to ompi_cmd_line_make_opt() will not be included in the
   * display (to allow for undocumented options).
   *
   * This function is typically only invoked internally by the
   * ompi_show_help() function.
   *
   * This function should probably be fixed up to produce prettier
   * output.
   *
   * The returned string must be freed by the caller.
   */
  char *ompi_cmd_line_get_usage_msg(ompi_cmd_line_t *cmd);
  /**
   * Test if a given option was taken on the parsed command line.
   *
   * @param cmd OMPI 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
   * ompi_cmd_line_parse().
   *
   * @retval false If the command line option was not found during
   * ompi_cmd_line_parse(), or ompi_cmd_line_parse() was not invoked on
   * this handle.
   *
   * This function should only be called after ompi_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.
   */
  bool ompi_cmd_line_is_taken(ompi_cmd_line_t *cmd, const char *opt);

  /**
   * Return the number of arguments parsed on a OMPI command line handle.
   *
   * @param cmd A pointer to the OMPI command line handle.
   *
   * @retval OMPI_ERROR If cmd is NULL.
   * @retval argc Number of arguments previously added to the handle.
   *
   * Arguments are added to the handle via the ompi_cmd_line_parse()
   * function.
   */
  int ompi_cmd_line_get_argc(ompi_cmd_line_t *cmd);

  /**
   * Return a string argument parsed on a OMPI command line handle.
   *
   * @param cmd A pointer to the OMPI 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
   * ompi_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.
   */
  char *ompi_cmd_line_get_argv(ompi_cmd_line_t *cmd, int index);

  /**
   * Return the number of instances of an option found during parsing.
   *
   * @param cmd OMPI 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 ompi_cmd_line_parse().
   *
   * @retval OMPI_ERR If the command line option was not found during
   * ompi_cmd_line_parse(), or ompi_cmd_line_parse() was not invoked on
   * this handle.
   *
   * This function should only be called after ompi_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 OMPI_ERR if
   * either the option was not specified as part of the OMPI command line
   * handle, or ompi_cmd_line_parse() was not invoked on this handle.
   */
  int ompi_cmd_line_get_ninsts(ompi_cmd_line_t *cmd, const char *opt);

  /**
   * Return a specific parameter for a specific instance of a option
   * from the parsed command line.
   *
   * @param cmd OMPI 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 ompi_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 ompi_cmd_line_get_param(cmd, "foo", 1, 1) would return
   * "bar4".  ompi_cmd_line_get_param(cmd, "bar", 0, 0) would return
   * NULL, as would ompi_cmd_line_get_param(cmd, "foo", 2, 2);
   *
   * The returned string should \em not be modified or freed by the
   * caller.
   */
  char *ompi_cmd_line_get_param(ompi_cmd_line_t *cmd, const char *opt, 
                               int instance_num, int param_num);

  /**
   * Return the entire "tail" of unprocessed argv from a OMPI
   * command line handle.
   *
   * @param cmd A pointer to the OMPI 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 OMPI_ERROR If cmd is NULL or otherwise invalid.
   * @retval OMPI_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 ompi_argv_free()) by the caller.
   */
  int ompi_cmd_line_get_tail(ompi_cmd_line_t *cmd, int *tailc, 
                             char ***tailv);
#ifdef __cplusplus
}
#endif


#endif /* OMPI_CMD_LINE_H */