help_parser 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0e34375237fe8e17187ef472cdec33cecb71a604
-  data.tar.gz: ddb37f1e37e3900494b3099ad8d944cfbdb5847e
+  metadata.gz: 8f2cddf5444a61128c4e9dee462687c0b806cc14
+  data.tar.gz: b3771ac46dd21a3c35a9b364044d9f7c8ac72eba
 SHA512:
-  metadata.gz: 4eaf7e06d366440c40e7519656e1dc05a04b4efde4af03e691dcbbe693ba177165622dac7cb608c515ce7eece9ab9f9fed0b96c9c45f7000460a4d2c168b7ea4
-  data.tar.gz: 17a48d312dd790501189f5ab05a94f6c55d59d8aa613988223ce464415cb50ff05aae6eddccf1119d57772fff1ab35507cdff55315f797e3d5c2c65d7f546760
+  metadata.gz: 452bd92f2c59ab12e26dbf7df0770f32fd12182bfd6dc3899b5d79fdccd9382daf1d908dce056833f4737f45cd3b521053d6425aca16ada30315f66f268c4dfd
+  data.tar.gz: 6578b276cfb4be11bf3597a650f3dd6661ddf4811e4a35b41b1d0c6394c700b3f1039df9724836e3c57b1a3938e6d4032e3e120ed3df55dd5dfb490c59b87a53

data/README.rdoc

@@ -1,5 +1,7 @@
 = HelpParser
 
+This is version 3!
+
 github :: https://www.github.com/carlosjhr64/help_parser
 rubygems :: https://rubygems.org/gems/help_parser
 
@@ -10,48 +12,45 @@ HelpParser - Parses your help text to define your command line options.
 == FEATURES/PROBLEMS:
 
 * long to short option mapping
-* --no-lopt sets lopt to false
 
 == SYNOPSIS:
 
-  require 'help_parser'
-  include HELP_PARSER
-  HELP = <<HELP
-  Usage:
-    mycmdapp [options] command
-  Options:
-    -h --help      Show this help and exit
-    -v --version   Show the version and exit
-    -q --quiet     Be quiet
-    -V --verbose   Say more about whats going on
-    --value=5.0    Pass values, provide default.
-  HELP
-  begin
-    OPTIONS = HelpParser.new('1.0.0', HELP)
-    puts "Tracing..." unless OPTIONS[:quiet]
-    puts "More tracing..." if OPTIONS[:V] # verbose
-    if value = OPTIONS[:value]
-      if value == 5.0
-        # --value by itself gives the give default.
-        puts "You gave the default value of 5.0."
-      else
-        puts "You gave different value #{value}."
-      end
+    #!/usr/bin/env ruby
+    require 'help_parser'
+    VERSION = '1.2.3'
+    HELP = <<HELP
+    ### cmd ###
+    Usage:
+      cmd --wut <price> <count> <name>
+      cmd [:options] <args>+
+    Options:
+      -h --help   \tTab marks comment
+      -v --version\tShort and long synonyms
+      -q --quiet
+      -V --verbose
+      --val 5.0   \tProvided default to long
+      --number    \tLike --number=3
+    Types:
+      Float --val price   \tPredefined Float and Int
+      Int   --number count
+      ^[A-Z][a-z]+$ name  \tUser defined type
+    Notes:
+      Stuff the help parser will ignore.
+    HELP
+    OPTIONS = HelpParser.new(VERSION, HELP)
+    # Shorts and longs as booleans via missing ? methods
+    "Got Options!" unless OPTIONS.q?
+    puts OPTIONS if OPTIONS.V?
+    # Long values via missing ! methods
+    puts "val = #{OPTIONS.val!}"
+    # Arguments via plain missing methods
+    if OPTIONS.wut?
+      puts "price = '#{OPTIONS.price}'"
+      puts "count = '#{OPTIONS.count}'"
+      puts "name = '#{OPTIONS.name}'"
     else
-      puts "You did not give me a value."
+      puts "args = '#{OPTIONS.args.join(',')}'"
     end
-    # mycmdapp code continues...
-    # ...
-  rescue UsageException
-    puts $!.message # User just wants help or version
-    exit 0  # Not an error
-  rescue UsageError
-    STDERR.puts '*** '+$!.message+' ***'
-    STDERR.puts $!.obj.help
-    exit 64 # Usage error exit code
-  end
-
-See `examples/command_suite` for an example of how to build a command suite with HelpParser.
 
 == INSTALL:
 
@@ -59,25 +58,6 @@ See `examples/command_suite` for an example of how to build a command suite with
 
 == LICENSE:
 
