argser 1.1

data/README.md

@@ -0,0 +1,186 @@
+# 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
+
+```ruby
+require 'argser'
+
+Argser::Parser.new({
+    options:    {...general options...},
+    params:     {...parameters options...},
+    remaining:  {...remaining array options...}
+})
+```
+
+## GENERAL OPTIONS
+
+- <code>:description</code>, a string containing the description of the application (default: "")
+- <code>:usage</code>, a string describing how to use the application (default: "")
+- <code>:details</code>, a string containing details about the application (default: "")
+- <code>:info</code>, a string printer bellow errors indicating how to find more information about them (default: "For more information try '--help'")
+- <code>:unknown</code>, a string with the message to show when a parameter is not known (default: "Unknown parameter '$p'")
+- <code>:fatal</code>, a string with the message to show when an internal error is found while parsing parameters (default: "An internal error was found")
+- <code>:help</code>, a boolean value indicating if the parser should automatically display the help if parameter :help is given (default: true)
+
+## PARAMETERS OPTIONS
+
+- <code>:shortcut</code>, a symbol used as a shortcut for this parameter (default: nil)
+- <code>:type</code>,  symbol indicating the type of this parameter (default: :string)
+- <code>:default</code>, the default value if not other value is provided (default: '')
+- <code>:required</code>, a boolean value indicating if this parameter is required or not
+- <code>:sanitize</code>, a function to sanitize the value given (return the identifier of a message to show it or the sanitized value the parser should save)
+- <code>:callback</code>, a function to call to do something with the parameter
+- <code>:messages</code> A hash with all available messages to show where the key is used as an identifier (:help, :type and :required are created by default)
+
+## REMAINING ARRAY OPTIONS
+
+- <code>:type</code>, a symbol indicating the type of this parameter (default: :string)
+- <code>:default</code>, the default value if not other value is provided (default: '')
+- <code>:minimum</code>, minimum number of strings allowed
+- <code>:maximum</code>, maximum number of strings allowed
+- <code>:sanitize</code>, a function to sanitize the value given (return the identifier of a message to show it or the sanitized value the parser should save)
+- <code>:callback</code>, a function to call to do something with the parameter
+- <code>:messages</code>,  hash with all available messages to show where the key is used as an identifier (:help, :type and :required are created by default)
+
+## AVAILABLE TYPES
+
+Here is the list of types:
+
+- <code>:integer</code>, integer value (default: 0)
+- <code>:float</code>, float value (default: 0.0)
+- <code>:boolean</code>, boolean value (default: false)
+- <code>:alpanumeric</code>, letters and numbers (default: '')
+- <code>:letters</code>, letters (default: '')
+- <code>:words</code>, words (default: '')
+- <code>:range</code>, integer range (default: [0, 0])
+- <code>:interval</code>, float range (default: [0.0, 0.0])
+- <code>:string</code>, string (default: '')
+
+The default type is <code>:string</code>
+
+# EXAMPLE
+
+```ruby
+require '../lib/argser/parser.rb'
+
+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},
+            messages: {
+                help:  "Specify your age",
+                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!"},
+        messages: {
+            help: "Specify your name and surname",
+            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 a little adult!"
+    end
+else
+    comment = 'how old are you?'
+end
+
+puts "What's up #{parser.remaining[0]}? #{comment}"
+```
+
+## TESTS
+
+```bash
+$ ruby greetings.rb --help
+```
+```
+This is a greeting application
+
+greeting [OPTIONS] NAME
+
+   -a   --age               Specify your age
+   -h   --help              Display this help and exit
+
+Provided your age and your name, this application will greet you in a unique way.
+```
+
+```bash
+$ ruby greetings.rb --age 20
+```
+```
+Incorrect number of remaining arguments
+For more information contact me at foo@/dev/null.com or try '--help'
+```
+
+```bash
+$ 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'
+```
+
+```bash
+$ 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'
+```
+
+```bash
+$ ruby greetings.rb --age 20 "Dummy Name"
+```
+```
+Alright, I got your name!
+What's up Dummy Name? you're a teenager!
+```
+
+```bash
+$ ruby greetings.rb "Dummy Name" --age 25
+```
+```
+Alright, I got your name!
+What's up Dummy Name? you're a young man!
+```
+
+# AUTHOR
+
+Matías Parodi © 2013  
+mparodilabs@gmail.com

