qoobaa-user-choices 1.1.7

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,39 @@
+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/README.rdoc

@@ -0,0 +1,7 @@
+= user-choices
+
+Description goes here.
+
+== Copyright
+
+Copyright (c) 2009 Jakub. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "user-choices"
+    gem.summary = %Q{Unified interface to command-line, environment, and configuration files.}
+    gem.email = "marick@exampler.com"
+    gem.homepage = "http://github.com/qoobaa/user-choices"
+    gem.authors = ["Brian Marick"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "user-choices #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+1.1.7

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,46 @@
+#!/usr/bin/env ruby
+
+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,41 @@
+#!/usr/bin/env ruby
+
+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,58 @@
+#!/usr/bin/env ruby
+
+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,39 @@
+#!/usr/bin/env ruby
+
+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