user-choices 1.1.0

data/History.txt

@@ -0,0 +1,17 @@
+Version 1.1.0
+  * Handles YAML files as well as XML.
+  * Minor, incompatible changes to the API.
+  * Command-line arglist handling now works with other sources the
+    way options do. In particular, an empty arglist can, for example, 
+    have its value given by defaults rather than locking the value
+    of the choice down to the empty array.
+  * Command-line arglists used to have their length specified independently
+    of all other sources. Now there's a :length "type" that applies to all
+    sources, including the command line. From the user's point of view,     
+    though, wrong-sized arglists look like they're caught by OptionParser.
+  * These relatively minor changes required a bigger overhaul to the 
+    internals. They're less stupid, but I suspect they're still stupid.
+  * A tutorial.
+ 
+Version 1.0.0
+  * Version from _Everyday Scripting with Ruby_

data/LICENSE.txt

@@ -0,0 +1,34 @@
+This software is Copyright (C) 2007 by Brian Marick <marick@exampler.com>. It is licensed according to "the Ruby license". Specifically:
+
+You can redistribute it and/or modify it under either the terms of the GNU General Public License, version 2, <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html> or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+          modifications to Usenet or an equivalent medium, or by allowing
+          the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) make other distribution arrangements with the author.
+
+  3. You may modify and include part of the software into any other
+     software (possibly commercial).  
+
+  4. Text or files supplied as input to or produced as output from 
+     the software do not automatically fall under the copyright of the
+     software, but belong to whomever generated them, and may be sold
+     commercially, and may be aggregated with this software.
+
+  5. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/Manifest.txt

@@ -0,0 +1,40 @@
+History.txt
+LICENSE.txt
+Manifest.txt
+README.txt
+Rakefile
+Rakefile.hoe
+examples/older/README.txt
+examples/older/command-line.rb
+examples/older/default-values.rb
+examples/older/multiple-sources.rb
+examples/older/postprocess.rb
+examples/older/switches.rb
+examples/older/two-args.rb
+examples/older/types.rb
+examples/tutorial/index.html
+examples/tutorial/tutorial1.rb
+examples/tutorial/tutorial2.rb
+examples/tutorial/tutorial3.rb
+examples/tutorial/tutorial4.rb
+examples/tutorial/tutorial5.rb
+examples/tutorial/tutorial6.rb
+examples/tutorial/tutorial7.rb
+lib/user-choices.rb
+lib/user-choices/arglist-strategies.rb
+lib/user-choices/builder.rb
+lib/user-choices/command-line-source.rb
+lib/user-choices/command.rb
+lib/user-choices/conversions.rb
+lib/user-choices/ruby-extensions.rb
+lib/user-choices/sources.rb
+lib/user-choices/version.rb
+setup.rb
+test/arglist-strategy-tests.rb
+test/builder-tests.rb
+test/command-line-source-tests.rb
+test/conversion-tests.rb
+test/set-standalone-test-paths.rb
+test/source-tests.rb
+test/user-choices-slowtests.rb
+user-choices.tmproj

data/README.txt

@@ -0,0 +1 @@
+The best introduction to user-choices is the tutorial[http://user-choices.rubyforge.org].

data/Rakefile

@@ -0,0 +1,19 @@
+# This is a Makefile that would live in the root folder for a package
+# that follows the Scripting for Testers conventions.
+
+$started_from_rakefile = true
+
+PACKAGE_ROOT = Dir.pwd
+$:.unshift("#{PACKAGE_ROOT}/lib")
+require 's4t-utils/load-path-auto-adjuster'
+
+require 's4t-utils'
+include S4tUtils
+
+MyFileSystemName='user-choices'  # No ".rb" extension.
+MyModuleName='UserChoices'
+MyRdocFiles = FileList.new("lib/#{MyFileSystemName}.rb",
+                           "lib/#{MyFileSystemName}/**/*.rb").exclude('**/third-party/**')
+
+require 's4t-utils/rakefile-common'
+

data/Rakefile.hoe

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-03.
+#  Copyright (c) 2007. All rights reserved.
+
+require 'hoe'
+require 'lib/user-choices/version'
+
+Hoe.new("user-choices", UserChoices::Version) do |p|
+  p.rubyforge_name = "user-choices"
+  p.changes = "See History.txt"
+  p.author = "Brian Marick"
+  p.description = "Unified interface to command-line, environment, and configuration files."
+  p.summary = p.description
+  p.email = "marick@exampler.com"
+  p.extra_deps = [['xmp-simple', '>= 1.0.11'], 
+                  ['s4t-utils', '>= 1.0.2'],
+                  ['extensions', '>= 0.6.0'],    # for testing
+                  ['builder' '>= 2.1.2']]        # for testing
+  p.test_globs = "test/**/*-tests.rb"
+  p.rdoc_pattern = %r{README.txt|History.txt|lib/user-choices.rb|lib/user-choices/.+\.rb}
+  p.url = "http://user-choices.rubyforge.org"
+  p.remote_rdoc_dir = 'rdoc'
+end

data/examples/older/README.txt

@@ -0,0 +1,133 @@
+Here are brief instructions for using the different scripts in this directory. The tutorial files aren't described here; instead, the tutorial (on the website) describes them. 
+
+
+		      == Command-line arguments ==
+
++ Help is generated for you:
+
+prompt> ruby command-line.rb --help
+
++ Options are placed into a hash, as is the argument list
+
+prompt> ruby command-line.rb --choice cho sophie paul dawn me
+
++ The usual variant ways of specifying options
+
+prompt> ruby command-line.rb -c choice
+prompt> ruby command-line.rb -cchoice
+prompt> ruby command-line.rb --choi choice
+prompt> ruby command-line.rb --choi choice -- -name1- -name2-
+
++ There are error messages for extra and malformed options
+
+prompt> ruby command-line.rb --choice
+prompt> ruby command-line.rb --other 3 -- choice
+
+			 == Default values ==
+
++ You can specify default values when you define choices.
+
+prompt> ruby default-values.rb --choice specific
+prompt> ruby default-values.rb
+
++ Note: defaulting behavior applies to other sources of choices, not
+   just command lines.
+
+		       == Optional arguments ==
+
++ When single optional arguments are required, the result is not a
+  list - it's either the value or nothing. 
+
+prompt> ruby default-values.rb only-arg
+
+== Type checks and conversions
+
++ There are ways to describe what kind of thing an argument
+   is. (Currently limited.)
+
+prompt> ruby types.rb --a-or-b not-a  argument
+prompt> ruby types.rb --must-be-integer 1d argument
+prompt> ruby types.rb --option-list first,second argument
+
++ Integer-valued options are converted into integers, not left as
+   strings:
+
+prompt> ruby types.rb --must-be-integer 3 argument
+
++ Type-checking and type conversions apply to all sources, not just
+   command lines. 
+
+		       == Required Arguments ==
+
++ You can require exactly one argument:
+
+prompt> ruby types.rb
+prompt> ruby types.rb argument extra-argument
+
+	      == Switches (values without arguments) ==
+
++ Switches can also be specified.  Typically, their values are either
+   true or false (rather than strings or numbers). 
+
++ How they are given on the command line may be unfamiliar to you:
+
+prompt> ruby switches.rb --help
+
++ Examples of use:
+
+prompt> ruby switches.rb 1 2
+prompt> ruby switches.rb --switch 1 2
+prompt> ruby switches.rb -s 2 1 
+prompt> ruby switches.rb --no-switch 1 2
+
+== A range of arguments == 
+
++ You can require that the number of arguments be in a range. In this
+   case, it's 2-4:
+
+prompt> ruby switches.rb 1 
+prompt> ruby switches.rb 1  2 
+prompt> ruby switches.rb 1  2  3 4
+prompt> ruby switches.rb 1  2  3 4 5
+
++ You can also require any particular exact number of arguments:
+
+prompt> ruby two-args.rb 1
+prompt> ruby two-args.rb 1 2 
+prompt> ruby two-args.rb 1 2 3 
+
+			 == Postprocessing ==
+
++ You can also postprocess choices into a form more convenient for the
+  rest of the program.
+
+prompt> ruby postprocess.rb 1 2
+
+			== Multiple Sources ==
+
++ First see what happens when no arguments are given.
+
+prompt> ruby command-line.rb
+
++ Create a file named ms-config.xml in your home / login folder, and
+  put the following in it. (Note the underscore in "ordinary_choice" -
+  this is the name of the choice, not the representation of that choice
+  on the command line.)
+
+       <config>
+         <ordinary_choice>greetings</ordinary_choice>
+       </config>
+
+prompt> ruby multiple-sources.rb 
+
+Set an environment variable ms_ordinary_choice with value 'hi'. 
+
+prompt> ruby multiple-sources.rb
+
+Which takes precedence, the environment or the configuration file?
+(This is configurable.) 
+
+The command line arguments have highest precedence of all:
+
+prompt> ruby multiple-sources.rb --ordinary-choice hello
+

data/examples/older/command-line.rb

@@ -0,0 +1,51 @@
+### 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 CommandLineExample < UserChoices::Command
+
+  # The _sources_ are the various places in which the user can
+  # describe her choices to the program. In this case, there's
+  # only the command line. 
+
+  def add_sources(builder)
+    builder.add_source(UserChoices::CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] names...")
+  end
+
+  # Each individual choice is named with a symbol. The block
+  # describes the command line options corresponding to the choice, plus
+  # any help text for that option. The arguments to uses_options are passed
+  # on to OptionParser. 
+
+  def add_choices(builder)
+    builder.add_choice(:choice) { | command_line |
+      command_line.uses_option("-c", "--choice CHOICE",
+                               "CHOICE can be any string.")
+    }
+
+    # The argument list to the command is interpreted as another
+    # option. In this case, it's a list of strings.
+    builder.add_choice(:names) { | command_line |
+      command_line.uses_arglist
+    }
+  end
+
+  # Perform the command.
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    CommandLineExample.new.execute
+  end
+end

data/examples/older/default-values.rb

@@ -0,0 +1,47 @@
+### 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 ArgNotingCommand < UserChoices::Command
+
+  def add_sources(builder)
+    builder.add_source(UserChoices::CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] [name]")
+  end
+
+  def add_choices(builder)
+    # This example shows how you can specify a default value for an
+    # option.
+    builder.add_choice(:choice,
+                       :default => 'default') { | command_line |
+      command_line.uses_option("-c", "--choice CHOICE",
+                               "CHOICE can be any string.")
+    }
+
+    # uses_optional_arg allows either zero or one arguments. If an
+    # argument is given, it is directly the value of user_choices[key]
+    # (rather than being stored as a single-element array).
+    builder.add_choice(:name) { | command_line |
+      command_line.uses_optional_arg
+    }
+  end
+
+  # Perform the command.
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    ArgNotingCommand.new.execute
+  end
+end

data/examples/older/multiple-sources.rb

@@ -0,0 +1,63 @@
+### 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 MultipleSourcesExample < UserChoices::Command
+  include UserChoices
+
+  # Here are the four sources currently available. 
+  #
+  # EnvironmentSource is initialized with a prefix. If a choice is
+  # named "foo" and the prefix is "ms_", then the value of
+  # ENV["ms_foo"] initializes user_choices[:foo].
+  #
+  # YamlConfigFileSource reads from a given YAML file. The choices in the
+  # config file have the same spelling as the choice name (without the
+  # colon that makes the choice name a symbol).
+  #
+  # XmlConfigFileSource reads from a given XML file. The choices in the
+  # config file have the same spelling as the choice name (without the
+  # colon that makes the choice name a symbol).
+  #
+  # CommandLineSource uses the command line (including the argument list). 
+  # Much of the initialization is done with a block attached to add_choice. 
+  #
+  # Sources are added in descending order of precedence.
+
+  def add_sources(builder)
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] names...")
+    builder.add_source(EnvironmentSource, :with_prefix, "ms_")
+    builder.add_source(YamlConfigFileSource, :from_file, "ms-config.yml")
+    builder.add_source(XmlConfigFileSource, :from_file, "ms-config.xml")
+  end
+
+  def add_choices(builder)
+    builder.add_choice(:ordinary_choice,
+                       :default => 'default') { | command_line |
+      command_line.uses_option("-o", "--ordinary-choice CHOICE",
+                               "CHOICE can be any string.")
+    }
+
+    builder.add_choice(:names) { | command_line |
+      command_line.uses_arglist
+    }
+  end
+
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    MultipleSourcesExample.new.execute
+  end
+end

