option_list 0.1.6

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTZjYWUzNDczZmFlZTFhNTNlNTU0YmEzZjYzNGM1OTUzZDJmNTdjNw==
+  data.tar.gz: !binary |-
+    OTljOTcyODI0MDIyNzgxYjE3ZTkzNjQyOWUwZDk5NTgyZGVjYTAzMQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ODg1OWYxZGU0YmU1MmYyYjRmMTZlOGE1NGZlYWYzMDlmOTY2MjRlZmM1NzM3
+    YTRjODM2ZDUyYzk2MDRiOGY3OWY3MmM4Zjk4ZTJiMWU3ZTRkMDcyZDQwZmZk
+    OWUwMzRiYTMyNjcyZmZmNzYzOGYyMGZmMWNmZmQ3OWQyM2JhMGU=
+  data.tar.gz: !binary |-
+    Y2VhZjdhNDFhMjlhNDdlZjRjNTJhMmFkM2NlMTE4YTg5YzE4YmVkYWY5M2I0
+    NmVmMWFhMWE0OWQ1YTdlZDEyNmZkZDNkZWI3MjM4NjFhYmEwNjFlNGIxZWJi
+    MDU0OTMwODUyNDQzZDI5ZGQzN2MyYmUyZGU2ZGRiODk3MWIxNzA=

data/option_list.rb