-(The MIT License)
-
-Copyright (c) 2013 CarlosJHR64
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+(The "Can't touch this, b/c it's all mine!" License)
 
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2016 CarlosJHR64

data/lib/help_parser/constants.rb

@@ -0,0 +1,30 @@
+module HELP_PARSER # Constants
+
+  NOTES,USAGE,TYPES = 'notes','usage','types'
+  Z,M,E,P,Q,I = '','-','=','[',']',''
+  H,LH,V,LV = '-h','--help','-v','--version'
+
+  S,SNS = /\s/,/\s*\n\s*/
+
+  COLOR = [
+    "\e[0m",    # no color
+    "\e[1;31m", # red
+  ]
+
+  FLOAT,INT = 'Float', 'Int'
+  Types = {
+    INT   => /^[+-]?\d+$/,
+    FLOAT => /^[+-]?\d+\.\d+$/,
+  }
+
+  # Errors
+  class UsageError < StandardError
+  end
+  class HelpFormatError < StandardError
+  end
+  class NoMatch < StandardError
+  end
+  class SoftwareError < StandardError
+  end
+  SOFTWARE_ERROR_MSG = 'please submit a bug report'
+end

data/lib/help_parser/help_parser.rb

@@ -1,163 +1,71 @@
 module HELP_PARSER
+  # HelpParser Hash will act as if a GoLang map[string]string.
   class HelpParser < Hash
-    using HELP_PARSER
-
-    # HelpParser.parse parses the argv for command line
-    # options, shifting them out, and passes on the key-value
-    # pairs to the block. no-key values are negated.
-    def self.parse(argv, &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[0..2]=='no-'
-            loption = loption[3..-1]
-            if value
-              raise UsageError, "no-key should not have value: no-#{loption}=#{value}"
+    def consume(argv)
+      n = 0
+      while a = argv.shift
+        if a[0]==M # '-'
+          if a==M
+            self[M] = argv
+            break # end of parse
+          else
+            if a[1]==M
+              k,v = a.split(E,2) # split by '='
+              self[k] = (v)? v : Z # ''
+            else
+              # set each flag
+              a[1..-1].chars.each{|c|self[M+c]=Z}
             end
-            value = :F
           end
-          block.call loption, value
         else
-          # These are single character options...
-          option.each_char do |c|
-            block.call c, :T
-          end
+          # the nth argument
+          self[n.to_s] = a
+          n+=1
         end
       end
     end
 
-    # HelpParser.new(version, help, argv=ARGV, dict={})
-    # Not necessarily in that order, see the code.
-    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
-      preferred = {}
- 
-      raise "Need help" unless help
-      raise "Need version" unless version
-
-      # We ensure the following mappings...
-      dict[:help],    preferred[:help]    = :h, :T
-      dict[:version], preferred[:version] = :v, :T
-
-      # 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|
-          v = :T
-          if i = o.index('=')
-            v = o[i+1..-1]
-            o = o[0...i]
-          end
-          o = o.to_key
-          preferred[o] = v
-          o
-        }.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.
-          unless dict[k]==v
-            raise ImplementationError, "#{k} redefinition from #{dict[k]} to #{v}."
-          end
-        end
-        dict[k]=v
+    def initialize(version=nil, help=nil, argv=nil)
+      consume (argv.nil?)? [File.basename($0)]+ARGV : argv
+      if version and (self[V] or self[LV]) # -v or --version
+        puts version
+        exit(0)
       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?
-            raise ImplementationError, "Expected terminal #{v}:  #{k} => #{v} => #{dict[v]}"
-          end
-        else
-          terminals.push(v)
+      if help
+        if self[H] or self[LH] # -h or --help
+          puts help
+          exit(0)
         end
-      end
-      terminals.each{|v| dict[v] = nil}
-
-      # Parsing command line options
-      HelpParser.parse(argv) do |opt, value|
-        key = opt.to_key
-        value = preferred[key] if value.nil?
-        # Translate key to the terminal key.
-        key = dict[key] unless dict[key].nil?
-        # Ensure user only uses the defined keys.
-        unless dict.has_key?(key)
-          raise UsageError, "Not a valid option:  #{opt}"
-        end
-        # As we parse ARGV, we should only be setting keys once.
-        if self.has_key?(key)
-          raise UsageError, "Duplicate command line option:  #{opt}"
-        end
-        self[key] = value.to_value
-      end
-
-      # The parse takes all options to its terminal value.
-      # Now set the synonyms...
-      dict.each do |synonym, 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?(synonym)
-          self[synonym] = self[terminal]
+        begin
+          Usage.new(help).validate(self)
+        rescue UsageError
+          $stderr.puts COLOR[1]+$!.message+COLOR[0]
+          $stderr.puts help
+          exit(64) # Usage
         end
       end
