ing 0.1.2 → 0.1.5

data/README.md

@@ -39,7 +39,7 @@ simplified to
 
 The "subcommand" is your task. To take some examples.
 
-    ing -r./path/to/some/task.rb some:task run something --verbose
+    ing -r ./path/to/some/task.rb some:task run something --verbose
     
   1. `ing -r` loads specified ruby files or libraries/gems; then
   2. it dispatches to `Some::Task.new(:verbose => true).run("something")`.
@@ -53,7 +53,7 @@ By default, it requires a file `./ing.rb` if it exists (the equivalent of
 Rakefile or Thorfile). In which case, assuming your task class is
 defined or loaded from there, the command can be simply 
 
-    ing some:task run --verbose
+    ing some:task run something --verbose
 
 ### Built-in commands
 
@@ -129,8 +129,8 @@ end
     
 As you can see, the second arg corresponds to the method name. `call` is what
 gets called when there is no second arg.  Organizing the methods like this means
-you can also do `ing test type unit`: extra non-option arguments are passed into 
-the method as parameters.  
+you can also do `ing test type custom`: extra non-option arguments are passed 
+into the method as parameters.  
 
 For more worked examples of ing tasks, see the 
 [examples](ing/blob/master/examples) directory.
@@ -140,15 +140,18 @@ For more worked examples of ing tasks, see the
 ### Option arguments
 
 Your tasks (ing subcommands) can specify what options they take by defining a 
-class method `specify_options`.  The best way to understand how this is done is 
-by example:
+class method `specify_options`.  For example:
 
 ```ruby
 class Cleanup
 
-  def self.specify_options(expect)
-    expect.opt :quiet, "Run silently"
-    expect.opt :path,  "Path to clean up", :type => :string, :default => '.'
+  def self.specify_options(spec)
+    spec.text "Clean up your path"
+    spec.text "\nUsage:"
+    spec.text "ing cleanup [OPTIONS]"
+    spec.text "\nOptions:"
+    spec.opt :quiet, "Run silently"
+    spec.opt :path,  "Path to clean up", :type => :string, :default => '.'
   end
     
   attr_accessor :options
@@ -163,12 +166,46 @@ end
 
 The syntax used in `self.specify_options` is Trollop - in fact what you are 
 doing is building a `Trollop::Parser` which then emits the parsed options into 
-your constructor. In general your constructor should just save the options to
+your constructor. 
+
+In general your constructor should just save the options to
 an instance variable like this, but in some cases you might want to do further
 processing of the passed options.
 
 [MORE](ing/blob/master/OPTIONS.md)
 
+### Using the Task base class
+
+To save some boilerplate, and to allow more flexible options specification, 
+as well as a few more conveniences, you can inherit from `Ing::Task` and 
+rewrite this example as:
+
+```ruby
+class Cleanup < Ing::Task
+  desc "Clean up your path"
+  usage "ing cleanup [OPTIONS]"
+  opt :quiet, "Run silently"
+  opt :path,  "Path to clean up", :type => :string, :default => '.'
+
+  # ...
+end
+```
+
+This gives you a slightly more automated help message, with the description
+lines followed by usage followed by options, and with headers for each section.
+
+`Ing::Task` also lets you inherit options. Say you have another task:
+
+```ruby
+class BigCleanup < Cleanup
+  opt :servers, "On servers", :type => :string, :multi => true
+end
+```
+
+This task will have the two options from its superclass as well as its own. 
+(Note the description and usage lines are _not_ inherited this way, only the 
+options).
+
 ### Generator tasks
 
 If you want to use Thor-ish generator methods, your task classes need a few more
@@ -177,7 +214,7 @@ things added to their interface. Basically, it should look something like this.
 ```ruby
 class MyGenerator
 
-  def self.specify_options(expect)
+  def self.specify_options(spec)
     # ...
   end
   
@@ -207,6 +244,11 @@ The generator methods need `:destination_root`, `:source_root`, and `:shell`.
 Also, `include Ing::Files` _after_ you specify any options (this is because
 `Ing::Files` adds several options automatically).
 
+If you prefer, you can inherit from `Ing::Generator`, which gives you all of 
+the above defaults, plus the functionality of `Ing::Task`.
+
+Like `Ing::Task`, `Ing::Generator` is simply a convenience for common scenarios.
+
 [MORE](ing/blob/master/GENERATORS.md)
 
 ## Motivation

data/lib/ing.rb

@@ -7,6 +7,8 @@
  'ing/common_options',
  'ing/boot',
  'ing/files',
+ 'ing/task',
+ 'ing/generator',
  'ing/commands/implicit',
  'ing/commands/list',
  'ing/commands/help',

data/lib/ing/boot.rb

@@ -1,10 +1,11 @@
-# Base implementation of boot dispatch
-# Mixed in to Commands::Implicit, Commands::Generate
-# Note this does NOT provide any options, only provides implementation.
-# Assumes target class will provide +namespace+ option, otherwise defaults to
-# global namespace (::Object).
-#
-module Ing
+module Ing
+
+  # Base implementation of boot dispatch
+  # Mixed in to Commands::Implicit, Commands::Generate
+  # Note this does NOT provide any options, only provides implementation.
+  # Assumes target class will provide +namespace+ option, otherwise defaults to
+  # global namespace (::Object).
+  #
   module Boot
 
     # Configure the command prior to dispatch.

data/lib/ing/common_options.rb

@@ -1,5 +1,6 @@
-# Common options for built-in Ing commands
-module Ing
+module Ing
+
+  # Common options for built-in Ing commands
   module CommonOptions
  
     # a bit of trickiness to change a singleton method...

data/lib/ing/dispatcher.rb

@@ -3,6 +3,17 @@ require 'set'
       
 module Ing
 
+  # Generic router for ing commands (both built-in and user-defined).
+  # Resolves class, parses options with Trollop if target class 
+  # defines +specify_options+, then dispatches like (simplifying):
+  #
+  #   Target.new(options).send(*args)
+  #
+  # if the target is class-like, i.e. responds to +new+. Otherwise it dispatches
+  # to the target as a callable:
+  #   
+  #   Target.call(*args, options)
+  #
   class Dispatcher
     
     # Global set of dispatched commands as [dispatch_class, dispatch_meth], 
@@ -35,7 +46,6 @@ module Ing
       ns                  = Util.namespaced_const_get(namespaces)
       self.dispatch_class = Util.namespaced_const_get(classes, ns)
       self.dispatch_meth  = extract_method!(args, dispatch_class)
-      self.options        = parse_options!(args, dispatch_class) || {}
       self.args           = args
       @invoking           = false
     end
@@ -92,6 +102,7 @@ module Ing
     end
     
     def execute
+      self.options = parse_options!(args, dispatch_class) || {}
       if dispatch_class.respond_to?(:new)
         cmd = dispatch_class.new(options)
         yield cmd if block_given?

data/lib/ing/files.rb

@@ -32,12 +32,17 @@ require File.expand_path('actions/file_manipulation', File.dirname(__FILE__))
 require File.expand_path('actions/inject_into_file', File.dirname(__FILE__))
 
 
-# Interface with base class:
-#  - attr_reader :source_root, :destination_root
-#  - attr_reader :shell, :options
-#  - self.specify_options (optional; adds to it if defined)
 module Ing
   
+  # Provides filesystem actions using the same interface as Thor::Actions
+  #
+  # The target class must provide at least:
+  #   attr_reader :source_root, :destination_root
+  #   attr_reader :shell, :options
+  #
+  # Adds to target class options:
+  #   verbose, force, pretend, revoke, quiet, skip.
+  #
   module Files
 
     # a bit of trickiness to change a singleton method...

data/lib/ing/generator.rb

@@ -0,0 +1,26 @@
+module Ing
+  class Generator < Task
+        
+    opt :dest, "Destination root", :type => :string
+    opt :source, "Source root", :type => :string
+        
+    include Ing::Files
+        
+    # Destination root for filesystem actions
+    def destination_root
+      File.expand_path(options[:dest])
+    end
+    
+    # Source root for filesystem actions
+    def source_root
+      File.expand_path(options[:source])
+    end
+    
+    def initialize(options)
+      super
+      validate_option_exists :dest, 'destination_root'
+      validate_option_exists :source, 'source_root'
+    end
+        
+  end
+end

data/lib/ing/shell.rb

@@ -1,4 +1,27 @@
-require 'fileutils'
+#
+# Copyright (c) 2008 Yehuda Katz, Eric Hodel, et al.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# 
+
+require 'fileutils'
 require 'tempfile'
 
 module Ing

data/lib/ing/task.rb

@@ -0,0 +1,176 @@
+
+module Ing
+
+  # A base class to simplify typical task use-cases.
+  # Adds some class methods and state to allow inherited options/flexibly-
+  # ordered option specification.
+  # Note that options are inherited to subclasses, but description and usage
+  # lines are not.
+  #
+  class Task
+
+    class << self
+    
+      def inherited(subclass)
+        subclass.set_options self.options.dup
+      end
+      
+      # Modify the option named +name+ according to +specs+ (Hash).
+      # Option will be created if it doesn't exist.
+      #
+      # Example:
+      #
+      #   modify_option :file, :required => true
+      #
+      def modify_option(name, specs)
+        opt(name) unless options[name]
+        options[name].opts.merge!(specs)
+      end
+      
+      # Modify the default for option +name+ to +val+.
+      # Option will be created if it doesn't exist.
+      def default(name, val)
+        modify_option name, {:default => val}
+      end
+            
+      # Add a description line
+      def desc(line="")
+        desc_lines << line
+      end
+      alias description desc
+      
+      # Add a usage line
+      def usage(line="")
+        usage_lines << line
+      end
+      
+      # Add an option. Note the syntax is identical to +Trollop::Parser#opt+
+      def opt(name, desc="", settings={})
+        options[name] = Option.new(name, desc, settings)
+      end
+      alias option opt
+      
+      # Build option parser based on desc, usage, and options (including
+      # inherited options). This method is called by `Ing::Dispatcher`.
+      #
+      def specify_options(parser)
+        desc_lines.each do |line|
+          parser.text line
+        end
+        unless usage_lines.empty?
+          parser.text "\nUsage:"
+          usage_lines.each do |line|
+            parser.text line
+          end
+        end
+        unless options.empty?
+          parser.text "\nOptions:"
+          options.each do |name, opt|
+            parser.opt *opt.to_args
+          end
+        end
+      end
+      
+      # Description lines
+      def desc_lines
+        @desc_lines ||= []
+      end
+      
+      # Usage lines
+      def usage_lines
+        @usage_lines ||= []
+      end
+      
+      # Options hash. Note that in a subclass, options are copied down from 
+      # superclass.
+      def options
+        @options ||= {}
+      end
+      
+      protected
+      
+      def set_options(o)  #:nodoc:
+        @options = o
+      end
+      
+    end
+    
+    attr_accessor :options, :shell
+    def initialize(options)
+      self.options = initial_options(options)
+    end
+    
+    # Override in subclass for adjusting given options on initialization
+    def initial_options(given)
+      given
+    end
+
+    # Use in initialization for option validation (post-parsing).
+    #
+    # Example:
+    #
+    #   validate_option(:color, "Color must be :black or :white") do |actual|
+    #     [:black, :white].include?(actual)
+    #   end
+    #
+    def validate_option(opt, desc=opt, msg=nil)
+      msg ||= "Error in option #{desc} for `#{self.class}`."
+      !!yield(self.options[opt]) or raise ArgumentError, msg
+    end
+    
+    # Validate that the option was passed or otherwise defaulted to something truthy.
+    # Note that in most cases, instead you should set :required => true on the option
+    # and let Trollop catch the error -- rather than catching it post-parsing.
+    #
+    # Note +validate_option_exists+ will raise an error if the option is passed 
+    # but false or nil, unlike the Trollop parser.
+    #
+    def validate_option_exists(opt, desc=opt)
+      msg = "No #{desc} specified for #{self.class}. You must either " +
+            "specify a `--#{opt}` option or set a default in #{self.class} or " +
+            "in its superclass(es)."
+      validate_option(opt, desc, msg) {|val| val }
+    end
+    
+  end
+  
+  class Option < Struct.new(:name, :desc, :opts)
+    
+    def initialize(*args)
+      super
+      self.opts ||= {}
+    end
+    
+    def default; opts[:default]; end
+    def default=(val)
+      opts[:default] = val
+    end
+    
+    def type; opts[:type]; end
+    def type=(val)
+      opts[:type] = val
+    end
+    
+    def multi; opts[:multi]; end
+    def multi=(val)
+      opts[:multi] = val
+    end
+    
+    def long; opts[:long]; end
+    def long=(val)
+      opts[:long] = val
+    end    
+    
+    def short; opts[:short]; end
+    def short=(val)
+      opts[:short] = val
+    end
+    
+    def to_args
+      [name, desc, opts]
+    end
+    
+  end
+  
+end
+

data/lib/ing/version.rb

@@ -1,3 +1,3 @@
 module Ing
-  VERSION = '0.1.2'
+  VERSION = '0.1.5'
 end

data/test/acceptance/ing_task_tests.rb

