josevalim-thor 0.10.0

data/CHANGELOG.rdoc

@@ -0,0 +1,73 @@
+== TODO
+
+* Improve spec coverage for Thor::Runner
+* Improve help output to list shorthand switches, too
+* Investigate and fix deep namespacing ("foo:bar:baz") issues
+
+== Current
+
+* 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
+
+* Fixed some tiny issues that were introduced lately.
+
+== 0.9.7, released 2008-10-13
+
+* Setting global method options on the initialize method works as expected:
+  All other tasks will accept these global options in addition to their own.
+* Added 'group' notion to Thor task sets (class Thor); by default all tasks
+  are in the 'standard' group. Running 'thor -T' will only show the standard
+  tasks - adding --all will show all tasks. You can also filter on a specific
+  group using the --group option: thor -T --group advanced
+  
+== 0.9.6, released 2008-09-13
+
+* Generic improvements
+
+== 0.9.5, released 2008-08-27
+
+* Improve Windows compatibility
+* Update (incorrect) README and task.thor sample file
+* Options hash is now frozen (once returned)
+* Allow magic predicates on options object. For instance: `options.force?`
+* Add support for :numeric type
+* BACKWARDS INCOMPATIBLE: Refactor Thor::Options. You cannot access shorthand forms in options hash anymore (for instance, options[:f])
+* Allow specifying optional args with default values: method_options(:user => "mislav")
+* Don't write options for nil or false values. This allows, for example, turning color off when running specs.
+* Exit with the status of the spec command to help CI stuff out some.
+
+== 0.9.4, released 2008-08-13
+
+* Try to add Windows compatibility.
+* BACKWARDS INCOMPATIBLE: options hash is now accessed as a property in your class and is not passed as last argument anymore
+* Allow options at the beginning of the argument list as well as the end.
+* Make options available with symbol keys in addition to string keys.
+* Allow true to be passed to Thor#method_options to denote a boolean option.
+* If loading a thor file fails, don't give up, just print a warning and keep going.
+* Make sure that we re-raise errors if they happened further down the pipe than we care about.
+* Only delete the old file on updating when the installation of the new one is a success
+* Make it Ruby 1.8.5 compatible.
+* Don't raise an error if a boolean switch is defined multiple times.
+* 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.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Yehuda Katz
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,76 @@
+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 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]
+      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:
+
+    app install myname --force
+    
+That gets converted to:
+
+    MyApp.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.
+    
+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>
+  <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>
+</dl>
+
+In case of unsatisfied requirements, `Thor::Options::Error` is raised.
+
+Examples of option parsing:
+
+    # 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}

data/Rakefile

@@ -0,0 +1,6 @@
+task :default => :install
+
+desc "install the gem locally"
+task :install do
+  sh %{ruby "#{File.dirname(__FILE__)}/bin/thor" :install}
+end

