clamp 0.0.9 → 0.1.0

data/README.markdown

@@ -26,42 +26,32 @@ Clamp models a command as a Ruby class; a subclass of `Clamp::Command`.  They lo
         Integer(s)
       end
 
-      parameter "WORDS ...", "the thing to say"
-      
-      def execute
+      parameter "WORDS ...", "the thing to say", :attribute_name => :words
 
-        signal_usage_error "I have nothing to say" if arguments.empty?
-        the_truth = arguments.join(" ")
+      def execute
+        the_truth = words.join(" ")
         the_truth.upcase! if loud?
-
         iterations.times do
           puts the_truth
         end
-
       end
 
     end
 
-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:
-
-    SpeakCommand.new("speak").run(["--loud", "a", "b", "c"])
-
-but it's more typical to use the class-level "`run`" method:
+Calling `run` on a command class creates an instance of it, then invokes it using command-line arguments (from ARGV, by default).
 
     SpeakCommand.run
-    
-which takes arguments from `ARGV`, and includes some handy error-handling.
+
+Class-level methods like `option` and `parameter` declare attributes (in a similar way to `attr_accessor`), and arrange for them to be populated automatically based on command-line arguments.  They are aso used to generate `help` documentation.  
 
 Declaring options
 -----------------
 
-Options are declared using the [`option`](../Clamp/Command.option) method.  The three required arguments are:
+Options are declared using the `option` method.  The three required arguments are:
 
   1. the option switch (or switches),
-  2. a short description of the option argument type, and
-  3. a description of the option itself
+  2. an option argument name
+  3. a short description
 
 For example:
 
@@ -90,7 +80,7 @@ Some options are just boolean flags.  Pass "`:flag`" as the second parameter to
 
     option "--verbose", :flag, "be chatty"
 
-For flag options, Clamp appends "`?`" to the generated reader method; ie. you get a method called "`verbose?`", rather than just "`verbose`".
+For flag options, Clamp appends "`?`" to the generated reader method; ie. you get a method called "`#verbose?`", rather than just "`#verbose`".
 
 Negatable flags are easy to generate, too: 
 
@@ -98,33 +88,72 @@ Negatable flags are easy to generate, too:
 
 Clamp will handle both "`--force`" and "`--no-force`" options, setting the value of "`#force?`" appropriately.
 
-### Validation and conversion of option arguments
+Declaring parameters
+--------------------
+
+Positional parameters can be declared using `parameter`, specifying
+
+  1. the parameter name, and
+  2. a short description
+
+For example:
+
+    parameter "SRC", "source file"
+
+Like options, parameters are implemented as attributes of the command, with the default attribute name derived from the parameter name (in this case, "`src`"). By convention, parameter names are specified in uppercase, to make them obvious in usage help.
+
+### Optional parameters
 
-If a block is passed to `option`, it will be called with the raw string option argument, and is expected to coerce that String to the correct type, e.g.
+Wrapping a parameter name in square brackets indicates that it's optional, e.g.
+
+    parameter "[TARGET_DIR]", "target directory"
+
+### Greedy parameters
+
+Three dots at the end of a parameter name makes it "greedy" - it will consume all remaining command-line arguments.  For example:
+
+    parameter "FILE ...", "input files"
+
+The suffix "`_list`" is appended to the default attribute name for greedy parameters; in this case, an attribute called "`file_list`" would be generated.
+
+Parsing and validation of options and parameters
+------------------------------------------------
+
+When you `#run` a command, it will first attempt to `#parse` command-line arguments, and map them onto the declared options and parameters, before invoking your `#execute` method.
+
+If parameters are declared, Clamp will verify that all required (ie. non-optional) parameters are present, and signal a error if they aren't. Otherwise, arguments that remain after option parsing will be made available via `#arguments`.
+
+### Validation block
+
+Both `option` and `parameter` accept an optional block.  If present, the block will be 
+called with the raw string option argument, and is expected to coerce it to 
+the correct type, e.g.
 
     option "--port", "PORT", "port to listen on" do |s|
       Integer(s)
     end
 
