Initial notifier yardoc.

This commit is contained in:
Michael Kessler 2011-09-20 13:06:35 +02:00
parent ab91117ed7
commit 98ee450037

View File

@ -3,13 +3,28 @@ require 'pathname'
require 'guard/ui' require 'guard/ui'
module Guard 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 module Notifier
# Application name as shown in the specific notification settings
APPLICATION_NAME = "Guard" APPLICATION_NAME = "Guard"
# Turn notifications of.
#
def self.turn_off def self.turn_off
ENV["GUARD_NOTIFY"] = 'false' ENV["GUARD_NOTIFY"] = 'false'
end 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 def self.turn_on
ENV["GUARD_NOTIFY"] = 'true' ENV["GUARD_NOTIFY"] = 'true'
case RbConfig::CONFIG['target_os'] case RbConfig::CONFIG['target_os']
@ -22,6 +37,15 @@ module Guard
end end
end end
# Show a message with the system notification.
#
# @see .image_path
#
# @param [String] the message to show
# @param [Hash] options the notification options
# @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 = {}) def self.notify(message, options = {})
if enabled? if enabled?
image = options.delete(:image) || :success image = options.delete(:image) || :success
@ -38,12 +62,23 @@ module Guard
end end
end end
# Test if the notifications are enabled and available.
#
# @return [Boolean] whether the notifications are available
#
def self.enabled? def self.enabled?
ENV["GUARD_NOTIFY"] == 'true' ENV["GUARD_NOTIFY"] == 'true'
end end
private private
# 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) def self.notify_mac(title, message, image, options)
require_growl # need for guard-rspec formatter that is called out of guard scope require_growl # need for guard-rspec formatter that is called out of guard scope
@ -61,18 +96,42 @@ module Guard
end end
end end
# 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) def self.notify_linux(title, message, image, options)
require_libnotify # need for guard-rspec formatter that is called out of guard scope 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 } default_options = { :body => message, :summary => title, :icon_path => image_path(image), :transient => true }
Libnotify.show default_options.merge(options) if enabled? Libnotify.show default_options.merge(options) if enabled?
end end
# 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) def self.notify_windows(title, message, image, options)
require_rbnotifu # need for guard-rspec formatter that is called out of guard scope 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 } default_options = { :message => message, :title => title, :type => image_level(image), :time => 3 }
Notifu.show default_options.merge(options) if enabled? Notifu.show default_options.merge(options) if enabled?
end 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) def self.image_path(image)
images_path = Pathname.new(File.dirname(__FILE__)).join('../../images') images_path = Pathname.new(File.dirname(__FILE__)).join('../../images')
case image case image
@ -88,6 +147,11 @@ module Guard
end end
end end
# The notification level type for the given image.
#
# @param [Symbol] image the image
# @return [Symbol] the level
#
def self.image_level(image) def self.image_level(image)
case image case image
when :failed when :failed
@ -101,6 +165,9 @@ module Guard
end end
end end
# Try to safely load growl and turns notifications
# off on load failure.
#
def self.require_growl def self.require_growl
begin begin
require 'growl_notify' require 'growl_notify'
@ -119,6 +186,9 @@ module Guard
UI.info "Please install growl_notify or growl gem for Mac OS X notification support and add it to your Gemfile" UI.info "Please install growl_notify or growl gem for Mac OS X notification support and add it to your Gemfile"
end end
# Try to safely load libnotify and turns notifications
# off on load failure.
#
def self.require_libnotify def self.require_libnotify
require 'libnotify' require 'libnotify'
rescue LoadError rescue LoadError
@ -126,11 +196,15 @@ module Guard
UI.info "Please install libnotify gem for Linux notification support and add it to your Gemfile" UI.info "Please install libnotify gem for Linux notification support and add it to your Gemfile"
end end
# Try to safely load rb-notifu and turns notifications
# off on load failure.
#
def self.require_rbnotifu def self.require_rbnotifu
require 'rb-notifu' require 'rb-notifu'
rescue LoadError rescue LoadError
turn_off turn_off
UI.info "Please install rb-notifu gem for Windows notification support and add it to your Gemfile" UI.info "Please install rb-notifu gem for Windows notification support and add it to your Gemfile"
end end
end end
end end