josevalim-thor 0.10.23 → 0.10.25

data/README.markdown

@@ -1,76 +1,247 @@
 thor
 ====
 
-Map options to a class. Simply create a class with the appropriate annotations, and have options automatically map
-to functions and parameters.
+Map options to a class. Simply create a class with the appropriate annotations
+and have options automatically map to functions and parameters.
 
 Example:
 
-    class MyApp < Thor                                                # [1]
-      map "-L" => :list                                               # [2]
-                                                                    
-      desc "install APP_NAME", "install one of the available apps"    # [3]
-      method_options :force => :boolean, :alias => :optional          # [4]
+    class App < Thor                                                 # [1]
+      map "-L" => :list                                              # [2]
+      
+      desc "install APP_NAME", "install one of the available apps"   # [3]
+      method_options :force => :boolean, :alias => :string           # [4]
       def install(name)
         user_alias = options[:alias]
         if options.force?
           # do something
         end
-        # ... other code ...
+        # other code
       end
       
       desc "list [SEARCH]", "list all of the available apps, limited by SEARCH"
-      def list(search = "")
+      def list(search="")
         # list everything
       end
     end
-    
+
 Thor automatically maps commands as such:
 
-    app install myname --force
-    
+    thor app:install myname --force
+
 That gets converted to:
 
-    MyApp.new.install("myname")
+    App.new.install("myname")
     # with {'force' => true} as options hash
 
 1.  Inherit from Thor to turn a class into an option mapper
-2.  Map additional non-valid identifiers to specific methods. In this case,
-    convert -L to :list
-3.  Describe the method immediately below. The first parameter is the usage information,
-    and the second parameter is the description.
-4.  Provide any additional options. These will be marshaled from `--` and `-` params.
-    In this case, a `--force` and a `-f` option is added.
-    
+2.  Map additional non-valid identifiers to specific methods. In this case, convert -L to :list
+3.  Describe the method immediately below. The first parameter is the usage information, and the second parameter is the description
+4.  Provide any additional options that will be available the instance method options.
+
 Types for `method_options`
 --------------------------
 
 <dl>
   <dt><code>:boolean</code></dt>
-    <dd>true if the option is passed</dd>
-  <dt><code>true or false</code></dt>
-    <dd>same as <code>:boolean</code>, but fall back to given boolean as default value</dd>
-  <dt><code>:required</code></dt>
-    <dd>the value for this option MUST be provided</dd>
-  <dt><code>:optional</code></dt>
-    <dd>the value for this option MAY be provided</dd>
+    <dd>is parsed as --option or --option=true</dd>
+  <dt><code>:string</code></dt>
+    <dd>is parsed as --option=VALUE</dd>
   <dt><code>:numeric</code></dt>
-    <dd>the value MAY be provided, but MUST be in numeric form</dd>
-  <dt>a String or Numeric</dt>
-    <dd>same as <code>:optional</code>, but fall back to the given object as default value</dd>
+    <dd>is parsed as --option=N</dd>
+  <dt><code>:array</code></dt>
+    <dd>is parsed as --option=one two three</dd>
+  <dt><code>:hash</code></dt>
+    <dd>is parsed as --option=key:value key:value key:value</dd>
 </dl>
 
