OptionParser 0.5.0 → 0.5.1

data/LICENSE

@@ -0,0 +1,31 @@
+OPTIONPARSER LICENSE
+
+Copyright (c) 2005, Jim Freeze
+All rights reserved.
+
+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.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+  http://www.opensource.org/licenses/mit-license.php
+  http://www.opensource.org/licenses/bsd-license.php
+

data/README

@@ -1,32 +1,22 @@
-LICENSE
-
-This release is licensed under the RLL - Ruby Lovers License. If you don't
-love Ruby, then you don't have permission to even think about using/reading/
-opening any file in this project.
-
-If you a lover of Ruby, then you may use this freely and pay for your use
-by giving feedback to the author, Jim Freeze.
-
-
 CommandLine::OptionParser
 =========================
-
+Author: Jim Freeze
+Copyright 2005 Jim Freeze
 
 ABOUT 
 =====
-
 CommandLine::OptionParser is part of the CommandLine suite of
-tools and is used for command line parsing. The parser integrates
-with CommandLine::Option, CommandLine::OptionData and 
-CommandLine::Application.
+tools and is used for command line parsing. The command line
+parser suite consists of classes CommandLine::Option, 
+CommandLine::OptionData and CommandLine::Application.
 
 The parser supports POSIX, Gnu and XTools style parsing options. 
-It also gives you flexibility to provide <em>non standard</em>
+It also provides flexibility to support <em>non standard</em>
 options. For example:
 
 POSIX
 =====
-OptionParser.new Option.new(:names => "-f")
+OptionParser.new Option.new(:posix, :names => "-f")
 
 Gnu
 ===
@@ -43,50 +33,44 @@ OptionParser.new(Option.new(
    :arg_arity => [1,-1],
    :arg_description => "file1 [file2, ...]"))
 
-This option parser with a single option prints:
+This last option prints:
 
  OPTIONS
 
      --file,-file,--files,-files,-f file1 [file2, ...]
 
 
-There is document describing the various usage scenarios
-at its homepage.
-
+HISTORY
+=======
 After poking around in a few corporations, it was evident that
-option parsing was not understood. Nevertheless, many tools
-were built that did not conform to any of the POSIX, Gnu or XTools
+option parsing was not well understood. Therefore, many inhouse
+tools were built that did not conform to any of the POSIX, Gnu or XTools
 option styles. CommandLine::OptionParser was developed so that
-new application could be written that conformed to accepted standards,
+new applications could be written that conformed to accepted standards,
 but non-standard option configurations could be handled as well
 to support legacy interfaces.
 
-More information on OptionParser can be found on its homepage:
-http://optionparser.rubyforge.org
-
-
-Major Features - 06/07/2005
-=============
-* First public release 0.5.0
-
-
-Thanks for all the feedback!
-
+More information and usage scenarios on OptionParser can be found at:
+    http://rubyforge.org/projects/optionparser/
 
 Download & Installation
 =======================
 
-Homepage: http://optionparser.rubyforge.org
-Download: http://rubyforge.org/frs/?group_id=296
+Homepage: http://rubyforge.org/projects/optionparser/
+Download: http://rubyforge.org/frs/?group_id=632&release_id=2345
 
 Dependencies:
 * None
 
-There are many ways to install optionparser. Choose the one you like best:
+Currently optionparser is only available as a rubygem.
 
 Via RubyGems 
   $ gem install optionparser
 
+All feedback is appreciated!
+
+Installations not available yet
+===============================
 # not in RPA yet
 Via RPA 
   $ rpa install optionparser
@@ -102,9 +86,18 @@ The simplified do-it-yourself way
   $ rake install
 
 
-Integration with Application
-============================
+RELEASE NOTES
+=============
+
+---------------------------------------------------------------------
+0.5.1  06/17/2005
+* Contains all planned features except CVS like command handling
+* Fixed loading path using gems. Is now loaded by:
+   require 'rubygems'
+   require 'commandline/optionparser'
+* Updated documentation
+
+---------------------------------------------------------------------
+0.5.0  06/07/2005  
+* First public release
 
-  class MyApp << CommandLine::Application
-    
-  end

data/docs/index.html

