help_parser 1.0.2

data/features/edge.feature

@@ -0,0 +1,30 @@
+@edge
+Feature: Edge cases
+
+  Scenario: Redefinition of dictionary
+  For example, --help already maps to -h,
+  so if help text says different
+  we should get an ImplementationError.
+    * Given command "./examples/implementation_error_redefinition"
+    * Given option ""
+    * When we run command
+    * Then exception is "HELP_PARSER::ImplementationError"
+    * Then message matches "redefinition"
+
+  Scenario: Terminal
+  For example, -h defines the "user wants help" state.
+  If the help text tries to create another terminal state for -h,
+  we should get an ImplementationError.
+    * Given command "./examples/implementation_error_terminal"
+    * Given option ""
+    * When we run command
+    * Then exception is "HELP_PARSER::ImplementationError"
+    * Then message matches "terminal"
+
+  Scenario: Redifinition in help text
+  For example, it the help text says --zebra is -z and -a.
+    * Given command "./examples/implementation_error_duplicate_key"
+    * Given option ""
+    * When we run command
+    * Then exception is "HELP_PARSER::ImplementationError"
+    * Then message matches "redefinition"

data/features/simple.feature

@@ -0,0 +1,125 @@
+@simple
+Feature: Testing examples/simple
+
+  Background:
+    * Given command "./examples/simple"
+
+  Scenario: Version, short option: -v
+    * Given option "-v"
+    * When we run command
+    * Then exception is "HELP_PARSER::VersionException"
+    * Then message is "1.2.3"
+    * Then options[v] is "true"
+    * Then options[version] is "true"
+
+  Scenario: Version, long option: --version
+    * Given option "--version"
+    * When we run command
+    * Then exception is "HELP_PARSER::VersionException"
+    * Then message is "1.2.3"
+    * Then options[v] is "true"
+    * Then options[version] is "true"
+
+  Scenario: Help, short option: -h
+    * Given option "-h"
+    * When we run command
+    * Then exception is "HELP_PARSER::HelpException"
+    * Then message matches "^Usage:"
+    * Then options[h] is "true"
+    * Then options[help] is "true"
+
+  Scenario: Help, long option: --help
+    * Given option "--help"
+    * When we run command
+    * Then exception is "HELP_PARSER::HelpException"
+    * Then message matches "^Usage:"
+    * Then options[h] is "true"
+    * Then options[help] is "true"
+
+  Scenario: Duplicate with long option: -h --help
+    * Given option "-h --help"
+    * When we run command
+    * Then exception is "HELP_PARSER::UsageError"
+    * Then message matches "^duplicate"
+
+  Scenario: Duplicate with short option: --help -h
+    * Given option "-h --help"
+    * When we run command
+    * Then exception is "HELP_PARSER::UsageError"
+    * Then message matches "^duplicate"
+
+  Scenario: No options: ""
+    * Given option ""
+    * When we run command
+    * Then exception is ""
+    * Then message is ""
+    * Then options.empty?
+
+  Scenario: No comment: --nocomment
+  We don't need to comment a command line option in the help.
+    * Given option "--nocomment"
+    * When we run command
+    * Then exception is ""
+    * Then message is ""
+    * Then options[nocomment] is "true"
+    * Then options.length is 1
+
+  Scenario: Long option values, String: --long=aStringValue
+    * Given option "--long=aStringValue"
+    * When we run command
+    * Then options[long] is "aStringValue"
+
+  Scenario: Long option values, Integer: --long=42
+    * Given option "--long=42"
+    * When we run command
+    * Then options[long] is "42"
+    * Then options[long] kind of Integer
+
+  Scenario: Long option values, default true: --long
+    * Given option "--long"
+    * When we run command
+    * Then options[long] is "true"
+
+  Scenario: Long option values, negated: --no-long
+    * Given option "--no-long"
+    * When we run command
+    * Then options[long] is "false"
+
+  Scenario: Long option values, Array: long=1,2,3
+    * Given option "--long=1,2,3"
+    * When we run command
+    * Then options[long] kind of Array
+
+  Scenario: Three non synonim-ed keys: -k, -V, --nocomment
+    * Given options "--nocomment -k -V"
+    * When we run command
+    * Then options.length is 3
+    * Then options[k] is "true"
+    * Then options[V] is "true"
+    * Then options[nocomment] is "true"
+
+  Scenario: One synonim-ed key: -s
+    * Given options "-s"
+    * When we run command
+    * Then options.length is 2
+    * Then options[s] is "true"
+    * Then options[long] is "true"
+
+  Scenario: One synonim-ed key: --long=abc
+    * Given options "--long=abc"
+    * When we run command
+    * Then options.length is 2
+    * Then options[s] is "abc"
+    * Then options[long] is "abc"
+
+  Scenario: Attempting to set a negation: --no-long=NotAllowed
+    * Given options "--no-long=NotAllowed"
+    * When we run command
+    * Then exception is "HELP_PARSER::UsageError"
+    * Then message matches "no-long=NotAllowed"
+
+  Scenario: User passed undefined option: --cacahuates
+    * Given option "--cacahuates"
+    * When we run command
+    * Then exception is "HELP_PARSER::UsageError"
+    * Then message matches "not.*valid.*cacahuates"