data/examples/older/postprocess.rb

@@ -0,0 +1,45 @@
+### 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 ArgNotingCommand < UserChoices::Command
+
+  def add_sources(builder)
+    builder.add_source(UserChoices::CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] infile outfile")
+    
+  end
+
+  def add_choices(builder)
+    builder.add_choice(:args, :length => 2) { | command_line |
+      command_line.uses_arglist
+    }
+  end
+
+  # postprocess_user_choices gives the program the opportunity to
+  # do something about choices immediately after they are made. This method
+  # runs only once per invocation, whereas the execute() method can 
+  # execute several times. This method will often set instance variables. 
+  def postprocess_user_choices
+    @user_choices[:infile] = @user_choices[:args][0]
+    @user_choices[:outfile] = @user_choices[:args][1]
+  end
+
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    ArgNotingCommand.new.execute
+  end
+end

data/examples/older/switches.rb

@@ -0,0 +1,50 @@
+### 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 SwitchExample < UserChoices::Command
+
+  def add_sources(builder)
+    builder.add_source(UserChoices::CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] args...",
+                       "There may be 2-4 arguments.")
+    
+  end
+
+  # Switches are slightly different than options. (The difference is
+  # in how they're invoked, as either --switch or --no-switch.) Almost
+  # certainly, you want the switch to be of type :boolean and have a
+  # default.
+  def add_choices(builder)
+    builder.add_choice(:switch,
+                       :default => false,
+                       :type => :boolean) { | command_line |
+      command_line.uses_switch("--switch", "-s")
+    }
+
+    # You control the allowable length of a choice with the :length
+    # keyword argument. It applies to command-line arglists, lists given
+    # in configuration files, and the like.
+    builder.add_choice(:args, :length => 2..4) { | command_line |
+      command_line.uses_arglist
+    }
+  end
+
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    SwitchExample.new.execute
+  end
+end

