cmdparse 1.0.2 → 1.0.3

data/ChangeLog

@@ -1,4 +1,44 @@
 ------------------------------------------------------------------------
+r291 | thomas | 2005-06-09 12:24:24 +0200 (Thu, 09 Jun 2005) | 1 line
+Changed paths:
+   M /trunk/cmdparse/doc/src/index.page
+
+* small docu change
+------------------------------------------------------------------------
+r290 | thomas | 2005-06-09 12:19:20 +0200 (Thu, 09 Jun 2005) | 1 line
+Changed paths:
+   M /trunk/cmdparse/doc/src/default.template
+
+
+------------------------------------------------------------------------
+r285 | thomas | 2005-05-21 14:05:54 +0200 (Sat, 21 May 2005) | 1 line
+Changed paths:
+   M /trunk/cmdparse/doc/src/default.template
+
+* added validation images to default.template
+------------------------------------------------------------------------
+r284 | thomas | 2005-05-21 13:16:15 +0200 (Sat, 21 May 2005) | 3 lines
+Changed paths:
+   M /trunk/cmdparse/README
+   M /trunk/cmdparse/Rakefile
+   M /trunk/cmdparse/TODO
+   A /trunk/cmdparse/doc/plugin
+   A /trunk/cmdparse/doc/plugin/extract.rb
+   A /trunk/cmdparse/doc/src/about.page
+   M /trunk/cmdparse/doc/src/default.css
+   M /trunk/cmdparse/doc/src/default.template
+   A /trunk/cmdparse/doc/src/documentation.page
+   M /trunk/cmdparse/doc/src/download.page
+   M /trunk/cmdparse/doc/src/features.page
+   M /trunk/cmdparse/doc/src/index.page
+   M /trunk/cmdparse/doc/src/meta.info
+   M /trunk/cmdparse/lib/cmdparse.rb
+   M /trunk/cmdparse/test.rb
+
+* added optional graceful exception handling to CommandParser
+* added two doc pages: about.page and documentation.page
+* uniformed naming: only <cmdparse> valid anymore
+------------------------------------------------------------------------
 r265 | thomas | 2005-04-21 12:57:51 +0200 (Thu, 21 Apr 2005) | 1 line
 Changed paths:
    M /trunk/cmdparse/doc/src/index.page

data/README

@@ -36,7 +36,7 @@ You can build the documentation by invoking
  $ rake doc
 
 This builds the API and the additional documentation. The additional documentation needs webgen
->=0.3.2 (webgen.rubyforge.org) for building.
+>=0.3.4 (webgen.rubyforge.org) for building.
 
 
 = Example

data/Rakefile

@@ -70,9 +70,9 @@ end
 CLOBBER << "doc/output"
 desc "Builds the documentation"
 task :doc => [:rdoc] do
-  Dir.chdir("doc")
-  sh "webgen -V 3"
-  Dir.chdir("..")
+  chdir "doc" do
+    sh "webgen"
+  end
 end
 
 rd = Rake::RDocTask.new do |rdoc|
