README.rdoc @@ -1,3 +1,4 @@ /pkg /coverage /spec/sandbox +/rdoc .gitignore @@ -2,6 +2,9 @@ require 'rubygems' require 'rubygems/specification' require 'thor/tasks' +require 'rubygems' +require 'rdoc/rdoc' + GEM = "thor" GEM_VERSION = "0.11.3" AUTHOR = "Yehuda Katz" @@ -30,6 +33,8 @@ SPEC = Gem::Specification.new do |s| end class Default < Thor + include Thor::Actions + # Set up standard Thortasks spec_task(Dir["spec/**/*_spec.rb"]) spec_task(Dir["spec/**/*_spec.rb"], :name => "rcov", :rcov => {:exclude => %w(spec task.thor Thorfile)}) @@ -37,8 +42,30 @@ class Default < Thor desc "gemspec", "make a gemspec file" def gemspec - File.open("#{GEM}.gemspec", "w") do |file| - file.puts SPEC.to_ruby - end + create_file "#{GEM}.gemspec", SPEC.to_ruby, :force => true + end + + desc "rdoc PATH", "generate rdoc for the path passed as an argument" + def rdoc(path=File.dirname(__FILE__)) + path = File.expand_path(path) + readme = File.join(path, "README.rdoc") + + destination = File.join(Dir.pwd, 'rdoc') + remove_dir(destination) + + # get all the files to process + files = Dir.glob("#{path}/lib/**/*.rb") + files += ["#{path}/README.rdoc", "#{path}/CHANGELOG.rdoc", "#{path}/LICENSE"] + + # rdoc args + project = File.basename(path) + arguments = [ + "-t", project, + "-m", readme, + "--op", destination + ] + + say_status :rdoc, "#{project} (#{files.size} files) to: #{destination}" + RDoc::RDoc.new.document(arguments + files) end end Thorfile @@ -187,11 +187,11 @@ class Thor protected # The banner for this class. You can customize it if you are invoking the - # thor class by another means which is not the Thor::Runner. It receives - # the task that is going to be invoked and if the namespace should be - # displayed. + # 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) #:nodoc: + def banner(task, namespace=true) task.formatted_usage(self, namespace) end lib/thor.rb @@ -58,8 +58,7 @@ class Thor # It also accepts :force, :skip and :pretend to set the behavior # and the respective option. # - # destination_root<String>:: The root directory needed for some actions. It's also known - # as destination root. + # destination_root<String>:: The root directory needed for some actions. # def initialize(args=[], options={}, config={}) self.behavior = case config[:behavior].to_s @@ -78,7 +77,7 @@ class Thor # Wraps an action object and call it accordingly to the thor class behavior. # - def action(instance) + def action(instance) #:nodoc: if behavior == :revoke instance.revoke! else lib/thor/actions.rb @@ -3,7 +3,7 @@ require 'thor/actions/empty_directory' class Thor module Actions - # Copies interactively the files from source directory to root directory. + # Copies recursively 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 lib/thor/actions/directory.rb @@ -34,7 +34,7 @@ class Thor action InjectIntoFile.new(self, destination, data, config) end - class InjectIntoFile < EmptyDirectory + class InjectIntoFile < EmptyDirectory #:nodoc: attr_reader :flag, :replacement def initialize(base, destination, data, config) lib/thor/actions/inject_into_file.rb @@ -78,7 +78,6 @@ class Thor # Whenever a class inherits from Thor or Thor::Group, we should track the # class and the file on Thor::Base. This is the method responsable for it. - # Also adds the source root to the source paths if the klass respond to it. # def register_klass_file(klass) #:nodoc: file = caller[1].match(/(.*):\d+/)[1] @@ -246,7 +245,8 @@ class Thor # Returns the tasks for this Thor class. # # ==== Returns - # OrderedHash:: An ordered hash with this class tasks. + # OrderedHash:: An ordered hash with tasks names as keys and Thor::Task + # objects as values. # def tasks @tasks ||= Thor::CoreExt::OrderedHash.new @@ -255,7 +255,8 @@ class Thor # Returns the tasks for this Thor class and all subclasses. # # ==== Returns - # OrderedHash + # OrderedHash:: An ordered hash with tasks names as keys and Thor::Task + # objects as values. # def all_tasks @all_tasks ||= from_superclass(:all_tasks, Thor::CoreExt::OrderedHash.new) @@ -342,7 +343,7 @@ class Thor # Default way to start generators from the command line. # - def start(given_args=ARGV, config={}) #:nodoc: + def start(given_args=ARGV, config={}) config[:shell] ||= Thor::Base.shell.new yield rescue Thor::Error => e @@ -360,7 +361,7 @@ class Thor # hooks to add extra options, one of them if the third argument called # extra_group that should be a hash in the format :group => Array[Options]. # - # The second is by returning a lamda used to print values. The lambda + # The second is by returning a lambda used to print values. The lambda # requires two options: the group name and the array of options. # def class_options_help(shell, ungrouped_name=nil, extra_group=nil) #:nodoc: @@ -377,24 +378,14 @@ class Thor options.each do |option| item = [ option.usage(padding) ] - - item << if option.description - "# #{option.description}" - else - "" - end + item.push(option.description ? "# #{option.description}" : "") list << item list << [ "", "# Default: #{option.default}" ] if option.show_default? end unless list.empty? - if group_name - shell.say "#{group_name} options:" - else - shell.say "Options:" - end - + shell.say(group_name ? "#{group_name} options:" : "Options:") shell.print_table(list, :ident => 2) shell.say "" end @@ -412,7 +403,7 @@ class Thor # Raises an error if the word given is a Thor reserved word. # - def is_thor_reserved_word?(word, type) + def is_thor_reserved_word?(word, type) #:nodoc: return false unless THOR_RESERVED_WORDS.include?(word.to_s) raise "#{word.inspect} is a Thor reserved word and cannot be defined as #{type}" end @@ -423,7 +414,7 @@ class Thor # name<Symbol>:: The name of the argument. # options<Hash>:: Described in both class_option and method_option. # - def build_option(name, options, scope) + 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]) @@ -437,7 +428,7 @@ class Thor # ==== Parameters # Hash[Symbol => Object] # - def build_options(options, scope) + def build_options(options, scope) #:nodoc: options.each do |key, value| scope[key] = Thor::Option.parse(key, value) end @@ -447,7 +438,7 @@ class Thor # class, just return it, otherwise dup it and add the fresh copy to the # current task hash. # - def find_and_refresh_task(name) + def find_and_refresh_task(name) #:nodoc: task = if task = tasks[name.to_s] task elsif task = all_tasks[name.to_s] @@ -465,7 +456,7 @@ class Thor end # Fire this callback whenever a method is added. Added methods are - # tracked as tasks if the requirements set by valid_task? are valid. + # tracked as tasks by invoking the create_task method. # def method_added(meth) meth = meth.to_s @@ -486,7 +477,7 @@ class Thor end # Retrieves a value from superclass. If it reaches the baseclass, - # returns nil. + # returns default. # def from_superclass(method, default=nil) if self == baseclass || !superclass.respond_to?(method, true) lib/thor/base.rb @@ -1,5 +1,5 @@ class Thor - module CoreExt + module CoreExt #:nodoc: # A hash with indifferent access and magic predicates. # @@ -9,7 +9,7 @@ class Thor # hash['foo'] #=> 'bar' # hash.foo? #=> true # - class HashWithIndifferentAccess < ::Hash + class HashWithIndifferentAccess < ::Hash #:nodoc: def initialize(hash={}) super() lib/thor/core_ext/hash_with_indifferent_access.rb @@ -1,6 +1,4 @@ -require 'forwardable' - -class Thor #:nodoc: +class Thor module CoreExt #:nodoc: if RUBY_VERSION >= '1.9' lib/thor/core_ext/ordered_hash.rb @@ -1,27 +1,27 @@ class Thor - # Thor::Error is raised when it's caused by the user invoking the task and - # only errors that inherit from it are rescued. + # Thor::Error is raised when it's caused by wrong usage of thor classes. Those + # errors have their backtrace supressed and are nicely shown to the user. # - # So, for example, if the developer declares a required argument after an - # option, it should raise an ::ArgumentError and not ::Thor::ArgumentError, - # because it was caused by the developer and not the "final user". + # Errors that are caused by the developer, like declaring a method which + # overwrites a thor keyword, it SHOULD NOT raise a Thor::Error. This way, we + # ensure that developer errors are shown with full backtrace. # - class Error < StandardError #:nodoc: + class Error < StandardError end # Raised when a task was not found. # - class UndefinedTaskError < Error #:nodoc: + class UndefinedTaskError < Error end # Raised when a task was found, but not invoked properly. # - class InvocationError < Error #:nodoc: + class InvocationError < Error end - class RequiredArgumentMissingError < InvocationError #:nodoc: + class RequiredArgumentMissingError < InvocationError end - class MalformattedArgumentError < InvocationError #:nodoc: + class MalformattedArgumentError < InvocationError end end lib/thor/error.rb @@ -221,9 +221,9 @@ class Thor::Group protected # The banner for this class. You can customize it if you are invoking the - # thor class by another means which is not the Thor::Runner. + # thor class by another ways which is not the Thor::Runner. # - def banner #:nodoc: + def banner "#{self.namespace} #{self.arguments.map {|a| a.usage }.join(' ')}" end @@ -244,7 +244,7 @@ class Thor::Group # Shortcut to invoke with padding and block handling. Use internally by # invoke and invoke_from_option class methods. # - def _invoke_for_class_method(klass, task=nil, *args, &block) + def _invoke_for_class_method(klass, task=nil, *args, &block) #:nodoc: shell.padding += 1 result = if block_given? lib/thor/group.rb @@ -96,20 +96,8 @@ class Thor task, args, opts, config = nil, task, args, opts if task.nil? || task.is_a?(Array) args, opts, config = nil, args, opts if args.is_a?(Hash) - object, task = _prepare_for_invocation(name, task) - if object.is_a?(Class) - klass = object - - stored_args, stored_opts, stored_config = @_initializer - args ||= stored_args.dup - opts ||= stored_opts.dup - - config ||= {} - config = stored_config.merge(_shared_configuration).merge!(config) - instance = klass.new(args, opts, config) - else - klass, instance = object.class, object - end + object, task = _prepare_for_invocation(name, task) + klass, instance = _initialize_klass_with_initializer(object, args, opts, config) method_args = [] current = @_invocations[klass] @@ -134,7 +122,7 @@ class Thor # Configuration values that are shared between invocations. # - def _shared_configuration + def _shared_configuration #:nodoc: { :invocations => @_invocations } end @@ -154,13 +142,13 @@ class Thor # If the object was not set, use self and use the name as task. object, task = self, name unless object - return object, _validate_klass_and_task(object, task) + return object, _validate_task(object, task) end # Check if the object given is a Thor class object and get a task object # for it. # - def _validate_klass_and_task(object, task) #:nodoc: + def _validate_task(object, task) #:nodoc: klass = object.is_a?(Class) ? object : object.class raise "Expected Thor class, got #{klass}" unless klass <= Thor::Base @@ -168,5 +156,23 @@ class Thor task = klass.all_tasks[task.to_s] || Task.dynamic(task) if task && !task.is_a?(Thor::Task) task end + + # Initialize klass using values stored in the @_initializer. + # + def _initialize_klass_with_initializer(object, args, opts, config) #:nodoc: + if object.is_a?(Class) + klass = object + + stored_args, stored_opts, stored_config = @_initializer + args ||= stored_args.dup + opts ||= stored_opts.dup + + config ||= {} + config = stored_config.merge(_shared_configuration).merge!(config) + [ klass, klass.new(args, opts, config) ] + else + [ object.class, object ] + end + end end end lib/thor/invocation.rb @@ -1,5 +1,5 @@ class Thor - class Argument + class Argument #:nodoc: VALID_TYPES = [ :numeric, :hash, :array, :string ] attr_reader :name, :description, :required, :type, :default, :banner lib/thor/parser/argument.rb @@ -1,5 +1,5 @@ class Thor - class Arguments + class Arguments #:nodoc: NUMERIC = /(\d*\.\d+|\d+)/ # Receives an array of args and returns two arrays, one with arguments lib/thor/parser/arguments.rb @@ -1,5 +1,5 @@ class Thor - class Option < Argument + class Option < Argument #:nodoc: attr_reader :aliases, :group VALID_TYPES = [:boolean, :numeric, :hash, :array, :string] lib/thor/parser/option.rb @@ -2,7 +2,7 @@ class Thor # This is a modified version of Daniel Berger's Getopt::Long class, licensed # under Ruby's license. # - class Options < Arguments + class Options < Arguments #:nodoc: LONG_RE = /^(--\w+[-\w+]*)$/ SHORT_RE = /^(-[a-z])$/i EQ_RE = /^(--\w+[-\w+]*|-[a-z])=(.*)$/i lib/thor/parser/options.rb @@ -4,7 +4,7 @@ require 'yaml' require 'digest/md5' require 'pathname' -class Thor::Runner < Thor +class Thor::Runner < Thor #:nodoc: map "-T" => :list, "-i" => :install, "-u" => :update # Override Thor#help so it can give information about any class and any method. lib/thor/runner.rb @@ -64,7 +64,7 @@ class Thor # Allow shell to be shared between invocations. # - def _shared_configuration + def _shared_configuration #:nodoc: super.merge!(:shell => self.shell) end lib/thor/shell.rb @@ -11,9 +11,9 @@ class Thor @base, @padding = nil, 0 end - # Do not allow padding to be less than zero. + # Sets the output padding, not allowing less than zero values. # - def padding=(value) #:nodoc: + def padding=(value) @padding = [0, value].max end @@ -52,7 +52,7 @@ class Thor # in log_status, avoiding the message from being shown. If a Symbol is # given in log_status, it's used as the color. # - def say_status(status, message, log_status=true) #:nodoc: + def say_status(status, message, log_status=true) return if quiet? || log_status == false spaces = " " * (padding + 1) color = log_status.is_a?(Symbol) ? log_status : :green @@ -103,7 +103,6 @@ class Thor # # ==== Options # ident<Integer>:: Ident the first column by ident value. - # emphasize_last<Boolean>:: When true, add a different behavior to the last column. # def print_table(table, options={}) return if table.empty? @@ -131,7 +130,7 @@ class Thor # # ==== Parameters # destination<String>:: the destination file to solve conflicts - # block<Proc>:: an optional proc that returns the value to be used in diff + # block<Proc>:: an optional block that returns the value to be used in diff # def file_collision(destination) return true if @always_force @@ -164,19 +163,20 @@ class Thor # wrong, you can always raise an exception. If you raise a Thor::Error, it # will be rescued and wrapped in the method below. # - def error(statement) #:nodoc: + def error(statement) $stderr.puts statement end - # Apply color to the given string with optional bold. + # Apply color to the given string with optional bold. Disabled in the + # Thor::Shell::Basic class. # - def set_color(string, color, bold=false) + def set_color(string, color, bold=false) #:nodoc: string end protected - def is?(value) + def is?(value) #:nodoc: value = value.to_s if value.size == 1 @@ -186,7 +186,7 @@ class Thor end end - def file_collision_help + def file_collision_help #:nodoc: <<HELP Y - yes, overwrite n - no, do not overwrite @@ -197,7 +197,7 @@ h - help, show this help HELP end - def show_diff(destination, content) + def show_diff(destination, content) #:nodoc: diff_cmd = ENV['THOR_DIFF'] || ENV['RAILS_DIFF'] || 'diff -u' Tempfile.open(File.basename(destination), File.dirname(destination)) do |temp| @@ -207,7 +207,7 @@ HELP end end - def quiet? + def quiet? #:nodoc: base && base.options[:quiet] end lib/thor/shell/basic.rb @@ -2,7 +2,8 @@ require 'thor/shell/basic' class Thor module Shell - # Set color in the output. Got color values from HighLine. + # Inherit from Thor::Shell::Basic and add set_color behavior. Check + # Thor::Shell::Basic to see all available methods. # class Color < Basic # Embed in a String to clear all previous ANSI sequences. @@ -44,9 +45,10 @@ class Thor # Set the terminal's background ANSI color to white. ON_WHITE = "\e[47m" - # Set color by using a string or one of the defined constants. Based - # on Highline implementation. CLEAR is automatically be embedded to - # the end of the returned String. + # Set color by using a string or one of the defined constants. If a third + # option is set to true, it also adds bold to the string. This is based + # on Highline implementation and it automatically appends CLEAR to the end + # of the returned String. # def set_color(string, color, bold=false) color = self.class.const_get(color.to_s.upcase) if color.is_a?(Symbol) @@ -59,7 +61,7 @@ class Thor # Overwrite show_diff to show diff with colors if Diff::LCS is # available. # - def show_diff(destination, content) + def show_diff(destination, content) #:nodoc: if diff_lcs_loaded? && ENV['THOR_DIFF'].nil? && ENV['RAILS_DIFF'].nil? actual = File.read(destination).to_s.split("\n") content = content.to_s.split("\n") @@ -72,7 +74,7 @@ class Thor end end - def output_diff_line(diff) + def output_diff_line(diff) #:nodoc: case diff.action when '-' say "- #{diff.old_element.chomp}", :red, true @@ -89,7 +91,7 @@ class Thor # Check if Diff::LCS is loaded. If it is, use it to create pretty output # for diff. # - def diff_lcs_loaded? + def diff_lcs_loaded? #:nodoc: return true if defined?(Diff::LCS) return @diff_lcs_loaded unless @diff_lcs_loaded.nil? lib/thor/shell/color.rb @@ -12,7 +12,7 @@ class Thor super(name.to_s, description, usage, options || {}) end - def initialize_copy(other) + def initialize_copy(other) #:nodoc: super(other) self.options = other.options.dup if other.options end @@ -67,20 +67,20 @@ class Thor # Given a target, checks if this class name is not a private/protected method. # - def public_method?(instance) + def public_method?(instance) #:nodoc: collection = instance.private_methods + instance.protected_methods !(collection).include?(name.to_s) && !(collection).include?(name.to_sym) # For Ruby 1.9 end # Clean everything that comes from the Thor gempath and remove the caller. # - def sans_backtrace(backtrace, caller) + def sans_backtrace(backtrace, caller) #:nodoc: dirname = /^#{Regexp.escape(File.dirname(__FILE__))}/ saned = backtrace.reject { |frame| frame =~ dirname } saned -= caller end - def parse_argument_error(instance, e, caller) + def parse_argument_error(instance, e, caller) #:nodoc: backtrace = sans_backtrace(e.backtrace, caller) if backtrace.empty? && e.message =~ /wrong number of arguments/ @@ -95,7 +95,7 @@ class Thor end end - def parse_no_method_error(instance, e) + def parse_no_method_error(instance, e) #:nodoc: if e.message =~ /^undefined method `#{name}' for #{Regexp.escape(instance.to_s)}$/ raise UndefinedTaskError, "The #{instance.class.namespace} namespace " << "doesn't have a '#{name}' task" lib/thor/task.rb @@ -12,7 +12,7 @@ class Thor tasks['install'] = Thor::InstallTask.new(spec, options) end - class InstallTask < Task + class InstallTask < Task #:nodoc: attr_accessor :spec, :config def initialize(gemspec, config={}) lib/thor/tasks/install.rb @@ -13,7 +13,7 @@ class Thor tasks['package'] = Thor::PackageTask.new(spec, options) end - class PackageTask < Task + class PackageTask < Task #:nodoc: attr_accessor :spec, :config def initialize(gemspec, config={}) lib/thor/tasks/package.rb @@ -15,12 +15,12 @@ class Thor # # All other options are added to rspec. # - def self.spec_task(files, options={}) + def self.spec_task(files, options={}) #:nodoc: name = (options.delete(:name) || 'spec').to_s tasks[name] = Thor::SpecTask.new(name, files, options) end - class SpecTask < Task + class SpecTask < Task #:nodoc: attr_accessor :name, :files, :rcov_dir, :rcov_config, :spec_config def initialize(name, files, config={}) lib/thor/tasks/spec.rb @@ -1,7 +1,8 @@ require 'rbconfig' class Thor - module Sandbox; end + module Sandbox #:nodoc: + end # This module holds several utilities: # @@ -214,7 +215,7 @@ class Thor # Return the path to the ruby interpreter taking into account multiple # installations and windows extensions. # - def self.ruby_command #:nodoc: + def self.ruby_command @ruby_command ||= begin ruby = File.join(Config::CONFIG['bindir'], Config::CONFIG['ruby_install_name']) ruby << Config::CONFIG['EXEEXT'] lib/thor/util.rb README.markdown c0bc615c1405503b8af1051a9c8541b1998a5fb0 José Valim jose.valim@gmail.com http://github.com/wycats/thor/commit/a6593858e36285263cd35d0a014ecabfc3c63e7c a6593858e36285263cd35d0a014ecabfc3c63e7c 2009-08-01T13:53:44-07:00 2009-08-01T13:53:44-07:00 Added rdoc task and checked if a good documentation will be generated. 515160de21086c4e27b58c40d56b1d68943c3ab6 José Valim jose.valim@gmail.com