Thor::Actions

Attributes

behavior[RW]

(Not documented)

Public Class Methods

new(args=[], options={}, config={}) click to toggle source

Extends initializer to add more configuration options.

Configuration

behavior:The actions default behavior. Can be :invoke or :revoke. It also accepts :force, :skip and :pretend to set the behavior and the respective option.
destination_root:The root directory needed for some actions.
    # File lib/thor/actions.rb, line 64
64:     def initialize(args=[], options={}, config={})
65:       self.behavior = case config[:behavior].to_s
66:         when "force", "skip"
67:           _cleanup_options_and_set(options, config[:behavior])
68:           :invoke
69:         when "revoke"
70:           :revoke
71:         else
72:           :invoke
73:       end
74: 
75:       super
76:       self.destination_root = config[:destination_root]
77:     end

Public Instance Methods

add_file(destination, data=nil, config={}, &block) click to toggle source

Alias for create_file

append_file(path, *args, &block) click to toggle source

Append text to a file. Since it depends on inject_into_file, it’s reversible.

Parameters

path:path of the file to be changed
data:the data to append to the file, can be also given as a block.
config:give :verbose => false to not log the status.

Example

  append_file 'config/environments/test.rb', 'config.gem "rspec"'

  append_file 'config/environments/test.rb' do
    'config.gem "rspec"'
  end
     # File lib/thor/actions/file_manipulation.rb, line 139
139:     def append_file(path, *args, &block)
140:       config = args.last.is_a?(Hash) ? args.pop : {}
141:       config.merge!(:before => /\z/)
142:       inject_into_file(path, *(args << config), &block)
143:     end
apply(path, config={}) click to toggle source

Loads an external file and execute it in the instance binding.

Parameters

path:The path to the file to execute. Can be a web address or a relative path from the source root.

Examples

  apply "http://gist.github.com/103208"

  apply "recipes/jquery.rb"
     # File lib/thor/actions.rb, line 176
176:     def apply(path, config={})
177:       verbose = config.fetch(:verbose, true)
178:       path    = find_in_source_paths(path) unless path =~ /^http\:\/\//
179: 
180:       say_status :apply, path, verbose
181:       shell.padding += 1 if verbose
182:       instance_eval(open(path).read)
183:       shell.padding -= 1 if verbose
184:     end
chmod(path, mode, config={}) click to toggle source

Changes the mode of the given file or directory.

Parameters

mode:the file mode
path:the name of the file to change mode
config:give :verbose => false to not log the status.

Example

  chmod "script/*", 0755
     # File lib/thor/actions/file_manipulation.rb, line 96
 96:     def chmod(path, mode, config={})
 97:       return unless behavior == :invoke
 98:       path = File.expand_path(path, destination_root)
 99:       say_status :chmod, relative_to_original_destination_root(path), config.fetch(:verbose, true)
100:       FileUtils.chmod_R(mode, path) unless options[:pretend]
101:     end
copy_file(source, destination=nil, config={}) click to toggle source

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:the relative path to the source root.
destination:the relative path to the destination root.
config:give :verbose => false to not log the status.

Examples

  copy_file "README", "doc/README"

  copy_file "doc/README"
    # File lib/thor/actions/file_manipulation.rb, line 21
21:     def copy_file(source, destination=nil, config={})
22:       destination ||= source
23:       source = File.expand_path(find_in_source_paths(source.to_s))
24: 
25:       create_file destination, nil, config do
26:         File.read(source)
27:       end
28:     end
create_file(destination, data=nil, config={}, &block) click to toggle source

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:the relative path to the destination root.
data:the data to append to the file.
config:give :verbose => false to not log the status.

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"
    # File lib/thor/actions/create_file.rb, line 23
23:     def create_file(destination, data=nil, config={}, &block)
24:       action CreateFile.new(self, destination, block || data.to_s, config)
25:     end
Also aliased as: add_file
destination_root() click to toggle source

Returns the root for this thor class (also aliased as destination root).

    # File lib/thor/actions.rb, line 91
