wycats-thor 0.9.8 → 0.10.26

data/CHANGELOG.rdoc

@@ -1,9 +1,32 @@
 == TODO
 
-* Change Thor.start to parse ARGV in a single pass
 * Improve spec coverage for Thor::Runner
 * Improve help output to list shorthand switches, too
-* Investigate and fix deep namespacing ("foo:bar:baz") issues
+
+== Current
+
+* BACKWARDS INCOMPATIBLE: aliases are not generated automatically anymore
+  since it wrong behavior to the invocation system.
+
+* thor help now show information about any class/task. All those calls are
+  possible:
+  
+    thor help describe
+    thor help describe:amazing
+
+  Or even with default namespaces:
+
+    thor help :spec
+
+* Thor::Runner now invokes the default task if none is supplied:
+
+    thor describe # invokes the default task, usually help
+
+* Thor::Runner now works with mappings:
+
+    thor describe -h
+
+* Added some documentation and code refactoring.
 
 == 0.9.8, released 2008-10-20
 
@@ -49,4 +72,4 @@
 * Thor::Options now doesn't parse through things that look like options but aren't.
 * Add URI detection to install task, and make sure we don't append ".thor" to URIs
 * Add rake2thor to the gem binfiles.
-* Make sure local Thorfiles override system-wide ones.
+* Make sure local Thorfiles override system-wide ones.

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</code></dt>
-    <dd>same as <code>:boolean</code></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/bin/rake2thor

@@ -2,6 +2,10 @@
 
 require 'rubygems'
 require 'ruby2ruby'
+require 'parse_tree'
+if Ruby2Ruby::VERSION >= "1.2.0"
+  require 'parse_tree_extensions'
+end
 require 'rake'
 
 input  = ARGV[0] || 'Rakefile'

data/bin/thor

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # -*- mode: ruby -*-
 
-require File.dirname(__FILE__) + "/../lib/thor"
+require File.join(File.dirname(__FILE__), '..', 'lib', 'thor')
 require 'thor/runner'
 
 Thor::Runner.start

data/lib/thor/actions/copy_file.rb

@@ -0,0 +1,32 @@
+require 'thor/actions/templater'
+
+class Thor
+  module Actions
+
+    # Copies the file from the relative source to the relative destination. If
+    # the destination is not given it's assumed to be equal to the source.
+    #
+    # ==== Parameters
+    # source<String>:: the relative path to the source root
+    # destination<String>:: the relative path to the destination root
+    # log_status<Boolean>:: if false, does not log the status. True by default.
+    #
+    # ==== Examples
+    #
+    #   copy_file "README", "doc/README"
+    #
+    #   copy_file "doc/README"
+    #
+    def copy_file(source, destination=nil, log_status=true)
+      action CopyFile.new(self, source, destination || source, log_status)
+    end
+
+    class CopyFile < Templater #:nodoc:
+
+      def render
+        @render ||= ::File.read(source)
+      end
+
+    end
+  end
+end

data/lib/thor/actions/create_file.rb

@@ -0,0 +1,49 @@
+require 'thor/actions/templater'
+
+class Thor
+  module Actions
+
+    # Create a new file relative to the destination root with the given data,
+    # which is the return value of a block or a data string.
+    #
+    # ==== Parameters
+    # destination<String>:: the relative path to the destination root.
+    # data<String|NilClass>:: the data to append to the file.
+    # log_status<Boolean>:: if false, does not log the status. True by default.
+    #
+    # ==== Examples
+    #
+    #   create_file "lib/fun_party.rb" do
+    #     hostname = ask("What is the virtual hostname I should use?")
+    #     "vhost.name = #{hostname}"
+    #   end
+    #
+    #   create_file "config/apach.conf", "your apache config"
+    #
+    def create_file(destination, data=nil, log_status=true, &block)
+      action CreateFile.new(self, destination, block || data.to_s, log_status)
+    end
+    alias :add_file :create_file
+
+    # AddFile is a subset of Template, which instead of rendering a file with
+    # ERB, it gets the content from the user.
+    #
+    class CreateFile < Templater #:nodoc:
+      attr_reader :data
+
+      def initialize(base, destination, data, log_status)
+        super(base, nil, destination, log_status)
+        @data = data
+      end
+
+      def render
+        @render ||= if data.is_a?(Proc)
+          data.call
+        else
+          data
+        end
+      end
+
+    end
+  end
+end

data/lib/thor/actions/directory.rb

@@ -0,0 +1,76 @@
+require 'thor/actions/templater'
+
+class Thor
+  module Actions
+
+    # Copies interactively 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:
+    #
+    #   doc/
+    #     components/.empty_directory
+    #     README
+    #     rdoc.rb.tt
+    #     %app_name%.rb
+    #
+    # When invoked as:
+    #
+    #   directory "doc"
+    #
+    # It will create a doc directory in the destination with the following
+    # files (assuming that the app_name is "blog"):
+    #
+    #   doc/
+    #     components/
+    #     README
+    #     rdoc.rb
+    #     blog.rb
+    #
+    # ==== Parameters
+    # source<String>:: the relative path to the source root
+    # destination<String>:: the relative path to the destination root
+    # recursive<Boolean>:: if the directory must be copied recursively, true by default
+    # log_status<Boolean>:: if false, does not log the status. True by default.
+    #
+    # ==== Examples
+    #
+    #   directory "doc"
+    #   directory "doc", "docs", false
+    #
+    def directory(source, destination=nil, recursive=true, log_status=true)
+      action Directory.new(self, source, destination || source, recursive, log_status)
+    end
+
+    class Directory < Templater #:nodoc:
+      attr_reader :recursive
+
+      def initialize(base, source, destination=nil, recursive=true, log_status=true)
+        @recursive = recursive
+        super(base, source, destination, log_status)
+      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) if recursive
+          elsif file_source !~ /\.empty_directory$/
+            if file_source =~ /\.tt$/
+              base.template(file_source, file_destination[0..-4], @log_status)
+            else
+              base.copy_file(file_source, file_destination, @log_status)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end