-
-      # Did the user ask for help or version?
-      raise HelpException,    help    if self[:h]==true
-      raise VersionException, version 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.
-      unless !value or value.class == type
-        raise UsageError, "Type error: #{symbol} needs to be #{type}"
+    # obj.m?      ::  !obj['--m'].nil?
+    # obj.method! ::  obj['--method']
+    # obj.method  ::  obj['method']
+    def method_missing(mthd, *args, &block)
+      if args.length==0
+        m=mthd.to_s
+        case m[-1]
+        when '?'
+          if m.length > 2
+            return !self[M+M+m[0..-2]].nil?
+          else
+            return !self[M+m[0]].nil?
+          end
+        when '!'
+          return self[M+M+m[0..-2]]
+        else
+          return self[m]
+        end
       end
-      return value
-    end
-
-    # HelpParser#defaults! is used to replace value with a
-    # default in the hash, self.
-    def defaults!(symbol, default1, default2=default1)
-      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)
+      super
     end
   end
 end

data/lib/help_parser/pattern.rb

@@ -0,0 +1,121 @@
+module HELP_PARSER
+  class Pattern
+    def initialize(options,usage)
+      @options,@usage = options,usage
+      @keys = options.keys
+      @cache = {}
+    end
+
+    def _matches(pattern, i)
+      pattern.each do |token|
+        case token
+        when Array # it's optional
+          begin
+            i = _matches(token,i)
+          rescue NoMatch
+            # Ok, no problem!
+          end
+          next
+        when /^:(.*?)([+]?)$/ # it's a selection
+          list,plus = @usage[$1].flatten,$2
+          raise NoMatch unless list.include?(@keys[i])
+          if plus=='+'
+            while list.include?(@keys[i+1])
+              i+=1
+            end
+          end
+        when /^<(.*)>([+]?)$/ # it's a variable
+          word,plus = $1,$2
+          raise NoMatch if @keys[i].to_i==0
+          if plus=='+'
+            @cache[word] = [@options[@keys[i]]]
+            while @keys[i+1].to_i > 0
+              i+=1
+              @cache[word].push(@options[@keys[i]])
+            end
+          else
+            @cache[word] = @options[@keys[i]]
+          end
+        else # it's a literal
+          if token[0]==M
+            raise NoMatch unless @keys[i]==token
+          else
+            raise NoMatch unless @options[@keys[i]]==token
+          end
+        end
+        i+=1
+      end
+      return i
+    end
+
+    def pad
+      @cache.each{|k,v|@options[k]=v}
+      @usage.each do |name,words|
+        next if [M,USAGE,TYPES].include?(name)
+        words.each do |word|
+          next unless word.length==2
+          k,v = word
+          next unless @options[k].nil?
+          if k[0]==M
+            if k[1]==M
+              # long option default
+              @options[k] = v
+            elsif v[0]==M and !@options[v].nil?
+              # long option synonym
+              @options[k] = @options[v]
+            end
+          else
+            # argument default
+            @options[k] = v
+          end
+        end
+      end
+    end
+
+    def types
+      @usage[TYPES].each do |type,*words|
+        tx = Types[type] || Regexp.new(type)
+        words.each do |word|
+          values = @options[word]
+          next if values.nil?
+          [*values].each do |value|
+            unless tx.match(value)
+              raise UsageError, "ERROR: #{word}=#{value} is not /#{type}/"
+            end
+          end
+          case type
+          when INT
+            case values
+            when Array
+              @options[word]=values.map{|v|v.to_i}
+            when String
+              @options[word]=values.to_i
+            end
+          when FLOAT
+            case values
+            when Array
+              @options[word]=values.map{|v|v.to_f}
+            when String
+              @options[word]=values.to_f
+            end
+          end
+        end
+      end
+    end
+
+    def matches(pattern)
+      begin
+        i = _matches(pattern, 0)
+        raise NoMatch if i != @options.length
+        pad
+        types if @usage[TYPES]
+        return true
+      rescue NoMatch
+        return false
+      ensure
+        @cache.clear
+      end
+      raise SoftwareError, SOFTWARE_ERROR_MSG
+    end
+  end
+end

data/lib/help_parser/usage.rb