@@ -3,9 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
-<title>Notes of Dr. Freeze</title>
-<link rel="alternate" type="text/xml" title="RSS"
-      href="http://localhost:8808/index.cgi/index.rss" />
+<title>CommandLine::OptionParser</title>
 
 <style type="text/css">
 body,td {
@@ -26,7 +24,10 @@ h1, h2, h3, h4, h5, h6 {
 }
 
 pre {
-   border-left: 7px solid #e8d8d8;
+   #border-left: 7px solid #e8d8d8;
+   background: #ffeeff;
+   border-top: 2px solid #aaaaaa;
+   border-left: 2px solid #aaaaaa;
 }
 
 .sidebar {
@@ -207,30 +208,522 @@ pre {
 </head>
 <body>
 <table border="0" cellpadding="0" cellspacing="0" width="100%">
+<tr valign="bottom">
+<td class="pagetitle">CommandLine::OptionParser</a></td>
+</tr>
+</table>
+<hr />
+<table>
+<tr valign="top"><td>
+
+<table class="entry" border="0" cellspacing="0" width="100%">
 <tr class="entrybody"><td colspan="3" class="entrybody">
-<h1>Welcome to <a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></h1>
-<tt><a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></tt> is
+<h1>Welcome to OptionParser</h1>
+<ul>
+<li>Copyright &#169; 2005 Jim Freeze
+
+</li>
+<li>Author: Jim Freeze
+
+</li>
+<li><a href="http://www.freeze.org/ruby/optionparser/license.txt">License</a>
+</li>
+<li><a href="http://rubyforge.org/projects/optionparser/">Project Page</a>
+</li>
+<li><a href="http://rubyforge.org/frs/?group_id=632&release_id=2345">Download</a>
+</li>
+</ul>
+<tt>OptionParser</tt> is
 designed to be a flexible command line parser with a Ruby look and feel to
-it. <a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a>
-got its birth from the need for a parser that was flexible. One that
-supported (or not) the standard command line styles of <tt>Unix</tt>,
-<tt>Gnu</tt> and <tt>X Toolkit</tt>.
+it. <tt>OptionParser</tt> got
+its birth from the need for a parser that is standards compliant, yet
+flexible. <tt>OptionParser</tt>
+supports the standard command line styles of <tt>Unix</tt>, <tt>Gnu</tt>
+and <tt>X Toolkit</tt>, but also lets you break those rules.
+
+<p>
+<tt>OptionParser</tt> is
+not a port of a traditional command line parser, but it is written to meet
+the feature requirements of traditional command line parsers. When using it
+as a library, you should notice that it is expressive, supports
+Ruby&#8217;s blocks and lambda&#8217;s, and is sprinkled with a little bit
+of magic.
+</p>
+<p>
+While the library can be used by itself, it is also designed to work with
+the <tt>CommandLine::Application</tt> class. These tools work together to
+facilitate the generation of a sophisticated (batch oriented) application
+user interface in a matter of minutes.
+</p>
+<p>
+If you need a refresher on the traditional option parsing schemes, see
+&quot;Traditional Option Parsing Schemes&quot; below.
+</p>
+<h1>Jumping Right In</h1>
+<h1>OptionParser Usage</h1>
+<p>
+The OptionParser
+library consists of three classes, <tt>Option</tt>, <tt>OptionParser</tt> and
+<tt>OptionData</tt>. For each option an <tt>Option</tt> object is created.
+When you are ready to prepare for command line parsing, these options are
+collected into an array and fed to <tt>OptionParser</tt>.
+This <tt>OptionParser</tt>
+object controls the type of option scheme that is implemented. When it
+comes time to parse a command line, call the method <tt>Option#parse</tt>.
+This will parse any array, but parses ARGV by default. The result is an
+<tt>OptionData</tt> object. This object can be used from which to extract
+values or it can be passed to another class as a fully encapsulated data
+object.
+</p>
+<h2>Getting Started</h2>
+<h3>Installing</h3>
+<pre>
+  gem install -r OptionParser
+</pre>
+<h3>Loading the library</h3>
+<pre>
+  require 'rubygems'
+  require 'commandline/optionparser'
+  include CommandLine
+</pre>
+<h3>Using Option Parser</h3>
+<p>
+An option is created with the following syntax:
+</p>
+<pre>
+  opt = Option.new([options], &lt;properties&gt;)
+</pre>
+<p>
+The options can be <tt>:flag</tt> or <tt>:posix</tt>. <tt>:flag</tt> means
+that the option is a mode flag and does not take any arguments.
+<tt>:posix</tt> means that <tt>Option</tt> will validate the properties to
+ensure they are posix compliant.
+</p>
+<p>
+An option object has six properties. Four of these properties define
+attributes of the object. The last two define <em>actions</em> that are
+taken when a command line is parsed.
+</p>
+<ol>
+<li>:names
+
+</li>
+<li>:arg_arity
+
+</li>
+<li>:opt_description
+
+</li>
+<li>:arg_description
+
+</li>
+<li>:opt_found
+
+</li>
+<li>:opt_not_found
+
+</li>
+</ol>
+<p>
+It is not necessary to set values for all of these properties. Some are set
+automatically, as we&#8217;ll see below.
+</p>
+<h3>Posix</h3>
+<p>
+The default <tt>Option</tt> object is non-posix.
+</p>
+<pre>
+    op1  = OptionParser.new(:posix, opts)
+    op2  = OptionParser.new(opts)
+    op1.posix  #=&gt; true
+    op2.posix  #=&gt; false
+</pre>
+<h3>Mode-Flag</h3>
+<p>
+To create a mode flag, that is, an option that is either true or false
+depending if it is seen on the command line or not, we could write:
+</p>
+<pre>
+  opt_debug = Option.new(
+    :names           =&gt; %w(--debug -d),       # the flag has two names
+    :arg_arity       =&gt; [0,0],                # this says take no arugments
+    :opt_description =&gt; &quot;Sets debug to true&quot;,
+    :arg_description =&gt; &quot;&quot;,
+    :opt_found       =&gt; true,                 # true if seen on command line
+    :opt_not_found   =&gt; false                 # false if not seen on command line
+  )
+</pre>
+<p>
+Now, this is a lot of work just for a common mode-flag. However, there is a
+shorter way:
+</p>
+<pre>
+  opt = Option.new(:flag, :names =&gt; %w(--debug -d))
+</pre>
+<p>
+When <tt>Option</tt> sees the :flag option, it makes some assignments
+behind the scenes and what you are left with is:
+</p>
+<pre>
+    :names           =&gt; [&quot;--debug&quot;, &quot;-d&quot;]
+    :arg_arity       =&gt; [0, 0]
+    :opt_description =&gt; &quot;Sets debug to true.&quot;  # debug is taken from the first name
+    :arg_description =&gt; &quot;&quot;
+    :opt_found       =&gt; true
+    :opt_not_found   =&gt; false
+</pre>
+<p>
+For a common option like a mode-flag, <tt>Option</tt> will use the first
+option &#8216;word&#8217; it finds in the :names list and use that in the
+automatic option text. Of course, if you don&#8217;t want any text, just
+set the option description to an empty string:
+</p>
+<pre>
+  :opt_description =&gt; &quot;&quot;.
+</pre>
+<h3>Option Arguments</h3>
+<p>
+If an option is not a mode flag, then it takes arguments. Most option
+parsers only permit a single argument per option flag. If your application
+needs multiple arguments, the standard method is just to repeat the option
+multiple times, once for each required argument. For example, if I need to
+pass two files to an application I would need something like:
+</p>
+<pre>
+  myapp -f file1 -f file2
+</pre>
+<p>
+But, it would be cleaner if the command line could be expressed as:
+</p>
+<pre>
+  myapp -f file1 file2
+</pre>
+<p>
+Well, no longer do you have to suffer with thirty-year old option parser
+technology. <tt>OptionParser</tt>
+permits multiple arguments per option flag and the number of arguments can
+be defined to be variable.
+</p>
+<p>
+To define an option that takes 1 or more arguments, the following can be
+done:
+</p>
+<pre>
+  opt = Option.new(:names =&gt; &quot;--file&quot;, :arg_arity =&gt; [1,-1])
+</pre>
+<p>
+Let&#8217;s say the option required at least two arguments, but not more
+than five. This is defined with:
+</p>
+<pre>
+  opt = Option.new(:names =&gt; &quot;--file&quot;, :arg_arity =&gt; [2,5])
+  OptionParser.new(opt).parse
+
+  % myapp --file file1                    # exception raised
+  % myapp --file file1 file2              # ok
+  % myapp --file file1 file2 file3        # ok
+  % myapp --file f1 f2 f3 f4 f5 f6        # f6 remains on the command line
+</pre>
+<p>
+This ability is handy on occassions where an option argument is
+&#8216;optional&#8217;.
+</p>
+<pre>
+  myapp --custom                 # no args, uses $HOME/.myapprc
+  myapp --custom my_custom_file  # uses my_custom_file
+</pre>
+<p>
+This type of option is defined by:
+</p>
+<pre>
+  opt = Option.new(:names =&gt; &quot;--custom&quot;, :arg_arity =&gt; [0,1])
+</pre>
+<p>
+If the <tt>:arg_arity</tt> is not satisfied, an exception is raised.
+</p>
+<h3>Actions</h3>
+<p>
+The option properties <tt>:opt_found</tt> and <tt>:opt_not_found</tt> are
+the source of the value returned for an option when it is parsed. These
+properties can be either an object or a proc/lambda. If they are an object,
+then the stored object is simply returned. If they are lambdas, then the
+stored value is the return value of the proc/lambda. So, the following will
+have the same result:
+</p>
+<pre>
+  opt_debug = Option.new(:flag
+    :names           =&gt; %w(--debug -d),
+    :opt_found       =&gt; true,
+    :opt_not_found   =&gt; false
+  )
 
+  opt_debug = Option.new(:flag
+    :names           =&gt; %w(--debug -d),
+    :opt_found       =&gt; lambda { true },
+    :opt_not_found   =&gt; lambda { false }
+  )
+</pre>
+<p>
+Notice that there is no need to set an instance variable to a default
+value. Normally one does:
+</p>
+<pre>
+  @debug = false
+  # option setup
+  ... parse the commandline
+  @debug = true if parse_results[&quot;--debug&quot;]
+</pre>
+<p>
+But with <tt>OptionParser</tt>, one
+has the capability of doing the following:
+</p>
+<pre>
+  opt_debug = Option.new(:flag, :names =&gt; %w(--debug -d))
+  ... parse the commandline
+  @debug = option_data[:debug]  # value is set without need for default
+
+  # or
+
+  opt_debug = Option.new(:flag
+    :names           =&gt; %w(--debug -d),
+    :opt_found       =&gt; lambda { @debug = true },
+    :opt_not_found   =&gt; lambda { @debug = false }
+  )
+  # do nothing, variable already set.
+</pre>
+<p>
+I find this much easier to manage than having to worry about setting
+default behaviour. Now that we know how to create options, let&#8217;s move
+on to the commandline parser.
+</p>
+<h2>OptionParser</h2>
+<p>
+Once the options are defined, we load them into an <tt>OptionParser</tt> and
+parse the command line. The syntax for creating an <tt>OptionParser</tt>
+object is:
+</p>
+<pre>
+  OptionParser.new(prop_flags, option)
+  OptionParser.new(prop_flags, [options])
+  OptionParser.new(option)
+  OptionParser.new([options])
+</pre>
+<p>
+where the possible property flags are:
+</p>
+<pre>
+  :posix
+  :unknown_options_action =&gt; :collect | :ignore | :raise
+</pre>
+<p>
+If you want to parse posix, you must specify so. <tt>OptionParser</tt> will
+not assume posix mode just because all of the options are posix options.
+This allows you to use posix only options but not require the strict
+parsing rules.
+</p>
+<p>
+Below are a few examples of creating an <tt>OptionParser</tt>
+object:
+</p>
+<pre>
+  opt = Option.new(:flag, :names =&gt; %w(-h))
+  op1 = OptionParser.new(:posix, opt)
+  op2 = OptionParser.new(opt)
+</pre>
+<p>
+or
+</p>
+<pre>
+  opts = []
+  opts &lt;&lt; Option.new(:flag, :names =&gt; %w(--help h))
+  opts &lt;&lt; Option.new(:flag, :names =&gt; %w(--debug d))
+</pre>
+<p>
+Options may be added to an <tt>OptionParser</tt> by
+three different methods:
+</p>
+<pre>
+  # Options added as arguments during OptionParser construction
+  op = OptionParser.new(opt1, opt2)
+  op = OptionParser.new([opt1, opt2])
+</pre>
+<p>
+or
+</p>
+<pre>
+  # Options added in a block constructor
+  op = OptionParser.new { |o| o &lt;&lt; opts }
+</pre>
+<p>
+or
+</p>
+<pre>
+  # Options added to an existing OptionParser object
+  op  = OptionParser.new
+  op &lt;&lt; opts
+</pre>
+<h3>Parsing the Command Line</h3>
+<p>
+Parsing the command line is as simple as calling <tt>#parse</tt>:
+</p>
+<pre>
+  option_data = op.parse
+</pre>
+<h3>Printing an Option Summary</h3>
+<p>
+A <tt>OptionParser</tt> with
+a complete set of options added to it defines the human interface that your
+application presents to a user. Therefore, the parser should be able to
+provide a nicely formatted summary for the user.
+</p>
+<p>
+An example is shown below with its corresponding output:
+</p>
+<pre>
+  require 'rubygems'
+  require 'commandline/optionparser'
+  include CommandLine
+  puts OptionParser.new { |o|
+    o &lt;&lt; Option.new(:flag, :names =&gt; %w[--debug -d])
+    o &lt;&lt; Option.new(:flag, :names =&gt; %w[--help  -h],
+              :opt_description =&gt; &quot;Prints this page.&quot;)
+    o &lt;&lt; Option.new(:names =&gt; %w[--ouput -o],
+              :opt_description =&gt; &quot;Defines the output file.&quot;,
+              :arg_description =&gt; &quot;output_file&quot;)
+    o &lt;&lt; Option.new(:names =&gt; %w[--a-long-opt --with-many-names -a -A],
+              :arg_arity =&gt; [2,-1],
+              :opt_description =&gt; &quot;Your really long description here.&quot;,
+              :arg_description =&gt; &quot;file1 file2 [file3 ...]&quot;)
+  }.to_s
+</pre>
+<p>
+Generates the output:
+</p>
+<pre>
+  OPTIONS
+
+      --debug,-d
+          Sets debug to true.
+
+      --help,-h
+          Prints this page.
+
+      --ouput,-o output_file
+          Defines the output file.
+
+      --a-long-opt,--with-many-names,-a,-A file1 file2 [file3 ...]
+          Your really long description here.
+</pre>
+<h2>Option Data</h2>
+<p>
+The <tt>OptionData</tt> is the return value of <tt>OptionParser#parse</tt>.
+The parsing results for each option are accessed with the bracket notation
+#[].
+</p>
+<pre>
+  opt = Option.new(:posix,
+                   :names =&gt; %w(-r),
+                   :opt_found =&gt; OptionParser::GET_ARGS)
+  od = OptionParser.new(:posix, opt).parse([&quot;-rubygems&quot;])
+  od[&quot;-r&quot;] #=&gt; &quot;ubygems&quot;
+
+  od = OptionParser.new(:posix, opt).parse([&quot;-r&quot;, &quot;ubygems&quot;])
+  od[&quot;-r&quot;] #=&gt; &quot;ubygems&quot;
+</pre>
+<p>
+<tt>OptionData</tt> behaves similar to a hash object in that the parsed
+option data is accessed with #[] where the key is the first item in the
+:names array of each option. An option cannot access its parsed values
+using just any of its names.
+</p>
+<pre>
+  od = OptionParser.new { |o|
+    o &lt;&lt; Option.new(:flag, :names =&gt; %w(--valid --notvalid))
+    o &lt;&lt; Option.new(:flag, :names =&gt; %w(--first --second))
+  }.parse(%w(--notvalid --second))
+  od[&quot;--valid&quot;]    #=&gt; true
+  od[&quot;--first&quot;]    #=&gt; true
+  od[&quot;--notvalid&quot;] #=&gt; CommandLine::OptionData::UnknownOptionError
+  od[&quot;--second&quot;]   #=&gt; CommandLine::OptionData::UnknownOptionError
+</pre>
+<h3>Built-in Data Handlers</h3>
+<p>
+OptionParser has
+built-in data handlers for handling common scenarios. These lambdas can
+save a lot of typing.
+</p>
+<h3>GET_ARG_ARRAY</h3>
+<p>
+This is useful for options that take a variable number of arguments. It
+returns all the arguments in an array.
+</p>
+<pre>
+  # GET_ARG_ARRAY returns all arguments in an array, even if no
+  # arguments are present. This is not to be confused with the option
+  # occuring multiple times on the command line.
+  opt = Option.new(:names          =&gt; %w(--file),
+                   :argument_arity =&gt; [0,-1],
+                   :opt_found      =&gt; OptionParser::GET_ARG_ARRAY)
+                   #:opt_found      =&gt; :collect)  # would this be better?
+  od  = OptionParser.new(opt).parse(%w(--file))
+  od[&quot;--file&quot;]    #=&gt; []
+  od  = OptionParser.new(opt).parse(%w(--file=file))
+  od[&quot;--file&quot;]    #=&gt; [&quot;file&quot;]
+  od  = OptionParser.new(opt).parse(%w(--file=file1 --file file2))
+  od[&quot;--file&quot;]    #=&gt; [&quot;file2&quot;]
+  od  = OptionParser.new(opt).parse(%w(--file=file1 file2))
+  od[&quot;--file&quot;]    #=&gt; [&quot;file1&quot;, &quot;file2&quot;]
+  od  = OptionParser.new(opt).parse(%w(--file file1 file2))
+  od[&quot;--file&quot;]    #=&gt; [&quot;file1&quot;, &quot;file2&quot;]
+</pre>
+<h3>GET_ARGS</h3>
+<p>
+This is a &#8216;smart&#8217; option getter. If no arguments are found, it
+returns true. If a single argument is found, it returns that argument. If
+more than one argument is found, it returns an array of those arguments.
+</p>
+<pre>
+  opt = Option.new(:names          =&gt; %w(--file),
+                   :argument_arity =&gt; [0,-1],
+                   :opt_found      =&gt; OptionParser::GET_ARGS)
+                   #:opt_found      =&gt; :smart_collect)  # would this be better?
+  od  = OptionParser.new(opt).parse(%w(--file))
+  od[&quot;--file&quot;]    #=&gt; true
+  od  = OptionParser.new(opt).parse(%w(--file=file))
+  od[&quot;--file&quot;]    #=&gt; &quot;file&quot;
+  od  = OptionParser.new(opt).parse(%w(--file=file1 --file file2))
+  od[&quot;--file&quot;]    #=&gt; &quot;file2&quot;
+  od  = OptionParser.new(opt).parse(%w(--file=file1 file2))
+  od[&quot;--file&quot;]    #=&gt; [&quot;file1&quot;, &quot;file2&quot;]
+  od  = OptionParser.new(opt).parse(%w(--file file1 file2))
+  od[&quot;--file&quot;]    #=&gt; [&quot;file1&quot;, &quot;file2&quot;]
+</pre>
 <p>
-<a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> is not
-a port of a traditional command line parser, but it is written to meet the
-feature requirements of traditional command line parsers. When using it as
-a library, you should notice that it is expressive, supports Ruby&#8217;s
-blocks and lambda&#8217;s, and is sprinkled with a little bit of magic.
+And, for those oxymoronic non-optional options:
 </p>
+<pre>
+  opt = Option.new(:names =&gt; %w(--not-really-an-option),
+    :opt_not_found =&gt; OptionParser::OPT_NOT_FOUND_BUT_REQUIRED
+  )
+  OptionParser.new(opt).parse([])   #=&gt; OptionParser::MissingRequiredOptionError
+</pre>
+<h3><tt>OptionData</tt></h3>
 <p>
-While the library can be used by itself, it is also designed to work with
-the CommandLine::Application class. These tools work together to facilitate
-the generation of a sophisticated (batch oriented) application user
-interface in a matter of minutes.
+We have just shown that after parsing a command line, the result of each
+option is found from OptionData. The values that remain on the command line
+are assigned to <tt>args</tt>. Other attributes of <tt>OptionData</tt> are:
+</p>
+<pre>
+  od.argv             # the original command line
+  od.unknown_options  # If OptionParser was told to :collect unknown options
+  od.args             # arguments not claimed by any option
+  od.not_parsed       # arguments following a '--' on the command line
+  od.cmd              # not yet implemented - but a cvs like command
+</pre>
+<hr size="2"></hr><h1>Traditional Option Parsing Schemes</h1>
+<p>
+This section is a brief overview of traditional command line parsing.
 </p>
-<h1>Traditional Option Parsing Schemes</h1>
 <p>
 Command line options traditionally occur in three flavors:
 </p>
@@ -371,11 +864,6 @@ The options in this style are sometimes referred to as
 The compatibility is maintained by preceding the <em>long_options</em> with
 two dashes. The option word must be two or more characters.
 </p>
-<pre>
-   :test
-   if gnu_style is slected, ensure only two options and that one
-   is Unix and one is Gnu style.
-</pre>
 <h3>Separation Between the Option Flag and Its Argument</h3>
 <p>
 Gnu style options cannot be grouped. For options that have an argument, the
@@ -419,18 +907,16 @@ filtered from the command line before passing them to an application.
 <p>
 It is convention that a bare hypen indicates to read from stdin.
 </p>
-<h2>The <a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> Style</h2>
+<h2>The OptionParser Style</h2>
 <p>
-The CommandLine::<a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> does not
+The CommandLine::OptionParser does not
 care what style you use. It is designed for maximum flexiblity so it may be
 used within any organiziation to meet their standards.
 </p>
 <h3>Multiple Option Names</h3>
-<p>
-<a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> does
+<p> OptionParser does
 not place restrictions on the number of options. The only restriction is
-that an option name begin with a hyphen &#8217;-&#8217;. An definitely
+that an option name begin with a hyphen &#8217;-&#8217;. A definitely
 conjured example of this freedom is:
 </p>
 <pre>
@@ -438,7 +924,6 @@ conjured example of this freedom is:
     --file --File --f --F -file -File -f -F
   )
 </pre>
-<h2>Miscellaneous Option Styles</h2>
 <h3>Prefix Matching</h3>
 <p>
 Although not encouraged, some prefer the ability to truncate option words
@@ -474,8 +959,7 @@ should happen when the following is given:
 <p>
 Should the parser flag this as an error or should it accept both arguments.
 </p>
-<p>
-<a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> gives
+<p> OptionParser gives
 you the choice of whether it raises an exception when an option is seen
 more than once, or it just passes the data onto the user.
 </p>
@@ -510,337 +994,12 @@ on how this is handled in the usage section.
 A conflict can occur where a grouping of single letter Unix options has the
 value as a word option preceded by a single dash. For this reason, it is
 customary to use the double-dash notation for word options. Unless
-double-dashes are enforced for word options, <a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> will
+double-dashes are enforced for word options, OptionParser will
 check for possible name conflicts and raise an exception if it finds one.
 </p>
-<p>
-An individual Option. Why isnt&#8217; a hash good enough? I think it is. An
-option, is a hash. But, it can&#8217;t validate itself. <a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> should
-worry about parsing using a collection of options
-</p>
-<h1><a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> Usage</h1>
-<p>
-The <a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a>
-library consists of three classes, <tt>Option</tt>, <tt><a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></tt> and
-<tt>OptionData</tt>. For each option an <tt>Option</tt> object is created.
-When you are ready to prepare for command line parsing, these options are
-collected into an <tt><a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></tt>
-object. This object controls the type of option scheme that is to be
-implemented. When it comes time to parse a command line, call the method
-+Option#parse+. This will parse any array, but parses ARGV by default. The
-result is an <tt>OptionData</tt> object. This object can be used from which
-to extract values or it can be passed to another class as a fully
-encapsulated data object.
-</p>
-<h2>Getting Started</h2>
-<p>
-An option is created with the following syntax:
-</p>
-<pre>
-  opt = Option.new([type], [options], &lt;properties&gt;)
-</pre>
-<p>
-The optional type can be <tt>:flag</tt> or <tt>:default</tt>, with
-<tt>:default</tt> naturally being the default.
-</p>
-<p>
-The options supported are
-</p>
-<pre>
-  :posix =&gt; true | false
-</pre>
-<p>
-with <tt>:posix =&gt; false</tt> being the default.
-</p>
-<p>
-An option object has six properties. Four of these properties define
-attributes of the object. The last two define <em>actions</em> that are
-taken when a command line is parsed.
-</p>
-<ol>
-<li>:names
-
-</li>
-<li>:arg_arity
-
-</li>
-<li>:opt_description
-
-</li>
-<li>:arg_description
-
-</li>
-<li>:opt_found
-
-</li>
-<li>:opt_not_found
-
-</li>
-</ol>
-<h3>Mode-Flag</h3>
-<p>
-To create a mode flag, that is an option that is either true or false
-depending if it is seen on the command line, we write:
-</p>
-<pre>
-  opt_debug = Option.new(
-    :names           =&gt; %w(--debug -d),
-    :arg_arity       =&gt; [0,0],
-    :opt_description =&gt; &quot;Sets debug to true&quot;,
-    :arg_description =&gt; &quot;&quot;,
-    :opt_found       =&gt; true,
-    :opt_not_found   =&gt; false
-  )
-</pre>
-<p>
-Now, this is a lot of work just for a common mode-flag. However, there is a
-shorter way:
-</p>
-<pre>
-  opt = Option.new(:flag,
-                   :names =&gt; %w(--debug -d),
-                   :opt_description =&gt; &quot;Sets debug to true.&quot;)
-</pre>
-<p>
-Or, even simpler yet,
-</p>
-<pre>
-  opt = Option.new(:flag, :names =&gt; %w(--debug -d))
-</pre>
-<p>
-For a common option like a mode-flag, <tt>Option</tt> will use the first
-option &#8216;word&#8217; it finds in the :names list and use that in the
-automatic option text. Of course, if you don&#8217;t want any text, just
-set the option description to an empty string:
-</p>
-<pre>
-  :opt_description =&gt; &quot;&quot;.
-</pre>
-<h3>POSIX</h3>
-<p>
-The default for is false, so the following are equivalent:
-</p>
-<pre>
-    op1  = OptionParser.new(opts, :posix =&gt; false)
-    op2  = OptionParser.new(opts)
-    op1.posix)  #=&gt; false
-    op2.posix)  #=&gt; false
-</pre>
-<h3>Actions</h3>
-<p>
-The option properties <tt>:opt_found</tt> and <tt>:opt_not_found</tt> are
-the source of the value returned for an option when it is parsed. These
-properties can be either an object or a proc/lambda. If they are an object,
-then the stored object is simply returned. If they are lambdas, then the
-stored value is the result of executing the lambda. So, the following will
-have the same result:
-</p>
-<p>
-object is the Options can perform actions
-</p>
-<pre>
-  opt_debug = Option.new(:flag
-    :names           =&gt; %w(--debug -d),
-    :opt_found       =&gt; true,
-    :opt_not_found   =&gt; false
-  )
-
-  opt_debug = Option.new(:flag
-    :names           =&gt; %w(--debug -d),
-    :opt_found       =&gt; lambda { true },
-    :opt_not_found   =&gt; lambda { false }
-  )
-</pre>
-<p>
-The key to notice here is that there is never a need to set an instance
-variable to a default value. Normally one does:
-</p>
-<pre>
-  @debug = false
-  # option setup
-  ... parse the commandline
-  @debug = true if parse_results[:debug]
-</pre>
-<p>
-Here, one has the option of doing the following:
-</p>
-<pre>
-  opt_debug = Option.new(:flag :names =&gt; %w(--debug -d),)
-  ... parse the commandline
-  @debug = option_data[:debug]
-
-  # or
-
-  opt_debug = Option.new(:flag
-    :names           =&gt; %w(--debug -d),
-    :opt_found       =&gt; lambda { @debug = true },
-    :opt_not_found   =&gt; lambda { @debug = false }
-  )
-  # do nothing, variable already set.
-</pre>
-<p>
-I find this much easier to manage that having to worry about setting
-default behaviour.
-</p>
-<h2><a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></h2>
-<p>
-Once the options are defined, we load them into and <a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> and parse
-the command line. The syntax for creating an <a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> object
-is:
-</p>
-<pre>
-  OptionParser.new(opt_or_array_of_opts[, options])
-</pre>
-<p>
-where the only option is for parsing posix:
-</p>
-<pre>
-  :posix =&gt; true | false  (default is false)
-</pre>
-<p>
-If you want to parse posix, you must specify so. <a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> will not
-assume posix mode just because all of the options are posix options. This
-allows you to use posix only options but not require the strict parsing
-rules.
-</p>
-<p>
-Some examples of creating an <a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> object:
-</p>
-<pre>
-  opt = Option.new(:flag, :names =&gt; %w(-h))
-
-  op  = OptionParser.new(opt, :posix =&gt; false)
-  op  = OptionParser.new(opt)
-
-  opts = []
-  opts &lt;&lt; Option.new(:flag, :names =&gt; %w(--help h))
-  opts &lt;&lt; Option.new(:flag, :names =&gt; %w(--debug d))
-  op = OptionParser.new(opts)
-
-  op  = OptionParser.new
-  op &lt;&lt; opt
-  op &lt;&lt; opts
-
-  # block constructor
-  op = OptionParser.new { |o|
-    o &lt;&lt; Option.new(:flag, :names =&gt; %w(--debug d))
-  }
-</pre>
-<h2>Parsing the Command Line</h2>
-<p>
-Parsing the command line is as simple as calling #parse:
-</p>
-<pre>
-  opt         = Option.new(:flag, :names =&gt; %w(-h))
-  op          = OptionParser.new(opt)
-  option_data = op.parse
-</pre>
-<h2>Option Data</h2>
-<p>
-The OptionData is the return value of <a
-href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a>#parse.
-The parsing results for each option are accessed with the bracket notation
-#[].
-</p>
-<pre>
-  opt = Option.new(:posix =&gt; true,
-                   :names =&gt; %w(-r),
-                   :opt_found =&gt; OptionParser::GET_ARGS)
-  od = OptionParser.new(opt, :posix =&gt; true).parse([&quot;-rubygems&quot;])
-  od[&quot;-r&quot;] #=&gt; &quot;ubygems&quot;
-
-  od = OptionParser.new(opt, :posix =&gt; true).parse([&quot;-r&quot;, &quot;ubygems&quot;])
-  od[&quot;-r&quot;] #=&gt; &quot;ubygems&quot;
-</pre>
-<p>
-But, OptionData is not liberal in that it only stores a reference to an
-options first name. An option cannot access its parsed values using just
-any of its names.
-</p>
-<pre>
-  od = OptionParser.new { |o|
-    o &lt;&lt; Option.new(:flag, :names =&gt; %w(--valid --notvalid))
-    o &lt;&lt; Option.new(:flag, :names =&gt; %w(--first --second))
-  }.parse(%w(--notvalid --second))
-  od[&quot;--valid&quot;]    #=&gt; true
-  od[&quot;--first&quot;]    #=&gt; true
-  od[&quot;--notvalid&quot;] #=&gt; CommandLine::OptionData::UnknownOptionError
-  od[&quot;--second&quot;]   #=&gt; CommandLine::OptionData::UnknownOptionError
-</pre>
-<h3>Built-in Data Handlers</h3>
-<p>
-<a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> has
-built-in data handlers for handling common scenarios. These lambas can save
-a lot of typing.
-</p>
-<p>
-The first is GET_ARG_ARRAY. This is useful for options that take a variable
-number of arguments. It returns all the arguments in an array.
-</p>
-<pre>
-  # GET_ARG_ARRAY returns all arguments in an array, even if no
-  # arguments are present. This is not to be confused with the option
-  # occuring multiple times on the command line.
-  opt = Option.new(:names          =&gt; %w(--file),
-                   :argument_arity =&gt; [0-1],
-                   :opt_found      =&gt; OptionParser::GET_ARG_ARRAY)
-  od  = OptionParser.new(opt).parse(%w(--file))
-  od[&quot;--file&quot;]    #=&gt; []
-  od  = OptionParser.new(opt).parse(%w(--file=file))
-  od[&quot;--file&quot;]    #=&gt; [&quot;file&quot;]
-  od  = OptionParser.new(opt).parse(%w(--file=file1 --file file2))
-  od[&quot;--file&quot;]    #=&gt; [&quot;file2&quot;]
-  od  = OptionParser.new(opt).parse(%w(--file=file1 file2))
-  od[&quot;--file&quot;]    #=&gt; [&quot;file1&quot;, &quot;file2&quot;]
-  od  = OptionParser.new(opt).parse(%w(--file file1 file2))
-  od[&quot;--file&quot;]    #=&gt; [&quot;file1&quot;, &quot;file2&quot;]
-</pre>
-<p>
-The next is GET_ARGS. This is a &#8216;smart&#8217; option getter. If no
-arguments are found, it returns true. If a single argument is found, it
-returns that argument. If more than one argument is found, it returns an
-array of those arguments.
-</p>
-<pre>
-  opt = Option.new(:names          =&gt; %w(--file),
-                   :argument_arity =&gt; [0-1],
-                   :opt_found      =&gt; OptionParser::GET_ARGS)
-  od  = OptionParser.new(opt).parse(%w(--file))
-  od[&quot;--file&quot;]    #=&gt; true
-  od  = OptionParser.new(opt).parse(%w(--file=file))
-  od[&quot;--file&quot;]    #=&gt; &quot;file&quot;
-  od  = OptionParser.new(opt).parse(%w(--file=file1 --file file2))
-  od[&quot;--file&quot;]    #=&gt; &quot;file2&quot;
-  od  = OptionParser.new(opt).parse(%w(--file=file1 file2))
-  od[&quot;--file&quot;]    #=&gt; [&quot;file1&quot;, &quot;file2&quot;]
-  od  = OptionParser.new(opt).parse(%w(--file file1 file2))
-  od[&quot;--file&quot;]    #=&gt; [&quot;file1&quot;, &quot;file2&quot;]
-</pre>
-<p>
-And, for those oxymoronic non-optional options:
-</p>
-<pre>
-  opt = Option.new(:names =&gt; %w(--not-really-an-option),
-    :opt_not_found =&gt; OptionParser::OPT_NOT_FOUND_BUT_REQUIRED
-  )
-  OptionParser.new(opt).parse([])   #=&gt; OptionParser::MissingRequiredOptionError
-</pre>
-<h3>OptionData</h3>
-<p>
-We have just shown that after parsing a command line, the result of each
-option is found from OptionData. The vaues that are left are assigned to
-<tt>args</tt>. And, the first argument can be a command if so desired.
-</p>
 
 </td></tr>
 </table>
