thor 0.13.4 → 0.14.3

data/lib/thor.rb

@@ -1,6 +1,5 @@
 require 'thor/base'
 
-# TODO: Update thor to allow for git-style CLI (git bisect run)
 class Thor
   class << self
     # Sets the default task when thor is executed without an explicit task to be called.
@@ -24,6 +23,7 @@ class Thor
     # ==== Parameters
     # usage<String>
     # description<String>
+    # options<String>
     #
     def desc(usage, description, options={})
       if options[:for]
@@ -31,7 +31,21 @@ class Thor
         task.usage = usage             if usage
         task.description = description if description
       else
-        @usage, @desc = usage, description
+        @usage, @desc, @hide = usage, description, options[:hide] || false
+      end
+    end
+
+    # Defines the long description of the next task.
+    #
+    # ==== Parameters
+    # long description<String>
+    #
+    def long_desc(long_description, options={})
+      if options[:for]
+        task = find_and_refresh_task(options[:for])
+        task.long_description = long_description if long_description
+      else
+        @long_desc = long_description
       end
     end
 
@@ -112,32 +126,6 @@ class Thor
       build_option(name, options, scope)
     end
 
-    # Parses the task and options from the given args, instantiate the class
-    # and invoke the task. This method is used when the arguments must be parsed
-    # from an array. If you are inside Ruby and want to use a Thor class, you
-    # can simply initialize it:
-    #
-    #   script = MyScript.new(args, options, config)
-    #   script.invoke(:task, first_arg, second_arg, third_arg)
-    #
-    def start(original_args=ARGV, config={})
-      super do |given_args|
-        meth = normalize_task_name(given_args.shift)
-        task = all_tasks[meth]
-
-        if task
-          args, opts = Thor::Options.split(given_args)
-          config.merge!(:task_options => task.options)
-        else
-          args, opts = given_args, {}
-        end
-
-        task ||= Thor::Task::Dynamic.new(meth)
-        trailing = args[Range.new(arguments.size, -1)]
-        new(args, opts, config).invoke(task, trailing || [])
-      end
-    end
-
     # Prints help information for the given task.
     #
     # ==== Parameters
@@ -153,7 +141,12 @@ class Thor
       shell.say "  #{banner(task)}"
       shell.say
       class_options_help(shell, nil => task.options.map { |_, o| o })
-      shell.say task.description
+      if task.long_description
+        shell.say "Description:"
+        shell.print_wrapped(task.long_description, :ident => 2)
+      else
+        shell.say task.description
+      end
     end
 
     # Prints help information for this class.
@@ -161,8 +154,8 @@ class Thor
     # ==== Parameters
     # shell<Thor::Shell>
     #
-    def help(shell)
-      list = printable_tasks
+    def help(shell, subcommand = false)
+      list = printable_tasks(true, subcommand)
       Thor::Util.thor_classes_in(self).each do |klass|
         list += klass.printable_tasks(false)
       end
@@ -175,28 +168,91 @@ class Thor
     end
 
     # Returns tasks ready to be printed.
-    def printable_tasks(all=true)
+    def printable_tasks(all = true, subcommand = false)
       (all ? all_tasks : tasks).map do |_, task|
+        next if task.hidden?
         item = []
-        item << banner(task)
+        item << banner(task, false, subcommand)
         item << (task.description ? "# #{task.description.gsub(/\s+/m,' ')}" : "")
         item
+      end.compact
+    end
+
+    def subcommands
+      @subcommands ||= from_superclass(:subcommands, [])
+    end
+
+    def subcommand(subcommand, subcommand_class)
+      self.subcommands << subcommand.to_s
+      subcommand_class.subcommand_help subcommand
+      define_method(subcommand) { |*args| invoke subcommand_class, args }
+    end
+
+    # Extend check unknown options to accept a hash of conditions.
+    #
+    # === Parameters
+    # options<Hash>: A hash containing :only and/or :except keys
+    def check_unknown_options!(options={})
+      @check_unknown_options ||= Hash.new
+      options.each do |key, value|
+        if value
+          @check_unknown_options[key] = Array(value)
+        else
+          @check_unknown_options.delete(key)
+        end
       end
