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`:
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
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` 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
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