+</table>
 </body>
 </html>

data/lib/commandline.rb

@@ -0,0 +1,14 @@
+#  $Id$
+#  $Source$
+#
+#  Author: Jim Freeze
+#  Copyright (c) 2005
+#
+# =DESCRIPTION
+# Loader
+#
+# =Revision History
+#  Jim.Freeze 2005/06/17 Birthday
+#
+
+require 'commandline/optionparser'

metadata

@@ -3,16 +3,16 @@ rubygems_version: 0.8.10
 specification_version: 1
 name: OptionParser
 version: !ruby/object:Gem::Version 
-  version: 0.5.0
-date: 2005-06-16
+  version: 0.5.1
+date: 2005-06-17
 summary: A flexible command line option parser.
 require_paths: 
-  - lib/commandline
-email: optionpaser@freeze.org
-homepage: http://optionparser.rubyforge.org/
+  - lib
+email: optionparser@freeze.org
+homepage: http://rubyforge.org/projects/optionparser/
 rubyforge_project: 
 description: 
-autorequire: optionparser
+autorequire: commandline/optionparser
 default_executable: 
 bindir: bin
 has_rdoc: true
@@ -27,9 +27,9 @@ platform: ruby
 authors: 
   - Jim Freeze
 files: 
-  - docs/api
   - docs/index.html
   - lib/commandline
