Thor::Actions

Attributes

output_buffer[RW]

behavior[RW]

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 72
72:     def initialize(args=[], options={}, config={})
73:       self.behavior = case config[:behavior].to_s
74:         when "force", "skip"
75:           _cleanup_options_and_set(options, config[:behavior])
76:           :invoke
77:         when "revoke"
78:           :revoke
79:         else
80:           :invoke
81:       end
82: 
83:       super
84:       self.destination_root = config[:destination_root]
85:     end

Public Instance Methods

add_file(destination, *args, &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 149
149:     def append_file(path, *args, &block)
150:       config = args.last.is_a?(Hash) ? args.pop : {}
151:       config.merge!(:before => /\z/)
152:       inject_into_file(path, *(args << config), &block)
153:     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 201
201:     def apply(path, config={})
202:       verbose = config.fetch(:verbose, true)
203:       is_uri  = path =~ /^https?\:\/\//
204:       path    = find_in_source_paths(path) unless is_uri
205: 
206:       say_status :apply, path, verbose
207:       shell.padding += 1 if verbose
208: 
209:       if is_uri
210:         contents = open(path, "Accept" => "application/x-thor-template") {|io| io.read }
211:       else
212:         contents = open(path) {|io| io.read }
213:       end
214: 
215:       instance_eval(contents, path)
216:       shell.padding -= 1 if verbose
217:     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 106
106:     def chmod(path, mode, config={})
107:       return unless behavior == :invoke
108:       path = File.expand_path(path, destination_root)
109:       say_status :chmod, relative_to_original_destination_root(path), config.fetch(:verbose, true)
110:       FileUtils.chmod_R(mode, path) unless options[:pretend]
111:     end

copy_file(source, *args, &block) 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, *args, &block)
22:       config = args.last.is_a?(Hash) ? args.pop : {}
23:       destination = args.first || source
24:       source = File.expand_path(find_in_source_paths(source.to_s))
25: 
26:       create_file destination, nil, config do
27:         content = File.binread(source)
28:         content = block.call(content) if block
29:         content
30:       end
31:     end

create_file(destination, *args, &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, *args, &block)
24:       config = args.last.is_a?(Hash) ? args.pop : {}
25:       data = args.first
26:       action CreateFile.new(self, destination, block || data.to_s, config)
27:     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 99
 99:     def destination_root
100:       @destination_stack.last
101:     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 106
106:     def destination_root=(root)
107:       @destination_stack ||= []
108:       @destination_stack[0] = File.expand_path(root || '')
109:     end

