clamp 0.2.3 → 0.3.0

data/README.markdown

@@ -205,11 +205,13 @@ Clamp generates an anonymous subclass of the current class, to represent the sub
 
 ### Default subcommand
 
-You can mark a subcommand as "default" by using `default_subcommand` to declare it, rather than `subcommand`.  Usually the SUBCOMMAND parameter is mandatory, but if a default subcommand is declared, it becomes optional.
+You can set a default subcommand, at the class level, as follows:
 
     class MainCommand < Clamp::Command
 
-      default_subcommand "status", "Display current status" do
+      self.default_subcommand = "status"
+      
+      subcommand "status", "Display current status" do
 
         def execute
           # ...
@@ -219,6 +221,8 @@ You can mark a subcommand as "default" by using `default_subcommand` to declare
       
     end
 
+Then, if when no SUBCOMMAND argument is provided, the default will be selected.
+
 ### Subcommand options and parameters
 
 Options are inheritable, so any options declared for a command are supported for it's sub-classes (e.g. those created using `subcommand`).  Parameters, on the other hand, are not inherited - each subcommand must declare it's own parameter list.

data/examples/flipflop

@@ -12,7 +12,9 @@ class FlipFlop < Clamp::Command
     exit(0)
   end
 
-  default_subcommand "flip", "flip it" do
+  self.default_subcommand = "flip"
+
+  subcommand "flip", "flip it" do
     def execute
       puts "FLIPPED"
     end
@@ -23,7 +25,7 @@ class FlipFlop < Clamp::Command
       puts "FLOPPED"
     end
   end
-  
+
 end
 
 FlipFlop.run

data/lib/clamp/attribute_declaration.rb

@@ -1,15 +1,15 @@
 module Clamp
-  
+
   module AttributeDeclaration
 
     protected
-    
+
     def define_accessors_for(attribute, &block)
       define_reader_for(attribute)
       define_default_for(attribute)
       define_writer_for(attribute, &block)
     end
-    
+
     def define_reader_for(attribute)
       define_method(attribute.read_method) do
         if instance_variable_defined?(attribute.ivar_name)
@@ -36,5 +36,5 @@ module Clamp
     end
 
   end
-  
+
 end

data/lib/clamp/command.rb

@@ -5,15 +5,15 @@ require 'clamp/option/parsing'
 require 'clamp/parameter/declaration'
 require 'clamp/parameter/parsing'
 require 'clamp/subcommand/declaration'
-require 'clamp/subcommand/execution'
+require 'clamp/subcommand/parsing'
 
 module Clamp
 
   # {Command} models a shell command.  Each command invocation is a new object.
-  # Command options and parameters are represented as attributes 
+  # Command options and parameters are represented as attributes
   # (see {Command::Declaration}).
   #
-  # The main entry-point is {#run}, which uses {#parse} to populate attributes based 
+  # 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.
   #
@@ -32,7 +32,7 @@ module Clamp
     # @return [String] the path used to invoke this command
     #
     attr_reader :invocation_path
-    
+
     # @return [Array<String>] unconsumed command-line arguments
     #
     def remaining_arguments
@@ -48,12 +48,13 @@ module Clamp
       @remaining_arguments = arguments.dup
       parse_options
       parse_parameters
-      @remaining_arguments
+      parse_subcommand
+      handle_remaining_arguments
     end
 
     # Run the command, with the specified arguments.
     #
-    # This calls {#parse} to process the command-line arguments, 
+    # This calls {#parse} to process the command-line arguments,
     # then delegates to {#execute}.
     #
     # @param [Array<String>] arguments command-line arguments
@@ -64,12 +65,12 @@ module Clamp
     end
 
     # 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
+      if @subcommand
+        @subcommand.execute
       else
         raise "you need to define #execute"
       end
@@ -83,12 +84,18 @@ module Clamp
 
     include Clamp::Option::Parsing
     include Clamp::Parameter::Parsing
-    include Clamp::Subcommand::Execution
+    include Clamp::Subcommand::Parsing
 
     protected
-    
+
     attr_accessor :context
 
+    def handle_remaining_arguments
+      unless remaining_arguments.empty?
+        signal_usage_error "too many arguments"
+      end
+    end
+
     private
 
     def signal_usage_error(message)
@@ -97,8 +104,8 @@ module Clamp
       raise e
     end
 
-    def help_requested=(value)
-      raise Clamp::HelpWanted.new(self)
+    def request_help
+      raise HelpWanted, self
     end
 
     class << self
@@ -113,9 +120,9 @@ module Clamp
       # @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 = File.basename($0), arguments = ARGV, context = {})
-        begin 
+        begin
           new(invocation_path, context).run(arguments)
         rescue Clamp::UsageError => e
           $stderr.puts "ERROR: #{e.message}"

data/lib/clamp/help.rb

@@ -23,8 +23,12 @@ module Clamp
     attr_reader :description
 
     def derived_usage_description
-      parts = parameters.map { |a| a.name }
-      parts.unshift("[OPTIONS]")
+      parts = ["[OPTIONS]"]
+      parts += parameters.map { |a| a.name }
+      if has_subcommands?
+        parts << "SUBCOMMAND"
+        parts << "[ARGS] ..."
+      end
       parts.join(" ")
     end
 

