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)
- 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)
-
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)
-
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
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)
- 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 = {})
- 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)
-
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)
-
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)
-
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)
-
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 = {})
- 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 = {})
-
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)
- 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