data/examples/older/two-args.rb

@@ -0,0 +1,37 @@
+### 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 TwoArgExample < UserChoices::Command
+
+  def add_sources(builder)
+    builder.add_source(UserChoices::CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] infile outfile")
+    
+  end
+
+  def add_choices(builder)
+    # You can specify an exact number of array elements required.
+    builder.add_choice(:args, :length => 2) { | command_line |
+      command_line.uses_arglist
+    }
+  end
+
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    TwoArgExample.new.execute
+  end
+end

data/examples/older/types.rb

@@ -0,0 +1,67 @@
+### 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'
+include UserChoices
+
+class TypesExample < Command
+
+  def add_sources(builder)
+    builder.add_source(CommandLineSource, :usage,
+                       "Usage: ruby #{$0} [options] arg")
+  end
+
+  def add_choices(builder)
+    # This is how you restrict an option argument to one of a list of
+    # strings.
+    builder.add_choice(:a_or_b,
+                       :type => ['a', 'b']) { | command_line |
+      command_line.uses_option("--a-or-b CHOICE",
+                               "CHOICE is either 'a' or 'b'")
+    }
+
+    # This is how you insist that an option argument be an integer
+    # (in string form). If correctly formatted, the string is turned
+    # into an integer. Note that the default value can be either a 
+    # string or an integer.
+    builder.add_choice(:must_be_integer,
+                       :default => 0,
+                       :type => :integer) { | command_line |
+      command_line.uses_option("--must-be-integer INT")
+    }
+
+    # This is how to tell the builder that the argument is a
+    # comma-separated list of options. The declaration is not required
+    # for command lines, or lists in a configuration file. Those are
+    # already broken out into their constituent elements in the source
+    # text, so the builder doesn't have to split a string at comma
+    # boundaries. You can declare the type if you want, though.
+    
+    builder.add_choice(:option_list, :type => [:string], :length => 2) { | command_line |
+      command_line.uses_option("--option-list OPT,OPT",
+                               "Comma-separated list of exactly two options.")
+    }
+                       
+
+    builder.add_choice(:arg) { | command_line |
+      command_line.uses_arg
+    }
+  end
+
+  def execute
+    pp @user_choices
+  end
+end
+
+
+if $0 == __FILE__
+  S4tUtils.with_pleasant_exceptions do
+    TypesExample.new.execute
+  end
+end