switches.rb 0.11.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc49f311d672f64884c36a8b1645d17be83d83df5e630a272a4740db00a48448
-  data.tar.gz: 9a5b8accb318737020f7d1c03dfee96ae21529dafe357aabc62abcbd5314dc5a
+  metadata.gz: 43cb8cbe7416baef56a0b3da428ad241fcd8b4622d926e6c64e0db0aa311d439
+  data.tar.gz: cbd74c3f9d883474c4e207ae1974f9f8271d2fb25865cf606c48794bc1498a61
 SHA512:
-  metadata.gz: 0171a8d12cacc99884b6606f08fb5fbf2ac048e5f9d8ed147e3bfe224a2724d2ecb6fc6d077edc9e533a2a7d4dfd2a0fb9c8563f63824ed0cd78506f6c708795
-  data.tar.gz: 7888b090acfe50edc7ded58b12b005232be881e0c9489edb07dec7fd126ec7afb8ef1a1cb926682e0eec96bd19efc4a5f26e9a555341f637e3caa60a905f04b8
+  metadata.gz: 06ab95f84758ab089a5ce0665ed43e5177b9fd638a0a663ade5ab52c94d587447ccd25fa890c26cd126a44b9da801bbb4aa0d1b647cc3d3423d6095cebdd64e8
+  data.tar.gz: bdc919b1bb6d903752337f606c91cd8cde56df35185c5b3b22a54aa5e7ef69bc30ac4553a03de60ff65773f4460bc905e6f5324c8ddf01d0deec0a8a7b55a29c

data/CHANGELOG

@@ -2,23 +2,33 @@
 
 ## 20260816
 
-0.11.0: Forward to OptionParser, which #method_missing has never actually done.
+0.12.1: Move the reasoning out of the CHANGELOG and the header into a ROADMAP.
+
+1. + ROADMAP.md: the design philosophy, a section per shipped version carrying why it went the way it did, the open questions, and the settled items. Not listed in the gemspec, so it does not ship. Follows namo's ROADMAP.md.
+2. - lib/Switches.rb: the # Todo: and # Ideas: header sections, now in ROADMAP.md, finishing what 0.10.2 began.
+3. ~ CHANGELOG: the 0.10.5 and 0.11.0 entries carried reasoning, measurement and outstanding work in prose between their numbered items; that is now in ROADMAP.md, and the entries record what changed.
 
-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.
+0.12.0: Refuse a switch whose accessor is a method the instance already has, rather than losing it.
 
-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.
+1. + lib/Switches.rb: Switches#check_switch_names, called first in #do_set and #do_action, which raises where respond_to?(accessor) is true, #method_missing firing only where no method exists.
+2. + lib/Switches.rb: SwitchNameCollision < ArgumentError.
+3. ~ README.md: + a Notes entry for the refusal, and for the booleans and OptionParser names it does not cover.
+4. + spec/all.rb: the refusal through #set and #perform, the message, that nothing reaches the parser first, and the two legal cases.
+5. + ROADMAP.md, and - the # Todo: and # Ideas: sections from the lib/Switches.rb header, which is where they were. Not listed in the gemspec, so it does not ship.
+
+0.11.0: Forward to OptionParser, which #method_missing has never actually done.
 
-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.
+1. ~ lib/Switches.rb: #method_missing compared method_name.to_s against @op.methods, an array of Symbols, so the forwarding branch was never true; now compared in symbols.
+2. ~ lib/Switches.rb: + Switches#declared_switch?, giving a declared switch precedence over the OptionParser method of the same name.
+3. + lib/Switches.rb: Switches::NEVER_FORWARDED, the names Ruby may call implicitly, excluded from the forwarded set, OptionParser#to_a otherwise answering Array() with the help.
+4. ~ lib/Switches.rb: + Switches#option_parser_methods, memoised, and + Switches#option_parser_method?.
+5. + spec/all.rb: the forwarding, the precedence rule, the fall-through, and #to_a.
+6. ~ README.md: the Notes entry describing forwarding, which had it backwards.
 
 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.
+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; and that the setting is named for the symbol declared. The behaviour is OptionParser's, a long switch being filed under a lookup key with its underscores turned to hyphens.
+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.
 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.
 

data/README.md

@@ -192,6 +192,7 @@ switches.class # => Hash
 ## Notes
 
 - The switch `-?` can't be used, since there is no Ruby method `#?` for it to map to.
+- A switch whose accessor would be a method the instance already has is refused at declaration, with a `SwitchNameCollision`. `s.set(:tap)` raises, `#tap` being `Kernel#tap` and so never reaching the settings; so do `Switches`' own methods, `s.set(:settings)` and `s.set(:set)` among them. The same name is fine as a boolean, since `s.boolean(:tap)` reads back through `#tap?`, and fine where the collision is with `OptionParser` rather than the instance, a declared switch winning over the parser.
 - 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.

