quickl 0.2.2 → 0.3.0

data/CHANGELOG.md

@@ -1,3 +1,85 @@
+# 0.3.0 / 2011-07-29
+
+* Upgrading from 0.2.x
+
+This release is mostly compatible with the 0.2.x branch, but may require a few 
+changes to your code to avoid deprecation warnings and prepare for 0.4.0 that 
+will break if yout don't. From the most to the less likely:
+
+  * If you originally copied the Help command from examples, please do it again
+    on the new version. The execute method of Help should be:
+
+      sup = Quickl.super_command(self)
+      sub = (args.size != 1) ? sup : Quickl.sub_command!(sup, args.first)
+      puts Quickl.help(sub)
+
+  * If you use `usage`, `help`, `overview` or any similar methods in the context
+    of a command (instance or class, except in rdoc-based documentation), please
+    use the equivalent module methods provided by Quickl.
+
+  * If you use methods provided by the Robustness module, notably valid_read_file!
+    and has_subcommand!, please use module methods provided by Quickl instead.
+
+  * If you override Command#_run, please now override Command#run instead.
+
+  * If you rescue SystemExit when executing Command#run, please now rescue 
+    Quickl::Error (or any subclass) instead. No change is required if you rescue
+    when executing Command.run, or if you don't rescue on errors at all.
+
+* Bug fixes
+
+  * A single dash option (e.g. -v) is now correctly recognized by a Delegator
+    command ("No such command -v" was previously raised) 
+
+* Enhancements
+
+  * Added Quickl.[command_name,super_command,sub_command,help,overview,usage,
+    documentation] as convenient query methods on commands and their hierarchy. 
+    These helpers work both on command instances and on command classes and will 
+    be part of the public API when stabilized (the same methods on the Command 
+    class should be considered private from now on; if you use them, please 
+    upgrade).
+
+  * Added Quickl.parse_commandline_args that converts a commandline string to
+    an ARGV array. This is mainly provided for testing purposes.
+
+  * Added Quickl.split_commandline_args to split ARGV on the "--" option 
+    separator
+
+  * Command#parse_options now accepts a second option that allows specifying
+    the behavior in presence of '--' option separators. Default behavior is
+    backward compatible and conforms to getopt(1). :keep and :split can be used
+    to keep separators in result, or split the latter on separators. Thanks to
+    Brian Candler for pointing to getopt(1) for specification.
+
+* Deprecations 
+
+The following methods are deprecated and will be removed in 0.4.0 (run with 
+ruby -w to see where refactoring is needed). Examples have been adapted and can 
+be copy-pasted safely.
+
+  * Command#method_missing auto-delegation from command instances to command 
+    classes is deprecated. Please use explicit calls to command methods on the 
+    class itself, or tools provided by the Quickl module itself.
+
+  * The robustness methods available in command instances, notably valid_read_file! 
+    and has_command! are deprecated and replaced by convenient helpers available 
+    as module methods of Quickl itself. The Robustness module will disappear in
+    0.4.0.
+
+* Possibly hurting changes to the internals
+
+  * An unused and undocumented `args` attribute (attr_reader) has been removed 
+    from Single commands instances.  
+
+  * No default behavior is implemented in Command#run anymore (call was 
+    previously delegated to _run and surrounded in a begin/rescue/end block). 
+    The method is now directly implemented in Single and Delegator subclasses. 
+    This may break your code if it redefines _run.
+    
+  * Error catching is done in Command.run instead of Command#run. The way to 
+    specify how to react to errors did not change.  
+
 # 0.2.2 / 2011.07.12
 
 * Enhancements

data/Gemfile.lock

@@ -1,34 +1,34 @@
 PATH
   remote: .
   specs:
-    quickl (0.2.2)
+    quickl (0.3.0)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    bluecloth (2.0.11)
+    bluecloth (2.1.0)
     diff-lcs (1.1.2)
     rake (0.9.2)
-    rspec (2.4.0)
-      rspec-core (~> 2.4.0)
-      rspec-expectations (~> 2.4.0)
-      rspec-mocks (~> 2.4.0)
-    rspec-core (2.4.0)
-    rspec-expectations (2.4.0)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
       diff-lcs (~> 1.1.2)
-    rspec-mocks (2.4.0)
+    rspec-mocks (2.6.0)
     wlang (0.10.2)
-    yard (0.6.8)
+    yard (0.7.2)
 
 PLATFORMS
   java
   ruby
 
 DEPENDENCIES
-  bluecloth (~> 2.0.9)
+  bluecloth (~> 2.1.0)
   bundler (~> 1.0)
   quickl!
   rake (~> 0.9.2)
-  rspec (~> 2.4.0)
-  wlang (~> 0.10.1)
-  yard (~> 0.6.4)
+  rspec (~> 2.6.0)
+  wlang (~> 0.10.2)
+  yard (~> 0.7.2)

data/bin/quickl

