thor 0.14.6 → 0.15.0

data/Thorfile

@@ -1,24 +1,30 @@
-# enconding: utf-8
+# encoding: utf-8
+$:.unshift File.expand_path("../lib", __FILE__)
+
+require 'bundler'
 require 'thor/rake_compat'
 
 class Default < Thor
   include Thor::RakeCompat
+  Bundler::GemHelper.install_tasks
 
-  require 'rspec/core/rake_task'
-  RSpec::Core::RakeTask.new(:spec)
+  desc "build", "Build thor-#{Thor::VERSION}.gem into the pkg directory"
+  def build
+    Rake::Task["build"].execute
+  end
 
-  require 'bundler'
-  Bundler::GemHelper.install_tasks
+  desc "install", "Build and install thor-#{Thor::VERSION}.gem into system gems"
+  def install
+    Rake::Task["install"].execute
+  end
+
+  desc "release", "Create tag v#{Thor::VERSION} and build and push thor-#{Thor::VERSION}.gem to Rubygems"
+  def release
+    Rake::Task["release"].execute
+  end
 
-  require 'rdoc/task'
-  if defined?(RDoc)
-    RDoc::Task.new do |rdoc|
-      rdoc.main     = 'README.md'
-      rdoc.rdoc_dir = 'rdoc'
-      rdoc.title    = 'thor'
-      rdoc.rdoc_files.include('README.md', 'LICENSE', 'CHANGELOG.rdoc', 'Thorfile')
-      rdoc.rdoc_files.include('lib/**/*.rb')
-      rdoc.options << '--line-numbers' << '--inline-source'
-    end
+  desc "spec", "Run RSpec code examples"
+  def spec
+    exec "rspec --color --format=documentation spec"
   end
 end

data/lib/thor.rb

@@ -5,7 +5,7 @@ class Thor
     # Sets the default task when thor is executed without an explicit task to be called.
     #
     # ==== Parameters
-    # meth<Symbol>:: name of the defaut task
+    # meth<Symbol>:: name of the default task
     #
     def default_task(meth=nil)
       case meth
@@ -28,7 +28,7 @@ class Thor
     def register(klass, subcommand_name, usage, description, options={})
       if klass <= Thor::Group
         desc usage, description, options
-        define_method(subcommand_name) { invoke klass }
+        define_method(subcommand_name) { |*args| invoke(klass, args) }
       else
         desc usage, description, options
         subcommand subcommand_name, klass
@@ -108,6 +108,8 @@ class Thor
       @method_options
     end
 
+    alias options method_options
+
     # Adds an option to the set of method options. If :for is given as option,
     # it allows you to change the options from a previous defined task.
     #
@@ -132,6 +134,7 @@ class Thor
     # :aliases  - Aliases for this option.
     # :type     - The type of the argument, can be :string, :hash, :array, :numeric or :boolean.
     # :banner   - String to show on usage notes.
+    # :hide     - If you want to hide this option from the help.
     #
     def method_option(name, options={})
       scope = if options[:for]
@@ -143,6 +146,8 @@ class Thor
       build_option(name, options, scope)
     end
 
+    alias option method_option
+
     # Prints help information for the given task.
     #
     # ==== Parameters
@@ -160,7 +165,7 @@ class Thor
       class_options_help(shell, nil => task.options.map { |_, o| o })
       if task.long_description
         shell.say "Description:"
-        shell.print_wrapped(task.long_description, :ident => 2)
+        shell.print_wrapped(task.long_description, :indent => 2)
       else
         shell.say task.description
       end
@@ -179,7 +184,7 @@ class Thor
       list.sort!{ |a,b| a[0] <=> b[0] }
 
       shell.say "Tasks:"
-      shell.print_table(list, :ident => 2, :truncate => true)
+      shell.print_table(list, :indent => 2, :truncate => true)
       shell.say
       class_options_help(shell)
     end
@@ -202,7 +207,11 @@ class Thor
     def subcommand(subcommand, subcommand_class)
       self.subcommands << subcommand.to_s
       subcommand_class.subcommand_help subcommand
