* updated Rakefile

* added config.yaml for documentation sothat html files get validated
* updated documentation
* bumped version number to 2.0.0
* updated cmdparse.rb
* added optparse wrapper
* updated README file

README

@@ -9,39 +9,39 @@ program from Subversion and the "gem" program from Rubygems. The standard Ruby d
 library to create programs that use such a command line interface.
 
 This library, cmdparse, can be used to create such a command line interface. Internally it uses
-optparse to parse options and it provides a nice API for specifying commands.
+optparse or any other option parser library to parse options and it provides a nice API for
+specifying commands.
 
 
 = Dependencies
 
- optparse - part of the standard Ruby 1.8 distribution, so nothing to do here
-
+ none
 
 = Installation
 
- $ ruby setup.rb config
- $ ruby setup.rb setup
- $ ruby setup.rb install
+The preferred way of installing cmdparse is via RubyGems:
+ $ gem install cmdparse
 
-Or you could use Rake and substitute the above commands with this:
+If you do not have RubyGems installed, but Rake, you can use the following command:
  $ rake install
 
-Or you could install cmdparse the "GEM way":
- $ gem install cmdparse
-
+If you have neither RubyGems nor Rake, use these commands:
+ $ ruby setup.rb config
+ $ ruby setup.rb setup
+ $ ruby setup.rb install
 
 = Documentation
 
 You can build the documentation by invoking
  $ rake doc
 
 This builds the API and the additional documentation. The additional documentation needs webgen
->=0.3.4 (webgen.rubyforge.org) for building.
+>=0.3.5 (webgen.rubyforge.org) for building.
 
 
 = Example
 
-There is an example of how to use cmdparse in the +test.rb+ file.
+There is an example of how to use cmdparse in the +net.rb+ file.
 
 
 = Contact

Rakefile

@@ -2,7 +2,7 @@
 #
 # $Id$
 #
-# cmdparse: an advanced command line parser using optparse which supports commands
+# cmdparse: advanced command line parser supporting commands
 # Copyright (C) 2004 Thomas Leitner
 #
 # This program is free software; you can redistribute it and/or modify it under the terms of the GNU
@@ -32,10 +32,11 @@ require 'rake/testtask'
 
 # General actions  ##############################################################
 
-require 'lib/cmdparse'
+$:.unshift 'lib'
+require 'cmdparse'
 
 PKG_NAME = "cmdparse"
-PKG_VERSION = CommandParser::VERSION.join( '.' )
+PKG_VERSION = CmdParse::VERSION.join( '.' )
 PKG_FULLNAME = PKG_NAME + "-" + PKG_VERSION
 
 SRC_RB = FileList['lib/**/*.rb']
@@ -78,8 +79,7 @@ end
 rd = Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'doc/output/rdoc'
   rdoc.title    = PKG_NAME
-  rdoc.options << '--line-numbers' << '--inline-source' << '-m README'
-  rdoc.rdoc_files.include( 'README' )
+  rdoc.options << '--line-numbers' << '--inline-source' << '-m CmdParse::CommandParser'
   rdoc.rdoc_files.include( 'lib/**/*.rb' )
 end
 
@@ -112,11 +112,11 @@ else
 
     s.name = PKG_NAME
     s.version = PKG_VERSION
-    s.summary = "An advanced command line parser using optparse which supports commands"
+    s.summary = "Advanced command line parser supporting commands"
     s.description = <<-EOF
-       cmdparse extends the default option parser 'optparse' by adding
-       support for commands. Programs that use such command line interfaces
-       are, for example, subversion's 'svn' or Rubygem's 'gem' program.
+       cmdparse provides classes for parsing commands on the command line; command line options
+       are parsed using optparse or any other option parser implementation. Programs that use
+       such command line interfaces are, for example, subversion's 'svn' or Rubygem's 'gem' program.
     EOF
 
     #### Dependencies, requirements and files
@@ -130,7 +130,7 @@ else
 
     s.has_rdoc = true
     s.extra_rdoc_files = rd.rdoc_files.reject do |fn| fn =~ /\.rb$/ end.to_a
-    s.rdoc_options = ['--line-numbers', '-m', 'README']
+    s.rdoc_options = ['--line-numbers', '-m', 'CmdParse::CommandParser']
 
     #### Author and project details
 

TODO

