cri 1.0.0 → 1.0.1

data/NEWS

@@ -0,0 +1,9 @@
+= Cri News
+
+== 1.0.1
+
+* Made gem actually include code. D'oh.
+
+== 1.0.0
+
+* Initial release!

data/Rakefile

@@ -0,0 +1,43 @@
+##### Requirements
+
+# Rake etc
+require 'rake'
+require 'minitest/unit'
+
+# Cri itself
+$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."
+
+    s.authors     = [ 'Denis Defreyne' ]
+    s.email       = "denis.defreyne@stoneship.org"
+
+    s.files       = FileList['[A-Z]*', 'lib/**/*']
+  end
+rescue LoadError
+  warn "Jeweler (or a dependency) is not available. Install it with `gem install jeweler`"
+end
+
+##### Testing
+
+desc 'Runs all tests'
+task :test do
+  ENV['QUIET'] ||= 'true'
+
+  $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/..'))
+
+  MiniTest::Unit.autorun
+
+  test_files = Dir['test/test_*.rb']
+  test_files.each { |f| require f }
+end
+
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+1.0.1

data/lib/cri.rb

@@ -0,0 +1,12 @@
+module Cri
+
+  # The current Cri version.
+  VERSION = '1.0'
+
+end
+
+# Load Cri
+require 'cri/base'
+require 'cri/command'
+require 'cri/core_ext'
+require 'cri/option_parser'

data/lib/cri/base.rb

@@ -0,0 +1,153 @@
+module Cri
+
+  # Cri::Base is the central class representing a commandline tool. It has a
+  # list of commands.
+  class Base
+
+    # The CLI's list of commands (should also contain the help command)
+    attr_reader :commands
+
+    # The CLI's help command (required)
+    attr_accessor :help_command
+
+    # Creates a new instance of the commandline tool.
+    def initialize(tool_name)
+      @tool_name = tool_name
+
+      @commands = []
+    end
+
+    # Parses the given commandline arguments and executes the requested
+    # command.
+    def run(args)
+      # Check arguments
+      if args.length == 0
+        @help_command.run([], [])
+        exit 1
+      end
+
+      # Partition options
+      opts_before_command         = []
+      command_name                = nil
+      opts_and_args_after_command = []
+      stage = 0
+      args.each do |arg|
+        # Update stage if necessary
+        stage = 1 if stage == 0 && !is_option?(arg)
+
+        # Add
+        opts_before_command << arg         if stage == 0
+        command_name = arg                 if stage == 1
+        opts_and_args_after_command << arg if stage == 2
+
+        # Update stage if necessary
+        stage = 2 if stage == 1
+      end
+
+      # Handle options before command
+      begin
+        parsed_arguments = Cri::OptionParser.parse(opts_before_command, global_option_definitions)
+      rescue Cri::OptionParser::IllegalOptionError => e
+        $stderr.puts "illegal option -- #{e}"
+        exit 1
+      end
+      parsed_arguments[:options].keys.each do |option|
+        handle_option(option)
+      end
+
+      # Get command
+      if command_name.nil?
+        $stderr.puts "no command given"
+        exit 1
+      end
+      command = command_named(command_name)
+      if command.nil?
+        $stderr.puts "no such command: #{command_name}"
+        exit 1
+      end
+
+      # Parse arguments
+      option_definitions = command.option_definitions + global_option_definitions
+      begin
+        parsed_arguments = Cri::OptionParser.parse(opts_and_args_after_command, option_definitions)
+      rescue Cri::OptionParser::IllegalOptionError => e
+        $stderr.puts "illegal option -- #{e}"
+        exit 1
+      rescue Cri::OptionParser::OptionRequiresAnArgumentError => e
+        $stderr.puts "option requires an argument -- #{e}"
+        exit 1
+      end
+
+      # Handle global options
+      global_options = global_option_definitions.map { |o| o[:long] }
+      global_options.delete_if { |o| !parsed_arguments[:options].keys.include?(o.to_sym) }
+      global_options.each { |o| handle_option(o.to_sym) }
+
+      if parsed_arguments[:options].has_key?(:help)
+        # Show help for this command
+        show_help(command)
+      else
+        # Run command
+        command.run(parsed_arguments[:options], parsed_arguments[:arguments])
+      end
+    end
+
+    # Returns the command with the given name.
+    def command_named(name)
+      # Find by exact name or alias
+      command = @commands.find { |c| c.name == name or c.aliases.include?(name) }
+      return command unless command.nil?
+
+      # Find by approximation
+      commands = @commands.select { |c| c.name[0, name.length] == name }
+      if commands.length > 1
+        $stderr.puts "#{@tool_name}: '#{name}' is ambiguous:"
+        $stderr.puts "  #{commands.map { |c| c.name }.join(' ') }"
+        exit 1
+      elsif commands.length == 0
+        $stderr.puts "#{@tool_name}: unknown command '#{name}'\n"
+        show_help
+        exit 1
+      else
+        return commands[0]
+      end
+    end
+
+    # Shows the help text for the given command, or shows the general help
+    # text if no command is given.
+    def show_help(command=nil)
+      if command.nil?
+        @help_command.run([], [])
+      else
+        @help_command.run([], [ command.name ])
+      end
+    end
+
+    # Returns the list of global option definitions.
+    def global_option_definitions
+      []
+    end
+
+    # Adds the given command to the list of commands. Adding a command will
+    # also cause the command's +base+ to be set to this instance.
+    def add_command(command)
+      @commands << command
+      command.base = self
+    end
+
+    # Handles the given option.
+    def handle_option(option)
+      false
+    end
+
+  private
+
+    # Returns true if the given string is an option (i.e. -foo or --foo),
+    # false otherwise.
+    def is_option?(string)
+      string =~ /^-/
+    end
+
+  end
+
+end

