switches.rb 0.10.4 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea74840ee7d4c44d9a22e7e6c4464eb0417fd4ac0d65e0683465600188e2d903
-  data.tar.gz: 7f68a8a35001b0ff0445d605f276b3205c0651e3ab5a582e970fe5d4a771ea0a
+  metadata.gz: fc49f311d672f64884c36a8b1645d17be83d83df5e630a272a4740db00a48448
+  data.tar.gz: 9a5b8accb318737020f7d1c03dfee96ae21529dafe357aabc62abcbd5314dc5a
 SHA512:
-  metadata.gz: 284df213837788db6c63752a357d763e16a84ea37331eb405365a6754335e8372a70a7dc880caddd3f6220d4530ccf901a4bfff12e3e9482ebbc7b22433e0bf2
-  data.tar.gz: 2b067b99909da06acaa0e366dae1ac41307f5347cd44383a3a036bac06e21eac521b6d670ac2ff07b6eac6f3332f9b07ddcee590c51e1466f039823569465f94
+  metadata.gz: 0171a8d12cacc99884b6606f08fb5fbf2ac048e5f9d8ed147e3bfe224a2724d2ecb6fc6d077edc9e533a2a7d4dfd2a0fb9c8563f63824ed0cd78506f6c708795
+  data.tar.gz: 7888b090acfe50edc7ded58b12b005232be881e0c9489edb07dec7fd126ec7afb8ef1a1cb926682e0eec96bd19efc4a5f26e9a555341f637e3caa60a905f04b8

data/CHANGELOG

@@ -2,6 +2,26 @@
 
 ## 20260816
 