+      @check_unknown_options
     end
 
-    def handle_argument_error(task, error) #:nodoc:
-      raise InvocationError, "#{task.name.inspect} was called incorrectly. Call as #{task.formatted_usage(self, banner_base == "thor").inspect}."
+    # Overwrite check_unknown_options? to take subcommands and options into account.
+    def check_unknown_options?(config) #:nodoc:
+      options = check_unknown_options
+      return false unless options
+
+      task = config[:current_task]
+      return true unless task
+
+      name = task.name
+
+      if subcommands.include?(name)
+        false
+      elsif options[:except]
+        !options[:except].include?(name.to_sym)
+      elsif options[:only]
+        options[:only].include?(name.to_sym)
+      else
+        true
+      end
     end
 
     protected
 
+      # The method responsible for dispatching given the args.
+      def dispatch(meth, given_args, given_opts, config) #:nodoc:
+        meth ||= retrieve_task_name(given_args)
+        task = all_tasks[normalize_task_name(meth)]
+
+        if task
+          args, opts = Thor::Options.split(given_args)
+        else
+          args, opts = given_args, nil
+          task = Thor::DynamicTask.new(meth)
+        end
+
+        opts = given_opts || opts || []
+        config.merge!(:current_task => task, :task_options => task.options)
+
+        trailing = args[Range.new(arguments.size, -1)]
+        new(args, opts, config).invoke_task(task, trailing || [])
+      end
+
       # The banner for this class. You can customize it if you are invoking the
       # thor class by another ways which is not the Thor::Runner. It receives
       # the task that is going to be invoked and a boolean which indicates if
       # the namespace should be displayed as arguments.
       #
-      def banner(task)
-        "#{banner_base} #{task.formatted_usage(self, banner_base == "thor")}"
+      def banner(task, namespace = nil, subcommand = false)
+        "#{basename} #{task.formatted_usage(self, $thor_runner, subcommand)}"
       end
 
       def baseclass #:nodoc:
@@ -205,10 +261,11 @@ class Thor
 
       def create_task(meth) #:nodoc:
         if @usage && @desc
-          tasks[meth.to_s] = Thor::Task.new(meth, @desc, @usage, method_options)
-          @usage, @desc, @method_options = nil
+          base_class = @hide ? Thor::HiddenTask : Thor::Task
+          tasks[meth] = base_class.new(meth, @desc, @long_desc, @usage, method_options)
+          @usage, @desc, @long_desc, @method_options, @hide = nil
           true
-        elsif self.all_tasks[meth.to_s] || meth.to_sym == :method_missing
+        elsif self.all_tasks[meth] || meth == "method_missing"
           true
         else
           puts "[WARNING] Attempted to create task #{meth.inspect} without usage or description. " <<
@@ -223,14 +280,30 @@ class Thor
         @method_options = nil
       end
 
+      # Retrieve the task name from given args.
+      def retrieve_task_name(args) #:nodoc:
+        meth = args.first.to_s unless args.empty?
+
+        if meth && (map[meth] || meth !~ /^\-/)
+          args.shift
+        else
+          nil
+        end
+      end
+
       # Receives a task name (can be nil), and try to get a map from it.
       # If a map can't be found use the sent name or the default task.
-      #
       def normalize_task_name(meth) #:nodoc:
-        mapping = map[meth.to_s]
-        meth = mapping || meth || default_task
+        meth = map[meth.to_s] || meth || default_task
         meth.to_s.gsub('-','_') # treat foo-bar > foo_bar
       end
+
+      def subcommand_help(cmd)
+        desc "help [COMMAND]", "Describe subcommands or one specific subcommand"
+        class_eval <<-RUBY
+          def help(task = nil, subcommand = true); super; end
+        RUBY
+      end
   end
 
   include Thor::Base
@@ -238,7 +311,7 @@ class Thor
   map HELP_MAPPINGS => :help
 
   desc "help [TASK]", "Describe available tasks or one specific task"
