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
  unless run_all_tasks
    throw :task_has_failed
  end
end

See Also:

Constant Summary collapse

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

Error raised when no engine is given.

Class.new(StandardError)

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#callbacks ⇒ Hash

Returns:

  • (Hash) 


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

def callbacks
  @callbacks
end

#group ⇒ Guard::Group

Returns:



132
133
134
 
# File 'lib/guard/plugin.rb', line 132

def group
  @group
end

#options ⇒ Hash

Returns:

  • (Hash) 


144
145
146
 
# File 'lib/guard/plugin.rb', line 144

def options
  @options
end

#watchers ⇒ Array<Guard::Watcher>

Returns:



136
137
138
 
# File 'lib/guard/plugin.rb', line 136

def watchers
  @watchers
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.



117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/guard/plugin.rb', line 117

def hook(event, *args)
  hook_name = if event.is_a? Symbol
                calling_method = caller(1..1).first[/`([^']*)'/, 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) 


260
261
262
 
# File 'lib/guard/plugin.rb', line 260

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 202

#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 211

#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 228

#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 220

#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 236

#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 244

#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 186

#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 194

#title ⇒ String

Returns the plugin's class name without the Guard:: namespace.

Examples:

Title for Guard::RSpec

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

Returns:

  • (String) 


272
273
274
 
# File 'lib/guard/plugin.rb', line 272

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

#to_s ⇒ String Also known as: inspect

String representation of the plugin.

Examples:

String representation of an instance of the Guard::RSpec plugin


Guard::RSpec.new.to_s
#=> "#<Guard::RSpec @name=rspec @group=#<Guard::Group @name=default
@options={}> @watchers=[] @callbacks=[] @options={ all_after_pass: true }>"

Returns:

  • (String) —

    the string representation



286
287
288
289
 
# File 'lib/guard/plugin.rb', line 286

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