Branch: Tag:

2000-12-13

2000-12-13 15:51:50 by Henrik Grubbström (Grubba) <grubba@grubba.org>

Added some AutoDoc mk II markup.

Rev: lib/modules/Getopt.pmod:1.12

1:   #pike __REAL_VERSION__    + //! @[Getopt] is a group of function which can be used to find command + //! line options. + //! + //! Command line options come in two flavors: long and short. The short ones + //! consists of a dash followed by a character (@tt{-t@}), the long ones + //! consist of two dashes followed by a string of text (@tt{--test@}). + //! The short options can also be combined, which means that you can write + //! @tt{-tda@} instead of @tt{-t -d -a@}. + //! + //! Options can also require arguments, in which case they cannot be + //! combined. To write an option with an argument you write + //! @tt{-t @i{argument@}@} or @tt{-t@i{argument@}@} or + //! @tt{--test=@i{argument@}@}. +  +    // startpid = (int)find_arg(argv, "s", ({ "start-script-pid" }),   // ({ "ROXEN_START_SCRIPT_PID"}));   
10:   // "../configurations");       + //! This is a generic function to parse command line options of the + //! type @tt{-f@}, @tt{--foo@} or @tt{--foo=bar@}. + //! + //! The first argument should be the array of strings that was sent as + //! the second argument to your @tt{main()@} function. + //! + //! The second is a string with the short form of your option. + //! The short form must be only one character long. + //! + //! The @[longform] is an alternative and maybe more readable way to + //! give the same option. If you give @tt{"foo"@} as @[longform] your program + //! will accept @tt{--foo@} as argument. + //! + //! The @[envvars] argument specifies the environment variables that can be + //! used to specify the same option. This option exists to make it easier + //! to customize program usage. + //! + //! The @[def] has two functions: It specifies if the option takes an + //! argument or not, and it tells @[find_option()] what to return if the + //! option is not present. If @[def] is given and the option does not have an + //! argument @[find_option()] will fail. + //! + //! If @[throw_errors] has been specified @[find_option] will throw errors + //! on failure. If it has been left out, or is @tt{0@} (zero), it will + //! instead print an error message and exit the program on failure. + //! + //! Also, as an extra bonus: @[shortform], @[longform] and @[envvars] can + //! all be arrays, in which case any of the options in the array will be + //! accepted. + //! + //! @note + //! find_option modifies argv. + //! + //! This function reads options even if they are written after the first + //! non-option on the line. + //! + //! @seealso + //! @[Getopt.get_args()] + //!   string|int find_option(array(string) argv,    array(string)|string shortform,    array(string)|string|void longform,
133:   #define ENV 3   #define DEF 4    + //! This function does the job of several calls to @[find_option()]. + //! The main advantage of this is that it allows it to handle the + //! @tt{@b{POSIX_ME_HARDER@}@} environment variable better. When the either + //! the argument @[posix_me_harder] or the environment variable + //! @tt{@b{POSIX_ME_HARDER@}@} is true, no arguments will be parsed after + //! the first non-option on the command line. + //! + //! Each element in the array @[options] should be an array on the + //! following form: + //! @array + //! @element string name + //! Name is a tag used to identify the option in the output. + //! @element int type + //! Type is one of @[Getopt.HAS_ARG], @[Getopt.NO_ARG] and + //! @[Getopt.MAY_HAVE_ARG] and it affects how the error handling + //! and parsing works. + //! You should use @[HAS_ARG] for options that require a path, a number or + //! similar. @[NO_ARG] should be used for options that do not need an + //! argument, such as @tt{--version@}. @[MAY_HAVE_ARG] should be used + //! for options that may or may not need an argument. + //! @element string|array(string) aliases + //! This is a string or an array of string of options that will be + //! looked for. Short and long options can be mixed, and short options + //! can be combined into one string. Note that you must include the dashes + //! so that @[find_all_options()] can distinguish between + //! long and short options. Example: @tt{({"-tT","--test"})@} + //! This would make @[find_all_options] look for @tt{-t@}, + //! @tt{-T@} and @tt{--test@}. + //! @element void|string|array(string) env_var + //! This is a string or an array of strings containing names of + //! environment variables that can be used instead of the + //! command line option. + //! @element void|mixed default + //! This is the default value the option will have in the output + //! from this function. Options without defaults will be omitted + //! from the output if they are not found in argv. + //! @endarray + //! + //! Only the first three elements need to be included. + //! + //! @returns + //! The good news is that the output from this function is a lot simpler. + //! @[find_all_options()] returns an array where each element is an array on + //! this form: + //! @array + //! @element string name + //! Option identifier name from the input. + //! @element mixed value + //! Value given. If no value was specified, and no default has been + //! specified, the value will be 1. + //! @endarray + //! + //! @note + //! @[find_all_options()] modifies @[argv]. + //! + //! @seealso + //! @[Getopt.get_args()], @[Getopt.find_option()] + //!   array find_all_options(array(string) argv,    array(array(array(string)|string)) options,    void|int posix_me_harder, void|int throw_errors)
265:    return ret;   }    -  + //! This function returns the remaining command line arguments after + //! you have run @[find_options()] or @[find_all_options()] to find + //! all the options in the argument list. If there are any options + //! left not handled by @[find_options()] or @[find_all_options()] + //! this function will fail. + //! + //! If @[throw_errors] has been specified @[get_args()] will throw errors + //! on failure. If it has been left out, or is @tt{0@} (zero), it will + //! instead print an error message and exit the program on failure. + //! + //! @returns + //! On success a new @[argv] array without the parsed options is + //! returned. + //! + //! @seealso + //! @[Getopt.find_option()], @[Getopt.find_all_options()] + //!   array(string) get_args(array(string) argv, void|int posix_me_harder,    void|int throw_errors)   {