guard 1.8.3 → 2.0.0.pre

data/lib/guard/notifier.rb

@@ -2,9 +2,23 @@ require 'yaml'
 require 'rbconfig'
 require 'pathname'
 
+require 'guard/ui'
+require 'guard/notifiers/emacs'
+require 'guard/notifiers/file_notifier'
+require 'guard/notifiers/gntp'
+require 'guard/notifiers/growl_notify'
+require 'guard/notifiers/growl'
+require 'guard/notifiers/libnotify'
+require 'guard/notifiers/notifysend'
+require 'guard/notifiers/rb_notifu'
+require 'guard/notifiers/terminal_notifier'
+require 'guard/notifiers/terminal_title'
+require 'guard/notifiers/tmux'
+
 module Guard
 
-  # The notifier handles sending messages to different notifiers. Currently the following
+  # The notifier handles sending messages to different notifiers. Currently the
+  # following
   # libraries are supported:
   #
   # * Ruby GNTP
@@ -17,7 +31,8 @@ module Guard
   # * Terminal Title
   # * Tmux
   #
-  # Please see the documentation of each notifier for more information about the requirements
+  # Please see the documentation of each notifier for more information about
+  # the requirements
   # and configuration possibilities.
   #
   # Guard knows four different notification types:
@@ -33,80 +48,59 @@ module Guard
   # `gntp` and `growl_notify` notifiers are able to register these types
   # at Growl and allows customization of each notification type.
   #
-  # Guard can be configured to make use of more than one notifier at once, @see Guard::Dsl
+  # Guard can be configured to make use of more than one notifier at once.
+  #
+  # @see Guard::Dsl
   #
   module Notifier
 
-    require 'guard'
-    require 'guard/ui'
-    require 'guard/notifiers/gntp'
-    require 'guard/notifiers/growl'
-    require 'guard/notifiers/growl_notify'
-    require 'guard/notifiers/libnotify'
-    require 'guard/notifiers/notifysend'
-    require 'guard/notifiers/rb_notifu'
-    require 'guard/notifiers/emacs'
-    require 'guard/notifiers/terminal_notifier'
-    require 'guard/notifiers/terminal_title'
-    require 'guard/notifiers/tmux'
-    require 'guard/notifiers/file_notifier'
-
     extend self
 
-    # List of available notifiers, grouped by functionality. It needs to be a nested hash instead of
-    # a simpler Hash, because it maintains its order on Ruby 1.8.7 also.
+    # List of available notifiers, grouped by functionality
     NOTIFIERS = [
-      [
-        [:gntp,              ::Guard::Notifier::GNTP],
-        [:growl,             ::Guard::Notifier::Growl],
-        [:growl_notify,      ::Guard::Notifier::GrowlNotify],
-        [:terminal_notifier, ::Guard::Notifier::TerminalNotifier],
-        [:libnotify,         ::Guard::Notifier::Libnotify],
-        [:notifysend,        ::Guard::Notifier::NotifySend],
-        [:notifu,            ::Guard::Notifier::Notifu]
-      ],
-      [[:emacs,             ::Guard::Notifier::Emacs]],
-      [[:tmux,              ::Guard::Notifier::Tmux]],
-      [[:terminal_title,    ::Guard::Notifier::TerminalTitle]],
-      [[:file,              ::Guard::Notifier::FileNotifier]]
+      {
+        gntp: GNTP,
+        growl: Growl,
+        growl_notify: GrowlNotify,
+        terminal_notifier: TerminalNotifier,
+        libnotify: Libnotify,
+        notifysend: NotifySend,
+        notifu: Notifu
+      },
+      { emacs: Emacs },
+      { tmux: Tmux },
+      { terminal_title: TerminalTitle },
+      { file: FileNotifier }
     ]
 
-    # Get the available notifications.
-    #
-    # @return [Hash] the notifications
-    #
-    def notifications
-      ENV['GUARD_NOTIFICATIONS'] ? YAML::load(ENV['GUARD_NOTIFICATIONS']) : []
+    def notifiers
+      ENV['GUARD_NOTIFIERS'] ? YAML::load(ENV['GUARD_NOTIFIERS']) : []
     end
 
