thor 0.9.9 → 0.11.5

data/CHANGELOG.rdoc

@@ -1,9 +1,34 @@
 == 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
+
+== 0.11.x, released 2009-07-01
+
+* Added a rake compatibility layer. It allows you to use spec and rdoc tasks on
+  Thor classes.
+
+* 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 +74,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.rdoc

@@ -0,0 +1,234 @@
+= thor
+
+Map options to a class. Simply create a class with the appropriate annotations
+and have options automatically map to functions and parameters.
+
+Example:
+
+    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
+      end
+      
+      desc "list [SEARCH]", "list all of the available apps, limited by SEARCH"
+      def list(search="")
+        # list everything
+      end
+    end
+
+Thor automatically maps commands as such:
+
+    thor app:install myname --force
+
+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.
+
+== 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>
+* :numeric - is parsed as <tt>--option=N</tt>
+* :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:
+
+    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 <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:
+
+    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 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).
+
+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 <tt>method_option</tt>
+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
+
+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.
+
+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.
+
+== License
+
+See MIT LICENSE.

data/Thorfile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'thor/rake_compat'
+require 'spec/rake/spectask'
+require 'rdoc/task'
+
+GEM_NAME = 'thor'
+EXTRA_RDOC_FILES = ["README.rdoc", "LICENSE", "CHANGELOG.rdoc", "VERSION", "Thorfile"]
+
+class Default < Thor
+  include Thor::RakeCompat
+
+  Spec::Rake::SpecTask.new(:spec) do |t|
+    t.spec_opts = ['--options', "spec/spec.opts"]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+  end
+
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_opts = ['--options', "spec/spec.opts"]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+    t.rcov = true
+    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'
+  end
+
+  begin
+    require 'jeweler'
+    Jeweler::Tasks.new do |s|
+      s.name = GEM_NAME
+      s.version = "0.11.4"
+      s.rubyforge_project = "textmate"
+      s.platform = Gem::Platform::RUBY
+      s.summary = "A scripting framework that replaces rake, sake and rubigen"
+      s.email = "ruby-thor@googlegroups.com"
+      s.homepage = "http://yehudakatz.com"
+      s.description = "A scripting framework that replaces rake, sake and rubigen"
+      s.authors = ['Yehuda Katz', 'José Valim']
+      s.has_rdoc = true
+      s.extra_rdoc_files = EXTRA_RDOC_FILES
+      s.require_path = 'lib'
+      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.exclude 'spec/sandbox/**/*'
+    end
+  rescue LoadError
+    puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.11.5

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

@@ -1,146 +1,243 @@
 $:.unshift File.expand_path(File.dirname(__FILE__))
-require "thor/options"
-require "thor/util"
-require "thor/task"
-require "thor/task_hash"
+require 'thor/base'
+require 'thor/group'
+require 'thor/actions'
 
 class Thor
-  attr_accessor :options
-  
-  def self.map(map)
-    @map ||= superclass.instance_variable_get("@map") || {}
-    map.each do |key, value|
-      if key.respond_to?(:each)
-        key.each {|subkey| @map[subkey] = value}
+  class << self
+    # Sets the default task when thor is executed without an explicit task to be called.
+    #
+    # ==== Parameters
+    # meth<Symbol>:: name of the defaut task
+    #
+    def default_task(meth=nil)
+      case meth
+        when :none
+          @default_task = 'help'
+        when nil
+          @default_task ||= from_superclass(:default_task, 'help')
+        else
+          @default_task = meth.to_s
+      end
+    end
+
+    # Defines the usage and the description of the next task.
+    #
+    # ==== Parameters
+    # usage<String>
+    # description<String>
+    #
+    def desc(usage, description, options={})
+      if options[:for]
+        task = find_and_refresh_task(options[:for])
+        task.usage = usage             if usage
+        task.description = description if description
       else
-        @map[key] = value
+        @usage, @desc = usage, description
       end
     end
-  end
 
-  def self.desc(usage, description)
-    @usage, @desc = usage, description
-  end
-  
-  def self.group(name)
-    @group_name = name.to_s
-  end
-  
-  def self.group_name
-    @group_name || 'standard'
-  end
-  
-  def self.method_options(opts)
-    @method_options = opts
-  end
+    # Maps an input to a task. If you define:
+    #
+    #   map "-T" => "list"
+    #
+    # Running:
+    #
+    #   thor -T
+    #
+    # Will invoke the list task.
+    #
+    # ==== Parameters
+    # Hash[String|Array => Symbol]:: Maps the string or the strings in the array to the given task.
+    #
+    def map(mappings=nil)
+      @map ||= from_superclass(:map, {})
+
+      if mappings
+        mappings.each do |key, value|
+          if key.respond_to?(:each)
+            key.each {|subkey| @map[subkey] = value}
+          else
+            @map[key] = value
+          end
+        end
+      end
 
