climate 0.6.0 → 0.7.0

data/README.md

@@ -62,3 +62,68 @@ There is a working example, `example.rb` that you can test out with
 or
 
     ruby -rrubygems -rclimate example.rb --help
+
+# rack-middleware like filtering
+
+Quite often in commands you might want some shared logic to do with setting up
+or tearing down an environment for your child commands.  For instance, you might
+want to setup an application environment, start a database transaction, or check
+some arguments are semantically correct in a way that is common based on a parent
+command, i.e:
+
+    class Parent < Climate::Command('parent')
+      def run(chain)
+        setup_logger
+        begin
+          chain.run
+        rescue => e
+          logger.error("oh noes!")
+          raise
+        end
+      end
+    end
+
+    class Child < Climate::Command('child')
+      subcommand_of Parent
+
+      def run
+        if all_ok?
+          do_the_thing
+        else
+          raise 'it went badly'
+        end
+      end
+    end
+
+The `run` method on non-leaf commands can also omit the chain argument, in which
+case you are not responsible for calling the next link in the chain, but you can
+still do some setup.
+
+# Accessing your parent command at execution time
+
+In the case where you have some parent command that gets all the top level
+options for your application, (i.e. config location, log mode), you may need to
+access this from your child commands.  You can do this with the `ancestor`
+instance method, or by proxying the method to your child class with
+`expose_ancestor_method`.  For example:
+
+    class Parent < Climate::Command('parent')
+      def useful_stuff ; end
+      def handy_service ; end
+    end
+
+    class Child < Climate::Command('child')
+      subcommand_of Parent
+
+      expose_ancestor_method Parent, :handy_service
+
+      def run
+        # finds the parent command instance so you can interrogate it
+        ancestor(Parent).useful_stuff
+
+        # handy_service was defined as an instance method using the
+        # #expose_ancestor_method above, but ultimately it is syntactic sugar
+        # for the above
+        handy_service.send_the_things
+      end
+    end

data/lib/climate/command.rb

@@ -24,14 +24,52 @@ module Climate
   #
   class Command
 
+    # Chain is a helper class for allowing parent commands to participate in
+    # command execution
+    class Chain
+
+      def initialize(commands)
+        @commands = commands
+      end
+
+      def empty?
+        @commands.empty?
+      end
+
+      def run
+        raise "Can't call run on an empty command chain" if empty?
+
+        next_command = @commands.shift
+
+        begin
+          if next_command.method(:run).arity == 1
+            next_command.run(self)
+          else
+            result = next_command.run
+            # we ignore the result from a run method with arity == 0 unless
+            # it is the last command in the chain.  Really this is only a
+            # convenience for testing, so we can assert the chain was followed
+            # properly
+            if empty?
+              result
+            else
+              self.run
+            end
+          end
+        rescue Climate::CommandError => e
+          e.command_class = next_command.class if e.command_class.nil?
+          raise
+        end
+      end
+    end
+
     class << self
       include ParsingMethods
 
-      # Create an instance of this command class and run it against the given
-      # arguments
+      # Recursively construct an array of commands
       # @param [Array<String>] argv A list of arguments, ARGV style
       # @param [Hash] options see {#initialize}
-      def run(argv, options={})
+      def build(argv, options={})
         begin
           instance = new(argv, options)
         rescue Trollop::HelpNeeded
@@ -39,18 +77,24 @@ module Climate
         end
 
         if subcommands.empty?
-          begin
-            instance.run
-          rescue Climate::CommandError => e
-            # make it easier on users
-            e.command_class = self if e.command_class.nil?
-            raise
-          end
+          [instance]
         else
-          find_and_run_subcommand(instance, options)
+          [instance, *find_and_build_subcommand(instance, options)]
         end
       end
 
+      def run(argv, options={})
+        command_instance_list = build(argv, options)
+        final_command = command_instance_list.last
+
+        if ! final_command.has_run?
+          raise NotImplementedError, "leaf command #{final_command} must implement #run"
+        end
+
+        runnable_commands = command_instance_list.select {|command| command.has_run? }
+        Chain.new(runnable_commands).run
+      end
+
       def ancestors(exclude_self=false)
         our_list = exclude_self ? [] : [self]
         parent.nil?? our_list : parent.ancestors + our_list
@@ -125,9 +169,21 @@ module Climate
       def has_subcommands? ; not subcommands.empty?   ; end
       def subcommands ; @subcommands ||= [] ; end
 
+      def expose_ancestor_method(ancestor_class, method_name)
+        define_method(method_name) do |*args|
+          ancestor(ancestor_class).send(method_name, *args)
+        end
+      end
+
+      def expose_ancestor_methods(ancestor_class, *method_names)
+        method_names.each do |method_name|
+          expose_ancestor_method(ancestor_class, method_name)
+        end
+      end
+
       private
 
-      def find_and_run_subcommand(parent, options)
+      def find_and_build_subcommand(parent, options)
         command_name, *arguments = parent.leftovers
 
         if command_name.nil?
@@ -138,7 +194,7 @@ module Climate
         found = subcommands.find {|c| c.command_name == command_name }
 
         if found
-          found.run(arguments, options.merge(:parent => parent))
+          found.build(arguments, options.merge(:parent => parent))
         else
           raise UnknownCommandError.new(command_name, parent)
         end
@@ -147,7 +203,7 @@ module Climate
     end
 
     # Create an instance of this command to be run.  You'll probably want to use
-    # {Command.run}
+    # {Command.run
     # @param [Array<String>] arguments ARGV style arguments to be parsed
     # @option options [Command] :parent The parent command, made available as {#parent}
     # @option options [IO] :stdout stream to use as stdout, defaulting to `$stdout`
@@ -202,10 +258,8 @@ module Climate
       end
     end
 
-    # Run the command, must be implemented by all commands that are not parent
-    # commands (leaf commands)
-    def run
-      raise NotImplementedError, "Leaf commands must implement a run method"
+    def has_run?
+      self.methods.include? :run
     end
 
     def exit(status)

data/lib/climate/version.rb

@@ -1,3 +1,3 @@
 module Climate
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

metadata

@@ -1,95 +1,95 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: climate
-version: !ruby/object:Gem::Version 
-  hash: 7
+version: !ruby/object:Gem::Version
+  version: 0.7.0
   prerelease: 
-  segments: 
-  - 0
-  - 6
-  - 0
-  version: 0.6.0
 platform: ruby
-authors: 
+authors:
 - Nick Griffiths
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2013-02-18 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2013-12-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: trollop
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 2
-        - 0
-        version: "2.0"
+      - !ruby/object:Gem::Version
+        version: '2.0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: minitest
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: yard
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: popen4
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: popen4
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id004
-description: Library, not a framework, for building command line interfaces to your ruby application
-email: 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Library, not a framework, for building command line interfaces to your
+  ruby application
+email:
 - nicobrevin@gmail.com
-executables: 
+executables:
 - climate
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
-- lib/climate/version.rb
+files:
+- lib/climate/command.rb
 - lib/climate/help/man.rb
 - lib/climate/command_compat.rb
-- lib/climate/command.rb
 - lib/climate/parser.rb
 - lib/climate/errors.rb
+- lib/climate/version.rb
 - lib/climate/script.rb
 - lib/climate/help.rb
 - lib/climate.rb
@@ -97,37 +97,27 @@ files:
 - bin/climate
 homepage: 
 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: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Library for building command line interfaces
 test_files: []
-
 has_rdoc: