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 Guard plugins and the file changes they are watching.

You can optionally group the Guard plugins with the `group` keyword and ignore and filter certain paths with the `ignore` and `filter` keywords.

You can set your preferred system notification library with `notification` and pass some optional configuration options for the library. If you don‘t configure a library, Guard will automatically pick one with default options (if you don‘t want notifications, specify `:off` as library). @see ::Guard::Notifier for more information about the supported libraries.

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`, `run_on_changes`, `run_on_additions`, `run_on_modifications` and `run_on_removals` Guard plugins 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`:

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

@see github.com/guard/guard/wiki/Guardfile-examples

Methods

Constants

IGNORE_PATHS_DEPRECATION = <<-EOS.gsub(/^\s*/, '') Starting with Guard v1.1 the use of the 'ignore_paths' Guardfile DSL method is deprecated. Please replace that method with the better 'ignore' or/and 'filter' methods. Documentation on the README: https://github.com/guard/guard#guardfile-dsl-ignore EOS .gsub(/^\s*/, '')   Deprecation message for the `ignore_paths` method
INTERACTOR_DEPRECATION = <<-EOS.gsub(/^\s*/, '') Starting with Guard v1.4 the use of the 'interactor' Guardfile DSL method is only used to disable or pass options to the Pry interactor. All other usages are deprecated. EOS .gsub(/^\s*/, '')   Deprecation message for the `ignore_paths` method

Attributes

options  [RW] 

Public Class methods

Start Guard and notification and show a message after the Guardfile has been re-evaluated.

Stop Guard and clear internal state before the Guardfile will be re-evaluated.

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 plugin.

@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] guardfile_path 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`, `run_on_changes` `run_on_additions`, `run_on_modifications` and `run_on_removals` plugin method.

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

@see Guard::Hook

Filter certain paths globally.

@example Filter some files

  filter /\.txt$/, /.*\.zip/

@param [Regexp] regexps a pattern for filtering paths

Replace filtered paths globally.

@example Filter only these files

  filter! /\.txt$/, /.*\.zip/

@param [Regexp] regexps a pattern for filtering paths

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

@example Declare two groups of Guard plugins

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

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

@param [Symbol, String] name the group 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 plugin 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 %r{^ignored/path/}, /man/

@param [Regexp] regexps a pattern for ignoring paths

Replace ignored paths globally

@example Ignore only these paths

  ignore! %r{^ignored/path/}, /man/

@param [Regexp] regexps a pattern for ignoring paths

@deprecated Ignore certain paths globally.

@example Ignore some paths

  ignore_paths ".git", ".svn"

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

Sets the interactor to use.

@example Turn off interactions

  interactor :off

@param [Symbol,Hash] options either `:off` or a Hash with interactor options

Configure the Guard logger.

  • Log level must be either `:debug`, `:info`, `:warn` or `:error`.
  • Template supports the following placeholders: `:time`, `:severity`, `:progname`, `:pid`, `:unit_of_work_id` and `:message`
  • Time format directives are the same as Time#strftime or :milliseconds
  • The `:only` and `:except` options must be a RegExp.

@example Set the log level

  logger :level => :warn

@example Set a custom log template

  logger :template => '[Guard - :severity - :progname - :time] :message'

@example Set a custom time format

  logger :time_format => '%h'

@example Limit logging to a Guard plugin

  logger :only => :jasmine

@example Log all but not the messages from a specific Guard plugin

  logger :except => :jasmine

@param [Hash] options the log options @option options [String, Symbol] level the log level @option options [String] template the logger template @option options [String, Symbol] time_format the time format @option options [RegExp] only show only messages from the matching Guard plugin @option options [RegExp] except does not show messages from the matching Guard plugin

Set notification options for the system notifications. You can set multiple notification, which allows you to show local system notifications and remote notifications with separate libraries. You can also pass `:off` as library to turn off notifications.

@example Define multiple notifications

  notification :growl_notify
  notification :ruby_gntp, :host => '192.168.1.5'

@see Guard::Notifier for available notifier and its options.

@param [Symbol, String] notifier the name of the notifier to use @param [Hash] options the notification library options

Sets the default scope on startup

@example Scope Guard to a single group

  scope :group => :frontend

@example Scope Guard to multiple groups

  scope :groups => [:specs, :docs]

@example Scope Guard to a single plugin

  scope :plugin => :test

@example Scope Guard to multiple plugins

  scope :plugins => [:jasmine, :rspec]

@param [Hash] scopes the scope for the groups and plugins

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]