+0.11.0: Forward to OptionParser, which #method_missing has never actually done.
+
+1. ~ lib/Switches.rb: #method_missing tested (@op.methods - Switches.instance_methods).include?(method_name.to_s), which compares a String against an array of Symbols and so was never true. Every call fell through to the settings OpenStruct, which accepts anything, so s.banner = '...' — documented in the README's "With a banner" example — silently became a setting named banner while the parser kept its default of "Usage: <program_name> [options]". The comparison is now made in symbols, and the forwarding works: #banner=, #separator, #program_name= and the other 58 OptionParser methods reach the parser.
+2. ~ lib/Switches.rb: a declared switch takes precedence over an OptionParser method of the same name, + Switches#declared_switch?. Making the forwarding work otherwise shadows any switch sharing a name with the parser, and OptionParser has version, help, release, load, order, top, base, parse, warn, abort and banner among its 61, several of which are switches a program would reasonably want. The rule is that the program's own declarations beat the wrapper's interface, which also leaves any existing program's switches reading as they did.
+3. ~ lib/Switches.rb: + Switches::NEVER_FORWARDED, the names Ruby may call implicitly, which are excluded from the forwarded set. The set has always been built by subtraction — everything the parser responds to, less everything Switches defines — which admits any such name Switches does not happen to define. OptionParser#to_a is `summarize("#{banner}".split(/^/))`, so without the exclusion Array(switches) and [*switches] answer with the parser's help. That was latent for as long as the branch was dead and became reachable the moment it was not, so it is part of this fix rather than a consequence of it. to_h was never at risk, but only because Switches happens to define it; the constant makes the exclusion deliberate rather than incidental.
+4. ~ lib/Switches.rb: + Switches#option_parser_methods, memoised, since the difference was recomputed upon every settings read, and + Switches#option_parser_method?.
+5. + spec/all.rb: forwarding of a writer, of a method taking an argument, and of a reader, each checked through the parser's own help output rather than by reading back what was written; that a declared switch wins over the OptionParser method of the same name, read and written; that a name which is neither still reaches the settings; and that #to_a, Array() and the splat are answered by the switches rather than the parser.
+6. ~ README.md: the Notes entry claiming a Switches instance can't define a method whose name matches an OptionParser method now describes what happens, which is the reverse: the switch wins.
+
+Not done: #respond_to_missing?, which ordinarily accompanies #method_missing. Note that it would not have prevented the to_a case above — Ruby's conversion check falls back to calling #method_missing directly when the ordinary dispatch fails, so Array() reaches #to_a whatever respond_to? answers. It wants deciding alongside the collision question below, both being about which names the object should own.
+
+Still outstanding: the converse fault, where #method_missing does not fire at all because the method exists. A switch named after a method Object already has — :tap, :class, :display, :hash, :method, :type — never reaches the settings, and Kernel#tap without a block raises LocalJumpError nowhere near the declaration.
+
+0.10.5: Specify and document that a multi-word switch may be supplied hyphenated, and name that form when it is missing.
+
+1. + spec/all.rb: multi-word switches, in both their underscored and their hyphenated form, for a boolean, an optional argument (#set), a required argument (#set!) and a required switch (#required); that either form counts as supplied for a required switch; and that the setting is named for the symbol declared whichever form was supplied. This behaviour is OptionParser's rather than this library's — a long switch is filed under a lookup key with its underscores turned to hyphens, and whatever is supplied is converted the same way before the lookup, so --update_template and --update-template have always been the one switch. It went untested and undocumented here, which left it resting upon an implementation detail of a library this one only wraps. The specs now pin it, and would fail here rather than in a caller's script were it ever to change.
+2. ~ lib/Switches.rb: the missing-switch message names the hyphenated form, so a switch declared :access_token is reported as --access-token, in place of the --access_token built from the symbol verbatim. Cosmetic, and it says the form to prefer at a command line.
+3. ~ lib/Switches.rb: + Switches#switch_string, which builds the switch string for an attribute, in place of the identical construction #on_args and #check_required_switches each carried.
+4. ~ README.md: + a multi-word switch to the Usage section, and + a note recording where the behaviour comes from, that the setting is named for the symbol declared, and that declaring the attribute hyphenated buys nothing and costs the accessor.
+
 0.10.4: Declare ostruct as a runtime dependency, in place of installing it at require time.
 
 1. ~ lib/Switches.rb: require 'ostruct', in place of the require_gem 'ostruct' introduced in 0.10.0. require_gem rescues the LoadError and shells out to gem install, so the dependency went unannounced and was satisfied silently into whatever GEM_HOME was set — which, under a Homebrew formula's wrapper, means the program installing a gem into its own keg. A library should announce what it needs and fail loudly without it.

data/README.md

@@ -135,6 +135,12 @@ switches = Switches.new do |s|
   s.set(:a){'This is the -a switch.'}
 end
 
+# With a multi-word switch, which may be supplied in either its underscored or its hyphenated form
+switches = Switches.new do |s|
+  s.boolean(:update_template)
+end
+# --update_template and --update-template both set it, and the setting remains #update_template?
+
 # With a banner
 switches = Switches.new do |s|
   s.banner = 'Here is a banner for the switches.'
@@ -186,9 +192,10 @@ switches.class # => Hash
 ## Notes
 
 - The switch `-?` can't be used, since there is no Ruby method `#?` for it to map to.
-- A `Switches` instance can't define a method whose name matches an `OptionParser` method, since such calls are forwarded to the underlying `OptionParser` instance.
+- A call which is neither a switch nor a `Switches` method is forwarded to the underlying `OptionParser`, which is what makes `s.banner = '...'` and `s.separator '...'` work. A declared switch wins over an `OptionParser` method of the same name, so `s.set(:version)` still reads back through `#version`; without that rule a switch called `--version`, `--help`, `--load` or `--order` would be shadowed by the parser, all four being names `OptionParser` has. The names Ruby may call implicitly — `#to_a`, `#to_s` and the rest of `Switches::NEVER_FORWARDED` — are never forwarded, since `OptionParser#to_a` answers with the help and would otherwise be what `Array(switches)` and `[*switches]` gave you.
 - There is a clear demarcation between whether a switch's argument is required and whether the switch itself is required.
 - The bang interface methods (for example `set!` and `required!`) modify the switch in place with a required argument, rather than relying on a default or a value set elsewhere and later.
+- A long switch whose name carries an underscore may be supplied in its hyphenated form as well, so `s.boolean(:update_template)` accepts both `--update_template` and `--update-template`. This comes from `OptionParser`, which files a long switch under a lookup key with its underscores turned to hyphens and applies the same conversion to whatever is supplied, so the two forms are one switch rather than two. The setting is named for the symbol declared, and so remains `#update_template?` whichever form was supplied. Declaring the attribute hyphenated, as `:'update-template'`, buys nothing and costs the accessor, which would then be reachable only through `#send`.
 
 ## Contributing
 

data/lib/Switches/VERSION.rb

@@ -2,5 +2,5 @@
 # Switches::VERSION
 
 class Switches
-  VERSION = '0.10.4'
+  VERSION = '0.11.0'
 end

data/lib/Switches.rb

@@ -153,6 +153,9 @@ class RequiredSwitchMissing < RuntimeError; end
 
 class Switches
   
+  # Names Ruby may call implicitly, and which must reach the settings rather than OptionParser.  #to_a would otherwise answer Array() and the splat with the parser's help.
+  NEVER_FORWARDED = [:to_a, :to_ary, :to_h, :to_hash, :to_s, :to_str, :pretty_print]
+  
   class << self
     
     def as_h(*args)
@@ -277,19 +280,36 @@ class Switches
   end
   
   def method_missing(method_name, *args, &block)
-    if (@op.methods - Switches.instance_methods).include?(method_name.to_s)
-      @op.send(method_name.to_s, *args, &block)
+    if option_parser_method?(method_name) && !declared_switch?(method_name)
+      @op.send(method_name, *args, &block)
     else
-      @settings.send(method_name.to_s, *args, &block)
+      @settings.send(method_name, *args, &block)
     end
   end
   
+  def option_parser_methods
+    @option_parser_methods ||= @op.methods - Switches.instance_methods - NEVER_FORWARDED
+  end
+  
+  def option_parser_method?(method_name)
+    option_parser_methods.include?(method_name.to_sym)
+  end
+  
+  def declared_switch?(method_name)
+    @all_switches.include?(method_name.to_s.delete_suffix('='))
+  end
+  
+  def switch_string(attr)
+    attr = attr.to_s
+    "-#{attr.long_switch? ? '-' : ''}#{attr.delete('?')}"
+  end
+  
   def on_args(requires_argument, options, *attrs, &block)
     on_args = []
     attrs.collect{|e| e.to_s}.each do |attr|
       @defaults[attr] = options[:default] if options[:default]
       @castings[attr] = (options[:cast] || options[:type] || options[:class]) if (options[:cast] || options[:type] || options[:class])
-      on_args << "-#{attr.long_switch? ? '-' : ''}#{attr.to_s.delete('?')}"
+      on_args << switch_string(attr)
     end
     if requires_argument
       on_args << (on_args.pop + ' REQUIRED_ARGUMENT')
@@ -310,7 +330,7 @@ class Switches
     messages = []
     @required_switches.each do |required_switch|
       unless supplied_switches.include?(required_switch)
-        messages << "required switch, -#{required_switch.long_switch? ? '-' : ''}#{required_switch.to_s.delete('?')}, is missing"
+        messages << "required switch, #{switch_string(required_switch).tr('_', '-')}, is missing"
       end
     end
     unless messages.empty?

data/spec/all.rb

@@ -164,6 +164,140 @@ describe Switches do
     end
   end
 
+  describe "OptionParser methods" do
+    def build(&block)
+      ARGV.clear
+      Switches.new(&block)
+    end
+
+    it "forwards a writer to the OptionParser" do
+      expect(build{|s| s.banner = 'Usage: tap-audit [options]'}.help).to match(/\AUsage: tap-audit \[options\]/)
+    end
+
+    it "forwards a method taking an argument to the OptionParser" do
+      expect(build{|s| s.separator 'Options:'}.help).to match(/^Options:$/)
+    end
+
+    it "forwards a reader to the OptionParser" do
+      switches = build{|s| s.program_name = 'tap-audit'}
+      expect(switches.program_name).to eq('tap-audit')
+      expect(switches.help).to match(/\AUsage: tap-audit/)
+    end
+
+    it "prefers a declared switch to the OptionParser method of the same name" do
+      ARGV.clear
+      %w{--version 2.1}.each{|a| ARGV << a}
+      expect(Switches.new{|s| s.set(:version)}.version).to eq('2.1')
+    end
+
+    it "prefers a declared switch when it is written to as well" do
+      switches = build{|s| s.set(:banner)}
+      switches.banner = 'a setting, not the banner'
+      expect(switches.to_h[:banner]).to eq('a setting, not the banner')
+    end
+
+    it "falls through to the settings for a name which is neither" do
+      expect(build{|s| s.set(:port)}.nonesuch).to eq(nil)
+    end
+
+    it "does not forward #to_a, which OptionParser answers with its help" do
+      expect(build{|s| s.set(:port)}.to_a).to eq(nil)
+    end
+
+    it "leaves Array() with the switches rather than the parser's help" do
+      switches = build{|s| s.set(:port)}
+      expect(Array(switches)).to eq([switches])
+    end
+
+    it "leaves the splat with the switches rather than the parser's help" do
+      switches = build{|s| s.set(:port)}
+      expect([*switches]).to eq([switches])
+    end
+  end
+
+  describe "multi-word switches" do
+    def build(switches_string = '')
+      ARGV.clear
+      switches_string.split.each{|a| ARGV << a}
+      Switches.new do |s|
+        s.boolean :update_template
+        s.set :access_token
+      end
+    end
+
+    it "sets a boolean switch supplied in its underscored form" do
+      expect(build('--update_template').update_template?).to eq(true)
+    end
+
+    it "sets a boolean switch supplied in its hyphenated form" do
+      expect(build('--update-template').update_template?).to eq(true)
+    end
+
+    it "sets a switch to the argument supplied in its underscored form" do
+      expect(build('--access_token abc123').access_token).to eq('abc123')
+    end
+
+    it "sets a switch to the argument supplied in its hyphenated form" do
+      expect(build('--access-token abc123').access_token).to eq('abc123')
+    end
+
+    it "names the setting for the symbol declared, whichever form is supplied" do
+      expect(build('--update-template --access-token abc123').to_h).to eq({update_template?: true, access_token: 'abc123'})
+    end
+  end
+
+  describe "multi-word switches with a required argument" do
+    def build(switches_string = '')
+      ARGV.clear
+      switches_string.split.each{|a| ARGV << a}
+      Switches.new do |s|
+        s.set! :access_token
+      end
+    end
+
+    it "sets the switch to the argument supplied in its underscored form" do
+      expect(build('--access_token abc123').access_token).to eq('abc123')
+    end
+
+    it "sets the switch to the argument supplied in its hyphenated form" do
+      expect(build('--access-token abc123').access_token).to eq('abc123')
+    end
+
+    it "raises OptionParser::MissingArgument when no argument is supplied to the underscored form" do
+      expect{build('--access_token')}.to raise_error(OptionParser::MissingArgument)
+    end
+
+    it "raises OptionParser::MissingArgument when no argument is supplied to the hyphenated form" do
+      expect{build('--access-token')}.to raise_error(OptionParser::MissingArgument)
+    end
+  end
+
+  describe "multi-word required switches" do
+    def build(switches_string = '')
+      ARGV.clear
+      switches_string.split.each{|a| ARGV << a}
+      Switches.new do |s|
+        s.required :access_token
+      end
+    end
+
+    it "counts the underscored form as supplied" do
+      expect(build('--access_token abc123').access_token).to eq('abc123')
+    end
+
+    it "counts the hyphenated form as supplied" do
+      expect(build('--access-token abc123').access_token).to eq('abc123')
+    end
+
+    it "raises RequiredSwitchMissing when neither form is supplied" do
+      expect{build}.to raise_error(RequiredSwitchMissing)
+    end
+
+    it "names the hyphenated form in the RequiredSwitchMissing message" do
+      expect{build}.to raise_error(RequiredSwitchMissing, /--access-token/)
+    end
+  end
+
   describe "#perform" do
     def build(switches_string = '', &block)
       ARGV.clear

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: switches.rb
 version: !ruby/object:Gem::Version
-  version: 0.10.4
+  version: 0.11.0
 platform: ruby
 authors:
 - thoran