-If the block raises an ArgumentError, Clamp will catch it, and report that the option value was bad:
+If the block raises an ArgumentError, Clamp will catch it, and report that the value was bad:
 
     !!!plain
     ERROR: option '--port': invalid value for Integer: "blah"
 
-Declaring parameters
---------------------
+### Advanced option/parameter handling
 
-The `parameter` method is used to declare positional command parameters:
+While Clamp provides an attribute-writer method for each declared option or parameter, you always have the option of overriding it to provide custom argument-handling logic, e.g.
 
-    parameter "FILE ...", "source files"
-    parameter "DIR", "target directory"
+    parameter "SERVER", "location of server"
+    
+    def server=(server)
+      @server_address, @server_port = server.split(":")
+    end
 
-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.
+Declaring Subcommands
+---------------------
 
-Sub-commands
-------------
+Subcommand support helps you wrap a number of related commands into a single script (ala tools like "`git`").  Clamp will inspect the first command-line argument (after options are parsed), and delegate to the named subcommand.
 
-The `subcommand` method declares sub-commands:
+Unsuprisingly, subcommands are declared using the `subcommand` method. e.g.
 
     class MainCommand < Clamp::Command
 
@@ -138,9 +167,7 @@ The `subcommand` method declares sub-commands:
       
     end
 
-Clamp generates an anonymous sub-class of the current class, to represent the sub-command.  Additional options may be declared within subcommand blocks, but all options declared on the parent class are also accepted.
-
-Alternatively, you can provide an explicit sub-command class, rather than a block:
+Clamp generates an anonymous subclass of the current class, to represent the subcommand.  Alternatively, you can provide an explicit subcommand class:
     
     class MainCommand < Clamp::Command
 
@@ -156,7 +183,11 @@ Alternatively, you can provide an explicit sub-command class, rather than a bloc
 
     end
 
-When a command has sub-commands, Clamp will attempt to delegate based on the first command-line argument, before options are parsed.  Remaining arguments will be passed on to the sub-command.
+### Subcommand options and parameters
+
+Options are inheritable, so any options declared for a parent command are supported for it's subcommands.  Parameters, on the other hand, are not inherited - each subcommand must declare it's own parameter list.
+
+Note that, if a subcommand accepts options, they must be specified on the command-line _after_ the subcommand name.  
 
 Getting help
 ------------

data/examples/flipflop

@@ -1,5 +1,7 @@
 #! /usr/bin/env ruby
 
+# An example of subcommands
+
 require "clamp"
 
 class FlipFlop < Clamp::Command

data/examples/speak

@@ -1,5 +1,7 @@
 #! /usr/bin/env ruby
 
+# A simple Clamp command, with options and parameters
+
 require "clamp"
 
 class SpeakCommand < Clamp::Command
@@ -9,12 +11,11 @@ class SpeakCommand < Clamp::Command
     Integer(s)
   end
 
-  parameter "WORDS ...", "the thing to say"
+  parameter "WORDS ...", "the thing to say", :attribute_name => :words
 
   def execute
 
-    signal_usage_error "I have nothing to say" if arguments.empty?
-    the_truth = arguments.join(" ")
+    the_truth = words.join(" ")
     the_truth.upcase! if loud?
 
     iterations.times do

data/lib/clamp/command.rb

@@ -1,32 +1,72 @@
-require 'clamp/command/declaration'
 require 'clamp/errors'
 require 'clamp/help'
+require 'clamp/option/declaration'
 require 'clamp/option/parsing'
+require 'clamp/parameter/declaration'
 require 'clamp/parameter/parsing'
+require 'clamp/subcommand/declaration'
 require 'clamp/subcommand/execution'
 
 module Clamp
 
+  # {Command} models a shell command.  Each command invocation is a new object.
+  # Command options and parameters are represented as attributes 
+  # (see {Command::Declaration}).
+  #
+  # The main entry-point is {#run}, which uses {#parse} to populate attributes based 
+  # on an array of command-line arguments, then calls {#execute} (which you provide)
+  # to make it go.
+  #
   class Command
 
-    def initialize(name, context = {})
-      @name = name
+    # Create a command execution.
+    #
+    # @param [String] invocation_path the path used to invoke the command
+    # @param [Hash] context additional data the command may need
+    #
+    def initialize(invocation_path, context = {})
+      @invocation_path = invocation_path
       @context = context
     end
 