data/lib/clamp/option/declaration.rb

@@ -35,7 +35,7 @@ module Clamp
           help_switches = ["--help"]
           help_switches.unshift("-h") unless effective_options.find { |o| o.handles?("-h") }
           option help_switches, :flag, "print help" do
-            raise Clamp::HelpWanted.new(self)
+            request_help
           end
         end
         @implicit_options_declared = true

data/lib/clamp/parameter/parsing.rb

@@ -4,7 +4,7 @@ module Clamp
     module Parsing
 
       protected
-      
+
       def parse_parameters
 
         self.class.parameters.each do |parameter|
@@ -16,10 +16,6 @@ module Clamp
           end
         end
 
-        unless remaining_arguments.empty?
-          signal_usage_error "too many arguments"
-        end
-
       end
 
     end

data/lib/clamp/subcommand/declaration.rb

@@ -10,48 +10,33 @@ module Clamp
       end
 
       def subcommand(name, description, subcommand_class = self, &block)
-        has_subcommands!
-        declare_subcommand(name, description, subcommand_class, &block)
-      end
-
-      def default_subcommand(name, description, subcommand_class = self, &block)
-        has_subcommands!(name)
-        declare_subcommand(name, description, subcommand_class, &block)
+        if block
+          # generate a anonymous sub-class
+          subcommand_class = Class.new(subcommand_class, &block)
+        end
+        recognised_subcommands << Subcommand.new(name, description, subcommand_class)
       end
 
       def has_subcommands?
-        @has_subcommands
+        !recognised_subcommands.empty?
       end
 
       def find_subcommand(name)
         recognised_subcommands.find { |sc| sc.is_called?(name) }
       end
-      
-      def has_subcommands!(default = nil)
-        if @has_subcommands
-          if default
-            raise "You must declare the default_subcommand before any other subcommands"
-          end
+
+      attr_writer :default_subcommand
+
+      def default_subcommand(*args, &block)
+        if args.empty?
+          @default_subcommand
         else
-          if default
-            parameter "[SUBCOMMAND]", "subcommand name", :attribute_name => :subcommand_name, :default => default
-          else
-            parameter "SUBCOMMAND", "subcommand name", :attribute_name => :subcommand_name
-          end
-          parameter "[ARGS] ...", "subcommand arguments", :attribute_name => :subcommand_arguments
-          @has_subcommands = true
+          $stderr.puts "WARNING: Clamp default_subcommand syntax has changed; check the README."
+          $stderr.puts "  (from #{caller.first})"
+          subcommand(*args, &block)
+          self.default_subcommand = args.first
         end
       end
-      
-      private
-      
-      def declare_subcommand(name, description, subcommand_class = self, &block)
-        if block
-          # generate a anonymous sub-class
-          subcommand_class = Class.new(subcommand_class, &block)
-        end
-        recognised_subcommands << Subcommand.new(name, description, subcommand_class)
-      end
 
     end
 

data/lib/clamp/subcommand/parsing.rb

@@ -0,0 +1,42 @@
+module Clamp
+  class Subcommand
+
+    module Parsing
+
+      protected
+
+      def parse_subcommand
+        return false unless self.class.has_subcommands?
+        subcommand_name = parse_subcommand_name
+        @subcommand = instatiate_subcommand(subcommand_name)
+        @subcommand.parse(remaining_arguments)
+        remaining_arguments.clear
+      end
+
+      private
+
+      def parse_subcommand_name
+        remaining_arguments.shift || self.class.default_subcommand || request_help
+      end
+
+      def find_subcommand(name)
+        self.class.find_subcommand(name) ||
+        signal_usage_error("No such sub-command '#{name}'")
+      end
+
+      def instatiate_subcommand(name)
+        subcommand_class = find_subcommand(name).subcommand_class
+        subcommand = subcommand_class.new("#{invocation_path} #{name}", context)
+        self.class.recognised_options.each do |option|
+          option_set = instance_variable_defined?(option.ivar_name)
+          if option_set && subcommand.respond_to?(option.write_method)
+            subcommand.send(option.write_method, self.send(option.read_method))
+          end
+        end
+        subcommand
+      end
+
+    end
+
+  end
+end

data/lib/clamp/version.rb

@@ -1,3 +1,3 @@
 module Clamp
-  VERSION = "0.2.3".freeze
+  VERSION = "0.3.0".freeze
 end

data/spec/clamp/command_group_spec.rb

@@ -33,40 +33,67 @@ describe Clamp::Command do
 
     end
 
+    context "executed with no subcommand" do
+
+      it "triggers help" do
+        lambda do
+          @command.run([])
+        end.should raise_error(Clamp::HelpWanted)
+      end
+
+    end
+
+    describe "#parse" do
+
+      describe "with too many arguments" do
+
+        it "raises a UsageError" do
+          lambda do
+            @command.parse(["flip", "extra", "args"])
+          end.should raise_error(Clamp::UsageError, "too many arguments")
+        end
+
+      end
+
+    end
+
     describe "#help" do
