optbind 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b4356b32d38251a6d9944f9b76cb4f67082c871c
-  data.tar.gz: d6f981ffc6296a2c4ea58ce98f02e62f59a985eb
+  metadata.gz: a75ae614f40e93666809a3bcefac9e58ed61e699
+  data.tar.gz: d3a138e3f55237c587aa1d1901f529c3415afa7a
 SHA512:
-  metadata.gz: 5c01afa32bb8a831976300d085c554139f2a93acc171c4df0dd71a94604e16c33a404b1db093c016bc0d31a304522b1d74b5dadd92497c1f62001e8dee84c85f
-  data.tar.gz: fecba5909fb7c7cbfd64573f0b90648dc4e59d06e176934e4454e319b307e050ee751248f4f13aa44798b9a0fcf534585b431e16b6915fc00be107f871418eeb
+  metadata.gz: c487f3899ff91d0a18a25647ffe10ae32dcf2cc0bf3b88aa524bb993bea749b271623b3be965970e56169bf5bd87afcc384bbf67c7f3b2b31be59bf64d45eff0
+  data.tar.gz: 2f52caa014b1fb9b66a228e1c557ba3daef0b3d220a392671880a46207fbcc71675e8184d34e2a25a7f88384e0faf88e5109baf6d4f0f584c2e7655ea026f31f

data/README.md

@@ -5,7 +5,7 @@
 
 Binds command-line options to variables.
 
