qoobaa-user-choices 1.1.7

data/lib/user-choices/builder.rb

@@ -0,0 +1,118 @@
+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
+
+    # Add a single line composed of _string_ to the current position in the
+    # help output.
+    def add_help_line(string)
+      user_claims(@command_line_source) {
+        "Can't use 'add_help_string' when there's no command line source."
+      }
+      @command_line_source.add_help_line(string)
+    end
+
+    # Demarcate a section of help text. It begins with the _description_,
+    # ends with a dashed line.
+    def section(description)
+      add_help_line("... " + description + ":")
+      yield
+      add_help_line("---------------------------------")
+      add_help_line('')
+    end
+
+    # In groups of related commands, there are often choices that apply to
+    # all commands and choices that apply only to this particular command.
+    # Use this to define the latter.
+    def section_specific_to_script
+      section("specific to this script") do
+        yield
+      end
+    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

data/lib/user-choices/command-line-source.rb

@@ -0,0 +1,224 @@
+require 'optparse'
+require 's4t-utils'
+require 'user-choices/sources.rb'
+require 'user-choices/arglist-strategies'
+include S4tUtils
+
+module UserChoices # :nodoc
+
+  # Treat the command line (including the arguments) as a source
+  # of choices.
+  class CommandLineSource < AbstractSource
+
+    def initialize
+      super
+      @parser = OptionParser.new
+      @arglist_handler = NoArguments.new(self)
+    end
+
+    def source     # :nodoc:
+      "the command line"
+    end
+
+    # The _usage_lines_ will be used to produce the output from
+    # --help (or on error).
+    def usage(*usage_lines)
+      help_banner(*usage_lines)
+      self
+    end
+
+    # Called in the case of command-line error or explicit request (--help)
+    # to print usage information.
+    def help
+      $stderr.puts @parser
+      exit
+    end
+
+    # What we can parse out of the command line
+
+    # Describes how a particular _choice_ is represented on the
+    # command line. The _args_ are passed to OptionParser. Each arg
+    # will either describe one variant of option (such as <tt>"-s"</tt>
+    # or <tt>"--show VALUE"</tt>) or is a line of help text about
+    # the option (multiple lines are allowed).
+    #
+    # If the option takes an array of values, separate the values by commas:
+    # --files a,b,c
+    # There's currently no way to escape a comma and no cleverness about
+    # quotes.
+    def uses_option(choice, *args)
+      external_names[choice] = '--' + extract_switch_raw_name(args)
+      @parser.on(*args) do | value |
+        self[choice] = value
+      end
+    end
+
+    # A switch is an option that doesn't take a value. A switch
+    # described as <tt>"--switch"</tt> has these effects:
+    # * If it is not given, the _choice_ is the default value
+    #   or is not present in the hash that holds all the choices.
+    # * If it is given as <tt>--switch</tt>, the _choice_ has the
+    #   value <tt>"true"</tt>. (If the _choice_ was described in
+    #   ChoicesBuilder#add_choice as having a <tt>:type => :boolean</tt>,
+    #   that value is converted from a string to +true+.)
+    # * If it is given as <tt>--no-switch</tt>, the _choice_ has the
+    #   value <tt>"false"</tt>.
+    def uses_switch(choice, *args)
+      external_name = extract_switch_raw_name(args)
+      external_names[choice] = '--' + external_name
+      args = change_name_to_switch(external_name, args)
+      @parser.on(*args) do | value |
+        self[choice] = value.to_s
+      end
+    end
+
+    # Bundle up all non-option and non-switch arguments into an
+    # array of strings indexed by _choice_.
+    def uses_arglist(choice)
+      use_strategy(choice, ArbitraryArglist)
+    end
+
+    # The single argument required argument is turned into
+    # a string indexed by _choice_. Any other case is an error.
+    def uses_arg(choice)
+      use_strategy(choice, OneRequiredArg)
+    end
+
+    # If a single argument is present, it (as a string) is the value of
+    # _choice_. If no argument is present, _choice_ has no value.
+    # Any other case is an error.
+    def uses_optional_arg(choice)
+      use_strategy(choice, OneOptionalArg)
+    end
+
+    # Add a single line composed of _string_ to the current position in the
+    # help output.
+    def add_help_line(string)
+      @parser.separator(string)
+    end
+
+
+    # Public for testing.
+
+    def fill # :nodoc:
+      exit_upon_error do
+        remainder = @parser.parse(ARGV)
+        @arglist_handler.fill(remainder)
+      end
+    end
+
+    def apply(all_choice_conversions) # :nodoc:
+      safely_modifiable_conversions = deep_copy(all_choice_conversions)
+      @arglist_handler.claim_conversions(safely_modifiable_conversions)
+
+      exit_upon_error do
+        @arglist_handler.apply_claimed_conversions
+        super(safely_modifiable_conversions)
+      end
+    end
+
+    def adjust(all_choices) # :nodoc:
+      exit_upon_error do
+        @arglist_handler.adjust(all_choices)
+      end
+    end
+
+    def help_banner(banner, *more)    # :nodoc:
+      @parser.banner = banner
+      more.each do | line |
+        add_help_line(line)
+      end
+
+      add_help_line ''
+      add_help_line 'Options:'
+
+      @parser.on_tail("-?", "-h", "--help", "Show this message.") do
+        help
+      end
+    end
+
+    def deep_copy(conversions) # :nodoc:
+      copy = conversions.dup
+      copy.each do |k, v|
+        copy[k] = v.collect { |conversion| conversion.dup }
+      end
+    end
+
+    def use_strategy(choice, strategy) # :nodoc:
+      # The argument list choice probably does not need a name.
+      # (Currently, the name is unused.) But I'll give it one, just
+      # in case, and for debugging.
+      external_names[choice] = "the argument list"
+      @arglist_handler = strategy.new(self, choice)
+    end
+
+
+    def exit_upon_error # :nodoc:
+      begin
+        yield
+      rescue SystemExit
+        raise
+      rescue Exception => ex
+        message = if ex.message.has_exact_prefix?(error_prefix)
+                    ex.message
+                  else
+                    error_prefix + ex.message
+                  end
+        $stderr.puts(message)
+        help
+      end
+    end
+
+
+
+    private
+
+    def extract_switch_raw_name(option_descriptions)
+      option_descriptions.each do | desc |
+        break $1 if /^--([\w-]+)/ =~ desc
+      end
+    end
+
+    def change_name_to_switch(name, option_descriptions)
+      option_descriptions.collect do | desc |
+        /^--/ =~ desc ? "--[no-]#{name}" : desc
+      end
+    end
+  end
+
+
+  # Process command-line choices according to POSIX rules. Consider
+  #
+  # ruby copy.rb file1 --odd-file-name
+  #
+  # Ordinarily, that's permuted so that --odd-file-name is expected to
+  # be an option or switch, not an argument. One way to make
+  # CommandLineSource parsing treat it as an argument is to use a -- to
+  # signal the end of option parsing:
+  #
+  # ruby copy.rb -- file1 --odd-file-name
+  #
+  # Another is to rely on the user to set environment variable
+  # POSIXLY_CORRECT.
+  #
+  # Since both of those require the user to do something, they're error-prone.
+  #
+  # Another way is to use this class, which obeys POSIX-standard rules. Under
+  # those rules, the first word on the command line that does not begin with
+  # a dash marks the end of all options. In that case, the first command line
+  # above would parse into two arguments and no options.
+  class PosixCommandLineSource < CommandLineSource
+    def fill
+      begin
+        already_set = ENV.include?('POSIXLY_CORRECT')
+        ENV['POSIXLY_CORRECT'] = 'true' unless already_set
+        super
+      ensure
+        ENV.delete('POSIXLY_CORRECT') unless already_set
+      end
+    end
+  end
+end
+
+
+

data/lib/user-choices/command.rb

@@ -0,0 +1,42 @@
+module UserChoices
+
+  # A template class. Subclasses describe all the choices a user may
+  # make to affect the execution of the command, and the sources for
+  # those choices (such as the command line).
+  class Command
+
+    attr_reader :user_choices
+
+    def initialize
+      builder = ChoicesBuilder.new
+      add_sources(builder)
+      add_choices(builder)
+      @user_choices = builder.build
+      postprocess_user_choices
+    end
+
+    # Add sources such as EnvironmentSource, XmlConfigFileSource,
+    # and CommandLineSource to the ChoicesBuilder.
+    #
+    # Must be defined in a subclass.
+    def add_sources(builder); subclass_responsibility; end
+
+    # Add choices to the ChoicesBuilder. A choice is a symbol that ends up in the
+    # @user_choices hash. It may have a :default value and a :type, as well
+    # as an OptionParser-style description of command-line arguments.
+    #
+    # Must be defined in a subclass.
+    def add_choices(builder); subclass_responsibility; end
+
+    # After choices from all sources are collected into @user_choices, this
+    # method is called to do any postprocessing. Does nothing unless
+    # overridden.
+    def postprocess_user_choices
+    end
+
+    # Execute the command, using @user_choices for parameterization.
+    #
+    # Must be defined in a subclass.
+    def execute; subclass_responsibility; end
+  end
+end