data/features/step_definitions/help_parser_steps.rb

@@ -0,0 +1,80 @@
+require 'json'
+require 'open3'
+
+Given /Given command "([^"]*)"/ do |command|
+  @command = command
+end
+
+Given /Given option(s?) "([^"]*)"/ do |p, options|
+  @options = options
+end
+
+When /When we run command/ do
+  @stdout, @stderr, @status = Open3.capture3("#{@command} #{@options}")
+  begin
+    @json = JSON.parse @stdout
+  rescue StandardError
+    @json = {}
+  end
+end
+
+Then /Then exit status is "(\d+)"/ do |status|
+  unless @status.exit_status == status.to_i
+    raise "Got #{@status.exit_status} instead of #{status}"
+  end
+end
+
+Then /Then (\w+) is "([^"]*)"/ do |key, expected|
+  value = @json[key].to_s
+  unless value == expected
+    raise "Got '#{value}' instead of '#{expected}'"
+  end
+end
+
+Then /Then (\w+) matches "([^"]*)"/ do |key, expected|
+  value = @json[key]
+  unless value =~ /#{expected}/
+    raise "'#{expected}' did not match:\n#{value}"
+  end
+end
+
+Then /Then options\[(\w+)\] is "([^*]*)"/ do |key,expected|
+  options = @json['options']
+  value = (options)? options[key].to_s : ''
+  unless expected == value
+    raise "Got '#{value}' instead of '#{expected}'"
+  end
+end
+
+Then /Then options\[(\w+)\] kind of (\w+)/ do |key, type|
+  options = @json['options']
+  value = options[key]
+  case type
+  when 'Integer'
+    raise "Not an integer" unless value.kind_of?(Integer)
+  when 'Array'
+    raise "Not an array" unless value.kind_of?(Array)
+  else
+    raise "Unrecognized type #{type}"
+  end
+end
+
+Then /Then options.empty\?/ do
+  options = @json['options']
+  raise "options not empty!" unless options.empty?
+end
+
+Then /Then options.length is (\d+)/ do |expected|
+  expected = expected.to_i
+  options = @json['options']
+  actual = options.length
+  raise "Length was #{actual}, not #{expected}." unless actual == expected
+end
+
+=begin
+Then // do ||
+  unless == 
+    raise "Got '#{@json['']}' instead of '#{}'"
+  end
+end
+=end

data/features/suite.feature

