thor 0.12.2 → 0.13.0

data/CHANGELOG.rdoc

@@ -1,9 +1,9 @@
-== TODO
-
-* Improve spec coverage for Thor::Runner
-
-== 0.12, released 2009-11-06
+== 0.12, released 2010-01-02
 
+* Methods generated by attr_* are automatically not marked as tasks
+* inject_into_file does not add the same content twice, unless :force is set
+* Removed rr in favor to rspec mock framework
+* Improved output for thor -T
 * [#7] Do not force white color on status
 * [#8] Yield a block with the filename on directory
 

data/README.rdoc

@@ -145,7 +145,7 @@ When invoking the task one:
 
 The output is "1 2 3", which means that the three task was invoked only once.
 You can even invoke tasks from another class, so be sure to check the
-documentation.
+documentation[http://rdoc.info/rdoc/wycats/thor/blob/f939a3e8a854616784cac1dcff04ef4f3ee5f7ff/Thor.html].
 
 == Thor::Group
 
@@ -227,7 +227,70 @@ To use them, you just need to include Thor::Actions in your Thor classes:
 
 Some actions like copy file requires that a class method called source_root is
 defined in your class. This is the directory where your templates should be
-placed. Be sure to check the documentation.
+placed. Be sure to check the documentation on actions[http://rdoc.info/rdoc/wycats/thor/blob/f939a3e8a854616784cac1dcff04ef4f3ee5f7ff/Thor/Actions.html].
+
+== Generators
+
+A great use for Thor is creating custom generators. Combining Thor::Group,
+Thor::Actions and ERB templates makes this very easy. Here is an example:
+
+    class Newgem < Thor::Group
+      include Thor::Actions
+
+      # Define arguments and options
+      argument :name
+      class_option :test_framework, :default => :test_unit
+
+      def self.source_root
+        File.dirname(__FILE__)
+      end
+
+      def create_lib_file
+        template('templates/newgem.tt', "#{name}/lib/#{name}.rb")
+      end
+
+      def create_test_file
+        test = options[:test_framework] == "rspec" ? :spec : :test
+        create_file "#{name}/#{test}/#{name}_#{test}.rb"
+      end
+
+      def copy_licence
+        if yes?("Use MIT license?")
+          # Make a copy of the MITLICENSE file at the source root
+          copy_file "MITLICENSE", "#{name}/MITLICENSE"
+        else
+          say "Shame on you…", :red
+        end
+      end
+    end
+
+Doing a <tt>thor -T</tt> will show how to run our generator. It should read:
+<tt>thor newgem NAME</tt>. This shows that we have to supply a NAME
+argument for our generator to run.
+
+The <tt>create_lib_file</tt> uses an ERB template. This is what it looks like:
+
+    class <%= name.camelize %>
+    end
+
+The arguments that you set in your generator will automatically be passed in
+when <tt>template</tt> gets called. Be sure to read the documentation[http://rdoc.info/rdoc/wycats/thor/blob/f939a3e8a854616784cac1dcff04ef4f3ee5f7ff/Thor/Actions.html] for
+more options.
+
+Running the generator with <tt>thor newgem devise</tt> will
+create two files: "devise/lib/devise.rb",
+"devise/test/devise_test.rb". The user will then be prompt (with the
+use of the method <tt>yes?</tt>) if he wants to copy the MITLICENSE. If you
+want to change the test framework, you can add the option:
+<tt>thor newgem devise --test-framework=rspec</tt>
+This will generate: "devise/lib/devise.rb" and
+"devise/spec/devise_spec.rb".
+
+== Further Reading
+
+Thor has many scripting possibilities beyond these examples. Be sure to read
+through the documentation[http://rdoc.info/rdoc/wycats/thor/blob/f939a3e8a854616784cac1dcff04ef4f3ee5f7ff/Thor.html] and specs[http://github.com/wycats/thor/tree/master/spec/] to get a better understanding of all the
+options Thor offers.
 
 == License
 

data/Thorfile

@@ -4,7 +4,10 @@ require File.join(File.dirname(__FILE__), "lib", "thor", "version")
 require 'rubygems'
 require 'thor/rake_compat'
 require 'spec/rake/spectask'
-require 'rdoc/task'
+begin
+  require 'rdoc/task'
+rescue LoadError
+end
 
 GEM_NAME = 'thor'
 EXTRA_RDOC_FILES = ["README.rdoc", "LICENSE", "CHANGELOG.rdoc", "VERSION", "Thorfile"]
@@ -26,13 +29,15 @@ class Default < Thor
     t.rcov_dir = "rcov"
   end
 
-  RDoc::Task.new do |rdoc|
-    rdoc.main     = "README.rdoc"
-    rdoc.rdoc_dir = "rdoc"
-    rdoc.title    = GEM_NAME
-    rdoc.rdoc_files.include(*EXTRA_RDOC_FILES)
-    rdoc.rdoc_files.include('lib/**/*.rb')
-    rdoc.options << '--line-numbers' << '--inline-source'
+  if defined?(RDoc)
+    RDoc::Task.new do |rdoc|
+      rdoc.main     = "README.rdoc"
+      rdoc.rdoc_dir = "rdoc"
+      rdoc.title    = GEM_NAME
+      rdoc.rdoc_files.include(*EXTRA_RDOC_FILES)
+      rdoc.rdoc_files.include('lib/**/*.rb')
+      rdoc.options << '--line-numbers' << '--inline-source'
+    end
   end
 
   begin

data/bin/thor

@@ -4,4 +4,5 @@
 require 'thor'
 require 'thor/runner'
 
+$thor_runner = true
 Thor::Runner.start

data/lib/thor/actions/create_file.rb

@@ -42,7 +42,7 @@ class Thor
       # Boolean:: true if it is identical, false otherwise.
       #
       def identical?
-        exists? && File.read(destination) == render
+        exists? && File.binread(destination) == render
       end
 
       # Holds the content to be added to the file.
@@ -58,7 +58,7 @@ class Thor
       def invoke!
         invoke_with_conflict_check do
           FileUtils.mkdir_p(File.dirname(destination))
-          File.open(destination, 'w'){ |f| f.write render }
+          File.open(destination, 'wb') { |f| f.write render }
         end
         given_destination
       end

data/lib/thor/actions/file_manipulation.rb

@@ -23,7 +23,7 @@ class Thor
       source = File.expand_path(find_in_source_paths(source.to_s))
 
       create_file destination, nil, config do
-        content = File.read(source)
+        content = File.binread(source)
         content = block.call(content) if block
         content
       end
@@ -48,7 +48,7 @@ class Thor
     #
     def get(source, destination=nil, config={}, &block)
       source = File.expand_path(find_in_source_paths(source.to_s)) unless source =~ /^http\:\/\//
-      render = open(source).read
+      render = File.binread(source)
 
       destination ||= if block_given?
         block.arity == 1 ? block.call(render) : block.call
@@ -80,7 +80,7 @@ class Thor
       context = instance_eval('binding')
 
       create_file destination, nil, config do
-        content = ERB.new(::File.read(source), nil, '-').result(context)
+        content = ERB.new(::File.binread(source), nil, '-').result(context)
         content = block.call(content) if block
         content
       end
@@ -193,7 +193,7 @@ class Thor
       say_status :gsub, relative_to_original_destination_root(path), config.fetch(:verbose, true)
 
       unless options[:pretend]
-        content = File.read(path)
+        content = File.binread(path)
         content.gsub!(flag, *args, &block)
         File.open(path, 'wb') { |file| file.write(content) }
       end

data/lib/thor/actions/inject_into_file.rb

@@ -10,7 +10,8 @@ class Thor
     # destination<String>:: Relative path to the destination root
     # data<String>:: Data to add to the file. Can be given as a block.
     # config<Hash>:: give :verbose => false to not log the status and the flag
-    #                for injection (:after or :before).
+    #                for injection (:after or :before) or :force => true for 
+    #                insert two or more times the same content.
     # 
     # ==== Examples
     #
@@ -55,7 +56,7 @@ class Thor
           replacement + '\0'
         end
 
-        replace!(/#{flag}/, content)
+        replace!(/#{flag}/, content, config[:force])
       end
 
       def revoke!
@@ -69,7 +70,7 @@ class Thor
           /(#{Regexp.escape(replacement)})(.*)(#{flag})/m
         end
 
-        replace!(regexp, content)
+        replace!(regexp, content, true)
       end
 
       protected
@@ -88,11 +89,13 @@ class Thor
 
         # Adds the content to the file.
         #
-        def replace!(regexp, string)
+        def replace!(regexp, string, force)
           unless base.options[:pretend]
-            content = File.read(destination)
-            content.gsub!(regexp, string)
-            File.open(destination, 'wb') { |file| file.write(content) }
+            content = File.binread(destination)
+            if force || !content.include?(replacement)
+              content.gsub!(regexp, string)
+              File.open(destination, 'wb') { |file| file.write(content) }
+            end
           end
         end
 

data/lib/thor/actions.rb

@@ -1,4 +1,5 @@
 require 'fileutils'
+require 'thor/core_ext/file_binary_read'
 
 Dir[File.join(File.dirname(__FILE__), "actions", "*.rb")].each do |action|
   require action

data/lib/thor/base.rb

@@ -8,6 +8,9 @@ require 'thor/task'
 require 'thor/util'
 
 class Thor
+  autoload :Actions,    'thor/actions'
+  autoload :RakeCompat, 'thor/rake_compat'
+
   # Shortcuts for help.
   HELP_MAPPINGS       = %w(-h -? --help -D)
 
@@ -94,6 +97,18 @@ class Thor
     module ClassMethods
       attr_accessor :debugging
 
+      def attr_reader(*) #:nodoc:
+        no_tasks { super }
+      end
+
+      def attr_writer(*) #:nodoc:
+        no_tasks { super }
+      end
+
+      def attr_accessor(*) #:nodoc:
+        no_tasks { super }
+      end
+
       # Adds an argument to the class and creates an attr_accessor for it.
       #
       # Arguments are different from options in several aspects. The first one

data/lib/thor/core_ext/file_binary_read.rb

@@ -0,0 +1,9 @@
+class File #:nodoc:
+
+  unless File.respond_to?(:binread)
+    def self.binread(file)
+      File.open(file, 'rb') { |f| f.read }
+    end
+  end
+
+end

data/lib/thor/group.rb

@@ -1,8 +1,9 @@
+require 'thor/base'
+
 # Thor has a special class called Thor::Group. The main difference to Thor class
 # is that it invokes all tasks at once. It also include some methods that allows
 # invocations to be done at the class method, which are not available to Thor
 # tasks.
-#
 class Thor::Group
   class << self
     # The descrition for this Thor::Group. If none is provided, but a source root
@@ -41,16 +42,12 @@ class Thor::Group
     # ==== Options
     # short:: When true, shows only usage.
     #
-    def help(shell, options={})
-      if options[:short]
-        shell.say banner
-      else
-        shell.say "Usage:"
-        shell.say "  #{banner}\n"
-        shell.say ""
-        class_options_help(shell)
-        shell.say self.desc if self.desc
-      end
+    def help(shell)
+      shell.say "Usage:"
+      shell.say "  #{banner}\n"
+      shell.say
+      class_options_help(shell)
+      shell.say self.desc if self.desc
     end
 
     # Stores invocations for this class merging with superclass values.
@@ -214,13 +211,27 @@ class Thor::Group
       end
     end
 
+    # Returns tasks ready to be printed.
+    def printable_tasks(*)
+      item = []
+      item << banner
+      item << (desc ? "# #{desc.gsub(/\s+/m,' ')}" : "")
+      [item]
+    end
+
     protected
 
       # 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.
       #
       def banner
-        "thor #{self.namespace} #{self.arguments.map {|a| a.usage }.join(' ')}"
+        base = $thor_runner ? "thor" : File.basename($0.split(" ").first)
+        "#{base} #{self_task.formatted_usage(self, false)}"
+      end
+
+      # Represents the whole class as a task.
+      def self_task #:nodoc:
+        Thor::Task::Dynamic.new(self.namespace, class_options)
       end
 
       def baseclass #:nodoc:
@@ -237,23 +248,25 @@ class Thor::Group
 
   protected
 
-    # Shortcut to invoke with padding and block handling. Use internally by
-    # invoke and invoke_from_option class methods.
-    #
-    def _invoke_for_class_method(klass, task=nil, *args, &block) #:nodoc:
-      shell.padding += 1
+  # Shortcut to invoke with padding and block handling. Use internally by
+  # invoke and invoke_from_option class methods.
+  def _invoke_for_class_method(klass, task=nil, *args, &block) #:nodoc:
+    shell.padding += 1
 
-      result = if block_given?
-        if block.arity == 2
-          block.call(self, klass)
-        else
-          block.call(self, klass, task)
-        end
-      else
-        invoke klass, task, *args
+    result = if block_given?
+      case block.arity
+      when 3
+        block.call(self, klass, task)
+      when 2
+        block.call(self, klass)
+      when 1
+        instance_exec(klass, &block)
       end
-
-      shell.padding -= 1
-      result
+    else
+      invoke klass, task, *args
     end
+
+    shell.padding -= 1
+    result
+  end
 end

data/lib/thor/runner.rb

@@ -1,4 +1,5 @@
 require 'fileutils'
+require 'thor/core_ext/file_binary_read'
 require 'open-uri'
 require 'yaml'
 require 'digest/md5'
@@ -32,7 +33,7 @@ class Thor::Runner < Thor #:nodoc:
   end
 
   desc "install NAME", "Install an optionally named Thor file into your system tasks"
-  method_options :as => :string, :relative => :boolean
+  method_options :as => :string, :relative => :boolean, :force => :boolean
   def install(name)
     initialize_thorfiles
 
@@ -55,7 +56,9 @@ class Thor::Runner < Thor #:nodoc:
     say "Your Thorfile contains:"
     say contents
 
-    return false if no?("Do you wish to continue [y/N]?")
+    unless options["force"]
+      return false if no?("Do you wish to continue [y/N]?")
+    end
 
     as = options["as"] || begin
       first_line = contents.split("\n")[0]
@@ -124,11 +127,7 @@ class Thor::Runner < Thor #:nodoc:
   method_options :internal => :boolean
   def installed
     initialize_thorfiles(nil, true)
-
-    klasses = Thor::Base.subclasses
-    klasses -= [Thor, Thor::Runner] unless options["internal"]
-
-    display_klasses(true, klasses)
+    display_klasses(true, options["internal"])
   end
 
   desc "list [SEARCH]", "List the available thor tasks (--substring means .*SEARCH)"
@@ -144,7 +143,7 @@ class Thor::Runner < Thor #:nodoc:
       (options[:all] || k.group == group) && k.namespace =~ search
     end
 
-    display_klasses(false, klasses)
+    display_klasses(false, false, klasses)
   end
 
   private
@@ -160,7 +159,7 @@ class Thor::Runner < Thor #:nodoc:
     def thor_yaml
       @thor_yaml ||= begin
         yaml_file = File.join(thor_root, "thor.yml")
-        yaml      = YAML.load_file(yaml_file) if File.exists?(yaml_file)
+        yaml = YAML.load_file(yaml_file) if File.exists?(yaml_file)
         yaml || {}
       end
     end
@@ -219,9 +218,6 @@ class Thor::Runner < Thor #:nodoc:
     # 5. c:\ <-- no Thorfiles found!
     #
     def thorfiles(relevant_to=nil, skip_lookup=false)
-      # TODO Remove this dealing with deprecated thor when :namespaces: is available as constants
-      save_yaml(thor_yaml) if Thor::Util.convert_constants_to_namespaces(thor_yaml)
-
       thorfiles = []
 
       unless skip_lookup
@@ -257,47 +253,54 @@ class Thor::Runner < Thor #:nodoc:
     # Display information about the given klasses. If with_module is given,
     # it shows a table with information extracted from the yaml file.
     #
-    def display_klasses(with_modules=false, klasses=Thor.subclasses)
-      klasses -= [Thor, Thor::Runner] unless with_modules
+    def display_klasses(with_modules=false, show_internal=false, klasses=Thor::Base.subclasses)
+      klasses -= [Thor, Thor::Runner, Thor::Group] unless show_internal
+
       raise Error, "No Thor tasks available" if klasses.empty?
+      show_modules if with_modules && !thor_yaml.empty?
 
-      if with_modules && !thor_yaml.empty?
-        info  = []
-        labels = ["Modules", "Namespaces"]
+      # Remove subclasses
+      klasses.dup.each do |klass|
+        klasses -= Thor::Util.thor_classes_in(klass)
+      end
 
-        info << labels
-        info << [ "-" * labels[0].size, "-" * labels[1].size ]
+      list = Hash.new { |h,k| h[k] = [] }
+      groups = klasses.select { |k| k.ancestors.include?(Thor::Group) }
 
-        thor_yaml.each do |name, hash|
-          info << [ name, hash[:namespaces].join(", ") ]
-        end
+      # Get classes which inherit from Thor
+      (klasses - groups).each { |k| list[k.namespace] += k.printable_tasks(false) }
 
-        print_table info
-        say ""
-      end
+      # Get classes which inherit from Thor::Base
+      groups.map! { |k| k.printable_tasks(false).first }
+      list["root"] = groups
 
-      unless klasses.empty?
-        klasses.dup.each do |klass|
-          klasses -= Thor::Util.thor_classes_in(klass)
-        end
+      # Order namespaces with default coming first
+      list = list.sort{ |a,b| a[0].sub(/^default/, '') <=> b[0].sub(/^default/, '') }
+      list.each { |n, tasks| display_tasks(n, tasks) unless tasks.empty? }
+    end
 
-        klasses.each { |k| display_tasks(k) }
-      else
-        say "\033[1;34mNo Thor tasks available\033[0m"
-      end
+    def display_tasks(namespace, list) #:nodoc:
+      list.sort!{ |a,b| a[0] <=> b[0] }
+
+      say shell.set_color(namespace, :blue, true)
+      say "-" * namespace.size
+
+      print_table(list, :truncate => true)
+      say
     end
 
-    # Display tasks from the given Thor class.
-    #
-    def display_tasks(klass)
-      unless klass.tasks.empty?
-        base = klass.namespace
+    def show_modules #:nodoc:
+      info  = []
+      labels = ["Modules", "Namespaces"]
 
-        say shell.set_color(base, :blue, true)
-        say "-" * base.length
+      info << labels
+      info << [ "-" * labels[0].size, "-" * labels[1].size ]
 
-        klass.help(shell, :short => true)
-        say
+      thor_yaml.each do |name, hash|
+        info << [ name, hash[:namespaces].join(", ") ]
       end
+
+      print_table info
+      say ""
     end
 end

data/lib/thor/shell/color.rb

@@ -63,7 +63,7 @@ class Thor
         #
         def show_diff(destination, content) #:nodoc:
           if diff_lcs_loaded? && ENV['THOR_DIFF'].nil? && ENV['RAILS_DIFF'].nil?
-            actual  = File.read(destination).to_s.split("\n")
+            actual  = File.binread(destination).to_s.split("\n")
             content = content.to_s.split("\n")
 
             Diff::LCS.sdiff(actual, content).each do |diff|

data/lib/thor/task.rb

@@ -1,11 +1,11 @@
 class Thor
   class Task < Struct.new(:name, :description, :usage, :options)
+    FILE_REGEXP = /^#{Regexp.escape(File.dirname(__FILE__))}/
 
     # A dynamic task that handles method missing scenarios.
-    #
     class Dynamic < Task
-      def initialize(name)
-        super(name.to_s, "A dynamically-generated task", name.to_s)
+      def initialize(name, options=nil)
+        super(name.to_s, "A dynamically-generated task", name.to_s, options)
       end
 
       def run(instance, args=[])
@@ -27,7 +27,6 @@ class Thor
 
     # By default, a task invokes a method in the thor class. You can change this
     # implementation to create custom tasks.
-    #
     def run(instance, args=[])
       raise UndefinedTaskError, "the '#{name}' task of #{instance.class} is private" unless public_method?(instance)
       instance.send(name, *args)
@@ -41,8 +40,8 @@ class Thor
 
     # Returns the formatted usage by injecting given required arguments 
     # and required options into the given usage.
-    def formatted_usage(klass, namespace=nil)
-      namespace = klass.namespace if namespace.nil?
+    def formatted_usage(klass, namespace=true)
+      namespace = klass.namespace unless namespace == false
 
       # Add namespace
       formatted = if namespace
@@ -54,7 +53,7 @@ class Thor
       # Add usage with required arguments
       formatted << if klass && !klass.arguments.empty?
         usage.to_s.gsub(/^#{name}/) do |match|
-          match << " " << required_arguments(klass)
+          match << " " << klass.arguments.map{ |a| a.usage }.compact.join(' ')
         end
       else
         usage.to_s
@@ -69,25 +68,25 @@ class Thor
 
     protected
 
-      def required_arguments(klass)
-        klass.arguments.map{ |a| a.usage if a.required? }.compact.join(' ')
-      end
-
       def required_options
         @required_options ||= options.map{ |_, o| o.usage if o.required? }.compact.sort.join(" ")
       end
 
       # Given a target, checks if this class name is not a private/protected method.
-      #
       def public_method?(instance) #:nodoc:
         collection = instance.private_methods + instance.protected_methods
         (collection & [name.to_s, name.to_sym]).empty?
       end
 
+      def sans_backtrace(backtrace, caller) #:nodoc:
+        saned  = backtrace.reject { |frame| frame =~ FILE_REGEXP }
+        saned -= caller
+      end
+
       def parse_argument_error(instance, e, caller) #:nodoc:
-        method_name = /`#{Regexp.escape(name.split(':').last)}'/
+        backtrace = sans_backtrace(e.backtrace, caller)
 
-        if e.message =~ /wrong number of arguments/ && e.backtrace.first.to_s =~ method_name
+        if backtrace.empty? && e.message =~ /wrong number of arguments/
           if instance.is_a?(Thor::Group)
             raise e, "'#{name}' was called incorrectly. Are you sure it has arity equals to 0?"
           else

data/lib/thor/util.rb

@@ -76,8 +76,10 @@ class Thor
     # Returns the thor classes declared inside the given class.
     #
     def self.thor_classes_in(klass)
+      stringfied_constants = klass.constants.map { |c| c.to_s }
       Thor::Base.subclasses.select do |subclass|
-        klass.constants.include?(subclass.name.gsub("#{klass.name}::", ''))
+        next unless subclass.name
+        stringfied_constants.include?(subclass.name.gsub("#{klass.name}::", ''))
       end
     end
 
@@ -155,7 +157,7 @@ class Thor
     # inside the sandbox to avoid namespacing conflicts.
     #
     def self.load_thorfile(path, content=nil)
-      content ||= File.read(path)
+      content ||= File.binread(path)
 
       begin
         Thor::Sandbox.class_eval(content, path)
@@ -164,26 +166,6 @@ class Thor
       end
     end
 
-    # Receives a yaml (hash) and updates all constants entries to namespace.
-    # This was added to deal with deprecated versions of Thor.
-    #
-    # TODO Deprecate this method in the future.
-    #
-    # ==== Returns
-    # TrueClass|FalseClass:: Returns true if any change to the yaml file was made.
-    #
-    def self.convert_constants_to_namespaces(yaml)
-      yaml_changed = false
-
-      yaml.each do |k, v|
-        next unless v[:constants] && v[:namespaces].nil?
-        yaml_changed = true
-        yaml[k][:namespaces] = v[:constants].map{|c| Thor::Util.namespace_from_thor_class(c)}
-      end
-
-      yaml_changed
-    end
-
     def self.user_home
       @@user_home ||= if ENV["HOME"]
         ENV["HOME"]