@@ -0,0 +1,53 @@
+module HELP_PARSER
+  class Usage < Hash
+    def parse(chars)
+      tokens, token = [], I
+      while c = chars.shift
+        case c
+        when S,P,Q
+          unless token==I
+            tokens.push(token)
+            token = I
+          end
+          tokens.push parse(chars) if c==P
+          return tokens if c==Q
+        else
+          token += c
+        end
+      end
+      tokens.push(token) unless token==I
+      return tokens
+    end
+
+    def initialize(help)
+      name = M # '-'
+      self[name] = []
+      help.strip.split(SNS).each do |line|
+        line.sub!(/\s*\t.*$/,'') # tabs marks comment
+        case line
+        when /^(\w+):$/
+          name = $1.downcase
+          break if name==NOTES
+          raise HelpFormatError, "#{name} section redefinition"  if self[name]
+          self[name] = []
+        when /^\s*#/
+          next
+        else
+          if name==USAGE
+            self[USAGE].push(parse(line.chars))
+          else
+            self[name].push line.split(/\s+/)
+          end
+        end
+      end
+    end
+
+    def validate(options)
+      pattern = Pattern.new(options,self)
+      self[USAGE].each do |cmd|
+        return if pattern.matches(cmd)
+      end
+      raise UsageError, 'Please match usage!'
+    end
+  end
+end

data/lib/help_parser/version.rb

@@ -1,3 +1,3 @@
 module HELP_PARSER
-  VERSION = '2.0.0'
+  VERSION = '3.0.0'
 end

data/lib/help_parser.rb

@@ -1,8 +1,9 @@
 require 'help_parser/version'
-require 'help_parser/exceptions'
-require 'help_parser/errors'
-require 'help_parser/refinements'
+require 'help_parser/constants'
+require 'help_parser/pattern'
+require 'help_parser/usage'
 require 'help_parser/help_parser'
+HelpParser = HELP_PARSER::HelpParser
 
 # Requires:
 #`ruby`

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: help_parser
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - carlosjhr64
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-25 00:00:00.000000000 Z
+date: 2016-10-31 00:00:00.000000000 Z
 dependencies: []
-description: |
-  HelpParser - Parses your help text to define your command line options.
+description: 'HelpParser - Parses your help text to define your command line options.
+
+'
 email: carlosjhr64@gmail.com
 executables: []
 extensions: []
@@ -20,10 +21,10 @@ extra_rdoc_files:
 files:
 - README.rdoc
 - lib/help_parser.rb
-- lib/help_parser/errors.rb
-- lib/help_parser/exceptions.rb
+- lib/help_parser/constants.rb
 - lib/help_parser/help_parser.rb
-- lib/help_parser/refinements.rb
+- lib/help_parser/pattern.rb
+- lib/help_parser/usage.rb
 - lib/help_parser/version.rb
 homepage: https://github.com/carlosjhr64/help_parser
 licenses:
@@ -46,9 +47,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- 'ruby: ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-linux]'
+- 'ruby: ruby 2.3.1p112 (2016-04-26 revision 54768) [x86_64-linux]'
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: HelpParser - Parses your help text to define your command line options.

data/lib/help_parser/errors.rb

@@ -1,16 +0,0 @@
-module HELP_PARSER
-
-  # ImplementationError is an error due to a
-  # inconsistent help text.  The raise is as follows:
-  #    raise ImplementationError, message
-  class ImplementationError < StandardError
-  end
-
-  # UsageError is an error when the user passed command
-  # line options that are inconsistent with expectations.
-  # The raise is as follows:
-  #    raise UsageError, message
-  class UsageError < StandardError
-  end
-
-end

data/lib/help_parser/exceptions.rb

@@ -1,25 +0,0 @@
-module HELP_PARSER
-
-  # 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 is as follows:
-  #    raise UsageException, message
-  class UsageException < Exception
-  end
-
-  # HelpException is a type of UsageException, where the
-  # user asks for help in the command line options.
-  # The raise is as follows:
-  #    raise HelpException, help_message
-  class HelpException < UsageException
-  end
-
-  # VersionException is a type of UsageException, where the
-  # user asks for version in the command line options.
-  # The raise is as follows:
-  #    raise VersionException, version_message
-  class VersionException < UsageException
-  end
-
-end

data/lib/help_parser/refinements.rb

@@ -1,40 +0,0 @@
-module HELP_PARSER
-  # Refinements
-
-  refine Symbol do
-    def to_value
-      case self
-      when :T
-        return true
-      when :F
-        return false
-      end
-      raise "Unrecognized key: #{self}"
-    end
-  end
-
-  refine String do
-    def to_value
-      case self
-      when /^[-+]?\d+$/
-        return self.to_i
-      when /^[-+]?\d+\.\d+([eE][+-]?\d+)?$/
-        return self.to_f
-      when /,/
-        return self.split(',').map{|s| s.to_value}
-      else
-        return self
-      end
-    end
-
-    # 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 to_key
-      self.sub(/^--?/,'').gsub('-','_').to_sym
-    end
-
-  end
-end