+  - lib/commandline.rb
   - lib/commandline/optionparser
   - lib/commandline/optionparser.rb
   - lib/commandline/text
@@ -38,12 +38,12 @@ files:
   - lib/commandline/optionparser/optionparser.rb
   - lib/commandline/text/format.rb
   - README
-test_files: 
-  - test/testall.rb
-  - test/tc_option.rb
+  - LICENSE
+test_files: []
 rdoc_options: []
 extra_rdoc_files: 
   - README
+  - LICENSE
 executables: []
 extensions: []
 requirements: []

data/test/tc_option.rb

@@ -1,121 +0,0 @@
-#  $Id$
-#  $Source$
-#
-#  Author: Jim Freeze
-#  Copyright (c) 2005 
-#
-# =DESCRIPTION
-# Test cases for Option Class
-#
-# =Revision History
-#  Jim.Freeze 2005/04/02 Birthday
-#
-
-require 'test/unit'
-require 'commandline/optionparser'
-
-class TC_Option < Test::Unit::TestCase
-  include CommandLine
-
-  def test_flag_parameters
-      opt = Option.new(:flag, :names => "-h")
-      assert_equal(%w(-h), opt.names)
-      assert_equal([0,0],  opt.arg_arity)
-      assert_equal("",     opt.opt_description)
-      assert_equal("",     opt.arg_description)
-      assert_equal(true,   opt.opt_found)
-      assert_equal(false,  opt.opt_not_found)
-      assert_equal(false,  opt.posix)
-  end
-
-  def test_posix
-    op = Option.new(:flag, :posix, :names => %w(-))
-    assert_equal(true, op.posix)
-    op = Option.new(:flag, :names => %w(-))
-    assert_equal(false, op.posix)
-
-    assert_raises(CommandLine::Option::InvalidOptionNameError) {
-      Option.new(:flag, :posix, :names => %w(--help))
-    }
-    assert_raises(CommandLine::Option::InvalidOptionNameError) {
-      Option.new(:flag, :posix, :names => %w(-help))
-    }
-    assert_nothing_raised {
-      Option.new(:flag, :posix, :names => %w(-h))
-    }
-    assert_nothing_raised {
-      Option.new(:flag, :posix, :names => %w(-H))
-    }
-    assert_nothing_raised {
-      Option.new(:flag, :posix, :names => %w(-))
-    }
-  end
-
-  def test_no_dash_name
-    assert_raises(CommandLine::Option::InvalidOptionNameError) { 
-      Option.new(:flag, :names => ["fred"])
-    }
-  end
-
-  def test_flag_constructor
-    opt = nil
-    assert_nothing_raised { opt = Option.new(:flag, :names => %w(--debug -d) ) }
-    assert_equal("Sets debug to true.", opt.opt_description)
-
-    opt = Option.new(:flag, 
-               :names => %w(--debug -d),
-               :opt_description => ""
-              )
-    assert_equal("", opt.opt_description)
-
-    opt = Option.new(:flag, 
-               :names => %w(--debug -d),
-               :opt_description => "Custom description"
-              )
-    assert_equal("Custom description", opt.opt_description)
-  end
-
-  def test_block_constructor
-    assert_raises(CommandLine::Option::MissingPropertyError) {
-      opt = Option.new {  |opp| opp.names = %w(--fred -f) }
-    }
-  end
-
-  def test_no_arity
-    opt = nil
-    assert_nothing_raised { opt = Option.new(:flag, :names => %w(--debug -d) ) }
-    assert_equal([0,0], opt.arg_arity)
-  end
-
-  def test_arity_is_number
-    opt = nil
-    assert_nothing_raised { opt = 
-      Option.new(:names     => %w(--debug -d), 
-                 :arg_arity => 1) }
-    assert_equal([1,1], opt.arg_arity)
-
-    opt = nil
-    assert_nothing_raised { opt = 
-      Option.new(:names     => %w(--debug -d), 
-                 :arg_arity => 2) }
-    assert_equal([2,2], opt.arg_arity)
-  end
-
-  def test_names_not_array
-    op = nil
-    assert_nothing_raised { op = Option.new(:flag, :names => "-fred") }
-    assert_equal(["-fred"], op.names)
-  end
-
-  def test_incompatible_properties
-    assert_raises(CommandLine::Option::InvalidArgumentArityError) { 
-      opt = Option.new(:flag, :names => "-a", :arg_arity => 1) }
-    assert_raises(CommandLine::Option::InvalidArgumentArityError) { 
-      Option.new(:flag, :names => "-b", :arg_arity => 1) }
-
-    assert_raises(CommandLine::Option::InvalidOptionNameError) { 
-      Option.new(:posix, :names => "--fred") }
-  end
-
-
-end#class TC_Option

data/test/testall.rb

@@ -1,16 +0,0 @@
-#!/usr/bin/env ruby 
-
-$LOAD_PATH.unshift("#{File.dirname(__FILE__)}/../lib")
-
-require 'commandline/optionparser'
-
-#tc = %w( tc_option.rb tc_optionparser.rb tc_optiondata.rb )
-tc = Dir["tc_*rb"]
-
-tc.each { |lib|
-  fork { 
-    require lib 
-    #puts "===> Testing #{lib}"
-  }
-}
-