@@ -0,0 +1,54 @@
+require File.expand_path('../test_helper', File.dirname(__FILE__))
+
+describe Ing::Task do
+  include TestHelpers
+  
+  def capture_help(args)
+    capture(:stdout) { Ing.run ["help", "-n", "object"] + args }
+  end
+
+  def capture_run(args)
+    capture(:stdout) { Ing.run args }
+  end
+  
+  describe "single inheritance" do
+  
+    subject { ["simple_task"] }
+    
+    it "help should display the description, followed by usage, followed by options" do
+      lines = capture_help(subject).split("\n")
+      assert_equal 9, lines.length
+      assert_equal "My great task of immense importance", lines[0]
+      assert_equal "A simple example of a task using Ing::Task", lines[1]
+      assert_empty lines[2]
+      assert_equal "Usage:", lines[3]
+      assert_equal "  ing simple_task [OPTIONS]", lines[4]
+      assert_empty lines[5]
+      assert_equal "Options:", lines[6]
+      assert_match /--fast/, lines[7]
+      assert_match /--altitude/, lines[8]
+    end
+    
+  end
+
+  describe "double inheritance" do
+  
+    subject { ["big_task"] }
+    
+    it "help should display all the options defined by the task and its superclass" do
+      output = capture_help(subject)
+      assert_match(/^\s*--fast/, output)
+      assert_match(/^\s*--altitude/, output)
+      assert_match(/^\s*--yards/, output)
+      assert_match(/^\s*--color/, output)
+    end
+    
+    it "run should reflect modifications to superclass options" do
+      output = capture_help(subject)
+      assert_match(/^\s*--fast.+\(default: true\)/, output)
+      assert_match(/^\s*--altitude\, -l.+\(default: 2500\)/, output)      
+    end
+    
+  end
+  
+end

data/test/fixtures/task.ing.rb

@@ -34,3 +34,29 @@ class Amazing
   
 end
 
+
+
+class SimpleTask < Ing::Task
+  
+  desc  "My great task of immense importance"
+  desc  "A simple example of a task using Ing::Task"
+  usage "  ing simple_task [OPTIONS]"
+  opt   :fast, "Run it at fast speed"
+  opt   :altitude, "Start altitude", :type => :integer
+  
+  def call
+    # ....
+  end
+  
+end
+
+class BigTask < SimpleTask
+
+  desc "Even bigger!"
+  opt :yards, "Yards of fishing line given", :type => :integer, :default => 25
+  opt :color, "Color of cloth", :type => :string, :default => 'green'
+  
+  default :fast, true
+  modify_option :altitude, :short => 'l', :default => 2500
+  
+end

data/todo.yml

@@ -3,4 +3,3 @@
 - add Shell::Color
 - remove global Ing.shell_class, specify via color switch
 - incorporate gsub_file patch, patches to Shell
-- add a generator base class for the common use-case

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ing
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-16 00:00:00.000000000Z
+date: 2012-09-17 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &17352160 !ruby/object:Gem::Requirement
+  requirement: &14733000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *17352160
+  version_requirements: *14733000
 - !ruby/object:Gem::Dependency
   name: fakeweb
-  requirement: &17351600 !ruby/object:Gem::Requirement
+  requirement: &14677360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *17351600
+  version_requirements: *14677360
 description: ! "\nAn alternative to Rake and Thor, Ing has a command-line syntax similar
   to \nThor's, and it incorporates Thor's (Rails') generator methods and shell \nconventions.
   But unlike Thor or Rake, it does not define its own DSL. Your tasks\ncorrespond
@@ -70,14 +70,17 @@ files:
 - lib/ing/common_options.rb
 - lib/ing/dispatcher.rb
 - lib/ing/files.rb
+- lib/ing/generator.rb
 - lib/ing/lib_trollop.rb
 - lib/ing/shell.rb
+- lib/ing/task.rb
 - lib/ing/trollop/parser.rb
 - lib/ing/util.rb
 - lib/ing/version.rb
 - lib/thor/actions/file_manipulation.rb
 - lib/thor/shell/basic.rb
 - test/acceptance/ing_run_tests.rb
+- test/acceptance/ing_task_tests.rb
 - test/actions/create_file_spec.rb
 - test/actions/create_link_spec.rb
 - test/actions/directory_spec.rb
@@ -132,6 +135,7 @@ specification_version: 3
 summary: Vanilla ruby command-line scripting
 test_files:
 - test/acceptance/ing_run_tests.rb
+- test/acceptance/ing_task_tests.rb
 - test/actions/create_file_spec.rb
 - test/actions/create_link_spec.rb
 - test/actions/directory_spec.rb