cri 1.0.1 → 2.0a1

data/NEWS.md

@@ -0,0 +1,18 @@
+Cri News
+========
+
+2.0
+---
+
+* Added DSL
+* Added support for nested commands
+
+1.0.1
+-----
+
+* Made gem actually include code. D'oh.
+
+1.0.0
+-----
+
+* Initial release!

data/README.md

@@ -0,0 +1,15 @@
+Cri
+===
+
+Cri is a library for building easy-to-use commandline tools.
+
+Contributors
+------------
+
+(In alphabetical order)
+
+* Toon Willems
+
+Thanks for Lee “injekt” Jarvis for [Slop][1], which has inspired the design of Cri 2.0.
+
+[1]: https://github.com/injekt/slop

data/Rakefile

@@ -1,3 +1,5 @@
+# encoing: utf-8
+
 ##### Requirements
 
 # Rake etc
@@ -8,22 +10,18 @@ require 'minitest/unit'
 $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/lib'))
 require 'cri'
 
-##### Packaging
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |s|
-    s.name        = "cri"
-    s.summary     = "Cri is a library for building easy-to-use commandline tools."
-    s.description = "Cri is a library for building easy-to-use commandline tools."
+##### Documentation
 
-    s.authors     = [ 'Denis Defreyne' ]
-    s.email       = "denis.defreyne@stoneship.org"
+require 'yard'
 
-    s.files       = FileList['[A-Z]*', 'lib/**/*']
-  end
-rescue LoadError
-  warn "Jeweler (or a dependency) is not available. Install it with `gem install jeweler`"
+YARD::Rake::YardocTask.new(:doc) do |yard|
+  yard.files   = Dir['lib/**/*.rb']
+  yard.options = [
+    '--markup',        'markdown',
+    '--readme',        'README.md',
+    '--files',         'NEWS.md,LICENSE',
+    '--output-dir',    'doc/yardoc',
+  ]
 end
 
 ##### Testing
@@ -32,10 +30,12 @@ desc 'Runs all tests'
 task :test do
   ENV['QUIET'] ||= 'true'
 
-  $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/..'))
+  $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__)))
 
   MiniTest::Unit.autorun
 
+  require 'test/helper.rb'
+
   test_files = Dir['test/test_*.rb']
   test_files.each { |f| require f }
 end

data/cri.gemspec

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+$LOAD_PATH.unshift(File.expand_path('../lib/', __FILE__))
+require 'cri'
+
+Gem::Specification.new do |s|
+  s.name        = 'cri'
+  s.version     = Cri::VERSION
+  s.homepage    = 'http://stoneship.org/software/cri/' # TODO CREATE A WEB SITE YOU SILLY PERSON
+  s.summary     = 'a library for building easy-to-use commandline tools'
+  s.description = 'Cri allows building easy-to-use commandline interfaces with support for subcommands.'
+
+  s.author = 'Denis Defreyne'
+  s.email  = 'denis.defreyne@stoneship.org'
+
+  s.files              = Dir['[A-Z]*'] +
+                         Dir['{lib,test}/**/*'] +
+                         [ 'cri.gemspec', '.gemtest' ]
+  s.require_paths      = [ 'lib' ]
+
+  s.rdoc_options     = [ '--main', 'README.md' ]
+  s.extra_rdoc_files = [ 'ChangeLog', 'LICENSE', 'README.md', 'NEWS.md' ]
+end

data/lib/cri.rb

@@ -1,12 +1,16 @@
+# encoding: utf-8
+
 module Cri
 
   # The current Cri version.
-  VERSION = '1.0'
+  VERSION = '2.0a1'
+
+  autoload 'Command',           'cri/command'
+  autoload 'CommandDSL',        'cri/command_dsl'
+  autoload 'OptionParser',      'cri/option_parser'
 
 end
 
-# Load Cri
-require 'cri/base'
-require 'cri/command'
+require 'set'
+
 require 'cri/core_ext'
-require 'cri/option_parser'

data/lib/cri/command.rb

@@ -1,65 +1,216 @@
+# encoding: utf-8
+
 module Cri
 
   # Cri::Command represents a command that can be executed on the commandline.
-  # It is an abstract superclass for all commands.
+  # It is also used for the commandline tool itself.
   class Command
 
