Class Guard::Dsl
In: lib/guard/dsl.rb
Parent: Object

The DSL class provides the methods that are used in each `Guardfile` to describe the behaviour of Guard.

The main keywords of the DSL are `guard` and `watch`. These are necessary to define the used Guards and the file changes they are watching.

You can optionally group the Guards with the `group` keyword and ignore certain paths with the `ignore_paths` keyword.

A more advanced DSL use is the `callback` keyword that allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`, `run_all` and `run_on_change` Guards’ method. You can even insert more hooks inside these methods. Please [checkout the Wiki page](github.com/guard/guard/wiki/Hooks-and-callbacks) for more details.

The DSL will also evaluate normal Ruby code.

There are two possible locations for the `Guardfile`:

  • The `Guardfile` in the current directory where Guard has been started
  • The `.Guardfile` in your home directory.

In addition, if a user configuration `.guard.rb` in your home directory is found, it will be appended to the current project `Guardfile`.

@example A sample of a complex Guardfile

  group 'frontend' do
    guard 'passenger', :ping => true do
      watch('config/application.rb')
      watch('config/environment.rb')
      watch(%r{^config/environments/.+\.rb})
      watch(%r{^config/initializers/.+\.rb})
    end

    guard 'livereload', :apply_js_live => false do
      watch(%r{^app/.+\.(erb|haml)})
      watch(%r{^app/helpers/.+\.rb})
      watch(%r{^public/javascripts/.+\.js})
      watch(%r{^public/stylesheets/.+\.css})
      watch(%r{^public/.+\.html})
      watch(%r{^config/locales/.+\.yml})
    end
  end

  group 'backend' do
    # Reload the bundle when the Gemfile is modified
    guard 'bundler' do
      watch('Gemfile')
    end

    # for big project you can fine tune the "timeout" before Spork's launch is considered failed
    guard 'spork', :wait => 40 do
      watch('Gemfile')
      watch('config/application.rb')
      watch('config/environment.rb')
      watch(%r{^config/environments/.+\.rb})
      watch(%r{^config/initializers/.+\.rb})
      watch('spec/spec_helper.rb')
    end

    # use RSpec 2, from the system's gem and with some direct RSpec CLI options
    guard 'rspec', :version => 2, :cli => "--color --drb -f doc", :bundler => false do
      watch('spec/spec_helper.rb')                                  { "spec" }
      watch('app/controllers/application_controller.rb')            { "spec/controllers" }
      watch('config/routes.rb')                                     { "spec/routing" }
      watch(%r{^spec/support/(controllers|acceptance)_helpers\.rb}) { |m| "spec/#{m[1]}" }
      watch(%r{^spec/.+_spec\.rb})

      watch(%r{^app/controllers/(.+)_(controller)\.rb}) { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }

      watch(%r{^app/(.+)\.rb}) { |m| "spec/#{m[1]}_spec.rb" }
      watch(%r{^lib/(.+)\.rb}) { |m| "spec/lib/#{m[1]}_spec.rb" }
    end
  end

Methods

Public Class methods

Evaluate the DSL methods in the `Guardfile`.

@option options [Array<Symbol,String>] groups the groups to evaluate @option options [String] guardfile the path to a valid Guardfile @option options [String] guardfile_contents a string representing the content of a valid Guardfile @raise [ArgumentError] when options are not a Hash

Get the content to evaluate and stores it into the options as `:guardfile_contents`.

Get the content of the `Guardfile`.

@return [String] the Guardfile content

Tests if the current `Guardfile` content is usable.

@return [Boolean] if the Guardfile is usable

Get the content of the `Guardfile` and the global user configuration file.

@see user_config_path

@return [String] the Guardfile content

Gets the default path of the `Guardfile`. This returns the `Guardfile` from the current directory when existing, or the global `.Guardfile` at the home directory.

@return [String] the path to the Guardfile

Test if the current `Guardfile` contains a specific Guard.

@param [String] guard_name the name of the Guard @return [Boolean] whether the Guard has been declared

Get the file path to the project `Guardfile`.

@return [String] the path to the Guardfile

Evaluate the content of the `Guardfile`.

@param [String] contents the content to evaluate.

Read the current `Guardfile` content.

@param [String] the path to the Guardfile

Re-evaluate the `Guardfile` to update the current Guard configuration.

Public Instance methods

Define a callback to execute arbitrary code before or after any of the `start`, `stop`, `reload`, `run_all` and `run_on_change` guards’ method.

@param [Array] args the callback arguments @yield a block with listeners

@see Guard::Hook

Declares a group of guards to be run with `guard start —group group_name`.

@example Declare two groups of Guards

  group 'backend' do
    guard 'spork'
    guard 'rspec'
  end

  group 'frontend' do
    guard 'passenger'
    guard 'livereload'
  end

@param [Symbol, String] name the group‘s name called from the CLI @param [Hash] options the options accepted by the group @yield a block where you can declare several guards

@see Guard.add_group @see Dsl#guard @see Guard::DslDescriber

Declare a guard to be used when running `guard start`.

The name parameter is usually the name of the gem without the ‘guard-’ prefix.

The available options are different for each Guard implementation.

@example Declare a Guard

  guard 'rspec' do
  end

@param [String] name the Guard name @param [Hash] options the options accepted by the Guard @yield a block where you can declare several watch patterns and actions

@see Guard.add_guard @see Dsl#group @see Dsl#watch @see Guard::DslDescriber

Ignore certain paths globally.

@example Ignore some paths

  ignore_paths ".git", ".svn"

@param [Array] paths the list of paths to ignore

@see Guard::Listener

Define a pattern to be watched in order to run actions on file modification.

@example Declare watchers for a Guard

  guard 'rspec' do
    watch('spec/spec_helper.rb')
    watch(%r{^.+_spec.rb})
    watch(%r{^app/controllers/(.+).rb}) { |m| 'spec/acceptance/#{m[1]}s_spec.rb' }
  end

@param [String, Regexp] pattern the pattern to be watched by the guard @yield a block to be run when the pattern is matched @yieldparam [MatchData] m matches of the pattern @yieldreturn a directory, a filename, an array of directories / filenames, or nothing (can be an arbitrary command)

@see Guard::Watcher @see Dsl#guard

[Validate]