-  def help(task=nil)
-    task ? self.class.task_help(shell, task) : self.class.help(shell)
+  def help(task = nil, subcommand = false)
+    task ? self.class.task_help(shell, task) : self.class.help(shell, subcommand)
   end
 end

data/spec/actions/directory_spec.rb

@@ -37,7 +37,7 @@ describe Thor::Actions::Directory do
     it "raises an error if the source does not exist" do
       lambda {
         invoke! "unknown"
-      }.must raise_error(Thor::Error, /Could not find "unknown" in source paths/)
+      }.must raise_error(Thor::Error, /Could not find "unknown" in any of your source paths/)
     end
 
     it "copies the whole directory recursively to the default destination" do
@@ -84,7 +84,7 @@ describe Thor::Actions::Directory do
       File.directory?(file).must be_true
     end
 
-    it "does not copy .empty_diretories files" do
+    it "does not copy .empty_directory files" do
       invoke! "doc", "docs"
       file = File.join(destination_root, "docs", "components", ".empty_directory")
       File.exists?(file).must be_false

data/spec/actions/file_manipulation_spec.rb

@@ -117,6 +117,13 @@ describe Thor::Actions do
   end
 
   describe "#template" do
+    it "allows using block helpers in the template" do
+      action :template, "doc/block_helper.rb"
+
+      file = File.join(destination_root, "doc/block_helper.rb")
+      File.read(file).must == "Hello world!"
+    end
+
     it "evaluates the template given as source" do
       runner.instance_variable_set("@klass", "Config")
       action :template, "doc/config.rb"

data/spec/actions_spec.rb

@@ -107,7 +107,7 @@ describe Thor::Actions do
       it "raises an error if source path is empty" do
         lambda {
           A.new.find_in_source_paths("foo")
-        }.must raise_error(Thor::Error, /You don't have any source path defined for class A/)
+        }.must raise_error(Thor::Error, /Currently you have no source paths/)
       end
 
       it "finds a template inside the source path" do
@@ -192,10 +192,28 @@ describe Thor::Actions do
         @foo = "FOO"
         say_status :cool, :padding
       TEMPLATE
-      @template.instance_eval "def read; self; end" # Make the string respond to read
+      @template.stub(:read).and_return(@template)
 
+      @file = '/'
+      runner.stub(:open).and_return(@template)
+    end
+
+    it "accepts a URL as the path" do
       @file = "http://gist.github.com/103208.txt"
-      runner.should_receive(:open).and_return(@template)
+      runner.should_receive(:open).with(@file, "Accept" => "application/x-thor-template").and_return(@template)
+      action(:apply, @file)
+    end
+
+    it "accepts a secure URL as the path" do
+      @file = "https://gist.github.com/103208.txt"
+      runner.should_receive(:open).with(@file, "Accept" => "application/x-thor-template").and_return(@template)
+      action(:apply, @file)
+    end
+
+    it "accepts a local file path with spaces" do
+      @file = File.expand_path("fixtures/path with spaces", File.dirname(__FILE__))
+      runner.should_receive(:open).with(@file).and_return(@template)
+      action(:apply, @file)
     end
 
     it "opens a file and executes its content in the instance binding" do

data/spec/base_spec.rb

@@ -74,7 +74,7 @@ describe Thor::Base do
       MyCounter.start(["1", "2", "--third", "3"])[2].must == 3
     end
 
-    it "does not create an acessor for it" do
+    it "does not create an accessor for it" do
       BrokenCounter.start(["1", "2", "--third", "3"])[3].must be_false
     end
   end
@@ -176,8 +176,8 @@ describe Thor::Base do
     it "returns tracked subclasses, grouped by the files they come from" do
       thorfile = File.join(File.dirname(__FILE__), "fixtures", "script.thor")
       Thor::Base.subclass_files[File.expand_path(thorfile)].must == [
-        MyScript, MyScript::AnotherScript, MyChildScript, Scripts::MyScript,
-        Scripts::MyDefaults, Scripts::ChildDefault
+        MyScript, MyScript::AnotherScript, MyChildScript, Barn,
+        Scripts::MyScript, Scripts::MyDefaults, Scripts::ChildDefault
       ]
     end
 
