Getopt.pmod

#pike __REAL_VERSION__

#pragma strict_types

//! @[Getopt] is a group of functions 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@}@}.

protected void my_error(string err, int throw_errors) {
  if(throw_errors) error(err);
  werror([string(0..255)]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 @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 @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.
//!
//!   The value may be one of:
//!   @mixed
//!     @type int(0..0)|zero
//!       The option does not require a value.
//!     @type int(1..1)|string
//!       The option requires a value, and @[def] will be returned
//!       if the option is not present. If the option is present,
//!       but does not have an argument @[find_option()] will fail.
//!
//!       Note that a set option will always return a @expr{string@},
//!       so setting @[def] to @expr{1@} can be used to detect whether
//!       the option is present or not.
//!   @endmixed
//!
//! @param throw_errors