@@ -0,0 +1,260 @@
+require 'set'
+
+#=== The MIT License (MIT).
+#
+#Copyright (c) 2013 Peter Camilleri
+#
+#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.
+#
+#=== The file option_list.rb and the class \OptionList.
+#This file contains the code for the \OptionList class that implements smart
+#and easy options for functions. It has the virtue of defining function
+#options clearly in a single place instead of spread out in complex code.
+#A classic but unclear sequence in many functions is the use of boolean values
+#to control or switch on or off some option. For example consider the well 
+#known readline function:
+# cmd = readline(">", false)
+#See the boolean at the end? It says "false". What is "false"? Who knows? You 
+#need to dig deeper or guess or just cut and paste without understanding. What
+#if, instead, the code looked like:
+# cmd = readline(">", :nohistory)
+#The boolean has been replaced by something a lot clearer. The problem with
+#such clarity is that it involves a lot more effort than the lazy boolean. The
+#\OptionList class aims to solve that issue by making useful, flexible options
+#just about as easy to use as the lazy way.
+#==== Warning: This code is most opinionated! ;-)
+#The philosophy and opinion expressed through this code is that errors should
+#be detected as close to the point of error as possible and that an error is
+#preferable to running with potentially incorrect results. As a result, it
+#will be noted that the programmer does not hesitate to use the fAE, a wrapper
+#of the "fail" keyword, liberally throughout the code to achieve this end.
+#Complimentary to this is the idea that the library (gem) writer should do as
+#much of the "heavy lifting" as possible, with clear, detailed documentation so
+#that the library (gem) user does not have to work hard or be lost or confused.
+#Only time will tell to what extent these lofty goals have been achieved. 
+#Hopefully, with good feedback, this and other code libraries will improve.
+class OptionList
+  #An internal marker for value entries.
+  VALUE_ENTRY = 'A value entry.'
+
+  #Create an option list from an array of option specs. These specs consist of
+  #a number of array specifications and hash specifications.
+  #==== Array Specification
+  #In the array form of specification, the first element of the array is the
+  #category of the option, and the subsequent entries are the allowed values
+  #for that category. The first of these values is the default value for the 
+  #category. This may be nil to have no default value. The symbols used in each
+  #category must be unique. Duplicates will fail with an ArgumentError.
+  #==== Hash Specification
+  #In the hash form of specification, the key is the category and the value 
+  #is the default value. There is no list of allowed values in this case. 
+  #==== Example:
+  # @opt_list = OptionList.new([:history, :history, :nohistory], {:page_len => 42})
+  #==== Parameters:
+  #* option_specs - The comma separated option specs, made into an array by the
+  #  splat operator.
+  #==== Dynamic Methods:
+  #As option specs are added, new methods are created to allow for easy access
+  #to the option information. If the above example were processed, the following
+  #methods would be added:
+  #* history - would return the value of the :history category.
+  #* history? - would return true if the :history option where active.
+  #* nohistory? - would return true if the :nohistory option were active.
+  #* page_len - would return the value of the :page_len category.
+  #==== Exceptions:
+  #* ArgumentError for a number of invalid argument conditions.
+  def initialize(*option_specs)
+    @categories = Hash.new
+    @default    = Hash.new
+    @selected   = Hash.new
+    do_add_specs(option_specs)
+  end
+  
+  #Add additonal option specifications to the option list. See the method new
+  #for more information on those specifications.
+  def add_specs(*option_specs)
+    do_add_specs(option_specs)
+  end
+  
+  private  #Private methods follow.
+
+  #Iterate over the array of specs, adding them to the option list.
+  def do_add_specs(option_specs)
+    option_specs.each do |spec|
+      if spec.is_a?(Hash)
+        hash_spec(spec)
+      elsif spec.is_a?(Array)
+        array_spec(spec)
+      else
+        fAE "Found #{spec.class} instead of Hash or Array."
+      end
+    end
+  end
+  
+  #Process an array spec that lists all the valid values for an option. See
+  #the new method for more information on these specs.
+  def array_spec(spec)
+    cat = spec.delete_at(0)
+    fAE "Found #{cat.class}, expected Symbol." unless cat.is_a?(Symbol)   
+    fAE "Duplicate category: #{cat}" if @default.has_key?(cat)
+    fAE "Invalid number of entries for #{cat}." unless spec.length > 1
+    define_singleton_method(cat) { @selected[cat] }
+
+    spec.each_with_index do |opt, index|
+      if opt != nil
+        fAE "Found #{opt.class}, expected Symbol." unless opt.is_a?(Symbol)   
+        fAE "Duplicate option: #{opt}" if @categories.has_key?(opt)
+        
+        @categories[opt] = cat
+        qry = (opt.to_s + '?').to_sym
+        define_singleton_method(qry) { @selected[cat] == opt }
+        @selected[cat] = @default[cat] = opt if index == 0
+      elsif index == 0
+        @selected[cat] = @default[cat] = nil
+      else
+        fAE "The value nil is only allowed as the default option."
+      end
+    end
+  end
+  
+  #Process a hash spec that lists only the default value for an option. See
+  #the new method for more information on these specs.
+  def hash_spec(spec)
+    fAE "Hash contains no specs." unless spec.length > 0
+
+    spec.each do |cat, value|
+      fAE "Found #{cat.class}, expected Symbol." unless cat.is_a?(Symbol)    
+      fAE "Duplicate category: #{cat}" if @default.has_key?(cat)
+      
+      define_singleton_method(cat) { @selected[cat] }
+      @categories[cat] = VALUE_ENTRY
+      @selected[cat] = @default[cat] = value    
+    end  
+  end
+  
+  public #Back to public methods.
+  
+  #From the possible options, select the actual, in force, options for use in
+  #the code. These options may take several forms:
+  #=== Types of option data:
+  #* A symbol - For categories with a specified symbol list, simply list one
+  #  of the allowed symbols.
+  #* A hash - For any type of category, a hash may be used in the the form
+  #  {category => value}. Note that for categories with a specified symbol list
+  #  the value must be a symbol in the list.
+  #* Mixed - Symbols and hashes can be mixed in an array (see below on how this
+  #  is done) Note: Option order does not matter.
+  #Some examples:
+  # foo(:sedan, :turbo)
+  # foo({:style=>:sedan})
+  # foo({:page_len=>60})
+  # foo(:sedan, :turbo, {:page_len=>60})
+  # foo({:style=>:sedan, :page_len=>60})
+  # foo({:style=>:sedan}, {:page_len=>60})
+  #=== Passing in option data:
+  #The caller of this method may pass these options in a number of ways:
+  #==== Array (via a splat)
+  #Given the example shown in the new method, consider:
+  # def test(count, *opt)
+  #   @opt_list.select(opt)
+  #   #etc, etc, etc...
+  # end
+  #With the caller now looking like:
+  # test(43, :history)
+  #==== Array (explicit)
+  #An alternative strategy, where the use of splat is not desired, is to simply
+  #have an array argument, as below:
+  # def test(*arg1, opt)
+  #   @opt_list.select(opt)
+  #   #etc, etc, etc...
+  # end
+  #With the caller now looking like:
+  # test(34, 53, 76, 'hike!', [:history])
+  #==== Hash
+  #Options may also be passed via a hash.
+  # test(34, 53, 76, 'hike!', {:history=>:history, :page_len=>55})
+  #==== Symbol
+  #If only a single option is required, it can be passed simply as:
+  # test(34, 53, 76, 'hike!', :history)
+  #==== Parameters:
+  #* selections - An array of the options passed into the client function, usually
+  #  with the splat operator. Note that if select is called with no arguments,
+  #  all of the default values will be selected.
+  #==== Exceptions:
+  #* ArgumentError for a number of invalid argument conditions.
+  def select(selections=[])
+    @selected = @default.clone
+    add_selections(selections)
+  end
+
+  #Add/override additional selections to the option_list. See the select method
+  #for more information about those selection values.
+  def add_selections(selections=[])
+    selections = [selections] unless selections.is_a?(Array)
+    dup = Set.new
+
+    selections.each do |opt|
+      if opt.is_a?(Symbol)
+        symbolic_selection(opt, dup)
+      elsif opt.is_a?(Hash)
+        hash_selections(opt, dup)
+      else
+        fAE "Found #{opt.class} instead of Hash or Symbol."
+      end
+    end
+  end
+  
+  private  #Some more privacy, please!
+  
+  #Process a symbolic option selection.
+  #==== Parameters:
+  #* option - a symbol to process.
+  #* dup - a set of categories that have been set. Used to detect duplicates.
+  def symbolic_selection(option, dup)
+    fAE "Unknown option: #{option}." unless @categories.has_key?(option)
+    cat = @categories[option]
+    fAE "Category #{cat} has multiple values." if dup.include?(cat)
+    dup.add(cat)
+    @selected[cat] = option
+  end
+  
+  #Process a hash of option selection values.
+  #==== Parameters:
+  #* options - a hash of options to process.
+  #* dup - a set of categories that have been set. Used to detect duplicates.
+  def hash_selections(options, dup)
+    options.each do |cat, value|
+      fAE "Not a category: #{cat}." unless @default.has_key?(cat)
+      fAE "Category #{cat} has multiple values." if dup.include?(cat)
+           
+      unless (@categories[cat] == VALUE_ENTRY) || value.nil?
+        fAE "Found #{opt.class}, expected Symbol." unless value.is_a?(Symbol)
+        fAE "Invalid option: #{value}." unless @categories[value] == cat
+      end
+      
+      dup.add(cat)
+      @selected[cat] = value
+    end
+  end
+  
+  #Fail with an argument error.
+  def fAE(msg)
+    fail(ArgumentError, msg, caller)
+  end
+end