@@ -244,6 +244,12 @@ describe Thor::Base do
         MyScript.start(["foo", "bar", "--force", "true", "--unknown", "baz"])
       }.strip.must == "Unknown switches '--unknown'"
     end
+
+    it "checks unknown options except specified" do
+      capture(:stderr) {
+        MyScript.start(["with_optional", "NAME", "--omg", "--invalid"]).must == ["NAME", {}]
+      }.strip.must be_empty
+    end
   end
 
   describe "attr_*" do

data/spec/fixtures/doc/block_helper.rb

@@ -0,0 +1,3 @@
+<% world do -%>
+Hello
+<% end -%>

data/spec/fixtures/group.thor

@@ -6,9 +6,7 @@ class MyCounter < Thor::Group
     from_superclass(:get_from_super, 13)
   end
 
-  def self.source_root
-    File.expand_path(File.dirname(__FILE__))
-  end
+  source_root File.expand_path(File.dirname(__FILE__))
   source_paths << File.expand_path("broken", File.dirname(__FILE__))
 
   argument :first,     :type => :numeric
@@ -20,7 +18,7 @@ class MyCounter < Thor::Group
 
   desc <<-FOO
 Description:
-  This generator run three tasks: one, two and three.
+  This generator runs three tasks: one, two and three.
 FOO
 
   def one
@@ -39,6 +37,13 @@ FOO
     super
     base.source_paths.unshift(File.expand_path(File.join(File.dirname(__FILE__), "doc")))
   end
+
+  no_tasks do
+    def world(&block)
+      result = capture(&block)
+      concat(result.strip + " world!")
+    end
+  end
 end
 
 class ClearCounter < MyCounter
@@ -81,3 +86,10 @@ class WhinyGenerator < Thor::Group
   def wrong_arity(required)
   end
 end
+
+class TaskConflict < Thor::Group
+  desc "A group with the same name as a default task"
+  def group
+    puts "group"
+  end
+end

data/spec/fixtures/script.thor

@@ -1,5 +1,5 @@
 class MyScript < Thor
-  check_unknown_options!
+  check_unknown_options! :except => :with_optional
 
   attr_accessor :some_attribute
   attr_writer :another_attribute
@@ -26,6 +26,11 @@ class MyScript < Thor
     [type]
   end
 
+  desc "hidden TYPE", "this is hidden", :hide => true
+  def hidden(type)
+    [type]
+  end
+
   desc "foo BAR", <<END
 do some fooing
   This is more info!
@@ -37,6 +42,7 @@ END
   end
 
   desc "example_default_task", "example!"
+  method_options :with => :string
   def example_default_task
     options.empty? ? "default task" : options
   end
@@ -52,6 +58,12 @@ END
   end
 
   desc "long_description", "a" * 80
+  long_desc <<-D
+    This is a really really really long description.
+    Here you go. So very long.
+
+    It even has two paragraphs.
+  D
   def long_description
   end
 
@@ -60,6 +72,10 @@ END
   end
 
   method_options :all => :boolean
+  method_option :lazy, :lazy_default => "yes"
+  method_option :lazy_numeric, :type => :numeric, :lazy_default => 42
+  method_option :lazy_array,   :type => :array,   :lazy_default => %w[eat at joes]
+  method_option :lazy_hash,    :type => :hash,    :lazy_default => {'swedish' => 'meatballs'}
   desc "with_optional NAME", "invoke with optional name"
   def with_optional(name=nil)
     [ name, options ]
@@ -114,6 +130,24 @@ class MyChildScript < MyScript
   remove_task :boom, :undefine => true
 end
 
