help_parser 6.3.0 → 7.0.200907

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8f371bee63827fcbd8051796c5fce3421da5a3fc41bf6223e546c28ec99362c
-  data.tar.gz: 4484cae785efb013dfccdbcec34a7f17ed89fe013b0a5018c31f4515e87a9439
+  metadata.gz: 7df1feedeed249286efe5cd5f1e2cc187a91d348eab654d5a6f110292d0c3476
+  data.tar.gz: a3f142a3d2cf4c6bf038b25e3552dfc3f56bfbb3469749386994b0763ccaea4c
 SHA512:
-  metadata.gz: ad1de10f9ba6c1788db1dcae160c5fe8ea8c61432d388c097aab22efe8edfa6f86e22131e43159f8ab944615e8e3aa9e66fa714131e0347a241ded901aba8926
-  data.tar.gz: c4086cff775108315243f191acb81d243b792fdc18718b5390070b67f9b2174f8f5a517bf3a665807a4122bce80118799559f5883142e914f748eaa5f8895884
+  metadata.gz: c3df75b2ae4640bc268e86774facbc7f60e74fda4d58c3262022e3a571cb3d716af2be92e7d1652e2ffa5469a1852da4a412e582141f155fe849f37e62d4e4dc
+  data.tar.gz: 447dfb4939662fec618c4c315f104785e1923a6a625b82ed028981a9ff98c35c9049b23586501c8bd06e244f21de8da4cec2c491bf815a17d3c2d38f93495e4e

data/README.md

@@ -1,73 +1,127 @@
-# Help Parser VI: Tweeker
+# Help Parser VII: Deader
 