-    attr_accessor :base
+    # Delegate used for partitioning the list of arguments and options. This
+    # delegate will stop the parser as soon as the first argument, i.e. the
+    # command, is found.
+    #
+    # @api private
+    class OptionParserPartitioningDelegate
+
+      # Returns the last parsed argument, which, in this case, will be the
+      # first argument, which will be either nil or the command name.
+      #
+      # @return [String] The last parsed argument.
+      attr_reader :last_argument
+
+      # Called when an option is parsed.
+      #
+      # @param [Symbol] key The option key (derived from the long format)
+      #
+      # @param value The option value
+      #
+      # @param [Cri::OptionParser] option_parser The option parser
+      #
+      # @return [void]
+      def option_added(key, value, option_parser)
+      end
+
+      # Called when an argument is parsed.
+      #
+      # @param [String] argument The argument
+      #
+      # @param [Cri::OptionParser] option_parser The option parser
+      #
+      # @return [void]
+      def argument_added(argument, option_parser)
+        @last_argument = argument
+        option_parser.stop
+      end
+
+    end
+
+    # @todo Document
+    attr_accessor :supercommand
+
+    # @todo document
+    attr_accessor :commands
+    alias_method :subcommands, :commands
+
+    # @todo Document
+    attr_accessor :name
+
+    # @todo Document
+    attr_accessor :aliases
+
+    # @todo Document
+    attr_accessor :short_desc
 
-    # Returns a string containing the name of thi command. Subclasses must
-    # implement this method.
-    def name
-      raise NotImplementedError.new("Command subclasses should override #name")
+    # @todo Document
+    attr_accessor :long_desc
+
+    # @todo Document
+    attr_accessor :usage
+
+    # @todo Document
+    attr_accessor :option_definitions
+
+    # @todo Document
+    attr_accessor :block
+
+    # @todo Document
+    def self.define(string=nil, &block)
+      dsl = Cri::CommandDSL.new
+      if block
+        dsl.instance_eval(&block)
+      else
+        dsl.instance_eval(string)
+      end
+      dsl.command
+    end
+
+    # @todo Document
+    def self.new_basic_root
+      filename = File.dirname(__FILE__) + '/commands/basic_root.rb'
+      self.define(File.read(filename))
     end
 
-    # Returns an array of strings containing the aliases for this command.
-    # Subclasses must implement this method.
-    def aliases
-      raise NotImplementedError.new("Command subclasses should override #aliases")
+    # @todo Document
+    def self.new_basic_help
+      filename = File.dirname(__FILE__) + '/commands/basic_help.rb'
+      self.define(File.read(filename))
     end
 
-    # Returns a string containing this command's short description, which
-    # should not be longer than 50 characters. Subclasses must implement this
-    # method.
-    def short_desc
-      raise NotImplementedError.new("Command subclasses should override #short_desc")
+    def initialize
+      @aliases            = Set.new
+      @commands           = Set.new # TODO make this a hash (name -> cmd)
+      @option_definitions = Set.new
     end
 
-    # Returns a string containing this command's complete description, which
-    # should explain what this command does and how it works in detail.
-    # Subclasses must implement this method.
-    def long_desc
-      raise NotImplementedError.new("Command subclasses should override #long_desc")
+    # @todo Document
+    def modify(&block)
+      dsl = Cri::CommandDSL.new(self)
+      dsl.instance_eval(&block)
+      self
     end
 
-    # Returns a string containing this command's usage. Subclasses must
-    # implement this method.
-    def usage
-      raise NotImplementedError.new("Command subclasses should override #usage")
+    # @todo Document
+    def global_option_definitions
+      res = Set.new
+      res.merge(option_definitions)
+      res.merge(supercommand.global_option_definitions) if supercommand
+      res
     end
 
-    # Returns an array containing this command's option definitions. See the
-    # documentation for Cri::OptionParser for details on what option
-    # definitions look like. Subclasses may implement this method if the
-    # command has options.
-    def option_definitions
-      []
+    # @todo Document
+    def add_command(command)
+      @commands << command
+      command.supercommand = self
     end
 
-    # Executes the command. Subclasses must implement this method
-    # (obviously... what's the point of a command that can't be run?).
+    # @todo Document
+    def define_command(name=nil, &block)
+      # Execute DSL
+      dsl = Cri::CommandDSL.new
+      dsl.name name unless name.nil?
+      dsl.instance_eval(&block)
+
+      # Create command
+      cmd = dsl.command
+      self.add_command(cmd)
+      cmd
+    end
+
+    # Returns the commands that could be referred to with the given name. If
+    # the result contains more than one command, the name is ambiguous.
     #
-    # +options+:: A hash containing the parsed commandline options. For
-    #             example, '--foo=bar' will be converted into { :foo => 'bar'
-    #             }. See the Cri::OptionParser documentation for details.
+    # @todo Document
+    def commands_named(name)
+      # Find by exact name or alias
+      @commands.each do |cmd|
+        found = cmd.name == name || cmd.aliases.include?(name)
+        return [ cmd ] if found
+      end
+
+      # Find by approximation
+      @commands.select do |cmd|
+        cmd.name[0, name.length] == name
+      end
+    end
+
+    # Returns the command with the given name.
     #