-  def self.subclass_files
-    @subclass_files ||= Hash.new {|h,k| h[k] = []}
-  end
-  
-  def self.subclasses
-    @subclasses ||= []
-  end
-  
-  def self.tasks
-    @tasks ||= TaskHash.new(self)
-  end
+      @map
+    end
 
-  def self.opts
-    (@opts || {}).merge(self == Thor ? {} : superclass.opts)
-  end
+    # Declares the options for the next task to be declared.
+    #
+    # ==== Parameters
+    # Hash[Symbol => Object]:: The hash key is the name of the option and the value
+    # is the type of the option. Can be :string, :array, :hash, :boolean, :numeric
+    # or :required (string). If you give a value, the type of the value is used.
+    #
+    def method_options(options=nil)
+      @method_options ||= {}
+      build_options(options, @method_options) if options
+      @method_options
+    end
 
-  def self.[](task)
-    namespaces = task.split(":")
-    klass = Thor::Util.constant_from_thor_path(namespaces[0...-1].join(":"))
-    raise Error, "`#{klass}' is not a Thor class" unless klass <= Thor
-    klass.tasks[namespaces.last]
-  end
+    # Adds an option to the set of class options. If :for is given as option,
+    # it allows you to change the options from a previous defined task.
+    #
+    #   def previous_task
+    #     # magic
+    #   end
+    #
+    #   method_options :foo => :bar, :for => :previous_task
+    #
+    #   def next_task
+    #     # magic
+    #   end
+    #
+    # ==== Parameters
+    # name<Symbol>:: The name of the argument.
+    # options<Hash>:: Described below.
+    #
+    # ==== Options
+    # :desc     - Description for the argument.
+    # :required - If the argument is required or not.
+    # :default  - Default value for this argument. It cannot be required and have default values.
+    # :aliases  - Aliases for this option.
+    # :type     - The type of the argument, can be :string, :hash, :array, :numeric or :boolean.
+    # :group    - The group for this options. Use by class options to output options in different levels.
+    # :banner   - String to show on usage notes.
+    #
+    def method_option(name, options={})
+      scope = if options[:for]
+        find_and_refresh_task(options[:for]).options
+      else
+        method_options
+      end
 
-  def self.maxima
-    @maxima ||= begin
-      max_usage = tasks.map {|_, t| t.usage}.max {|x,y| x.to_s.size <=> y.to_s.size}.size
-      max_desc  = tasks.map {|_, t| t.description}.max {|x,y| x.to_s.size <=> y.to_s.size}.size
-      max_opts  = tasks.map {|_, t| t.opts ? t.opts.formatted_usage : ""}.max {|x,y| x.to_s.size <=> y.to_s.size}.size
-      Struct.new(:description, :usage, :opt).new(max_desc, max_usage, max_opts)
+      build_option(name, options, scope)
     end
-  end
-  
-  def self.start(args = ARGV)
-    options = Thor::Options.new(self.opts)
-    opts = options.parse(args, false)
-    args = options.trailing_non_opts
-
-    meth = args.first
-    meth = @map[meth].to_s if @map && @map[meth]
-    meth ||= "help"
-    
-    tasks[meth].parse new(opts, *args), args[1..-1]
-  rescue Thor::Error => e
-    $stderr.puts e.message
-  end
 
-  class << self
-    protected
-    def inherited(klass)
-      register_klass_file klass
+    # 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={})
+      super do
+        meth = normalize_task_name(given_args.shift)
+        task = all_tasks[meth]
+
+        if task
+          args, opts = Thor::Options.split(given_args)
+          config.merge!(:task_options => task.options)
+        else
+          args, opts = given_args, {}
+        end
+
+        task ||= Task.dynamic(meth)
+        trailing = args[Range.new(arguments.size, -1)]
+        new(args, opts, config).invoke(task, trailing || [])
+      end
     end
 
