guard 0.7.0 → 0.8.0

data/lib/guard/listeners/darwin.rb

@@ -1,41 +1,60 @@
 module Guard
+
+  # Listener implementation for Mac OS X `FSEvents`.
+  #
   class Darwin < Listener
 
+    # Initialize the Listener.
+    #
     def initialize(*)
       super
       @fsevent = FSEvent.new
     end
 
-    def worker
-      @fsevent
-    end
-
+    # Start the listener.
+    #
     def start
       super
       worker.run
     end
 
+    # Stop the listener.
+    #
     def stop
       super
       worker.stop
     end
 
+    # Check if the listener is usable on the current OS.
+    #
+    # @return [Boolean] whether usable or not
+    #
     def self.usable?
       require 'rb-fsevent'
       if !defined?(FSEvent::VERSION) || (defined?(Gem::Version) &&
           Gem::Version.new(FSEvent::VERSION) < Gem::Version.new('0.4.0'))
-        UI.info "Please update rb-fsevent (>= 0.4.0)"
+        UI.info 'Please update rb-fsevent (>= 0.4.0)'
         false
       else
         true
       end
     rescue LoadError
-      UI.info "Please install rb-fsevent gem for Mac OSX FSEvents support"
+      UI.info 'Please install rb-fsevent gem for Mac OSX FSEvents support'
       false
     end
 
-  private
+    private
+
+    # Get the listener worker.
+    #
+    def worker
+      @fsevent
+    end
 
+    # Watch the given directory for file changes.
+    #
+    # @param [String] directory the directory to watch
+    #
     def watch(directory)
       worker.watch(directory) do |modified_dirs|
         files = modified_files(modified_dirs)

data/lib/guard/listeners/linux.rb

@@ -1,6 +1,11 @@
 module Guard
+
+  # Listener implementation for Linux `inotify`.
+  #
   class Linux < Listener
 
+    # Initialize the Listener.
+    #
     def initialize(*)
       super
       @inotify = INotify::Notifier.new
@@ -8,44 +13,53 @@ module Guard
       @latency = 0.5
     end
 
+    # Start the listener.
+    #
     def start
       @stop = false
       super
       watch_change unless watch_change?
     end
 
+    # Stop the listener.
+    #
     def stop
       super
       @stop = true
       sleep(@latency)
     end
 
+    # Check if the listener is usable on the current OS.
+    #
+    # @return [Boolean] whether usable or not
+    #
     def self.usable?
       require 'rb-inotify'
       if !defined?(INotify::VERSION) || (defined?(Gem::Version) &&
           Gem::Version.new(INotify::VERSION.join('.')) < Gem::Version.new('0.8.5'))
-        UI.info "Please update rb-inotify (>= 0.8.5)"
+        UI.info 'Please update rb-inotify (>= 0.8.5)'
         false
       else
         true
       end
     rescue LoadError
-      UI.info "Please install rb-inotify gem for Linux inotify support"
+      UI.info 'Please install rb-inotify gem for Linux inotify support'
       false
     end
 
-    def watch_change?
-      !!@watch_change
-    end
-
-  private
+    private
 
+    # Get the listener worker.
+    #
     def worker
       @inotify
     end
 
+    # Watch the given directory for file changes.
+    #
+    # @param [String] directory the directory to watch
+    #
     def watch(directory)
-      # The event selection is based on https://github.com/guard/guard/wiki/Analysis-of-inotify-events-for-different-editors
       worker.watch(directory, :recursive, :attrib, :create, :move_self, :close_write) do |event|
         unless event.name == "" # Event on root directory
           @files << event.absolute_name
@@ -54,6 +68,16 @@ module Guard
     rescue Interrupt
     end
 
+    # Test if inotify is watching for changes.
+    #
+    # @return [Boolean] whether inotify is active or not
+    #
+    def watch_change?
+      !!@watch_change
+    end
+
+    # Watch for file system changes.
+    #
     def watch_change
       @watch_change = true
       until @stop

data/lib/guard/listeners/polling.rb

@@ -1,24 +1,46 @@
 module Guard
+
+  # Polling listener that works cross-platform and
+  # has no dependencies. This is the listener that
+  # uses the most CPU processing power and has higher
+  # file IO that the other implementations.
+  #
   class Polling < Listener
 
+    # Initialize the Listener.
+    #
     def initialize(*)
       super
       @latency = 1.5
     end
 
+    # Start the listener.
+    #
     def start
       @stop = false
       super
       watch_change
     end
 
+    # Stop the listener.
+    #
     def stop
       super
       @stop = true
     end
 