-    # Set the available notifications.
-    #
-    # @param [Array<Hash>] notifications the notifications
-    #
-    def notifications=(notifications)
-      ENV['GUARD_NOTIFICATIONS'] = YAML::dump(notifications)
+    def notifiers=(notifiers)
+      ENV['GUARD_NOTIFIERS'] = YAML::dump(notifiers)
     end
 
     # Clear available notifications.
     #
-    def clear_notifications
-      ENV['GUARD_NOTIFICATIONS'] = nil
+    def clear_notifiers
+      ENV['GUARD_NOTIFIERS'] = nil
     end
 
-    # Turn notifications on. If no notifications are defined
-    # in the `Guardfile` Guard auto detects the first available
-    # library.
+    # Turn notifications on. If no notifications are defined in the `Guardfile`
+    # Guard auto detects the first available library.
     #
     def turn_on
-      auto_detect_notification if notifications.empty? && (!::Guard.options || ::Guard.options[:notify])
+      _auto_detect_notification if notifiers.empty? && (!::Guard.options || ::Guard.options.notify)
 
-      if notifications.empty?
-        ENV['GUARD_NOTIFY'] = 'false'
+      if notifiers.empty?
+        turn_off
       else
-        notifications.each do |notification|
-          ::Guard::UI.info "Guard is using #{ get_notifier_module(notification[:name]).to_s.split('::').last } to send notifications."
-          notifier = get_notifier_module(notification[:name])
-          notifier.turn_on(notification[:options]) if notifier.respond_to?(:turn_on)
+        notifiers.each do |notifier|
+          notifier_class = _get_notifier_module(notifier[:name])
+          ::Guard::UI.info "Guard is using #{ notifier_class.title } to send notifications."
+
+          notifier_class.turn_on if notifier_class.respond_to?(:turn_on)
         end
 
         ENV['GUARD_NOTIFY'] = 'true'
@@ -116,9 +110,10 @@ module Guard
     # Turn notifications off.
     #
     def turn_off
-      notifications.each do |notification|
-        notifier = get_notifier_module(notification[:name])
-        notifier.turn_off(notification[:options]) if notifier.respond_to?(:turn_off)
+      notifiers.each do |notifier|
+        notifier_class = _get_notifier_module(notifier[:name])
+
+        notifier_class.turn_off if notifier_class.respond_to?(:turn_off)
       end
 
       ENV['GUARD_NOTIFY'] = 'false'
@@ -127,7 +122,7 @@ module Guard
     # Toggle the system notifications on/off
     #
     def toggle
-      if ENV['GUARD_NOTIFY'] == 'true'
+      if enabled?
         ::Guard::UI.info 'Turn off notifications'
         turn_off
       else
@@ -146,17 +141,17 @@ module Guard
     # Add a notification library to be used.
     #
     # @param [Symbol] name the name of the notifier to use
-    # @param [Boolean] silent disable any error message
     # @param [Hash] options the notifier options
+    # @option options [String] silent disable any error message
     # @return [Boolean] if the notification could be added
     #
-    def add_notification(name, options = { }, silent = false)
+    def add_notifier(name, opts = {})
       return turn_off if name == :off
 
-      notifier = get_notifier_module(name)
+      notifier_class = _get_notifier_module(name)
 
-      if notifier && notifier.available?(silent, options)
-        self.notifications = notifications << { :name => name, :options => options }
+      if notifier_class && notifier_class.available?(opts)
+        self.notifiers = notifiers << { name: name, options: opts }
         true
       else
         false
@@ -166,21 +161,19 @@ module Guard
     # Show a system notification with all configured notifiers.
     #
     # @param [String] message the message to show
-    # @option options [Symbol, String] image the image symbol or path to an image
-    # @option options [String] title the notification title
+    # @option opts [Symbol, String] image the image symbol or path to an image
+    # @option opts [String] title the notification title
     #
-    def notify(message, options = { })
-      if enabled?
-        type  = notification_type(options[:image] || :success)
-        image = image_path(options.delete(:image) || :success)
-        title = options.delete(:title) || 'Guard'
+    def notify(message, opts = {})
+      return unless enabled?
+
+      notifiers.each do |notifier|
+        notifier = _get_notifier_module(notifier[:name]).new(notifier[:options])
 
-        notifications.each do |notification|
-          begin
-            get_notifier_module(notification[:name]).notify(type, title, message, image, options.merge(notification[:options]))
-          rescue Exception => e
-            ::Guard::UI.error "Error sending notification with #{ notification[:name] }: #{ e.message }"
-          end
+        begin
+          notifier.notify(message, opts)
+        rescue Exception => e
+          ::Guard::UI.error "Error sending notification with #{ notifier.name }: #{ e.message }"
         end
       end
     end