@@ -94,6 +94,7 @@ PKG_FILES = FileList.new( [
                             'README',
                             'Rakefile',
                             'ChangeLog',
+                            'test.rb',
                             'VERSION',
                             'lib/**/*.rb',
                             'doc/**/*'

data/TODO

@@ -5,3 +5,4 @@
 * raise NoCommandGivenError when no command was given
 * 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

data/VERSION

@@ -1 +1 @@
-1.0.2
+1.0.3

data/doc/plugin/extract.rb

@@ -0,0 +1,29 @@
+module CmdparsePlugins
+
+  class ExtractTag < Tags::DefaultTag
+
+    summary "Extracts lines from a file"
+    depends_on 'Tags'
+    add_param 'file', nil, 'the file from which to read the lines'
+    add_param 'lines', nil, 'the lines which should be read (Range)'
+    set_mandatory 'file'
+    set_mandatory 'lines'
+
+    def initialize
+      super
+      @processOutput = false
+      register_tag( 'extract' )
+    end
+
+    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 << '</tr></table>'
+      out
+    end
+
+  end
+
+end

data/doc/src/about.page

@@ -0,0 +1,20 @@
+---
+title: About
+inMenu: true
+orderInfo: 2
+---
+h2. About @cmdparse@
+
+Some new programs use a "command style" command line. Examples for such programs are the "svn"
+program from Subversion and the "gem" program from Rubygems. The standard Ruby distribution has no
+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.
+
+h2. Author
+
+* *Thomas Leitner*
+* Web: "http://cmdparse.rubyforge.org":http://cmdparse.rubyforge.org
+* e-Mail: "t_leitner@gmx.at":mailto:t_leitner@gmx.at
+* GPG Key-Id: 0xD942E7F6

data/doc/src/default.css

@@ -143,4 +143,9 @@
   .webgen-gallery table td{
     text-align: center;
     border: 1px solid black;
-  }
+  }
+
+  table.cmdparse-example td {
+    border: 1px solid #408040;
+    background-color: white;
+  }

data/doc/src/default.template

@@ -2,7 +2,7 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="{lang:}">
   <head>
-    <title>CommandParser: {title:}</title>
+    <title>cmdparse: {title:}</title>
     <link href="{relocatable: default.css}" rel="stylesheet" />
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   </head>
@@ -13,7 +13,7 @@
         <table>
           <tr>
             <td><img src="{relocatable: logo.png}" alt="Logo" title="Logo" /></td>
-            <td><h1>CommandParser<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 which supports commands</span></h1>
             </td>
           </tr>
         </table>
@@ -34,7 +34,9 @@
       </div>
 
       <div id="footer" class="bar">
-        generated with <em><b><a href="http://webgen.rubyforge.org"><em><b>webgen</b></em></a></b></em> on <b>{date: }</b>
+        <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>
       </div>
     </div>
   </body>

data/doc/src/documentation.page

@@ -0,0 +1,91 @@
+---
+title: Documentation
+inMenu: true
+orderInfo: 6
+---
+h2. Documentation
+
+The <a href="{relocatable: /rdoc/index.html}">API reference</a> provides information on how to use
+@cmdparse@. Here is only a short tutorial which shows most of the features.
+
+h2. Tutorial
+
+<b>The complete code for this example can be found in the file @test.rb@ of the @cmdparse@
+package!</b>
+
+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>
+
+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.
+
+<notextile>{extract: {file: ../test.rb, lines: !ruby/range 29..37}}</notextile>
+
+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>
+
+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 program can be executed now but won't be useful as we have not specified any commands. It will
+always produce error messages.
+
+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>
+
+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>
+
+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.
+
+This command has to be added to our @CommandParser@ object.
+
+<notextile>{extract: {file: ../test.rb, lines: !ruby/range 38..38}}</notextile>
+
+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!
+
+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:
+
+# [optional] Global options
+# Command name
+# [optional] Command specific options
+# [optional] Additional arguments
+
+So, a typical invokation looks like this:
+
+<pre>
+  $ ruby test.rb -r myfunc test -a arg1 arg2 arg3
+</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

data/doc/src/download.page

@@ -1,7 +1,7 @@
 ---
 title: Download & Installation
 inMenu: true
-menuOrder: 3
+orderInfo: 4
 ---
 h2. Download
 

data/doc/src/features.page

@@ -1,7 +1,7 @@
 ---
 title: Features
 inMenu: true
-menuOrder: 5
+orderInfo: 3
 ---
 h2. Feature list
 

data/doc/src/index.page

@@ -1,24 +1,31 @@
 ---
 title: HomePage
 inMenu: true
-directoryName: CommandParser
+directoryName: cmdparse
 menuOrder: 1
 ---
 h2. Welcome
 
-... to the homepage of _*CommandParser*_, an advanced command line parser.
+... to the homepage of _*cmdparse*_, an advanced command line parser.
 
 Have a look around the site!
 
 h2. News
 
-<b>cmdparse 1.0.2 released!!!</b>
+<b>2005-06-09 cmdparse 1.0.3 released!!!</b>
+
+Changes:
+
+* added optional graceful exception handling
+
+
+<b>2005-04-21 cmdparse 1.0.2 released!!!</b>
 
 Changes:
 
 * splitted parsing of the arguments and executing the command into two methods
 
-<b>cmdparse 1.0.1 released!!!</b>
+<b>2005-04-13 cmdparse 1.0.1 released!!!</b>
 
 Changes:
 
@@ -26,15 +33,6 @@ Changes:
 * Possibility to define a default command which is used when no command was specified
 * A @NoCommandGivenError@ is thrown when no command on the CLI and no default command was specified
 
-h2. Description
-
-Some new programs use a "command style" command line. Examples for such programs are the "svn"
-program from Subversion and the "gem" program from Rubygems. The standard Ruby distribution has no
-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.
-
 h2. And so
 
 ... have fun!

data/doc/src/meta.info

@@ -1,6 +1,5 @@
 api.html:
-  en:
     dest: rdoc/index.html
     title: API Reference
-    menuOrder: 7
+    orderInfo: 7
     inMenu: true

data/lib/cmdparse.rb

@@ -1,7 +1,7 @@
 #
 #--
 #
-# $Id: cmdparse.rb 246 2005-04-13 13:36:19Z thomas $
+# $Id: cmdparse.rb 284 2005-05-21 11:16:15Z thomas $
 #
 # cmdparse: an advanced command line parser using optparse which supports commands
 # Copyright (C) 2004 Thomas Leitner
@@ -27,6 +27,9 @@ require 'optparse'
 # Some extension to the standard option parser class
 class OptionParser
 
+  Officious.delete( 'version' )
+  Officious.delete( 'help' )
+
   # Returns the <tt>@banner</tt> value. Needed because the method <tt>OptionParser#banner</tt> does
   # not return the internal value of <tt>@banner</tt> but a modified one.
   def get_banner
@@ -99,7 +102,7 @@ end
 class CommandParser
 
   # The version of the command parser
-  VERSION = [1, 0, 2]
+  VERSION = [1, 0, 3]
 
   # This error is thrown when an invalid command is encountered.
   class InvalidCommandError < OptionParser::ParseError
@@ -216,7 +219,7 @@ class CommandParser
       width = commandParser.commands.keys.max {|a,b| a.length <=> b.length }.length
       commandParser.commands.sort.each do |name, command|
         print commandParser.options.summary_indent + name.ljust( width + 4 ) + command.description
-        print " (default)" if name == commandParser.default
+        print " (=default command)" if name == commandParser.default
         print "\n"
       end
       puts ""
@@ -268,15 +271,23 @@ class CommandParser
 
   end
 
-  # Holds the registered commands
+  # Holds the registered commands.
   attr_reader :commands
+
+  # Returns the name of the default command.
   attr_reader :default
 
-  def initialize
+  # Are Exceptions be handled gracefully? I.e. by printing error message and help screen?
+  attr_reader :handleExceptions
+
+  # Create a new CommandParser object. The optional argument +handleExceptions+ specifies if the
+  # object should handle exceptions gracefully.
+  def initialize( handleExceptions = false )
     @options = OptionParser.new
     @commands = {}
     @default = nil
     @parsed = {}
+    @handleExceptions = handleExceptions
   end
 
   # If called with a block, this method yields the global options of the +CommandParser+. If no
@@ -314,18 +325,30 @@ class CommandParser
   # is true, the command is executed immediately. If false, the +CommandParser#execute+ has to be
   # called to execute the command.
   def parse!( args, execCommand = true )
-    @options.order!( args )
-    @parsed[:command] = args.shift
-    if @parsed[:command].nil?
-      if @default.nil?
-        raise NoCommandGivenError
+    # parse global options
+    begin
+      @options.order!( args )
+      @parsed[:command] = args.shift
+      if @parsed[:command].nil?
+        if @default.nil?
+          raise NoCommandGivenError
+        else
+          @parsed[:command] = @default
+        end
       else
-        @parsed[:command] = @default
+        raise InvalidCommandError.new( @parsed[:command] ) unless commands.include?( @parsed[:command] )
       end
-    else
-      raise InvalidCommandError.new( @parsed[:command] ) unless commands.include?( @parsed[:command] )
+    rescue OptionParser::ParseError => e
+      handle_exception( e, :global )
     end
-    commands[@parsed[:command]].options.permute!( args ) unless commands[@parsed[:command]].options.nil?
+
+    # parse local options
+    begin
+      commands[@parsed[:command]].options.permute!( args ) unless commands[@parsed[:command]].options.nil?
+    rescue OptionParser::ParseError => e
+      handle_exception( e, :local )
+    end
+
     @parsed[:args] = args
     execute if execCommand
   end
@@ -335,5 +358,16 @@ class CommandParser
     commands[@parsed[:command]].execute( self, @parsed[:args] ) if @parsed[:command]
   end
 
+  private
+
+  def handle_exception( exception, context )
+    raise unless @handleExceptions
+    s = (context == :global ? "global" : "command specific")
+    puts "Error parsing #{s} options:\n    " + exception.message
+    puts
+    commands['help'].execute( self, (context == :global ? [] : [@parsed[:command]]) ) if commands['help']
+    exit
+  end
+
 end
 

data/test.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# if something is changed here -> change line numbers in doc/src/documentation.page
+$:.unshift "lib"
+require 'cmdparse'
+require 'ostruct'
+
+
+class TestCommand < CommandParser::Command
+  def initialize
+    super('test')
+    @internal = OpenStruct.new
+    @internal.function = nil
+    @internal.audible = false
+    options.separator "Options:"
+    options.on("-t", "--test FUNCTION", "Test only FUNCTION") do |func|
+      @internal.function = func
+    end
+    options.on("-a", "--[no-]audible", "Run audible") { |@internal.audible| }
+  end
+  def description
+    "Executes various tests"
+  end
+  def execute( commandParser, args )
+    puts "Additional arguments: "+ args.inspect
+    puts "Internal values: " + @internal.inspect
+  end
+end
+
+cmd = CommandParser.new(true)
+cmd.options do |opt|
+  opt.program_name = "test.rb"
+  opt.version = [0, 1, 0]
+  opt.release = "1.0"
+  opt.separator "Global options:"
+  opt.on("-r", "--require TEST",  "Require the TEST") {|t| puts "required: #{t}"}
+  opt.on("--delay N", Integer, "Delay test for N seconds before executing") {|d| puts "delay: #{d}"}
+end
+cmd.add_command TestCommand.new, true
+cmd.add_command CommandParser::HelpCommand.new
+cmd.add_command CommandParser::VersionCommand.new
+cmd.parse!( ARGV, false )
+cmd.execute

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.6
 specification_version: 1
 name: cmdparse
 version: !ruby/object:Gem::Version 
-  version: 1.0.2
-date: 2005-04-21
+  version: 1.0.3
+date: 2005-06-09
 summary: An advanced command line parser using optparse which supports commands
 require_paths: 
   - lib
@@ -35,16 +35,21 @@ files:
   - README
   - Rakefile
   - ChangeLog
+  - test.rb
   - VERSION
   - lib/cmdparse.rb
   - doc/src
+  - doc/plugin
   - doc/src/default.css
   - doc/src/features.page
   - doc/src/index.page
+  - doc/src/about.page
   - doc/src/download.page
   - doc/src/default.template
   - doc/src/meta.info
   - doc/src/logo.png
+  - doc/src/documentation.page
+  - doc/plugin/extract.rb
 test_files: []
 rdoc_options: 
   - "--line-numbers"