-In case of unsatisfied requirements, `Thor::Options::Error` is raised.
+Besides, method_option allows a default value to be given, examples:
+
+    method_options :force => false
+    #=> Creates a boolean option with default value false
+
+    method_options :alias => "bar"
+    #=> Creates a string option with default value "bar"
+
+    method_options :threshold => 3.0
+    #=> Creates a numeric option with default value 3.0
+
+You can also supply :option => :required to mark an option as required. The
+type is assumed to be string. If you want a required hash with default values
+as option, you can use `method_option` which uses a more declarative style:
+
+    method_option :attributes, :type => :hash, :default => {}, :required => true
+
+All arguments can be set to nil (except required arguments), by suppling a no or
+skip variant. For example:
+
+    thor app name --no-attributes
+
+In previous versions, aliases for options were created automatically, but now
+they should be explicit. You can supply aliases in both short and declarative
+styles:
+
+    method_options %w( force -f ) => :boolean
+
+Or:
+
+    method_option :force, :type => :boolean, :aliases => "-f"
+
+You can supply as many aliases as you want.
+
+NOTE: Type :optional available in Thor 0.9.0 was deprecated. Use :string or :boolean instead.
+
+Namespaces
+----------
+
+By default, your Thor tasks are invoked using Ruby namespace. In the example
+above, tasks are invoked as:
+
+    thor app:install name --force
+
+However, you could namespace your class as:
+
+    module Sinatra
+      class App < Thor
+        # tasks
+      end
+    end
+
+And then you should invoke your tasks as:
+
+    thor sinatra:app:install name --force
+
+If desired, you can change the namespace:
+
+    module Sinatra
+      class App < Thor
+        namespace :myapp
+        # tasks
+      end
+    end
+
+And then your tasks hould be invoked as:
+
+    thor myapp:install name --force
+
+Invocations
+-----------
+
+Thor comes with a invocation-dependency system as well which allows a task to be
+invoked only once. For example:
+
+    class Counter < Thor
+      desc "one", "Prints 1, 2, 3"
+      def one
+        puts 1
+        invoke :two
+        invoke :three
+      end
+      
+      desc "two", "Prints 2, 3"
+      def two
+        puts 2
+        invoke :three
+      end
+      
+      desc "three", "Prints 3"
+      def three
+        puts 3
+      end
+    end
+
+When invoking the task one:
+
+    thor counter: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.
+
+Thor::Group
+-----------
+
+Thor has a special class called Thor::Group. The main difference to Thor class
+is that it invokes all tasks at once. The example above could be rewritten in
+Thor::Group as this:
+
+    class Counter < Thor::Group
+      desc "Prints 1, 2, 3"
+      
+      def one
+        puts 1
+      end
+     
+      def two
+        puts 2
+      end
+      
+      def three
+        puts 3
+      end
+    end
+
+When invoked:
+
+    thor counter
+
+It prints "1 2 3" as well. Notice you should described (desc) only the class
+and not each task anymore. Thor::Group is a great tool to create generators,
+since you can define several steps which are invoked in the order they are
+defined (Thor::Group is the tool use in generators in Rails 3.0).
+
+Besides, Thor::Group can parse arguments and options as Thor tasks:
+
+    class Counter < Thor::Group
+      # number will be available as attr_accessor
+      argument :number, :type => :numeric, :desc => "The number to start counting"
+      desc "Prints the 'number' given upto 'number+2'"
+      
+      def one
+        puts number + 0
+      end
+      
+      def two
+        puts number + 1
+      end
+      
+      def three
+        puts number + 2
+      end
+    end
+
+The counter above expects one parameter and has the folling outputs:
+
+    thor counter 5
+    # Prints "5 6 7"
+
+    thor counter 11
+    # Prints "11 12 13"
+
+You can also give options to Thor::Group, but instead of using `method_option` and
+`method_options`, you should use `class_option` and `class_options`. Both argument
+and class_options methods are available to Thor class as well.
+
+Actions
+-------
+
+Thor comes with several actions which helps with script and generator tasks. You
+might be familiar with them since some came from Rails Templates. They are: `say`,
+`ask`, `yes?`, `no?`, `add_file`, `remove_file`, `copy_file`, `template`,
+`directory`, `inside`, `run`, `inject_into_file` and a couple more.
+
+To use them, you just need to include Thor::Actions in your Thor classes:
+
+    class App < Thor
+      include Thor::Actions
+      # tasks
+    end
+
+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.
 
-Examples of option parsing:
+License
+-------
 