-      define_method(subcommand) { |*args| invoke subcommand_class, args }
+
+      define_method(subcommand) do |*args|
+        args, opts = Thor::Arguments.split(args)
+        invoke subcommand_class, args, opts
+      end
     end
 
     # Extend check unknown options to accept a hash of conditions.
@@ -259,8 +268,11 @@ class Thor
         opts = given_opts || opts || []
         config.merge!(:current_task => task, :task_options => task.options)
 
+        instance = new(args, opts, config)
+        yield instance if block_given?
+        args = instance.args
         trailing = args[Range.new(arguments.size, -1)]
-        new(args, opts, config).invoke_task(task, trailing || [])
+        instance.invoke_task(task, trailing || [])
       end
 
       # The banner for this class. You can customize it if you are invoking the
@@ -300,7 +312,6 @@ class Thor
       # 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
@@ -308,11 +319,45 @@ class Thor
         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.
+      # receives a (possibly nil) task name and returns a name that is in
+      # the tasks hash. In addition to normalizing aliases, this logic
+      # will determine if a shortened command is an unambiguous prefix of
+      # a task or alias.
+      #
+      # +normalize_task_name+ also converts names like +animal-prison+
+      # into +animal_prison+.
       def normalize_task_name(meth) #:nodoc:
-        meth = map[meth.to_s] || meth || default_task
-        meth.to_s.gsub('-','_') # treat foo-bar > foo_bar
+        return default_task.to_s.gsub('-', '_') unless meth
+
+        possibilities = find_task_possibilities(meth)
+        if possibilities.size > 1
+          raise ArgumentError, "Ambiguous task #{meth} matches [#{possibilities.join(', ')}]"
+        elsif possibilities.size < 1
+          meth = meth || default_task
+        elsif map[meth]
+          meth = map[meth]
+        else
+          meth = possibilities.first
+        end
+
+        meth.to_s.gsub('-','_') # treat foo-bar as foo_bar
+      end
+
+      # this is the logic that takes the task name passed in by the user
+      # and determines whether it is an unambiguous prefix of a task or
+      # alias name.
+      def find_task_possibilities(meth)
+        len = meth.to_s.length
+        possibilities = all_tasks.merge(map).keys.select { |n| meth == n[0, len] }.sort
+        unique_possibilities = possibilities.map { |k| map[k] || k }.uniq
+
+        if possibilities.include?(meth)
+          [meth]
+        elsif unique_possibilities.size == 1
+          unique_possibilities
+        else
+          possibilities
+        end
       end
 
       def subcommand_help(cmd)

data/lib/thor/actions.rb

@@ -55,7 +55,7 @@ class Thor
                                :desc => "Run but do not make any changes"
 
         class_option :quiet, :type => :boolean, :aliases => "-q", :group => :runtime,
-                             :desc => "Supress status output"
+                             :desc => "Suppress status output"
 
         class_option :skip, :type => :boolean, :aliases => "-s", :group => :runtime,
                             :desc => "Skip files that already exist"
@@ -114,8 +114,12 @@ class Thor
     # the script started).
     #
     def relative_to_original_destination_root(path, remove_dot=true)
-      path = path.gsub(@destination_stack[0], '.')
-      remove_dot ? (path[2..-1] || '') : path
+      if path =~ /^#{@destination_stack[0]}/
+        path = path.gsub(@destination_stack[0], '.')
+        path = remove_dot ? (path[2..-1] || '') : path
+      end
+
+      path
     end
 
     # Holds source paths in instance so they can be manipulated.

data/lib/thor/actions/create_link.rb

@@ -41,7 +41,7 @@ class Thor
         invoke_with_conflict_check do
           FileUtils.mkdir_p(File.dirname(destination))
           # Create a symlink by default
-          config[:symbolic] ||= true
+          config[:symbolic] = true if config[:symbolic].nil?
           File.unlink(destination) if exists?
           if config[:symbolic]
             File.symlink(render, destination)

data/lib/thor/actions/directory.rb

@@ -2,13 +2,13 @@ require 'thor/actions/empty_directory'
 
 class Thor
   module Actions
-
     # Copies recursively the files from source directory to root directory.
     # If any of the files finishes with .tt, it's considered to be a template
     # and is placed in the destination without the extension .tt. If any
     # empty directory is found, it's copied and all .empty_directory files are