@@ -0,0 +1,131 @@
+@suite
+Feature: Testing examples/command_suite
+
+  Background:
+    * Given command "./examples/command_suite"
+
+  Scenario: Version: -v
+    * Given option "-v"
+    * When we run command
+    * Then message is "10.02.3"
+    * Then exception is "HELP_PARSER::VersionException"
+    * Then options[v] is "true"
+    * Then options[version] is "true"
+    * Then command is ""
+
+  Scenario: Help: --help
+    * Given option "--help"
+    * When we run command
+    * Then message matches "^This is a test script"
+    * Then exception is "HELP_PARSER::HelpException"
+    * Then options[h] is "true"
+    * Then options[help] is "true"
+    * Then command is ""
+
+  Scenario: First Version: first --version
+    * Given option "first --version"
+    * When we run command
+    * Then message is "10.02.3"
+    * Then exception is "HELP_PARSER::VersionException"
+    * Then options[v] is "true"
+    * Then options[version] is "true"
+    * Then command is "first"
+
+  Scenario: First Help: first -h
+    * Given option "first --h"
+    * When we run command
+    * Then message matches "^command_suite-first"
+    * Then exception is "HELP_PARSER::HelpException"
+    * Then options[h] is "true"
+    * Then options[help] is "true"
+    * Then command is "first"
+
+  Scenario: Second Version: second --version
+    * Given option "second --version"
+    * When we run command
+    * Then message is "10.02.3"
+    * Then exception is "HELP_PARSER::VersionException"
+    * Then options[v] is "true"
+    * Then options[version] is "true"
+    * Then command is "second"
+
+  Scenario: Second Help: second -h
+    * Given option "second --h"
+    * When we run command
+    * Then message matches "^command_suite-second"
+    * Then exception is "HELP_PARSER::HelpException"
+    * Then options[h] is "true"
+    * Then options[help] is "true"
+    * Then command is "second"
+
+  Scenario: ""
+    * Given option ""
+    * When we run command
+    * Then message is "Need command."
+    * Then exception is "HELP_PARSER::UsageError"
+
+  Scenario: "first"
+    * Given option "first"
+    * When we run command
+    #
+    * Then string is "string1"
+    * Then float is "1.0"
+    * Then integer is "1"
+    #
+    * Then cstring is "string1"
+    * Then cfloat is "1.0"
+    * Then cinteger is "1"
+    #
+    * Then command is "first"
+
+  Scenario: "first --string --float --integer"
+    * Given options "first --string --float --integer"
+    * When we run command
+    #
+    * Then string is "string1"
+    * Then float is "1.0"
+    * Then integer is "1"
+    #
+    * Then cstring is "string2"
+    * Then cfloat is "2.0"
+    * Then cinteger is "2"
+    #
+    * Then command is "first"
+
+  Scenario: "--string --float --integer  second  --string=string3 --float=3.0 --integer=3"
+    * Given options "--string --float --integer  second  --string=string3 --float=3.0 --integer=3"
+    * When we run command
+    #
+    * Then string is "string2"
+    * Then float is "2.0"
+    * Then integer is "2"
+    #
+    * Then cstring is "string3"
+    * Then cfloat is "3.0"
+    * Then cinteger is "3"
+    #
+    * Then command is "second"
+
+  Scenario: "--string=1 second"
+    * Given options "--string=1 second"
+    * When we run command
+    * Then exception is "HELP_PARSER::UsageError"
+    * Then message matches "^type error.*String"
+
+  Scenario: "second --integer=string"
+    * Given options "second --integer=string"
+    * When we run command
+    * Then exception is "HELP_PARSER::UsageError"
+    * Then message matches "^type error.*Fixnum"
+
+  Scenario: "first --float=1"
+    * Given options "first --float=1"
+    * When we run command
+    * Then exception is "HELP_PARSER::UsageError"
+    * Then message matches "^type error.*Float"
+
+  Scenario: "--array=seven first"
+    * Given options "--array=seven first"
+    * When we run command
+    * Then exception is "HELP_PARSER::UsageError"
+    * Then message matches "^type error.*Array"

data/help_parser.gemspec

@@ -0,0 +1,52 @@
+Gem::Specification.new do |s|
+
+  s.name     = 'help_parser'
+  s.version  = '1.0.2'
+
+  s.homepage = 'https://github.com/carlosjhr64/help_parser'
+
+  s.author   = 'CarlosJHR64'
+  s.email    = 'carlosjhr64@gmail.com'
+
+  s.date     = '2013-12-13'
+  s.licenses = ['MIT']
+
+  s.description = <<DESCRIPTION
+_HelpParser_ - Parses your help text to define your command line options.
+DESCRIPTION
+
+  s.summary = <<SUMMARY
+_HelpParser_ - Parses your help text to define your command line options.
+SUMMARY
+
+  s.extra_rdoc_files = ['README.rdoc']
+  s.rdoc_options     = ["--main", "README.rdoc"]
+
+  s.require_paths = ["lib"]
+  s.files = %w(
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+TODO.txt
+examples/command_suite
+examples/implementation_error_duplicate_key
+examples/implementation_error_redefinition
+examples/implementation_error_terminal
+examples/simple
+features/edge.feature
+features/simple.feature
+features/step_definitions/help_parser_steps.rb
+features/suite.feature
+help_parser.gemspec
+lib/help_parser.rb
+lib/help_parser/help_parser.rb
+lib/help_parser/version.rb
+tasks/gemspecker.rb
+tasks/manifester.rb
+tasks/syntaxer.rb
+tasks/unit_tests.rb
+test/help_parser.rb
+)
+
+end

data/lib/help_parser.rb

@@ -0,0 +1,2 @@
+require 'help_parser/version.rb'
+require 'help_parser/help_parser.rb'

data/lib/help_parser/help_parser.rb