-    # let's say this is how we defined options for a method:
-    method_options(:force => :boolean, :retries => :numeric)
-    
-    # here is how the following command-line invocations would be parsed:
-    
-    command -f --retries 5    # => {'force' => true, 'retries' => 5}
-    command --force -r=5      # => {'force' => true, 'retries' => 5}
-    command -fr 5             # => {'force' => true, 'retries' => 5}
-    command --retries=5       # => {'retries' => 5}
-    command -r5               # => {'retries' => 5}
+See MIT LICENSE.

data/lib/thor.rb

@@ -199,7 +199,7 @@ class Thor
       end
 
       def valid_task?(meth) #:nodoc:
-        public_instance_methods.include?(meth) && @usage && @desc
+        @usage && @desc
       end
 
       def create_task(meth) #:nodoc:

data/lib/thor/actions.rb

@@ -175,7 +175,9 @@ class Thor
     #                       If a symbol is given, uses it as the output color.
     #
     def run_ruby_script(command, log_status=true)
-      run("ruby #{command}", log_status)
+      return unless behavior == :invoke
+      say_status File.basename(Thor::Util.ruby_command), command, log_status
+      `#{Thor::Util.ruby_command} #{command}` unless options[:pretend]
     end
 
     # Run a thor command. A hash of options can be given and it's converted to 
@@ -198,13 +200,14 @@ class Thor
     #
     def thor(task, *args)
       log_status = args.last.is_a?(Symbol) || [true, false].include?(args.last) ? args.pop : true
-      options = args.last.is_a?(Hash) ? args.pop : {}
+      options    = args.last.is_a?(Hash) ? args.pop : {}
 
-      in_root do
-        args.unshift "thor #{task}"
-        args.push Thor::Options.to_switches(options)
-        run args.join(' ').strip, log_status
-      end
+      args.unshift task
+      args.push Thor::Options.to_switches(options)
+      command = args.join(' ').strip
+
+      say_status :thor, command, log_status
+      run "thor #{command}", false
     end
 
     # Removes a file at the given location.
@@ -221,9 +224,10 @@ class Thor
     #
     def remove_file(path, log_status=true)
       return unless behavior == :invoke
-      path = File.expand_path(path, root)
-      say_status :remove, relative_to_absolute_root(path), log_status
+      path  = File.expand_path(path, root)
+      color = log_status.is_a?(Symbol) ? log_status : :red
 
+      say_status :remove, relative_to_absolute_root(path), log_status
       ::FileUtils.rm_rf(path) if !options[:pretend] && File.exists?(path)
     end
 
@@ -305,11 +309,11 @@ class Thor
 
       # Allow current root to be shared between invocations.
       #
-      def _shared_configuration
+      def _shared_configuration #:nodoc:
         super.merge!(:root => self.root)
       end
 
-      def _cleanup_options_and_set(options, key)
+      def _cleanup_options_and_set(options, key) #:nodoc:
         case options
           when Array
             %w(--force -f --skip -s).each { |i| options.delete(i) }

data/lib/thor/actions/directory.rb

@@ -53,13 +53,14 @@ class Thor
       end
 
       def invoke!
+        base.empty_directory given_destination
         lookup = recursive ? File.join(source, '**', '*') : File.join(source, '*')
 
         Dir[lookup].each do |file_source|
           file_destination = File.join(given_destination, file_source.gsub(source, '.'))
 
           if File.directory?(file_source)
-            base.empty_directory(file_destination, @log_status)
+            base.empty_directory(file_destination, @log_status) if recursive
           elsif file_source !~ /\.empty_directory$/
             if file_source =~ /\.tt$/
               base.template(file_source, file_destination[0..-4], @log_status)

data/lib/thor/actions/templater.rb

@@ -65,7 +65,7 @@ class Thor
       # Revokes the action.
       #
       def revoke!
-        say_status :remove, :green
+        say_status :remove, :red
         ::FileUtils.rm_rf(destination) if !pretend? && exists?
       end
 

data/lib/thor/base.rb

@@ -374,7 +374,7 @@ class Thor
               groups[value.group] << value
             end
 
-            printer = lambda do |group_name, options|
+            printer = proc do |group_name, options|
               list = []
               padding = options.collect{ |o| o.aliases.size  }.max.to_i * 4
 
