clamp 0.0.7 → 0.0.9

data/README.markdown

@@ -26,7 +26,7 @@ Clamp models a command as a Ruby class; a subclass of `Clamp::Command`.  They lo
         Integer(s)
       end
 
-      argument "WORDS ...", "the thing to say"
+      parameter "WORDS ...", "the thing to say"
       
       def execute
 
@@ -42,7 +42,7 @@ Clamp models a command as a Ruby class; a subclass of `Clamp::Command`.  They lo
 
     end
 
-Class-level methods (like `option` and `argument`) are available to declare command-line options, and document usage.  
+Class-level methods (like `option` and `parameter`) are available to declare command-line options, and document usage.  
 
 The command can be invoked by instantiating the class, and asking it to run:
 
@@ -111,15 +111,15 @@ If the block raises an ArgumentError, Clamp will catch it, and report that the o
     !!!plain
     ERROR: option '--port': invalid value for Integer: "blah"
 
-Declaring arguments
--------------------
+Declaring parameters
+--------------------
 
-The `argument` method is used to declare command arguments:
+The `parameter` method is used to declare positional command parameters:
 
-    argument "FILE ...", "source files"
-    argument "DIR", "target directory"
+    parameter "FILE ...", "source files"
+    parameter "DIR", "target directory"
 
-Use of `argument` is entirely for documentation purposes.  Whether or not you declare and describe your expected arguments, the actual arguments that remain after option parsing will be available as `arguments` when your `#execute` method is called.
+Use of `parameter` is entirely for documentation purposes.  Whether or not you declare and describe your expected arguments, the actual arguments that remain after option parsing will be available as `arguments` when your `#execute` method is called.
 
 Sub-commands
 ------------
@@ -161,7 +161,7 @@ When a command has sub-commands, Clamp will attempt to delegate based on the fir
 Getting help
 ------------
 
-All Clamp commands support a "`--help`" option, which outputs brief usage documentation, based on those seemingly useless extra parameters that you had to pass to `option` and `argument`.
+All Clamp commands support a "`--help`" option, which outputs brief usage documentation, based on those seemingly useless extra parameters that you had to pass to `option` and `parameter`.
 
     $ speak --help
     Usage:

data/examples/rename

@@ -6,8 +6,8 @@ class Rename < Clamp::Command
 
   usage "[OPTIONS] TRANSFORM FILE ..."
 
-  argument "TRANSFORM", "a Ruby expression"
-  argument "FILE", "a file to rename"
+  parameter "TRANSFORM", "a Ruby expression"
+  parameter "FILE", "a file to rename"
   
   option ["-v", "--verbose"], :flag, "be verbose"
 

data/examples/speak

@@ -9,7 +9,7 @@ class SpeakCommand < Clamp::Command
     Integer(s)
   end
 
-  argument "WORDS ...", "the thing to say"
+  parameter "WORDS ...", "the thing to say"
 
   def execute
 

data/lib/clamp/attribute_declaration.rb

@@ -0,0 +1,38 @@
+module Clamp
+  
+  module AttributeDeclaration
+
+    protected
+    
+    def define_accessors_for(attribute, &block)
+      define_reader_for(attribute)
+      define_writer_for(attribute, &block)
+    end
+    
+    def define_reader_for(attribute)
+      reader_name = attribute.attribute_name
+      reader_name += "?" if attribute.respond_to?(:flag?) && attribute.flag?
+      ivar_name = "@#{attribute.attribute_name}"
+      define_method(reader_name) do
+        if instance_variable_defined?(ivar_name)
+          instance_variable_get(ivar_name)
+        elsif parent_command && parent_command.respond_to?(reader_name)
+          parent_command.send(reader_name)
+        elsif attribute.respond_to?(:default_value)
+          attribute.default_value
+        end
+      end
+    end
+
+    def define_writer_for(attribute, &block)
+      define_method("#{attribute.attribute_name}=") do |value|
+        if block
+          value = instance_exec(value, &block)
+        end
+        instance_variable_set("@#{attribute.attribute_name}", value)
+      end
+    end
+
+  end
+  
+end

data/lib/clamp/command.rb

@@ -1,6 +1,9 @@
-require 'clamp/help_support'
-require 'clamp/option_support'
-require 'clamp/subcommand_support'
+require 'clamp/command/declaration'
+require 'clamp/errors'
+require 'clamp/help'
+require 'clamp/option/parsing'
+require 'clamp/parameter/parsing'
+require 'clamp/subcommand/execution'
 
 module Clamp
 
@@ -18,28 +21,9 @@ module Clamp
     attr_accessor :parent_command
 
     def parse(arguments)
-      while arguments.first =~ /^-/
-        case (switch = arguments.shift)
-
-        when /\A--\z/
-          break
-
-        else
-          option = find_option(switch)
-          value = if option.flag?
-            option.flag_value(switch)
-          else
-            arguments.shift
-          end
-          begin
-            send("#{option.attribute_name}=", value)
-          rescue ArgumentError => e
-            signal_usage_error "option '#{switch}': #{e.message}"
-          end
-
-        end
-      end
-      @arguments = arguments
+      @arguments = arguments.dup
+      parse_options
+      parse_parameters
     end
 
     # default implementation
@@ -60,32 +44,12 @@ module Clamp
       self.class.help(name)
     end
 
+    include Option::Parsing
+    include Parameter::Parsing
+    include Subcommand::Execution
+    
     private
 
-    def execute_subcommand
-      signal_usage_error "no subcommand specified" if arguments.empty?
-      subcommand_name = arguments.shift
-      subcommand_class = find_subcommand_class(subcommand_name)
-      subcommand = subcommand_class.new("#{name} #{subcommand_name}", context)
-      subcommand.parent_command = self
-      subcommand.run(arguments)
-    end
-
-    def find_option(switch)
-      self.class.find_option(switch) || 
-      signal_usage_error("Unrecognised option '#{switch}'")
-    end
-
-    def find_subcommand(name)
-      self.class.find_subcommand(name) || 
-      signal_usage_error("No such sub-command '#{name}'")
-    end
-
-    def find_subcommand_class(name)
-      subcommand = find_subcommand(name)
-      subcommand.subcommand_class if subcommand
-    end
-
     def signal_usage_error(message)
       e = UsageError.new(message, self)
       e.set_backtrace(caller)
@@ -98,9 +62,8 @@ module Clamp
 
     class << self
 
-      include OptionSupport
-      include SubcommandSupport
-      include HelpSupport
+      include Command::Declaration
+      include Help
 
       def run(name = $0, args = ARGV, context = {})
         begin 
@@ -119,27 +82,4 @@ module Clamp
 
   end
 
-  class Error < StandardError
-
-    def initialize(message, command)
-      super(message)
-      @command = command
-    end
-
-    attr_reader :command
-
-  end
-
-  # raise to signal incorrect command usage
-  class UsageError < Error; end
-
-  # raise to request usage help
-  class HelpWanted < Error
-
-    def initialize(command)
-      super("I need help", command)
-    end
-
-  end
-
 end

data/lib/clamp/command/declaration.rb

@@ -0,0 +1,15 @@
+require 'clamp/option/declaration'
+require 'clamp/parameter/declaration'
+require 'clamp/subcommand/declaration'
+
+module Clamp
+  class Command
+    
+    module Declaration
+      include Option::Declaration
+      include Parameter::Declaration
+      include Subcommand::Declaration
+    end
+
+  end
+end

data/lib/clamp/errors.rb

@@ -0,0 +1,26 @@
+module Clamp
+  
+  class Error < StandardError
+
+    def initialize(message, command)
+      super(message)
+      @command = command
+    end
+
+    attr_reader :command
+
+  end
+
+  # raise to signal incorrect command usage
+  class UsageError < Error; end
+
+  # raise to request usage help
+  class HelpWanted < Error
+
+    def initialize(command)
+      super("I need help", command)
+    end
+
+  end
+
+end

data/lib/clamp/{help_support.rb → help.rb}

@@ -1,22 +1,6 @@
 module Clamp
 
-  class Argument < Struct.new(:name, :description)
-
-    def help
-      [name, description]
-    end
-
-  end
-
-  module HelpSupport
-
-    def declared_arguments
-      @declared_arguments ||= []
-    end
-
-    def argument(name, description)
-      declared_arguments << Argument.new(name, description)
-    end
+  module Help
 
     def usage(usage)
       @declared_usage_descriptions ||= []
@@ -26,7 +10,7 @@ module Clamp
     attr_reader :declared_usage_descriptions
 
     def derived_usage_description
