class UserChoices::ChoicesBuilder

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.

Public Instance Methods

add_choice(choice, args={}, &block) click to toggle source

Add the choice named choice, a symbol. args is a keyword argument:

:default takes a value that is the default value of the choice.
:type can be given an array of valid string values. These are checked.
:type can also be given :integer. The value is cast into an integer. If that’s impossible, an exception is raised.
:type can also be given :boolean. The value is converted into true or false (or an exception is raised).
:type can also be given [:string]. The value will be an array of strings. For example, “–value a,b,c” will produce [‘a’, ‘b’, ‘c’].

You might also give :length => 5 or :length => 3..4. (In this case, a :type of [:string] is assumed.)

The block is passed a CommandLineSource object. It’s used to describe the command line.

# File lib/user-choices/builder.rb, line 39
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

add_help_line(string) click to toggle source

Add a single line composed of string to the current position in the help output.

# File lib/user-choices/builder.rb, line 62
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

add_source(source_class, *messages_and_args) click to toggle source

This adds a source of choices. The source is a class like CommandLineSource. The messages_and_args are sent to a new object of that class.

# File lib/user-choices/builder.rb, line 53
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

build() click to toggle source

Once sources and choices have been described, this builds and returns a hash-like object indexed by the choices.

# File lib/user-choices/builder.rb, line 91
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

section(description) { || ... } click to toggle source

Demarcate a section of help text. It begins with the description, ends with a dashed line.

# File lib/user-choices/builder.rb, line 71
def section(description)
  add_help_line("... " + description + ":")
  yield
  add_help_line("---------------------------------")
  add_help_line('')
end

section_specific_to_script() { || ... } click to toggle source

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.

# File lib/user-choices/builder.rb, line 81
def section_specific_to_script
  section("specific to this script") do
    yield
  end
end

Public Class Methods

new() click to toggle source

# File lib/user-choices/builder.rb, line 15
def initialize
  @defaults = {}
  @conversions = {}
  @sources = []
end