diff options
Diffstat (limited to 'lib/mauve/notification.rb')
| -rw-r--r-- | lib/mauve/notification.rb | 88 |
1 files changed, 68 insertions, 20 deletions
diff --git a/lib/mauve/notification.rb b/lib/mauve/notification.rb index 00ce989..920f1b1 100644 --- a/lib/mauve/notification.rb +++ b/lib/mauve/notification.rb @@ -6,7 +6,7 @@ module Mauve # This class provides an execution context for the code found in 'during' # blocks in the configuration file. This code specifies when an alert # should cause notifications to be generated, and can access @time and - # @alert variables. There are also some helper methods to provide + # \@alert variables. There are also some helper methods to provide # oft-needed functionality such as hours_in_day. # # e.g. to send alerts only between 10 and 11 am: @@ -15,7 +15,7 @@ module Mauve # # ... later on ... # - # DuringRunner.new(Time.now, my_alert, &during).inside? + # DuringRunner.new(Time.now, my_alert, &during).now? # # ... or to ask when an alert will next be cued ... # @@ -28,6 +28,14 @@ module Mauve attr_reader :time, :alert, :during + # + # Sets up the class + # + # @param [Time] time The time we're going to test + # @param [Mauve::Alert or Nilclass] alert The alert that we can use in tests. + # @param [Proc] during The Proc that is evaluated inside the instance to decide if now is now! + # @raise [ArgumentError] if +time+ is not a Time + # def initialize(time, alert=nil, &during) raise ArgumentError.new("Must supply time (not #{time.inspect})") unless time.is_a?(Time) @time = time @@ -36,14 +44,21 @@ module Mauve @logger = Log4r::Logger.new "Mauve::DuringRunner" end + # This evaluates the +during+ block, returning the result. # - # - # + # @param [Time] t Set the time at which to evaluate the +during+ block. + # @return [Boolean] def now?(t=@time) @test_time = t - res = instance_eval(&@during) + instance_eval(&@during) ? true : false end + # This finds the next occurance of the +during+ block evaluating to true. + # It returns nil if an occurence cannot be found within the next 8 days. + # + # @param [Integer] after Skip time forward this many seconds before starting + # @return [Time or nil] + # def find_next(after = 0) t = @time+after # @@ -86,18 +101,28 @@ module Mauve protected + # Returns true if the current hour is in the list of hours given. + # + # @param [Array] hours List of hours (as Integers) + # @return [Boolean] def hours_in_day(*hours) @test_time = @time if @test_time.nil? x_in_list_of_y(@test_time.hour, hours.flatten) - end - + end + + # Returns true if the current day is in the list of days given + # + # @param [Array] days List of days (as Integers) + # @return [Boolean] def days_in_week(*days) @test_time = @time if @test_time.nil? x_in_list_of_y(@test_time.wday, days.flatten) end - ## Return true if the alert has not been acknowledged within a certain time. - # + # Tests if the alert has not been acknowledged within a certain time. + # + # @param [Integer] seconds Number of seconds + # @return [Boolean] def unacknowledged(seconds) @test_time = @time if @test_time.nil? @alert && @@ -106,6 +131,11 @@ module Mauve (@test_time - @alert.raised_at) >= seconds end + # Checks to see if x is contained in y + # + # @param [Array] y Array to search for +x+ + # @param [Object] x + # @return [Boolean] def x_in_list_of_y(x,y) y.any? do |range| if range.respond_to?("include?") @@ -116,16 +146,17 @@ module Mauve end end + # Test to see if we're in working hours. See Time#working_hours? + # + # @return [Boolean] def working_hours? @test_time = @time if @test_time.nil? @test_time.working_hours? end - # Return true in the dead zone between 3 and 7 in the morning. + # Test to see if we're in the dead zone. See Time#dead_zone? # - # Nota bene that this is used with different times in the reminder section. - # - # @return [Boolean] Whether now is a in the dead zone or not. + # @return [Boolean] def dead_zone? @test_time = @time if @test_time.nil? @test_time.dead_zone? @@ -139,20 +170,31 @@ module Mauve # class Notification < Struct.new(:people, :level, :every, :during, :list) - def to_s - "#<Notification:of #{people.map { |p| p.username }.join(',')} at level #{level} every #{every}>" - end - - attr_reader :thread_list - + # Set up a new notification + # + # @param [Array] people List of Mauve::Person to notify + # @param [Symbol] level Level at which to notify def initialize(people, level) self.level = level self.every = 300 self.people = people end + # @return [String] + def to_s + "#<Notification:of #{people.map { |p| p.username }.join(',')} at level #{level} every #{every}>" + end + + # @return Log4r::Logger def logger ; Log4r::Logger.new self.class.to_s ; end + # Push a notification on to the queue for this alert. The Mauve::Notifier + # will then pop it off and do the notification in a separate thread. + # + # @param [Mauve::Alert or Mauve::AlertChanged] alert The alert in question + # @param [Array] already_sent_to A list of people that have already received this alert. + # + # @return [Array] The list of people that have received this alert. def notify(alert, already_sent_to = []) if people.nil? or people.empty? @@ -187,7 +229,13 @@ module Mauve return already_sent_to end - + + # Work out when this notification should next get sent. Nil will be + # returned if the alert is not raised. + # + # @param [Mauve::Alert] alert The alert in question + # @return [Time or nil] The time a reminder should get sent, or nil if it + # should never get sent again. def remind_at_next(alert) return nil unless alert.raised? |