help_parser 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2b2c0821ccb920314039d7e8f92851e7be14382a
-  data.tar.gz: f5184113ef5d80ae592c2f923d895527d078d954
+  metadata.gz: 15eed085a057dd27423f3a363e2a172cceecd664
+  data.tar.gz: 9159259d556060cebe4d1241d0065b6252a0280a
 SHA512:
-  metadata.gz: 1afa018ea4504b0dfc00a443e26dda59338f4d7aa0f68f64b72b4c61c1d05d5558a3be3da9427bb07e57152da2fd6c2c77caf2e37d62729a5e3f905df18ec711
-  data.tar.gz: 70bb2be1242c6c094bba0b61e209f7028a8cb47c63f30ed9a9c5e3088d19f23107aa55d872c89bd153dfe73201a32936c967809de63dc16c0ba4ec8e10c4f2ea
+  metadata.gz: 3b8aeb803ca69f593a861d49e574175178a57574fd42664ff853ba229be9b84118fb26c9bed3ed3029c52b1b60727fc3368ab6409a1987da527a645f46f41e4d
+  data.tar.gz: f40a072547ec26b18c174f3f313106132f64299c4356ba07a1b3e915558d73a8ee9674b28dad9533bdcecc21ed678460e4c21e96432fb31f83372d2e85cfcedf

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 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/README.md

@@ -1,151 +1,63 @@
-# HelpParser
-## Version 4!!!
+# Help Parser
+## V: Infamous
 
-* [github](https://www.github.com/carlosjhr64/help_parser)
+* [github](https://www.github.com/carlosjhr64/Ruby-HelpParser)
 * [rubygems](https://rubygems.org/gems/help_parser)
 
 ## DESCRIPTION:
-HelpParser - Parses your help text to define your command line options.
+All help is about to get parsed...
+Again!!!
 
-## INSTALL:
-
-    $ sudo gem install help_parser
-
-## LICENSE:
-[MIT](https://en.wikipedia.org/wiki/MIT_License) Copyright (c) 2017 CarlosJHR64
-
-## MINIMAL
-
-    #!/usr/bin/env ruby
-    require 'help_parser'
-    
-    OPTIONS = HelpParser.new
-    p OPTIONS._hash
+And this time,
+the battle between complexity and simplicity
+has as familiar text.
 
 ## SYNOPSIS:
 
-    #!/usr/bin/env ruby
-    require 'help_parser'
-
-    OPTIONS = HelpParser.new('1.2.3', <<-HELP)
-    Usage:
-      synopsis [:options] <x> <y>
-    Options:
-      --verbose
-    HELP
-
-    # Existentials via missing "?" methods
-    puts 'Whats x * y?' if OPTIONS.verbose?
-
-    # Values via missing methods.
-    puts OPTIONS.x.to_f * OPTIONS.y.to_f
-
-## MORE:
-
-    #!/usr/bin/env ruby
-    require 'help_parser'
-
-    # Any version string, does not have to be semantic versioning.
-    VERSION = '1.2.3'
+    require "pp"
+    require "help_parser"
 
     HELP = <<-HELP
-    ### more ###########################################
-    # Lines starting with the pound sign are comments.
-    # HelpPaser parses the help text by sections
-    # with a heading of the form `<Section Name>:`.
-    # The Usage section gives the allowed forms of the
-    # command.  Keys, arguments, and selectors in
-    # square bracket are optional and can be nested.
-    # A plus sign, `+`, marks the associated token as
-    # taking multiple values. Note that variable
-    # arguments have the form `<name>`.
-    ####################################################
+    The Awesome Command.
     Usage:
-      more --wut <price> <count> [<name>]
-      more [:options] <args>+
-    ####################################################
-    # Tipically you'll have an `Options:` section, but
-    # you can give the section any name.
-    # An `Options:` section should match an `:options`
-    # selector in at least one of your usages.
-    # Assigning values to keys via the command line
-    # is done in the form `--key=value`.
-    ####################################################
+      awesome [:options+] <args>+
+      awesome :alternate <arg=NAME>
     Options:
-      -h --help    \tTab marks comment
-      -v --version \tShort and long synonyms
-      --val 5.0    \tProvided default to long
-      --number     \tLike --number=3
-      --usage
-    ####################################################
-    # The `Defaults:` section can give default values
-    # to arguments and options. 
-    # So for options you have a choice of where to set
-    # your defaults, but for arguments, it's done here.
-    ####################################################
-    Defaults:
-      name Carlos  \tDefault for name
-    ####################################################
-    # HelpPaser has two automatic types, `Float` and
-    # `Int`, which will convert values from String to
-    # Floats and Integers repectively.
-    # You can also provide you own custom validation
-    # with regular expressions.
-    ####################################################
+      -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:
-      Float --val price    \tPredefined Float and Int
-      Int   --number count
-      ^[A-Z][a-z]+$ name   \tUser defined type
-    ####################################################
-    # The start of a `Notes:` section tells HelpParser
-    # to break out of it's parsing.
-    # Anything else written after this heading is of
-    # no consequence to HelpParser.
-    ####################################################
-    Notes:
-      Stuff the help parser will ignore.
+      NAME  /^[A-Z][a-z]+$/
+      FLOAT /^\\d+\\.\\d+$/
+      YN    /^[YNyn]$/
     HELP
 
-    OPTIONS = HelpParser.new(VERSION, HELP)
+    VERSION = "5.0.0"
 
-    # Short and long values via missing methods.
-    # Short and long existentials(booleans) via missing `?` methods.
-    # To avoid name collisions with command line argument and options,
-    # the HelpParser object was subclassed from BasicObject.
-    if OPTIONS.wut?
-      puts "Count:  #{_=OPTIONS.count}\t#{_.class}"
-      puts "Price:  #{_=OPTIONS.price}\t#{_.class}"
-      puts "Name:   #{_=OPTIONS.name}\t#{_.class}"
-    else
-      puts "Args: #{OPTIONS.args.join(', ')}"
-    end
-    puts "Name:   #{_=OPTIONS.name}\t#{_.class}"
-    puts "Val:    #{_=OPTIONS.val}\t#{_.class}"
-    puts "Number: #{_=OPTIONS.number}\t#{_.class}"
+    # 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
 
-    # The objects's hash data method is `_hash`.
-    # You can also get the help text parsed data from `_usage._hash`
-    puts '###'
-    if OPTIONS.usage?
-      p OPTIONS._usage._hash
-    else
-      p OPTIONS._hash
-    end
+    HelpParser.run(VERSION, HELP) do |options|
+      hash = options._hash
+      pp hash # to inspect the hash
 
-## WHY?
-Even with the really nice options parsers available,
-for quick little scripts
-I kept writing stuff like `ARGV.include?(key)`
-or `options=ARGV.select{|a|a[0]=='-'}`.
-Just to have to go back and reimplement with a proper options parser
-when the little script ends up being useful and grows into something bigger.
-And I was doing this after I had written my own previous versions of HelpParser.
-So now I should have no excuse to just use HelpParser.  Always:
+      pp options.name  if hash["name"]?
+      pp options.args  if hash["args"]?
+      pp options.value if hash["value"]?
+      pp options.number?
+    end
 
-    require 'HelpParser'
-    OPTIONS = HelpParser.new # DONE!
+YES!!!
 
-Can't be any simpler.
+## INSTALL:
 
-As the script evolves... add version.. add help text..
-no need to rework the code for not having started out with a proper options parser.
+    $ sudo gem install help_parser

data/lib/help_parser.rb

@@ -1,9 +1,37 @@
-require 'help_parser/constants'
-require 'help_parser/pattern'
-require 'help_parser/usage'
-require 'help_parser/help_parser'
-HelpParser = HELP_PARSER::HelpParser
-HELP_PARSER::VERSION = '4.0.0'
+require_relative "./help_parser/constants"
+require_relative "./help_parser/exceptions"
+require_relative "./help_parser/aliases"
+require_relative "./help_parser/parsea"
+require_relative "./help_parser/validations"
+require_relative "./help_parser/parseu"
+require_relative "./help_parser/parseh"
+require_relative "./help_parser/k2t2r"
+require_relative "./help_parser/completion"
+require_relative "./help_parser/options"
+require_relative "./help_parser/macros"
+
+module HelpParser
+  VERSION = "5.0.0"
+
+  def self.[](
+    version = nil,
+    help    = nil,
+    argv    = [File.basename($0)]+ARGV)
+    Options.new(version, help, argv)
+  rescue HelpParserException => exception
+    exception.exit
+  end
+
+  def self.run(
+    version = nil,
+    help    = nil,
+    argv    = [File.basename($0)]+ARGV)
+    options = Options.new(version, help, argv)
+    yield options
+  rescue HelpParserException => exception
+    exception.exit
+  end
+end
 
 # Requires:
 #`ruby`

data/lib/help_parser/aliases.rb

@@ -0,0 +1,19 @@
+module HelpParser
+  class NoDupHash < Hash
+    def []=(k,v)
+      raise HelpError, "Duplicate key: #{k}" if self.has_key?(k)
+      super
+    end
+  end
+
+  class ArgvHash < Hash
+    def []=(k,v)
+      raise UsageError, "Duplicate key: #{k}" if self.has_key?(k)
+      super
+    end
+  end
+
+  def self.f2k(f)
+    f[1]=='-' ? f[2..((f.index('=')||0)-1)] : f[1]
+  end
+end

data/lib/help_parser/completion.rb

@@ -0,0 +1,135 @@
+module HelpParser
+  class Completion
+    def initialize(hash, specs, cache = NoDupHash.new)
+      @hash,@specs,@cache = hash,specs,cache
+      usage if @specs.has_key?(USAGE)
+      pad
+      types
+    end
+
+    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
+        rescue NoMatch
+          next
+        ensure
+          @cache.clear
+        end
+      end
+      raise UsageError, "Please match usage."
+    end
+
+    def types
+      if t2r = HelpParser.t2r(@specs)
+        k2t = HelpParser.k2t(@specs)
+        HelpParser.validate_k2t2r(@specs, k2t, t2r)
+        @hash.each do |key,value|
+          next unless key.is_a?(String)
+          if type = k2t[key]
+            regex = t2r[type]
+            case value
+            when String
+              raise UsageError, "Not a #{type}: #{key}" unless value=~regex
+            when Array
+              value.each do |string|
+                raise UsageError, "Not a #{type}: #{key}" unless string=~regex
+              end
+            else
+              raise UsageError, "Need a #{type}: #{key}"
+            end
+          end
+        end
+      end
+    end
+
+    def pad
+      # Synonyms and defaults:
+      @specs.each do |section,options|
+        next if section==USAGE || section==TYPES
+        options.each do |words|
+          next unless words.size>1
+          first,second,default = words[0],words[1],words[2]
+          if first[0]=='-'
+            if second[0]=='-'
+              i = second.index('=') || 0
+              short,long = first[1],second[2..(i-1)]
+              if @hash.has_key?(short)
+                if @hash.has_key?(long)
+                  raise UsageError, "Option #{short} is a synonym for #{long}."
+                end
+                @hash[long] = (default.nil?) ? true : default
+              elsif value = @hash[long]
+                @hash[short] = true
+                if value==true && !default.nil?
+                  @hash.delete(long)
+                  @hash[long]=default
+                end
+              end
+            else
+              i = first.index('=') || 0
+              long,default = first[2..(i-1)],second
+              value = @hash[long]
+              if value==true
+                @hash.delete(long)
+                @hash[long] = default
+              end
+            end
+          end
+        end
+      end
+    end
+
+    def matches(cmd, i = 0)
+      keys = @hash.keys
+      cmd.each do |token|
+        if token.is_a?(Array)
+          begin
+            i = matches(token, i)
+          rescue NoMatch
+            # OK, NEVERMIND!
+          end
+          next
+        elsif m=FLAG_GROUP.match(token)
+          group,plus = m["k"],m["p"]
+          key = keys[i]
+          raise NoMatch if key.nil? || key.is_a?(Integer)
+          list = @specs[group].flatten.select{|f|f[0]=='-'}.map{|f| HelpParser.f2k(f)}
+          raise NoMatch unless list.include?(key)
+          unless plus.nil?
+            loop do
+              key = keys[i+1]
+              break if key.nil? || key.is_a?(Integer) || !list.include?(key)
+              i+=1
+            end
+          end
+        elsif m=VARIABLE.match(token)
+          key = keys[i]
+          raise NoMatch unless key.is_a?(Integer)
+          variable,plus = m["k"],m["p"]
+          if plus.nil?
+            @cache[variable] = @hash[key]
+          else
+            strings = []
+            strings.push @hash[key]
+            loop do
+              key = keys[i+1]
+              break unless key.is_a?(Integer)
+              strings.push @hash[key]
+              i+=1
+            end
+            @cache[variable] = strings
+          end
+        else # literal
+          key = keys[i]
+          raise NoMatch if key.nil? || @hash[key]!=token
+        end
+        i += 1
+      end
+      return i
+    end
+  end
+end

data/lib/help_parser/constants.rb

@@ -1,75 +1,23 @@
-module HELP_PARSER # Constants
+module HelpParser
+  USAGE = "usage"
+  TYPES = "types"
 
-  ### OPTIONS LANGUAGE ###
+  # usage
+  FLAG       = /^[-][-]?(?<k>\w+)$/
+  LITERAL    = /^(?<k>\w[\w.-]*:?)$/
+  VARIABLE   = /^<(?<k>\w+)(=(?<t>[A-Z]+))?>(?<p>[+])?$/
+  FLAG_GROUP = /^:(?<k>\w+)(?<p>[+])?$/
 
-  H,LH = :h,:help
-  V,LV = :v,:version
+  # spec --?w+
+  SHORT = /^[-](?<s>\w)$/
+  LONG  = /^[-][-](?<k>\w+)(=(?<t>[A-Z]+))?(,?\s+(?<d>[^-\s]\S*))?$/
 
-  C,Z,M,E,P,Q,I = '#','-','-','=','[',']',''
-  MM = '--'
+  # spec -w,? --w+
+  SHORT_LONG         = /^[-](?<s>\w),?\s+[-][-](?<k>\w+)$/
+  SHORT_LONG_DEFAULT = /^[-](?<s>\w),?\s+[-][-](?<k>\w+)(=(?<t>[A-Z]+))?,?\s+(?<d>[^-\s]\S*)$/
 
-  ### HELP TEXT KEYS ###
-
-  NOTES,USAGE,TYPES,DEFAULTS = 'notes','usage','types','defaults'
-
-  ### ERROR COLOR CODES ###
-
-  COLOR = [
-    "\e[0m",    # no color
-    "\e[1;31m", # red
-  ]
-
-  ### TYPE MAPPINGS ###
-
-  FLOAT,INT = :Float, :Int
-  Types = {
-    INT   => /^[+-]?\d+$/,
-    FLOAT => /^[+-]?\d+\.\d+$/,
-  }
-
-  ### PATTERNS ###
-  
-  S          = /\s/             # space
-  SNS        = /\s*\n\s*/
-  KEY        = /^[-][-]?(.*)$/  #
-  SPS        = /\s+/            # spaces
-  MNS        = /^--?/
-  ERROR_KEY  = /:\s+(\S+)/
-  COMMENTARY = /\s*\t.*$/       # tab marks start of field comment
-
-  SELECTION   = /^(\w+):$/
-  SELECTION_P = /^:(.*?)([+]?)$/
-
-  VARIABLE    = /^<(.*)>$/
-  VARIABLE_P  = /^<(.*)>([+])?$/
-
-  ### Error Messages ###
-
-  MATCH_USAGE          = 'Please match usage!'
-  DUP_KEY              = 'Duplicate Key: '
-  ILLEGAL_KEY          = 'Illegal Key: '
-  SECTION_REDEFINITION = 'Section Redefinition: '
-  UNBALANCE_BRACKETS   = 'Unbalanced Brackets in Usage: '
-  MISSING_MINUS        = 'Missing Minus For Flag: '
-  NOT_A_FLAG           = 'No Minus For Types Or Defaults: '
-
-  ### Errors ###
-
-  class UsageError < RuntimeError
-  end
-  class HelpError < RuntimeError
-  end
-  class NoMatch < RuntimeError
-  end
-
-  ### REFINEMENTS ###
-
-  module Refinements
-    refine Array do
-      def detect_duplicate
-        self.detect{|_|self.rindex(_) != self.index(_)}
-      end
-    end
-  end
+  # spec W+ /~/
+  TYPE_DEF = /^(?<t>[A-Z]+),?\s+\/(?<r>\S+)\/$/
 
+  CSV = /,?\s+/
 end