@@ -6,3 +6,4 @@
 * ability to specify default command (used when no command was given)
 * add order,order!,... methods to mimic optparse
 * optionally capture error messages and provide friendlier output
+* if command has subcommands, use order! method, if has arguments use permute! (=POSIXLY_CORRECT); same with getoptlong

doc/config.yaml

@@ -0,0 +1,2 @@
+PageHandler:
+  validator: xmllint

doc/plugin/extract.rb

@@ -19,7 +19,7 @@ def process_tag( tag, node, refNode )
       data = File.readlines( get_param( 'file' ) ).unshift( 'empty null line' )[get_param( 'lines' )]
       out = '<table class="cmdparse-example"><tr>'
       out << '<td><pre>' << get_param( 'lines' ).collect {|n| "#{n}<br />" }.to_s << '</pre></td>'
-      out << '<td><pre>' << data.collect {|line| "#{CGI::escapeHTML(line)}<br />" }.to_s << '</pre></td>'
+      out << '<td><pre>' << data.collect {|line| "#{CGI::escapeHTML(line)}" }.to_s << '</pre></td>'
       out << '</tr></table>'
       out
     end

doc/src/about.page

@@ -10,7 +10,15 @@ program from Subversion and the "gem" program from Rubygems. The standard Ruby d
 library to create programs that use such a command line interface.
 
 This library, cmdparse, can be used to create such a command line interface. Internally it uses
-optparse to parse options and it provides a nice API for specifying commands.
+optparse or any other option parser library to parse options and it provides a nice API for
+specifying commands and subcommands.
+
+A typical command line for a program which uses commands looks like this:
+
+<pre>
+  $ net --verbose ipaddr add 192.168.0.1 193.150.0.1
+</pre>
+
 
 h2. Author
 

doc/src/default.template

@@ -13,7 +13,7 @@
         <table>
           <tr>
             <td><img src="{relocatable: logo.png}" alt="Logo" title="Logo" /></td>
-            <td><h1>cmdparse<span style="font-size: 60%"> - advanced command line parser which supports commands</span></h1>
+            <td><h1>cmdparse<span style="font-size: 60%"> - advanced command line parser supporting commands</span></h1>
             </td>
           </tr>
         </table>
@@ -34,9 +34,9 @@
       </div>
 
       <div id="footer" class="bar">
-        <a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml11" alt="Valid XHTML 1.1!" height="31" width="88" /></a>
-        <a href="http://jigsaw.w3.org/css-validator/check/referer"><img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" /></a>
-        <a href="http://webgen.rubyforge.org"><img src="http://webgen.rubyforge.org/generated_by_webgen.png" alt="Generated by webgen" height="31" width="88"/></a> on <b>{date: }</b>
+        <a href="http://validator.w3.org/check?uri=referer"><img src="{resource: w3c-valid-xhtml11}" alt="Valid XHTML 1.1!" height="31" width="88" /></a>
+        <a href="http://jigsaw.w3.org/css-validator/check/referer"><img src="{resource: w3c-valid-css}" alt="Valid CSS!" height="31" width="88" /></a>
+        <a href="http://webgen.rubyforge.org"><img src="{resource: webgen-generated}" alt="Generated by webgen" height="31" width="88"/></a> on <b>{date: }</b>
       </div>
     </div>
   </body>

doc/src/documentation.page

@@ -10,82 +10,118 @@ The <a href="{relocatable: /rdoc/index.html}">API reference</a> provides informa
 
 h2. Tutorial
 
-<b>The complete code for this example can be found in the file @test.rb@ of the @cmdparse@
+<b>The complete code for this example can be found in the file @net.rb@ of the @cmdparse@
 package!</b>
 
+This tutorial produces a small @net@ application which can add, delete and list IP adresses and show
+'network statistics'. The shown code fragments do not include the whole program. So, instead of
+writing all the code yourself, just look at the code fragments first and then use the include
+@net.rb@ file for running the program.
+
 h3. Require statements
 
 Create a new new file and write the necessary @require@ statements.
 
-<notextile>{extract: {file: ../test.rb, lines: !ruby/range 4..5}}</notextile>
+<notextile>{extract: {file: ../net.rb, lines: !ruby/range 5..5}}</notextile>
 
 h3. The @CommandParser@ class
 
 Next we will define our basic @CommandParser@ by defining the name of the program, its version and