+class Barn < Thor
+  desc "open [ITEM]", "open the barn door"
+  def open(item = nil)
+    if item == "shotgun"
+      puts "That's going to leave a mark."
+    else
+      puts "Open sesame!"
+    end
+  end
+
+  desc "paint [COLOR]", "paint the barn"
+  method_option :coats, :type => :numeric, :default => 2, :desc => 'how many coats of paint'
+  def paint(color='red')
+    puts "#{options[:coats]} coats of #{color} paint"
+  end
+
+end
+
 module Scripts
   class MyScript < MyChildScript
     argument :accessor, :type => :string
@@ -126,11 +160,21 @@ module Scripts
   end
 
   class MyDefaults < Thor
+    check_unknown_options!
+
     namespace :default
-    desc "test", "prints 'test'"
-    def test
-      puts "test"
+    desc "cow", "prints 'moo'"
+    def cow
+      puts "moo"
     end
+
+    desc "task_conflict", "only gets called when prepended with a colon"
+    def task_conflict
+      puts "task"
+    end
+
+    desc "barn", "commands to manage the barn"
+    subcommand "barn", Barn
   end
 
   class ChildDefault < Thor

data/spec/group_spec.rb

@@ -36,11 +36,11 @@ describe Thor::Group do
 
   describe "#desc" do
     it "sets the description for a given class" do
-      MyCounter.desc.must == "Description:\n  This generator run three tasks: one, two and three.\n"
+      MyCounter.desc.must == "Description:\n  This generator runs three tasks: one, two and three.\n"
     end
 
     it "can be inherited" do
-      BrokenCounter.desc.must == "Description:\n  This generator run three tasks: one, two and three.\n"
+      BrokenCounter.desc.must == "Description:\n  This generator runs three tasks: one, two and three.\n"
     end
 
     it "can be nil" do
@@ -59,7 +59,7 @@ describe Thor::Group do
 
     it "shows description" do
       @content.must =~ /Description:/
-      @content.must =~ /This generator run three tasks: one, two and three./
+      @content.must =~ /This generator runs three tasks: one, two and three./
     end
 
     it "shows options information" do

data/spec/invocation_spec.rb

@@ -37,13 +37,6 @@ describe Thor::Invocation do
       base.invoke(B, :one, ["Jose"]).must == "Valim, Jose"
     end
 
-    it "accepts a Thor instance as argument" do
-      invoked = B.new([], :last_name => "Valim")
-      base = A.new
-      base.invoke(invoked, :one, ["Jose"]).must == "Valim, Jose"
-      base.invoke(invoked, :one, ["Jose"]).must be_nil
-    end
-
     it "allows customized options to be given" do
       base = A.new([], :last_name => "Wrong")
       base.invoke(B, :one, ["Jose"], :last_name => "Valim").must == "Valim, Jose"
@@ -91,7 +84,7 @@ describe Thor::Invocation do
 
     it "raises Thor::UndefinedTaskError if the task can't be found even if all tasks where already executed" do
       base = C.new
-      silence(:stdout){ base.invoke }
+      silence(:stdout){ base.invoke_all }
 
       lambda do
         base.invoke("foo:bar")

data/spec/parser/option_spec.rb

@@ -6,8 +6,8 @@ describe Thor::Option do
     Thor::Option.parse(key, value)
   end
 
-  def option(name, description=nil, required=false, type=nil, default=nil, banner=nil, group=nil, aliases=[])
-    @option ||= Thor::Option.new(name, description, required, type, default, banner, group, aliases)
+  def option(name, *args)
+    @option ||= Thor::Option.new(name, *args)
   end
 
   describe "#parse" do

data/spec/parser/options_spec.rb

@@ -47,6 +47,11 @@ describe Thor::Options do
     it "accepts hashes" do
       Thor::Options.to_switches(:count => {:a => :b}).must == "--count a:b"
     end
+    
+    it "accepts underscored options" do
+      Thor::Options.to_switches(:under_score_option => "foo bar").must == '--under_score_option "foo bar"'
+    end
+    
   end
 
   describe "#parse" do
@@ -115,6 +120,18 @@ describe Thor::Options do
       parse("--asdf---asdf", "baz", "--foo", "--asdf---dsf--asdf").must == {"foo" => "--asdf---dsf--asdf"}
       check_unknown!
     end
