Class: Guard::Guard

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

Overview

Base class that every Guard implementation must inherit from.

Guard will trigger the `start`, `stop`, `reload`, `run_all`, `run_on_change` and `run_on_deletion` task methods depending on user interaction and file modification.

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 I'll be passed to the "_end" hook for further evaluation. You can throw `:task_has_failed` to indicate that your Guard method was not successful, and successive guard tasks will be aborted when the group has set the `:halt_on_fail` option.

Each Guard should provide a template Guardfile located within the Gem at `lib/guard/guard-name/templates/Guardfile`.

By default all watchers for a Guard are returning strings of paths to the Guard, but if your Guard want to allow any return value from a watcher, you can set the `any_return` option to true.

If one of those methods raise an exception other than `:task_has_failed`, the Guard::GuardName instance will be removed from the active guards.

Examples:

Throw :task_has_failed


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

See Also:

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Hook

add_callback, callbacks, has_callback?, included, notify, reset_callbacks!

Constructor Details

- (Guard) initialize(watchers = [], options = {})

Initialize a Guard.

Parameters:

  • watchers (Array<Guard::Watcher>) (defaults to: []) —

    the Guard file watchers

  • options (Hash) (defaults to: {}) —

    the custom Guard options

Options Hash (options):

  • group (Symbol) —

    the group this Guard belongs to

  • any_return (Boolean) —

    allow any object to be returned from a watcher



48
49
50
51
 
# File 'lib/guard/guard.rb', line 48

def initialize(watchers = [], options = {})
  @group = options[:group] ? options.delete(:group).to_sym : :default
  @watchers, @options = watchers, options
end

Instance Attribute Details

- (Object) group

Returns the value of attribute group



39
40
41
 
# File 'lib/guard/guard.rb', line 39

def group
  @group
end

- (Object) options

Returns the value of attribute options



39
40
41
 
# File 'lib/guard/guard.rb', line 39

def options
  @options
end

- (Object) watchers

Returns the value of attribute watchers



39
40
41
 
# File 'lib/guard/guard.rb', line 39

def watchers
  @watchers
end

Class Method Details

+ (Object) init(name)

Initialize the Guard. This will copy the Guardfile template inside the Guard gem. The template Guardfile must be located within the Gem at `lib/guard/guard-name/templates/Guardfile`.

Parameters:

  • name (String) —

    the name of the Guard



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/guard/guard.rb', line 58

def self.init(name)
  if ::Guard::Dsl.guardfile_include?(name)
    ::Guard::UI.info "Guardfile already includes #{ name } guard"
  else
    content = File.read('Guardfile')
    guard   = File.read("#{ ::Guard.locate_guard(name) }/lib/guard/#{ name }/templates/Guardfile")

    File.open('Guardfile', 'wb') do |f|
      f.puts(content)
      f.puts("")
      f.puts(guard)
    end

    ::Guard::UI.info "#{ name } guard added to Guardfile, feel free to edit it"
  end
end

Instance Method Details

- (Object) reload

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



97
98
 
# File 'lib/guard/guard.rb', line 97

def reload
end

- (Object) run_all

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



106
107
 
# File 'lib/guard/guard.rb', line 106

def run_all
end

- (Object) run_on_change(paths)

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

Parameters:

  • paths (Array<String>) —

    the changes files or paths

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when run_on_change has failed



115
116
 
# File 'lib/guard/guard.rb', line 115

def run_on_change(paths)
end

- (Object) run_on_deletion(paths)

Called on file(s) deletions that the Guard watches.

Parameters:

  • paths (Array<String>) —

    the deleted files or paths

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when run_on_change has failed



124
125
 
# File 'lib/guard/guard.rb', line 124

def run_on_deletion(paths)
end

- (Object) start

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

Returns:

  • (Object) —

    the task result

Raises:

  • (:task_has_failed) —

    when start has failed



80
81
 
# File 'lib/guard/guard.rb', line 80

def start
end

- (Object) stop

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



88
89
 
# File 'lib/guard/guard.rb', line 88

def stop
end