pike.git / lib / modules / Getopt.pmod

version» Context lines:

pike.git/lib/modules/Getopt.pmod:20:    if(throw_errors) error(err);    werror(err);    exit(1);   }      //! This is a generic function to parse command line options of the   //! type @tt{-f@}, @tt{--foo@} or @tt{--foo=bar@}.   //!   //! @param argv   //! The first argument should be the array of strings that was sent as - //! the second argument to your @tt{main()@} function. + //! the second argument to your @expr{main()@} function.   //!   //! @param shortform   //! The second is a string with the short form of your option. The   //! short form must be only one character long. It can also be an   //! array of strings, in which case any of the options in the array   //! will be accepted.   //!   //! @param longform   //! This is an alternative and maybe more readable way to give the - //! same option. If you give @tt{"foo"@} as @[longform] your program + //! same option. If you give @expr{"foo"@} as @[longform] your program   //! will accept @tt{--foo@} as argument. This argument can also be   //! an array of strings, in which case any of the options in the   //! array will be accepted.   //!   //! @param envvars   //! This argument specifies an environment variable that can be used   //! to specify the same option, to make it easier to customize   //! program usage. It can also be an array of strings, in which case   //! any of the mentioned variables in the array may be used.   //!   //! @param def   //! This argument has two functions: It specifies if the option takes an   //! argument or not, and it informs @[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. @[def] can be specified as   //! @[UNDEFINED] or left out if the option does not take an argument.   //!   //! @param throw_errors - //! 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 on @[Stdio.stderr] and exit the - //! program with result code 1 on failure. + //! If @[throw_errors] has been specified @[find_option()] will + //! throw errors on failure. If it has been left out, or is + //! @expr{0@} (zero), it will instead print an error message on + //! @[Stdio.stderr] and exit the program with result code 1 on + //! failure.   //!   //! @returns   //! Returns the value the option has been set to if any.   //! - //! If the option is present, but has not been set to anything @tt{1@} - //! will be returned. + //! If the option is present, but has not been set to anything + //! @expr{1@} will be returned.   //!   //! Otherwise if any of the environment variables specified in @[envvars] has   //! been set, that value will be returned.   //!   //! If all else fails, @[def] will be returned.   //!   //! @throws   //! If an option that requires an argument lacks an argument and   //! @[throw_errors] is set an error will be thrown.   //!   //! @note   //! @[find_option()] modifies @[argv]. Parsed options will be removed   //! from @[argv]. Elements of @[argv] that have been removed entirely will   //! be replaced with zeroes.   //!   //! This function reads options even if they are written after the first   //! non-option on the line.   //! - //! Index @tt{0@} (zero) of @[argv] is not scanned for options, since it - //! is reserved for the program name. + //! Index @expr{0@} (zero) of @[argv] is not scanned for options, + //! since it is reserved for the program name.   //!   //! Only the first ocurrance of an option will be parsed. To parse   //! multiple ocurrances, call @[find_option()] multiple times.   //!   //! @seealso   //! @[Getopt.get_args()]   //!   string|int(0..1) find_option(array(string) argv,    array(string)|string shortform,    array(string)|string|void longform,
pike.git/lib/modules/Getopt.pmod:190:         //! 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.   //!   //! @param argv - //! The should be the array of strings that was sent as - //! the second argument to your @tt{main()@} function. + //! The should be the array of strings that was sent as the second + //! argument to your @expr{main()@} function.   //!   //! @param options   //! Each element in the array @[options] should be an array on the   //! following form:   //! @array   //! @elem string name   //! Name is a tag used to identify the option in the output.   //! @elem 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.   //! @elem 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"})@} + //! long and short options. Example: @expr{({"-tT","--test"})@}   //! This would make @[find_all_options] look for @tt{-t@},   //! @tt{-T@} and @tt{--test@}.   //! @elem 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.   //! @elem void|mixed default   //! This is the default value a @[MAY_HAVE_ARG] option will have in the   //! output if it was set but not assigned any value.   //! @endarray   //!   //! Only the first three elements need to be included.   //!   //! @param posix_me_harder   //! Don't scan for arguments after the first non-option.   //!   //! @param throw_errors - //! If @[throw_errors] has been specified @[find_all_options()] will throw - //! errors on failure. If it has been left out, or is @tt{0@} (zero), it will - //! instead print an error message on @[Stdio.stderr] and exit the - //! program with result code 1 on failure. + //! If @[throw_errors] has been specified @[find_all_options()] will + //! throw errors on failure. If it has been left out, or is + //! @expr{0@} (zero), it will instead print an error message on + //! @[Stdio.stderr] and exit the program with result code 1 on + //! failure.   //!   //! @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   //! @elem string name   //! Option identifier name from the input.   //! @elem 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].   //! - //! Index @tt{0@} (zero) of @[argv] is not scanned for options, since it - //! is reserved for the program name. + //! Index @expr{0@} (zero) of @[argv] is not scanned for options, + //! since it is reserved for the program name.   //!   //! @seealso   //! @[Getopt.get_args()], @[Getopt.find_option()]   //!   array(array) find_all_options(array(string) argv,    array(array(array(string)|string|int)) options,    void|int(-1..1) posix_me_harder, void|int throw_errors)   {    // --- Initialize variables