-    # +arguments+:: An array of strings representing the commandline arguments
-    #               given to this command.
-    def run(options, arguments)
-      raise NotImplementedError.new("Command subclasses should override #run")
+    # @todo Document
+    def command_named(name)
+      commands = commands_named(name)
+
+      if commands.size < 1
+        $stderr.puts "#{self.name}: unknown command '#{name}'\n"
+        exit 1
+      elsif commands.size > 1
+        $stderr.puts "#{self.name}: '#{name}' is ambiguous:"
+        $stderr.puts "  #{commands.map { |c| c.name }.join(' ') }"
+        exit 1
+      else
+        commands[0]
+      end
+    end
+
+    # @todo Document
+    def run(opts_and_args, parent_opts={})
+      if subcommands.empty?
+        # Parse
+        parser = Cri::OptionParser.new(
+          opts_and_args, global_option_definitions)
+        self.handle_parser_errors_while { parser.run }
+        local_opts  = parser.options
+        global_opts = parent_opts.merge(parser.options)
+        args = parser.arguments
+
+        # Handle options
+        handle_options(local_opts)
+
+        # Execute
+        if @block.nil?
+          raise "No implementation available for '#{self.name}'"
+        end
+        self.instance_exec(global_opts, args, &block)
+      else
+        # Parse up to command name
+        stuff = partition(opts_and_args)
+        opts_before_cmd, cmd_name, opts_and_args_after_cmd = *stuff
+
+        # Handle options
+        handle_options(opts_before_cmd)
+
+        # Get command
+        if cmd_name.nil?
+          $stderr.puts "#{name}: no command given"
+          exit 1
+        end
+        command = command_named(cmd_name)
+
+        # Run
+        command.run(opts_and_args_after_cmd, opts_before_cmd)
+      end
     end
 
-    # Returns the help text for this command.
+    # @return [String] The help text for this command
     def help
       text = ''
 
@@ -80,14 +231,32 @@ module Cri
       text << "\n"
       text << long_desc.wrap_and_indent(78, 4) + "\n"
 
+      # Append subcommands
+      unless self.commands.empty?
+        text << "\n"
+        text << (self.supercommand ? 'subcommands' : 'commands') << ":\n"
+        text << "\n"
+        length = self.commands.inject(0) { |m,c| [ m, c.name.size ].max }
+        self.commands.each do |cmd|
+          text << sprintf("    %-#{length+4}s %s\n",
+            cmd.name,
+            cmd.short_desc)
+        end
+      end
+
       # Append options
-      all_option_definitions = base.global_option_definitions + option_definitions
-      unless all_option_definitions.empty?
+      defs = global_option_definitions.sort { |x,y| x[:long] <=> y[:long] }
+      unless defs.empty?
         text << "\n"
         text << "options:\n"
         text << "\n"
-        all_option_definitions.sort { |x,y| x[:long] <=> y[:long] }.each do |opt_def|
-          text << sprintf("    -%1s --%-10s %s\n", opt_def[:short], opt_def[:long], opt_def[:desc])
+        length = defs.inject(0) { |m,o| [ m, o[:long].size ].max }
+        defs.each do |opt_def|
+          text << sprintf(
+            "    -%1s --%-#{length+4}s %s\n",
+            opt_def[:short],
+            opt_def[:long],
+            opt_def[:desc])
         end
       end
 
@@ -100,6 +269,44 @@ module Cri
       self.name <=> other.name
     end
 
+  protected
+
+    def handle_options(opts)
+      opts.each_pair do |key, value|
+        opt_def = global_option_definitions.find { |o| o[:long] == key.to_s }
+        block = opt_def[:block]
+        self.instance_exec(value, &block) if block
+      end
+    end
+
+    def partition(opts_and_args)
+      # Parse
+      delegate = Cri::Command::OptionParserPartitioningDelegate.new
+      parser = Cri::OptionParser.new(opts_and_args, global_option_definitions)
+      parser.delegate = delegate
+      self.handle_parser_errors_while { parser.run }
+      parser
+
+      # Extract
+      [
+        parser.options,
+        delegate.last_argument,
+        parser.unprocessed_arguments_and_options
+      ]
+    end
+
+    def handle_parser_errors_while(&block)
+      begin
+        block.call
+      rescue Cri::OptionParser::IllegalOptionError => e
+        $stderr.puts "#{name}: illegal option -- #{e}"
+        exit 1
+      rescue Cri::OptionParser::OptionRequiresAnArgumentError => e
+        $stderr.puts "#{name}: option requires an argument -- #{e}"
+        exit 1
+      end
+    end
+
   end
 
 end