+* [VERSION 7.0.200907](https://github.com/carlosjhr64/Ruby-HelpParser/releases)
 * [github](https://www.github.com/carlosjhr64/Ruby-HelpParser)
 * [rubygems](https://rubygems.org/gems/help_parser)
 
 ## DESCRIPTION:
-Welcome to the best Help Parser of all!
-Tweeker!
-Which do you find most helpful?
-Hard?
-I prefer easy.
+
+Can't help YOU???
+You're not the first to say that...
+
+I will parse your help!
 
 ## SYNOPSIS:
+<!-- The following PREVIEW has been approved for ALL PROGRAMMERS by CarlosJHR64.
+For the README validator that checks against me lying....
+```ruby
+unless File.basename($PROGRAM_NAME) == 'deader'
+  # For example's sake say
+  $PROGRAM_NAME = 'deader'
+  # and ARGV is
+  ARGV.concat ["-\-age", "-\-date=2020-09-07", 'invoke', 'the', 'command']
+  # and proceed as if run as:
+  #     awesome -\-name=Doe -\-value  a b c
+end
+```
+The following gem has been rated
+| M | Mature |
+-->
+
+> Who ever you are, you were meant to find me today...
+> there is no turning back!
+> Above all, don't invoke the command!
+
+```ruby
+require "help_parser"
+
+HELP = <<-HELP
+# <= Hash here, parser skips
+# HelpParser: Deader command example #
+Usage:
+  deader :options+ [<args>+]
+  deader [:alternate] <arg=FLOAT>
+  deader literal <arg1=WORD> <arg2=WORD> <arg3=WORD>
+Options:
+  -v --version       \t Give version and quit
+  -h --help          \t Give help and quit
+  -s --long          \t Short long synonyms
+  --command invoke   \t Defaulted
+  --date=DATE        \t Typed
+  --age=INTEGER 80   \t Typed and Defaulted
+  -a --all=YN y      \t Short, long, typed, and defaulted
+  --to_be
+  --not_to_be
+Exclusive:
+  to_be not_to_be    \t Tells parser these are mutually exclusive keys
+Inclusive:
+  date age           \t Tells parser any of these must include all of these
+Alternate:
+  --invoke
+  --wut
+Types:
+  WORD    /^[A-Za-z]+$/
+  DATE    /^\\d\\d\\d\\d-\\d\\d-\\d\\d$/
+  INTEGER /^\\d+$/
+  FLOAT   /^\\d+\\.\\d+$/
+  YN      /^[YNyn]$/
+# <= Hash here, parser breaks out
+# Notes #
+Don't invoke the command.
+HELP
+
+VERSION = "1.2.3"
+
+OPTIONS = HelpParser[VERSION, HELP] #~> HelpParser
+
+# Macros:
+HelpParser.strings?(:args)             # for OPTIONS.args      : Array(String) | Nil
+HelpParser.int?(:age)                  # for OPTIONS.age?      : Integer | Nil
+HelpParser.float(:arg)                 # for options.arg       : Float
+HelpParser.string(:arg1, :arg2, :arg3) # for OPTIONS.arg1, etc : String
+#=> [:arg1, :arg2, :arg3]
+
+## If run as:
+##   deader --age --date=2020-09-07 invoke the command
+OPTIONS.age                  #=> 80
+OPTIONS.args                 #=> ["invoke", "the", "command"]
+OPTIONS.arg? and OPTIONS.arg #=> false
+```
 
-    require "pp"
-    require "help_parser"
-
-    HELP = <<-HELP
-    # <= Hash here, parser skips
-    # The Awesome Command.
-    Usage:
-      awesome [:options+] <args>+
-      awesome :alternate <arg=NAME>
-    Options:
-      -v --version       \t Give version and quit
-      -h --help          \t Give help and quit
-      -s --long          \t Short long synonyms
-      --name=NAME        \t Typed
-      --number 5         \t Defaulted
-      --value=FLOAT 1.23 \t Typed and Defaulted
-      -a --all=YN y      \t Short, long, typed, and defaulted
-    Alternate:
-      -V                 \t Just short
-    Types:
-      NAME  /^[A-Z][a-z]+$/
-      FLOAT /^\\d+\\.\\d+$/
-      YN    /^[YNyn]$/
-    Exclusive:
-      version help       \t Tells parser these are exclusive keys
-    # <= Hash here, parser breaks out
-    # Notes #
-    Blah blah blah
-    HELP
-
-    VERSION = "6.3.0"
-
-    # Macros:
-    HelpParser.string(name)  # for options.name    : String
-    HelpParser.strings(args) # for options.args    : Array(String)
-    HelpParser.float(value)  # for options.value   : Float
-    HelpParser.int?(number)  # for options.number? : Int32 | Nil
-
-    HelpParser.run(VERSION, HELP) do |options|
-      hash = options._hash
-      pp hash # to inspect the hash
-
-      pp options.name  if hash["name"]?
-      pp options.args  if hash["args"]?
-      pp options.value if hash["value"]?
-      pp options.number?
-    end
-
-Well, what do you think?
-PERFECT!
-
-## New for 6.1.0:
-
-Running your `awesome` command with the `--help` flag will also check your help text for errors,
-on top of giving the help text. Otherwise, the parser no longer checks for help text errors.
+YOU HAVE INVOKED THE COMMAND...
+YOUR HELP BELONGS TO ME!!!
+
+## Features
+
+* $DEBUG=true on --debug
+* $VERBOSE=true on --verbose
+* -h and --help simultaneously will check help string for errors
 
 ## INSTALL:
 
     $ sudo gem install help_parser
+
+## LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2020 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 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.

data/lib/help_parser.rb

@@ -11,7 +11,7 @@ require_relative './help_parser/options'
 require_relative './help_parser/macros'
 
 module HelpParser
-  VERSION = '6.3.0'
+  VERSION = '7.0.200907'
 
   def self.[](
     version = nil,

data/lib/help_parser/completion.rb

@@ -3,44 +3,56 @@ module HelpParser
     def initialize(hash, specs)
       @hash,@specs = hash,specs
       @cache = NoDupHash.new
-      usage if @specs.has_key?(USAGE)
+      usage or diagnose  if @specs.has_key?(USAGE)
       pad
-      types
+      types  if @specs.has_key?(TYPES)
     end
 
+    # Which usage does the user's command options match?
     def usage
       @specs[USAGE].each do |cmd|
         begin
           i = matches(cmd)
           raise NoMatch unless @hash.size==i
           @cache.each{|k,v|@hash[k]=v} # Variables
-          return
+          return true # Good! Found matching usage.
         rescue NoMatch
           next
         ensure
           @cache.clear
         end
       end
+      return false # Bad! Did not match any of the expected usage.
+    end
+
+    # Diagnose user's usage.
+    def diagnose
+      dict = {}
+      @specs.each do |k,v|
+        next if RESERVED[k]
+        v.flatten.map{|_|_.scan(/\w+/).first}.each{|_|dict[_]=true}
+      end
+      typos = @hash.keys.select{|k|k.is_a? String and not dict[k]}
+      raise UsageError, MSG[UNRECOGNIZED, typos] unless typos.empty?
+
       raise UsageError, MATCH_USAGE
     end
 
     def types
-      if t2r = HelpParser.t2r(@specs)
-        k2t = HelpParser.k2t(@specs)
-        @hash.each do |key,value|
-          next unless key.is_a?(String)
-          if type = k2t[key]
-            regex = t2r[type]
-            case value
-            when String
-              raise UsageError, "--#{key}=#{value} !~ #{type}=#{regex.inspect}" unless value=~regex
-            when Array
-              value.each do |string|
-                raise UsageError, "--#{key}=#{string} !~ #{type}=#{regex.inspect}" unless string=~regex
-              end
-            else
-              raise UsageError, "--#{key} !~ #{type}=#{regex.inspect}"
+      t2r,k2t = HelpParser.t2r(@specs),HelpParser.k2t(@specs)
+      @hash.each do |key,value|
+        next unless key.is_a?(String)
+        if type = k2t[key]
+          regex = t2r[type]
+          case value
+          when String
+            raise UsageError, "--#{key}=#{value} !~ #{type}=#{regex.inspect}" unless value=~regex
+          when Array
+            value.each do |string|
+              raise UsageError, "--#{key}=#{string} !~ #{type}=#{regex.inspect}" unless string=~regex
             end
+          else
+            raise UsageError, "--#{key} !~ #{type}=#{regex.inspect}"
           end
         end
       end
@@ -65,7 +77,7 @@ module HelpParser
               elsif value = @hash[long]
                 @hash[short] = true
                 if value==true && !default.nil?
-                  @hash.delete(long)
+                  @hash.delete(long) # ArgvHash reset
                   @hash[long]=default
                 end
               end
@@ -74,7 +86,7 @@ module HelpParser
               long,default = first[2..(i-1)],second
               value = @hash[long]
               if value==true
-                @hash.delete(long)
+                @hash.delete(long) # ArgvHash reset
                 @hash[long] = default
               end
             end

data/lib/help_parser/constants.rb

@@ -1,15 +1,8 @@
 module HelpParser
-  @@validate = false
-  def self.validate!
-    @@validate = true
-  end
-  def self.validate?
-    @@validate
-  end
-
   USAGE = 'usage'
   TYPES = 'types'
   EXCLUSIVE = 'exclusive'
+  INCLUSIVE = 'inclusive'
 
   # usage
   FLAG       = /^[-][-]?(?<k>\w+)$/
@@ -29,7 +22,7 @@ module HelpParser
   TYPE_DEF = /^(?<t>[A-Z]+),?\s+\/(?<r>\S+)\/$/
 
   # spec w+( w+)+
-  X_DEF = /^\w+( +\w+)+$/
+  X_DEF = /^\w+( +\w+)+$/ # for both exclusive and inclusive specs
 
   CSV = /,?\s+/
 
@@ -42,18 +35,20 @@ module HelpParser
   DUP_KEY             = 'Duplicate key'
   DUP_WORD            = 'Duplicate word'
   DUP_FLAG            = 'Duplicate flag'
-  DUP_X               = 'Duplicate exclusive spec'
+  DUP_X               = 'Duplicate exclusive/inclusive spec'
   UNSEEN_FLAG         = 'Undefined flag'
   INCONSISTENT        = 'Inconsistent use of variable'
   UNEXPECTED          = 'Unexpected string in help text'
   BAD_REGEX           = 'Bad regex'
   REDUNDANT           = 'Redundant'
   EXCLUSIVE_KEYS      = 'Exclusive keys'
+  INCLUSIVE_KEYS      = 'Inclusive keys'
   UNBALANCED          = 'Unbalanced brackets'
   UNRECOGNIZED_TOKEN  = 'Unrecognized usage token'
   UNRECOGNIZED_TYPE   = 'Unrecognized type spec'
-  UNRECOGNIZED_X      = 'Unrecognized exclusive spec'
+  UNRECOGNIZED_X      = 'Unrecognized exclusive/inclusive spec'
   UNRECOGNIZED_OPTION = 'Unrecognized option spec'
+  UNRECOGNIZED        = 'Unrecognized'
   UNDEFINED_SECTION   = 'Section not defined'
   MISSING_CASES       = 'Missing cases'
   MISSING_USAGE       = 'Missing usage'
@@ -71,7 +66,8 @@ module HelpParser
   EXTRANEOUS_SPACES   = 'Extraneous spaces in help.'
 
   # lambda utilities
-  MSG = lambda{|msg,*keys| "\033[0;31m#{msg}:  #{keys.join(' ')}\033[0m"}
+  MSG = lambda{|msg,*keys| "#{msg}:  #{keys.join(' ')}"}
   F2K = lambda{|f| f[1]=='-' ? f[2..((f.index('=')||0)-1)] : f[1]}
-  RESERVED = lambda{|k| [USAGE,TYPES,EXCLUSIVE].include?(k)} # reserved
+  RESERVED = lambda{|k| [USAGE,TYPES,EXCLUSIVE,INCLUSIVE].include?(k)} # reserved
+  REDTTY = lambda{|msg,out=$stderr| out.tty? ? out.puts("\033[0;31m#{msg}\033[0m"): out.puts(msg)}
 end

data/lib/help_parser/exceptions.rb

@@ -10,9 +10,9 @@ module HelpParser
 
     def exit
       if @code > 0
-        STDERR.puts self.message
+        REDTTY[self.message]
       else
-        puts self.message
+        $stdout.puts self.message
       end
       Kernel.exit @code
     end
@@ -36,10 +36,10 @@ module HelpParser
   end
 
   class NoMatch < HelpParserException
-    # used to shortcircuit out
+    # used to short-circuit out
     def _init; @code = EX_SOFTWARE; end
 
-    # Forces it's owm message
+    # Forces it's own message
     def initialize
       super(NO_MATCH)
     end

data/lib/help_parser/k2t2r.rb

@@ -5,8 +5,11 @@ module HelpParser
     tokens.each do |token|
       if match = VARIABLE.match(token) || LONG.match(token)
         name, type = match['k'], match['t']
-        k2t[name] = type if !k2t.has_key?(name)
-        raise HelpError, MSG[INCONSISTENT,name,type,k2t[name]] if !(type==k2t[name])
+        if _=k2t[name]
+          raise HelpError, MSG[INCONSISTENT,name,type,_]  unless type==_
+        else
+          k2t[name] = type
+        end
       else
         # Expected these to be caught earlier...
         raise SoftwareError, MSG[UNEXPECTED,token]

data/lib/help_parser/options.rb

@@ -7,22 +7,28 @@ module HelpParser
         raise VersionException, version
       end
       if help
-        # -h or --help
-        if @hash.has_key?('h') || _=@hash.has_key?('help')
-          begin
-            # validates help
-            HelpParser.parseh(help, true)
-          rescue HelpError
-            $stderr.puts $!
-          end if _
+        h = ['h', 'help']
+        if h.any?{|_|@hash.key?_}
+          HelpParser.parseh(help, validate: true)  if h.all?{|_|@hash.key?_}
           raise HelpException, help
         end
-        specs = HelpParser.parseh(help, HelpParser.validate?)
+        specs = HelpParser.parseh(help)
         Completion.new(@hash, specs)
         if exclusive=specs[EXCLUSIVE]
-          exclusive.each{|xs| raise HelpParser::UsageError, MSG[EXCLUSIVE_KEYS,*xs] if @hash.keys.count{|k|xs.include?(k)}>1}
+          exclusive.each do |x|
+            count = @hash.keys.count{|k|x.include?(k)}
+            raise HelpParser::UsageError, MSG[EXCLUSIVE_KEYS,*x] if count > 1
+          end
+        end
+        if inclusive=specs[INCLUSIVE]
+          inclusive.each do |i|
+            count = @hash.keys.count{|k|i.include?(k)}
+            raise HelpParser::UsageError, MSG[INCLUSIVE_KEYS,*i] unless count==0 or count==i.length
+          end
         end
       end
+      $VERBOSE = true if @hash['verbose']==true
+      $DEBUG = true if @hash['debug']==true
     end
 
     def _hash

data/lib/help_parser/parseh.rb

@@ -1,5 +1,5 @@
 module HelpParser
-  def self.parseh(help, validate=true)
+  def self.parseh(help, validate: false)
     specs,name = NoDupHash.new,''
     help.each_line do |line|
       line.chomp!
@@ -18,11 +18,11 @@ module HelpParser
           HelpParser.validate_line_chars(spec.chars) if validate
           tokens = HelpParser.parseu(spec.chars)
           HelpParser.validate_usage_tokens(tokens) if validate
-          specs[name].push tokens
+          specs[USAGE].push tokens
         when TYPES
           raise HelpError, MSG[UNRECOGNIZED_TYPE,spec] if validate and not spec=~TYPE_DEF
-          specs[name].push spec.split(CSV)
-        when EXCLUSIVE
+          specs[TYPES].push spec.split(CSV)
+        when EXCLUSIVE,INCLUSIVE
           raise HelpError, MSG[UNRECOGNIZED_X,spec] if validate and not spec=~X_DEF
           specs[name].push spec.split(CSV)
         else

data/lib/help_parser/validations.rb

@@ -30,14 +30,16 @@ module HelpParser
   def self.validate_usage_specs(specs)
     option_specs = specs.select{|a,b| !RESERVED[a]}
     flags = option_specs.values.flatten.select{|f|f[0]=='-'}.map{|f| F2K[f]}
-    if exclusive=specs[EXCLUSIVE]
-      seen = {}
-      exclusive.each do |xs|
-        k = xs.sort.join(' ').to_sym
-        raise HelpError, MSG[DUP_X,k] if seen[k]
-        seen[k] = true
-        xs.each do |x|
-          raise HelpError, MSG[UNSEEN_FLAG, x] unless flags.include?(x)
+    [EXCLUSIVE,INCLUSIVE].each do |k|
+      if a=specs[k]
+        seen = {}
+        a.each do |xs|
+          k = xs.sort.join(' ').to_sym
+          raise HelpError, MSG[DUP_X,k] if seen[k] or not xs.length==xs.uniq.length
+          seen[k] = true
+          xs.each do |x|
+            raise HelpError, MSG[UNSEEN_FLAG, x] unless flags.include?(x)
+          end
         end
       end
     end

metadata

@@ -1,21 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: help_parser
 version: !ruby/object:Gem::Version
-  version: 6.3.0
+  version: 7.0.200907
 platform: ruby
 authors:
 - carlosjhr64
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-01 00:00:00.000000000 Z
+date: 2020-09-07 00:00:00.000000000 Z
 dependencies: []
 description: |
-  Welcome to the best Help Parser of all!
-  Tweeker!
-  Which do you find most helpful?
-  Hard?
-  I prefer easy.
+  Can't help YOU???
+  You're not the first to say that...
+
+  I will parse your help!
 email: carlosjhr64@gmail.com
 executables: []
 extensions: []
@@ -54,11 +53,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- 'ruby: ruby 2.5.0p0 (2017-12-25 revision 61468) [x86_64-linux]'
-rubyforge_project: 
-rubygems_version: 2.7.3
+- 'ruby: ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c) [x86_64-linux]'
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Welcome to the best Help Parser of all! Tweeker! Which do you find most helpful?
-  Hard? I prefer easy.
+summary: Can't help YOU??? You're not the first to say that...
 test_files: []