thor 0.12.0 → 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

@@ -1,9 +1,13 @@
 # enconding: utf-8
 
 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"]
@@ -25,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
@@ -52,7 +58,7 @@ class Default < Thor
       s.bindir = "bin"
       s.executables = %w( thor rake2thor )
       s.files = s.extra_rdoc_files + Dir.glob("{bin,lib}/**/*")
-      s.files.exclude 'spec/sandbox/**/*'
+      s.test_files.include 'spec/**/*'
       s.test_files.exclude 'spec/sandbox/**/*'
     end
 

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/directory.rb

@@ -79,11 +79,9 @@ class Thor
                 next if dirname == given_destination
                 base.empty_directory(dirname, config)
               when /\.tt$/
-                destination = base.template(file_source, file_destination[0..-4], config)
-                @block.call(destination) if @block
+                destination = base.template(file_source, file_destination[0..-4], config, &@block)
               else
-                destination = base.copy_file(file_source, file_destination, config)
-                @block.call(destination) if @block
+                destination = base.copy_file(file_source, file_destination, config, &@block)
             end
           end
         end

data/lib/thor/actions/file_manipulation.rb

@@ -18,12 +18,14 @@ class Thor
     #
     #   copy_file "doc/README"
     #
-    def copy_file(source, destination=nil, config={})
+    def copy_file(source, destination=nil, config={}, &block)
       destination ||= source
       source = File.expand_path(find_in_source_paths(source.to_s))
 
       create_file destination, nil, config do
-        File.read(source)
+        content = File.binread(source)
+        content = block.call(content) if block
+        content
       end
     end
 
@@ -46,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
@@ -72,13 +74,15 @@ class Thor
     #
     #   template "doc/README"
     #
-    def template(source, destination=nil, config={})
+    def template(source, destination=nil, config={}, &block)
       destination ||= source
       source  = File.expand_path(find_in_source_paths(source.to_s))
       context = instance_eval('binding')
 
       create_file destination, nil, config do
-        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
     end
 
@@ -189,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
@@ -38,17 +39,17 @@ class Thor
       # Add runtime options that help actions execution.
       #
       def add_runtime_options!
-        class_option :pretend, :type => :boolean, :aliases => "-p", :group => :runtime,
-                               :desc => "Run but do not make any changes"
-
         class_option :force, :type => :boolean, :aliases => "-f", :group => :runtime,
                              :desc => "Overwrite files that already exist"
 
-        class_option :skip, :type => :boolean, :aliases => "-s", :group => :runtime,
-                            :desc => "Skip files that already exist"
+        class_option :pretend, :type => :boolean, :aliases => "-p", :group => :runtime,
+                               :desc => "Run but do not make any changes"
 
         class_option :quiet, :type => :boolean, :aliases => "-q", :group => :runtime,
                              :desc => "Supress status output"
+
+        class_option :skip, :type => :boolean, :aliases => "-s", :group => :runtime,
+                            :desc => "Skip files that already exist"
       end
     end
 

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)
 
@@ -92,6 +95,20 @@ class Thor
     end
 
     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
@@ -347,10 +364,11 @@ class Thor
       # Default way to start generators from the command line.
       #
       def start(given_args=ARGV, config={})
+        self.debugging = given_args.include?("--debug")
         config[:shell] ||= Thor::Base.shell.new
         yield
       rescue Thor::Error => e
-        if given_args.include?("--debug")
+        if debugging
           raise e
         else
           config[:shell].error e.message
@@ -361,48 +379,43 @@ class Thor
       protected
 
         # Prints the class options per group. If an option does not belong to
-        # any group, it uses the ungrouped name value. This method provide to
-        # hooks to add extra options, one of them if the third argument called
-        # extra_group that should be a hash in the format :group => Array[Options].
-        #
-        # The second is by returning a lambda used to print values. The lambda
-        # requires two options: the group name and the array of options.
+        # any group, it's printed as Class option.
         #
-        def class_options_help(shell, ungrouped_name=nil, extra_group=nil) #:nodoc:
-          groups = {}
-
+        def class_options_help(shell, groups={}) #:nodoc:
+          # Group options by group
           class_options.each do |_, value|
             groups[value.group] ||= []
             groups[value.group] << value
           end
 
-          printer = proc do |group_name, options|
-            list = []
-            padding = options.collect{ |o| o.aliases.size  }.max.to_i * 4
+          # Deal with default group
+          global_options = groups.delete(nil) || []
+          print_options(shell, global_options)
 
-            options.each do |option|
-              item = [ option.usage(padding) ]
-              item.push(option.description ? "# #{option.description}" : "")
+          # Print all others
+          groups.each do |group_name, options|
+            print_options(shell, options, group_name)
+          end
+        end
 
-              list << item
-              list << [ "", "# Default: #{option.default}" ] if option.show_default?
-            end
+        # Receives a set of options and print them.
+        def print_options(shell, options, group_name=nil)
+          return if options.empty?
 
-            unless list.empty?
-              shell.say(group_name ? "#{group_name} options:" : "Options:")
-              shell.print_table(list, :ident => 2)
-              shell.say ""
-            end
-          end
+          list = []
+          padding = options.collect{ |o| o.aliases.size }.max.to_i * 4
 
-          # Deal with default group
-          global_options = groups.delete(nil) || []
-          printer.call(ungrouped_name, global_options) if global_options
+          options.each do |option|
+            item = [ option.usage(padding) ]
+            item.push(option.description ? "# #{option.description}" : "")
 
-          # Print all others
-          groups = extra_group.merge(groups) if extra_group
-          groups.each(&printer)
-          printer
+            list << item
+            list << [ "", "# Default: #{option.default}" ] if option.show_default?
+          end
+
+          shell.say(group_name ? "#{group_name} options:" : "Options:")
+          shell.print_table(list, :ident => 2)
+          shell.say ""
         end
 
         # Raises an error if the word given is a Thor reserved word.

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}"
-        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.
@@ -177,15 +174,11 @@ class Thor::Group
     # Overwrite class options help to allow invoked generators options to be
     # shown recursively when invoking a generator.
     #
-    def class_options_help(shell, ungrouped_name=nil, extra_group=nil) #:nodoc:
-      group_options = {}
-
-      get_options_from_invocations(group_options, class_options) do |klass|
-        klass.send(:get_options_from_invocations, group_options, class_options)
+    def class_options_help(shell, groups={}) #:nodoc:
+      get_options_from_invocations(groups, class_options) do |klass|
+        klass.send(:get_options_from_invocations, groups, class_options)
       end
-
-      group_options.merge!(extra_group) if extra_group
-      super(shell, ungrouped_name, group_options)
+      super(shell, groups)
     end
 
     # Get invocations array and merge options from invocations. Those
@@ -218,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
-        "#{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:
@@ -241,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
-
-      result = if block_given?
-        if block.arity == 2
-          block.call(self, klass)
-        else
-          block.call(self, klass, task)
-        end
-      else
-        invoke klass, task, *args
+  # 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?
+      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