-  private
+    # Watch the given directory for file changes.
+    #
+    # @param [String] directory the directory to watch
+    #
+    def watch(directory)
+      @existing = all_files
+    end
+
+    private
 
+    # Watch for file system changes.
+    #
     def watch_change
       until @stop
         start = Time.now.to_f
@@ -29,9 +51,5 @@ module Guard
       end
     end
 
-    def watch(directory)
-      @existing = all_files
-    end
-
   end
 end

data/lib/guard/listeners/windows.rb

@@ -1,35 +1,48 @@
 module Guard
+
+  # Listener implementation for Windows `fchange`.
+  #
   class Windows < Listener
 
+    # Initialize the Listener.
+    #
     def initialize(*)
       super
       @fchange = FChange::Notifier.new
     end
 
+    # Start the listener.
+    #
     def start
       super
       worker.run
     end
 
+    # Stop the listener.
+    #
     def stop
       super
       worker.stop
     end
 
+    # Check if the listener is usable on the current OS.
+    #
+    # @return [Boolean] whether usable or not
+    #
     def self.usable?
       require 'rb-fchange'
       true
     rescue LoadError
-      UI.info "Please install rb-fchange gem for Windows file events support"
+      UI.info 'Please install rb-fchange gem for Windows file events support'
       false
     end
 
-  private
-
-    def worker
-      @fchange
-    end
+    private
 
+    # Watch the given directory for file changes.
+    #
+    # @param [String] directory the directory to watch
+    #
     def watch(directory)
       worker.watch(directory, :all_events, :recursive) do |event|
         paths = [File.expand_path(event.watcher.path)]
@@ -38,5 +51,11 @@ module Guard
       end
     end
 
+    # Get the listener worker.
+    #
+    def worker
+      @fchange
+    end
+
   end
 end

data/lib/guard/notifier.rb

@@ -3,13 +3,29 @@ require 'pathname'
 require 'guard/ui'
 
 module Guard
+
+  # The notifier class handles cross-platform system notifications that supports:
+  #
+  # - Growl on Mac OS X
+  # - Libnotify on Linux
+  # - Notifu on Windows
+  #
   module Notifier
+
+    # Application name as shown in the specific notification settings
     APPLICATION_NAME = "Guard"
 
+    # Turn notifications off.
+    #
     def self.turn_off
       ENV["GUARD_NOTIFY"] = 'false'
     end
 
+    # Turn notifications on. This tries to load the platform
+    # specific notification library.
+    #
+    # @return [Boolean] whether the notification could be enabled.
+    #
     def self.turn_on
       ENV["GUARD_NOTIFY"] = 'true'
       case RbConfig::CONFIG['target_os']
@@ -22,6 +38,14 @@ module Guard
       end
     end
 
+    # Show a message with the system notification.
+    #
+    # @see .image_path
+    #
+    # @param [String] the message to show
+    # @option options [Symbol, String] image the image symbol or path to an image
+    # @option options [String] title the notification title
+    #
     def self.notify(message, options = {})
       if enabled?
         image = options.delete(:image) || :success
@@ -38,13 +62,24 @@ module Guard
       end
     end
 
+    # Test if the notifications are enabled and available.
+    #
+    # @return [Boolean] whether the notifications are available
+    #
     def self.enabled?
       ENV["GUARD_NOTIFY"] == 'true'
     end
 
   private
 
-    def self.notify_mac(title, message, image, options)
+    # Send a message to Growl either with the `growl` gem or the `growl_notify` gem.
+    #
+    # @param [String] title the notification title
+    # @param [String] message the message to show
+    # @param [Symbol, String] the image to user
+    # @param [Hash] options the growl options
+    #
+    def self.notify_mac(title, message, image, options = {})
       require_growl # need for guard-rspec formatter that is called out of guard scope
 
       default_options = { :title => title, :icon => image_path(image), :name => APPLICATION_NAME }
@@ -61,18 +96,43 @@ module Guard
       end
     end
 
-    def self.notify_linux(title, message, image, options)
+    # Send a message to libnotify.
+    #
+    # @param [String] title the notification title
+    # @param [String] message the message to show
+    # @param [Symbol, String] the image to user
+    # @param [Hash] options the libnotify options
+    #
+    def self.notify_linux(title, message, image, options = {})
       require_libnotify # need for guard-rspec formatter that is called out of guard scope
       default_options = { :body => message, :summary => title, :icon_path => image_path(image), :transient => true }
       Libnotify.show default_options.merge(options) if enabled?
     end
 
-    def self.notify_windows(title, message, image, options)
+    # Send a message to notifu.
+    #
+    # @param [String] title the notification title
+    # @param [String] message the message to show
+    # @param [Symbol, String] the image to user
+    # @param [Hash] options the notifu options
+    #
+    def self.notify_windows(title, message, image, options = {})
       require_rbnotifu # need for guard-rspec formatter that is called out of guard scope
       default_options = { :message => message, :title => title, :type => image_level(image), :time => 3 }
       Notifu.show default_options.merge(options) if enabled?
     end
 
+    # Get the image path for an image symbol.
+    #
+    # Known symbols are:
+    #
+    # - failed
+    # - pending
+    # - success
+    #
+    # @param [Symbol] image the image name
+    # @return [String] the image path
+    #
     def self.image_path(image)
       images_path = Pathname.new(File.dirname(__FILE__)).join('../../images')
       case image
@@ -88,6 +148,11 @@ module Guard
       end
     end
 
+    # The notification level type for the given image.
+    #
+    # @param [Symbol] image the image
+    # @return [Symbol] the level
+    #
     def self.image_level(image)
       case image
       when :failed
@@ -101,6 +166,9 @@ module Guard
       end
     end
 
+    # Try to safely load growl and turns notifications
+    # off on load failure.
+    #
     def self.require_growl
       begin
         require 'growl_notify'
@@ -119,6 +187,9 @@ module Guard
       UI.info "Please install growl_notify or growl gem for Mac OS X notification support and add it to your Gemfile"
     end
 
+    # Try to safely load libnotify and turns notifications
+    # off on load failure.
+    #
     def self.require_libnotify
       require 'libnotify'
     rescue LoadError
@@ -126,11 +197,15 @@ module Guard
       UI.info "Please install libnotify gem for Linux notification support and add it to your Gemfile"
     end
 
+    # Try to safely load rb-notifu and turns notifications
+    # off on load failure.
+    #
     def self.require_rbnotifu
       require 'rb-notifu'
     rescue LoadError
       turn_off
       UI.info "Please install rb-notifu gem for Windows notification support and add it to your Gemfile"
     end
+
   end
 end

data/lib/guard/ui.rb

@@ -1,88 +1,88 @@
 module Guard
-  module UI
-
-    ANSI_ESCAPE_BRIGHT = "1"
-
-    ANSI_ESCAPE_BLACK = "30"
-    ANSI_ESCAPE_RED = "31"
-    ANSI_ESCAPE_GREEN = "32"
-    ANSI_ESCAPE_YELLOW = "33"
-    ANSI_ESCAPE_BLUE = "34"
-    ANSI_ESCAPE_MAGENTA = "35"
-    ANSI_ESCAPE_CYAN = "36"
-    ANSI_ESCAPE_WHITE = "37"
-
-    ANSI_ESCAPE_BGBLACK = "40"
-    ANSI_ESCAPE_BGRED = "41"
-    ANSI_ESCAPE_BGGREEN = "42"
-    ANSI_ESCAPE_BGYELLOW = "43"
-    ANSI_ESCAPE_BGBLUE = "44"
-    ANSI_ESCAPE_BGMAGENTA = "45"
-    ANSI_ESCAPE_BGCYAN = "46"
-    ANSI_ESCAPE_BGWHITE = "47"
 
+  # The UI class helps to format messages for the user.
+  #
+  module UI
     class << self
 
       color_enabled = nil
 
-      def info(message, options = {})
-        unless ENV["GUARD_ENV"] == "test"
+      # Show an info message.
+      #
+      # @param [String] message the message to show
+      # @option options [Boolean] reset whether to clean the output before
+      #
+      def info(message, options = { })
+        unless ENV['GUARD_ENV'] == 'test'
           reset_line if options[:reset]
           puts color(message) if message != ''
         end
       end
 
-      def error(message, options={})
-        unless ENV["GUARD_ENV"] == "test"
+      # Show a red error message that is prefixed with ERROR.
+      #
+      # @param [String] message the message to show
+      # @option options [Boolean] reset whether to clean the output before
+      #
+      def error(message, options = { })
+        unless ENV['GUARD_ENV'] == 'test'
           reset_line if options[:reset]
           puts color('ERROR: ', :red) + message
         end
       end
 
-      def deprecation(message, options = {})
-        unless ENV["GUARD_ENV"] == "test"
+      # Show a red deprecation message that is prefixed with DEPRECATION.
+      #
+      # @param [String] message the message to show
+      # @option options [Boolean] reset whether to clean the output before
+      #
+      def deprecation(message, options = { })
+        unless ENV['GUARD_ENV'] == 'test'
           reset_line if options[:reset]
           puts color('DEPRECATION: ', :red) + message
         end
       end
 