+    
+    it "excepts underscores in commandline args hash for boolean" do
+      create :foo_bar => :boolean
+      parse("--foo_bar")["foo_bar"].must == true
+      parse("--no_foo_bar")["foo_bar"].must == false
+    end
+    
+    it "excepts underscores in commandline args hash for strings" do
+      create :foo_bar => :string, :baz_foo => :string
+      parse("--foo_bar", "baz")["foo_bar"].must == "baz"
+      parse("--baz_foo", "foo bar")["baz_foo"].must == "foo bar"
+    end
 
     describe "with no input" do
       it "and no switches returns an empty hash" do
@@ -170,12 +187,22 @@ describe Thor::Options do
         parse("--foo=12")["foo"].must == "12"
         parse("--foo=bar=baz")["foo"].must == "bar=baz"
       end
+      
+      it "must accept underscores switch=value assignment" do
+        create :foo_bar => :required
+        parse("--foo_bar=http://example.com/under_score/")["foo_bar"].must == "http://example.com/under_score/"
+      end
 
       it "accepts a --no-switch format" do
         create "--foo" => "bar"
         parse("--no-foo")["foo"].must be_nil
       end
 
+      it "does not consume an argument for --no-switch format" do
+        create "--cheese" => :string
+        parse('burger', '--no-cheese', 'fries')["cheese"].must be_nil
+      end
+
       it "accepts a --switch format on non required types" do
         create "--foo" => :string
         parse("--foo")["foo"].must == "foo"

data/spec/runner_spec.rb

@@ -30,9 +30,8 @@ describe Thor::Runner do
     end
 
     it "raises error if a class/task cannot be found" do
-      Thor::Runner.should_receive(:exit).with(1)
       content = capture(:stderr){ Thor::Runner.start(["help", "unknown"]) }
-      content.strip.must == 'Could not find namespace or task "unknown".'
+      content.strip.must == 'Could not find task "unknown" in "default" namespace.'
     end
   end
 
@@ -68,10 +67,9 @@ describe Thor::Runner do
     end
 
     it "raises an error if class/task can't be found" do
-      Thor::Runner.should_receive(:exit).with(1)
       ARGV.replace ["unknown"]
       content = capture(:stderr){ Thor::Runner.start }
-      content.strip.must == 'Could not find namespace or task "unknown".'
+      content.strip.must == 'Could not find task "unknown" in "default" namespace.'
     end
 
     it "does not swallow NoMethodErrors that occur inside the called method" do
@@ -87,7 +85,7 @@ describe Thor::Runner do
     it "does not swallow Thor InvocationError" do
       ARGV.replace ["my_script:animal"]
       content = capture(:stderr) { Thor::Runner.start }
-      content.strip.must == '"animal" was called incorrectly. Call as "my_script:animal TYPE".'
+      content.strip.must == '"animal" was called incorrectly. Call as "thor my_script:animal TYPE".'
     end
   end
 
@@ -145,12 +143,22 @@ describe Thor::Runner do
 
       it "presents tasks in the default namespace with an empty namespace" do
         ARGV.replace ["list"]
-        capture(:stdout) { Thor::Runner.start }.must =~ /^thor :test\s+# prints 'test'/m
+        capture(:stdout) { Thor::Runner.start }.must =~ /^thor :cow\s+# prints 'moo'/m
       end
 
       it "runs tasks with an empty namespace from the default namespace" do
-        ARGV.replace [":test"]
-        capture(:stdout) { Thor::Runner.start }.must == "test\n"
+        ARGV.replace [":task_conflict"]
+        capture(:stdout) { Thor::Runner.start }.must == "task\n"
+      end
+
+      it "runs groups even when there is a task with the same name" do
+        ARGV.replace ["task_conflict"]
+        capture(:stdout) { Thor::Runner.start }.must == "group\n"
+      end
+
+      it "runs tasks with no colon in the default namespace" do
+        ARGV.replace ["cow"]
+        capture(:stdout) { Thor::Runner.start }.must == "moo\n"
       end
     end