@@ -21,7 +21,7 @@ class Quickl::Main < Quickl::Command(__FILE__, __LINE__)
   OPTION_HELPERS = {
     :version => %q{
       opt.on_tail('--version', 'Show version and exit'){
-        raise Quickl::Exit, "#{program_name} #{VERSION}"
+        raise Quickl::Exit, "#{Quickl.program_name} #{VERSION}"
       }
     },
     :help => %q{
@@ -81,7 +81,7 @@ class Quickl::Main < Quickl::Command(__FILE__, __LINE__)
 
     # Show version and exit
     opt.on_tail("--version", "Show version") do
-      raise Quickl::Exit, "#{program_name} #{Quickl::VERSION} #{Quickl::COPYRIGHT}"
+      raise Quickl::Exit, "#{Quickl.program_name} #{Quickl::VERSION} #{Quickl::COPYRIGHT}"
     end
     
   end

data/lib/quickl.rb

@@ -8,7 +8,17 @@ require 'quickl/command'
 module Quickl
 
   # Quickl's COPYRIGHT info 
-  COPYRIGHT = "(c) 2010, Bernard Lambeau"
+  COPYRIGHT = "(c) 2010-2011, Bernard Lambeau"
+  
+  #
+  # Prints a deprecation message on STDERR if $VERBOSE is set to true
+  #
+  def self.deprecated(who, instead, caller)
+    if $VERBOSE
+      STDERR << "WARN (Quickl): #{who} is deprecated, use #{instead} "\
+                "(#{caller.first})\n"
+    end
+  end
   
   #
   # Yields the block with the current command builder.
@@ -43,4 +53,154 @@ module Quickl
     end
   end
   
-end # module Quickl
+  #
+  # Convenient method for <code>File.basename($0)</code>
+  #
+  def self.program_name
+    File.basename($0)
+  end
+
+  #
+  # When `cmd` is a class, returns it. When a command instance, returns 
+  # `cmd.class`. Otherwise, raises an ArgumentError.
+  #
+  def self.command_class(cmd)
+    case cmd
+    when Class
+      cmd
+    when Command
+      cmd.class
+    else
+      raise ArgumentError, "Not a recognized command #{cmd}"
+    end
+  end
+
+  #
+  # Returns the super command of `cmd`, or nil.
+  # 
+  def self.super_command(cmd)
+    command_class(cmd).super_command
+  end
+
+  #
+  # Returns the subcommand of `cmd` which is called `name`, or nil.
+  #
+  def self.sub_command(cmd, name)
+    command_class(cmd).subcommand_by_name(name)
+  end
+
+  #
+  # Returns the subcommand of `cmd` which is called `name`. Raises a 
+  # NoSuchCommand if not found.
+  #
+  def self.sub_command!(cmd, name)
+    unless subcmd = sub_command(cmd, name)
+      raise NoSuchCommand, "No such command #{name}" 
+    end
+    subcmd
+  end
+
+  #
+  # Convenient method for <code>command_class(cmd).command_name</code>
+  #
+  def self.command_name(cmd)
+    command_class(cmd).command_name
+  end
+
+  #
+  # Convenient method for <code>command_class(cmd).usage</code>
+  #
+  def self.usage(cmd)
+    command_class(cmd).usage
+  end
+
+  #
+  # Convenient method for <code>command_class(cmd).overview</code>
+  #
+  def self.overview(cmd)
+    command_class(cmd).overview
+  end
+  
+  #
+  # Convenient method for <code>command_class(cmd).documentation</code>
+  #
+  def self.documentation(cmd)
+    command_class(cmd).documentation
+  end
+  
+  #
+  # Alias for documentation
+  #
+  def self.help(cmd)
+    command_class(cmd).help
+  end
+  
+  #
+  # Checks that `file` is a readable file or raises an error. Returns `file` on 
+  # success.
+  #
+  # @param [String] file path to a file that should exists and be readable 
+  # @param [Class] error_class the error class to use on error 
+  #        (Quickl::IOAccessError by default)
+  # @param [String] msg a dedicated error message (a default one is provided)
+  # @return [String] file on success
+  #
+  def self.valid_read_file!(file, error_class = nil, msg = nil)
+    if File.file?(file) and File.readable?(file)
+      file
+    else
+      error_class ||= Quickl::IOAccessError
+      msg ||= "Not a file or not readable: #{file}"
+      raise error_class, msg, caller
+    end
+  end
+
+  #
+  # Parse a string with commandline arguments and returns an array.
+  #
+  # Example:
+  # 
+  #   parse_commandline_args("--text --size=10") # => ['--text', '--size=10']
+  #
+  def self.parse_commandline_args(args)
+    args = args.split(/\s+/)
+    result = []
+    until args.empty?
+      quote = ['"', "'"].find{|q| q == args.first[0,1]}
+      if quote
+        if args.first[-1,1] == quote
+          result << args.shift[1...-1]
+        else
+          block = [ args.shift[1..-1] ]
+          while args.first[-1,1] != quote
+            block << args.shift
+          end 
+          block << args.shift[0...-1]
+          result << block.join(" ")
+        end
+      else
+        result << args.shift
+      end  
+    end
+    result
+  end
+
+  #
+  # Splits an array `args` on '--' option separator. 
+  # 
+  def self.split_commandline_args(args)
+    args = args.dup
+    result, current = [], []
+    until args.empty?
+      if (x = args.shift) == "--"
+        result << current
+        current = []
+      else
+        current << x
+      end
+    end
+    result << current
+    result
+  end
+  
+end # module Quickl

data/lib/quickl/command.rb

@@ -39,7 +39,7 @@ module Quickl
       
       # Returns name of the program under execution
       def program_name
-        File.basename($0)
+        Quickl.program_name
       end
       
       # Returns command name
@@ -85,7 +85,10 @@ module Quickl
       
       # Runs the command
       def run(argv = [], requester = nil)
-        self.new.run(argv, requester)
+        cmd = self.new
+        cmd.run(argv, requester)
+      rescue Quickl::Error => ex
+        handle_error(ex, cmd)
       end
       
       ############################################### Error handling 
@@ -98,7 +101,7 @@ module Quickl
       
       # Should I bypass reaction to a given error?
       def no_react_to?(ex)
-        @no_react_to && @no_react_to.find{|c|
+        defined?(@no_react_to) && Array(@no_react_to).find{|c|
           ex.is_a?(c)
         }
       end
@@ -108,6 +111,20 @@ module Quickl
         !no_react_to?(ex)
       end
       
+      # Handles a command error
+      def handle_error(ex, cmd = self)
+        if react_to?(ex)
+          begin
+            ex.command = cmd
+            ex.react!
+          rescue Quickl::Error => ex2
+            handle_error(ex2, cmd)
+          end
+        else
+          raise ex
+        end
+      end
+  
     end # module ClassMethods
     
     # Methods installed on all command instances
@@ -120,40 +137,13 @@ module Quickl
       # (gives access to options, help, usage, ...)
       def method_missing(name, *args, &block)
         if self.class.respond_to?(name)
+          Quickl.deprecated(name, "self.class.#{name}", caller)
           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, requester = nil)
-        @requester = requester
-        _run(argv)
-      rescue Quickl::Error => ex
-        handle_error(ex)
-      end
-    
+
     end # module InstanceMethods
     
     # Tracks child classes

data/lib/quickl/command/builder.rb

@@ -56,16 +56,16 @@ module Quickl
         end
 
         # install hierarchy
-        parent = @parent || RubyTools::parent_module(command)
+        parent = (defined?(@parent) && @parent) || RubyTools::parent_module(command)
         if parent && parent.ancestors.include?(Command)
           command.super_command = parent
           parent.subcommands << command
         end
         
         # execute callbacks
-        @callbacks.each do |blk|
+        Array(@callbacks).each do |blk|
           blk.call(command)
-        end if @callbacks
+        end if defined?(@callbacks)
       
         command
       end

data/lib/quickl/command/delegator.rb

@@ -1,26 +1,36 @@
 module Quickl
+  
   module Command::Delegator
     module InstanceMethods
      
       # Run the command by delegation
-      def _run(argv = [])
-        # My own options
-        my_argv = []
-        while argv.first =~ /^--/
-          my_argv << argv.shift
-        end
+      def run(argv = [], requester = nil)
+        @requester = requester
+        my_argv, rest = split_argv(argv)
         parse_options(my_argv)
-        execute(argv)
+        execute(rest)
       end
       
       def execute(argv)
         if cmd = argv.shift
-          cmd = has_command!(cmd).run(argv, self)
+          Quickl.sub_command!(self, cmd).run(argv, self)
         else
           raise Quickl::Help.new(cmd.nil? ? 0 : -1)
         end
       end
       
+      private 
+      
+      def split_argv(argv)
+        my_argv = []
+        while (!argv.empty?) && 
+              (argv.first[0,1] == '-') && 
+              (argv.first != '--')
+          my_argv << argv.shift
+        end
+        [my_argv, argv]
+      end
+      
     end
     module ClassMethods
       
@@ -45,9 +55,9 @@ module Quickl
   #
   def self.Delegator(*args)
     command_builder do |b|
-      b.document *args
-      b.class_module    Command::Delegator::ClassMethods
-      b.instance_module Command::Delegator::InstanceMethods
+      b.document(*args)
+      b.class_module(Command::Delegator::ClassMethods)
+      b.instance_module(Command::Delegator::InstanceMethods)
       yield(b) if block_given?
     end
     Command
@@ -58,4 +68,4 @@ module Quickl
     self.Delegator(*args, &block)
   end
   
-end # module Quickl
+end # module Quickl