data/option_list_test.rb

@@ -0,0 +1,244 @@
+#A formal testing frame for the option list class.
+#Execute this file to perform the tests.
+
+require_relative 'option_list'
+require          'minitest/autorun'
+
+class OptionListTester < MiniTest::Unit::TestCase
+  def setup
+    @ol1 = OptionList.new([:history, :history, :nohistory], {:pg_len => 42})
+    @ol2 = OptionList.new([:history, nil, :history, :nohistory]) 
+  end
+
+  def test_that_it_rejects_bad_specs
+    #Reject empty argument lists.
+    assert_raises(ArgumentError) { @x = OptionList.new([])}
+    assert_raises(ArgumentError) { @x = OptionList.new({})}
+    
+    #Reject if not an array or a hash.
+    assert_raises(ArgumentError) { @x = OptionList.new(4) }
+    assert_raises(ArgumentError) { @x = OptionList.new('foobar') }    
+
+    #Reject for too few arguments.
+    assert_raises(ArgumentError) { @x = OptionList.new([]) }
+    assert_raises(ArgumentError) { @x = OptionList.new([:foo]) }
+    assert_raises(ArgumentError) { @x = OptionList.new([:foo, :bar]) }
+    
+    #Reject for the wrong types of arguments.
+    assert_raises(ArgumentError) { @x = OptionList.new(['foo', :foo,  :bar] )}
+    assert_raises(ArgumentError) { @x = OptionList.new([:foo,  'foo', :bar] )}
+    assert_raises(ArgumentError) { @x = OptionList.new([:foo,  :foo,  'bar'])}
+    assert_raises(ArgumentError) { @x = OptionList.new({'foo' => 42})}
+    
+    #Reject for duplicate categories.
+    assert_raises(ArgumentError) { @x = OptionList.new([:foo, :lala, :bar], [:foo, :kung, :east]) }
+    assert_raises(ArgumentError) { @x = OptionList.new([:foo, :lala, :bar], {:foo => :kung}) }
+    assert_raises(ArgumentError) { @x = OptionList.new({:foo => :lala}, {:foo => :kung}) }
+    #The following is not detectable since :foo => :kung overwrites :foo => :lala
+    #assert_raises(ArgumentError) { @x = OptionList.new({:foo => :lala, :foo => :kung}) }
+    
+    #Reject for duplicate options.
+    assert_raises(ArgumentError) { @x = OptionList.new([:foo, :bar, :bar]) }
+    assert_raises(ArgumentError) { @x = OptionList.new([:foo, :foo, :bar], [:bla, :food, :bar]) }    
+
+    #Reject for nil in the wrong position.    
+    assert_raises(ArgumentError) { @x = OptionList.new([:foo, :bar, nil]) }
+  end
+  
+  def test_that_the_methods_were_added
+    assert_respond_to(@ol1, :history)
+    assert_respond_to(@ol1, :history? )
+    assert_respond_to(@ol1, :nohistory? )
+    assert_respond_to(@ol1, :pg_len)
+    
+    assert_respond_to(@ol2, :history)
+    assert_respond_to(@ol2, :history? )
+    assert_respond_to(@ol2, :nohistory? )
+    assert_raises(NoMethodError) { @ol2.send((nil.to_s+'?').to_sym) }
+  end
+  
+  def test_that_it_rejects_bad_added_specs
+    #reject a bad addition...
+    assert_raises(ArgumentError) {@ol1.add_specs({:history=>'fun'})}
+    #but don't mess up.
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)
+
+    #reject a bad addition...
+    assert_raises(ArgumentError) {@ol1.add_specs({:pg_len=>66})}
+    #but don't mess up.
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)
+  end
+
+  def test_that_it_rejects_bad_selections
+    #Reject if options are not an array or a hash.
+    assert_raises(ArgumentError) { @ol1.select(45) }
+    
+    #Reject if the option is not a symbol.
+    assert_raises(ArgumentError) { @ol1.select([34]) }
+    
+    #Reject if the category is not a symbol.
+    assert_raises(ArgumentError) { @ol1.select({'page_len'=>77}) }
+    
+    #Reject if the symbol is not one defined.
+    assert_raises(ArgumentError) { @ol1.select([:foobar]) }
+    assert_raises(ArgumentError) { @ol1.select({:history=>:foobar}) }
+    
+    #Reject on duplicate symbol from the same category.
+    assert_raises(ArgumentError) { @ol1.select([:history, :history]) }
+    assert_raises(ArgumentError) { @ol1.select([:history, :nohistory]) }   
+    assert_raises(ArgumentError) { @ol1.select([:history, {:history=>:nohistory}]) }
+    assert_raises(ArgumentError) { @ol1.select([{:history=>:history}, {:history=>:nohistory}]) }
+    
+    #Reject on an undefined category.
+    assert_raises(ArgumentError) { @ol1.select({:zoo => 999})}
+  end
+  
+  def test_that_it_handles_good_options
+    #ol1 test series.
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)    
+    
+    @ol1.select
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)    
+    
+    @ol1.select([])
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)    
+    
+    @ol1.select([:history])
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)    
+    
+    @ol1.select([:nohistory])
+    assert(@ol1.nohistory?)
+    refute(@ol1.history?)
+    assert_equal(@ol1.history, :nohistory)
+    assert_equal(@ol1.pg_len, 42)    
+
+    @ol1.select({:history=>:history})
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)    
+    
+    @ol1.select({:history=>:nohistory})
+    assert(@ol1.nohistory?)
+    refute(@ol1.history?)
+    assert_equal(@ol1.history, :nohistory)
+    assert_equal(@ol1.pg_len, 42)    
+
+    @ol1.select({:pg_len=>55})
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 55)
+    
+    @ol1.select({:history=>:history, :pg_len=>55})
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 55)
+
+    @ol1.select({:history=>:nohistory, :pg_len=>55})
+    assert(@ol1.nohistory?)
+    refute(@ol1.history?)
+    assert_equal(@ol1.history, :nohistory)
+    assert_equal(@ol1.pg_len, 55)
+
+    @ol1.select([:history, {:pg_len=>55}])
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 55)
+
+    @ol1.select([:nohistory, {:pg_len=>55}])
+    assert(@ol1.nohistory?)
+    refute(@ol1.history?)
+    assert_equal(@ol1.history, :nohistory)
+    assert_equal(@ol1.pg_len, 55)
+    
+    @ol1.add_specs([:temp, nil, :hot, :nice, :cold])
+    @ol1.select   #Restore to default values.
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)    
+    refute(@ol1.hot?)
+    refute(@ol1.nice?)
+    refute(@ol1.cold?)
+    assert_equal(@ol1.temp, nil)    
+    @ol1.select(:hot)
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)    
+    assert(@ol1.hot?)
+    refute(@ol1.nice?)
+    refute(@ol1.cold?)
+    assert_equal(@ol1.temp, :hot)
+    
+    #Adding selections.
+    @ol1.select   #Restore to default values.
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)    
+    refute(@ol1.hot?)
+    refute(@ol1.nice?)
+    refute(@ol1.cold?)
+    assert_equal(@ol1.temp, nil)
+    @ol1.add_selections({:temp=>:hot})
+    assert(@ol1.history?)
+    refute(@ol1.nohistory?)
+    assert_equal(@ol1.history, :history)
+    assert_equal(@ol1.pg_len, 42)    
+    assert(@ol1.hot?)
+    refute(@ol1.nice?)
+    refute(@ol1.cold?)
+    assert_equal(@ol1.temp, :hot)
+    @ol1.add_selections([:cold, :nohistory])
+    assert(@ol1.nohistory?)
+    refute(@ol1.history?)
+    assert_equal(@ol1.history, :nohistory)
+    refute(@ol1.hot?)
+    refute(@ol1.nice?)
+    assert(@ol1.cold?)
+    assert_equal(@ol1.temp, :cold)
+
+
+    #ol2 test series.
+    refute(@ol2.history?)
+    refute(@ol2.nohistory?)
+    assert(@ol2.history.nil?)
+    
+    @ol2.select([:history])
+    assert(@ol2.history?)
+    refute(@ol2.nohistory?)
+    assert_equal(@ol2.history, :history)
+    
+    @ol2.select([:nohistory])
+    assert(@ol2.nohistory?)
+    refute(@ol2.history?)
+    assert_equal(@ol2.history, :nohistory)
+    
+    @ol2.select([])
+    refute(@ol2.history?)
+    refute(@ol2.nohistory?)
+    assert(@ol2.history.nil?)
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: option_list
+version: !ruby/object:Gem::Version
+  version: 0.1.6
+platform: ruby
+authors:
+- Peter Camilleri
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-20 00:00:00.000000000 Z
+dependencies: []
+description: A unified handler for flexible function option parameters.
+email: peter.c.camilleri@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- option_list.rb
+- option_list_test.rb
+homepage: http://teuthida-technologies.com/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --output=doc
+- option_list.rb
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- No special requirements.
+rubyforge_project: 
+rubygems_version: 2.0.7
+signing_key: 
+specification_version: 4
+summary: A unified handler for flexible function option parameters.
+test_files:
+- option_list_test.rb