data/examples/greetings.rb

@@ -0,0 +1,51 @@
+require '../lib/argser/parser.rb'
+
+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},
+            messages: {
+                help:  "Specify your age",
+                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!"},
+        messages: {
+            help: "Specify your name and surname",
+            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 a little adult!"
+    end
+else
+    comment = 'how old are you?'
+end
+
+puts "What's up #{parser.remaining[0]}? #{comment}"

data/lib/argser/parser.rb

@@ -0,0 +1,300 @@
+module Argser
+
+    class Parser
+
+        @tokens
+        @options
+        @params
+        @remaining
+
+        #Available types (:integer, :float, :boolean, :alpanumeric, :letters, :words, :range, :interval and :string)
+        TYPES = {
+            integer:      [/^\s*\d+\s*$/,                                                                            lambda {|value, match, default| value.to_i || 0}],
+            float:        [/^\s*\d+\.\d+\s*$/,                                                                       lambda {|value, match, default| value.to_f || 0.0}],
+            boolean:      [/^\s*$/,                                                                                  lambda {|value, match, default| !default || false}],
+            letters:      [/^\s*[A-Za-z]+\s*$/,                                                                      lambda {|value, match, default| (!default) ? value.strip : (value || '').strip}],
+            alphanumeric: [/^\s*\w+\s*$/,                                                                            lambda {|value, match, default| (!default) ? value.strip : (value || '').strip}],
+            words:        [/^\s*[A-Za-z]+(?:\s+[A-Za-z]+)*\s*$/,                                                     lambda {|value, match, default| (!default) ? value.strip : (value || '').strip}],
+            range:        [/^\s*(?:(\d+)\.\.(\d+)|(\d*)\.\.|\.\.(\d+))\s*$/,                                         lambda {|value, match, default| (!default) ? [(match[0] || match[3]).to_i, (match[2] || match[4]).to_i] : [0,0]}],
+            interval:     [/^\s*(?:(\d+(?:\.\d+)?)\.\.(\d+(?:\.\d+)?)|(\d*(?:\.\d+)?)\.\.|\.\.(\d+(?:\.\d+)?))\s*$/, lambda {|value, match, default| (!default) ? [(match[0] || match[3]).to_f, (match[2] || match[4]).to_f] : [0.0,0.0]}],
+            string:       [/^.*$/,                                                                                   lambda {|value, match, default| value || ''}]
+        }
+
+        #Initialize the parser
+        def initialize(config)
+            @tokens, @options, @params, @remaining = {}, {}, {}, {}
+            init_options(config[:options] || {})
+            init_params(config[:params] || {})
+            init_remaining(config[:remaining] || {})
+        end
+
+        #Parse an array with arguments and associate each element to one of the parameters or to the remaining array
+        def parse(args)
+            begin
+                #Identify each element in the array of arguments
+                last_param = nil
+                args.each do |arg|
+                    if (arg =~ /^--?\w+$/)
+                        arg = arg.downcase
+
+                        raise_message(@options[:unknown], arg) unless @tokens.has_key? arg
+                        param = @params[@tokens[arg]]
+                        param[:given] = arg
+                        if (@params[@tokens[arg]][:type] != :boolean)
+                            last_param = param
+                        end
+
+                        #If parameter :help was given and the parser is supposed to automatically display the help, do so
+                        help if (param? :help) and (@options[:help])
+                    else
+                        if (last_param)
+                            last_param[:value] = arg
+                            last_param = nil
+                        else
+                            @remaining[:value] = [] if @remaining[:given] == 0
+                            @remaining[:given] += 1
+                            @remaining[:value].push arg
+                        end
+                    end
+                end
+
+                #Iterate over all parameters and process their values
+                @params.each do |token, param|
+                    raise_message(param[:messages][:required], "--#{param[:token].to_s}") unless param?(token) or !param[:required]
+                    validate_param(param)
+                    sanitize(param)
+                end
+
+                #Process the value of the remaining array
+                raise_message(@remaining[:messages][:required]) unless (@remaining[:minimum] <= remaining?) and (remaining? <= @remaining[:maximum])
+                validate_remaining()
+                sanitize(@remaining)
+
+                #Invoke all callbacks
+                invoke_callbacks
+            rescue ParserError => error
+                #In case of error, print the reason and how to find more information
+                puts error.message
+                puts @options[:info] unless @options[:info].empty?
+                exit
+            end
+        end
+
+        #Check if a parameter was given
+        def param?(param)
+            (@tokens.has_key? param) ? !!@params[@tokens[param]][:given] : false
+        end
+
+        #Return the value of a parameter
+        def param(param)
+            (@tokens.has_key? param) ? @params[@tokens[param]][:value] : ''
+        end
+
+        #Returns the number of remaining strings that were found
+        def remaining?()
+            @remaining[:given]
+        end
+
+        #Return the remaining values
+        def remaining()
+            @remaining[:value]
+        end
+
+        #Return both parameters and remaining values in a hash
+        def dump
+            values = {}
+            @params.each do |token, param|
+                values[token] = param[:value]
+            end
+            {params: values, remaining: @remaining[:value]}
+        end
+
+        #Display the help and exit
+        def help
+            puts "#{@options[:description]}\n\n" unless @options[:description].empty?
+            puts "#{@options[:usage]}\n\n"  unless @options[:usage].empty?
+            @params.each do |token, param|
+                token = "--#{token.to_s}"
+                shortcut = (param[:shortcut].is_a? Symbol) ? "-#{param[:shortcut]}" : ''
+                help = param[:messages][:help]
+                puts "   #{shortcut.ljust(5, ' ')}#{token.ljust(20, ' ')}#{help}"
+            end
+            puts "\n"
+            puts "#{@options[:details]}" unless @options[:details].empty?
+            exit
+        end
+
+        private
+
+            #Available 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 message to show when a parameter is not known (default: "Unknown parameter '$p'")
+            #   :fatal          A string with the message 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)
+
+            #Save all options for the parser
+            def init_options(options={})
+                @options = {
+                    description: "",
+                    usage:       "",
+                    details:     "",
+                    info:        "For more information try '--help'",
+                    unknown:     "Unknown parameter '$p'",
+                    fatal:       "An internal error was found",
+                    help:        true
+                }.merge options
+            end
+
+            #Available parameter options:
+            #   :shortcut    A symbol used as a shortcut for this parameter (default: nil)
+            #   :type        A 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 a message to show it or the sanitized value the parser should save)
+            #   :callback    A function to call to do something with the parameter
+            #   :messages    A hash with all available messages to show where the key is used as an identifier (:help, :type and :required are created by default)
+
+            #Save all parameters the parser should recognize
+            def init_params(params={})
+                #If the parser should recognize :help, add it
+                if (!params.has_key? :help) and (@options[:help])
+                    params[:help] = {
+                        shortcut: :h,
+                        type:     :boolean,
+                        default:  false,
+                        messages: {
+                            help: 'Display this help and exit'
+                        }
+                    }
+                end
+
+                #Save each param and overwrite default options
+                params.each do |token, param|
+                    @params[token] = {
+                        shortcut: nil,
+                        type:     :string,
+                        default:  '',
+                        required: false,
+                        sanitize: lambda {|value, default| value},
+                        callback: lambda {|value, default|},
+                        messages: {}
+                    }.merge param
+
+                    @params[token][:token] = token
+                    @params[token][:value] = @params[token][:default]
+                    @params[token][:given] = false
+
+                    #Save messages, make sure :help, :type and :required is available
+                    @params[token][:messages] = {
+                        help:     "",
+                        type:     "Invalid value '$v' for parameter '$p'",
+                        required: "Parameter '$p' is required"
+                    }.merge @params[token][:messages]
+
+                    #Register all tokens for the parameter
+                    @tokens[token] = token
+                    @tokens["--#{token}"] = token
+                    if (param[:shortcut].is_a? Symbol)
+                        @tokens[param[:shortcut]] = token
+                        @tokens["-#{param[:shortcut]}"] = token
+                    end
+                end
+            end
+
+            #Available 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 (default: 0)
+            #   :maximum     Maximum number of strings allowed (default: Infinity)
+            #   :sanitize    A function to sanitize the value given (return the identifier of a message to show it or the sanitized value the parser should save)
+            #   :callback    A function to call to do something with the parameter
+            #   :messages    A hash with all available messages to show where the key is used as an identifier (:help, :type and :required are created by default)
+
+            #Save options for remaining strings
+            def init_remaining(remaining={})
+                @remaining = {
+                    type:     :string,
+                    default:  [],
+                    minimum: 0,
+                    maximum: Float::INFINITY,
+                    sanitize: lambda {|value, default| value},
+                    callback: lambda {|value, default|},
+                    messages: {}
+                }.merge remaining
+
+                @remaining[:value] = @remaining[:default]
+                @remaining[:given] = 0
+
+                #Save messages, make sure :help, :type and :required is available
+                @remaining[:messages] = {
+                    help:     "",
+                    type:     "Invalid value '$v'",
+                    required: "Incorrect number of remaining arguments"
+                }.merge @remaining[:messages]
+            end
+
+            #Validate the value of a parameter based on its type
+            def validate_param(param)
+                #If the type is a symbol, it must be a valid type
+                if (param[:type].is_a? Symbol)
+                    type = TYPES[param[:type]]
+                    raise_message(param[:messages][:type], param[:token], param[:value]) if (param[:given]) and (param[:value].is_a? String) and !(match = type[0].match param[:value])
+                    #Convert value to the correct type
+                    param[:value] = type[1].call(param[:value], match, !param[:given])
+                else #Otherwise it must be a regexp and the value must match
+                    raise_message(param[:messages][:type], param[:token], param[:value]) unless param[:value] =~ param[:type]
+                end
+            end
+
+            #Validate the value of the remaining array based on its type
+            def validate_remaining()
+                #If the type is a symbol, it must be a valid type
+                if (@remaining[:type].is_a? Symbol)
+                    type = TYPES[@remaining[:type]]
+                    @remaining[:value].each_with_index do |value, i|
+                        raise_message(@remaining[:messages][:type], @remaining[:token], value) unless (@remaining[:given] == 0) or (match = type[0].match value)
+                        #Convert value to the correct type
+                        @remaining[:value][i] = type[1].call(value, match, @remaining[:given] == 0)
+                    end
+                else #Otherwise it must be a regexp and the values must match
+                    @remaining[:value].each do |value|
+                        raise_message(@remaining[:messages][:type], @remaining[:token], value) unless value =~ @remaining[:type]
+                    end
+                end
+            end
+
+            #Sanitize the value of the parameter, if a symbol is returned the associated message is shown
+            def sanitize(param)
+                value = param[:sanitize].call(param[:value], !param[:given])
+                raise_message(param[:messages][value], param[:token], param[:value]) if value.is_a? Symbol
+                #Update the value
+                param[:value] = value
+            end
+
+            #Invoke parameters and remaining array callbacks
+            def invoke_callbacks
+                @params.each do |token, param|
+                    param[:callback].call(param[:value], !param[:given])
+                end
+                @remaining[:callback].call(@remaining[:value], !@remaining[:given])
+            end
+
+            #Raise an error message
+            def raise_message(message, token='', value='')
+                raise ParserError.new(message || @options[:fatal], token, value)
+            end
+
+            #Parser errors used to display messages ($p is replaced by the parameter used by the user, $v is replaced by the value given)
+            class ParserError < Exception
+                attr_reader :message
+                def initialize(message, token='', value='')
+                    @message = message.gsub('$p', token.to_s).gsub('$v', value.to_s)
+                end
+            end
+
+    end
+
+end

data/lib/argser.rb

@@ -0,0 +1,10 @@
+#Argser 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.
+#
+#Author: Matías Parodi © 2013
+#
+module Argser
+    require 'argser/parser'
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: argser
+version: !ruby/object:Gem::Version
+  version: '1.1'
+  prerelease: 
+platform: ruby
+authors:
+- Matías Parodi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-14 00:00:00.000000000 Z
+dependencies: []
+description: 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).
+email:
+- mparodilabs@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/argser.rb
+- lib/argser/parser.rb
+- examples/greetings.rb
+homepage: http://rubygems.org/gems/argser
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Argser is a library that aims to simplify the process of parsing arguments
+  in command line scripts written in Ruby
+test_files: []
+has_rdoc: