Permalink
Browse files

Update docs and man page.

This continues to change the docs naming of Guard implementation as Guard plugins.
Also the man page has been updated with the latest options. Lastly old references to
`run_on_change` has been renamed to `run_on_changes` where appropriate.
  • Loading branch information...
1 parent 776a0ce commit fef1cb48d549b7c2660d1e89f22ab15e95204096 @netzpirat netzpirat committed Jul 2, 2012
Showing with 507 additions and 162 deletions.
  1. +4 −4 CHANGELOG.md
  2. +5 −19 Guardfile
  3. +5 −4 README.md
  4. +25 −25 lib/guard.rb
  5. +8 −8 lib/guard/cli.rb
  6. +15 −13 lib/guard/dsl.rb
  7. +2 −2 lib/guard/dsl_describer.rb
  8. +2 −2 lib/guard/group.rb
  9. +36 −36 lib/guard/guard.rb
  10. +2 −2 lib/guard/hook.rb
  11. +3 −3 lib/guard/interactor.rb
  12. +8 −9 lib/guard/runner.rb
  13. +1 −1 lib/guard/ui.rb
  14. +5 −5 lib/guard/watcher.rb
  15. +69 −0 man/guard
  16. +15 −9 man/guard.1
  17. +16 −10 man/guard.1.html
  18. +14 −8 man/guard.1.ronn
  19. +270 −0 man/guard.html
  20. +2 −2 spec/guard/dsl_spec.rb
View
@@ -31,7 +31,7 @@
- New `--force-polling`/`-p` option to force usage of the Listen polling listener.
- `--watch-all-modifications`/`-A` option is removed and is now always on.
- `--no-vendor`/`-I` option is removed because the monitoring gems are now part of the [Listen gem](https://github.com/guard/listen). You can specify a custom version of any monitoring gem directly in your Gemfile if you want to overwrite Listen's default monitoring gems.
-- Guards implementations must now implement `run_on_additions`, `run_on_modifications`, `run_on_removals` and / or `run_on_changes`. The `run_on_change` and `run_on_deletion` methods are deprecated and should be removed as soon as possible. See the [Upgrade guide for existing guards to Guard v1.1](https://github.com/guard/guard/wiki/Upgrade-guide-for-existing-guards-to-Guard-v1.1) for more info.
+- Guard plugins must now implement `run_on_additions`, `run_on_modifications`, `run_on_removals` and / or `run_on_changes`. The `run_on_change` and `run_on_deletion` methods are deprecated and should be removed as soon as possible. See the [Upgrade guide for existing guards to Guard v1.1](https://github.com/guard/guard/wiki/Upgrade-guide-for-existing-guards-to-Guard-v1.1) for more info.
The Listen integration has been supervised by [@thibaudgg][] and executed by [@Maher4Ever][], [@rymai][] and [@thibaudgg][].
@@ -219,7 +219,7 @@ The Listen integration has been supervised by [@thibaudgg][] and executed by [@M
- [#136][] New CLI `:watch_all_modifications`/`-A` option to watch for deleted and moved files too. ([@limeyd][] and [@netzpirat][])
- [#97][] Guard dependencies. Task execution can now be halted if a Guard throws `:task_has_failed` and `Guard::Dsl#group` options include `:halt_on_fail => true`. ([@rymai][])
-- [#121][] `Guard.guards` and `Guard.groups` are now smart accessors. Filters can be passed to find a specific Guard/group or several Guards/groups that match (see YARDoc). ([@rymai][] and [@ches][])
+- [#121][] `Guard.guards` and `Guard.groups` are now smart accessors. Filters can be passed to find a specific Guard/group or several Guard plugins/groups that match (see YARDoc). ([@rymai][] and [@ches][])
- New `Guard::Group` class to store groups defined in Guardfile (with `Guard::Dsl#group`). ([@rymai][])
### Improvements
@@ -262,7 +262,7 @@ The Listen integration has been supervised by [@thibaudgg][] and executed by [@M
### New features
- Groups are now stored in a `groups` instance variable (will be used for future features). ([@rymai][])
-- Guards will now receive their group in the options hash at initialization (will be used for future features). ([@rymai][])
+- Guard plugins will now receive their group in the options hash at initialization (will be used for future features). ([@rymai][])
### Improvement
@@ -308,7 +308,7 @@ The Listen integration has been supervised by [@thibaudgg][] and executed by [@M
### New features
- Guard::Ego is now part of Guard, so Guardfile is automagically re-evaluated when modified. ([@thibaudgg][])
-- [#91][] Show Guards in Guardfile with the `guard -T`. ([@johnbintz][])
+- [#91][] Show Guard plugins in Guardfile with the `guard -T`. ([@johnbintz][])
### Improvements
View
@@ -8,22 +8,8 @@ group :specs do
end
end
-# group :docs do
-# guard :ronn do
-# watch(%r{^man/.+\.ronn?$})
-# end
-# end
-
-# require 'guard/guard'
-#
-# module ::Guard
-# class Breaking < ::Guard::Guard
-# def run_all
-# raise "Fool !"
-# end
-# end
-# end
-#
-# group "exceptional" do
-# guard :breaking
-# end
+group :docs do
+ guard :ronn do
+ watch(%r{^man/.+\.ronn?$})
+ end
+end
View
@@ -174,9 +174,9 @@ end
Add Guard plugins
-----------------
-Guard is now ready to use and you should add some Guard plugins for your specific use. Start exploring the many Guards
-available by browsing the [Guard organization](https://github.com/guard) on GitHub or by searching for `guard-` on
-[RubyGems](https://rubygems.org/search?utf8=%E2%9C%93&query=guard-).
+Guard is now ready to use and you should add some Guard plugins for your specific use. Start exploring the many Guard
+plugins available by browsing the [Guard organization](https://github.com/guard) on GitHub or by searching for `guard-`
+on [RubyGems](https://rubygems.org/search?utf8=%E2%9C%93&query=guard-).
When you have found a Guard plugin of your interest, add it to your `Gemfile`:
@@ -636,7 +636,8 @@ interactor :off
### callback
The `callback` method 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.
+`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.
```ruby
guard :rspec do
View
@@ -2,7 +2,7 @@
require 'listen'
# Guard is the main module for all Guard related modules and classes.
-# Also other Guard implementation should use this namespace.
+# Also Guard plugins should use this namespace.
#
module Guard
@@ -133,14 +133,14 @@ def setup_interactor
end
end
- # Start Guard by evaluate the `Guardfile`, initialize the declared Guards
+ # Start Guard by evaluate the `Guardfile`, initialize the declared Guard plugins
# and start the available file change listener.
- # Main method for Guard that is called from the CLI when guard starts.
+ # Main method for Guard that is called from the CLI when Guard starts.
#
# - Setup Guard internals
# - Evaluate the `Guardfile`
# - Configure Notifiers
- # - Initialize the declared Guards
+ # - Initialize the declared Guard plugins
# - Start the available file change listener
#
# @option options [Boolean] clear if auto clear the UI should be done
@@ -174,9 +174,9 @@ def stop
@allow_stop.signal if @allow_stop
end
- # Reload Guardfile and all Guards currently enabled.
+ # Reload Guardfile and all Guard plugins currently enabled.
#
- # @param [Hash] scopes an hash with a guard or a group scope
+ # @param [Hash] scopes an hash with a Guard plugin or a group scope
#
def reload(scopes)
within_preserved_state do
@@ -187,9 +187,9 @@ def reload(scopes)
end
end
- # Trigger `run_all` on all Guards currently enabled.
+ # Trigger `run_all` on all Guard plugins currently enabled.
#
- # @param [Hash] scopes an hash with a guard or a group scope
+ # @param [Hash] scopes an hash with a Guard plugin or a group scope
#
def run_all(scopes)
within_preserved_state do
@@ -211,22 +211,22 @@ def pause
end
end
- # Smart accessor for retrieving a specific guard or several guards at once.
+ # Smart accessor for retrieving a specific Guard plugin or several Guard plugins at once.
#
# @see Guard.groups
#
- # @example Filter Guards by String or Symbol
+ # @example Filter Guard plugins by String or Symbol
# Guard.guards('rspec')
# Guard.guards(:rspec)
#
- # @example Filter Guards by Regexp
+ # @example Filter Guard plugins by Regexp
# Guard.guards(/rsp.+/)
#
- # @example Filter Guards by Hash
+ # @example Filter Guard plugins by Hash
# Guard.guards({ :name => 'rspec', :group => 'backend' })
#
- # @param [String, Symbol, Regexp, Hash] filter the filter to apply to the Guards
- # @return [Array<Guard>] the filtered Guards
+ # @param [String, Symbol, Regexp, Hash] filter the filter to apply to the Guard plugins
+ # @return [Array<Guard>] the filtered Guard plugins
#
def guards(filter = nil)
@guards ||= []
@@ -249,7 +249,7 @@ def guards(filter = nil)
end
end
- # Smart accessor for retrieving a specific group or several groups at once.
+ # Smart accessor for retrieving a specific plugin group or several plugin groups at once.
#
# @see Guard.guards
#
@@ -274,13 +274,13 @@ def groups(filter = nil)
end
end
- # Add a Guard to use.
+ # Add a Guard plugin to use.
#
# @param [String] name the Guard name
# @param [Array<Watcher>] watchers the list of declared watchers
# @param [Array<Hash>] callbacks the list of callbacks
- # @param [Hash] options the Guard options (see the given Guard documentation)
- # @return [Guard::Guard] the guard added
+ # @param [Hash] options the plugin options (see the given Guard documentation)
+ # @return [Guard::Guard] the added Guard plugin
#
def add_guard(name, watchers = [], callbacks = [], options = {})
if name.to_sym == :ego
@@ -294,11 +294,11 @@ def add_guard(name, watchers = [], callbacks = [], options = {})
end
end
- # Add a Guard group.
+ # Add a Guard plugin group.
#
# @param [String] name the group name
# @option options [Boolean] halt_on_fail if a task execution
- # should be halted for all Guards in this group if one Guard throws `:task_has_failed`
+ # should be halted for all Guard plugins in this group if one Guard throws `:task_has_failed`
# @return [Guard::Group] the group added (or retrieved from the `@groups` variable if already present)
#
def add_group(name, options = {})
@@ -329,7 +329,7 @@ def within_preserved_state
@result
end
- # Tries to load the Guard main class. This transforms the supplied Guard
+ # Tries to load the Guard plugin main class. This transforms the supplied Guard plugin
# name into a class name:
#
# * `guardname` will become `Guard::Guardname`
@@ -367,9 +367,9 @@ def get_guard_class(name, fail_gracefully=false)
end
end
- # Locate a path to a Guard gem.
+ # Locate a path to a Guard plugin gem.
#
- # @param [String] name the name of the Guard without the prefix `guard-`
+ # @param [String] name the name of the Guard plugin without the prefix `guard-`
# @return [String] the full path to the Guard gem
#
def locate_guard(name)
@@ -382,9 +382,9 @@ def locate_guard(name)
UI.error "Could not find 'guard-#{ name }' gem path."
end
- # Returns a list of guard Gem names installed locally.
+ # Returns a list of Guard plugin Gem names installed locally.
#
- # @return [Array<String>] a list of guard gem names
+ # @return [Array<String>] a list of Guard plugin gem names
#
def guard_gem_names
if Gem::Version.create(Gem::VERSION) >= Gem::Version.create('1.8.0')
View
@@ -85,7 +85,7 @@ class CLI < Thor
:aliases => '-p',
:banner => 'Force usage of the Listen polling listener'
- # Start Guard by initialize the defined Guards and watch the file system.
+ # Start Guard by initialize the defined Guard plugins and watch the file system.
# This is the default task, so calling `guard` is the same as calling `guard start`.
#
# @see Guard.start
@@ -100,7 +100,7 @@ def start
desc 'list', 'Lists guards that can be used with init'
- # List the Guards that are available for use in your system and marks
+ # List the Guard plugins that are available for use in your system and marks
# those that are currently used in your `Guardfile`.
#
# @see Guard::DslDescriber.list
@@ -130,14 +130,14 @@ def version
:aliases => '-b',
:banner => 'Generate a bare Guardfile without adding any installed guard into it'
- # Initializes the templates of all installed Guards and adds them
- # to the `Guardfile` when no Guard name is passed. When passed
- # a guard name is does the same but only for that Guard.
+ # Initializes the templates of all installed Guard pluginss and adds them
+ # to the `Guardfile` when no Guard name is passed. When passing
+ # a Guard plugin name it does the same but only for that Guard plugin.
#
# @see Guard::Guard.initialize_template
# @see Guard::Guard.initialize_all_templates
#
- # @param [String] guard_name the name of the Guard to initialize
+ # @param [String] guard_name the name of the Guard plugin to initialize
#
def init(guard_name = nil)
verify_bundler_presence
@@ -153,10 +153,10 @@ def init(guard_name = nil)
end
end
- desc 'show', 'Show all defined Guards and their options'
+ desc 'show', 'Show all defined Guard plugins and their options'
map %w(-T) => :show
- # Shows all Guards and their options that are defined in
+ # Shows all Guard plugins and their options that are defined in
# the `Guardfile`
#
# @see Guard::DslDescriber.show
View
@@ -4,9 +4,9 @@ module Guard
# 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.
+ # the used Guard plugins and the file changes they are watching.
#
- # You can optionally group the Guards with the `group` keyword and ignore and filter certain paths
+ # 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
@@ -15,8 +15,9 @@ module Guard
# 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` and `run_on_change`
- # Guards' method. You can even insert more hooks inside these methods.
+ # 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](https://github.com/guard/guard/wiki/Hooks-and-callbacks) for more details.
#
# The DSL will also evaluate normal Ruby code.
@@ -119,7 +120,7 @@ def reevaluate_guardfile
after_reevaluate_guardfile
end
- # Stop Guards and clear internal state
+ # Stop Guard and clear internal state
# before the Guardfile will be re-evaluated.
#
def before_reevaluate_guardfile
@@ -131,7 +132,7 @@ def before_reevaluate_guardfile
@@options.delete(:guardfile_contents)
end
- # Start Guards and notification and show a message
+ # Start Guard and notification and show a message
# after the Guardfile has been re-evaluated.
#
def after_reevaluate_guardfile
@@ -158,7 +159,7 @@ def instance_eval_guardfile(contents)
UI.error "Invalid Guardfile, original error is:\n#{ $! }"
end
- # Test if the current `Guardfile` contains a specific Guard.
+ # 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
@@ -206,7 +207,7 @@ def fetch_guardfile_contents
end
unless guardfile_contents_usable?
- UI.error 'No Guards found in Guardfile, please add at least one.'
+ UI.error 'No Guard plugins found in Guardfile, please add at least one.'
end
end
@@ -320,9 +321,9 @@ def interactor(interactor)
::Guard::Interactor.interactor = interactor.to_sym
end
- # Declares a group of guards to be run with `guard start --group group_name`.
+ # Declares a group of Guard plugins to be run with `guard start --group group_name`.
#
- # @example Declare two groups of Guards
+ # @example Declare two groups of Guard plugins
#
# group 'backend' do
# guard 'spork'
@@ -334,7 +335,7 @@ def interactor(interactor)
# guard 'livereload'
# end
#
- # @param [Symbol, String] name the group's name called from the CLI
+ # @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
#
@@ -356,7 +357,7 @@ def group(name, options = {})
end
end
- # Declare a guard to be used when running `guard start`.
+ # 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.
@@ -411,7 +412,8 @@ def watch(pattern, &action)
end
# Define a callback to execute arbitrary code before or after any of
- # the `start`, `stop`, `reload`, `run_all` and `run_on_change` guards' method.
+ # 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
Oops, something went wrong.

0 comments on commit fef1cb4

Please sign in to comment.