data/bin/rake2thor

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'ruby2ruby'
+require 'parse_tree'
+if Ruby2Ruby::VERSION >= "1.2.0"
+  require 'parse_tree_extensions'
+end
+require 'rake'
+
+input  = ARGV[0] || 'Rakefile'
+output = ARGV[1] || 'Thorfile'
+
+$requires = []
+
+module Kernel
+  def require_with_record(file)
+    $requires << file if caller[1] =~ /rake2thor:/
+    require_without_record file
+  end
+  alias_method :require_without_record, :require
+  alias_method :require, :require_with_record
+end
+
+load input
+
+@private_methods = []
+
+def file_task_name(name)
+  "compile_" + name.gsub('/', '_slash_').gsub('.', '_dot_').gsub(/\W/, '_')
+end
+
+def method_for_task(task)
+  file_task = task.is_a?(Rake::FileTask)
+  comment = task.instance_variable_get('@comment')
+  prereqs = task.instance_variable_get('@prerequisites').select(&Rake::Task.method(:task_defined?))
+  actions = task.instance_variable_get('@actions')
+  name = task.name.gsub(/^([^:]+:)+/, '')
+  name = file_task_name(name) if file_task
+  meth = ''
+
+  meth << "desc #{name.inspect}, #{comment.inspect}\n" if comment
+  meth << "def #{name}\n"
+
+  meth << prereqs.map do |pre|
+    pre = pre.to_s
+    pre = file_task_name(pre) if Rake::Task[pre].is_a?(Rake::FileTask)
+    '  ' + pre
+  end.join("\n")
+
+  meth << "\n\n" unless prereqs.empty? || actions.empty?
+
+  meth << actions.map do |act|
+    act = act.to_ruby
+    unless act.gsub!(/^proc \{ \|(\w+)\|\n/,
+                     "  \\1 = Struct.new(:name).new(#{name.inspect}) # A crude mock Rake::Task object\n")
+      act.gsub!(/^proc \{\n/, '')
+    end
+    act.gsub(/\n\}$/, '')
+  end.join("\n")
+
+  meth << "\nend"
+
+  if file_task
+    @private_methods << meth
+    return
+  end
+
+  meth
+end
+
+body = Rake::Task.tasks.map(&method(:method_for_task)).compact.map { |meth| meth.gsub(/^/, '  ') }.join("\n\n")
+
+unless @private_methods.empty?
+  body << "\n\n  private\n\n"
+  body << @private_methods.map { |meth| meth.gsub(/^/, '  ') }.join("\n\n")
+end
+
+requires = $requires.map { |r| "require #{r.inspect}" }.join("\n")
+
+File.open(output, 'w') { |f| f.write(<<END.lstrip) }
+#{requires}
+
+class Default < Thor
+#{body}
+end
+END

data/bin/thor

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

data/lib/thor.rb

@@ -0,0 +1,229 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+require 'thor/base'
+require 'thor/group'
+require 'thor/actions'
+
+class Thor
+
+  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
+        @usage, @desc = usage, description
+      end
+    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
+
+      @map
+    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 :optional, :required, :boolean or :numeric.
+    #
+    def method_options(options=nil)
+      @method_options ||= Thor::CoreExt::OrderedHash.new
+      build_options(options, @method_options) if options
+      @method_options
+    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>:: The description, type, default value, aliases and if this option is required or not.
+    #                 The type can be :string, :boolean, :numeric, :hash or :array. If none is given
+    #                 a default type which accepts both (--name and --name=NAME) entries is assumed.
+    #
+    def method_option(name, options)
+      scope = if options[:for]
+        find_and_refresh_task(options[:for]).options
+      else
+        method_options
+      end
+
+      build_option(name, options, scope)
+    end
+
+    # 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(args=ARGV, config={})
+      config[:shell] ||= Thor::Base.shell.new
+
+      meth = normalize_task_name(args.shift)
+      task = self[meth]
+
+      options = class_options.merge(task.options)
+      opts = Thor::Options.new(options)
+      opts.parse(args)
+
+      instance = new(opts.arguments, opts.options, config)
+      instance.invoke(task.name, *opts.trailing)
+    rescue Thor::Error => e
+      config[:shell].error e.message
+    end
+
+    # 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)
+      namespace = options[:namespace] ? self : nil
+
+      if meth
+        task = self.all_tasks[meth]
+        raise UndefinedTaskError, "task '#{meth}' could not be found in namespace '#{self.namespace}'" unless task
+
+        shell.say "Usage:"
+        shell.say "  #{task.formatted_usage(namespace)}"
+        shell.say
+        options_help(shell)
+        shell.say task.description
+      else
+        if options[:short]
+          list = self.tasks.map do |_, task|
+            [ task.formatted_usage(namespace), task.short_description || '' ]
+          end
+
+          shell.print_table(list, :emphasize_last => true)
+        else
+          options_help(shell)
+
+          list = self.all_tasks.map do |_, task|
+            [ task.formatted_usage(namespace), task.short_description || '' ]
+          end
+
+          shell.say "Tasks:"
+          shell.print_table(list, :ident => 2, :emphasize_last => true)
+        end
+      end
+    end
+
+    protected
+
+      def baseclass #:nodoc:
+        Thor
+      end
+
+      def valid_task?(meth) #:nodoc:
+        public_instance_methods.include?(meth) && @usage && @desc
+      end
+
+      def create_task(meth) #:nodoc:
+        tasks[meth.to_s] = Thor::Task.new(meth, @desc, @usage, method_options)
+        @usage, @desc, @method_options = nil
+      end
+
+      def initialize_added #:nodoc:
+        class_options.merge!(method_options)
+        @method_options = nil
+      end
+
+      # 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
+
+      def options_help(shell) #:nodoc:
+        unless self.class_options.empty?
+          list = self.class_options.map do |_, option|
+            [ option.usage, option.description || '' ]
+          end
+
+          shell.say "Global arguments:"
+          shell.print_table(list, :emphasize_last => true, :ident => 2)
+          shell.say ""
+        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