thor 0.13.4 → 0.14.3

data/CHANGELOG.rdoc

@@ -1,8 +1,10 @@
 == 0.13, released 2010-02-03
 
-* Several bug fixes
+* Added :lazy_default which is only triggered if a switch is given
+* Added Thor::Shell::HTML
+* Added subcommands
 * Decoupled Thor::Group and Thor, so it's easier to vendor
-* Added check_unknown_options! in case you want error messages to be raised in valid switches.
+* Added check_unknown_options! in case you want error messages to be raised in valid switches
 * run(command) should return the results of command
 
 == 0.12, released 2010-01-02
@@ -20,7 +22,7 @@
   Thor classes.
 
 * BACKWARDS INCOMPATIBLE: aliases are not generated automatically anymore
-  since it wrong behavior to the invocation system.
+  since it may cause wrong behavior in the invocation system.
 
 * thor help now show information about any class/task. All those calls are
   possible:

data/{README.rdoc → README.md}

@@ -1,7 +1,21 @@
-= thor
+# Thor 
 
-Map options to a class. Simply create a class with the appropriate annotations
-and have options automatically map to functions and parameters.
+## Description
+
+Thor is a simple and efficient tool for building self-documenting command line utilities.  It removes the pain of parsing command line options, writing "USAGE:" banners, and can also be used as an alternative to the [Rake](http://github.com/jimweirich/rake) build tool.  The syntax is Rake-like, so it should be familiar to most Rake users. 
+
+## Installation
+
+$ gem install thor
+
+or
+
+$ gem install wycats-thor -s http://gems.github.com
+
+## Usage
+
+Map options to a class.  Simply create a class with the appropriate annotations
+and have options automatically map to functions and parameters.  
 
 Example:
 
@@ -24,7 +38,7 @@ Example:
       end
     end
 
-Thor automatically maps commands as such:
+Thor automatically maps commands as such: 
 
     thor app:install myname --force
 
@@ -33,12 +47,12 @@ That gets converted to:
     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 that will be available the instance method options.
+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 that will be available the instance method options.  
 
-== Types for <tt>method_options</tt>
+## Types for <tt>method_options</tt>
 
 * :boolean - is parsed as <tt>--option</tt> or <tt>--option=true</tt>
 * :string  - is parsed as <tt>--option=VALUE</tt>
@@ -46,7 +60,7 @@ That gets converted to:
 * :array   - is parsed as <tt>--option=one two three</tt>
 * :hash    - is parsed as <tt>--option=name:string age:integer</tt>
 
-Besides, method_option allows a default value to be given, examples:
+Besides, method_option allows a default value to be given.  Examples:
 
     method_options :force => false
     #=> Creates a boolean option with default value false
@@ -57,19 +71,19 @@ Besides, method_option allows a default value to be given, examples:
     method_options :threshold => 3.0
     #=> Creates a numeric option with default value 3.0
 
-You can also supply <tt>:option => :required</tt> to mark an option as required. The
-type is assumed to be string. If you want a required hash with default values
+You can also supply <tt>:option => :required</tt> 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 <tt>method_option</tt> 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:
+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
+they should be explicit.  You can supply aliases in both short and declarative
 styles:
 
     method_options %w( force -f ) => :boolean
@@ -82,9 +96,9 @@ 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
+## Namespaces
 
-By default, your Thor tasks are invoked using Ruby namespace. In the example
+By default, your Thor tasks are invoked using Ruby namespace.  In the example
 above, tasks are invoked as:
 
     thor app:install name --force
@@ -110,14 +124,13 @@ If desired, you can change the namespace:
       end
     end
 
-And then your tasks hould be invoked as:
+And then your tasks should be invoked as:
 
     thor myapp:install name --force
 
-== Invocations
+## Invocations
 
-Thor comes with a invocation-dependency system as well which allows a task to be
-invoked only once. For example:
+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"
@@ -143,14 +156,16 @@ When invoking the task one:
 
     thor counter:one
 
-The output is "1 2 3", which means that the three task was invoked only once.
+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[http://rdoc.info/rdoc/wycats/thor/blob/f939a3e8a854616784cac1dcff04ef4f3ee5f7ff/Thor.html].
+[documentation](http://rdoc.info/rdoc/wycats/thor/blob/f939a3e8a854616784cac1dcff04ef4f3ee5f7ff/Thor.html).
 
-== Thor::Group
+Notice invocations do not share the same object. I.e, Thor will instantiate Counter once to invoke the task one, then, it instantiates another to invoke the task two and another for task three. This happens to allow options and arguments to parsed again. For example, if two and three have different options and both of them were given to the command line, calling invoke makes them be parsed each time and used accordingly by each task.
 
-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
+
+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
@@ -173,12 +188,12 @@ When invoked:
 
     thor counter
 
-It prints "1 2 3" as well. Notice you should describe (using the method <tt>desc</tt>)
-only the class and not each task anymore. Thor::Group is a great tool to create
+It prints "1 2 3" as well.  Notice you should describe (using the method <tt>desc</tt>)
+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).
+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:
+Besides, Thor::Group can parse arguments and options as Thor tasks: 
 
     class Counter < Thor::Group
       # number will be available as attr_accessor
@@ -210,13 +225,13 @@ You can also give options to Thor::Group, but instead of using <tt>method_option
 and <tt>method_options</tt>, you should use <tt>class_option</tt> and <tt>class_options</tt>.
 Both argument and class_options methods are available to Thor class as well.
 
-== Actions
+## 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:
+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:
 <tt>say</tt>, <tt>ask</tt>, <tt>yes?</tt>, <tt>no?</tt>, <tt>add_file</tt>,
 <tt>remove_file</tt>, <tt>copy_file</tt>, <tt>template</tt>, <tt>directory</tt>,
-<tt>inside</tt>, <tt>run</tt>, <tt>inject_into_file</tt> and a couple more.
+<tt>inside</tt>, <tt>run</tt>, <tt>inject_into_file</tt> and a couple more. 
 
 To use them, you just need to include Thor::Actions in your Thor classes:
 
@@ -226,13 +241,13 @@ To use them, you just need to include Thor::Actions in your Thor classes:
     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 on actions[http://rdoc.info/rdoc/wycats/thor/blob/f939a3e8a854616784cac1dcff04ef4f3ee5f7ff/Thor/Actions.html].
+defined in your class.  This is the directory where your templates should be
+placed.  Be sure to check the documentation on [actions](http://rdoc.info/rdoc/wycats/thor/blob/f939a3e8a854616784cac1dcff04ef4f3ee5f7ff/Thor/Actions.html).
 
-== Generators
+## 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:
+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
@@ -264,34 +279,29 @@ Thor::Actions and ERB templates makes this very easy. Here is an example:
       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
+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 %>
+    class <%= name.capitalize %>
     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
+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".
+create two files: "devise/lib/devise.rb", and "devise/test/devise_test.rb".  The user will then be asked (via a prompt by the <tt>yes?</tt> method) whether or not they would like to copy the MIT License.  If you want to change the test framework, you can add the option: <tt>thor newgem devise --test-framework=rspec</tt> 
+
+This will generate two files - "devise/lib/devise.rb" and "devise/spec/devise_spec.rb".
 
-== Further Reading
+## 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.
+Thor offers 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 the options available. 
 
-== License
+## License
 
-See MIT LICENSE.
+Released under the MIT License.  See the LICENSE file for further details. 

data/Thorfile

@@ -10,7 +10,7 @@ rescue LoadError
 end
 
 GEM_NAME = 'thor'
-EXTRA_RDOC_FILES = ["README.rdoc", "LICENSE", "CHANGELOG.rdoc", "VERSION", "Thorfile"]
+EXTRA_RDOC_FILES = ["README.md", "LICENSE", "CHANGELOG.rdoc", "Thorfile"]
 
 class Default < Thor
   include Thor::RakeCompat
@@ -44,7 +44,7 @@ class Default < Thor
     require 'jeweler'
     Jeweler::Tasks.new do |s|
       s.name = GEM_NAME
-      s.version = Thor::VERSION
+      s.version = Thor::VERSION.dup
       s.rubyforge_project = "textmate"
       s.platform = Gem::Platform::RUBY
       s.summary = "A scripting framework that replaces rake, sake and rubigen"
@@ -59,6 +59,7 @@ class Default < Thor
       s.executables = %w( thor rake2thor )
       s.files = s.extra_rdoc_files + Dir.glob("{bin,lib}/**/*")
       s.test_files.include 'spec/**/*'
+      s.test_files.include 'spec/fixtures/doc/components/.empty_directory'
       s.test_files.exclude 'spec/sandbox/**/*'
     end
 

data/lib/thor/actions/create_file.rb

@@ -20,7 +20,9 @@ class Thor
     #
     #   create_file "config/apach.conf", "your apache config"
     #
-    def create_file(destination, data=nil, config={}, &block)
+    def create_file(destination, *args, &block)
+      config = args.last.is_a?(Hash) ? args.pop : {}
+      data = args.first
       action CreateFile.new(self, destination, block || data.to_s, config)
     end
     alias :add_file :create_file

data/lib/thor/actions/directory.rb

@@ -21,7 +21,7 @@ class Thor
     #   directory "doc"
     #
     # It will create a doc directory in the destination with the following
-    # files (assuming that the app_name is "blog"):
+    # files (assuming that the `app_name` method returns the value "blog"):
     #
     #   doc/
     #     components/
@@ -40,7 +40,9 @@ class Thor
     #   directory "doc"
     #   directory "doc", "docs", :recursive => false
     #
-    def directory(source, destination=nil, config={}, &block)
+    def directory(source, *args, &block)
+      config = args.last.is_a?(Hash) ? args.pop : {}
+      destination = args.first || source
       action Directory.new(self, source, destination || source, config, &block)
     end
 

data/lib/thor/actions/file_manipulation.rb

@@ -18,8 +18,9 @@ class Thor
     #
     #   copy_file "doc/README"
     #
-    def copy_file(source, destination=nil, config={}, &block)
-      destination ||= source
+    def copy_file(source, *args, &block)
+      config = args.last.is_a?(Hash) ? args.pop : {}
+      destination = args.first || source
       source = File.expand_path(find_in_source_paths(source.to_s))
 
       create_file destination, nil, config do
@@ -46,9 +47,12 @@ class Thor
     #     content.split("\n").first
     #   end
     #
-    def get(source, destination=nil, config={}, &block)
+    def get(source, *args, &block)
+      config = args.last.is_a?(Hash) ? args.pop : {}
+      destination = args.first
+
       source = File.expand_path(find_in_source_paths(source.to_s)) unless source =~ /^http\:\/\//
-      render = open(source).binmode.read
+      render = open(source) {|input| input.binmode.read }
 
       destination ||= if block_given?
         block.arity == 1 ? block.call(render) : block.call
@@ -74,13 +78,15 @@ class Thor
     #
     #   template "doc/README"
     #
-    def template(source, destination=nil, config={}, &block)
-      destination ||= source
+    def template(source, *args, &block)
+      config = args.last.is_a?(Hash) ? args.pop : {}
+      destination = args.first || source
+
       source  = File.expand_path(find_in_source_paths(source.to_s))
       context = instance_eval('binding')
 
       create_file destination, nil, config do
-        content = ERB.new(::File.binread(source), nil, '-').result(context)
+        content = ERB.new(::File.binread(source), nil, '-', '@output_buffer').result(context)
         content = block.call(content) if block
         content
       end
@@ -219,5 +225,22 @@ class Thor
     end
     alias :remove_dir :remove_file
 
+  private
+    attr_accessor :output_buffer
+    def concat(string)
+      @output_buffer.concat(string)
+    end
+
+    def capture(*args, &block)
+      with_output_buffer { block.call(*args) }
+    end
+
+    def with_output_buffer(buf = '') #:nodoc:
+      self.output_buffer, old_buffer = buf, output_buffer
+      yield
+      output_buffer
+    ensure
+      self.output_buffer = old_buffer
+    end
   end
 end

data/lib/thor/actions.rb

@@ -1,4 +1,5 @@
 require 'fileutils'
+require 'uri'
 require 'thor/core_ext/file_binary_read'
 
 Dir[File.join(File.dirname(__FILE__), "actions", "*.rb")].each do |action|
@@ -19,7 +20,13 @@ class Thor
       # inherited paths and the source root.
       #
       def source_paths
-        @source_paths ||= []
+        @_source_paths ||= []
+      end
+
+      # Stores and return the source root for this class
+      def source_root(path=nil)
+        @_source_root = path if path
+        @_source_root
       end
 
       # Returns the source paths in the following order:
@@ -31,7 +38,7 @@ class Thor
       def source_paths_for_search
         paths = []
         paths += self.source_paths
-        paths << self.source_root if self.respond_to?(:source_root)
+        paths << self.source_root if self.source_root
         paths += from_superclass(:source_paths, [])
         paths
       end
@@ -115,7 +122,7 @@ class Thor
       @source_paths ||= self.class.source_paths_for_search
     end
 
-    # Receives a file or directory and search for it in the source paths. 
+    # Receives a file or directory and search for it in the source paths.
     #
     def find_in_source_paths(file)
       relative_root = relative_to_original_destination_root(destination_root, false)
@@ -125,12 +132,19 @@ class Thor
         return source_file if File.exists?(source_file)
       end
 
+      message = "Could not find #{file.inspect} in any of your source paths. "
+
+      unless self.class.source_root
+        message << "Please invoke #{self.class.name}.source_root(PATH) with the PATH containing your templates. "
+      end
+
       if source_paths.empty?
-        raise Error, "You don't have any source path defined for class #{self.class.name}. To fix this, " <<
-                     "you can define a source_root in your class."
+        message << "Currently you have no source paths."
       else
-        raise Error, "Could not find #{file.inspect} in source paths."
+        message << "Your current source paths are: \n#{source_paths.join("\n")}"
       end
+
+      raise Error, message
     end
 
     # Do something in the root or on a provided subfolder. If a relative path
@@ -176,11 +190,19 @@ class Thor
     #
     def apply(path, config={})
       verbose = config.fetch(:verbose, true)
-      path    = find_in_source_paths(path) unless path =~ /^http\:\/\//
+      is_uri  = path =~ /^https?\:\/\//
+      path    = find_in_source_paths(path) unless is_uri
 
       say_status :apply, path, verbose
       shell.padding += 1 if verbose
-      instance_eval(open(path).read)
+
+      if is_uri
+        contents = open(path, "Accept" => "application/x-thor-template") {|io| io.read }
+      else
+        contents = open(path) {|io| io.read }
+      end
+
+      instance_eval(contents, path)
       shell.padding -= 1 if verbose
     end
 
@@ -223,7 +245,7 @@ class Thor
       run command, config.merge(:with => Thor::Util.ruby_command)
     end
 
-    # Run a thor command. A hash of options can be given and it's converted to 
+    # Run a thor command. A hash of options can be given and it's converted to
     # switches.
     #
     # ==== Parameters

data/lib/thor/base.rb

@@ -53,7 +53,7 @@ class Thor
 
       opts = Thor::Options.new(parse_options, hash_options)
       self.options = opts.parse(array_options)
-      opts.check_unknown! if self.class.check_unknown_options?
+      opts.check_unknown! if self.class.check_unknown_options?(config)
     end
 
     class << self
@@ -114,8 +114,12 @@ class Thor
         @check_unknown_options = true
       end
 
-      def check_unknown_options? #:nodoc:
-        @check_unknown_options || false
+      def check_unknown_options #:nodoc:
+        @check_unknown_options ||= from_superclass(:check_unknown_options, false)
+      end
+
+      def check_unknown_options?(config) #:nodoc:
+        !!check_unknown_options
       end
 
       # Adds an argument to the class and creates an attr_accessor for it.
@@ -336,6 +340,7 @@ class Thor
       def no_tasks
         @no_tasks = true
         yield
+      ensure
         @no_tasks = false
       end
 
@@ -363,32 +368,42 @@ class Thor
       #
       def namespace(name=nil)
         case name
-          when nil
-            @namespace ||= Thor::Util.namespace_from_thor_class(self)
-          else
-            @namespace = name.to_s
+        when nil
+          @namespace ||= Thor::Util.namespace_from_thor_class(self)
+        else
+          @namespace = name.to_s
         end
       end
 
-      # Default way to start generators from the command line.
+      # 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(given_args=ARGV, config={})
-        self.debugging = given_args.include?("--debug")
+        self.debugging = given_args.delete("--debug")
         config[:shell] ||= Thor::Base.shell.new
-        yield(given_args.dup)
+        dispatch(nil, given_args.dup, nil, config)
       rescue Thor::Error => e
         debugging ? (raise e) : config[:shell].error(e.message)
         exit(1) if exit_on_failure?
       end
 
       def handle_no_task_error(task) #:nodoc:
-        if self.banner_base == "thor"
+        if $thor_runner
           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}."
+      end
+
       protected
 
         # Prints the class options per group. If an option does not belong to
@@ -445,7 +460,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[:group], options[:aliases])
+                                               options[:lazy_default], options[:group], options[:aliases])
         end
 
         # Receives a hash of options, parse them and add to the scope. This is a
@@ -516,9 +531,11 @@ class Thor
           false
         end
 
-        # Returns the base for banner.
-        def banner_base
-          @banner_base ||= $thor_runner ? "thor" : File.basename($0.split(" ").first)
+        #
+        # The basename of the program invoking the thor class.
+        #
+        def basename
+          File.basename($0).split(' ').first
         end
 
         # SIGNATURE: Sets the baseclass. This is where the superclass lookup
@@ -535,6 +552,12 @@ class Thor
         # class.
         def initialize_added #:nodoc:
         end
+
+        # SIGNATURE: The hook invoked by start.
+        def dispatch(task, given_args, given_opts, config) #:nodoc:
+          raise NotImplementedError
+        end
+
     end
   end
 end

data/lib/thor/core_ext/hash_with_indifferent_access.rb

@@ -65,7 +65,7 @@ class Thor
             else
               self[$1] == args.first
             end
-          else 
+          else
             self[method]
           end
         end