user-choices 1.1.0

data/examples/tutorial/tutorial1.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+### The following adjusts the load path so that the correct version of
+### a self-contained package is found, no matter where the script is
+### run from. 
+require 'pathname'
+$:.unshift((Pathname.new(__FILE__).parent.parent.parent + 'lib').to_s)
+require 's4t-utils/load-path-auto-adjuster'
+
+require 'pp'
+require 'user-choices'
+
+# See the tutorial for explanations.
+
+class TutorialExample < UserChoices::Command
+  include UserChoices
+
+  def add_sources(builder)
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options]")
+    builder.add_source(EnvironmentSource, :with_prefix, "myprog_")
+    builder.add_source(YamlConfigFileSource, :from_file, ".myprog-config.yml")
+  end
+
+  def add_choices(builder)
+    builder.add_choice(:connections, :type=>:integer, :default=>0) { | command_line |
+      command_line.uses_option("-c", "--connections COUNT",
+                               "Number of connections to open.")
+    }
+  end
+
+  def execute
+    puts "There are #{@user_choices[:connections]} connections."
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    TutorialExample.new.execute
+  end
+end

data/examples/tutorial/tutorial2.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+
+# See the tutorial for explanations.
+
+### The following adjusts the load path so that the correct version of
+### a self-contained package is found, no matter where the script is
+### run from. 
+require 'pathname'
+$:.unshift((Pathname.new(__FILE__).parent.parent.parent + 'lib').to_s)
+require 's4t-utils/load-path-auto-adjuster'
+
+require 'pp'
+require 'user-choices'
+
+class TutorialExample < UserChoices::Command
+  include UserChoices
+
+  def add_sources(builder)
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] file1 [file2]")
+    builder.add_source(EnvironmentSource, :with_prefix, "myprog_")
+    builder.add_source(YamlConfigFileSource, :from_file, ".myprog-config.yml")
+  end
+
+  def add_choices(builder)
+    builder.add_choice(:connections, :type=>:integer, :default=>0) { | command_line |
+      command_line.uses_option("-c", "--connections COUNT",
+                               "Number of connections to open.")
+    }
+    builder.add_choice(:ssh, :type=>:boolean, :default=>false) { | command_line |
+      command_line.uses_switch("-s", "--ssh",
+                               "Use ssh to open connection.")
+    }
+  end
+
+  def execute
+    puts format("SSH %s be used.", @user_choices[:ssh] ? "should" : "should not")
+    puts "There are #{@user_choices[:connections]} connections."
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    TutorialExample.new.execute
+  end
+end

data/examples/tutorial/tutorial3.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+
+# See the tutorial for explanations.
+
+### The following adjusts the load path so that the correct version of
+### a self-contained package is found, no matter where the script is
+### run from. 
+require 'pathname'
+$:.unshift((Pathname.new(__FILE__).parent.parent.parent + 'lib').to_s)
+require 's4t-utils/load-path-auto-adjuster'
+
+require 'pp'
+require 'user-choices'
+
+class TutorialExample < UserChoices::Command
+  include UserChoices
+
+  def add_sources(builder)
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] file1 [file2]")
+    builder.add_source(EnvironmentSource, :with_prefix, "myprog_")
+    builder.add_source(YamlConfigFileSource, :from_file, ".myprog-config.yml")
+  end
+
+  def add_choices(builder)
+    builder.add_choice(:connections, :type=>:integer, :default=>0) { | command_line |
+      command_line.uses_option("-c", "--connections COUNT",
+                               "Number of connections to open.")
+    }
+    builder.add_choice(:ssh, :type=>:boolean, :default=>false) { | command_line |
+      command_line.uses_switch("-s", "--ssh",
+                               "Use ssh to open connection.")
+    }
+    builder.add_choice(:files) { | command_line | 
+      command_line.uses_arglist
+    }
+  end
+
+  def execute
+    puts format("SSH %s be used.", @user_choices[:ssh] ? "should" : "should not")
+    puts "There are #{@user_choices[:connections]} connections."
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    TutorialExample.new.execute
+  end
+end