91:     def destination_root
92:       @destination_stack.last
93:     end
destination_root=(root) click to toggle source

Sets the root for this thor class. Relatives path are added to the directory where the script was invoked and expanded.

     # File lib/thor/actions.rb, line 98
 98:     def destination_root=(root)
 99:       @destination_stack ||= []
100:       @destination_stack[0] = File.expand_path(root || '')
101:     end
directory(source, destination=nil, config={}) click to toggle source

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 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:the relative path to the source root.
destination:the relative path to the destination root.
config:give :verbose => false to not log the status. If :recursive => false, does not look for paths recursively.

Examples

  directory "doc"
  directory "doc", "docs", :recursive => false
    # File lib/thor/actions/directory.rb, line 43
43:     def directory(source, destination=nil, config={})
44:       action Directory.new(self, source, destination || source, config)
45:     end
empty_directory(destination, config={}) click to toggle source

Creates an empty directory.

Parameters

destination:the relative path to the destination root.
config:give :verbose => false to not log the status.

Examples

  empty_directory "doc"
    # File lib/thor/actions/empty_directory.rb, line 14
14:     def empty_directory(destination, config={})
15:       action EmptyDirectory.new(self, destination, config)
16:     end
find_in_source_paths(file) click to toggle source

Receives a file or directory and search for it in the source paths.

     # File lib/thor/actions.rb, line 119
119:     def find_in_source_paths(file)
120:       relative_root = relative_to_original_destination_root(destination_root, false)
121: 
122:       source_paths.each do |source|
123:         source_file = File.expand_path(file, File.join(source, relative_root))
124:         return source_file if File.exists?(source_file)
125:       end
126: 
127:       if source_paths.empty?
128:         raise Error, "You don't have any source path defined for class #{self.class.name}. To fix this, " <<
129:                      "you can define a source_root in your class."
130:       else
131:         raise Error, "Could not find #{file.inspect} in source paths."
132:       end
133:     end
get(source, destination=nil, config={}, &block) click to toggle source

Gets the content at the given address and places it at the given relative destination. If a block is given instead of destination, the content of the url is yielded and used as location.

Parameters

source:the address of the given content.
destination:the relative path to the destination root.
config:give :verbose => false to not log the status.

Examples

  get "http://gist.github.com/103208", "doc/README"

  get "http://gist.github.com/103208" do |content|
    content.split("\n").first
  end
    # File lib/thor/actions/file_manipulation.rb, line 47
47:     def get(source, destination=nil, config={}, &block)
48:       source = File.expand_path(find_in_source_paths(source.to_s)) unless source =~ /^http\:\/\//
49:       render = open(source).read
50: 
51:       destination ||= if block_given?
52:         block.arity == 1 ? block.call(render) : block.call
53:       else
54:         File.basename(source)
55:       end
56: 
57:       create_file destination, render, config
58:     end
gsub_file(path, flag, *args, &block) click to toggle source

Run a regular expression replacement on a file.

Parameters

path:path of the file to be changed
flag:the regexp or string to be replaced
replacement:the replacement, can be also given as a block
config:give :verbose => false to not log the status.

Example

  gsub_file 'app/controllers/application_controller.rb', /#\s*(filter_parameter_logging :password)/, '\1'

  gsub_file 'README', /rake/, :green do |match|
    match << " no more. Use thor!"
  end
     # File lib/thor/actions/file_manipulation.rb, line 184
184:     def gsub_file(path, flag, *args, &block)
185:       return unless behavior == :invoke
186:       config = args.last.is_a?(Hash) ? args.pop : {}
187: 
188:       path = File.expand_path(path, destination_root)
189:       say_status :gsub, relative_to_original_destination_root(path), config.fetch(:verbose, true)
190: 
191:       unless options[:pretend]
192:         content = File.read(path)
193:         content.gsub!(flag, *args, &block)
194:         File.open(path, 'wb') { |file| file.write(content) }
195:       end
196:     end
in_root() click to toggle source

Goes to the root and execute the given block.

     # File lib/thor/actions.rb, line 160
160:     def in_root
161:       inside(@destination_stack.first) { yield }
162:     end
inject_into_class(path, klass, *args, &block) click to toggle source

Injects text right after the class definition. Since it depends on inject_into_file, it’s reversible.

Parameters

path:path of the file to be changed
klass:the class to be manipulated
data:the data to append to the class, can be also given as a block.
config:give :verbose => false to not log the status.

Examples

  inject_into_class "app/controllers/application_controller.rb", "  filter_parameter :password\n"

  inject_into_class "app/controllers/application_controller.rb", ApplicationController do
    "  filter_parameter :password\n"
  end
     # File lib/thor/actions/file_manipulation.rb, line 162
162:     def inject_into_class(path, klass, *args, &block)
163:       config = args.last.is_a?(Hash) ? args.pop : {}
164:       config.merge!(:after => /class #{klass}\n|class #{klass} .*\n/)
165:       inject_into_file(path, *(args << config), &block)
166:     end
inject_into_file(destination, *args, &block) click to toggle source

Injects the given content into a file. Different from gsub_file, this method is reversible.

Parameters

destination:Relative path to the destination root
data:Data to add to the file. Can be given as a block.
config:give :verbose => false to not log the status and the flag for injection (:after or :before).

Examples

  inject_into_file "config/environment.rb", "config.gem :thor", :after => "Rails::Initializer.run do |config|\n"

  inject_into_file "config/environment.rb", :after => "Rails::Initializer.run do |config|\n" do
    gems = ask "Which gems would you like to add?"
    gems.split(" ").map{ |gem| "  config.gem :#{gem}" }.join("\n")
  end
    # File lib/thor/actions/inject_into_file.rb, line 24
24:     def inject_into_file(destination, *args, &block)
25:       if block_given?
26:         data, config = block, args.shift
27:       else
28:         data, config = args.shift, args.shift
29:       end
30:       action InjectIntoFile.new(self, destination, data, config)
31:     end
inside(dir='', config={}, &block) click to toggle source

Do something in the root or on a provided subfolder. If a relative path is given it’s referenced from the current root. The full path is yielded to the block you provide. The path is set back to the previous path when the method exits.

Parameters

dir:the directory to move to.
config:give :verbose => true to log and use padding.
     # File lib/thor/actions.rb, line 144
144:     def inside(dir='', config={}, &block)
145:       verbose = config.fetch(:verbose, false)
146: 
147:       say_status :inside, dir, verbose
148:       shell.padding += 1 if verbose
149:       @destination_stack.push File.expand_path(dir, destination_root)
150: 
151:       FileUtils.mkdir_p(destination_root) unless File.exist?(destination_root)
152:       FileUtils.cd(destination_root) { block.arity == 1 ? yield(destination_root) : yield }
153: 
154:       @destination_stack.pop
155:       shell.padding -= 1 if verbose
156:     end
prepend_file(path, *args, &block) click to toggle source

Prepend text to a file. Since it depends on inject_into_file, it’s reversible.

Parameters

path:path of the file to be changed
data:the data to prepend to the file, can be also given as a block.
config:give :verbose => false to not log the status.

Example

  prepend_file 'config/environments/test.rb', 'config.gem "rspec"'

  prepend_file 'config/environments/test.rb' do
    'config.gem "rspec"'
  end
     # File lib/thor/actions/file_manipulation.rb, line 118
118:     def prepend_file(path, *args, &block)
119:       config = args.last.is_a?(Hash) ? args.pop : {}
120:       config.merge!(:after => /\A/)
121:       inject_into_file(path, *(args << config), &block)
122:     end
relative_to_original_destination_root(path, remove_dot=true) click to toggle source

Returns the given path relative to the absolute root (ie, root where the script started).

     # File lib/thor/actions.rb, line 106
106:     def relative_to_original_destination_root(path, remove_dot=true)
107:       path = path.gsub(@destination_stack[0], '.')
108:       remove_dot ? (path[2..-1] || '') : path
109:     end
remove_dir(path, config={}) click to toggle source

Alias for remove_file

remove_file(path, config={}) click to toggle source

Removes a file at the given location.

Parameters

path:path of the file to be changed
config:give :verbose => false to not log the status.

Example

  remove_file 'README'
  remove_file 'app/controllers/application_controller.rb'
     # File lib/thor/actions/file_manipulation.rb, line 209
209:     def remove_file(path, config={})
210:       return unless behavior == :invoke
211:       path  = File.expand_path(path, destination_root)
212: 
213:       say_status :remove, relative_to_original_destination_root(path), config.fetch(:verbose, true)
214:       ::FileUtils.rm_rf(path) if !options[:pretend] && File.exists?(path)
215:     end
Also aliased as: remove_dir
run(command, config={}) click to toggle source

Executes a command.

Parameters

command:the command to be executed.
config:give :verbose => false to not log the status. Specify :with to append an executable to command executation.

Example

  inside('vendor') do
    run('ln -s ~/edge rails')
  end
     # File lib/thor/actions.rb, line 199
199:     def run(command, config={})
200:       return unless behavior == :invoke
201: 
202:       destination = relative_to_original_destination_root(destination_root, false)
203:       desc = "#{command} from #{destination.inspect}"
204: 
205:       if config[:with]
206:         desc = "#{File.basename(config[:with].to_s)} #{desc}"
207:         command = "#{config[:with]} #{command}"
208:       end
209: 
210:       say_status :run, desc, config.fetch(:verbose, true)
211:       system(command) unless options[:pretend]
212:     end
run_ruby_script(command, config={}) click to toggle source

Executes a ruby script (taking into account WIN32 platform quirks).

Parameters

command:the command to be executed.
config:give :verbose => false to not log the status.
     # File lib/thor/actions.rb, line 220
220:     def run_ruby_script(command, config={})
221:       return unless behavior == :invoke
222:       run "#{command}", config.merge(:with => Thor::Util.ruby_command)
223:     end
source_paths() click to toggle source

Holds source paths in instance so they can be manipulated.

     # File lib/thor/actions.rb, line 113
113:     def source_paths
114:       @source_paths ||= self.class.source_paths_for_search
115:     end
template(source, destination=nil, config={}) click to toggle source

Gets an ERB template at the relative source, executes it and makes a copy at the relative destination. If the destination is not given it’s assumed to be equal to the source removing .tt from the filename.

Parameters

source:the relative path to the source root.
destination:the relative path to the destination root.
config:give :verbose => false to not log the status.

Examples

  template "README", "doc/README"

  template "doc/README"
    # File lib/thor/actions/file_manipulation.rb, line 75
75:     def template(source, destination=nil, config={})
76:       destination ||= source
77:       source  = File.expand_path(find_in_source_paths(source.to_s))
78:       context = instance_eval('binding')
79: 
80:       create_file destination, nil, config do
81:         ERB.new(::File.read(source), nil, '-').result(context)
82:       end
83:     end
thor(task, *args) click to toggle source

Run a thor command. A hash of options can be given and it’s converted to switches.

Parameters

task:the task to be invoked
args:arguments to the task
config:give :verbose => false to not log the status. Other options are given as parameter to Thor.

Examples

  thor :install, "http://gist.github.com/103208"
  #=> thor install http://gist.github.com/103208

  thor :list, :all => true, :substring => 'rails'
  #=> thor list --all --substring=rails
     # File lib/thor/actions.rb, line 242
242:     def thor(task, *args)
243:       config  = args.last.is_a?(Hash) ? args.pop : {}
244:       verbose = config.key?(:verbose) ? config.delete(:verbose) : true
245: 
246:       args.unshift task
247:       args.push Thor::Options.to_switches(config)
248:       command = args.join(' ').strip
249: 
250:       run command, :with => :thor, :verbose => verbose
251:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.