class Guard::Plugin
Base class from which every Guard plugin implementation must inherit.
Guard will trigger the {#start}, {#stop}, {#reload}, {#run_all} and {#run_on_changes} ({#run_on_additions}, {#run_on_modifications} and {#run_on_removals}) task methods depending on user interaction and file modification.
{#run_on_changes} could be implemented to handle all the changes task case (additions, modifications, removals) in once, or each task can be implemented separately with a specific behavior.
In each of these Guard task methods you have to implement some work when you want to support this kind of task. The return value of each Guard task method is not evaluated by Guard, but it'll be passed to the “_end” hook for further evaluation. You can throw `:task_has_failed` to indicate that your Guard plugin method was not successful, and successive Guard plugin tasks will be aborted when the group has set the `:halt_on_fail` option.
@see Guard::Group
@example Throw :task_has_failed
def run_all if !runner.run(['all']) throw :task_has_failed end end
Each Guard plugin should provide a template Guardfile located within the Gem at `lib/guard/guard-name/templates/Guardfile`.
Watchers for a Guard plugin should return a file path or an array of files paths to Guard, but if your Guard plugin wants to allow any return value from a watcher, you can set the `any_return` option to true.
If one of those methods raises an exception other than `:task_has_failed`, the `Guard::GuardName` instance will be removed from the active Guard plugins.
Constants
- TEMPLATE_FORMAT
Attributes
Public Class Methods
Add a callback.
@param [Block] listener the listener to notify @param [Guard::Plugin] guard_plugin the Guard plugin to add the callback @param [Array<Symbol>] events the events to register
# File lib/guard/plugin.rb, line 62 def self.add_callback(listener, guard_plugin, events) Array(events).each do |event| callbacks[[guard_plugin, event]] << listener end end
Initializes a Guard plugin. Don't do any work here, especially as Guard plugins get initialized even if they are not in an active group!
@param [Hash] options the Guard plugin options @option options [Array<Guard::Watcher>] watchers the Guard plugin file
watchers
@option options [Symbol] group the group this Guard plugin belongs to @option options [Boolean] any_return allow any object to be returned from
a watcher
# File lib/guard/plugin.rb, line 285 def initialize(options = {}) group_name = options.delete(:group) { :default } @group = Guard.state.session.groups.add(group_name) @watchers = options.delete(:watchers) { [] } @callbacks = options.delete(:callbacks) { [] } @options = options _register_callbacks end
Returns the non-namespaced class name of the plugin
@example Non-namespaced class name for Guard::RSpec
Guard::RSpec.non_namespaced_classname #=> "RSpec"
@return [String]
# File lib/guard/plugin.rb, line 140 def self.non_namespaced_classname to_s.sub("Guard::", "") end
Returns the non-namespaced name of the plugin
@example Non-namespaced name for Guard::RSpec
Guard::RSpec.non_namespaced_name #=> "rspec"
@return [String]
# File lib/guard/plugin.rb, line 153 def self.non_namespaced_name non_namespaced_classname.downcase end
Notify a callback.
@param [Guard::Plugin] guard_plugin the Guard plugin to add the callback @param [Symbol] event the event to trigger @param [Array] args the arguments for the listener
# File lib/guard/plugin.rb, line 74 def self.notify(guard_plugin, event, *args) callbacks[[guard_plugin, event]].each do |listener| listener.call(guard_plugin, event, *args) end end
Reset all callbacks.
TODO: remove (not used anywhere)
# File lib/guard/plugin.rb, line 83 def self.reset_callbacks! @callbacks = nil end
Specify the source for the Guardfile template. Each Guard plugin can redefine this method to add its own logic.
@param [String] plugin_location the plugin location
# File lib/guard/plugin.rb, line 162 def self.template(plugin_location) File.read(format(TEMPLATE_FORMAT, plugin_location, non_namespaced_name)) end
Public Instance Methods
When event is a Symbol, {#hook} will generate a hook name by concatenating the method name from where {#hook} is called with the given Symbol.
@example Add a hook with a Symbol
def run_all hook :foo end
Here, when {Guard::Plugin#run_all} is called, {#hook} will notify callbacks registered for the “run_all_foo” event.
When event is a String, {#hook} will directly turn the String into a Symbol.
@example Add a hook with a String
def run_all hook "foo_bar" end
When {Guard::Plugin::run_all} is called, {#hook} will notify callbacks registered for the “foo_bar” event.
@param [Symbol, String] event the name of the Guard event @param [Array] args the parameters are passed as is to the callbacks
registered for the given event.
# File lib/guard/plugin.rb, line 116 def hook(event, *args) hook_name = if event.is_a? Symbol calling_method = caller[0][/`([^']*)'/, 1] "#{ calling_method }_#{ event }" else event end UI.debug "Hook :#{ hook_name } executed for #{ self.class }" self.class.notify(self, hook_name.to_sym, *args) end
Returns the plugin's name (without “guard-”).
@example Name for Guard::RSpec
Guard::RSpec.new.name #=> "rspec"
@return [String]
# File lib/guard/plugin.rb, line 240 def name @name ||= self.class.non_namespaced_name end
- Returns the plugin's class name without the Guard
-
namespace.
@example Title for Guard::RSpec
Guard::RSpec.new.title #=> "RSpec"
@return [String]
# File lib/guard/plugin.rb, line 252 def title @title ||= self.class.non_namespaced_classname end
String representation of the plugin.
@example String representation of an instance of the Guard::RSpec plugin
Guard::RSpec.new.title #=> "#<Guard::RSpec @name=rspec @group=#<Guard::Group @name=default @options={}> @watchers=[] @callbacks=[] @options={all_after_pass: true}>"
@return [String] the string representation
# File lib/guard/plugin.rb, line 267 def to_s "#<#{self.class} @name=#{name} @group=#{group} @watchers=#{watchers}"\ " @callbacks=#{callbacks} @options=#{options}>" end
Private Instance Methods
Add all the Guard::Plugin's callbacks to the global @callbacks array that's used by Guard to know which callbacks to notify.
# File lib/guard/plugin.rb, line 297 def _register_callbacks callbacks.each do |callback| self.class.add_callback(callback[:listener], self, callback[:events]) end end