quickl 0.1.1

data/examples/delegate/lib/hello_world.rb

@@ -0,0 +1,39 @@
+class Delegate
+  #
+  # Say hello 
+  #
+  # SYNOPSIS
+  #   #{program_name} #{command_name} [--capitalize] [WHO]
+  #
+  # OPTIONS
+  # #{summarized_options}
+  #
+  # DESCRIPTION
+  #   Without any argument, says hello to the world. When a single argument 
+  #   is given says hello to the user.
+  #
+  class HelloWorld < Quickl::Command(__FILE__, __LINE__)
+  
+    # Install command options
+    options do |opt|
+
+      # Capitalize user name?
+      opt.on("--capitalize", "-c", "Capitalize user name") do 
+        @capitalize = true
+      end
+
+    end
+  
+    # Execute the command on some arguments
+    def execute(args)
+      if args.size <= 1
+        name = args.first || "world"
+        name = name.capitalize if @capitalize
+        puts "Hello #{name}!"
+      else
+        raise Quickl::InvalidArgument, "Useless arguments: #{args.join(' ')}"
+      end
+    end
+  
+  end # class HelloWorld
+end # class Delegate

data/examples/delegate/lib/help.rb

@@ -0,0 +1,24 @@
+class Delegate
+  # 
+  # Show help about a specific command
+  #
+  # SYNOPSIS
+  #   #{program_name} #{command_name} help COMMAND
+  #
+  class Help < Quickl::Command(__FILE__, __LINE__)
+    
+    # Let NoSuchCommandError be passed to higher stage
+    no_react_to Quickl::NoSuchCommand
+    
+    # Command execution
+    def execute(args)
+      if args.size != 1
+        puts super_command.help
+      else
+        cmd = has_command!(args.first, super_command)
+        puts cmd.help
+      end
+    end
+    
+  end # class Help
+end # class Delegate

data/examples/delegate/test/delegate_test.rb

@@ -0,0 +1,68 @@
+require 'test/unit'
+require 'stringio'
+begin 
+  require 'quickl'
+rescue LoadError
+  $LOAD_PATH.unshift File.expand_path('../../../../lib', __FILE__)
+  require 'quickl'
+end
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'delegate'
+
+class DelegateTest < Test::Unit::TestCase
+
+  def assert_exits(match, exit_code)  
+    yield
+    assert_false true, "Expected to exit with #{match}, nothing raised"
+  rescue Quickl::Exit => ex
+    assert_equal ex.exit_code, exit_code
+    assert ex.message =~ match
+  end
+  
+  def run_command(*args)
+    $stdout = StringIO.new
+    Delegate.no_react_to(Quickl::Exit)
+    Delegate.run args
+    $stdout.string
+  ensure
+    $stdout = STDOUT
+  end
+  
+  def test_alone
+    assert_exits(/Delegate execution to a sub command/, 0){ run_command }
+  end
+  
+  def test_help_option
+    assert_exits(/DESCRIPTION/, 0){ 
+      run_command("--help") 
+    }
+  end
+  
+  def test_version_option
+    assert_exits(/(c)/, 0){ 
+      run_command("--version") 
+    }
+  end
+  
+  def test_no_such_option
+    assert_exits(/invalid option/, -1){ 
+      run_command("--no-such-option") 
+    }
+  end
+  
+  def test_help_delegation
+    assert run_command("help", "hello-world") =~ /Say hello/
+  end
+  
+  def test_hello_delegation
+    assert_equal "Hello world!\n", run_command("hello-world")
+    assert_equal "Hello bob!\n", run_command("hello-world", "bob")
+  end
+  
+  def test_hello_capitalize
+    assert_equal "Hello World!\n", run_command("hello-world", "--capitalize")
+    assert_equal "Hello Bob!\n", run_command("hello-world", "bob", "--capitalize")
+  end
+  
+end
+

data/examples/hello/README.md

