pike.git / lib / modules / Getopt.pmod

version» Context lines:

pike.git/lib/modules/Getopt.pmod:45:   //! @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. + //! 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.   //!   //! @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.   //!   //! Otherwise if any of the environment variables specified in @[envvars] has - //! been set, that value will be return. + //! been set, that value will be returned.   //!   //! If all else fails, @[def] will be returned.   //!   //! @throws - //! If an option that requires an argument misses the argument and + //! 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]. + //! @[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.   //! -  + //! 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,    array(string)|string|void envvars,    string|int(0..1)|void def,    int|void throw_errors)   {