user-choices 1.1.0

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

@@ -0,0 +1,220 @@
+require 'optparse'
+require 's4t-utils'
+require 'user-choices/sources.rb'
+require 'user-choices/arglist-strategies'
+include S4tUtils
+require 'extensions/string'
+
+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
+
+
+
+
+    # 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 |
+        @parser.separator(line)
+      end
+      @parser.separator ''
+      @parser.separator '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.starts_with?(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,154 @@
+#!/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 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
+
+

data/lib/user-choices/ruby-extensions.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-08-10.
+#  Copyright (c) 2007. All rights reserved.
+
+
+class Range # :nodoc:
+  def in_words
+    last_element = self.last
+    last_element -= 1 if exclude_end?
+    "#{self.first} to #{last_element}"
+  end
+end
+
+class String # :nodoc:
+  def to_inputable_sym
+    gsub(/-/, '_').to_sym
+  end
+end
+

data/lib/user-choices/sources.rb

@@ -0,0 +1,269 @@
+require 'xmlsimple'
+require 'yaml'
+require 's4t-utils'
+include S4tUtils
+
+require 'user-choices/ruby-extensions'
+require 'user-choices/conversions'
+
+
+module UserChoices   # :nodoc
+
+
+  # TODO: Right now, elements that are named in a source, but not in an 
+  # add_choice() call, nevertheless appear in the final array. Is that good? 
+  # Bad? Irrelevant?
+  class AbstractSource < Hash # :nodoc:
+    
+    attr_reader :external_names
+
+    def initialize
+      super()
+      @external_names = {}
+    end
+
+    def source; subclass_responsibility; end
+
+    
+    def fill; subclass_responsibility; end
+    
+    def apply(choice_conversions)
+      each_conversion(choice_conversions) do | choice, conversion |
+        next unless self.has_key?(choice)
+        
+        user_claims(conversion.suitable?(self[choice])) {
+          error_prefix + bad_look(choice, conversion)
+        }
+        
+        self[choice] = conversion.convert(self[choice])
+      end
+    end
+
+    def adjust(final_results)
+      # Do nothing
+    end
+    
+    def each_conversion(choice_conversion_hash)
+      choice_conversion_hash.each do | choice, conversion_list | 
+        conversion_list.each do | conversion |
+          yield(choice, conversion)
+        end
+      end
+    end
+
+
+    protected
+
+    def error_prefix
+      "Error in #{source}: "
+    end
+    
+    def pretty_value(value)
+      case value
+      when Array: value.inspect
+      else "'#{value}'"
+      end
+    end
+
+    def bad_look(key, conversion)
+      like_what = conversion.description
+      "#{@external_names[key]}'s value must be #{like_what}, and #{pretty_value(self[key])} doesn't look right."
+    end
+
+  end
+
+  class DefaultSource < AbstractSource   # :nodoc:
+    
+    def use_hash(defaults)
+      @defaults = defaults
+      count_symbols_as_external_names(@defaults.keys)
+      self
+    end
+    
+    def fill
+      merge!(@defaults)
+    end
+
+    def source
+      "the default values"
+    end
+
+    def count_symbols_as_external_names(symbols)
+      symbols.each { | symbol |
+        # Use inspect so that symbol prints with leading colon
+        @external_names[symbol] = symbol.inspect
+      }
+    end
+  end
+  DefaultChoices = DefaultSource   # Backward compatibility
+
+
+  
+  # Describe the environment as a source of choices. 
+  class EnvironmentSource < AbstractSource
+    def fill    # :nodoc:
+      @external_names.each { | key, env_var |
+        self[key] = ENV[env_var] if ENV.has_key?(env_var)
+      }
+    end
+
+    # Environment variables beginning with _prefix_ (a string)
+    # are considered to be user choices relevant to this script.
+    # Everything after the prefix names a choice (that is, a symbol).
+    # Dashes are converted to underscores. Examples:
+    # * Environment variable <tt>prefix-my-choice</tt> with prefix <tt>"prefix-" is choice <tt>:my_choice</tt>.
+    # * Environment variable <tt>PREFIX_FOO</tt> with prefix <tt>"PREFIX_" is choice <tt>:FOO</tt>
+    #
+    # If you want an array of strings, separate the values by commas:
+    # ENV_VAR=a,b,c
+    # There's currently no way to escape a comma and no cleverness about
+    # quotes or whitespace.
+    
+    def with_prefix(prefix)
+      matches = ENV.collect do | env_var, ignored_value |
+        if /^#{prefix}(.+)/ =~ env_var
+          [$1.to_inputable_sym, env_var]
+        end
+      end
+      @external_names.merge!(Hash[*matches.compact.flatten])
+      self
+    end
+  
+    # Some environment variables have names you don't like. For example, $HOME
+    # might be annoying because of the uppercase. Also, if most of your program's 
+    # environment variables have some prefix (see with_prefix) but you also want to use
+    # $HOME, you need a way to do that. You can satisfy both desires with 
+    #
+    #      EnvironmentSource.new.with_prefix("my_").mapping(:home => "HOME")
+  
+    def mapping(map)
+      @external_names.merge!(map)
+      self
+    end
+      
+
+    def source    # :nodoc:
+      "the environment"
+    end
+  end
+  EnvironmentChoices = EnvironmentSource   # Backward compatibility
+  
+  
+  class FileSource < AbstractSource # :nodoc: 
+
+    def from_file(filename)
+      @path = File.join(S4tUtils.find_home, filename)
+      @contents_as_hash = self.read_into_hash
+      @contents_as_hash.each do | external_name, value |
+        sym = external_name.to_inputable_sym
+        @external_names[sym] = external_name
+      end
+      self
+    end
+
+    def fill    # :nodoc:
+      @external_names.each do | symbol, external_name |
+        self[symbol] = @contents_as_hash[external_name]
+      end
+    end
+
+    def source    # :nodoc:
+      "configuration file #{@path}"
+    end
+
+    def read_into_hash    # :nodoc:
+      return {} unless File.exist?(@path)
+      begin
+        format_specific_reading
+      rescue Exception => ex
+        if format_specific_exception?(ex)
+          msg = "Badly formatted #{source}: " + format_specific_message(ex)
+          ex = ex.class.new(msg)
+        end
+        raise ex
+      end
+    end
+
+    protected 
+    
+    def format_specific_message(ex)
+      ex.message
+    end
+    
+    def format_specific_exception_handling(ex); subclass_responsibility; end
+    def format_specific_reading; subclass_responsibility; end
+  end
+
+  # Use an XML file as a source of choices. The XML file is parsed
+  # with <tt>XmlSimple('ForceArray' => false)</tt>. That means that
+  # single elements like <home>Mars</home> are read as the value
+  # <tt>"Mars"</tt>, whereas <home>Mars</home><home>Venus</home> is
+  # read as <tt>["Mars", "Venus"]</tt>.
+  class XmlConfigFileSource < FileSource
+
+    # Treat _filename_ as the configuration file. _filename_ is expected
+    # to be in the home directory. The home directory is found in the
+    # same way Rubygems finds it. (First look in environment variables
+    # <tt>$HOME</tt>, <tt>$USERPROFILE</tt>, <tt>$HOMEDRIVE:$HOMEPATH</tt>,
+    # file expansion of <tt>"~"</tt> and finally the root.)
+    def format_specific_reading
+      XmlSimple.xml_in(@path, 'ForceArray' => false)
+    end
+    
+    def format_specific_exception?(ex)
+      ex.is_a?(REXML::ParseException)
+    end
+    
+    def format_specific_message(ex)
+      ex.continued_exception
+    end
+      
+  end
+  XmlConfigFileChoices = XmlConfigFileSource   # Backward compatibility
+  
+  
+  
+  
+  # Use an YAML file as a source of choices. Note: because the YAML parser
+  # can produce something out of many typo-filled YAML files, it's a 
+  # good idea to check that your file looks like you'd expect before 
+  # trusting in it. Do that with:
+  #
+  #    irb> require 'yaml'
+  #    irb> YAML.load_file('config.yaml')
+  #    
+  class YamlConfigFileSource < FileSource
+    # Treat _filename_ as the configuration file. _filename_ is expected
+    # to be in the home directory. The home directory is found in the
+    # same way Rubygems finds it. 
+    def format_specific_reading
+      result = YAML.load_file(@path)
+      ensure_hash_values_are_strings(result)
+      result
+    end
+
+    def format_specific_exception?(ex)
+      ex.is_a?(ArgumentError)
+    end
+
+
+
+    def ensure_hash_values_are_strings(h)
+      h.each { |k, v| ensure_element_is_string(h, k) }
+    end
+    
+    def ensure_array_values_are_strings(a)
+      a.each_with_index { |elt, index| ensure_element_is_string(a, index) }
+    end
+
+    def ensure_element_is_string(collection, key)
+      case collection[key]
+        when Hash: ensure_hash_values_are_strings(collection[key])
+        when Array: ensure_array_values_are_strings(collection[key])
+        else collection[key] = collection[key].to_s
+      end
+    end
+      
+    
+  end
+end

data/lib/user-choices/version.rb

@@ -0,0 +1,3 @@
+module UserChoices
+  Version = '1.1.0'
+end