data/lib/Switches/VERSION.rb

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

data/lib/Switches.rb

@@ -3,15 +3,6 @@
 
 # Description: Switches provides for a nice wrapper to OptionParser to also act as a store for switches supplied.  
 
-# Todo:
-# 1. Clean up #set.  Done as of 0.4.0.  
-# 2. Reinstitute some specs.  Done as of 0.9.8.  
-
-# Ideas: 
-# 1. Use ! for options with required switches?  Done as of 0.6.0.  (Changed to being for required arguments in 0.9.0 however.)
-# 2. Do away with optional arguments entirely.  Since when does anyone want to specify a non-boolean switch and then supply no arguments anyway?...  OK, maybe sometimes, but this is pretty obscure IMO.  OK, bad idea.  These can be used as action oriented sub-commands.  
-# 3. Allow for any one of the switches OpenStruct methods to assign values for any of the other associated methods, so as it is more than a read once switch and can be used for storage through out the application; although this might be stepping on Attributes.rb's toes?...  
-
 # Dependencies:
 # 1. Standard Ruby Library.
 # 2. ostruct, which ceased to be a default gem as of Ruby 4.0 and so is declared in the gemspec.
@@ -150,6 +141,7 @@ module CastingInterfaceMethods
 end
 
 class RequiredSwitchMissing < RuntimeError; end
+class SwitchNameCollision < ArgumentError; end
 
 class Switches
   
@@ -257,6 +249,7 @@ class Switches
   private
   
   def do_set(requires_argument, *attrs, &block)
+    check_switch_names(*attrs)
     set_if_required_switch(*attrs)
     options = attrs.extract_options!
     @all_switches = @all_switches + attrs.collect{|a| a.to_s}
@@ -268,6 +261,7 @@ class Switches
   end
   
   def do_action(requires_argument, *attrs, &block)
+    check_switch_names(*attrs)
     attrs.each do |attr|
       @settings.send(attr.to_s + '=', nil) # Needs to be set prior to checking for required switches, since that check relies upon the key having been set in @settings.  
     end
@@ -299,6 +293,14 @@ class Switches
     @all_switches.include?(method_name.to_s.delete_suffix('='))
   end
   
+  def check_switch_names(*attrs)
+    attrs.each do |attr|
+      next unless attr.is_a?(Symbol) || attr.is_a?(String)
+      next unless respond_to?(attr.to_s)
+      raise SwitchNameCollision, "switch, #{switch_string(attr)}, is already #{method(attr.to_s).owner}##{attr}, so it would never reach the settings"
+    end
+  end
+
   def switch_string(attr)
     attr = attr.to_s
     "-#{attr.long_switch? ? '-' : ''}#{attr.delete('?')}"

data/spec/all.rb

@@ -164,6 +164,51 @@ describe Switches do
     end
   end
 
+  describe "switch names which collide with a method" do
+    def build(&block)
+      ARGV.clear
+      Switches.new(&block)
+    end
+
+    it "refuses a switch named after a core method" do
+      expect{build{|s| s.set(:tap)}}.to raise_error(SwitchNameCollision, /Kernel#tap/)
+    end
+
+    it "refuses a switch named after a Switches method" do
+      expect{build{|s| s.set(:settings)}}.to raise_error(SwitchNameCollision, /Switches#settings/)
+    end
+
+    it "refuses a colliding name declared through #perform" do
+      expect{build{|s| s.perform(:display){}}}.to raise_error(SwitchNameCollision)
+    end
+
+    it "names the switch in the form it would be supplied in" do
+      expect{build{|s| s.set(:instance_variable_get)}}.to raise_error(SwitchNameCollision, /--instance_variable_get/)
+    end
+
+    it "raises before the switch is declared to the parser" do
+      switches = Switches.new
+      begin; switches.set(:tap); rescue SwitchNameCollision; end
+      expect(switches.to_h).to eq({})
+    end
+
+    it "accepts the name as a boolean, the accessor then carrying a question mark" do
+      ARGV.clear
+      ARGV << '--tap'
+      expect(Switches.new{|s| s.boolean(:tap)}.tap?).to eq(true)
+    end
+
+    it "accepts a name OptionParser has, a declared switch winning over the parser" do
+      ARGV.clear
+      %w{--banner text}.each{|a| ARGV << a}
+      expect(Switches.new{|s| s.set(:banner)}.banner).to eq('text')
+    end
+
+    it "raises a SwitchNameCollision, which is an ArgumentError" do
+      expect(SwitchNameCollision.ancestors).to include(ArgumentError)
+    end
+  end
+
   describe "OptionParser methods" do
     def build(&block)
       ARGV.clear

metadata

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