@@ -471,7 +471,13 @@ class Thor
             return
           end
 
+          # Return if it's not a public instance method
+          return unless public_instance_methods.include?(meth) ||
+                        public_instance_methods.include?(meth.to_sym)
+
+          # Return if @no_tasks is enabled or it's not a valid task
           return if @no_tasks || !valid_task?(meth)
+
           is_thor_reserved_word?(meth, :task)
           Thor::Base.register_klass_file(self)
           create_task(meth)
@@ -497,6 +503,7 @@ class Thor
         # SIGNATURE: Defines if a given method is a valid_task?. This method is
         # called before a new method is added to the class.
         def valid_task?(meth) #:nodoc:
+          true # unless otherwise given
         end
 
         # SIGNATURE: Creates a new task if valid_task? is true. This method is

data/lib/thor/core_ext/ordered_hash.rb

@@ -3,94 +3,100 @@ require 'forwardable'
 class Thor #:nodoc:
   module CoreExt #:nodoc:
 
-    # This class is based on the Ruby 1.9 ordered hashes.
-    #
-    # It keeps the semantics and most of the efficiency of normal hashes
-    # while also keeping track of the order in which elements were set.
-    #
-    class OrderedHash #:nodoc:
-      include Enumerable
-
-      Node = Struct.new(:key, :value, :next, :prev)
-
-      def initialize
-        @hash = {}
-      end
-
-      def [](key)
-        @hash[key] && @hash[key].value
+    if RUBY_VERSION >= '1.9'
+      class OrderedHash < ::Hash
       end
+    else
+      # This class is based on the Ruby 1.9 ordered hashes.
+      #
+      # It keeps the semantics and most of the efficiency of normal hashes
+      # while also keeping track of the order in which elements were set.
+      #
+      class OrderedHash #:nodoc:
+        include Enumerable
+
+        Node = Struct.new(:key, :value, :next, :prev)
+
+        def initialize
+          @hash = {}
+        end
 
-      def []=(key, value)
-        if node = @hash[key]
-          node.value = value
-        else
-          node = Node.new(key, value)
+        def [](key)
+          @hash[key] && @hash[key].value
+        end
 
-          if @first.nil?
-            @first = @last = node
+        def []=(key, value)
+          if node = @hash[key]
+            node.value = value
           else
-            node.prev = @last
-            @last.next = node
-            @last = node
+            node = Node.new(key, value)
+
+            if @first.nil?
+              @first = @last = node
+            else
+              node.prev = @last
+              @last.next = node
+              @last = node
+            end
           end
+
+          @hash[key] = node
+          value
         end
 
-        @hash[key] = node
-        value
-      end
+        def delete(key)
+          if node = @hash[key]
+            prev_node = node.prev
+            next_node = node.next
 
-      def delete(key)
-        if node = @hash[key]
-          prev_node = node.prev
-          next_node = node.next
+            next_node.prev = prev_node if next_node
+            prev_node.next = next_node if prev_node
 
-          next_node.prev = prev_node if next_node
-          prev_node.next = next_node if prev_node
+            @first = next_node if @first == node
+            @last = prev_node  if @last  == node
 
-          @first = next_node if @first == node
-          @last = prev_node  if @last  == node
+            value = node.value
+          end
 
-          value = node.value
+          @hash.delete(key)
+          value
         end
 
-        @hash.delete(key)
-        value
-      end
+        def keys
+          self.map { |k, v| k }
+        end
 
-      def keys
-        self.map { |k, v| k }
-      end
+        def values
+          self.map { |k, v| v }
+        end
 
-      def values
-        self.map { |k, v| v }
-      end
+        def each
+          return unless @first
+          yield [@first.key, @first.value]
+          node = @first
+          yield [node.key, node.value] while node = node.next
+          self
+        end
 
