quickl 0.1.1

data/lib/quickl/command/builder.rb

@@ -0,0 +1,58 @@
+module Quickl
+  class Command
+    class Builder
+      
+      # Adds document tracking information
+      def document(file, line)
+        @file, @line = file, line
+      end
+      
+      # Adds some command class modules
+      def class_modules(*mods)
+        @class_modules ||= [ 
+          Command::ClassMethods,
+          Command::Options::ClassMethods,
+        ]
+        @class_modules += mods
+      end
+      alias :class_module class_modules
+      
+      # Adds some command instance modules
+      def instance_modules(*mods)
+        @instance_modules ||= [ 
+          Command::InstanceMethods, 
+          Command::Robustness,
+          Command::Options::InstanceMethods
+        ]
+        @instance_modules += mods
+      end
+      alias :instance_module instance_modules
+      
+      # Installs on a command subclass
+      def run(command)
+        # install class and instance methods
+        class_modules.each{|mod|
+          command.extend(mod)
+        }
+        instance_modules.each{|mod|
+          command.instance_eval{ include mod } 
+        }
+      
+        # install documentation
+        if @file and @line
+          command.doc_place = [@file, @line]
+        end
+
+        # install hierarchy
+        parent = RubyTools::parent_module(command)
+        if parent && parent.ancestors.include?(Command)
+          command.super_command = parent
+          parent.subcommands << command
+        end
+      
+        command
+      end
+      
+    end # class Builder
+  end # class Command
+end # module Quickl

data/lib/quickl/command/delegate.rb

@@ -0,0 +1,53 @@
+module Quickl
+  module Command::Delegate
+    module InstanceMethods
+    
+      # Run the command by delegation
+      def _run(argv = [])
+        # My own options
+        my_argv = []
+        while argv.first =~ /^--/
+          my_argv << argv.shift
+        end
+        parse_options(my_argv)
+      
+        # Run the subcommand now
+        if cmd = argv.shift
+          has_command!(cmd).run(argv)
+        else
+          raise Quickl::Help.new(cmd.nil? ? 0 : -1)
+        end
+      end
+      
+    end
+    module ClassMethods
+      
+      def summarized_subcommands
+        doc = subcommands.collect{|cmd| 
+          [cmd.command_name, cmd.overview]
+        }
+        max = doc.inject(0){|memo,pair| 
+          l = pair.first.length
+          memo > l ? memo : l
+        }
+        doc.collect{|pair|
+          "  %-#{max}s     %s" % pair
+        }.join("\n")
+      end
+      
+    end
+  end # module Command::Delegate
+  
+  #
+  # Create a delegate command
+  #
+  def self.Delegate(*args)
+    command_builder do |b|
+      b.document *args
+      b.class_module    Command::Delegate::ClassMethods
+      b.instance_module Command::Delegate::InstanceMethods
+    end
+    Command
+  end
+  
+end # module Quickl

data/lib/quickl/command/options.rb

@@ -0,0 +1,55 @@
+module Quickl
+  module Command::Options
+    module ClassMethods
+      
+      # Installed options builders
+      attr_reader :option_builders
+    
+      # Builds an OptionParser instance
+      def build_options(scope = self)
+        OptionParser.new do |opt|
+          opt.program_name = File.basename $0
+          if const_defined?(:VERSION)
+            opt.version = const_get(:VERSION)
+          end
+          opt.summary_indent = ' ' * 2
+          (option_builders || []).each{|b| 
+            scope.instance_exec(opt, &b)
+          }
+        end
+      end
+      
+      # Without builder nor block, returns built options.
+      # Otherwise, adds a new option builder 
+      def options(builder = nil, &block)
+        if b = (builder || block)
+          @option_builders ||= []
+          @option_builders << b
+        else
+          build_options
+        end
+      end
+      
+      # Returns summarized options
+      def summarized_options
+        options.summarize.join.rstrip
+      end
+      
+    end # module ClassMethods
+    module InstanceMethods
+      
+      # Returns OptionParser instance
+      def options
+        @options ||= self.class.build_options(self)
+      end
+      
+      # Parses options
+      def parse_options(argv)
+        options.parse!(argv)
+      rescue OptionParser::ParseError => ex
+        raise Quickl::InvalidOption, ex.message, ex.backtrace
+      end
+      
+    end # module InstanceMethods
+  end # module Command::Options
+end # module Quickl

data/lib/quickl/command/robustness.rb

@@ -0,0 +1,18 @@
+module Quickl
+  class Command
+    module Robustness
+      include Naming
+      
+      # Checks that a command whose name is given exists
+      # or raises a NoSuchCommand.
+      def has_command!(name, referer = self.class)
+        name.split(':').inject(referer){|cur,look|
+          cur.const_get(command2module(look))
+        }
+      rescue NameError => ex
+        raise NoSuchCommand, "No such command #{name}", ex.backtrace
+      end
+      
+    end # module Robustness
+  end # class Command
+end # module Quickl

data/lib/quickl/command/single.rb

@@ -0,0 +1,27 @@
+module Quickl
+  
+  # Instance method for being a single command
+  module Command::Single
+    
+    # Command arguments after options parsing
+    attr_reader :args
+
+    # Run the command by delegation
+    def _run(argv = [])
+      execute(parse_options(argv))
+    end
+    
+  end # module Command::Delegate
+  
+  #
+  # Create a delegate command
+  #
+  def self.Command(*args)
+    command_builder do |b|
+      b.document *args
+      b.instance_module Command::Single
+    end
+    Command
+  end
+  
+end # module Quickl

data/lib/quickl/errors.rb

@@ -0,0 +1,196 @@
+module Quickl
+  
+  #
+  # Main class of all Quickl's errors.
+  #
+  # Quickl's errors normally occur only in the context of a command 
+  # execution, command which can be obtained through the dedicated 
+  # accessor.
+  #
+  # Each Quickl error comes bundled with a default reaction implemented 
+  # by the _react!_ method. Unless you provide your own reaction via
+  # dedicated Command's DSL methods (react_to, no_react_to, ...), this
+  # reaction will be executed if the error is raised. Default reactions
+  # are implemented so that the command fail gracefully for the ordinary 
+  # commandline user.
+  #
+  class Error < StandardError
+    
+    # Quickl command under execution
+    attr_accessor :command
+    
+    # Exit code
+    attr_reader :exit_code
+    
+    # Creates an Exit instance
+    def initialize(*args)
+      super(args.find{|s| s.is_a?(String)} || "")
+      @exit_code = args.find{|s| s.is_a?(Integer)} || nil
+    end
+    
+    # Returns true if exit code is not nil
+    def exit?
+      !exit_code.nil?
+    end
+    
+    # Returns $stdout or $stderr according to exit code.
+    def error_io
+      exit_code == -1 ? $stderr : $stdout
+    end
+    
+    # Print error's message on IO returned by error_io and
+    # make a call to Kernel.exit with required exit code.
+    def do_kernel_exit
+      error_io.puts self.message
+      Kernel.exit(exit_code) if exit?
+    end
+    
+  end # class Error
+  
+  #
+  # This error can be raised to exit command execution with a message
+  # and exit code. 
+  #
+  # Default exit code: 
+  #   0
+  # 
+  # Default reaction: 
+  #   Prints the error message (on $stdout if exit code is 0, on $stderr 
+  #   otherwise) then invoke Kernel.exit with the exit code.
+  #
+  # Examples:
+  #
+  #   # Non-failure exit, for --version, --help, --copyright and the 
+  #   # like
+  #   raise Quickl::Exit, "a friendly message"
+  #
+  #   # Failure exit, because something failed
+  #   raise Quickl::Exit.new(-1), "Something was wrong!"
+  #
+  class Exit < Error
+    
+    def initialize(*args)
+      super(*(args + [ 0 ]))
+    end
+    
+    def react!
+      do_kernel_exit
+    end
+    
+  end # class Exit
+  
+  # 
+  # This error can be raised to print command's help and exit.
+  #
+  # Default exit code: 
+  #   0
+  #
+  # Default reaction: 
+  #   raise Exit.new(code), additional + "\n" + help, backtrace
+  #
+  # Examples:
+  # 
+  #   # Print command help on $stdout and exit with 0
+  #   raise Quickl::Help
+  #
+  #   # Print command help on $stderr and exit with -1
+  #   raise Quickl::Help.new(-1)
+  # 
+  #   # Print additional message before help
+  #   raise Quickl::Help, "Hello user, below if the help!"
+  #
+  class Help < Error
+    
+    def initialize(*args)
+      super(*(args + [ 0 ]))
+    end
+    
+    def react!
+      msg = if (self.message || "").empty?
+        command.help
+      else
+        self.message.to_s + "\n" + command.help
+      end
+      raise Exit.new(self.exit_code), msg, backtrace
+    end
+    
+  end # class Help
+  
+  #
+  # This error can be raised to indicate that some command option
+  # was misused. This error is automatically raised on occurence
+  # of an OptionParser::ParseError when options are parsed.
+  #
+  # Default exit code:
+  #   -1
+  # 
+  # Default reaction: 
+  #   raise Help.new(code), message, backtrace
+  #
+  # Examples:
+  #
+  #   # Print message on $stderr and exit with -1
+  #   raise Quickl::InvalidOption, "--no-clue option does not exists" 
+  #
+  class InvalidOption < Error
+    
+    def initialize(*args)
+      super(*(args + [ -1 ]))
+    end
+    
+    def react!
+      raise Help.new(self.exit_code), self.message, backtrace
+    end
+    
+  end # class InvalidOption
+  
+  #
+  # This error can be raised to indicate that some command argument
+  # was misused.
+  #
+  # Default exit code:
+  #   -1
+  # 
+  # Default reaction: 
+  #   raise Help.new(code), message, backtrace
+  #
+  # Examples:
+  #
+  #   # Print message on $stderr and exit with -1
+  #   raise Quickl::InvalidArgument, "Missing command argument" 
+  #
+  class InvalidArgument < Error
+
+    def initialize(*args)
+      super(*(args + [ -1 ]))
+    end
+    
+    def react!
+      raise Help.new(self.exit_code), self.message, backtrace
+    end
+    
+  end # class InvalidArgument
+  
+  # 
+  # This error can be raised to indicate that a command has not been
+  # found (typically by delegates).
+  #
+  # Default exit code:
+  #   -1
+  # 
+  # Default reaction: 
+  #   raise Help.new(code), message, backtrace
+  #
+  class NoSuchCommand < Error 
+    
+    def initialize(*args)
+      super(*(args + [ -1 ]))
+    end
+    
+    def react!
+      raise Help.new(self.exit_code), self.message, backtrace
+    end
+    
+  end # class NoSuchCommand
+  
+end # module Quickl

data/lib/quickl/ext/object.rb

@@ -0,0 +1,29 @@
+class Object
+  # From active_support 2.3.4
+  unless defined? instance_exec # 1.9
+    module InstanceExecMethods #:nodoc:
+    end
+    include InstanceExecMethods
+
+    # Evaluate the block with the given arguments within the context of
+    # this object, so self is set to the method receiver.
+    #
+    # From Mauricio's http://eigenclass.org/hiki/bounded+space+instance_exec
+    def instance_exec(*args, &block)
+      begin
+        old_critical, Thread.critical = Thread.critical, true
+        n = 0
+        n += 1 while respond_to?(method_name = "__instance_exec#{n}")
+        InstanceExecMethods.module_eval { define_method(method_name, &block) }
+      ensure
+        Thread.critical = old_critical
+      end
+
+      begin
+        send(method_name, *args)
+      ensure
+        InstanceExecMethods.module_eval { remove_method(method_name) } rescue nil
+      end
+    end
+  end
+end

data/lib/quickl/naming.rb

@@ -0,0 +1,53 @@
+module Quickl
+  module Naming
+    
+    #
+    # Converts a command name to a module name. Implements
+    # the following conversions:
+    #
+    #   hello -> Hello
+    #   hello-world -> HelloWorld
+    #
+    # This method is part of Quickl's private interface even
+    # if its effect are considered public.
+    #
+    def command2module(name)
+      case name
+        when String
+          name.gsub(/^(.)|-(.)/){|x| x.upcase}.gsub(/-/,'')
+        when Symbol
+          command2module(name.to_s).to_sym
+        else
+          raise ArgumentError, "Invalid name argument #{name.class}"
+      end
+    end
+    
+    #
+    # Converts a module name to a command name. Implements the 
+    # following conversions:
+    #
+    #     Hello -> hello
+    #     HelloWorld -> hello-world
+    #
+    # This method is part of Quickl's private interface even
+    # if its effect are considered public.
+    #
+    def module2command(mod)
+      case mod
+        when Module
+          name = RubyTools::class_unqualified_name(mod)
+          name = name.gsub(/[A-Z]/){|x| "-#{x.downcase}"}[1..-1]
+        when String
+          name = mod.to_s
+          name = name.gsub(/[A-Z]/){|x| "-#{x.downcase}"}[1..-1]
+        when Symbol
+          name = mod.to_s
+          name = name.gsub(/[A-Z]/){|x| "-#{x.downcase}"}[1..-1]
+          name.to_sym
+        else
+          raise ArgumentError, "Invalid module argument #{mod.class}"
+      end
+    end
+    
+  end # module Naming
+end # module Quickl