-release number and the global options. These global options are always used by @CommandParser@ and
-have to be specified on the command line before the name of a command. The global options and, for
-the matter, the local command specific options are instances of the @OptionParser@ class which is
-available in the Ruby Standard library.
+the global options. The boolean argument to the constructor of the @CommandParser@ class defines
+whether exceptions should be handled gracefully, i.e. by showing an appropriate error message and
+the help screen.
+
+<notextile>{extract: {file: ../net.rb, lines: !ruby/range 30..36}}</notextile>
 
-<notextile>{extract: {file: ../test.rb, lines: !ruby/range 29..37}}</notextile>
+The options are defined using an option parser wrapper. Currently, the only option parser library
+supported is @optparse@ from the Ruby Standard Library. If you want to use another option parser
+library, you need to write a wrapper for it so that @cmdparse@ can use it.
 
 Now we only have to tell the program to use our newly defined class to process the command line
 arguments.
 
-<notextile>{extract: {file: ../test.rb, lines: !ruby/range 41..42}}</notextile>
+<notextile>{extract: {file: ../net.rb, lines: !ruby/range 86..86}}</notextile>
 
-The @#parse!@ method of our @CommandParser@ object parses the given array of options (the second
-argument specifies if a command should be executed immediately or if the options should only be
-parsed). The @#execute@ method then executes the command.
+The @parse@ method of our @CommandParser@ instance parses the given array of options (or @ARGV@ if
+no argument is specified). All the command line options are parsed and the given command executed.
 
-The program can be executed now but won't be useful as we have not specified any commands. It will
-always produce error messages.
+The program can be executed now but won't be useful as we did not specify any commands.
 
 h3. Defining commands
 
 So, as we have defined our @CommandParser@ object, we need to add some commands to it. First, we
 will add two predefined commands, namely the @help@ and the @version@ command.
 
-<notextile>{extract: {file: ../test.rb, lines: !ruby/range 39..40}}</notextile>
+<notextile>{extract: {file: ../net.rb, lines: !ruby/range 37..38}}</notextile>
 
 That was easy! Now you can execute the program and specify the commands @help@ or @version@.
 However, we want the program to do something "useful". Therefore we define a new command.
 
-<notextile>{extract: {file: ../test.rb, lines: !ruby/range 8..27}}</notextile>
+<notextile>{extract: {file: ../net.rb, lines: !ruby/range 41..44}}</notextile>
+
+This command is defined by using the default @Command@ class. First an instance is created
+assigning a name to the command and defining whether this command takes subcommands. Next we add a
+short description so that the @help@ command can produce something useful. And at last, we add this
+command to our @CommandParser@ instance.
+
+We specified that our @ipaddr@ command takes subcommands. So we have to define them, too:
+
+<notextile>{extract: {file: ../net.rb, lines: !ruby/range 46..78}}</notextile>
 
-The command specific options are initialized in the @#initialize@ method. These options are used by
-our @CommandParser@ object if, and only if, the command is specified on the command line. The
-@#description@ method describes the command and the @#execute@ is called when the command needs to
-be executed.
+We add three subcommands to the @ipaddr@ command: @add@, @del@ and @list@.
 
-This command has to be added to our @CommandParser@ object.
+The @add@ command is similar to the @ipaddr@ command. However, as the @add@ command does not take
+other commands, we have to define an execution block.
 
-<notextile>{extract: {file: ../test.rb, lines: !ruby/range 38..38}}</notextile>
+The @del@ command is similar to the @add@ command. As we want to be able to delete all IP addresses
+by issuing only one command, we add an option for this.
 
-By providing @true@ as second argument, we specifiy that the @test@ command should be the default
-command which gets invoked when no command is specified on the command line. Only one command can be
-specified as default command!
+By providing @true@ as second argument when we add the @list@ command to the @ipaddr@ command, we
+specifiy that this command should be the default command which gets invoked when no command name is
+specified on the command line. Only one command can be specified as default command!
+
+Till now we only used the basic @Command@ class to specify commands. However, new commands can also
+be created by subclassing the @Command@ class, as shown with this last command:
+
+<notextile>{extract: {file: ../net.rb, lines: !ruby/range 9..28}}</notextile>
+<notextile>{extract: {file: ../net.rb, lines: !ruby/range 39..39}}</notextile>
 
 h3. Running the program
 
 That's all! You can run the program now and have a look at the output which differs depending on
 which arguments you choose.
 