data/examples/tutorial/tutorial4.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+
+# See the tutorial for explanations.
+
+### The following adjusts the load path so that the correct version of
+### a self-contained package is found, no matter where the script is
+### run from. 
+require 'pathname'
+$:.unshift((Pathname.new(__FILE__).parent.parent.parent + 'lib').to_s)
+require 's4t-utils/load-path-auto-adjuster'
+
+require 'pp'
+require 'user-choices'
+
+class TutorialExample < UserChoices::Command
+  include UserChoices
+
+  def add_sources(builder)
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] file1 [file2]")
+    builder.add_source(EnvironmentSource, :with_prefix, "myprog_")
+    builder.add_source(YamlConfigFileSource, :from_file, ".myprog-config.yml")
+  end
+
+  def add_choices(builder)
+    builder.add_choice(:connections, :type=>:integer, :default=>0) { | command_line |
+      command_line.uses_option("-c", "--connections COUNT",
+                               "Number of connections to open.")
+    }
+    builder.add_choice(:ssh, :type=>:boolean, :default=>false) { | command_line |
+      command_line.uses_switch("-s", "--ssh",
+                               "Use ssh to open connection.")
+    }
+    builder.add_choice(:files, :length => 1..2) { | command_line | 
+      command_line.uses_arglist
+    }
+  end
+
+  def execute
+    puts format("SSH %s be used.", @user_choices[:ssh] ? "should" : "should not")
+    puts "There are #{@user_choices[:connections]} connections."
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    TutorialExample.new.execute
+  end
+end

data/examples/tutorial/tutorial5.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+### The following adjusts the load path so that the correct version of
+### a self-contained package is found, no matter where the script is
+### run from. 
+require 'pathname'
+$:.unshift((Pathname.new(__FILE__).parent.parent.parent + 'lib').to_s)
+require 's4t-utils/load-path-auto-adjuster'
+
+require 'pp'
+require 'user-choices'
+
+class TutorialExample < UserChoices::Command
+  include UserChoices
+
+  def add_sources(builder)
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage: ruby #{$0} infile")
+  end
+
+  def add_choices(builder)
+    builder.add_choice(:infile) { | command_line | 
+      command_line.uses_arg
+    }
+  end
+  
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    TutorialExample.new.execute
+  end
+end

data/examples/tutorial/tutorial6.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+### The following adjusts the load path so that the correct version of
+### a self-contained package is found, no matter where the script is
+### run from. 
+require 'pathname'
+$:.unshift((Pathname.new(__FILE__).parent.parent.parent + 'lib').to_s)
+require 's4t-utils/load-path-auto-adjuster'
+
+require 'pp'
+require 'user-choices'
+
+class TutorialExample < UserChoices::Command
+  include UserChoices
+
+  def add_sources(builder)
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage: ruby #{$0} infile")
+  end
+
+  def add_choices(builder)
+    builder.add_choice(:infile) { | command_line | 
+      command_line.uses_optional_arg
+    }
+  end
+  
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    TutorialExample.new.execute
+  end
+end

data/examples/tutorial/tutorial7.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+### The following adjusts the load path so that the correct version of
+### a self-contained package is found, no matter where the script is
+### run from. 
+require 'pathname'
+$:.unshift((Pathname.new(__FILE__).parent.parent.parent + 'lib').to_s)
+require 's4t-utils/load-path-auto-adjuster'
+
+require 'pp'
+require 'user-choices'
+
+class TutorialExample < UserChoices::Command
+  include UserChoices
+
+  def add_sources(builder)
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage: ruby #{$0} infile outfile")
+  end
+
+  def add_choices(builder)
+    builder.add_choice(:files, :length => 2) { | command_line | 
+      command_line.uses_arglist
+    }
+  end
+  
+  def postprocess_user_choices
+    @user_choices[:infile] = @user_choices[:files][0]
+    @user_choices[:outfile] = @user_choices[:files][1]
+  end
+  
+
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    TutorialExample.new.execute
+  end
+end

data/lib/user-choices/arglist-strategies.rb

@@ -0,0 +1,178 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-10.
+#  Copyright (c) 2007. All rights reserved.
+
+require 'user-choices/ruby-extensions'
+
+module UserChoices # :nodoc:
+  
+  # Arglists cause complications, mainly because a command's arglist is 
+  # never optional. If you ever want it to be ignored, for example, you have to treat it
+  # specially. An AbstractArglistStrategy is a sequence of messages that can 
+  # cope with those sort of complications. These messages are called at the 
+  # appropriate time by a CommandLineSource. 
+  #
+  # * <b>AbstractArglistStrategy#fill</b> takes the arglist and converts it to 
+  #   the value of some choice symbol. The name should remind you of AbstractSource#fill.
+  # * There may be conversions that make sense for values (for this choice symbol) when 
+  #   those values do <i>not</i> come from an arglist, but not when they do. 
+  #   <b>AbstractArglistStrategy#claim_conversions</b> squirrels them away to protect
+  #   them from more generic processing. They are then specially processed by 
+  #   AbstractArglistStrategy#apply_claimed_conversions.
+  # * After conversions, there may still be work to do. There may be some special
+  #   reconciling required to the entire collection of choices. (The final result
+  #   may depend on what value the arglist provided and what value some other source 
+  #   provided.) <b>AbstractArglistStrategy#adjust</b> does that work.
+  class AbstractArglistStrategy # :nodoc:
+    
+    attr_reader :choice
+    
+    # A strategy applies an argument list named _choice_ that is a key 
+    # in the <i>value_holder</i>. It's hackish, but don't give the _choice_ in 
+    # the case where there should be no arglist (and thus no choice symbol to 
+    # attach it to).
+    def initialize(value_holder, choice=nil)
+      @value_holder = value_holder
+      @choice = choice
+    end
+    
+    # This method takes the argument list, an array, and puts it into 
+    # the <code>value_holder</code>. 
+    def fill(arglist); subclass_responsibility; end
+    
+    # Given _conversions_map_, a list of Conversion, select which apply to the arglist,
+    # removing them from the hash.
+    def claim_conversions(conversions_map) 
+      @claimed_conversions = []
+    end
+    
+    # Apply the claimed conversions to the value previously stored in claim_conversions.
+    def apply_claimed_conversions
+      # None claimed by default
+    end
+      
+    # Apply any effects of changes to the arglist to the result for all the choices. 
+    def adjust(all_choices)
+      # By default, do nothing.
+    end
+
+    # public for testing.
+    def arglist_arity_error(length, arglist_arity) # :nodoc:
+      plural = length==1 ? '' : 's'
+      expected = case arglist_arity
+        when Integer
+          arglist_arity.to_s
+        when Range
+          if arglist_arity.end == arglist_arity.begin.succ
+            "#{arglist_arity.begin} or #{arglist_arity.end}"
+          else
+            arglist_arity.in_words
+          end
+        else
+          arglist_arity.inspect
+        end
+      "#{length} argument#{plural} given, #{expected} expected."
+    end
+    
+
+    protected
+    
+    def claim_length_check(conversions_map)
+      @length_check = conversions_map[@choice].find { |c| c.does_length_check? }
+      if @length_check
+        conversions_map[@choice].reject { |c| c.does_length_check? }
+      end
+    end
+
+    
+  end
+  
+  # An AbstractArglistStrategy that rejects any non-empty arglist.
+  class NoArguments < AbstractArglistStrategy # :nodoc:
+    def fill(arglist)
+      user_claims(arglist.length == 0) do
+        "No arguments are allowed."
+      end
+    end
+    
+  end
+  
+  # The arglist is to be treated as a list, possibly with a Conversion that
+  # limits its length. It defers processing of an empty arglist until the 
+  # last possible moment and only does it if there's no other value for the
+  # choice symbol.
+  class ArbitraryArglist < AbstractArglistStrategy # :nodoc:
+    def fill(arglist)
+      @value_holder[@choice] = arglist unless arglist.empty?
+    end
+    
+    def claim_conversions(conversions_map)
+      claim_length_check(conversions_map)
+    end
+    
+    def apply_claimed_conversions
+      apply_length_check
+    end
+      
+    def adjust(all_choices)
+      return if @value_holder[@choice]
+      return if all_choices.has_key?(@choice)
+      
+      all_choices[@choice] = []
+      @value_holder[@choice] = all_choices[@choice]
+      apply_length_check
+    end
+
+    private
+    
+    def apply_length_check
+      return unless @length_check
+      return unless @value_holder[@choice]
+      
+      value = @value_holder[@choice]
+      user_claims(@length_check.suitable?(value)) {
+        arglist_arity_error(value.length, @length_check.required_length)
+      }
+    end
+  end
+  
+  # General handling for cases where the Arglist isn't treated as a list, but
+  # rather as a single (possibly optional) element. Subclasses handle the 
+  # optional/non-optional case.
+  class NonListStrategy < AbstractArglistStrategy # :nodoc:
+    def arity; subclass_responsibility; end
+    
+    def fill(arglist)
+      case arglist.length
+      when 0: # This is not considered an error because another source
+              # might fill in the value.
+      when 1: @value_holder[@choice] = arglist[0]
+      else user_is_bewildered(arglist_arity_error(arglist.length, self.arity))
+      end
+    end
+    
+    def claim_conversions(conversions_map)
+      claim_length_check(conversions_map)
+      user_denies(@length_check) {
+        "Don't specify the length of an argument list when it's not treated as an array."
+      }
+    end
+  end
+    
+  
+  class OneRequiredArg < NonListStrategy   # :nodoc:
+    def arity; 1; end
+    
+    def adjust(all_choices)
+      return if all_choices.has_key?(@choice)
+      user_is_bewildered(arglist_arity_error(0,1))
+    end
+    
+  end
+  
+  class OneOptionalArg < NonListStrategy # :nodoc:
+    def arity; 0..1; end
+  end
+
+end

data/lib/user-choices/builder.rb

@@ -0,0 +1,89 @@
+require 's4t-utils'
+include S4tUtils
+require 'enumerator'
+
+require 'user-choices/conversions'
+require 'user-choices/sources'
+
+module UserChoices
+
+  # This class accepts a series of source and choice descriptions
+  # and then builds a hash-like object that describes all the choices
+  # a user has made before (or while) invoking a script.
+  class ChoicesBuilder
+
+    def initialize
+      @defaults = {}
+      @conversions = {}
+      @sources = []
+    end
+    
+    # Add the choice named _choice_, a symbol. _args_ is a keyword
+    # argument: 
+    # * <tt>:default</tt> takes a value that is the default value of the _choice_. 
+    # * <tt>:type</tt> can be given an array of valid string values. These are
+    #   checked.
+    # * <tt>:type</tt> can also be given <tt>:integer</tt>. The value is cast into
+    #   an integer. If that's impossible, an exception is raised. 
+    # * <tt>:type</tt> can also be given <tt>:boolean</tt>. The value is converted into
+    #   +true+ or +false+ (or an exception is raised).
+    # * <tt>:type</tt> can also be given <tt>[:string]</tt>. The value
+    #   will be an array of strings. For example, "--value a,b,c" will
+    #   produce ['a', 'b', 'c'].
+    #
+    # You might also give <tt>:length => 5</tt> or <tt>:length => 3..4</tt>. (In 
+    # this case, a <tt>:type</tt> of <tt>[:string]</tt> is assumed.)
+    # 
+    # The _block_ is passed a CommandLineSource object. It's used
+    # to describe the command line.
+    def add_choice(choice, args={}, &block)
+      # TODO: does the has_key? actually make a difference?
+      @defaults[choice] = args[:default] if args.has_key?(:default)
+      @conversions[choice] = []
+      Conversion.record_for(args[:type], @conversions[choice])
+      if args.has_key?(:length)
+        Conversion.record_for({:length => args[:length]}, @conversions[choice])
+      end
+      block.call(ArgForwarder.new(@command_line_source, choice)) if block
+    end
+
+    # This adds a source of choices. The _source_ is a class like
+    # CommandLineSource. The <tt>messages_and_args</tt> are sent 
+    # to a new object of that class. 
+    def add_source(source_class, *messages_and_args)
+      source = source_class.new
+      message_sends(messages_and_args).each { | send_me | source.send(*send_me) }
+      @sources << source
+      @command_line_source = source if source_class == CommandLineSource
+    end
+
+    # Once sources and choices have been described, this builds and
+    # returns a hash-like object indexed by the choices.
+    def build
+      retval = {}
+      @sources << DefaultSource.new.use_hash(@defaults)
+      @sources.each { |s| s.fill }
+      @sources.each { |s| s.apply(@conversions) }
+      @sources.reverse.each { |s| retval.merge!(s) }
+      @sources.each { |s| s.adjust(retval) }
+      retval
+    end
+    
+    # Public for testing.
+    
+    def message_sends(messages_and_args)  # :nodoc: 
+      where_at = symbol_indices(messages_and_args)
+      where_end = where_at[1..-1] + [messages_and_args.length]
+      where_at.to_enum(:each_with_index).collect do |start, where_end_index |
+        messages_and_args[start...where_end[where_end_index]]
+      end
+    end
+    
+    def symbol_indices(array) # :nodoc: 
+      array.to_enum(:each_with_index).collect do |obj, index|
+        index if obj.is_a?(Symbol)
+      end.compact
+    end
+  end
+
+end