@@ -0,0 +1,74 @@
+# Quickl example: hello 
+
+This example shows how to create a really simple commandline program. 
+
+## Structure
+
+The structure it follows is simply:
+
+    #
+    # Short description here
+    #
+    # SYNOPSIS
+    #   Usage: ...
+    #
+    # OPTIONS
+    # #{sumarized_options}
+    #
+    # DESCRIPTION
+    #   Long description here...
+    #
+    class SimpleCommand < Quickl::Command(__FILE__, __LINE__)
+    
+      # install options below
+      options do |opt|
+        # _opt_ is an OptionParser instance
+      end
+      
+      # install the code to run the command
+      def execute(args)
+        # _args_ are non-option command line parameters
+      end
+    
+    end
+    
+    # To run the command, typically in a bin/simple_command 
+    # shell file
+    SimpleCommand.run(ARGV)
+    
+
+## Example
+
+Try the following:
+
+    ./hello 
+    # => Hello world!
+    
+    ./hello --capitalize
+    # => Hello World!
+
+    ./hello bob
+    # => Hello bob!
+    
+    ./hello --capitalize bob
+    # => Hello Bob!
+    
+    ./hello --version
+    # => hello 0.1.0 (c) 2010, Bernard Lambeau
+    
+    ./hello --help
+    # => ...
+    
+    ./hello too many arguments
+    # => needless argument: too many arguments
+    # => hello [--help] [--version] [--capitalize] [WHO]
+    
+    ./hello --no-such-option 
+    # invalid option: --no-such-option
+    # hello [--help] [--version] [--capitalize] [WHO]
+
+## You have to known that ...
+
+* An **instance** of command is actually executed. Therefore, it is safe to install instance variables through options and to use them in execute().
+* Documentation shown with --help is the rdoc documentation evaluated in the binding of the SimpleCommand **class**. Therefore, you can use #{...} to display specific things (like #{sumarized_options}).
+* Default error handlers are installed by default to catch Interrupt, Quickl::Exit and OptionParser::Error. See error_handling example to learn more about them.

data/examples/hello/hello

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+require File.expand_path('../../helper', __FILE__)
+
+#
+# Say hello 
+#
+# SYNOPSIS
+#   #{program_name} [--help] [--version] [--capitalize] [WHO]
+#
+# OPTIONS
+# #{summarized_options}
+#
+# DESCRIPTION
+#   Without any argument, says hello to the world. When a single argument 
+#   is given says hello to the user.
+#
+class Hello < Quickl::Command(__FILE__, __LINE__)
+  
+  # Command's version
+  VERSION = "0.1.0"
+  
+  # Install command options
+  options do |opt|
+
+    # Capitalize user name?
+    opt.on("--capitalize", "-c", "Capitalize user name") do 
+      @capitalize = true
+    end
+
+    # Show the help and exit
+    opt.on_tail("--help", "Show help") do
+      raise Quickl::Help
+    end
+
+    # Show version and exit
+    opt.on_tail("--version", "Show version") do
+      raise Quickl::Exit, "#{program_name} #{VERSION} (c) 2010, Bernard Lambeau"
+    end
+    
+  end
+  
+  # Execute the command on some arguments
+  def execute(args)
+    if args.size <= 1
+      name = args.first || "world"
+      name = name.capitalize if @capitalize
+      puts "Hello #{name}!"
+    else
+      raise Quickl::InvalidArgument, "Useless arguments: #{args.join(' ')}"
+    end
+  end
+  
+end # class Hello
+
+if __FILE__ == $0
+  Hello.run(ARGV)
+end

data/examples/hello/hello_test.rb

@@ -0,0 +1,65 @@
+require 'test/unit'
+require 'stringio'
+begin 
+  require 'quickl'
+rescue LoadError
+  $LOAD_PATH.unshift File.expand_path('../../../lib', __FILE__)
+  require 'quickl'
+end
+Kernel.load File.expand_path('../hello', __FILE__)
+
+class HelloTest < Test::Unit::TestCase
+    
+  def assert_exits(match, exit_code)  
+    yield
+    assert_false true, "Expected to exit with #{match}, nothing raised"
+  rescue Quickl::Exit => ex
+    assert_equal exit_code, ex.exit_code
+    assert ex.message =~ match
+  end
+  
+  def run_command(*args)
+    $stdout = StringIO.new
+    Hello.no_react_to(Quickl::Exit)
+    Hello.run args
+    $stdout.string
+  ensure
+    $stdout = STDOUT
+  end
+  
+  def test_normal_runs
+    assert_equal "Hello world!\n",    run_command
+    assert_equal "Hello blambeau!\n", run_command("blambeau")
+  end
+  
+  def test_capitalize
+    assert_equal "Hello World!\n",    run_command("--capitalize")
+    assert_equal "Hello Blambeau!\n", run_command("--capitalize", "blambeau")
+  end
+  
+  def test_version_option
+    assert_exits(/(c)/, 0){ 
+      run_command("--version") 
+    }
+  end
+  
+  def test_help_option
+    assert_exits(/DESCRIPTION/, 0){ 
+      run_command("--help") 
+    }
+  end
+  
+  
+  def test_no_such_option
+    assert_exits(/invalid option/, -1){ 
+      run_command("--no-such-option") 
+    }
+  end
+  
+  def test_too_many_arguments
+    assert_exits(/Useless arguments/, -1){ 
+      run_command('hello', 'too') 
+    }
+  end
+  
+end

data/examples/helper.rb

@@ -0,0 +1,6 @@
+begin 
+  require 'quickl'
+rescue LoadError
+  $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+  require 'quickl'
+end

data/lib/quickl.rb