-*Notice:* Options, command name and additional arguments have to be in a certain order on the
-command line:
+So, a typical invocation of this program looks like this:
 
-# [optional] Global options
-# Command name
-# [optional] Command specific options
-# [optional] Additional arguments
+<pre>
+  $ ruby net.rb --verbose ipaddr add 192.168.0.1 193.150.0.1
+</pre>
 
-So, a typical invokation looks like this:
+* <notextile><tt>--verbose</tt></notextile> is a global option
+* @ipaddr@ is the first command name (which has no options)
+* @add@ is the second command name (which also has no options)
+* <tt>192.168.0.1 193.150.0.1</tt> are additional arguments
 
+You should notice that if you type
 <pre>
-  $ ruby test.rb -r myfunc test -a arg1 arg2 arg3
+  $ ruby net.rb
 </pre>
 
-* <tt>-r myfunc</tt> is a global option
-* @test@ is the command name
-* @-a@ is a command specific option (only available for the test command)
-* <tt>arg1 arg2 arg3</tt> are additional arguments
+you get an error because you did not specify any command.
+
+However, when you type
+<pre>
+  $ ruby net.rb ipaddr
+</pre>
+
+you do not get an error!
+
+Why? As the @ipaddr@ command takes subcommands there should be an additional command name (e.g.
+@list@) on the command line. However, as the @list@ command is the default command for @ipaddr@ you
+do not need to type it.
+
+*Notice:* The options of a command which does not take subcommands do not need to be at the front;
+they can be anywhere, like this
+<pre>
+  $ ruby test.rb --verbose mycommand file1 file2 --recursive file3
+</pre>

doc/src/download.page

@@ -7,28 +7,28 @@ h2. Download
 
 The newest version of cmdparse can be downloaded from Rubyforge.
 
-Homepage: <a href="http://cmdparse.rubyforge.org">cmdparse.rubyforge.org</a><br />
-Download: <a href="http://rubyforge.org/frs/?group_id=396">http://rubyforge.org/frs/?group_id=396</a>
+Homepage: "cmdparse.rubyforge.org":http://cmdparse.rubyforge.org <br />
+Download: "rubyforge.org/frs/?group_id=396":http://rubyforge.org/frs/?group_id=396
 
 h2. Dependencies
 
-optparse - part of the standard ruby distribution, so nothing to do here
+none
 
 h2. Installation
 
-You can use the standard way to install cmdparse:
+The preferred way of installing cmdparse is via RubyGems:
 <pre>
- $ ruby setup.rb config
- $ ruby setup.rb setup
- $ ruby setup.rb install
+ $ gem install cmdparse
 </pre>
 
-Or you could use Rake and substitute the above commands with this:
+If you do not have RubyGems installed, but Rake, you can use the following command:
 <pre>
  $ rake install
 </pre>
 
-Or you could install cmdparse the "GEM way":
+If you have neither RubyGems nor Rake, use these commands:
 <pre>
- $ gem install cmdparse
+ $ ruby setup.rb config
+ $ ruby setup.rb setup
+ $ ruby setup.rb install
 </pre>

doc/src/features.page

@@ -5,7 +5,7 @@ orderInfo: 3
 ---
 h2. Feature list
 
-* Based upon the standard library @optparse@
-* Default help and version commands
-* Each command is implemented via a class
-* As easy to use as @optparse@ itself!
+* Commands can have subcommands
+* Default commands for showing help and the version of the program
+* Option parsing library of choice can be used (after writing wrapper), default is @optparse@
+* Easy to use

doc/src/index.page

@@ -6,12 +6,23 @@ menuOrder: 1
 ---
 h2. Welcome
 
-... to the homepage of _*cmdparse*_, an advanced command line parser.
+... to the homepage of _*cmdparse*_, an advanced command line parser supporting commands.
 
 Have a look around the site!
 
 h2. News
 
+<b>2005-??-?? cmdparse 2.0.0 released!!!</b>
+
+This version is not compatible to previous versions of cmdparse as there have been major changes in
+the API. However, updating your code to use the new API is very easy!
+
+Changes:
+
+* Commands can now have subcommands which can have subcommands which can have subcommands...
+* No need to implement a whole new class for simple commands anymore
+* Default option parser library is @optparse@, however, any option parser library can be used after writing a small wrapper
+
 <b>2005-07-05 cmdparse 1.0.5 released!!!</b>
 
 Changes: