thor 0.9.2 → 0.9.5

data/CHANGELOG.rdoc

@@ -0,0 +1,35 @@
+== 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.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/README.markdown

@@ -4,58 +4,73 @@ thor
 Map options to a class. Simply create a class with the appropriate annotations, and have options automatically map
 to functions and parameters.
 
-Examples:
+Example:
 
-    class MyApp
-      extend Hermes                                                           # [1]
-      
-      map "-L" => :list                                                       # [2]
-      
-      desc "install APP_NAME", "install one of the available apps"            # [3]
-      method_options :force => :boolean                                       # [4]
-      def install(name, opts)
-        ... code ...
-        if opts[:force]
+    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
     
-    MyApp.start
-    
-Hermes automatically maps commands as follows:
+Thor automatically maps commands as such:
 
-    app install name --force
+    app install myname --force
     
 That gets converted to:
 
-    MyApp.new.install("name", :force => true)
-  
-[1] Use `extend Hermes` to turn a class into an option mapper
+    MyApp.new.install("myname")
+    # with {'force' => true} as options hash
 
-[2] Map additional non-valid identifiers to specific methods. In this case,
+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,
+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.
+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>:boolean</dt>
-  <dd>true if the option is passed</dd>
-  <dt>:required</dt>
-  <dd>A key/value option that MUST be provided</dd>
-  <dt>:optional</dt>
-  <dd>A key/value option that MAY be provided</dd>
-</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>
+  <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

@@ -1,41 +1,6 @@
-require 'rubygems'
-require 'rake/gempackagetask'
-require 'rubygems/specification'
-require 'spec/rake/spectask'
-require 'date'
-
-GEM = "thor"
-GEM_VERSION = "0.9.2"
-AUTHOR = "Yehuda Katz"
-EMAIL = "wycats@gmail.com"
-HOMEPAGE = "http://yehudakatz.com"
-SUMMARY = "A gem that maps options to a class"
-
-spec = Gem::Specification.new do |s|
-  s.name = GEM
-  s.version = GEM_VERSION
-  s.platform = Gem::Platform::RUBY
-  s.has_rdoc = true
-  s.extra_rdoc_files = ["README.markdown", "LICENSE"]
-  s.summary = SUMMARY
-  s.description = s.summary
-  s.author = AUTHOR
-  s.email = EMAIL
-  s.homepage = HOMEPAGE
-    
-  s.require_path = 'lib'
-  s.autorequire = GEM
-  s.bindir = "bin"
-  s.executables = %w( thor )
-  s.files = %w(LICENSE README.markdown Rakefile) + Dir.glob("{bin,lib,specs}/**/*")
-end
-
-Rake::GemPackageTask.new(spec) do |pkg|
-  pkg.gem_spec = spec
-end
-
 task :default => :install
+
 desc "install the gem locally"
-task :install => [:package] do
-  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION} --no-rdoc --no-ri --no-update-sources}
-end
+task :install do
+  sh %{ruby "#{File.dirname(__FILE__)}/bin/thor" :install}
+end

data/bin/rake2thor

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'ruby2ruby'
+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

@@ -1,327 +1,7 @@
 #!/usr/bin/env ruby
+# -*- mode: ruby -*-
 
-require "thor"
-require "open-uri"
-require "fileutils"
-require "yaml"
-require "digest/md5"
-require "readline"
+require File.dirname(__FILE__) + "/../lib/thor"
+require 'thor/runner'
 