-    # ignored. Remember that file paths can also be encoded, let's suppose a doc
-    # directory with the following files:
+    # ignored. If any file name is wrapped within % signs, the text within
+    # the % signs will be executed as a method and replaced with the returned
+    # value. Let's suppose a doc directory with the following files:
     #
     #   doc/
     #     components/.empty_directory
@@ -29,6 +29,10 @@ class Thor
     #     rdoc.rb
     #     blog.rb
     #
+    # <b>Encoded path note:</b> Since Thor internals use Object#respond_to? to check if it can
+    # expand %something%, this `something` should be a public method in the class calling
+    # #directory. If a method is private, Thor stack raises PrivateMethodEncodedError.
+    #
     # ==== Parameters
     # source<String>:: the relative path to the source root.
     # destination<String>:: the relative path to the destination root.

data/lib/thor/actions/empty_directory.rb

@@ -90,16 +90,35 @@ class Thor
 
         # Filenames in the encoded form are converted. If you have a file:
         #
-        #   %class_name%.rb
+        #   %file_name%.rb
         #
-        # It gets the class name from the base and replace it:
+        # It calls #file_name from the base and replaces %-string with the
+        # return value (should be String) of #file_name:
         #
         #   user.rb
         #
+        # The method referenced by %-string SHOULD be public. Otherwise you
+        # get the exception with the corresponding error message.
+        #
         def convert_encoded_instructions(filename)
-          filename.gsub(/%(.*?)%/) do |string|
-            instruction = $1.strip
-            base.respond_to?(instruction) ? base.send(instruction) : string
+          filename.gsub(/%(.*?)%/) do |initial_string|
+            call_public_method($1.strip) or initial_string
+          end
+        end
+
+        # Calls `base`'s public method `sym`.
+        # Returns:: result of `base.sym` or `nil` if `sym` wasn't found in
+        #  `base`
+        # Raises::  Thor::PrivateMethodEncodedError if `sym` references
+        #  a private method.
+        def call_public_method(sym)
+          if base.respond_to?(sym)
+            base.send(sym)
+          elsif base.respond_to?(sym, true)
+            raise Thor::PrivateMethodEncodedError,
+              "Method #{base.class}##{sym} should be public, not private"
+          else
+            nil
           end
         end
 

data/lib/thor/actions/file_manipulation.rb

@@ -102,7 +102,7 @@ class Thor
     #
     def template(source, *args, &block)
       config = args.last.is_a?(Hash) ? args.pop : {}
-      destination = args.first || source
+      destination = args.first || source.sub(/\.tt$/, '')
 
       source  = File.expand_path(find_in_source_paths(source.to_s))
       context = instance_eval('binding')
@@ -187,7 +187,7 @@ class Thor
     #
     # ==== Examples
     #
-    #   inject_into_class "app/controllers/application_controller.rb", "  filter_parameter :password\n"
+    #   inject_into_class "app/controllers/application_controller.rb", ApplicationController, "  filter_parameter :password\n"
     #
     #   inject_into_class "app/controllers/application_controller.rb", ApplicationController do
     #     "  filter_parameter :password\n"
@@ -229,6 +229,44 @@ class Thor
       end
     end
 