-      def debug(message, options={})
-        unless ENV["GUARD_ENV"] == "test"
+      # Show a debug message that is prefixed with DEBUG and a timestamp.
+      #
+      # @param [String] message the message to show
+      # @option options [Boolean] reset whether to clean the output before
+      #
+      def debug(message, options = { })
+        unless ENV['GUARD_ENV'] == 'test'
           reset_line if options[:reset]
           puts color("DEBUG (#{Time.now.strftime('%T')}): ", :yellow) + message if ::Guard.options && ::Guard.options[:debug]
         end
       end
 
+      # Reset a line.
+      #
       def reset_line
         print(color_enabled? ? "\r\e[0m" : "\r\n")
       end
 
+      # Clear the output.
+      #
       def clear
-        system("clear;")
+        system('clear;')
       end
 
-    private
+      private
 
+      # Reset a color sequence.
+      #
       # @deprecated
+      # @param [String] text the text
+      #
       def reset_color(text)
-        deprecation('UI.reset_color(text) is deprecated, please use color(text, "") instead.')
-        color(text, "")
-      end
-
-      def color(text, *color_options)
-        color_code = ""
-        color_options.each do |color_option|
-          color_option = color_option.to_s
-          if color_option != ""
-            if !(color_option =~ /\d+/)
-              color_option = const_get("ANSI_ESCAPE_#{color_option.upcase}")
-            end
-            color_code += ";" + color_option
-          end
-        end
-        color_enabled? ? "\e[0#{color_code}m#{text}\e[0m" : text
+        deprecation('UI.reset_color(text) is deprecated, please use color(text, ' ') instead.')
+        color(text, '')
       end
 
+      # Checks if color output can be enabled.
+      #
+      # @return [Boolean] whether color is enabled or not
+      #
       def color_enabled?
         if @color_enabled.nil?
           if RbConfig::CONFIG['target_os'] =~ /mswin|mingw/i
@@ -102,9 +102,87 @@ module Guard
             @color_enabled = true
           end
         end
+
         @color_enabled
       end
 
+      # Colorizes a text message. See the constant in the UI class for possible
+      # color_options parameters. You can pass optionally :bright, a foreground
+      # color and a background color.
+      #
+      # @example
+      #
+      #   color('Hello World', :red, :bright)
+      #
+      # @param [String] the text to colorize
+      # @param [Array] color_options the color options
+      #
+      def color(text, *color_options)
+        color_code = ''
+        color_options.each do |color_option|
+          color_option = color_option.to_s
+          if color_option != ''
+            if !(color_option =~ /\d+/)
+              color_option = const_get("ANSI_ESCAPE_#{ color_option.upcase }")
+            end
+            color_code += ';' + color_option
+          end
+        end
+        color_enabled? ? "\e[0#{ color_code }m#{ text }\e[0m" : text
+      end
+
     end
+
+    # Brighten the color
+    ANSI_ESCAPE_BRIGHT    = '1'
+
+    # Black foreground color
+    ANSI_ESCAPE_BLACK     = '30'
+
+    # Red foreground color
+    ANSI_ESCAPE_RED       = '31'
+
+    # Green foreground color
+    ANSI_ESCAPE_GREEN     = '32'
+
+    # Yellow foreground color
+    ANSI_ESCAPE_YELLOW    = '33'
+
+    # Blue foreground color
+    ANSI_ESCAPE_BLUE      = '34'
+
+    # Magenta foreground color
+    ANSI_ESCAPE_MAGENTA   = '35'
+
+    # Cyan foreground color
+    ANSI_ESCAPE_CYAN      = '36'
+
+    # White foreground color
+    ANSI_ESCAPE_WHITE     = '37'
+
+    # Black background color
+    ANSI_ESCAPE_BGBLACK   = '40'
+
+    # Red background color
+    ANSI_ESCAPE_BGRED     = '41'
+
+    # Green background color
+    ANSI_ESCAPE_BGGREEN   = '42'
+
+    # Yellow background color
+    ANSI_ESCAPE_BGYELLOW  = '43'
+
+    # Blue background color
+    ANSI_ESCAPE_BGBLUE    = '44'
+
+    # Magenta background color
+    ANSI_ESCAPE_BGMAGENTA = '45'
+
+    # Cyan background color
+    ANSI_ESCAPE_BGCYAN    = '46'
+
+    # White background color
+    ANSI_ESCAPE_BGWHITE   = '47'
+
   end
 end