directory(source, *args, &block) 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` method returns the value “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, *args, &block)
44:       config = args.last.is_a?(Hash) ? args.pop : {}
45:       destination = args.first || source
46:       action Directory.new(self, source, destination || source, config, &block)
47:     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 127
127:     def find_in_source_paths(file)
128:       relative_root = relative_to_original_destination_root(destination_root, false)
129: 
130:       source_paths.each do |source|
131:         source_file = File.expand_path(file, File.join(source, relative_root))
132:         return source_file if File.exists?(source_file)
133:       end
134: 
135:       message = "Could not find #{file.inspect} in any of your source paths. "
136: 
137:       unless self.class.source_root
138:         message << "Please invoke #{self.class.name}.source_root(PATH) with the PATH containing your templates. "
139:       end
140: 
141:       if source_paths.empty?
142:         message << "Currently you have no source paths."
143:       else
144:         message << "Your current source paths are: \n#{source_paths.join("\n")}"
145:       end
146: 
147:       raise Error, message
148:     end

get(source, *args, &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 50
50:     def get(source, *args, &block)
51:       config = args.last.is_a?(Hash) ? args.pop : {}
52:       destination = args.first
53: 
54:       source = File.expand_path(find_in_source_paths(source.to_s)) unless source =~ /^https?\:\/\//
55:       render = open(source) {|input| input.binmode.read }
56: 
57:       destination ||= if block_given?
58:         block.arity == 1 ? block.call(render) : block.call
59:       else
60:         File.basename(source)
61:       end
62: 
63:       create_file destination, render, config
64:     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 194
194:     def gsub_file(path, flag, *args, &block)
195:       return unless behavior == :invoke
196:       config = args.last.is_a?(Hash) ? args.pop : {}
197: 
198:       path = File.expand_path(path, destination_root)
199:       say_status :gsub, relative_to_original_destination_root(path), config.fetch(:verbose, true)
200: 
201:       unless options[:pretend]
202:         content = File.binread(path)
203:         content.gsub!(flag, *args, &block)
204:         File.open(path, 'wb') { |file| file.write(content) }
205:       end
206:     end

in_root() click to toggle source

Goes to the root and execute the given block.

     # File lib/thor/actions.rb, line 185
185:     def in_root
186:       inside(@destination_stack.first) { yield }
187:     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 172
172:     def inject_into_class(path, klass, *args, &block)
173:       config = args.last.is_a?(Hash) ? args.pop : {}
174:       config.merge!(:after => /class #{klass}\n|class #{klass} .*\n/)
175:       inject_into_file(path, *(args << config), &block)
176:     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) or :force => true for insert two or more times the same content.

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 25
25:     def inject_into_file(destination, *args, &block)
26:       if block_given?
27:         data, config = block, args.shift
28:       else
29:         data, config = args.shift, args.shift
30:       end
31:       action InjectIntoFile.new(self, destination, data, config)
32:     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 159
159:     def inside(dir='', config={}, &block)
160:       verbose = config.fetch(:verbose, false)
161:       pretend = options[:pretend]
162: 
163:       say_status :inside, dir, verbose
164:       shell.padding += 1 if verbose
165:       @destination_stack.push File.expand_path(dir, destination_root)
166: 
167:       # If the directory doesnt exist and we're not pretending
168:       if !File.exist?(destination_root) && !pretend
169:         FileUtils.mkdir_p(destination_root)
170:       end
171:       
172:       if pretend
173:         # In pretend mode, just yield down to the block
174:         block.arity == 1 ? yield(destination_root) : yield
175:       else
176:         FileUtils.cd(destination_root) { block.arity == 1 ? yield(destination_root) : yield }
177:       end
178: 
179:       @destination_stack.pop
180:       shell.padding -= 1 if verbose
181:     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 128
128:     def prepend_file(path, *args, &block)
129:       config = args.last.is_a?(Hash) ? args.pop : {}
130:       config.merge!(:after => /\A/)
131:       inject_into_file(path, *(args << config), &block)
132:     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 114
114:     def relative_to_original_destination_root(path, remove_dot=true)
115:       path = path.gsub(@destination_stack[0], '.')
116:       remove_dot ? (path[2..1] || '') : path
117:     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 219
219:     def remove_file(path, config={})
220:       return unless behavior == :invoke
221:       path  = File.expand_path(path, destination_root)
222: 
223:       say_status :remove, relative_to_original_destination_root(path), config.fetch(:verbose, true)
224:       ::FileUtils.rm_rf(path) if !options[:pretend] && File.exists?(path)
225:     end

Also aliased as: remove_dir

run(command, config={}) click to toggle source

Executes a command returning the contents of the 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 232
232:     def run(command, config={})
233:       return unless behavior == :invoke
234: 
235:       destination = relative_to_original_destination_root(destination_root, false)
236:       desc = "#{command} from #{destination.inspect}"
237: 
238:       if config[:with]
239:         desc = "#{File.basename(config[:with].to_s)} #{desc}"
240:         command = "#{config[:with]} #{command}"
241:       end
242: 
243:       say_status :run, desc, config.fetch(:verbose, true)
244:       `#{command}` unless options[:pretend]
245:     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 253
253:     def run_ruby_script(command, config={})
254:       return unless behavior == :invoke
255:       run command, config.merge(:with => Thor::Util.ruby_command)
256:     end

source_paths() click to toggle source

Holds source paths in instance so they can be manipulated.

     # File lib/thor/actions.rb, line 121
121:     def source_paths
122:       @source_paths ||= self.class.source_paths_for_search
123:     end

template(source, *args, &block) 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 81
81:     def template(source, *args, &block)
82:       config = args.last.is_a?(Hash) ? args.pop : {}
83:       destination = args.first || source
84: 
85:       source  = File.expand_path(find_in_source_paths(source.to_s))
86:       context = instance_eval('binding')
87: 
88:       create_file destination, nil, config do
89:         content = ERB.new(::File.binread(source), nil, '-', '@output_buffer').result(context)
90:         content = block.call(content) if block
91:         content
92:       end
93:     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 275
275:     def thor(task, *args)
276:       config  = args.last.is_a?(Hash) ? args.pop : {}
277:       verbose = config.key?(:verbose) ? config.delete(:verbose) : true
278:       pretend = config.key?(:pretend) ? config.delete(:pretend) : false
279: 
280:       args.unshift task
281:       args.push Thor::Options.to_switches(config)
282:       command = args.join(' ').strip
283: 
284:       run command, :with => :thor, :verbose => verbose, :pretend => pretend
285:     end

Private Instance Methods

capture(*args, &block) click to toggle source

     # File lib/thor/actions/file_manipulation.rb, line 234
234:     def capture(*args, &block)
235:       with_output_buffer { block.call(*args) }
236:     end

concat(string) click to toggle source

     # File lib/thor/actions/file_manipulation.rb, line 230
230:     def concat(string)
231:       @output_buffer.concat(string)
232:     end

Home Classes Methods

In Files

Namespace

Methods

Files

Class Index

Thor::Actions

Attributes

Public Class Methods

Configuration

Public Instance Methods

Parameters

Example

Parameters

Examples

Parameters

Example

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Example

Parameters

Examples

Parameters

Examples

Parameters

Parameters

Example

Parameters

Example

Parameters

Example

Parameters

Parameters

Examples

Parameters

Examples

Private Instance Methods