-    attr_reader :name
-    attr_reader :arguments
-
-    attr_accessor :context
-    attr_accessor :parent_command
+    # @return [String] the path used to invoke this command
+    #
+    attr_reader :invocation_path
+    
+    # @return [Array<String>] unconsumed command-line arguments
+    #
+    def arguments
+      @arguments
+    end
 
+    # Parse command-line arguments.
+    #
+    # @param [Array<String>] arguments command-line arguments
+    # @return [Array<String>] unconsumed arguments
+    #
     def parse(arguments)
       @arguments = arguments.dup
       parse_options
       parse_parameters
+      @arguments
+    end
+
+    # Run the command, with the specified arguments.
+    #
+    # This calls {#parse} to process the command-line arguments, 
+    # then delegates to {#execute}.
+    #
+    # @param [Array<String>] arguments command-line arguments
+    #
+    def run(arguments)
+      parse(arguments)
+      execute
     end
 
-    # default implementation
+    # Execute the command (assuming that all options/parameters have been set).
+    # 
+    # This method is designed to be overridden in sub-classes.
+    #
     def execute
       if self.class.has_subcommands?
         execute_subcommand
@@ -35,19 +75,21 @@ module Clamp
       end
     end
 
-    def run(arguments)
-      parse(arguments)
-      execute
-    end
-
+    # @return [String] usage documentation for this command
+    #
     def help
-      self.class.help(name)
+      self.class.help(invocation_path)
     end
 
-    include Option::Parsing
-    include Parameter::Parsing
-    include Subcommand::Execution
+    include Clamp::Option::Parsing
+    include Clamp::Parameter::Parsing
+    include Clamp::Subcommand::Execution
+
+    protected
     
+    attr_accessor :context
+    attr_accessor :parent_command
+
     private
 
     def signal_usage_error(message)
@@ -62,16 +104,24 @@ module Clamp
 
     class << self
 
-      include Command::Declaration
+      include Clamp::Option::Declaration
+      include Clamp::Parameter::Declaration
+      include Clamp::Subcommand::Declaration
       include Help
 
-      def run(name = $0, args = ARGV, context = {})
+      # Create an instance of this command class, and run it.
+      #
+      # @param [String] invocation_path the path used to invoke the command
+      # @param [Array<String>] arguments command-line arguments
+      # @param [Hash] context additional data the command may need
+      # 
+      def run(invocation_path = $0, arguments = ARGV, context = {})
         begin 
-          new(name, context).run(args)
+          new(invocation_path, context).run(arguments)
         rescue Clamp::UsageError => e
           $stderr.puts "ERROR: #{e.message}"
           $stderr.puts ""
-          $stderr.puts "See: '#{name} --help'"
+          $stderr.puts "See: '#{invocation_path} --help'"
           exit(1)
         rescue Clamp::HelpWanted => e
           puts e.command.help

data/lib/clamp/help.rb

@@ -20,20 +20,20 @@ module Clamp
       declared_usage_descriptions || [derived_usage_description]
     end
 
-    def help(command_name)
+    def help(invocation_path)
       help = StringIO.new
       help.puts "Usage:"
       usage_descriptions.each_with_index do |usage, i|
-        help.puts "    #{command_name} #{usage}".rstrip
+        help.puts "    #{invocation_path} #{usage}".rstrip
       end
       detail_format = "    %-29s %s"
-      unless parameters.empty?
+      if has_parameters?
         help.puts "\nParameters:"
         parameters.each do |parameter|
           help.puts detail_format % parameter.help
         end
       end
-      unless recognised_subcommands.empty?
+      if has_subcommands?
         help.puts "\nSubcommands:"
         recognised_subcommands.each do |subcommand|
           help.puts detail_format % subcommand.help

data/lib/clamp/option/declaration.rb

@@ -6,7 +6,7 @@ module Clamp
 
     module Declaration
 
-      include AttributeDeclaration
+      include Clamp::AttributeDeclaration
 
       def option(switches, type, description, opts = {}, &block)
         option = Clamp::Option.new(switches, type, description, opts)
@@ -18,20 +18,22 @@ module Clamp
         !declared_options.empty?
       end
 