@@ -0,0 +1,47 @@
+require 'quickl/ext/object'
+require 'quickl/errors'
+require 'quickl/ruby_tools'
+require 'quickl/naming'
+require 'quickl/command'
+module Quickl
+
+  # Quickl's VERSION
+  VERSION = '0.1.1'.freeze
+  
+  # Quickl's COPYRIGHT info 
+  COPYRIGHT = "(c) 2010, Bernard Lambeau"
+  
+  #
+  # Yields the block with the current command builder.
+  # A fresh new builder is created if not already done.
+  #
+  # This method is part of Quickl's private interface.
+  #
+  def self.command_builder 
+    @builder ||= Command::Builder.new
+    yield @builder if block_given?
+    @builder
+  end
+  
+  #
+  # Builds _command_ using the current builder. 
+  #
+  # The current command builder is considered consumed 
+  # and removed as a side effect. A RuntimeError is raised 
+  # if no builder is currently installed.
+  #
+  # Returns the command itself.
+  #
+  # This method is part of Quickl's private interface.
+  #
+  def self.build_command(command)
+    unless @builder
+      raise "No command builder currently installed"
+    else
+      @builder.run(command)
+      @builder = nil
+      command
+    end
+  end
+  
+end # module Quickl

data/lib/quickl/command.rb

@@ -0,0 +1,154 @@
+require 'optparse'
+module Quickl
+  class Command
+    extend Naming
+    
+    # Methods installed on all command classes
+    module ClassMethods
+      
+      # The super command, if any
+      attr_accessor :super_command
+      
+      # Command's summary
+      attr_accessor :doc_place
+      
+      # Returns the array of defined subcommands
+      def subcommands
+        @subcommands ||= []
+      end
+      
+      # Returns true if this command has at least one 
+      # subcommand
+      def has_sub_commands?
+        @subcommands and !@subcommands.empty?
+      end
+      
+      ############################################### Textual information about the command 
+      
+      # Returns name of the program under execution
+      def program_name
+        File.basename($0)
+      end
+      
+      # Returns command name
+      def command_name
+        module2command(self)
+      end
+      
+      # Loads and returns the documentation source
+      def doc_src
+        @doc_src ||= unless doc_place
+          "no documentation available" 
+        else
+          file, line = doc_place
+          RubyTools::extract_file_rdoc(file, line, true)
+        end
+      end
+      
+      # Returns command documentation
+      def documentation
+        @documentation ||= instance_eval("%Q{#{doc_src}}", *doc_place)
+      end
+      alias :help :documentation
+      
+      # Returns command usage
+      def usage
+        doc = documentation.split("\n")
+        doc.each_with_index{|line,i|
+          case line
+            when /Usage:/ 
+              return line.strip
+            when /SYNOPSIS/
+              return doc[i+1].strip || "no usage available"
+          end
+        } 
+        "no usage available"
+      end
+      
+      # Returns command overview
+      def overview
+        doc = documentation.split("\n")
+        doc.find{|s| !s.strip.empty?} || "no overview available"
+      end
+      
+      # Runs the command
+      def run(*args)
+        self.new.run(*args)
+      end
+      
+      ############################################### Error handling 
+      
+      # Bypass reaction to some exceptions
+      def no_react_to(*args)
+        @no_react_to ||= []
+        @no_react_to += args
+      end
+      
+      # Should I bypass reaction to a given error?
+      def no_react_to?(ex)
+        @no_react_to && @no_react_to.find{|c|
+          ex.is_a?(c)
+        }
+      end
+      
+      # Should I react to a given error?
+      def react_to?(ex)
+        !no_react_to?(ex)
+      end
+      
+    end # module ClassMethods
+    
+    # Methods installed on all command instances
+    module InstanceMethods
+
+      # Delegate unrecognized calls to the command class
+      # (gives access to options, help, usage, ...)
+      def method_missing(name, *args, &block)
+        if self.class.respond_to?(name)
+          self.class.send(name, *args, &block)
+        else
+          super
+        end
+      end
+      
+      # Handles a command error
+      def handle_error(ex)
+        if react_to?(ex)
+          begin
+            ex.command = self
+            ex.react!
+          rescue Quickl::Error => ex2
+            handle_error(ex2)
+          end
+        else
+          raise ex
+        end
+      end
+      
+      #
+      # Runs the command from a requester file with command-line
+      # arguments.
+      #
+      # This method is intended to be overriden and does nothing
+      # by default.
+      #
+      def run(argv)
+        _run(argv)
+      rescue Quickl::Error => ex
+        handle_error(ex)
+      end
+    
+    end # module InstanceMethods
+    
+    # Tracks child classes
+    def self.inherited(command)
+      Quickl.build_command(command)
+    end
+    
+  end # class Command
+end # module Quickl
+require 'quickl/command/builder'
+require 'quickl/command/robustness'
+require 'quickl/command/options'
+require 'quickl/command/single'
+require 'quickl/command/delegate'