data/lib/cri/command.rb

@@ -0,0 +1,105 @@
+module Cri
+
+  # Cri::Command represents a command that can be executed on the commandline.
+  # It is an abstract superclass for all commands.
+  class Command
+
+    attr_accessor :base
+
+    # Returns a string containing the name of thi command. Subclasses must
+    # implement this method.
+    def name
+      raise NotImplementedError.new("Command subclasses should override #name")
+    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")
+    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")
+    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")
+    end
+
+    # Returns a string containing this command's usage. Subclasses must
+    # implement this method.
+    def usage
+      raise NotImplementedError.new("Command subclasses should override #usage")
+    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
+      []
+    end
+
+    # Executes the command. Subclasses must implement this method
+    # (obviously... what's the point of a command that can't be run?).
+    #
+    # +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.
+    #
+    # +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")
+    end
+
+    # Returns the help text for this command.
+    def help
+      text = ''
+
+      # Append usage
+      text << usage + "\n"
+
+      # Append aliases
+      unless aliases.empty?
+        text << "\n"
+        text << "aliases: #{aliases.join(' ')}\n"
+      end
+
+      # Append short description
+      text << "\n"
+      text << short_desc + "\n"
+
+      # Append long description
+      text << "\n"
+      text << long_desc.wrap_and_indent(78, 4) + "\n"
+
+      # Append options
+      all_option_definitions = base.global_option_definitions + option_definitions
+      unless all_option_definitions.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])
+        end
+      end
+
+      # Return text
+      text
+    end
+
+    # Compares this command's name to the other given command's name.
+    def <=>(other)
+      self.name <=> other.name
+    end
+
+  end
+
+end

data/lib/cri/core_ext.rb

@@ -0,0 +1,8 @@
+module Cri::CoreExtensions
+end
+
+require 'cri/core_ext/string'
+
+class String
+  include Cri::CoreExtensions::String
+end

data/lib/cri/core_ext/string.rb