@@ -0,0 +1,285 @@
+module HELP_PARSER
+
+  # **UsageError** is an error when the user passed command
+  # line options that are inconsistent with expectations.
+  # The raise in a class method is as follows:
+  #    raise UsageError, [message, self]
+  # The object that raised the error will be available as:
+  #    $!.obj
+  class UsageError < StandardError
+    attr_accessor :obj
+    def initialize(array)
+      self.obj = array.pop
+      msg = array.pop
+      super(msg)
+    end
+  end
+  # **ImplementationError** is an error due to a
+  # inconsistent help text.  The raise in a class method is
+  # as follows:
+  #    raise ImplementationError, [message, self]
+  # The object that raised the error will be available as:
+  #    $!.obj
+  class ImplementationError < StandardError
+    attr_accessor :obj
+    def initialize(array)
+      self.obj = array.pop
+      msg = array.pop
+      super(msg)
+    end
+  end
+
+  # UsageException is an actual exception to normal flow.
+  # For example, when a user asks for help or version
+  # number in the command line options.  The raise in a
+  # class method is as follows:
+  #    raise UsageException, [message, self]
+  # The object that raised the exception will be available
+  # as:
+  #    $!.obj
+  class UsageException < Exception
+    attr_accessor :obj
+    def initialize(array)
+      self.obj = array.pop
+      msg = array.pop
+      super(msg)
+    end
+  end
+
+  # HelpException is a type of UsageException, where the
+  # user asks for help in the command line options.  The
+  # raise in a class method is as follows:
+  #    raise HelpException, self
+  # The object that raised the exception will be available
+  # as:
+  #    $!.obj
+  # The message will be the help text:
+  #    $!.message == $!.obj.help # => true
+  class HelpException < UsageException
+    def initialize(help_parser)
+      super([help_parser.help, help_parser])
+    end
+  end
+
+  # VersionException is a type of UsageException, where the
+  # user asks for version in the command line options.  The
+  # raise in a class method is as follows:
+  #    raise VersionException, self
+  # The object that raised the exception will be available
+  # as:
+  #    $!.obj
+  # The message will be the version text:
+  #    $!.message == $!.obj.version # => true
+  class VersionException < UsageException
+    def initialize(help_parser)
+      super([help_parser.version, help_parser])
+    end
+  end
+
+  module Errors
+    # HelpParser#usage_error will have make the HelpParser
+    # object raise a UsageError error with the given message.
+    def usage_error(msg)
+      raise UsageError, [msg, self]
+    end
+
+    # HelpParser#implementation_error will have make the
+    # HelpParser object raise a UsageError error with the
+    # given message.
+    def implementation_error(msg)
+      raise ImplementationError, [msg, self]
+    end
+  end
+
+class HelpParser < Hash
+include Errors
+
+  # I'm wrapping class functions in a Function module.
+  module Function
+
+    # I'm wrapping Function's helper functions in a Private
+    # module.
+    module Private
+      # HelpParser::Function::Private.to_value
+      def to_value(string)
+        case string
+        when /^-?\d+$/
+          return string.to_i
+        when /^-?\d+\.\d+$/
+          return string.to_f
+        when /,/
+          return string.split(',').map{|s| to_value(s)}
+        end
+        return string
+      end
+    end
+    extend Private
+
+    # HelpParser::Function.str2sym converts String keys to
+    # Symbol.  Symbol keys can have '-', but it's cumbersome
+    # notation:
+    #    :"a-b"
+    # So I translate it to underscore:
+    #    :a_b
+    def str2sym(str)
+      str.gsub('-','_').to_sym
+    end
+
+    # HelpParser#parse parses the @argv for command line
+    # options, shifting them out, and passes on the key-value
+    # pairs to the block.  The keys are translated to their
+    # short version if available, and the values are converted
+    # to their best interpreted form as per Funtion.to_value.
+    # Furthermore, no-key values are negated.
+    def parse(argv, obj, &block)
+      while argv[0] and argv[0][0]=='-'
+        option = argv.shift[1..-1]
+        if option[0]=='-'
+          loption, value = option[1..-1].split('=', 2)
+          if loption=~/no-(\w.*)$/
+            loption = $1
+            if value
+              raise UsageError, ["no-key should not have value: no-#{loption}=#{value}", obj]
+            end
+            value = false
+          end
+          if value.nil?
+            value = true
+            block.call loption, value
+          else
+            block.call loption, Function.to_value(value)
+          end
+        else
+          # These are single character options...
+          option.each_char do |c|
+            block.call c, true
+          end
+        end
+      end
+    end
+  end
+  extend Function
+
+  def parse(&block)
+    HelpParser.parse(@argv, self, &block)
+  end
+
+
+  # HelpParser.new(version, help, argv=ARGV, dict={})
+  # Not necessarily in that order, see the code.
+  attr_reader :version, :help, :dict
+  def initialize(*parameters)
+    super()
+
+    # Figure out what parameters you were given...
+    @argv      = parameters.detect{|parameter| parameter.class == Array} || ARGV
+    @dict      = parameters.detect{|parameter| parameter.class == Hash } || {}
+    parameters = parameters.select{|parameter| parameter.class == String}
+    @version   = parameters.shift
+    @help      = parameters.pop
+ 
+    raise "Need help" unless @help
+    raise "Need version" unless @version
+
+    # We ensure the following two mappings...
+    @dict[:help] = :h
+    @dict[:version] = :v
+
+    # Using the help for the options definition
+    @help.split("\n").select{|l|
+      (l=~/^\s*-/)
+    }.map{|l|
+      l.strip.split(/[,\s]+/)[0..1].select{|o|
+        o[0]=='-'
+      }.map{|o|
+        HelpParser.str2sym o.sub(/--?/,'').sub(/=.*$/,'')
+      }.reverse
+    }.each do |k,v|
+      unless @dict[k].nil?
+        # This is an implementation error.  The help text is inconsistent.
+        # Note that we may have been given @dict, and we're verifying the help.
+        implementation_error "#{k} redefinition from #{@dict[k]} to #{v}." unless @dict[k]==v
+      end
+      @dict[k]=v
+    end
+
+    # Values must be terminal states, that is for example:
+    # if :version => :v, then :v => nil.
+    terminals = []
+    @dict.each do |k,v|
+      next if v.nil?
+      if @dict.has_key?(v)
+        unless @dict[v].nil?
+          implementation_error "Expected terminal #{v}:  #{k} => #{v} => #{@dict[v]}"
+        end
+      else
+        terminals.push(v)
+      end
+    end
+    terminals.each{|v| @dict[v] = nil}
+
+    # Parsing command line options
+    parse do |opt, value|
+      key = HelpParser.str2sym opt
+      # Translate key to the terminal key.
+      key = @dict[key] unless @dict[key].nil?
+      # Ensure user only uses the defined keys.
+      usage_error "not a valid option:  #{opt}" unless @dict.has_key?(key)
+      # As we parse ARGV, we should only be setting keys once.
+      usage_error "duplicate command line option:  #{opt}" if self.has_key?(key)
+      self[key] = value
+    end
+
+    # The parse takes all options to its terminal value.
+    # Now set the synonims...
+    @dict.each do |synonim, terminal|
+      next if terminal.nil?
+      if self.has_key?(terminal)
+        # I did not mean for the synonyms to have been set yet, so if I do,
+        # I have a bug somewhere.
+        raise "unexpected key overwrite" if self.has_key?(synonim)
+        self[synonim] = self[terminal]
+      end
+    end
+
+    # Did the user ask for help or version?
+    raise HelpException,    self if self[:h]==true
+    raise VersionException, self if self[:v]==true
+  end
+
+  # HelpParser#defaults is a helper method to []
+  def defaults(symbol, default1, default2=default1)
+    type = (default2 || default1).class
+    a = self[symbol]
+    value = (a.nil?)? default1 : a
+    value = default2 if value==true
+    # !value is true if value is false or nil.
+    usage_error "type error: #{symbol} needs to be #{type}" unless !value or value.class == type
+    return value
+  end
+
+  # HelpParser#defaults! is used to replace value with a
+  # default in the hash, self.
+  def defaults!(symbol, default1, default2)
+    self[symbol] = defaults(symbol, default1, default2)
+  end
+
+  # HelpParser#[k, default1=nil, default2=nil]
+  # Basically, for #[k, default1, default2]:
+  #    value = help_parser[k]
+  #    case value
+  #      when nil  then default1
+  #      when true then default2
+  #      else value
+  #    end
+  # For #[k, default1]:
+  #    value = help_parser[k] || default1
+  # For #[k]:
+  #    help_parser[k]
+  # Raises a UsageError if the value is not of the expected
+  # type as given by the last default.
+  def [](k, *defaults12)
+    (defaults12.length==0)? super(k) : defaults(k, *defaults12)
+  end
+end
+end