-module ObjectSpace
-  
-  class << self
-
-    # ==== Returns
-    # Array[Class]:: All the classes in the object space.
-    def classes
-      klasses = []
-      ObjectSpace.each_object(Class) {|o| klasses << o}
-      klasses
-    end
-  end
-  
-end
-
-class Thor::Util
-  
-  # @public
-  def self.constant_to_thor_path(str)
-    snake_case(str).squeeze(":")
-  end
-
-  # @public
-  def self.constant_from_thor_path(str)
-    make_constant(to_constant(str))
-  end
-
-  def self.to_constant(str)
-    str.gsub(/:(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
-  end
-
-  def self.constants_in_contents(str)
-    klasses = self.constants.dup
-    eval(str)
-    ret = self.constants - klasses
-    ret.each {|k| self.send(:remove_const, k)}
-    ret
-  end
-
-  private  
-  # @private
-  def self.make_constant(str)
-    list = str.split("::")
-    obj = Object
-    list.each {|x| obj = obj.const_get(x) }
-    obj
-  end
-  
-  # @private
-  def self.snake_case(str)
-    return str.downcase if str =~ /^[A-Z]+$/
-    str.gsub(/([A-Z]+)(?=[A-Z][a-z]?)|\B[A-Z]/, '_\&') =~ /_*(.*)/
-      return $+.downcase
-  end  
-  
-end
-
-class Thor::Runner < Thor
-  
-  def self.globs_for(path)
-    ["#{path}/Thorfile", "#{path}/*.thor", "#{path}/tasks/*.thor", "#{path}/lib/tasks/*.thor"]
-  end
-
-  def initialize_thorfiles(include_system = true)
-    thorfiles(include_system).each {|f| load f unless Thor.subclass_files.keys.include?(File.expand_path(f))}
-  end
-
-  map "-T" => :list, "-i" => :install, "-u" => :update
-  
-  desc "install NAME", "install a Thor file into your system tasks, optionally named for future updates"
-  method_options :as => :optional
-  def install(name, opts)
-    initialize_thorfiles
-    begin
-      contents = open(name).read
-    rescue OpenURI::HTTPError
-      puts "The URI you provided: `#{name}' was invalid"
-      return
-    rescue Errno::ENOENT
-      puts "`#{name}' is not a valid file"
-      return
-    end
-    
-    puts "Your Thorfile contains: "
-    puts contents
-    print "Do you wish to continue [y/N]? "
-    response = Readline.readline
-    
-    return unless response =~ /^\s*y/i
-    
-    constants = Thor::Util.constants_in_contents(contents)
-    
-    name = name =~ /\.thor$/ ? name : "#{name}.thor"
-    
-    as = opts["as"] || begin
-      first_line = contents.split("\n")[0]
-      (match = first_line.match(/\s*#\s*module:\s*([^\n]*)/)) ? match[1].strip : nil
-    end
-        
-    if !as
-      print "Please specify a name for #{name} in the system repository [#{name}]: "
-      as = Readline.readline
-      as = name if as.empty?
-    end
-    
-    FileUtils.mkdir_p thor_root
-    
-    yaml_file = File.join(thor_root, "thor.yml")
-    FileUtils.touch(yaml_file)
-    yaml = thor_yaml
-    
-    yaml[as] = {:filename => Digest::MD5.hexdigest(name + as), :location => name, :constants => constants}
-    
-    save_yaml(yaml)
-    
-    puts "Storing thor file in your system repository"
-    
-    File.open(File.join(thor_root, yaml[as][:filename] + ".thor"), "w") do |file|
-      file.puts contents
-    end
-  end
-  
-  desc "uninstall NAME", "uninstall a named Thor module"
-  def uninstall(name)
-    yaml = thor_yaml
-    unless yaml[name]
-      puts "There was no module by that name installed"
-      return
-    end
-    
-    puts "Uninstalling #{name}."
-    
-    file = File.join(thor_root, "#{yaml[name][:filename]}.thor")
-    File.delete(file)
-    yaml.delete(name)
-    save_yaml(yaml)
-    
-    puts "Done."
-  end
-  
-  desc "update NAME", "update a Thor file from its original location"
-  def update(name)
-    yaml = thor_yaml
-    if !yaml[name] || !yaml[name][:location]
-      puts "`#{name}' was not found in the system repository"
-    else
-      puts "Updating `#{name}' from #{yaml[name][:location]}"
-      install(yaml[name][:location], "as" => name)
-    end
-  end
-  
-  def installed
-    Dir["#{ENV["HOME"]}/.thor/**/*.thor"].each do |f|
-      load f unless Thor.subclass_files.keys.include?(File.expand_path(f))
-    end
-    display_klasses(true)
-  end
-  
-  desc "list [SEARCH]", "list the available thor tasks (--substring means SEARCH can be anywhere in the module)"
-  method_options :substring => :boolean
-  def list(search = "", options = {})
-    initialize_thorfiles
-    search = ".*#{search}" if options["substring"]
-    search = /^#{search}.*/i
-    
-    display_klasses(false, Thor.subclasses.select {|k| 
-      Thor::Util.constant_to_thor_path(k.name) =~ search})
-  end
-    
-  def method_missing(meth, *args)
-    initialize_thorfiles(false)
-    meth = meth.to_s
-    unless meth =~ /:/
-      puts "Thor tasks must contain a :"
-      return
-    end
-    
-    thor_klass = meth.split(":")[0...-1].join(":")
-    to_call = meth.split(":").last
-    
-    yaml = thor_yaml
-
-    klass_str = Thor::Util.to_constant(thor_klass)
-    files = yaml.inject([]) { |a,(k,v)| a << v[:filename] if v[:constants] && v[:constants].include?(klass_str); a }
-
-    unless files.empty?
-      files.each do |f|
-        load File.join(thor_root, "#{f}.thor")
-      end
-      klass = Thor::Util.constant_from_thor_path(thor_klass)
-    else
-      begin
-        klass = Thor::Util.constant_from_thor_path(thor_klass)
-      rescue
-        puts "There was no available namespace `#{thor_klass}'."
-        return      
-      end
-    end
-    
-    unless klass.ancestors.include?(Thor)
-      puts "`#{thor_klass}' is not a Thor module"
-      return
-    end
-        
-    ARGV.replace [to_call, *(args + ARGV)].compact
-    begin
-      klass.start
-    rescue ArgumentError
-      puts "You need to call #{to_call} as `#{klass.usage_for_method(to_call)}'"
-    rescue NoMethodError
-      puts "`#{to_call}' is not available in #{thor_klass}"
-    end
-  end
-  
-  private
-  def thor_root
-    File.join(ENV["HOME"], ".thor")
-  end
-  
-  def thor_yaml
-    yaml_file = File.join(thor_root, "thor.yml")
-    yaml = YAML.load_file(yaml_file) if File.exists?(yaml_file)
-    yaml || {}
-  end
-  
-  def save_yaml(yaml)
-    yaml_file = File.join(thor_root, "thor.yml")
-    File.open(yaml_file, "w") {|f| f.puts yaml.to_yaml }
-  end
-  
-  def display_klasses(with_modules = false, klasses = Thor.subclasses)
-    klasses = klasses - [Thor::Runner]
-    
-    if klasses.empty?
-      puts "No thorfiles available"
-      return
-    end
-    
-    if with_modules
-      yaml = thor_yaml
-      max_name = yaml.max {|(xk,xv),(yk,yv)| xk.size <=> yk.size }.first.size
-      
-      print "%-#{max_name + 4}s" % "Name"
-      puts "Modules"
-      print "%-#{max_name + 4}s" % "----"
-      puts "-------"
-      
-      yaml.each do |name, info|
-        print "%-#{max_name + 4}s" % name
-        puts info[:constants].map {|c| Thor::Util.constant_to_thor_path(c)}.join(", ")
-      end
-    
-      puts
-    end
-    
-    puts "Tasks"
-    puts "-----"
-    
-    # Calculate the largest base class name
-    max_base = klasses.max do |x,y| 
-      Thor::Util.constant_to_thor_path(x.name).size <=> Thor::Util.constant_to_thor_path(y.name).size
-    end.name.size
-    
-    # Calculate the size of the largest option description
-    max_left_item = klasses.max do |x,y| 
-      (x.help_list && x.help_list.max.usage + x.help_list.max.opt).to_i <=> 
-      (y.help_list && y.help_list.max.usage + y.help_list.max.opt).to_i
-    end
-    
-    max_left = max_left_item.help_list.max.usage + max_left_item.help_list.max.opt
-        
-    klasses.map {|k| k.help_list}.compact.each do |item|
-      display_tasks(item, max_base, max_left)
-    end    
-  end  
-  
-  def display_tasks(item, max_base, max_left)
-    base = Thor::Util.constant_to_thor_path(item.klass.name)
-    item.usages.each do |name, usage|
-      format_string = "%-#{max_left + max_base + 5}s"
-      print format_string %
-        "#{base}:#{item.usages.assoc(name).last} #{display_opts(item.opts.assoc(name) && item.opts.assoc(name).last)}"
-      puts item.descriptions.assoc(name).last
-    end    
-  end
-  
-  def display_opts(opts)
-    return "" unless opts
-    opts.map do |opt, val|
-      if val == true || val == "BOOLEAN"
-        "[#{opt}]"
-      elsif val == "REQUIRED"
-        opt + "=" + opt.gsub(/\-/, "").upcase
-      elsif val == "OPTIONAL"
-        "[" + opt + "=" + opt.gsub(/\-/, "").upcase + "]"
-      end
-    end.join(" ")
-  end  
-  
-  def thorfiles(include_system = true)
-    path = Dir.pwd
-    system_thorfiles = Dir["#{ENV["HOME"]}/.thor/**/*.thor"]
-    thorfiles = []
-    
-    # Look for Thorfile or *.thor in the current directory or a parent directory, until the root
-    while thorfiles.empty?
-      thorfiles = Dir[*Thor::Runner.globs_for(path)]
-      path = File.dirname(path)
-      break if path == "/"
-    end
-    thorfiles + (include_system ? system_thorfiles : [])
-  end
-    
-end
-
-unless defined?(Spec)
-  Thor::Runner.start
-end
+Thor::Runner.start