-    def method_added(meth)
-      meth = meth.to_s
-      
-      if meth == "initialize"
-        @opts = @method_options
-        @method_options = nil
-        return
+    # Prints help information. If a task name is given, it shows information
+    # only about the specific task.
+    #
+    # ==== Parameters
+    # meth<String>:: An optional task name to print usage information about.
+    #
+    # ==== Options
+    # namespace:: When true, shows the namespace in the output before the usage.
+    # skip_inherited:: When true, does not show tasks from superclass.
+    #
+    def help(shell, meth=nil, options={})
+      meth, options = nil, meth if meth.is_a?(Hash)
+
+      if meth
+        task = all_tasks[meth]
+        raise UndefinedTaskError, "task '#{meth}' could not be found in namespace '#{self.namespace}'" unless task
+
+        shell.say "Usage:"
+        shell.say "  #{banner(task, options[:namespace], false)}"
+        shell.say
+        class_options_help(shell, "Class", :Method => task.options.map { |_, o| o })
+        shell.say task.description
+      else
+        list = (options[:short] ? tasks : all_tasks).map do |_, task|
+          item = [ banner(task, options[:namespace]) ]
+          item << "# #{task.short_description}" if task.short_description
+          item << " "
+        end
+
+        options[:ident] ||= 2
+        if options[:short]
+          shell.print_list(list, :ident => options[:ident])
+        else
+          shell.say "Tasks:"
+          shell.print_list(list, :ident => options[:ident])
+        end
+
+        Thor::Util.thor_classes_in(self).each do |subclass|
+          namespace = options[:namespace] == true || subclass.namespace.gsub(/^#{self.namespace}:/, '')
+          subclass.help(shell, options.merge(:short => true, :namespace => namespace))
+        end
+
+        class_options_help(shell, "Class") unless options[:short]
       end
+    end
 
-      return if !public_instance_methods.include?(meth) || !@usage
-      register_klass_file self
-
-      tasks[meth] = Task.new(meth, @desc, @usage, @method_options)
+    protected
 
-      @usage, @desc, @method_options = nil
-    end
+      # 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. It receives
+      # the task that is going to be invoked and a boolean which indicates if
+      # the namespace should be displayed as arguments.
+      #
+      def banner(task, namespace=true, show_options=true)
+        task.formatted_usage(self, namespace, show_options)
+      end
 
-    def register_klass_file(klass, file = caller[1].split(":")[0])
-      unless self == Thor
-        superclass.register_klass_file(klass, file)
-        return
+      def baseclass #:nodoc:
+        Thor
       end
 
-      file_subclasses = subclass_files[File.expand_path(file)]
-      file_subclasses << klass unless file_subclasses.include?(klass)
-      subclasses << klass unless subclasses.include?(klass)
-    end
-  end
+      def create_task(meth) #:nodoc:
+        if @usage && @desc
+          tasks[meth.to_s] = Thor::Task.new(meth, @desc, @usage, method_options)
+          @usage, @desc, @method_options = nil
+          true
+        elsif self.all_tasks[meth.to_s] || meth.to_sym == :method_missing
+          true
+        else
+          puts "[WARNING] Attempted to create task #{meth.inspect} without usage or description. " <<
+               "Call desc if you want this method to be available as task or declare it inside a " <<
+               "no_tasks{} block. Invoked from #{caller[1].inspect}."
+          false
+        end
+      end
 
-  def initialize(opts = {}, *args)
-  end
-  
-  map ["-h", "-?", "--help", "-D"] => :help
-  
-  desc "help [TASK]", "describe available tasks or one specific task"
-  def help(task = nil)
-    if task
-      if task.include? ?:
-        task = self.class[task]
-        namespace = true
-      else
-        task = self.class.tasks[task]
+      def initialize_added #:nodoc:
+        class_options.merge!(method_options)
+        @method_options = nil
       end
 
-      puts task.formatted_usage(namespace)
-      puts task.description
-    else
-      puts "Options"
-      puts "-------"
-      self.class.tasks.each do |_, task|
-        format = "%-" + (self.class.maxima.usage + self.class.maxima.opt + 4).to_s + "s"
-        print format % ("#{task.formatted_usage}")      
-        puts  task.description.split("\n").first
+      # Receives a task name (can be nil), and try to get a map from it.
+      # If a map can't be found use the sent name or the default task.
+      #
+      def normalize_task_name(meth) #:nodoc:
+        mapping = map[meth.to_s]
+        meth = mapping || meth || default_task
+        meth.to_s.gsub('-','_') # treat foo-bar > foo_bar
       end
-    end
   end
-  
+
+  include Thor::Base
+
+  map HELP_MAPPINGS => :help
+
+  desc "help [TASK]", "Describe available tasks or one specific task"
+  def help(task=nil)
+    self.class.help(shell, task, :namespace => task && task.include?(?:))
+  end
 end