choice 0.1.0

data/CHANGELOG

@@ -0,0 +1,2 @@
+0.1.0:
+  - First release

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2006 Chris Wanstrath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of 
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 
+the Software, and to permit persons to whom the Software is furnished to do so, 
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,347 @@
+= Welcome to Choice
+
+Choice is a small library for defining and parsing command line options.  It 
+works awesomely with Highline[http://highline.rubyforge.org/] or other command 
+line interface libraries.
+
+Choice was written by Chris Wanstrath as an exercise in test driving development 
+of a DSL.  We hope you find it useful.  If you don't, we'd love to hear why.  
+This project is still an infant: bugs are expected and tattling on them is 
+appreciated.  
+
+Installing is easy, with RubyGems.  Give it a shot:
+ $ gem install choice
+
+If you are lost, you can find Choice at http://choice.rubyforge.org or 
+http://rubyforge.org/projects/choice/.  E-mail inquiries can be directed to
+mailto:chris[at]ozmm[dot]org.
+
+Of course, Choice is licensed under the MIT License, which you can find included
+in the LICENSE file or by surfing your World Wide Web browser of choice towards 
+http://www.opensource.org/licenses/mit-license.php.
+
+== Using Choice
+
+An +examples+ directory is included with Choice, in which some contrived Ruby
+programs utilizing the library have been placed.  Here's a snippet:
+
+=== ftpd.rb
+
+  require 'choice'
+
+  PROGRAM_VERSION = 4
+
+  Choice.options do
+    header ''
+    header 'Specific options:'
+  
+    option :host do
+      short '-h'
+      long '--host=HOST'
+      desc 'The hostname or ip of the host to bind to (default 127.0.0.1)'
+      default '127.0.0.1'
+    end
+
+    option :port do
+      short '-p'
+      long '--port=PORT'
+      desc 'The port to listen on (default 21)'
+      cast Integer
+      default 21
+    end
+  
+    separator ''
+    separator 'Common options: '
+
+    option :help do
+      long '--help'
+      desc 'Show this message'
+    end
+
+    option :version do
+      short '-v'
+      long '--version'
+      desc 'Show version'
+      action do
+        puts "ftpd.rb FTP server v#{PROGRAM_VERSION}"
+        exit      
+      end
+    end
+  end
+
+  puts 'port: ' + Choice.choices[:port]
+
+Notice the last line.  For free, you will be given a <tt>Choice.choices</tt> 
+hash which contain, at runtime, the options found and their values.
+
+Because we gave option <tt>:port</tt> a default of 21, 
+<tt>Choice.choices[:port]</tt> should be 21 if we run ftpd.rb with no options.  
+Let's see.
+
+ $ ruby ftpd.rb
+ port: 21
+ 
+Cool.  On our system, port 21 is reserved.  Let's use another port.
+
+ $ ruby ftpd.rb -p 2100
+ port: 2100
+ 
+Alright.  And, of course, there is the hard way of doing things.
+
+ $ ruby ftpd.rb --port=2100
+ port: 2100
+ 
+That <tt>:version</tt> option looks pretty interesting, huh?  I wonder what it 
+does...
+ 
+  $ ruby ftpd.rb -v
+  ftpd.rb FTP server v4
+
+That's not all, though.  We also get a <tt>--help</tt> option for free.  
+
+  $ ruby ftpd.rb --help
+  Usage: ftpd.rb [-hpv]
+
+  Specific options:
+      -h, --host=HOST                  The hostname or ip of the host to bind to (default 127.0.0.1)
+      -p, --port=PORT                  The port to listen on (default 21)
+
+  Common options: 
+          --help                       Show this message
+      -v, --version                    Show version
+      
+      
+== The Choice.choices hash
+
+For better or worse, the <tt>Choice.choices</tt> hash is a bit lazy.  It does 
+not care how you access it.  Using the above example, assume we have a 
+<tt>:port</tt> option and we replace the last line of our program with the 
+following three lines:
+
+  puts 'port: ' + Choice.choices[:port]
+  puts 'port: ' + Choice.choices['port']
+  puts 'port: ' + Choice.choices.port
+
+Now, run it.
+
+  $ ftpd.rb -p 2100
+  port: 2100
+  port: 2100
+  port: 2100
+
+Lazy, huh?
+
+Keep in mind that your option's key in the <tt>Choice.choices</tt> hash is 
+defined by the first parameter passed to option statement.  This is perfectly 
+legit, albeit somewhat confusing:
+
+  option :name do
+    short '-h'
+    long '--handle=NAME'
+    desc "Your handle."
+  end
+
+You can access this option by using <tt>Choice.choices[:name]</tt>, not 
+<tt>:handle</tt>.
+
+== Option options
+
+Obviously, Choice revolves around the <tt>option</tt> statement, which receives
+a block.  Here are all the, er, options +option+ accepts.  None of them are 
+required but +short+ or +long+ must be present for Choice to know what to do.
+
+Options must be defined in the context of a <tt>Choice.options</tt> block, as 
+seen above.  This context is assumed for the following explanations.
+
+For the quick learners, here's the list:
+* short
+* long
+* default
+* desc
+* cast
+* validate (takes regex)
+* filter (takes a block)
+* action (ditto)
+
+You can define these within your option in any order which pleases you.
+
+=== short
+
+Defines the short switch for an option.  Expected to be a dash and a single
+character.
+
+=== long
+
+Defines the long switch for an option.  Expected to be a double dash followed by
+a string, an equal sign, and another string.  No spaces.
+
+There are two variants: longs where a parameter is required and longs where a 
+parameter is optional, in which case the value will be +true+ if the option is
+present.
+
+*Optional*:
+  long '--debug=[LEVEL]'
+
+Assuming our program defines Choices and ends with this line:
+  puts 'debug: ' + Choice.choices[:debug]
+
+we can do this:
+
+  $ ruby ftpd.rb --debug
+  debug: true
+  
+  $ ruby ftpd.rb --debug=1
+  debug: 1
+
+*Required*:
+  long '--debug=LEVEL'
+
+Assuming the same as above:
+
+  $ ruby ftpd.rb --debug=1
+  debug: 1
+  
+  $ ruby ftpd.rb --debug
+  <help screen printed>
+    
+=== default
+
+You can define a default value for your option, if you'd like.  If the option
+is not present in the argument list, the default will be returned when trying
+to access that element of the <tt>Choice.choices</tt> hash.
+
+As with the above, assume our program prints <tt>Choice.choices[:debug]</tt>:
+
+  default 'info'
+
+If we don't pass in <tt>--debug</tt>, the <tt>:debug</tt> element of our hash 
+will be 'info.'
+
+  $ ftpd.rb
+  debug: info
+
+  $ ftpd.rb --debug=warn
+  debug: warn
+
+=== desc
+
+The description of this option.  Fairly straightforward, with one little trick:
+multiple +desc+ statements in a single option will be considered new desc lines.  
+The desc lines will be printed in the order they are defined.  Like this:
+
+  desc "Your hostname."
+  desc "(default 'localhost')"
+
+A snippet from your <tt>--help</tt> might then look like this:
+
+  -h, --host=HOST                  Your hostname.
+                                   (default 127.0.0.1)
+
+
+=== cast
+
+By default, all members of the <tt>Choice.choices</tt> hash are strings.  If 
+you want something different, like an Integer for a port number, you can use 
+the +cast+ statement.
+
+Currently support +cast+ options:
+
+* Integer
+* String
+* Float
+* Symbol
+
+We'll probably add Date, Time, and DateTime in the future, if people want them.
+
+=== validate
+
+The +validate+ statement accepts a regular expression which it will test 
+against the value passed.  If the test fails, the <tt>--help</tt> screen will
+be printed.  I love ports, so let's stick with that example:
+
+  validate /^\d+$/
+
+Of course, 2100 matches this:
+
+  $ ruby ftpd.rb -p 2100
+  port: 21000
+
+I like dogs.  I wish dogs could be ports.  Alas, Choice knows better (once
+I've told it so):
+
+  $ ruby ftpd.rb -p labradoodle
+  <help screen printed>
+
+=== filter
+
+The +filter+ statement lets you play with a value before it goes into the
+<tt>Choice.choices</tt> hash.  If you use +cast+, this will occur post-casting.
+
+In this program we're defining a :name option and saying we don't want any 
+crazy characters in it, then printing that element of the 
+<tt>Choice.choices</tt>+ hash:
+
+  filter do |value|
+    value = value.gsub(/[^\w]/, '')
+  end
+
+Now:
+
+  $ ruby ftpd.rb --name=c.hr.is
+  name: chris
+
+You can probably think of better uses.  
+
+=== action
+
+A block passed to the +action+ statement will be run if that particular option
+is passed.  See the <tt>--version</tt> example earlier.
+
+== Other options
+
+These statements are purely aesthetic, used to help make your <tt>--help</tt>
+screen a little more digestible.
+
+Passing an empty string to any of these options will print a newline.
+
+=== banner
+
+The banner is the first line printed when your program is called with 
+<tt>--help</tt>.  By default, it will be something like this, based on the 
+options defined:
+
+  Usage: ftpd.rb [-hpv]
+
+You can pass any string to the +banner+ statement to override what prints.  This
+might be useful if you're into ascii art.
+
+=== header
+
+The header is what shows up after the banner but before your option definitions
+are printed.  Each header call is a newline.  Check out the example above.
+
+=== separator
+
+As in the example above, you can put separators between options to help display
+the logical groupings of your options.  Or whatever.  
+
+=== footer
+
+The footer is displayed after all your options are displayed.  Nothing new 
+here, works like the other options above.
+
+== It looks like poetry
+
+That's it.  Not much, I know.  Maybe this will make handling your command 
+line options a bit easier.  You can always use the option parser in the standard 
+Ruby library, but DSLs are just so cool.  As one of my non-programmer friends 
+said of a Ruby DSL: "It looks like poetry."
+
+== It's totally broken
+
+Okay, I knew this would happen.  Do me a favor, if you have time: run +rake+ 
+from the Choice directory and send me the output (mailto:chris[at]ozmm[dot]org).  
+This'll run the unit tests.  Also, if you would, send me a bit of information 
+on your platform.  Choice was tested on OS X and RHEL with a 2.4 kernel but who 
+knows.  Thanks a lot.
+

data/examples/ftpd.rb

@@ -0,0 +1,78 @@
+$:.unshift "../lib"
+require 'choice'
+
+port = 21
+PROGRAM_VERSION = 4
+
+Choice.options do
+  #banner "Usage: ftpd.rb [options]"
+  
+  header ""
+  header "Specific options:" 
+  
+  option :host do
+    short '-h'
+    long '--host=HOST'
+    desc "The hostname or ip of the host to bind to"
+    desc "(default 127.0.0.1)"
+    default '127.0.0.1'
+  end
+
+  option :port do
+    short '-p'
+    long '--port=PORT'
+    desc "The port to listen on (default 21)"
+    cast Integer
+    default port
+  end
+
+  option :clients do
+    short '-c'
+    long '--clients=NUM'
+    cast Integer
+    desc "The number of connections to allow at once (default 5)"
+    default 5
+  end
+      
+  option :yaml_cfg do
+    long '--config=FILE'
+    desc 'Load configuration from YAML file'
+  end
+  
+  option :sample do
+    long '--sample'
+    desc "See a sample YAML config file"
+    action do
+      puts "See!"
+      exit
+    end
+  end
+  
+  option :debug do
+    short '-d'
+    long '--debug'
+    desc 'Turn on debugging mode'
+  end  
+  
+   separator ''
+   separator 'Common options: '
+
+  option :help do
+    long '--help'
+    desc 'Show this message'
+  end
+
+  option :version do
+    short '-v'
+    long '--version'
+    desc 'Show version'
+    action do
+      puts "ftpd.rb FTP server v#{PROGRAM_VERSION}"
+      exit      
+    end
+  end
+  
+end
+
+print "Choices: "
+puts Choice.choices.inspect