-      def each
-        return unless @first
-        yield [@first.key, @first.value]
-        node = @first
-        yield [node.key, node.value] while node = node.next
-        self
-      end
+        def merge(other)
+          hash = self.class.new
 
-      def merge(other)
-        hash = self.class.new
+          self.each do |key, value|
+            hash[key] = value
+          end
 
-        self.each do |key, value|
-          hash[key] = value
-        end
+          other.each do |key, value|
+            hash[key] = value
+          end
 
-        other.each do |key, value|
-          hash[key] = value
+          hash
         end
 
-        hash
-      end
-
-      def empty?
-        @hash.empty?
+        def empty?
+          @hash.empty?
+        end
       end
     end
+
   end
 end

data/lib/thor/group.rb

@@ -63,10 +63,6 @@ class Thor::Group
         Thor::Group
       end
 
-      def valid_task?(meth) #:nodoc:
-        public_instance_methods.include?(meth)
-      end
-
       def create_task(meth) #:nodoc:
         tasks[meth.to_s] = Thor::Task.new(meth, nil, nil, nil)
       end

data/lib/thor/invocation.rb

@@ -97,7 +97,7 @@ class Thor
       method_args = []
       current = @_invocations[klass]
 
-      iterator = lambda do |_, task|
+      iterator = proc do |_, task|
         unless current.include?(task.name)
           current << task.name
           task.run(instance, method_args)

data/lib/thor/parser/option.rb

@@ -80,7 +80,7 @@ class Thor
     end
 
     def usage(padding=0)
-      sample = if banner
+      sample = if banner && !banner.to_s.empty?
         "#{switch_name}=#{banner}"
       else
         switch_name

data/lib/thor/runner.rb

@@ -243,8 +243,7 @@ class Thor::Runner < Thor
         v[:namespaces] && !(v[:namespaces] & lookup).empty?
       end
 
-      files.map! { |k, v| File.join(thor_root, "#{v[:filename]}") }
-      files
+      files.map { |k, v| File.join(thor_root, "#{v[:filename]}") }
     end
 
     # Display information about the given klasses. If with_module is given,

data/lib/thor/shell/color.rb

@@ -60,7 +60,7 @@ class Thor
         # available.
         #
         def show_diff(destination, content)
-          if diff_lcs_loaded?
+          if diff_lcs_loaded? && ENV['THOR_DIFF'].nil? && ENV['RAILS_DIFF'].nil?
             actual  = File.read(destination).to_s.split("\n")
             content = content.to_s.split("\n")
 

data/lib/thor/util.rb

@@ -1,3 +1,5 @@
+require 'rbconfig'
+
 class Thor
   module Sandbox; end
 
@@ -203,5 +205,19 @@ class Thor
       ["#{path}/Thorfile", "#{path}/*.thor", "#{path}/tasks/*.thor", "#{path}/lib/tasks/*.thor"]
     end
 
+    # Return the path to the ruby interpreter taking into account multiple
+    # installations and windows extensions.
+    #
+    def self.ruby_command #:nodoc:
+      @ruby_command ||= begin
+        ruby = File.join(Config::CONFIG['bindir'], Config::CONFIG['ruby_install_name'])
+        ruby << Config::CONFIG['EXEEXT']
+
+        # escape string in case path to ruby executable contain spaces.
+        ruby.sub!(/.*\s.*/m, '"\&"')
+        ruby
+      end
+    end
+
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: josevalim-thor
 version: !ruby/object:Gem::Version 
-  version: 0.10.23
+  version: 0.10.25
 platform: ruby
 authors: 
 - Yehuda Katz
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-02 00:00:00 -07:00
+date: 2009-07-04 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
-description: A gem that maps options to a class
+description: A scripting framework that replaces rake, sake and rubigen
 email: wycats@gmail.com
 executables: 
 - thor
@@ -93,6 +93,6 @@ rubyforge_project: thor
 rubygems_version: 1.2.0
 signing_key: 
 specification_version: 3
-summary: A gem that maps options to a class
+summary: A scripting framework that replaces rake, sake and rubigen
 test_files: []