Class: Guard::Plugin

Inherits:
Object
  • Object
show all
Defined in:
lib/guard/plugin.rb

Overview

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.

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.

Examples:

Throw :task_has_failed


def run_all
  if !runner.run(['all'])
    throw :task_has_failed
  end
end

See Also:

Constant Summary collapse

TEMPLATE_FORMAT = 
"%s/lib/guard/%s/templates/Guardfile"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#callbacks ⇒ Object

Returns the value of attribute callbacks.



129
130
131
 
# File 'lib/guard/plugin.rb', line 129

def callbacks
  @callbacks
end

#group ⇒ Object

Returns the value of attribute group.



129
130
131
 
# File 'lib/guard/plugin.rb', line 129

def group
  @group
end

#options ⇒ Object

Returns the value of attribute options.



129
130
131
 
# File 'lib/guard/plugin.rb', line 129

def options
  @options
end

#watchers ⇒ Object

Returns the value of attribute watchers.



129
130
131
 
# File 'lib/guard/plugin.rb', line 129

def watchers
  @watchers
end

Class Method Details

.add_callback(listener, guard_plugin, events) ⇒ Object

Add a callback.

Parameters:

  • listener (Block) —

    the listener to notify

  • guard_plugin (Guard::Plugin) —

    the Guard plugin to add the callback

  • events (Array<Symbol>) —

    the events to register



62
63
64
65
66
 
# 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

.callbacks ⇒ Object

Get all callbacks registered for all Guard plugins present in the Guardfile.



52
53
54
 
# File 'lib/guard/plugin.rb', line 52

def self.callbacks
  @callbacks ||= Hash.new { |hash, key| hash[key] = [] }
end

.non_namespaced_classname ⇒ String

Returns the non-namespaced class name of the plugin

Examples:

Non-namespaced class name for Guard::RSpec

Guard::RSpec.non_namespaced_classname
#=> "RSpec"

Returns:

  • (String) 


140
141
142
 
# File 'lib/guard/plugin.rb', line 140

def self.non_namespaced_classname
  to_s.sub("Guard::", "")
end

.non_namespaced_name ⇒ String

Returns the non-namespaced name of the plugin

Examples:

Non-namespaced name for Guard::RSpec

Guard::RSpec.non_namespaced_name
#=> "rspec"

Returns:

  • (String) 


153
154
155
 
# File 'lib/guard/plugin.rb', line 153

def self.non_namespaced_name
  non_namespaced_classname.downcase
end

.notify(guard_plugin, event, *args) ⇒ Object

Notify a callback.

Parameters:

  • guard_plugin (Guard::Plugin) —

    the Guard plugin to add the callback

  • event (Symbol) —

    the event to trigger

  • args (Array) —

    the arguments for the listener



74
75
76
77
78
 
# 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_callbacks! ⇒ Object

Reset all callbacks.

TODO: remove (not used anywhere)



83
84
85
 
# File 'lib/guard/plugin.rb', line 83

def self.reset_callbacks!
  @callbacks = nil
end

.template(plugin_location) ⇒ Object

Specify the source for the Guardfile template. Each Guard plugin can redefine this method to add its own logic.

Parameters:

  • plugin_location (String) —

    the plugin location



162
163
164
 
# File 'lib/guard/plugin.rb', line 162

def self.template(plugin_location)
  File.read(format(TEMPLATE_FORMAT, plugin_location, non_namespaced_name))
end

Instance Method Details

#hook(event, *args) ⇒ Object

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.

Here, when #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.

When run_all is called, #hook will notify callbacks registered for the “foo_bar” event.

Examples:

Add a hook with a Symbol


def run_all
  hook :foo
end

Add a hook with a String


def run_all
  hook "foo_bar"
end

Parameters:

  • event (Symbol, String) —

    the name of the Guard event

  • args (Array) —

    the parameters are passed as is to the callbacks registered for the given event.



116
117
118
119
120
121
122
123
124
125
126
127
 
# 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

#name ⇒ String

Returns the plugin’s name (without “guard-”).

Examples:

Name for Guard::RSpec

Guard::RSpec.new.name
#=> "rspec"

Returns:

  • (String) 


240
241
242
 
# File 'lib/guard/plugin.rb', line 240

def name
  @name ||= self.class.non_namespaced_name
end

#reload ⇒ Object

Called when ‘reload|r|z + enter` is pressed. This method should be mainly used for “reload” (really!) actions like reloading passenger/spork/bundler/…

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when reload has failed




# File 'lib/guard/plugin.rb', line 182

#run_all ⇒ Object

Called when just ‘enter` is pressed This method should be principally used for long action like running all specs/tests/…

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when run_all has failed




# File 'lib/guard/plugin.rb', line 191

#run_on_additions(paths) ⇒ Object

Called on file(s) additions that the Guard plugin watches.

Parameters:

  • paths (Array<String>) —

    the changes files or paths

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when run_on_additions has failed




# File 'lib/guard/plugin.rb', line 208

#run_on_changes(paths) ⇒ Object

Default behaviour on file(s) changes that the Guard plugin watches.

Parameters:

  • paths (Array<String>) —

    the changes files or paths

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when run_on_changes has failed




# File 'lib/guard/plugin.rb', line 200

#run_on_modifications(paths) ⇒ Object

Called on file(s) modifications that the Guard plugin watches.

Parameters:

  • paths (Array<String>) —

    the changes files or paths

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when run_on_modifications has failed




# File 'lib/guard/plugin.rb', line 216

#run_on_removals(paths) ⇒ Object

Called on file(s) removals that the Guard plugin watches.

Parameters:

  • paths (Array<String>) —

    the changes files or paths

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when run_on_removals has failed




# File 'lib/guard/plugin.rb', line 224

#start ⇒ Object

Called once when Guard starts. Please override initialize method to init stuff.

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when start has failed




# File 'lib/guard/plugin.rb', line 166

#stop ⇒ Object

Called when ‘stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when stop has failed




# File 'lib/guard/plugin.rb', line 174

#title ⇒ String

Returns the plugin’s class name without the Guard

namespace.

Examples:

Title for Guard::RSpec

Guard::RSpec.new.title
#=> "RSpec"

Returns:

  • (String) 


252
253
254
 
# File 'lib/guard/plugin.rb', line 252

def title
  @title ||= self.class.non_namespaced_classname
end

#to_s ⇒ String

String representation of the plugin.

Examples:

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}>"

Returns:

  • (String) —

    the string representation



267
268
269
270
 
# File 'lib/guard/plugin.rb', line 267

def to_s
  "#<#{self.class} @name=#{name} @group=#{group} @watchers=#{watchers}"\
    " @callbacks=#{callbacks} @options=#{options}>"
end