module EasyOptions

EasyOptions 2015.2.28
Copyright (c) 2013, 2014 Renato Silva
BSD licensed

This script is supposed to parse command line arguments in a way that, even though its implementation is not trivial, it should be easy and smooth to use. For using this script, simply document your target script using double-hash comments, like this:

## Program Name v1.0
## Copyright (C) Someone
##
## This program does something. Usage:
##     @#script.name [option]
##
## Options:
##     -h, --help              All client scripts have this by default,
##                             it shows this double-hash documentation.
##
##     -o, --option            This option will get stored as true value
##                             under EasyOptions.options[:option]. Long
##                             version is mandatory, and can be specified
###                            before or after short version.
##
##         --some-boolean      This will get stored as true value under
##                             EasyOptions.options[:some_boolean].
##
##         --some-value=VALUE  This is going to store the VALUE specified
##                             under EasyOptions.options[:some_value].
##                             The equal sign is optional and can be
##                             replaced with blank space when running the
##                             target script. If VALUE is composed of
##                             digits, it will be converted into an
##                             integer, otherwise it will get stored as a
##                             string. Short version is not available in
##                             this format.

The above comments work both as source code documentation and as help text, as well as define the options supported by your script. There is no duplication of the options specification. The string @#script.name will be replaced with the actual script name.

After writing your documentation, you simply require this script. Then all command line options will get parsed into the EasyOptions.options hash, as described above. You can then check their values for reacting to them. All regular arguments will get stored into the EasyOptions.arguments array.

In fact, this script is an example of itself. You are seeing this help message either because you are reading the source code, or you have called the script in command line with the –help option.

Note: the options and arguments are also available as global variables in
current version, but their use is discouraged and is supposed to be
eventually removed.

This script can be used from Bash scripts as well. If the $from environment variable is set, that will be assumed as the source Bash script from which to parse the documentation and the provided options. Then, instead of parsing the options into Ruby variables, evaluable assignment statements will be generated for the corresponding Bash environment variables. For example:

eval "$(from="$0" @script.name "$@" || echo exit 1)"

If the script containing this command is documented as in the example above, and it is executed from command line with the -o and –some-value=10 options, and one regular argument abc, then the evaluable output would look like this:

option="yes"
some_value="10"
unset arguments
arguments+=("abc")
arguments