1
1

- Fix a bug that occurred when not enough command line arg params were

provided for a given option.
- Move all docs to the .h file, where they belong.

This commit was SVN r1360.
Этот коммит содержится в:
Jeff Squyres 2004-06-17 14:25:29 +00:00
родитель 1b542d409b
Коммит a5b3478c88
2 изменённых файлов: 228 добавлений и 198 удалений

Просмотреть файл

@ -2,8 +2,6 @@
* $HEADER$
*/
/** @file **/
#include "ompi_config.h"
#include <stdio.h>
@ -74,25 +72,8 @@ static cmd_line_option_t *find_option(ompi_cmd_line_t *cmd,
const char *option_name);
/**
/*
* Create a OMPI command line handle.
*
* @retval NULL Upon failure.
* @retval cmd A pointer to an empty command line handle upon success.
*
* This is the first function invoked to start command line parsing.
* It creates an independant handle that is used in all other
* 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.
*
* It is necessary to call ompi_cmd_line_free() with the handle
* returned from this function in order to free all memory associated
* with it.
*/
ompi_cmd_line_t *ompi_cmd_line_create(void)
{
@ -125,23 +106,9 @@ ompi_cmd_line_t *ompi_cmd_line_create(void)
}
/**
/*
* Free a (ompi_cmd_line_t*) that was initially allocated via
* ompi_cmd_line_create().
*
* @param cmd The OMPI command line handle to free.
*
* This function frees a OMPI command line handle and all its
* associated memory. This function can be called with any non-NULL
* pointer that was returned from ompi_cmd_line_create(). Once called,
* the handle is no longer valid.
*
* Access into this function is not thread safe. Since, by
* definition, calling this function will destroy the handle, it does
* not make sense to try to have thread A invoke a different
* ompi_cmd_line*() function and thread B invoke ompi_cmd_line_free() --
* even if the calls are serialized, there's a race condition where
* thread A may try to use a now-invalid handle.
*/
void ompi_cmd_line_free(ompi_cmd_line_t *cmd)
{
@ -179,30 +146,8 @@ void ompi_cmd_line_free(ompi_cmd_line_t *cmd)
}
/**
/*
* Create a command line option.
*
* @param cmd OMPI command line handle.
* @param short_name "Short" 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
* long_name may take the special value NULL to not have a long name.
* However, either the long or the short name must take valid value.
*
* 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_opt(ompi_cmd_line_t *cmd, char short_name,
const char *long_name, int num_params,
@ -250,48 +195,9 @@ int ompi_cmd_line_make_opt(ompi_cmd_line_t *cmd, char short_name,
}
/**
/*
* 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)
@ -412,6 +318,7 @@ int ompi_cmd_line_parse(ompi_cmd_line_t *cmd, bool ignore_unknown,
if (NULL != param->clp_argv)
ompi_argv_free(param->clp_argv);
free(param);
param = NULL;
i = cmd->lcl_argc;
break;
} else {
@ -439,7 +346,9 @@ int ompi_cmd_line_parse(ompi_cmd_line_t *cmd, bool ignore_unknown,
/* If we succeeded in all that, save the param to the list on
the ompi_cmd_line_t handle */
ompi_list_append(&cmd->lcl_params, item);
if (NULL != param) {
ompi_list_append(&cmd->lcl_params, item);
}
}
}
@ -469,26 +378,8 @@ int ompi_cmd_line_parse(ompi_cmd_line_t *cmd, bool ignore_unknown,
}
/**
/*
* 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)
{
@ -587,24 +478,8 @@ 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)
{
@ -612,25 +487,8 @@ bool ompi_cmd_line_is_taken(ompi_cmd_line_t *cmd, const char *opt)
}
/**
/*
* 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)
{
@ -672,29 +530,6 @@ 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 inst,
int idx)

Просмотреть файл

@ -2,7 +2,11 @@
* $HEADER$
*/
/** @file **/
/**
* @file
*
* General command line parsing facility for use throughout Open MPI.
*/
#ifndef OMPI_CMD_LINE_H
#define OMPI_CMD_LINE_H
@ -13,63 +17,254 @@
#include "threads/mutex.h"
#include "util/argv.h"
/*
* Top-level descriptor
/**
* \internal
*
* Top-level descriptor. This type is actually internal to the
* cmd_line interface, but we can't have the top-level convenience
* typedef without it. You should not use the internal members of
* this struct; please use the interface described in this file.
*/
struct ompi_cmd_line_t {
ompi_mutex_t lcl_mutex;
/* List of cmd_line_option_t's, below */
/**< Thread safety */
ompi_list_t lcl_options;
/* Duplicate of the argc / argv passed in to ompi_cmd_line_parse() */
/**< List of cmd_line_option_t's, below */
int lcl_argc;
/**< Duplicate of argc from ompi_cmd_line_parse() */
char **lcl_argv;
/* Parsed output; list of cmd_line_param_t's, below */
/**< Duplicate of argv from ompi_cmd_line_parse() */
ompi_list_t lcl_params;
/* List of tail (unprocessed) arguments */
/**< Parsed output; list of cmd_line_param_t's, below */
int lcl_tail_argc;
/**< List of tail (unprocessed) arguments */
char **lcl_tail_argv;
/**< List of tail (unprocessed) arguments */
};
/**
* Convenience typedef.
*/
typedef struct ompi_cmd_line_t ompi_cmd_line_t;
#ifdef __cplusplus
extern "C" {
#endif
/* Create / destroy */
/**
* Create a OMPI command line handle.
*
* @retval NULL Upon failure.
* @retval cmd A pointer to an empty command line handle upon success.
*
* This is the first function invoked to start command line parsing.
* It creates an independant handle that is used in all other
* 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.
*
* It is necessary to call ompi_cmd_line_free() with the handle
* returned from this function in order to free all memory associated
* with it.
*/
ompi_cmd_line_t *ompi_cmd_line_create(void);
/*
* Free a (ompi_cmd_line_t*) that was initially allocated via
* ompi_cmd_line_create().
*
* @param cmd The OMPI command line handle to free.
*
* This function frees a OMPI command line handle and all its
* associated memory. This function can be called with any non-NULL
* pointer that was returned from ompi_cmd_line_create(). Once called,
* the handle is no longer valid.
*
* Access into this function is not thread safe. Since, by
* definition, calling this function will destroy the handle, it does
* not make sense to try to have thread A invoke a different
* ompi_cmd_line*() function and thread B invoke ompi_cmd_line_free() --
* even if the calls are serialized, there's a race condition where
* thread A may try to use a now-invalid handle.
*/
void ompi_cmd_line_free(ompi_cmd_line_t *cmd);
/* Writes */
/**
* Create a command line option.
*
* @param cmd OMPI command line handle.
* @param short_name "Short" 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
* long_name may take the special value NULL to not have a long name.
* However, either the long or the short name must take valid value.
*
* 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_opt(ompi_cmd_line_t *cmd, char short_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);
/* Reads */
static inline int ompi_cmd_line_get_argc(ompi_cmd_line_t *cmd);
static inline char *ompi_cmd_line_get_argv(ompi_cmd_line_t *cmd, int index);
/**
* 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 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);
static inline int ompi_cmd_line_get_tail(ompi_cmd_line_t *cmd, int *tailc,
char ***tailv);
#ifdef __cplusplus
}
#endif