-      
+
+      it "shows subcommand parameters in usage" do
+        @command.help.should include("flipflop [OPTIONS] SUBCOMMAND [ARGS] ...")
+      end
+
       it "lists subcommands" do
         @help = @command.help
         @help.should =~ /Subcommands:/
         @help.should =~ /flip +flip it/
         @help.should =~ /flop +flop it/
       end
-      
+
       it "handles new lines in subcommand descriptions" do
-        @help = @command.help        
-        @help.should =~ /flop +flop it\n +for extra flop/
+        @command.help.should =~ /flop +flop it\n +for extra flop/
       end
-      
+
     end
-    
+
   end
 
   describe "with an aliased subcommand" do
-    
+
     given_command "blah" do
 
       subcommand ["say", "talk"], "Say something" do
-        
+
         parameter "WORD ...", "stuff to say"
-        
+
         def execute
           puts word_list
         end
-        
+
       end
-      
+
     end
-    
+
     it "responds to both aliases" do
 
       @command.run(["say", "boo"])
@@ -76,8 +103,8 @@ describe Clamp::Command do
       stdout.should =~ /jive/
 
     end
-    
-    describe "#help" do 
+
+    describe "#help" do
 
       it "lists all aliases" do
         @help = @command.help
@@ -85,9 +112,9 @@ describe Clamp::Command do
       end
 
     end
-    
+
   end
-  
+
   describe "with nested subcommands" do
 
     given_command "fubar" do
@@ -110,9 +137,36 @@ describe Clamp::Command do
     end
 
   end
-  
+
   describe "with a default subcommand" do
-    
+
+    given_command "admin" do
+
+      subcommand "status", "Show status" do
+
+        def execute
+          puts "All good!"
+        end
+
+      end
+
+      self.default_subcommand = "status"
+
+    end
+
+    context "executed with no subcommand" do
+
+      it "invokes the default subcommand" do
+        @command.run([])
+        stdout.should =~ /All good/
+      end
+
+    end
+
+  end
+
+  describe "with a default subcommand, declared the old way" do
+
     given_command "admin" do
 
       default_subcommand "status", "Show status" do
@@ -125,13 +179,17 @@ describe Clamp::Command do
 
     end
 
-    it "delegates multiple levels" do
-      @command.run([])
-      stdout.should =~ /All good/
+    context "executed with no subcommand" do
+
+      it "invokes the default subcommand" do
+        @command.run([])
+        stdout.should =~ /All good/
+      end
+
     end
-    
+
   end
-  
+
   describe "each subcommand" do
 
     before do
@@ -146,7 +204,7 @@ describe Clamp::Command do
         option "--direction", "DIR", "which way", :default => "home"
 
         include speed_options
-        
+
         subcommand "move", "move in the appointed direction" do
 
           def execute

metadata

@@ -1,30 +1,23 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: clamp
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.3.0
   prerelease: 
-  version: 0.2.3
 platform: ruby
-authors: 
+authors:
 - Mike Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-07-31 00:00:00 Z
+date: 2011-10-30 00:00:00.000000000Z
 dependencies: []
-
-description: |
-  Clamp provides an object-model for command-line utilities.  
-  It handles parsing of command-line options, and generation of usage help.
-
+description: ! "Clamp provides an object-model for command-line utilities.  \nIt handles
+  parsing of command-line options, and generation of usage help.\n"
 email: mdub@dogbiscuit.org
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - README.markdown
@@ -48,7 +41,7 @@ files:
 - lib/clamp/parameter/parsing.rb
 - lib/clamp/subcommand.rb
 - lib/clamp/subcommand/declaration.rb
-- lib/clamp/subcommand/execution.rb
+- lib/clamp/subcommand/parsing.rb
 - lib/clamp/version.rb
 - spec/clamp/command_group_spec.rb
 - spec/clamp/command_spec.rb
@@ -58,38 +51,35 @@ files:
 - spec/spec_helper.rb
 homepage: http://github.com/mdub/clamp
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 1591530698992906617
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: 2140542804318955849
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 1591530698992906617
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: 2140542804318955849
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.7.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: a minimal framework for command-line utilities
-test_files: 
+test_files:
 - spec/clamp/command_group_spec.rb
 - spec/clamp/command_spec.rb
 - spec/clamp/option_module_spec.rb

data/lib/clamp/subcommand/execution.rb

@@ -1,36 +0,0 @@
-module Clamp
-  class Subcommand
-
-    module Execution
-
-      protected
-      
-      def execute_subcommand
-        signal_usage_error "no subcommand specified" unless subcommand_name
-        subcommand_class = find_subcommand_class(subcommand_name)
-        subcommand = subcommand_class.new("#{invocation_path} #{subcommand_name}", context)
-        self.class.recognised_options.each do |option|
-          option_set = instance_variable_defined?(option.ivar_name)
-          if option_set && subcommand.respond_to?(option.write_method)
-            subcommand.send(option.write_method, self.send(option.read_method))
-          end
-        end
-        subcommand.run(subcommand_arguments)
-      end
-
-      private
-
-      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
-
-    end
-
-  end
-end