@@ -0,0 +1,41 @@
+module Cri::CoreExtensions
+
+  module String
+
+    # Word-wraps and indents the string.
+    #
+    # +width+:: The maximal width of each line. This also includes indentation,
+    #           i.e. the actual maximal width of the text is width-indentation.
+    #
+    # +indentation+:: The number of spaces to indent each wrapped line.
+    def wrap_and_indent(width, indentation)
+      # Split into paragraphs
+      paragraphs = self.split("\n").map { |p| p.strip }.reject { |p| p == '' }
+
+      # Wrap and indent each paragraph
+      paragraphs.map do |paragraph|
+        # Initialize
+        lines = []
+        line = ''
+
+        # Split into words
+        paragraph.split(/\s/).each do |word|
+          # Begin new line if it's too long
+          if (line + ' ' + word).length >= width
+            lines << line
+            line = ''
+          end
+
+          # Add word to line
+          line += (line == '' ? '' : ' ' ) + word
+        end
+        lines << line
+
+        # Join lines
+        lines.map { |l| ' '*indentation + l }.join("\n")
+      end.join("\n\n")
+    end
+
+  end
+
+end

data/lib/cri/option_parser.rb

@@ -0,0 +1,186 @@
+module Cri
+
+  # Cri::OptionParser is used for parsing commandline options.
+  class OptionParser
+
+    # Error that will be raised when an unknown option is encountered.
+    class IllegalOptionError < RuntimeError ; end
+
+    # Error that will be raised when an option without argument is
+    # encountered.
+    class OptionRequiresAnArgumentError < RuntimeError ; end
+
+    # Parses the commandline arguments in +arguments_and_options+, using the
+    # commandline option definitions in +definitions+.
+    #
+    # +arguments_and_options+ is an array of commandline arguments and
+    # options. This will usually be +ARGV+.
+    #
+    # +definitions+ contains a list of hashes defining which options are
+    # allowed and how they will be handled. Such a hash has three keys:
+    #
+    # :short:: The short name of the option, e.g. +a+. Do not include the '-'
+    #          prefix.
+    #
+    # :long:: The long name of the option, e.g. +all+. Do not include the '--'
+    #         prefix.
+    #
+    # :argument:: Whether this option's argument is required (:required),
+    #             optional (:optional) or forbidden (:forbidden).
+    #
+    # A sample array of definition hashes could look like this:
+    #
+    #     [
+    #       { :short => 'a', :long => 'all',  :argument => :forbidden },
+    #       { :short => 'p', :long => 'port', :argument => :required  },
+    #     ]
+    #
+    # During parsing, two errors can be raised:
+    #
+    # IllegalOptionError:: An unrecognised option was encountered, i.e. an
+    #                      option that is not present in the list of option
+    #                      definitions.
+    #
+    # OptionRequiresAnArgumentError:: An option was found that did not have a
+    #                                 value, even though this value was
+    #                                 required.
+    #
+    # What will be returned, is a hash with two keys, :arguments and :options.
+    # The :arguments value contains a list of arguments, and the :options
+    # value contains a hash with key-value pairs for each option. Options
+    # without values will have a +nil+ value instead.
+    #
+    # For example, the following commandline options (which should not be
+    # passed as a string, but as an array of strings):
+    #
+    #     foo -xyz -a hiss -s -m please --level 50 --father=ani -n luke squeak
+    #
+    # with the following option definitions:
+    #
+    #     [
+    #       { :short => 'x', :long => 'xxx',    :argument => :forbidden },
+    #       { :short => 'y', :long => 'yyy',    :argument => :forbidden },
+    #       { :short => 'z', :long => 'zzz',    :argument => :forbidden },
+    #       { :short => 'a', :long => 'all',    :argument => :forbidden },
+    #       { :short => 's', :long => 'stuff',  :argument => :optional  },
+    #       { :short => 'm', :long => 'more',   :argument => :optional  },
+    #       { :short => 'l', :long => 'level',  :argument => :required  },
+    #       { :short => 'f', :long => 'father', :argument => :required  },
+    #       { :short => 'n', :long => 'name',   :argument => :required  }
+    #     ]
+    #
+    # will be translated into:
+    #
+    #     {
+    #       :arguments => [ 'foo', 'hiss', 'squeak' ],
+    #       :options => {
+    #         :xxx    => true,
+    #         :yyy    => true,
+    #         :zzz    => true,
+    #         :all    => true,
+    #         :stuff  => true,
+    #         :more   => 'please',
+    #         :level  => '50',
+    #         :father => 'ani',
+    #         :name   => 'luke'
+    #       }
+    #     }
+    def self.parse(arguments_and_options, definitions)
+      # Don't touch original argument
+      unprocessed_arguments_and_options = arguments_and_options.dup
+
+      # Initialize
+      arguments = []
+      options   = {}
+
+      # Determines whether we've passed the '--' marker or not
+      no_more_options = false
+
+      loop do
+        # Get next item
+        e = unprocessed_arguments_and_options.shift
+        break if e.nil?
+
+        # Handle end-of-options marker
+        if e == '--'
+          no_more_options = true
+        # Handle incomplete options
+        elsif e =~ /^--./ and !no_more_options
+          # Get option key, and option value if included
+          if e =~ /^--([^=]+)=(.+)$/
+            option_key   = $1
+            option_value = $2
+          else
+            option_key    = e[2..-1]
+            option_value  = nil
+          end
+
+          # Find definition
+          definition = definitions.find { |d| d[:long] == option_key }
+          raise IllegalOptionError.new(option_key) if definition.nil?
+
+          if [ :required, :optional ].include?(definition[:argument])
+            # Get option value if necessary
+            if option_value.nil?
+              option_value = unprocessed_arguments_and_options.shift
+              if option_value.nil? || option_value =~ /^-/
+                if definition[:argument] == :required
+                  raise OptionRequiresAnArgumentError.new(option_key)
+                else
+                  unprocessed_arguments_and_options.unshift(option_value)
+                  option_value = true
+                end
+              end
+            end
+
+            # Store option
+            options[definition[:long].to_sym] = option_value
+          else
+            # Store option
+            options[definition[:long].to_sym] = true
+          end
+        # Handle -xyz options
+        elsif e =~ /^-./ and !no_more_options
+          # Get option keys
+          option_keys = e[1..-1].scan(/./)
+
+          # For each key
+          option_keys.each do |option_key|
+            # Find definition
+            definition = definitions.find { |d| d[:short] == option_key }
+            raise IllegalOptionError.new(option_key) if definition.nil?
+
+            if option_keys.length > 1 and definition[:argument] == :required
+              # This is a combined option and it requires an argument, so complain
+              raise OptionRequiresAnArgumentError.new(option_key)
+            elsif [ :required, :optional ].include?(definition[:argument])
+              # Get option value
+              option_value = unprocessed_arguments_and_options.shift
+              if option_value.nil? || option_value =~ /^-/
+                if definition[:argument] == :required
+                  raise OptionRequiresAnArgumentError.new(option_key)
+                else
+                  unprocessed_arguments_and_options.unshift(option_value)
+                  option_value = true
+                end
+              end
+
+              # Store option
+              options[definition[:long].to_sym] = option_value
+            else
+              # Store option
+              options[definition[:long].to_sym] = true
+            end
+          end
+        # Handle normal arguments
+        else
+          arguments << e
+        end
+      end
+
+      { :options => options, :arguments => arguments }
+    end
+
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: cri
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors: 
 - Denis Defreyne
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-01 00:00:00 +01:00
+date: 2009-11-02 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -26,7 +26,16 @@ extra_rdoc_files:
 files: 
 - ChangeLog
 - LICENSE
+- NEWS
 - README
+- Rakefile
+- VERSION
+- lib/cri.rb
+- lib/cri/base.rb
+- lib/cri/command.rb
+- lib/cri/core_ext.rb
+- lib/cri/core_ext/string.rb
+- lib/cri/option_parser.rb
 has_rdoc: true
 homepage: 
 licenses: []