+    # Uncomment all lines matching a given regex.  It will leave the space
+    # which existed before the comment hash in tact but will remove any spacing
+    # between the comment hash and the beginning of the line.
+    #
+    # ==== Parameters
+    # path<String>:: path of the file to be changed
+    # flag<Regexp|String>:: the regexp or string used to decide which lines to uncomment
+    # config<Hash>:: give :verbose => false to not log the status.
+    #
+    # ==== Example
+    #
+    #   uncomment_lines 'config/initializers/session_store.rb', /active_record/
+    #
+    def uncomment_lines(path, flag, *args)
+      flag = flag.respond_to?(:source) ? flag.source : flag
+
+      gsub_file(path, /^(\s*)#\s*(.*#{flag})/, '\1\2', *args)
+    end
+
+    # Comment all lines matching a given regex.  It will leave the space
+    # which existed before the beginning of the line in tact and will insert
+    # a single space after the comment hash.
+    #
+    # ==== Parameters
+    # path<String>:: path of the file to be changed
+    # flag<Regexp|String>:: the regexp or string used to decide which lines to comment
+    # config<Hash>:: give :verbose => false to not log the status.
+    #
+    # ==== Example
+    #
+    #   comment_lines 'config/initializers/session_store.rb', /cookie_store/
+    #
+    def comment_lines(path, flag, *args)
+      flag = flag.respond_to?(:source) ? flag.source : flag
+
+      gsub_file(path, /^(\s*)([^#|\n]*#{flag})/, '\1# \2', *args)
+    end
+
     # Removes a file at the given location.
     #
     # ==== Parameters

data/lib/thor/base.rb

@@ -19,7 +19,7 @@ class Thor
                            action add_file create_file in_root inside run run_ruby_script)
 
   module Base
-    attr_accessor :options
+    attr_accessor :options, :parent_options, :args
 
     # It receives arguments in an Array and two hashes, one for options and
     # other for configuration.
@@ -38,22 +38,43 @@ class Thor
     # config<Hash>:: Configuration for this Thor class.
     #
     def initialize(args=[], options={}, config={})
-      args = Thor::Arguments.parse(self.class.arguments, args)
-      args.each { |key, value| send("#{key}=", value) }
-
       parse_options = self.class.class_options
 
+      # The start method splits inbound arguments at the first argument
+      # that looks like an option (starts with - or --). It then calls
+      # new, passing in the two halves of the arguments Array as the
+      # first two parameters.
+
       if options.is_a?(Array)
         task_options  = config.delete(:task_options) # hook for start
         parse_options = parse_options.merge(task_options) if task_options
         array_options, hash_options = options, {}
       else
+        # Handle the case where the class was explicitly instantiated
+        # with pre-parsed options.
         array_options, hash_options = [], options
       end
 
+      # Let Thor::Options parse the options first, so it can remove
+      # declared options from the array. This will leave us with
+      # a list of arguments that weren't declared.
       opts = Thor::Options.new(parse_options, hash_options)
       self.options = opts.parse(array_options)
+
+      # If unknown options are disallowed, make sure that none of the
+      # remaining arguments looks like an option.
       opts.check_unknown! if self.class.check_unknown_options?(config)
+
+      # Add the remaining arguments from the options parser to the
+      # arguments passed in to initialize. Then remove any positional
+      # arguments declared using #argument (this is primarily used
+      # by Thor::Group). Tis will leave us with the remaining
+      # positional arguments.
+      thor_args = Thor::Arguments.new(self.class.arguments)
+      thor_args.parse(args + opts.remaining).each { |k,v| send("#{k}=", v) }
+      args = thor_args.remaining
+
+      @args = args
     end
 
     class << self
@@ -94,8 +115,6 @@ class Thor
     end
 
     module ClassMethods
-      attr_accessor :debugging
-
       def attr_reader(*) #:nodoc:
         no_tasks { super }
       end
@@ -212,13 +231,14 @@ class Thor
       # options<Hash>:: Described below.
       #
       # ==== Options
-      # :desc     - Description for the argument.
-      # :required - If the argument is required or not.
-      # :default  - Default value for this argument.
-      # :group    - The group for this options. Use by class options to output options in different levels.
-      # :aliases  - Aliases for this option.
-      # :type     - The type of the argument, can be :string, :hash, :array, :numeric or :boolean.
-      # :banner   - String to show on usage notes.
+      # :desc::     -- Description for the argument.
+      # :required:: -- If the argument is required or not.
+      # :default::  -- Default value for this argument.
+      # :group::    -- The group for this options. Use by class options to output options in different levels.
+      # :aliases::  -- Aliases for this option. <b>Note:</b> Thor follows a convention of one-dash-one-letter options. Thus aliases like "-something" wouldn't be parsed; use either "\--something" or "-s" instead.
+      # :type::     -- The type of the argument, can be :string, :hash, :array, :numeric or :boolean.
+      # :banner::   -- String to show on usage notes.
+      # :hide::     -- If you want to hide this option from the help.
       #
       def class_option(name, options={})
         build_option(name, options, class_options)
@@ -227,7 +247,7 @@ class Thor
       # Removes a previous defined argument. If :undefine is given, undefine
       # accessors as well.
       #
-      # ==== Paremeters
+      # ==== Parameters
       # names<Array>:: Arguments to be removed
       #
       # ==== Examples
@@ -246,7 +266,7 @@ class Thor
 
       # Removes a previous defined class option.
       #
-      # ==== Paremeters
+      # ==== Parameters
       # names<Array>:: Class options to be removed
       #
       # ==== Examples
@@ -384,17 +404,22 @@ class Thor
       #   script.invoke(:task, first_arg, second_arg, third_arg)
       #
       def start(given_args=ARGV, config={})
-        self.debugging = given_args.delete("--debug")
         config[:shell] ||= Thor::Base.shell.new
         dispatch(nil, given_args.dup, nil, config)
       rescue Thor::Error => e
-        debugging ? (raise e) : config[:shell].error(e.message)
+        ENV["THOR_DEBUG"] == "1" ? (raise e) : config[:shell].error(e.message)
         exit(1) if exit_on_failure?
+      rescue Errno::EPIPE
+        # This happens if a thor task is piped to something like `head`,
+        # which closes the pipe when it's done reading. This will also
+        # mean that if the pipe is closed, further unnecessary
+        # computation will not occur.
+        exit(0)
       end
 
       # Allows to use private methods from parent in child classes as tasks.
       #
-      # ==== Paremeters
+      # ==== Parameters
       #   names<Array>:: Method names to be used as tasks
       #
       # ==== Examples
@@ -408,16 +433,26 @@ class Thor
         end
       end
 
-      def handle_no_task_error(task) #:nodoc:
-        if $thor_runner
+      def handle_no_task_error(task, has_namespace = $thor_runner) #:nodoc:
+        if has_namespace
           raise UndefinedTaskError, "Could not find task #{task.inspect} in #{namespace.inspect} namespace."
         else
           raise UndefinedTaskError, "Could not find task #{task.inspect}."
         end
       end
 
-      def handle_argument_error(task, error) #:nodoc:
-        raise InvocationError, "#{task.name.inspect} was called incorrectly. Call as #{self.banner(task).inspect}."
+      def handle_argument_error(task, error, arity=nil) #:nodoc:
+        msg = "#{basename} #{task.name}"
+        if arity
+          required = arity < 0 ? (-1 - arity) : arity
+          msg << " requires at least #{required} argument"
+          msg << "s" if required > 1
+        else
+          msg = "call #{msg} as"
+        end
+
+        msg << ": #{self.banner(task).inspect}."
+        raise InvocationError, msg
       end
 
       protected
@@ -450,15 +485,17 @@ class Thor
           padding = options.collect{ |o| o.aliases.size }.max.to_i * 4
 
           options.each do |option|
-            item = [ option.usage(padding) ]
-            item.push(option.description ? "# #{option.description}" : "")
+            unless option.hide
+              item = [ option.usage(padding) ]
+              item.push(option.description ? "# #{option.description}" : "")
 
-            list << item
-            list << [ "", "# Default: #{option.default}" ] if option.show_default?
+              list << item
+              list << [ "", "# Default: #{option.default}" ] if option.show_default?
+            end
           end
 
           shell.say(group_name ? "#{group_name} options:" : "Options:")
-          shell.print_table(list, :ident => 2)
+          shell.print_table(list, :indent => 2)
           shell.say ""
         end
 
@@ -476,7 +513,7 @@ class Thor
         def build_option(name, options, scope) #:nodoc:
           scope[name] = Thor::Option.new(name, options[:desc], options[:required],
                                                options[:type], options[:default], options[:banner],
-                                               options[:lazy_default], options[:group], options[:aliases])
+                                               options[:lazy_default], options[:group], options[:aliases], options[:hide])
         end
 
         # Receives a hash of options, parse them and add to the scope. This is a
@@ -509,6 +546,7 @@ class Thor
         # and file into baseclass.
         def inherited(klass)
           Thor::Base.register_klass_file(klass)
+          klass.instance_variable_set(:@no_tasks, false)
         end
 
         # Fire this callback whenever a method is added. Added methods are