healthy_options 0.0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1ed3f8e766787a98e9435461195c58252cdc4409
+  data.tar.gz: 3be9aff97d9a762fe3c1d5dea09e55c6748cc718
+SHA512:
+  metadata.gz: db01c61673ba876f03842e653d0ee89a3646de2fb9e77f01b91a3a83895caeb15b77995d1329bb41c0d25409c64acab9f98758799ac47f42c168cfd660e0e09a
+  data.tar.gz: 444c049bdb6a8d43e2d67a389e98b29a225510b27e8b458d1728d8c73b27b8ef745343e7595b7b324d51188e20984c080950c3e86b20ba119f625c7a2c853127

data/README.md

@@ -0,0 +1,109 @@
+# Notes
+
+*subject to revision; just capturing some notes for now; pay no heed*
+
+# arg styles
+
+* flags always start with dash
+* could be double-dash long-form e.g. --long-flag
+* could be single-dash short-form e.g. -l
+* could be single-dash long-form e.g. -lf
+
+# Values
+
+* space, e.g. --long-flag value
+* equals, e.g. --long-flag=value
+* smash, e.g. -lvalue
+
+# Smash flags
+
+* e.g. ps aux
+
+
+cases:
+
+`-lf -lr`
+
+1. is this flag=l value=f or flag=lf
+2. check flag=lf first, noting whether we have a value for it
+3. we don't have a value for flag=lf: no equals, and the next arg is a flag
+
+
+let's consider the following flags:
+
+--name,      -n, requires a value
+--enable,    -e, no value accepted
+--net-read, -nr, requires a value
+
+`-nr -e`
+
+This can't be --net-read because we don't have a value.  It must be name=r.
+
+--name,      -n, requires a value
+--enable,    -e, no value accepted
+--net-read, -nr, no value accepted
+
+`-nr -e`
+
+This could be --net-read or name=r, but we'll take --net-read because it was
+specific.
+
+Recommendation:
+
+1. don't support -nr (one dash for short options, two for long)
+2. don't support smashing for long options, ever
+3. support smashing for short options, both flags and any final value
+4. always handle an = immediately after a recognized flag (which takes a value) as a value assignment
+
+
+2 primary distinctions:
+
+* short option or long option
+* takes a value or not
+
+if it's a long option, it's easy:
+1. read 2 dashes
+2. read until [space] or [equals]
+3. match flag or fail
+4. does match take an arg?
+ yes.1 if we have [equals] [value], done.
+ yes.2 if the next arg is not a flag, done.
+ yes.3 otherwise fail
+ no.1 if we have equals, fail
+ no.2 if the next arg is a flag, done
+ no.3 if there are no more args, done
+ no.4 if there are no more flags, done (leave non-flag args alone)
+ no.5 otherwise we have an arg, fail
+
+
+if it's a short option, we have to consider smashing
+1. read a single dash followed by alphanum
+2. confirm the flag and whether it takes a value
+3. if the next character is a space, look for value match
+ 2.a if no value wanted, done
+ 2.b if value wanted, fail if no args or next arg is a flag. otherwise done
+3. if the next character is equals, look for a value match
+ 3.a if no value wanted, fail
+ 3.b if value wanted, take the right side of the equals, done
+4. if the next character is an alphanum, then we have either a smashed flag or a smashed value, depending on #2.
+ 3.a if no value wanted, then parse next char as a short flag
+ 3.b if value wanted, read the rest of the word as a value, done
+
+
+1. given a string of alphanum, punctuation, and whitespace
+2. split on whitespace into args consisting of alphanum and punctuation
+3. an arg is either an option-flag, an option-value,
+   a combination of these 2, or a non-option
+4. the combinations consist of short-option smashing or flag=value
+5. options come before non-options
+6. args flatten to FLAG VALUE NONOPT [[DOUBLEDASH] ANY]
+7. FLAG can be followed by FLAG or !FLAG
+8. VALUE must be preceded by FLAG (otherwise it's a NONOPT)
+9. every arg after a NONOPT must be a NONOPT
+10. any NONOPT that looks like a flag is forbidden
+11. unless it's the special DOUBLEDASH
+
+
+So, split on whitespace.  That's handled for us with ARGV.
+
+Next, look for dashes in the first arg.

data/VERSION

@@ -0,0 +1 @@
+0.0.0.3

data/lib/healthy_options.rb

@@ -0,0 +1,218 @@
+class HealthyOptions
+  RGX = {
+    long: %r{
+    \A       # starts with
+    --       # double dash
+    (?'flag' # named group
+      (?:    # non-capturing group
+        \w+  # word chars
+        -?   # possible dash
+      )*     # some number of word-word- (possibly none)
+      \w+    # one last word (possibly first as well)
+    )        # end flag group
+    }x,      # end :long regex
+
+    short: %r{
+    \A       # starts with
+    -        # single dash
+    (?'flag' # named group
+      \w     # word char
+    )        # end flag group
+    }x,      # end :short regex
+  }
+
+  SPECIALS = {
+    separator: '--',
+  }
+
+  def self.index(flags)
+    idx = { long: {}, short: {}, }
+    flags.each { |flag, cfg|
+      [:long, :short].each { |fld|
+        idx[fld][cfg[fld]] = flag if cfg[fld]
+      }
+    }
+    idx
+  end
+
+  # consider dropping this and inlining calls to it
+  def self.flag?(arg)
+    arg[0] == '-'
+  end
+
+  def initialize(flags = {})
+    self.flags = flags
+  end
+
+  def flags=(hsh)
+    @flags = {}
+    hsh.each { |flag, cfg|
+      raise("symbol expected for #{flag}") unless flag.is_a?(Symbol)
+      my_cfg = {}
+      cfg.each { |sym, val|
+        raise("symbol expected for #{sym}") unless sym.is_a?(Symbol)
+        my_cfg[sym] = val
+      }
+      @flags[flag] = my_cfg
+    }
+    self.reindex
+    @flags
+  end
+
+  def reindex
+    @index = self.class.index(@flags)
+  end
+
+  def check_flag(arg)
+    # note, #parse has already confirmed self.class.flag?(arg)
+    SPECIALS.each { |sym, val| return [sym, val] if arg == val }
+    flag = nil
+    flag_type = nil
+
+    # check the purported flag against the regex
+    RGX.each { |ft, rgx|
+      if (m = rgx.match(arg))
+        flag = m['flag']
+        flag_type = ft
+        break
+      end
+    }
+    raise "strange flag: #{arg}" unless flag_type # arg doesn't match regex
+
+    # look up the flag in the index
+    sym = @index.dig(flag_type, flag)
+    return [:unknown_flag, flag] unless sym
+    spec = @flags.fetch(sym)
+
+    #
+    # perform validation based on long/short and value/no-value
+    # everything below here returns or raises
+    #
+
+    val = arg.dup
+    first_two = val.slice!(0, 2)
+
+    # consume and validate the flag portion of arg (now val)
+    if flag_type == :short
+      raise "expected #{arg} to lead with -#{flag}" if first_two != "-#{flag}"
+    elsif flag_type == :long
+      raise("expected #{arg} arg to lead with --") if first_two != "--"
+      flagcheck = val.slice!(0, flag.length)
+      if flagcheck != flag
+        raise("expected #{arg} (#{flagcheck}) to match #{flag}")
+      end
+    end
+
+    if spec[:value]
+      # happy, common case -- the needed value is in the next arg to follow
+      return [:flag_need_val, flag] if val.empty?
+
+      # check for equals -- consume it and take the rest as value
+      if val[0] == '='
+        val.slice!(0, 1)
+        if val.empty?
+          raise("a value is required after = (#{arg})")
+        else
+          return [:flag_has_val, flag, val]
+        end
+      end
+
+      if flag_type == :short
+        # allow smashed value; the rest of the arg must be the value
+        return [:flag_has_val, flag, val]
+      else
+        raise("could not determine value for #{flag} in #{arg}")
+      end
+    else
+      # no value required
+      return [:flag_no_val, flag] if val.empty?
+
+      if flag_type == :short
+        # next char must not be equals
+        if val[0] == '='
+          raise("#{flag} does not take a value: #{arg}")
+        else
+          return [:flag_no_val_more, flag, val]
+        end
+      else
+        raise("#{flag} does not take a value: #{arg}")
+      end
+    end
+  end
+
+  def self.pop_value(args)
+    val = args.first
+    raise "args is empty" unless val
+    raise "#{val} is not a value" if self.flag?(val)
+    args.shift
+  end
+
+  # this is a recursive method
+  # opts tends to grow while args shrinks
+  def parse(args, opts = {})
+    return [args, opts] if args.empty?
+    return [args, opts] unless self.class.flag?(args.first)
+
+    res, flag, value = self.check_flag(args.first)
+    # puts "\n\nDEBUG: #{res} #{flag} #{value}"
+
+    return [args, opts] if res == :separator
+    raise("flag expected for #{res}") unless flag # sanity check
+
+    # TODO: we should know by now whether it's a long or short flag
+    sym = @index[:long][flag] || @index[:short][flag]
+    raise "unrecognized flag: #{flag}" unless sym
+    args.shift
+
+    case res
+    when :flag_has_val
+      raise("value expected") unless value
+      opts[sym] = value
+    when :flag_need_val
+      opts[sym] = self.class.pop_value(args)
+    when :flag_no_val
+      opts[sym] = true
+    when :flag_no_val_more
+      opts[sym] = true
+      raise("more exected for #{flag} parsed as #{res}") unless value
+      # look for smashed flags
+      self.parse_smashed(value).each { |smflag, smval|
+        # the last smashed flag may need a val from args
+        opts[smflag] = smval || self.class.pop_value(args)
+      }
+    else
+      raise "unknown result: #{res}"
+    end
+    self.parse(args, opts)
+  end
+
+
+
+  # original args: -af=5
+  #                -af 5
+  def parse_smashed(arg)
+    opts = {}
+    # preceding dash and flag have been removed
+    val = arg.dup
+    loop {
+      break if val.empty?
+      char = val.slice!(0, 1)
+      sym = @index[:short][char]
+      raise "unknown flag smashed in: #{char} in #{arg}" unless sym
+      spec = @flags.fetch(sym)
+      # TODO: error handling (punctuation, -p5 -5p, etc)
+      if spec[:value]
+        val.slice!(0, 1) if val[0] == '='
+        if val.empty?
+          opts[sym] = nil # indicate to parse we need another arg; ugh, hack!
+        else
+          opts[sym] = val
+        end
+        break # a value always ends smashing
+      else
+        opts[sym] = true
+      end
+    }
+    opts
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: healthy_options
+version: !ruby/object:Gem::Version
+  version: 0.0.0.3
+platform: ruby
+authors:
+- Rick Hull
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-01-29 00:00:00.000000000 Z
+dependencies: []
+description: |
+  * long and short options
+  * value or not
+  * use equals for value or not
+  * short option smashing
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- VERSION
+- lib/healthy_options.rb
+homepage: https://github.com/rickhull/healthy_options
+licenses:
+- GPL-3.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Parse a wide but limited variety of command line option styles
+test_files: []