INTRODUCTION

Argser (from "ARGuments parSER") is a library that aims to simplify the process of parsing arguments in command line scripts written in Ruby. It provides an easy way to specify which parameters are valid, their type or format, error conditions, description, etc. In that way, it reduces the need to write code specificaly to parse and validate such arguments.

The idea is pretty simple. To be able to use the arguments passed when the script was executed in a easy and consistent way, you only need to specify some general options for the application, a list of parameters and some properties that must hold for both, parameters and what is called the 'remaining array' (an array with strings that don't belong to any parameter).

INSTALLATION

gem install argser

USAGE

require 'argser'

Argser::Parser.new({
    options:    {...general options...},
    params:     {...parameters options...},
    remaining:  {...remaining array options...}
})

GENERAL OPTIONS

:description, a string containing the description of the application (default: "")
:usage, a string describing how to use the application (default: "")
:details, a string containing details about the application (default: "")
:info, a string printer bellow errors indicating how to find more information about them (default: "For more information try '--help'")
:unknown, a string with the error to show when a parameter is not known (default: "Unknown parameter '$p'")
:fatal, a string with the error to show when an internal error is found while parsing parameters (default: "An internal error was found")
:help, a boolean value indicating if the parser should automatically display the help if parameter :help is given (default: true)

PARAMETERS OPTIONS

:shortcut, a symbol used as a shortcut for this parameter (default: nil)
:type, symbol indicating the type of this parameter (default: :string)
:default, the default value if not other value is provided (default: '')
:required, a boolean value indicating if this parameter is required or not
:sanitize, a function to sanitize the value given (return the identifier of an error to show it or the sanitized value the parser should save)
:callback, a function to call to do something with the parameter
:help, a string with the message to print as the help for this parameter
:errors, a hash with all available errors to show where the key is used as an identifier (:type and :required are created by default)

REMAINING ARRAY OPTIONS

:type, a symbol indicating the type of this parameter (default: :string)
:default, the default value if not other value is provided (default: '')
:minimum, minimum number of strings allowed
:maximum, maximum number of strings allowed
:sanitize, a function to sanitize the value given (return the identifier of an error to show it or the sanitized value the parser should save)
:callback, a function to call to do something with the parameter
:help, a string with the message to print as the help for the remaining strings
:errors, a hash with all available errors to show where the key is used as an identifier (:type and :required are created by default)

AVAILABLE TYPES

Here is the list of types:

:integer, integer value (default: 0)
:float, float value (default: 0.0)
:boolean, boolean value (default: false)
:alpanumeric, letters and numbers (default: '')
:letters, letters (default: '')
:words, words (default: '')
:range, integer range (default: [0, 0])
:interval, float range (default: [0.0, 0.0])
:string, string (default: '')

The default type is :string

EXAMPLE

require 'argser'

parser = Argser::Parser.new({
    options: {
        description: "This is a greeting application",
        usage:       "greeting [OPTIONS] NAME",
        details:     "Provided your age and your name, this application will greet you in a unique way.",
        info:        "For more information contact me at foo@/dev/null.com or try '--help'",
        unknown:     "What's '$p'?",
        fatal:       "There has been a weird error!!",
        help:        true
    },
    params: {
        age: {
            shortcut: :a,
            default:  18,
            type:     :integer,
            sanitize: lambda {|value, default| (value >= 18) ? value : :young},
            help:  "Specify your age",
            errors: {
                type:  "I can't believe you're '$v' years old",
                young: "You can't use this application unless you're older than 18!"
            }
        }
    },
    remaining: {
        type:    /[A-Z][A-Za-z]+\s[A-Z][A-Za-z]+/,
        minimum: 1,
        maximum: 1,
        callback: lambda {|values, default| puts "Alright, I got your name!"},
        help: "Specify your name and surname",
        errors: {
            type: "What!? Your name is '$v'!?"
        }
    }
})

parser.parse(ARGV)

comment = ''
if (parser.param? :age)
    comment = case parser.param(:age)
        when 18..20 then "you're a teenager!"
        when 21..30 then "you're a young man!"
        when 30..99 then "you're an adult!"
        when 100..1.0/0.0 then "you're awesome!"
    end
else
    comment = 'how old are you?'
end

puts "What's up #{parser.remaining[0]}? #{comment}"

TESTS

$ ruby greetings.rb --help

This is a greeting application

greeting [OPTIONS] NAME

   -a   --age               Specify your age
   -h   --help              Display this help and exit

                            Specify your name and surname

Provided your age and your name, this application will greet you in a unique way.

$ ruby greetings.rb --age 20

Incorrect number of remaining arguments
For more information contact me at foo@/dev/null.com or try '--help'

$ ruby greetings.rb --age 10 "Dummy Name"

You can't use this application unless you're older than 18!
For more information contact me at foo@/dev/null.com or try '--help'

$ ruby greetings.rb --age 20 "Dummy Name" "Another Name"

Incorrect number of remaining arguments
For more information contact me at foo@/dev/null.com or try '--help'

$ ruby greetings.rb --age 20 "Dummy Name"

Alright, I got your name!
What's up Dummy Name? you're a teenager!

$ ruby greetings.rb "Dummy Name" --age 25

Alright, I got your name!
What's up Dummy Name? you're a young man!