data/lib/user-choices/conversions.rb

@@ -0,0 +1,169 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-06.
+#  Copyright (c) 2007. All rights reserved.
+
+module UserChoices
+  class Conversion # :nodoc:
+    @@subclasses = []
+    def self.inherited(subclass)
+      @@subclasses << subclass
+    end
+
+    def self.is_abstract
+      @@subclasses.delete(self)
+    end
+
+    def self.record_for(conversion_tag, recorder)
+      return if conversion_tag.nil?   # This simplifies caller.
+      recorder << self.for(conversion_tag)
+    end
+
+    def self.for(conversion_tag)
+      subclass = @@subclasses.find { |sc| sc.described_by?(conversion_tag) }
+      user_claims(subclass) { "#{conversion_tag} doesn't describe any Conversion object." }
+      subclass.new(conversion_tag)
+    end
+
+    def initialize(conversion_tag)
+      @conversion_tag = conversion_tag
+    end
+
+    def self.described_by?(conversion_tag); subclass_responsibility; end
+    def suitable?(actual); subclass_responsibility; end
+    def description; subclass_responsibility; end
+
+    def convert(value); value; end  # Some conversions are just for error-checking
+    def does_length_check?; false; end
+  end
+
+  class NoOpConversion < Conversion # :nodoc:
+    def self.described_by?(conversion_tag)
+      conversion_tag == :string
+    end
+
+    def description; "a string"; end
+    def suitable?(actual); true; end
+    def convert(value); value; end
+  end
+
+
+  class ConversionToInteger < Conversion # :nodoc:
+    def self.described_by?(conversion_tag)
+      conversion_tag == :integer
+    end
+
+    def description; "an integer"; end
+
+    def suitable?(actual)
+      return true if actual.is_a?(Integer)
+      actual.is_a?(String) and /^\d+$/ =~ actual # String check for better error message.
+     end
+
+    def convert(value); value.to_i; end
+  end
+
+  class ConversionToBoolean < Conversion # :nodoc:
+    def self.described_by?(conversion_tag)
+      conversion_tag == :boolean
+    end
+
+    def description; "a boolean"; end
+
+    def suitable?(actual)
+      return true if [true, false].include?(actual)
+      return false unless actual.is_a?(String)
+      ['true', 'false'].include?(actual.downcase)
+    end
+
+    def convert(value)
+      case value
+      when String
+        eval(value.downcase)
+      else
+        value
+      end
+    end
+  end
+
+  class SplittingConversion < Conversion # :nodoc:
+    def self.described_by?(conversion_tag)
+      conversion_tag == [:string]
+    end
+
+    def description; "a comma-separated list"; end
+
+    def suitable?(actual)
+      actual.is_a?(String) || actual.is_a?(Array)
+    end
+
+    def convert(value)
+      case value
+      when String
+        value.split(',')
+      when Array
+        value
+      end
+    end
+
+  end
+
+  class LengthConversion < Conversion # :nodoc:
+    is_abstract
+
+    attr_reader :required_length
+    def initialize(conversion_tag)
+      super
+      @required_length = conversion_tag[:length]
+    end
+
+    def self.described_by?(conversion_tag, value_class)
+      conversion_tag.is_a?(Hash) && conversion_tag[:length].is_a?(value_class)
+    end
+
+    def suitable?(actual)
+      actual.respond_to?(:length) && yield
+    end
+
+    def does_length_check?; true; end
+
+  end
+
+  class ExactLengthConversion < LengthConversion # :nodoc:
+    def self.described_by?(conversion_tag)
+      super(conversion_tag, Integer)
+    end
+
+    def description; "of length #{@required_length}"; end
+
+    def suitable?(actual)
+      super(actual) { actual.length == @required_length }
+    end
+  end
+
+  class RangeLengthConversion < LengthConversion # :nodoc:
+    def self.described_by?(conversion_tag)
+      super(conversion_tag, Range)
+    end
+
+    def description; "a list whose length is in this range: #{@required_length}"; end
+
+    def suitable?(actual)
+      super(actual) { @required_length.include?(actual.length) }
+    end
+  end
+
+  # Note: since some of the above classes are described_by? methods that
+  # respond_to :include, this class should be last, so that it's checked
+  # last.
+  class ChoiceCheckingConversion < Conversion  # :nodoc:
+    def self.described_by?(conversion_tag)
+      conversion_tag.respond_to?(:include?)
+    end
+
+    def suitable?(actual); @conversion_tag.include?(actual); end
+    def description; "one of #{friendly_list('or', @conversion_tag)}"; end
+  end
+end
+
+