@@ -192,78 +185,31 @@ module Guard
     # @param [Symbol] name the notifier name
     # @return [Module] the notifier module
     #
-    def get_notifier_module(name)
-      notifier = NOTIFIERS.flatten(1).detect { |n| n.first == name }
-      notifier ? notifier.last : notifier
+    def _get_notifier_module(name)
+      NOTIFIERS.each do |group|
+        if notifier = group.find { |n, _| n == name }
+          return notifier.last
+        end
+      end
+
+      nil
     end
 
     # Auto detect the available notification library. This goes through
     # the list of supported notification gems and picks the first that
     # is available in each notification group.
     #
-    def auto_detect_notification
+    def _auto_detect_notification
+      self.notifiers = []
       available = nil
-      self.notifications = []
 
       NOTIFIERS.each do |group|
-        added = group.map { |n| n.first }.find { |notifier| add_notification(notifier, { }, true) }
-        available = available || added
+        notifier_added = group.find { |name, klass| add_notifier(name, silent: true) }
+        available ||= notifier_added
       end
 
       ::Guard::UI.info('Guard could not detect any of the supported notification libraries.') unless available
     end
-
-    # Get the image path for an image symbol for the following
-    # known image types:
-    #
-    # - failed
-    # - pending
-    # - success
-    #
-    # If the image is not a known symbol, it will be returned unmodified.
-    #
-    # @param [Symbol, String] image the image symbol or path to an image
-    # @return [String] the image path
-    #
-    def image_path(image)
-      case image
-        when :failed
-          images_path.join('failed.png').to_s
-        when :pending
-          images_path.join('pending.png').to_s
-        when :success
-          images_path.join('success.png').to_s
-        else
-          image
-      end
-    end
-
-    # Paths where all Guard images are located
-    #
-    # @return [Pathname] the path to the images directory
-    #
-    def images_path
-      @images_path ||= Pathname.new(File.dirname(__FILE__)).join('../../images')
-    end
-
-    # Get the notification type depending on the
-    # image that has been selected for the notification.
-    #
-    # @param [Symbol, String] image the image symbol or path to an image
-    # @return [String] the notification type
-    #
-    def notification_type(image)
-      case image
-        when :failed
-          'failed'
-        when :pending
-          'pending'
-        when :success
-          'success'
-        else
-          'notify'
-      end
-    end
   end
 
 end

data/lib/guard/notifiers/base.rb

@@ -0,0 +1,220 @@
+require 'rbconfig'
+require 'guard/ui'
+
+module Guard
+  module Notifier
+
+    # Base class for all notifiers.
+    #
+    class Base
+
+      HOSTS = {
+        darwin:  'Mac OS X',
+        linux:   'Linux',
+        freebsd: 'FreeBSD',
+        openbsd: 'OpenBSD',
+        sunos:   'SunOS',
+        solaris: 'Solaris',
+        mswin:   'Windows',
+        mingw:   'Windows',
+        cygwin:  'Windows'
+      }
+
+      attr_reader :options
+
+      def initialize(opts = {})
+        @options = opts
+      end
+
+      # This method should be overriden by subclasses and return an array of
+      # OSes the notifier supports. By default, it returns :all which mean
+      # there's no check against the current OS.
+      #
+      # @see HOSTS for the list of possible OSes
+      #
+      def self.supported_hosts
+        :all
+      end
+
+      # Test if the notifier can be used.
+      #
+      # @param [Hash] opts notifier options
+      # @option opts [Boolean] silent true if no error messages should be shown
+      # @return [Boolean] the availability status
+      #
+      def self.available?(opts = {})
+        options = { silent: false }.merge(opts)
+
+        unless _supported_host?
+          hosts = supported_hosts.map { |host| HOSTS[host.to_sym] }.join(', ')
+          ::Guard::UI.error "The :#{name} notifier runs only on #{hosts}." unless options[:silent]
+          return false
+        end
+
+        true
+      end
+
+      # This method must be implemented.
+      #
+      def notify(message, opts = {})
+        raise NotImplementedError
+      end
+
+      # Returns the title of the notifier.
+      #
+      # @example Un-modulize the class name
+      #   Guard::Notifier::FileNotifier.title
+      #   #=> 'FileNotifier'
+      #
+      # @return [String] the title of the notifier
+      #
+      def self.title
+        self.to_s.sub(/.+::(\w+)$/, '\1')
+      end
+
+      # Returns the name of the notifier.
+      #
+      # @example Un-modulize, underscorize and downcase the class name
+      #   Guard::Notifier::FileNotifier.name
+      #   #=> 'file_notifier'
+      #
+      # @return [String] the name of the notifier
+      #
+      def self.name
+        title.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+      end
+
+      # Returns the name of the notifier's gem. By default it returns the
+      # notifier name. This method can be overriden by subclasses.
+      #
+      # @example Un-modulize, underscorize and downcase the class name
+      #   Guard::Notifier::FileNotifier.gem_name
+      #   #=> 'file_notifier'
+      #
+      # @return [String] the name of the notifier's gem
+      #
+      def self.gem_name
+        name
+      end
+
+      # This method tries to require the gem whose name is returned by
+      # `.gem_name`. If a LoadError or NameError occurs, it displays an error
+      # message (unless opts[:silent] is true) and returns false.
+      #
+      # @param [Hash] opts some options
+      # @option opts [Boolean] silent true if no error messages should be shown
+      #
+      # @return [Boolean] whether or not the gem is loaded
+      #
+      def self.require_gem_safely(opts = {})
+        require gem_name
+        true
+      rescue LoadError, NameError
+        unless opts[:silent]
+          ::Guard::UI.error "Please add \"gem '#{gem_name}'\" to your Gemfile and run Guard with \"bundle exec\"."
+        end
+        false
+      end
+
+      # Returns the title of the notifier.
+      #
+      # @example Un-modulize the class name
+      #   Guard::Notifier::FileNotifier.new.title
+      #   #=> 'FileNotifier'
+      #
+      # @return [String] the title of the notifier
+      #
+      def title
+        self.class.title
+      end
+
+      # Returns the name of the notifier.
+      #
+      # @example Un-modulize, underscorize and downcase the class name
+      #   Guard::Notifier::FileNotifier.new.name
+      #   #=> 'file_notifier'
+      #
+      # @return [String] the name of the notifier
+      #
+      def name
+        self.class.name
+      end
+
+      # Paths where all Guard images are located
+      #
+      # @return [Pathname] the path to the images directory
+      #
+      def images_path
+        @images_path ||= Pathname.new(File.dirname(__FILE__)).join('../../../images')
+      end
+
+      # @private
+      #
+      # Checks if the current OS is supported by the notifier.
+      #
+      # @see .supported_hosts
+      #
+      def self._supported_host?
+        supported_hosts == :all ||
+        RbConfig::CONFIG['host_os'] =~ /#{supported_hosts.join('|')}/
+      end
+
+      # Set or modify the `:title`, `:type` and `:image` options for a
+      # notification. Should be used in `#notify`.
+      #
+      # @param [Hash] opts additional notification library options
+      # @option opts [String] type the notification type. Either 'success',
+      #   'pending', 'failed' or 'notify'
+      # @option opts [String] title the notification title
+      # @option opts [String] image the path to the notification image
+      #
+      def normalize_standard_options!(opts)
+        opts[:title] ||= 'Guard'
+        opts[:type]  ||= _notification_type(opts.fetch(:image, :success))
+        opts[:image]   = _image_path(opts.delete(:image) { :success })
+      end
+
+      private
+
+      # Get the image path for an image symbol for the following
+      # known image types:
+      #
+      # - failed
+      # - pending
+      # - success
+      #
+      # If the image is not a known symbol, it will be returned unmodified.
+      #
+      # @param [Symbol, String] image the image symbol or path to an image
+      #
+      # @return [String] the image path
+      #
+      def _image_path(image)
+        case image.to_sym
+        when :failed, :pending, :success
+          images_path.join("#{image.to_s}.png").to_s
+        else
+          image
+        end
+      end
+
+      # Get the notification type depending on the
+      # image that has been selected for the notification.
+      #
+      # @param [Symbol, String] image the image symbol or path to an image
+      #
+      # @return [String] the notification type
+      #
+      def _notification_type(image)
+        case image.to_sym
+        when :failed, :pending, :success
+          image.to_sym
+        else
+          :notify
+        end
+      end
+
+    end
+
+  end
+end