class Guard::Dsl


@see github.com/guard/guard/wiki/Guardfile-examples<br><br>found, it will be appended to the current project ‘Guardfile`.
In addition, if a user configuration `.guard.rb` in your home directory is
* The `.Guardfile` in your home directory.
has been started
* The `Guardfile` or `guardfile.rb` in the current directory where Guard
There are two possible locations for the `Guardfile`:
The DSL will also evaluate normal Ruby code.
more details.
Wiki page](github.com/guard/guard/wiki/Hooks-and-callbacks) for
You can even insert more hooks inside these methods. Please [checkout the
Guard plugins method.
{Plugin#run_on_modifications} and {Plugin#run_on_removals}
{Plugin#run_on_changes}, {Plugin#run_on_additions},
{Plugin#stop}, {Plugin#reload}, {Plugin#run_all},
execute arbitrary code before or after any of the {Plugin#start},
A more advanced DSL use is the {#callback} keyword that allows you to
{Notifier} for more information about the supported libraries.
(if you don’t want notifications, specify ‘:off` as library). Please see
configure a library, Guard will automatically pick one with default options
and pass some optional configuration options for the library. If you don’t
You can set your preferred system notification library with {#notification}
ignore and filter certain paths with the {#ignore} and {#filter} keywords.
You can optionally group the Guard plugins with the {#group} keyword and
to define the used Guard plugins and the file changes they are watching.
The main keywords of the DSL are {#guard} and {#watch}. These are necessary
describe the behaviour of Guard.
The Dsl class provides the methods that are used in each ‘Guardfile` to

def _cleanup_backtrace(backtrace)

def _cleanup_backtrace(backtrace)
  dirs = { File.realpath(Dir.pwd) => ".", }
  gem_env = ENV["GEM_HOME"] || ""
  dirs[gem_env] = "$GEM_HOME" unless gem_env.empty?
  gem_paths = (ENV["GEM_PATH"] || "").split(File::PATH_SEPARATOR)
  gem_paths.each_with_index do |path, index|
    dirs[path] = "$GEM_PATH[#{index}]"
  end
  backtrace.dup.map do |raw_line|
    path = nil
    symlinked_path = raw_line.split(":").first
    begin
      path = raw_line.sub(symlinked_path, File.realpath(symlinked_path))
      dirs.detect { |dir, name| path.sub!(File.realpath(dir), name) }
      path
    rescue Errno::ENOENT
      path || symlinked_path
    end
  end
end

def callback(*args, &block)

Other tags:
    Yield: - a callback block

Parameters:
  • args (Array) -- the callback arguments

Other tags:
    Example: Add callback before the `start` and `stop` actions. -
    Example: Add callback before the `reload` action. -
def callback(*args, &block)
  @plugin_options ||= nil
  fail "callback must be called within a guard block" unless @plugin_options
  block, events = if args.size > 1
                    # block must be the first argument in that case, the
                    # yielded block is ignored
                    args
                  else
                    [block, args[0]]
                  end
  @plugin_options[:callbacks] << { events: events, listener: block }
end

def clearing(on)

Parameters:
  • on (Symbol) -- ':on' to turn on, ':off' (default) to turn off

Other tags:
    Example: switching clearing the screen on -
def clearing(on)
  Guard.state.session.clearing(on == :on)
end

def directories(directories)

Parameters:
  • directories (Array) -- directories for Listen to watch

Other tags:
    Example: watch only given directories -
def directories(directories)
  directories.each do |dir|
    fail "Directory #{dir.inspect} does not exist!" unless Dir.exist?(dir)
  end
  Guard.state.session.watchdirs = directories
end

def evaluate(contents, filename, lineno) # :nodoc

:nodoc
def evaluate(contents, filename, lineno) # :nodoc
  instance_eval(contents, filename.to_s, lineno)
rescue StandardError, ScriptError => e
  prefix = "\n\t(dsl)> "
  cleaned_backtrace = _cleanup_backtrace(e.backtrace)
  backtrace = "#{prefix}#{cleaned_backtrace.join(prefix)}"
  msg = "Invalid Guardfile, original error is: \n\n%s, \nbacktrace: %s"
  raise Error, format(msg, e, backtrace)
end

def group(*args)

Other tags:
    See: #guard -
    See: Guard.add_group -
    See: Group -

Other tags:
    Yield: - a block where you can declare several Guard plugins

Parameters:
  • options (Hash) -- the options accepted by the group
  • name (Symbol, String, Array) -- the group name called

Other tags:
    Example: Declare two groups of Guard plugins -
def group(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  groups = args
  groups.each do |group|
    next unless group.to_sym == :all
    fail ArgumentError, "'all' is not an allowed group name!"
  end
  if block_given?
    groups.each do |group|
      # TODO: let groups be added *after* evaluation
      Guard.state.session.groups.add(group, options)
    end
    @current_groups ||= []
    @current_groups.push(groups)
    yield
    @current_groups.pop
  else
    UI.error \
      "No Guard plugins found in the group '#{ groups.join(', ') }',"\
      " please add at least one."
  end
end

def guard(name, options = {})

Other tags:
    See: #group -
    See: #watch -
    See: Guard.add_plugin -
    See: Plugin -

Other tags:
    Yield: - a block where you can declare several watch patterns and actions

Parameters:
  • options (Hash) -- the options accepted by the Guard plugin
  • name (String) -- the Guard plugin name

Other tags:
    Example: Declare a Guard with a `watch` pattern -
    Example: Declare a Guard without `watch` patterns -
def guard(name, options = {})
  @plugin_options = options.merge(watchers: [], callbacks: [])
  yield if block_given?
  @current_groups ||= []
  groups = @current_groups && @current_groups.last || [:default]
  groups.each do |group|
    opts = @plugin_options.merge(group: group)
    # TODO: let plugins be added *after* evaluation
    Guard.state.session.plugins.add(name, opts)
  end
  @plugin_options = nil
end

def ignore(*regexps)

Parameters:
  • regexps (Regexp) -- a pattern (or list of patterns) for ignoring paths

Other tags:
    Example: Ignore some paths -
def ignore(*regexps)
  # TODO: use guardfile results class
  Guard.state.session.guardfile_ignore = regexps
end

def ignore!(*regexps)

Parameters:
  • regexps (Regexp) -- a pattern (or list of patterns) for ignoring paths

Other tags:
    Example: Ignore only these paths -
def ignore!(*regexps)
  @ignore_regexps ||= []
  @ignore_regexps << regexps
  # TODO: use guardfile results class
  Guard.state.session.guardfile_ignore_bang = @ignore_regexps
end

def interactor(options)

Parameters:
  • options (Symbol, Hash) -- either `:off` or a Hash with interactor

Other tags:
    Example: Turn off interactions -
    Example: Pass options to the interactor -
def interactor(options)
  # TODO: remove dependency on Interactor (let session handle this)
  case options
  when :off
    Interactor.enabled = false
  when Hash
    Interactor.options = options
  end
end

def logger(options)

Options Hash: (**options)
  • except (Regexp) -- does not show messages from the matching
  • only (Regexp) -- show only messages from the matching Guard
  • time_format (String, Symbol) -- the time format
  • template (String) -- the logger template
  • level (String, Symbol) -- the log level

Parameters:
  • options (Hash) -- the log options

Other tags:
    Example: Log all but not the messages from a specific Guard plugin -
    Example: Limit logging to a Guard plugin -
    Example: Set a custom time format -
    Example: Set a custom log template -
    Example: Set the log level -
def logger(options)
  if options[:level]
    options[:level] = options[:level].to_sym
    unless [:debug, :info, :warn, :error].include? options[:level]
      UI.warning(format(WARN_INVALID_LOG_LEVEL, options[:level]))
      options.delete :level
    end
  end
  if options[:only] && options[:except]
    UI.warning WARN_INVALID_LOG_OPTIONS
    options.delete :only
    options.delete :except
  end
  # Convert the :only and :except options to a regular expression
  [:only, :except].each do |name|
    next unless options[name]
    list = [].push(options[name]).flatten.map do |plugin|
      Regexp.escape(plugin.to_s)
    end
    options[name] = Regexp.new(list.join("|"), Regexp::IGNORECASE)
  end
  UI.options = UI.options.merge(options)
end

def notification(notifier, opts = {})

Other tags:
    See: Guard::Notifier - for available notifier and its options.

Parameters:
  • opts (Hash) -- the notification library options
  • notifier (Symbol, String) -- the name of the notifier to use

Other tags:
    Example: Define multiple notifications -
def notification(notifier, opts = {})
  Guard.state.session.guardfile_notification = { notifier.to_sym => opts }
end

def scope(scope = {})

Parameters:
  • scope (Hash) -- the scope for the groups and plugins

Other tags:
    Example: Scope Guard to multiple plugins -
    Example: Scope Guard to a single plugin -
    Example: Scope Guard to multiple groups -
    Example: Scope Guard to a single group -
def scope(scope = {})
  # TODO: use a Guardfile::Results class
  Guard.state.session.guardfile_scope(scope)
end

def watch(pattern, &action)

Other tags:
    See: #guard -
    See: Guard::Watcher -

Other tags:
    Yieldreturn: - a directory, a filename, an array of

Other tags:
    Yieldparam: m - matches of the pattern

Other tags:
    Yield: - a block to be run when the pattern is matched

Parameters:
  • pattern (String, Regexp) -- the pattern that Guard must watch for

Other tags:
    Example: Declare global watchers outside of a Guard -
    Example: Declare watchers for a Guard -
def watch(pattern, &action)
  # Allow watches in the global scope (to execute arbitrary commands) by
  # building a generic Guard::Plugin.
  @plugin_options ||= nil
  return guard(:plugin) { watch(pattern, &action) } unless @plugin_options
  @plugin_options[:watchers] << Watcher.new(pattern, action)
end