qoobaa-user-choices 1.1.7

data/examples/tutorial/tutorial1.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+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,44 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+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,47 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+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,47 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+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,35 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+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,35 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+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,41 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-09.
+#  Copyright (c) 2007. All rights reserved.
+
+# See the tutorial for explanations.
+
+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.rb

@@ -0,0 +1,131 @@
+require 'user-choices/arglist-strategies'
+require 'user-choices/builder'
+require 'user-choices/command'
+require 'user-choices/command-line-source'
+require "user-choices/conversions"
+require "user-choices/ruby-extensions"
+require 'user-choices/sources'
+require 'user-choices/version'
+
+=begin rdoc
+
+UserChoices provides a unified interface to more than one source of
+user choices: the command line, environment variables, configuration
+files, and the choice to use program defaults. A typical usage defines allowable choices
+within the framework of a Command object:
+
+    class Example < Command
+
+      # The sources are the various places in which the user can
+      # describe her choices to the program.
+
+      def add_sources(builder)
+        builder.add_source(...)
+        ...
+      end
+
+      # Each individual choice is named with a symbol that is common
+      # to all sources.
+      def add_choices(builder)
+        builder.add_choice(:choice, ...) { | command_line | ... }
+      end
+
+      # Immediately after recording the choices, the program can
+      # add new (derived ones) or do any other once-per-program
+      # initialization.
+      def postprocess_user_choices
+        ... @user_choices ...
+      end
+
+      # Perform the command.
+      def execute
+        ...
+      end
+    end
+
+    ...
+    CommandLineExample.new.execute
+    ...
+
+= Describing sources
+
+Sources are described by ChoicesBuilder#add_source.
+
+EnvironmentSource describes the use of environment variables as sources. The following says that all environment variables beginning with "amazon_" are choices about this program.
+
+    builder.add_source(EnvironmentSource, :with_prefix, "amazon_")
+
+XmlConfigFileSource points to a configuration file with choices.
+
+    builder.add_source(XmlConfigFileSource, :from_file, "ms-config.xml")
+
+CommandLineSource uses the command line options and
+arguments as a source of choices. The following gives the usage line
+for the script:
+
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage ruby #{$0} [options] names...")
+
+= Describing choices
+
+The end result of the process is a hash mapping choices to chosen
+values. Choices are named by symbols. They are described by
+ChoicesBuilder#add_choice. Here are simple examples that
+don't involve the command line.
+
+The first just names a choice.
+
+    builder.add_choice(:ordinary_choice)
+
+The second gives a default value:
+
+    builder.add_choice(:ordinary_choice,
+                       :default => "eaargh")
+
+The second gives a default value and a type. The type is used to check the value and, if appropriate, to convert the value away from a string. Note that the default is always a string regardless of the type.
+
+    builder.add_choice(:on,
+                       :default => "false",
+                       :type => :boolean)
+
+= Command line options
+
+ChoicesBuilder#add_choice passes a
+CommandLineSource object to a block. That can be used to
+describe the command line. The syntax is the same as OptionParser.
+
+In the following, <tt>ordinary_choice</tt> can be specified with either the <tt>-o</tt> or <tt>--ordinary-choice</tt> options. The strings also appear in help messages (automatically produced from <tt>ruby script --help</tt>).
+
+    builder.add_choice(:ordinary_choice,
+                       :default => 'default') { | command_line |
+      command_line.uses_option("-o", "--ordinary-choice CHOICE",
+                               "CHOICE can be any string.")
+    }
+
+The command line's argument list (everything that's not an option) can
+be bundled up into another choice. Here, the arguments become an array
+named by <tt>:names</tt>:
+
+    builder.add_choice(:names) { | command_line |
+      command_line.uses_arglist
+    }
+
+= Using choices
+
+Most often, choices are used within the context of a Command object. They are stored in a hash named by instance variable <tt>@user_choices</tt> (or accessor +user_choices+).
+
+  class AffinityTripCommand < Command
+    ...
+    def execute
+      starting_url = @strategy.url_for(self.user_choices[:isbn])
+      take_trip(starting_url, self.user_choices[:trip_steps])
+    end
+
+You can construct the hash directly with ChoicesBuilder#build. That's
+not needed or used when using the Command object.
+
+=end
+
+module UserChoices
+end
+

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

@@ -0,0 +1,179 @@
+#!/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