+      def find_option(switch)
+        recognised_options.find { |o| o.handles?(switch) }
+      end
+
+      protected 
+
       def declared_options
         my_declared_options + inherited_declared_options
       end
 
+      private
+
       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

data/lib/clamp/parameter.rb

@@ -30,18 +30,20 @@ module Clamp
     
     private
 
+    NAME_PATTERN = "([A-Za-z0-9_-]+)"
+    
     def infer_attribute_name_and_multiplicity
       case @name
-      when /^\[(\S+)\]$/
+      when /^\[#{NAME_PATTERN}\]$/
         @attribute_name = $1
-      when /^\[(\S+)\] ...$/
+      when /^\[#{NAME_PATTERN}\] ...$/
         @attribute_name = "#{$1}_list"
         @multivalued = true
-      when /^(\S+) ...$/
+      when /^#{NAME_PATTERN} ...$/
         @attribute_name = "#{$1}_list"
         @multivalued = true
         @required = true
-      when /^\S+$/
+      when /^#{NAME_PATTERN}$/
         @attribute_name = @name
         @required = true
       else

data/lib/clamp/parameter/declaration.rb

@@ -6,12 +6,16 @@ module Clamp
 
     module Declaration
 
-      include AttributeDeclaration
+      include Clamp::AttributeDeclaration
 
       def parameters
         @parameters ||= []
       end
 
+      def has_parameters?
+        !parameters.empty?
+      end
+
       def parameter(name, description, options = {}, &block)
         parameter = Parameter.new(name, description, options)
         parameters << parameter

data/lib/clamp/subcommand/execution.rb

@@ -9,7 +9,7 @@ module Clamp
         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 = subcommand_class.new("#{invocation_path} #{subcommand_name}", context)
         subcommand.parent_command = self
         subcommand.run(arguments)
       end

data/lib/clamp/version.rb

@@ -1,3 +1,3 @@
 module Clamp
-  VERSION = "0.0.9".freeze
+  VERSION = "0.1.0".freeze
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: clamp
 version: !ruby/object:Gem::Version 
-  hash: 13
+  hash: 27
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 9
-  version: 0.0.9
+  version: 0.1.0
 platform: ruby
 authors: 
 - Mike Williams
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-11 00:00:00 +11:00
+date: 2010-11-15 00:00:00 +11:00
 default_executable: 
 dependencies: []
 
@@ -37,13 +37,10 @@ files:
 - Rakefile
 - clamp.gemspec
 - examples/flipflop
-- examples/icecream
-- examples/rename
 - examples/speak
 - lib/clamp.rb
 - lib/clamp/attribute_declaration.rb
 - lib/clamp/command.rb
-- lib/clamp/command/declaration.rb
 - lib/clamp/errors.rb
 - lib/clamp/help.rb
 - lib/clamp/option.rb

data/examples/icecream

@@ -1,16 +0,0 @@
-#! /usr/bin/env ruby
-
-require "clamp"
-
-class Icecream < Clamp::Command
-
-  option "--flavour", "FLAVOUR", "ice-cream flavour"
-
-  def execute
-    signal_usage_error "what flavour?" unless flavour
-    puts "You chose #{flavour}.  Excellent choice!"
-  end
-  
-end
-
-Icecream.run

data/examples/rename

@@ -1,33 +0,0 @@
-#! /usr/bin/env ruby
-
-require "clamp"
-
-class Rename < Clamp::Command
-
-  usage "[OPTIONS] TRANSFORM FILE ..."
-
-  parameter "TRANSFORM", "a Ruby expression"
-  parameter "FILE", "a file to rename"
-  
-  option ["-v", "--verbose"], :flag, "be verbose"
-
-  option ["-n", "--times"], "TIMES", "repetitions" do |n|
-    n = Integer(n)
-    raise ArgumentError, "too big" if n > 9
-    n
-  end
-
-  def initialize(name)
-    super
-    @times = 1
-  end
-  
-  def execute
-    @times.times do
-      puts "Blah blah blah" if verbose?
-    end
-  end
-  
-end
-
-Rename.run

data/lib/clamp/command/declaration.rb

@@ -1,15 +0,0 @@
-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