-Extends command-line option analysis by wrapping an instance of standard [`OptionParser`](http://ruby-doc.org/stdlib-2.2.3/libdoc/optparse/rdoc/OptionParser.html).
+Extends command-line option analysis by wrapping an instance of standard [`OptionParser`](http://ruby-doc.org/stdlib-2.3.1/libdoc/optparse/rdoc/OptionParser.html).
 Enables binding of options and arguments to instance or local variables. Provides `Hash` and `String` only interfaces
 to define command line options, unlike a mixed interface by standard library. Supports access to default values and
 partial argument analysis. Builds Git-like options and help by default. 
@@ -21,7 +21,7 @@ Bind local variables to `ARGV` and parse command line arguments:
 ```ruby
 require 'optbind'
 
-ARGV                                         #=> ['--no-verbose', '-o', 'file.out', 'file.in'] 
+ARGV                                         #=> ['--no-verbose', '-o', 'file.out', 'file.in']
 
 i, o, v = STDIN, STDOUT, true
 
@@ -33,11 +33,191 @@ ARGV.bind_and_parse! to: :locals do
   arg 'i [<file>]'
 end
 
+ARGV                                         #=> []
+
 [i, o, v]                                    #=> ['file.in', 'file.out', false]
 ```
 
+Use `bind` or one of its aliases on `ARGV` instead of `bind_and_parse!` to be able to `parse!` command line arguments later:
+
+```ruby
+ARGV.bind to: :locals do
+  # ...
+end
+
+ARGV.parse!
+```
+
+Create an `OptionBinder` and use it directly:
+
+```ruby
+binder = OptionBinder.new do
+  # ...
+end
+
+binder.parse! ARGV
+```
+
+Note that plain `OptionBinder.new` binds to local variables of top level binding object by default. 
+
 See specs for more examples and details on usage.
 
+### Bindings
+
+Various binding possibilities include:   
+
+#### Bind to `Hash` object
+
+Create target:
+
+```ruby
+options = { input: STDIN, output: STDOUT }
+```
+
+Use `OptionBinder` directly:
+
+```ruby
+OptionBinder.new(target: options) do
+  # ...
+end
+```
+
+Use `ARGV` shortcut:
+
+```ruby
+ARGV.define_and_bind(to: options) do
+  # ... 
+end  
+```
+
+#### Bind to public accessors
+
+Create target:
+
+```ruby
+class Options
+  attr_accessor :input, :output
+  
+  def initialize
+    @input, @output = STDIN, STDOUT
+  end
+end
+```
+
+Use `OptionBinder` directly:
+
+```ruby
+OptionBinder.new(target: options) do
+  # ...
+end
+```
+
+Use `ARGV` shortcut:
+
+```ruby
+ARGV.define_and_bind(to: options) do
+  # ... 
+end  
+```
+
+#### Bind to class variables
+
+Create target:
+
+```ruby
+class Options
+  @@input, @@output = STDIN, STDOUT
+end
+
+options = Options.new
+```
+
+Use `OptionBinder` directly:
+
+```ruby
+OptionBinder.new(target: options, bind: :to_class_variables) do
+  # ...
+end
+```
+
+Use `ARGV` shortcut:
+
+```ruby
+ARGV.define_and_bind(to: options, via: :class_variables) do
+  # ... 
+end  
+```
+
+#### Bind to instance variables
+
+Create target:
+
+```ruby
+class Options
+  def initialize
+    @input, @output = STDIN, STDOUT
+  end
+end
+
+options = Options.new
+```
+
+Use `OptionBinder` directly:
+
+```ruby
+OptionBinder.new(target: options, bind: :to_instance_variables) do
+  # ...
+end
+```
+
+Use `ARGV` shortcut:
+
+```ruby
+ARGV.define_and_bind(to: options, via: :instance_variables) do
+  # ... 
+end  
+```
+
+#### Bind to local variables
+
+Create target:
+
+```ruby
+input, output = STDIN, STDOUT
+```
+
+Use `OptionBinder` directly:
+
+```ruby
+OptionBinder.new(target: TOPLEVEL_BINDING, bind: :to_local_variables) do
+  # ...
+end
+```
+
+Use `OptionBinder` directly with top level binding object as target by default:
+
+```ruby
+OptionBinder.new do
+  # ...
+end
+```
+
+Use `ARGV` shortcut:
+
+```ruby
+ARGV.define_and_bind(to: TOPLEVEL_BINDING, via: :local_variables) do
+  # ... 
+end  
+```
+
+Use `ARGV` shortcut with top level binding object as target by default:
+
+```ruby
+ARGV.define_and_bind(to: :locals) do
+  # ... 
+end  
+```
+
 ## Testing
 
     bundle exec rspec

data/TODO.md

@@ -1,10 +1,16 @@
 # TODOS
 
+  - move order and permute to separate package, required on demand
+  
   - `Switch#parser_opts_from_string` - support regexps with options, like `=<name:/[a-z]/i>`
   - `Switch#parser_opts_from_string` - support ranges, like `=<indent:0..8>`
-  - add default support for ranges on `OptionParser` level
-  - add support for `Module#class_variables`
-  - add type conversion and patterns for arguments
+  
+  - add custom type definitions to separate package, required on demand 
+  - add support for ranges on `OptionParser` level
+
+  - add optbind/handlers from extise as separate package, required on demand
+  - add optbind/defaults from extise as separate package, required on demand
+
   - make optional extensions for `OptionParser` monkey-patching `make_switch` to support hash-or-string-exclusive arguments 
 
 # IDEAS
@@ -17,10 +23,7 @@ gems:
   opt ???           enhances syntax            see syntax def below
   optargs           supoort for args            
 
-- store defaults and make them always accessible
-- support arguments? consider ARGF
-
-- bind API:
+bind API:
   must be uninvasive, i.e. must not affect #on in any way, must act as #parse, see example
   ARGV, OptionParser (options)
   example: ARGV.options { |o| o.on(...); o.bind ...; o.parse! }

data/lib/optbind/version.rb

@@ -1,3 +1,3 @@
 module OptBind
-  VERSION = '0.3.2'
+  VERSION = '0.4.0'
 end

data/lib/optbind.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 require 'optparse'
 
@@ -18,6 +20,8 @@ class OptionBinder
       return -> (v) { target.local_variable_get v }, -> (v, x) { target.local_variable_set v, x }
     when :to_instance_variables
       return -> (v) { target.instance_variable_get "@#{v}" }, -> (v, x) { target.instance_variable_set "@#{v}", x }
+    when :to_class_variables
+      return -> (v) { target.class_variable_get "@@#{v}" }, -> (v, x) { target.class_variable_set "@@#{v}", x }
     else
       return -> (v) { target[v] }, -> (v, x) { target[v] = x } if target.respond_to? :[]
       return -> (v) { target.public_send v }, -> (v, x) { target.public_send "#{v}=", x }
@@ -25,11 +29,14 @@ class OptionBinder
   end
 
   def resolve_parser(parser = nil)
-    parser || OptionParser.new do |p|
+    parser ||= OptionParser.new do |p|
       p.define_singleton_method(:banner) { (b = super()) !~ /\AU/ ? b : "usage: #{program_name} [<options>]\n\n" }
-      p.define_singleton_method(:version) { super() || (defined?(::VERSION) && ::VERSION) }
       p.define_singleton_method(:help) { super().gsub(/(-\S+)=\[/, '\1[=') << "    -h, --help\n        --version\n\n" }
     end
+    parser.tap do |p|
+      p.program_name = ::PROGRAM if defined? ::PROGRAM
+      p.version = ::VERSION if defined? ::VERSION
+    end
   end
 
   private :resolve_binding, :resolve_parser
@@ -40,8 +47,12 @@ class OptionBinder
   def_delegators :@parser, :abort, :warn
   def_delegators :@parser, :load
 
-  { order: '*argv, &blk', order!: 'argv', permute: '*argv', permute!: 'argv', parse: '*argv', parse!: 'argv' }.each do |m, a|
-    class_eval "def #{m} #{a}; @parser.#{m} #{a}; parse_args#{'!' if m =~ /!\z/} argv; rescue OptionParser::ParseError; @parser.abort; end", __FILE__, __LINE__
+  def parse(argv)
+    parse!(argv.dup) and argv
+  end
+
+  def parse!(argv)
+    parse_args! @parser.parse! argv
   end
 
   def_delegators :@parser, :to_a, :to_s
@@ -54,10 +65,10 @@ class OptionBinder
     line = (args * ' ') << "\n"
 
     if @parser.banner =~ /\Ausage:.+\n\n/i
-      @parser.banner = "usage: #{program} " << line
+      @parser.banner = "usage: #{program} #{line}"
       @parser.separator "\n"
     else
-      @parser.banner << "   or: #{program} " << line
+      @parser.banner += "   or: #{program} #{line}"
     end
 
     self
@@ -69,14 +80,11 @@ class OptionBinder
     opts, handler, bound, variable, default = *several_variants(*opts, &handler)
 
     @parser.on(*opts) do |r|
-      if opts.include? :REQUIRED
-        a = opts.select { |o| o =~ /\A-/ }.sort_by { |o| o.length }[-1]
-        @parser.abort "missing argument: #{a}=" if !r || (r.respond_to?(:empty?) && r.empty?)
-      end
-
+      raise OptionParser::InvalidArgument if opts.include?(:REQUIRED) && (r.nil? || r.respond_to?(:empty?) && r.empty?)
       handle! handler, r, bound, variable, default
     end
 
+    (@option_definitions ||= []) << { opts: opts, handler: handler, bound: bound, variable: variable }
     (@bound_variables_with_defaults ||= {})[variable] = default if bound
     self
   end
@@ -86,8 +94,9 @@ class OptionBinder
   def argument(*opts, &handler)
     opts, handler, bound, variable, default = *several_variants(*opts, &handler)
 
-    opts.each do |opt|
-      (opts << :MULTIPLE) and break if opt.to_s =~ /<\S+>\.{3}/
+    (@argument_parser ||= OptionParser.new).on(*(opts << "--#{(@argument_definitions || []).size}")) do |r|
+      raise OptionParser::InvalidArgument if opts.include?(:REQUIRED) && (r.nil? || r.respond_to?(:empty?) && r.empty?)
+      handle! handler, r, bound, variable, default
     end
 
     (@argument_definitions ||= []) << { opts: opts, handler: handler, bound: bound, variable: variable }
@@ -118,12 +127,12 @@ class OptionBinder
   end
 
   def bound?(v)
-    (@bound_variables_with_defaults || {}).has_key? v.to_sym
+    (@bound_variables_with_defaults || {}).key? v.to_sym
   end
 
   def assigned?(v)
     return nil unless bound? v
-    (@assigned_variables_with_values || {}).has_key? v.to_sym
+    (@assigned_variables_with_values || {}).key? v.to_sym
   end
 
   module Switch
@@ -151,9 +160,9 @@ class OptionBinder
     end
 
     def self.parser_opts_from_string(string = '', &handler)
-      shorts, longs = [], []
+      string, shorts, longs = string.dup, [], []
 
-      while string.sub!(/\A(?:(?<short>-\w)\s+)/, '')
+      while string.sub!(/\A(?:(?<short>-\w)\s+)/, '') do
         shorts << $~[:short]
       end
 
@@ -164,6 +173,7 @@ class OptionBinder
         next unless $~[:argument]
         argument = $~[:argument]
         style = argument =~ /\A=?[<(]/ ? :REQUIRED : :OPTIONAL
+        pattern = Array if argument =~ /\.{3}\]?\z/
         values = $~[:values].split('|') if argument =~ /(?:\[?=?|=\[)\((?<values>\S*)\)\]?/
 
         if values.nil? && argument =~ /(?:\[?=?|=\[)<(?<name>\S+):(?<pattern>\S+)>\]?/
@@ -203,25 +213,36 @@ class OptionBinder
 
   private :several_variants
 
-  def parse_args(argv)
-    parse_args! argv.dup
+  class MissingArguments < OptionParser::ParseError
+    const_set :Reason, 'missing arguments'
+    alias_method :message, :reason
+    alias_method :to_s, :reason
+  end
+
+  class TooManyArguments < OptionParser::ParseError
+    const_set :Reason, 'too many arguments'
+    alias_method :message, :reason
+    alias_method :to_s, :reason
   end
 
   def parse_args!(argv)
-    return argv unless @argument_definitions
-    @argument_definitions.each do |a|
-      default = (@bound_variables_with_defaults ||= {})[a[:variable]]
-      r = argv[0] ? argv.shift : default
-      r = ([r].flatten + argv.shift(argv.size)).compact if a[:opts].include? :MULTIPLE
-      @parser.abort 'missing arguments' if (r.nil? || (r.is_a?(Array) && r.empty?)) && a[:opts].include?(:REQUIRED)
-      handle! a[:handler], r, a[:bound], a[:variable], default
-      return argv if a[:opts].include? :MULTIPLE
+    return argv unless @argument_parser
+    k = @argument_definitions.find_index { |a| a[:opts].include? Array }
+    p = k ? argv[0...k].map { |r| [r] } << argv[k..-1] : argv.map { |r| [r] }
+    p = (p.empty? ? p << [] : p).each_with_index.map do |r, i|
+      a = @argument_definitions[i]
+      raise TooManyArguments unless a
+      raise MissingArguments if a[:opts].include?(:REQUIRED) && r.empty?
+      "--#{i}=#{r * ','}" if a[:opts].include?(:REQUIRED) || !(r.empty? || r.find(&:empty?))
     end
-    @parser.abort 'too many arguments' if argv[0]
+    @argument_parser.order! p
+    argv.shift argv.size - p.size
     argv
+  rescue OptionParser::InvalidArgument
+    raise $!.tap { |e| e.args[0] = e.args[0].sub(/\A--\d+=/, '') }
   end
 
-  private :parse_args, :parse_args!
+  private :parse_args!
 
   def handle!(handler, raw, bound, variable, default)
     (handler || -> (r) { r }).call(raw == nil ? default : raw).tap do |x|
@@ -264,9 +285,14 @@ class OptionBinder
     alias_method :define_and_bind, :binder
     alias_method :bind, :binder
 
+    def define_and_parse(opts = {}, &blk)
+      define(opts, &blk) and parse
+    end
+
+    alias_method :bind_and_parse, :define_and_parse
+
     def define_and_parse!(opts = {}, &blk)
-      define opts, &blk
-      parse!
+      define(opts, &blk) and parse!
     end
 
     alias_method :bind_and_parse!, :define_and_parse!
@@ -275,12 +301,8 @@ class OptionBinder
       self.options
     end
 
-    def order!(&blk)
-      binder.order! self, &blk
-    end
-
-    def permute!
-      binder.permute! self
+    def parse
+      binder.parse self
     end
 
     def parse!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: optbind
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Pavol Zbell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-08 00:00:00.000000000 Z
+date: 2016-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -72,7 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Binds command-line options to variables.