guard 1.4.0 → 1.5.0

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 1.5.0 - 22 October, 2012
+
+### New features
+
+- [#327][] Use Pry as interactor. ([@netzpirat][])
+- [#345][] Use Lumberjack as customizable logger. ([@netzpirat][])
+- [#342][] Add notifier for displaying result in terminal title. ([@tomas-zemres][])
+- [#348][] Introduce grouping of the notifiers for better auto-detection. ([@netzpirat][])
+
+### Improvements
+
+- [#348][] Introduce grouping of the notifiers. ([@netzpirat][])
+- [#343][] Customize tmux notifier status location. ([@nickmabry][])
+- Adds ability to override default options in emacs notifier. ([@d1][])
+- Use `$stderr` instead of `STDERR` to allow redirection. ([@netzpirat][])
+- [#334][] Extend `:tmux` notifier with use of `tmux display-message` and options to configure them. ([@matthijsgroen][])
+
 ## 1.4.0 - 26 September, 2012
 
 - [#331][] Add tmux notifier. ([@royvandewater][])
@@ -600,6 +617,9 @@ The Listen integration has been supervised by [@thibaudgg][] and executed by [@M
 [#317]: https://github.com/guard/guard/issues/317
 [#324]: https://github.com/guard/guard/issues/324
 [#331]: https://github.com/guard/guard/issues/331
+[#334]: https://github.com/guard/guard/issues/334
+[#342]: https://github.com/guard/guard/issues/342
+[#343]: https://github.com/guard/guard/issues/343
 [@Gazer]: https://github.com/Gazer
 [@Maher4Ever]: https://github.com/Maher4Ever
 [@alandipert]: https://github.com/alandipert
@@ -611,6 +631,7 @@ The Listen integration has been supervised by [@thibaudgg][] and executed by [@M
 [@capotej]: https://github.com/capotej
 [@ches]: https://github.com/ches
 [@chrisberkhout]: https://github.com/chrisberkhout
+[@d1]: https://github.com/d1
 [@dgutov]: https://github.com/dgutov
 [@dnagir]: https://github.com/dnagir
 [@docwhat]: https://github.com/docwhat
@@ -639,12 +660,14 @@ The Listen integration has been supervised by [@thibaudgg][] and executed by [@M
 [@madtrick]: https://github.com/madtrick
 [@maio]: https://github.com/maio
 [@mattgreen]: https://github.com/mattgreen
+[@matthijsgroen]: https://github.com/matthijsgroen
 [@mcmire]: https://github.com/mcmire
 [@mislav]: https://github.com/mislav
 [@monocle]: https://github.com/monocle
 [@mordaroso]: https://github.com/mordaroso
 [@nestegg]: https://github.com/nestegg
 [@netzpirat]: https://github.com/netzpirat
+[@nickmabry]: https://github.com/nickmabry
 [@nicksieger]: https://github.com/nicksieger
 [@niklas]: https://github.com/niklas
 [@oliamb]: https://github.com/oliamb
@@ -667,6 +690,7 @@ The Listen integration has been supervised by [@thibaudgg][] and executed by [@M
 [@thibaudgg]: https://github.com/thibaudgg
 [@thierryhenrio]: https://github.com/thierryhenrio
 [@tinogomes]: https://github.com/tinogomes
+[@tomas-zemres]: https://github.com/tomas-zemres
 [@tpope]: https://github.com/tpope
 [@uk-ar]: https://github.com/uk-ar
 [@veged]: https://github.com/veged

data/README.md

@@ -101,8 +101,7 @@ end
 
 ### System notifications
 
-You can configure Guard to make use of the following system notification libraries, but it's strongly recommended
-to use either Ruby GNTP, Libnotify or Notifu:
+You can configure Guard to make use of the following system notification libraries:
 
 #### Ruby GNTP
 
@@ -219,13 +218,45 @@ group :development do
 end
 ```
 
+#### Terminal Title
+
+* Runs in every terminal supporting XTerm escape sequences to set the window title.
+
 #### Emacs
 
 * Runs on any platform with Emacs + emacsclient (http://www.emacswiki.org/emacs/EmacsClient)
 
-### Tmux
+### TMux
+
+* To use TMux notifications, you have to start Guard within a [TMux](http://tmux.sourceforge.net/) session.
+
+The TMux notifier will color the background of the left part of the
+status bar indicating the status of the notifications. Optionally you
+can set `:display_message => true` to display the Guard notification as
+'display-message' notification.
+
+The way these messages are formatted is configurable.
+
+```ruby
+# Guardfile
+notification :tmux,
+  :display_message => true,
+  :timeout => 5, # in seconds
+  :default_message_format => '%s >> %s',
+  # the first %s will show the title, the second the message
+  # Alternately you can also configure *success_message_format*,
+  # *pending_message_format*, *failed_message_format*
+  :line_separator => ' > ', # since we are single line we need a separator
+  :color_location => 'status-left-bg' # to customize which tmux element will change color
+```
+
+The result will be for RSpec using example above
+
+    RSpec >> 15 test, 0 failures > in 0.002 sec
+
+You can use nice powerline chars here if you have that configured.
 
-* To use Tmux notifications, you have to start Guard within a [tmux](http://tmux.sourceforge.net/) session.
+You can get the message history by using `Ctrl+b ~` (where `Ctrl+b` is your key to activate TMux).
 
 Add Guard plugins
 -----------------
@@ -457,82 +488,41 @@ read more about these files in the shared configuration section below.
 Interactions
 ------------
 
-You can interact with Guard and enter commands when Guard has nothing to do. Guard understands the following commands:
+Guard shows a [Pry](http://pryrepl.org/) console whenever it has nothing to do and comes with some Guard specific Pry
+commands:
 
-* `↩`:                 Run all plugins.
-* `h`, `help`:         Show a help of the available interactor commands.
-* `r`, `reload`:       Reload all plugins.
-* `c`, `change`:       Trigger a file change to the plugins.
-* `s`, `show`:         Show the plugin configurations.
-* `n`, `notification`: Toggle system notifications on and off.
-* `p`, `pause`:        Toggles the file modification listener. The prompt will change to `p>` when paused.
-                       This is useful when switching Git branches, rebase Git or change whitespace.
-* `e`, `exit`:         Stop all plugins and quit Guard.
+ * `↩`, `a`, `all`: Run all plugins.
+ * `h`, `help`: Show help for all interactor commands.
+ * `c`, `change`: Trigger a file change.
+ * `n`, `notification`: Toggles the notifications.
+ * `p`, `pause`: Toggles the file listener.
+ * `r`, `reload`: Reload all plugins.
+ * `s`, `show`: Show all Guard plugins.
+ * `e`, `exit`: Stop all plugins and quit Guard
 
-Instead of running all plugins with the `↩` key, you can also run a single plugin by entering its name:
+The `all` and `reload` commands supports an optional scope, so you limit the Guard action to either a Guard plugin or
+a Guard group like:
 
 ```bash
-> rspec
+[1]  guard(main)> all rspec
+[2]  guard(main)> all frontend
 ```
 
-It's also possible to run all plugins within a group by entering the group name:
+Remember, you can always use `help` on the Pry command line to see all available commands and `help <command>` for
+more detailed information. `help guard` will show all Guard related commands available
 
-```bash
-> frontend
-```
+Pry supports the Ruby built-in Readline, [rb-readline](https://github.com/luislavena/rb-readline) and
+[Coolline](https://github.com/Mon-Ouie/coolline). Just install the readline implementation of your choice by adding it
+to your `Gemfile.
 
-The same applies to reloading. You can reload a plugin with the following command:
+You can also disable the interactions completely by running Guard with the `--no-interactions` option.
 
-```bash
-> ronn reload
-```
-
-This will reload only the Ronn plugin. You can also reload all plugins within a group:
-
-```bash
-> backend reload
-```
-
-The action and plugin/group name can have any order, so you can also write:
-
-```bash
-> reload backend
-```
-
-You can pass a list of filenames to the `change` command to trigger manually a file modification:
-
-```bash
-> change spec/guard_spec.rb
-```
+### Customizations
 
-### Readline support
-
-With Readline enabled, you'll see a command prompt `>` when Guard is ready to accept a command. The command line
-supports history navigation with the `↑` and `↓` arrow keys, and command auto-completion with the `⇥` key.
-
-Unfortunately Readline [does not work on MRI](http://bugs.ruby-lang.org/issues/5539) on Mac OS X by default. You can
-work around the issue by installing a pure Ruby implementation:
-
-```ruby
-platforms :ruby do
-  gem 'rb-readline'
-end
-```
-
-Guard will automatically enable Readline support if your environment supports it, but you can disable Readline with the
-`interactor` DSL method or turn off completely with the `--no-interactions` option.
-
-### Coolline support
-
-With Ruby 1.9.3 you can use a [Coolline](https://github.com/Mon-Ouie/coolline) based interactor, which uses the new
-`io/console` from stdlib. Just add it to your `Gemfile`
-
-```ruby
-gem 'coolline'
-```
-
-Guard will automatically enable Coolline support if your environment supports it, but you can disable Coolline with the
-`interactor` DSL method or turn off completely with the `--no-interactions` option.
+Further Guard specific customizations can be made in `~/.guardrc` that will be evaluated prior the Pry session is
+started. This allows you to make use of the Pry plugin architecture to provide custom commands and extend Guard for
+your own needs and distribute as a gem. Please have a look at the [Pry Wiki](https://github.com/pry/pry/wiki) for more
+information.
 
 ### Signals
 
@@ -683,15 +673,7 @@ notification :off
 
 ### interactor
 
-You can disable the interactor auto detection and select a specific implementation:
-
-```ruby
-interactor :coolline
-interactor :readline
-interactor :simple
-```
-
-If you do not need the keyboard interactions with Guard at all, you can turn them off:
+If you do not need the Pry interactions with Guard at all, you can turn it off:
 
 ```ruby
 interactor :off
@@ -744,6 +726,30 @@ Please note that method only accept regexps. More on the
 filter /\.txt$/, /.*\.zip/
 ```
 
+### logger
+
+The `logger` method allows you to customize the Guard log output to your needs by specifying one or more options like:
+
+```ruby
+logger :level       => :warn,
+       :template    => '[:severity - :time - :progname] :message',
+       :time_format => 'at %I:%M%p',
+       :only        => [:rspec, :jasmine, 'coffeescript'],
+       :except      => :jammit
+```
+
+Log `:level` option must be either `:debug`, `:info`, `:warn` or `:error`. If Guard is started in debug mode, the log
+level will be automatically set to `:debug`.
+
+The `:template` option is a string which can have one or more of the following placeholders: `:time`, `:severity`,
+`:progname`, `:pid`, `:unit_of_work_id` and `:message`. A unit of work is assigned for each action Guard performs on
+multiple Guard plugin.
+
+The `:time_format` option directives are the same as Time#strftime or can be `:milliseconds`
+
+The `:only` and `:except` are either a string or a symbol, or an array of strings or symbols that matches the name of
+the Guard plugin name that sends the log message. They cannot be specified at the same time.
+
 ### Example
 
 ```ruby

data/lib/guard.rb

@@ -54,13 +54,16 @@ module Guard
       setup_listener
       setup_signal_traps
 
-      debug_command_execution if @options[:debug]
-
       ::Guard::Dsl.evaluate_guardfile(options)
       ::Guard::UI.error 'No guards found in Guardfile, please add at least one.' if @guards.empty?
 
       runner.deprecation_warning if @options[:show_deprecations]
 
+      if @options[:debug]
+        ::Guard::UI.options[:level] = :debug
+        debug_command_execution
+      end
+      
       setup_notifier
       setup_interactor
 
@@ -130,7 +133,7 @@ module Guard
     #
     def setup_interactor
       unless options[:no_interactions]
-        @interactor = ::Guard::Interactor.fabricate
+        @interactor = ::Guard::Interactor.new
       end
     end
 

data/lib/guard/cli.rb

@@ -21,13 +21,13 @@ module Guard
                   :type    => :boolean,
                   :default => false,
                   :aliases => '-c',
-                  :banner  => 'Auto clear shell before each change/run_all/reload'
+                  :banner  => 'Auto clear shell before each action'
 
     method_option :notify,
                   :type    => :boolean,
                   :default => true,
                   :aliases => '-n',
-                  :banner  => 'Notifications feature (growl/libnotify)'
+                  :banner  => 'Notifications feature'
 
     method_option :debug,
                   :type    => :boolean,

data/lib/guard/commands/all.rb

@@ -0,0 +1,34 @@
+module Guard
+  class Interactor
+
+    ALL = Pry::CommandSet.new do
+      create_command 'all' do
+
+        group 'Guard'
+        description 'Run all plugins.'
+
+        banner <<-BANNER
+          Usage: all <scope>
+
+          Run the Guard plugin `run_all` action.
+
+          You may want to specify an optional scope to the action,
+          either the name of a Guard plugin or a plugin group.
+        BANNER
+
+        def process(*entries)
+          scopes, rest = ::Guard::Interactor.convert_scope(entries)
+
+          if rest.length == 0
+            ::Guard.run_all scopes
+          else
+            output.puts "Unkown scope #{ rest.join(', ') }"
+          end
+        end
+      end
+    end
+
+  end
+end
+
+Pry.commands.import ::Guard::Interactor::ALL

data/lib/guard/commands/change.rb

@@ -0,0 +1,37 @@
+module Guard
+  class Interactor
+
+    CHANGE = Pry::CommandSet.new do
+      create_command 'change' do
+
+        group 'Guard'
+        description 'Trigger a file change.'
+
+        banner <<-BANNER
+          Usage: change <scope>
+
+          Runs the Guard plugin `run_on_changes` action.
+
+          You may want to specify an optional scope to the action,
+          either the name of a Guard plugin or a plugin group.
+        BANNER
+
+        def process(*entries)
+          scopes, rest = ::Guard::Interactor.convert_scope(entries)
+
+          if rest.length != 0
+            ::Guard.within_preserved_state do
+              ::Guard.runner.run_on_changes(rest, [], [])
+            end
+          else
+            output.puts 'Please specify a file.'
+          end
+        end
+
+      end
+    end
+
+  end
+end
+
+Pry.commands.import ::Guard::Interactor::CHANGE

data/lib/guard/commands/notification.rb

@@ -0,0 +1,27 @@
+require 'guard/notifier'
+
+module Guard
+  class Interactor
+
+     NOTIFICATION = Pry::CommandSet.new do
+      create_command 'notification' do
+
+        group 'Guard'
+        description 'Toggles the notifications.'
+
+        banner <<-BANNER
+          Usage: notification
+
+          Toggles the notifications on and off.
+        BANNER
+
+        def process
+          ::Guard::Notifier.toggle
+        end
+      end
+    end
+
+  end
+end
+
+Pry.commands.import ::Guard::Interactor::NOTIFICATION

data/lib/guard/commands/pause.rb

@@ -0,0 +1,28 @@
+module Guard
+  class Interactor
+
+    PAUSE = Pry::CommandSet.new do
+      create_command 'pause' do
+
+        group 'Guard'
+        description 'Toggles the file listener.'
+
+        banner <<-BANNER
+          Usage: pause
+
+          Toggles the file listener on and off.
+
+          When the file listener is paused, the default Guard Pry
+          prompt will show the pause sign `[p]`.
+        BANNER
+
+        def process
+          ::Guard.pause
+        end
+      end
+    end
+
+  end
+end
+
+Pry.commands.import ::Guard::Interactor::PAUSE