-      parts = declared_arguments.map { |a| a.name }
+      parts = parameters.map { |a| a.name }
       parts.unshift("SUBCOMMAND") if has_subcommands?
       parts.unshift("[OPTIONS]") if has_options?
       parts.join(" ")
@@ -43,10 +27,10 @@ module Clamp
         help.puts "    #{command_name} #{usage}".rstrip
       end
       detail_format = "    %-29s %s"
-      unless declared_arguments.empty?
-        help.puts "\nArguments:"
-        declared_arguments.each do |argument|
-          help.puts detail_format % argument.help
+      unless parameters.empty?
+        help.puts "\nParameters:"
+        parameters.each do |parameter|
+          help.puts detail_format % parameter.help
         end
       end
       unless recognised_subcommands.empty?

data/lib/clamp/option.rb

@@ -2,9 +2,9 @@ module Clamp
 
   class Option
 
-    def initialize(switches, argument_type, description, options = {})
+    def initialize(switches, type, description, options = {})
       @switches = Array(switches)
-      @argument_type = argument_type
+      @type = type
       @description = description
       if options.has_key?(:attribute_name)
         @attribute_name = options[:attribute_name].to_s 
@@ -14,7 +14,7 @@ module Clamp
       end
     end
 
-    attr_reader :switches, :argument_type, :description, :default_value
+    attr_reader :switches, :type, :description, :default_value
 
     def attribute_name
       @attribute_name ||= long_switch.sub(/^--(\[no-\])?/, '').tr('-', '_')
@@ -29,21 +29,29 @@ module Clamp
     end
 
     def flag?
-      @argument_type == :flag
+      @type == :flag
     end
     
     def flag_value(switch)
       !(switch =~ /^--no-(.*)/ && switches.member?("--\[no-\]#{$1}"))
     end
     
+    def extract_value(switch, arguments)
+      if flag?
+        flag_value(switch)
+      else
+        arguments.shift
+      end
+    end
+    
     def help
       lhs = switches.join(", ")
-      lhs += " " + argument_type unless flag?
+      lhs += " " + type unless flag?
       [lhs, description]
     end
 
     private
-    
+
     def recognised_switches
       switches.map do |switch|
         if switch =~ /^--\[no-\](.*)/

data/lib/clamp/option/declaration.rb

@@ -0,0 +1,56 @@
+require 'clamp/attribute_declaration'
+require 'clamp/option'
+
+module Clamp
+  class Option
+
+    module Declaration
+
+      include AttributeDeclaration
+
+      def option(switches, type, description, opts = {}, &block)
+        option = Clamp::Option.new(switches, type, description, opts)
+        my_declared_options << option
+        define_accessors_for(option, &block)
+      end
+
+      def has_options?
+        !declared_options.empty?
+      end
+
+      def declared_options
+        my_declared_options + inherited_declared_options
+      end
+
+      def recognised_options
+        declared_options + standard_options
+      end
+
+      def find_option(switch)
+        recognised_options.find { |o| o.handles?(switch) }
+      end
+
+      private
+
+      def my_declared_options
+        @my_declared_options ||= []
+      end
+
+      def inherited_declared_options
+        if superclass.respond_to?(:declared_options)
+          superclass.declared_options
+        else
+          []
+        end
+      end
+
+      HELP_OPTION = Clamp::Option.new("--help", :flag, "print help", :attribute_name => :help_requested)
+
+      def standard_options
+        [HELP_OPTION]
+      end
+
+    end
+
+  end
+end

data/lib/clamp/option/parsing.rb

@@ -0,0 +1,36 @@
+module Clamp
+  class Option
+
+    module Parsing
+
+      protected
+
+      def parse_options
+        while arguments.first =~ /^-/
+
+          switch = arguments.shift
+          break if switch == "--"
+
+          option = find_option(switch)
+          value = option.extract_value(switch, arguments)
+
+          begin
+            send("#{option.attribute_name}=", value)
+          rescue ArgumentError => e
+            signal_usage_error "option '#{switch}': #{e.message}"
+          end
+
+        end
+      end
+
+      private
+
+      def find_option(switch)
+        self.class.find_option(switch) || 
+        signal_usage_error("Unrecognised option '#{switch}'")
+      end
+
+    end
+
+  end
+end