Class: IceCube::Schedule

Inherits:
Object
  • Object
show all
Extended by:
Deprecated
Defined in:
lib/ice_cube/schedule.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Deprecated

deprecated, deprecated_alias, schedule_options

Constructor Details

#initialize(start_time = nil, options = {}) {|_self| ... } ⇒ Schedule

Create a new schedule

Yields:

  • (_self)

Yield Parameters:


16
17
18
19
20
21
22
23
# File 'lib/ice_cube/schedule.rb', line 16

def initialize(start_time = nil, options = {})
  self.start_time = start_time || TimeUtil.now
  self.end_time = self.start_time + options[:duration] if options[:duration]
  self.end_time = options[:end_time] if options[:end_time]
  @all_recurrence_rules = []
  @all_exception_rules = []
  yield self if block_given?
end

Instance Attribute Details

#end_timeObject

Get the end time


12
13
14
# File 'lib/ice_cube/schedule.rb', line 12

def end_time
  @end_time
end

#start_timeObject

Get the start time


8
9
10
# File 'lib/ice_cube/schedule.rb', line 8

def start_time
  @start_time
end

Class Method Details

.dump(schedule) ⇒ Object


399
400
401
402
# File 'lib/ice_cube/schedule.rb', line 399

def self.dump(schedule)
  return schedule if schedule.nil? || schedule == ""
  schedule.to_yaml
end

.from_hash(original_hash, options = {}) ⇒ Object

Load the schedule from a hash


373
374
375
376
377
378
# File 'lib/ice_cube/schedule.rb', line 373

def self.from_hash(original_hash, options = {})
  HashParser.new(original_hash).to_schedule do |schedule|
    Deprecated.schedule_options(schedule, options)
    yield schedule if block_given?
  end
end

.from_ical(ical, options = {}) ⇒ Object

Load the schedule from ical


337
338
339
# File 'lib/ice_cube/schedule.rb', line 337

def self.from_ical(ical, options = {})
  IcalParser.schedule_from_ical(ical, options)
end

.from_yaml(yaml, options = {}) ⇒ Object

Load the schedule from yaml


347
348
349
350
351
352
# File 'lib/ice_cube/schedule.rb', line 347

def self.from_yaml(yaml, options = {})
  YamlParser.new(yaml).to_schedule do |schedule|
    Deprecated.schedule_options(schedule, options)
    yield schedule if block_given?
  end
end

.load(yaml) ⇒ Object


404
405
406
407
# File 'lib/ice_cube/schedule.rb', line 404

def self.load(yaml)
  return yaml if yaml.nil? || yaml == ""
  from_yaml(yaml)
end

Instance Method Details

#add_exception_rule(rule) ⇒ Object Also known as: exrule

Add an exception rule to the schedule


81
82
83
84
# File 'lib/ice_cube/schedule.rb', line 81

def add_exception_rule(rule)
  return if rule.nil?
  @all_exception_rules << rule unless @all_exception_rules.include?(rule)
end

#add_exception_time(time) ⇒ Object Also known as: extime

Add an exception time to the schedule


57
58
59
60
61
62
# File 'lib/ice_cube/schedule.rb', line 57

def add_exception_time(time)
  return if time.nil?
  rule = SingleOccurrenceRule.new(time)
  add_exception_rule rule
  time
end

#add_recurrence_rule(rule) ⇒ Object Also known as: rrule

Add a recurrence rule to the schedule


68
69
70
71
# File 'lib/ice_cube/schedule.rb', line 68

def add_recurrence_rule(rule)
  return if rule.nil?
  @all_recurrence_rules << rule unless @all_recurrence_rules.include?(rule)
end

#add_recurrence_time(time) ⇒ Object Also known as: rtime

Add a recurrence time to the schedule


46
47
48
49
50
51
# File 'lib/ice_cube/schedule.rb', line 46

def add_recurrence_time(time)
  return if time.nil?
  rule = SingleOccurrenceRule.new(time)
  add_recurrence_rule rule
  time
end

#all_occurrencesObject

All of the occurrences


152
153
154
155
# File 'lib/ice_cube/schedule.rb', line 152

def all_occurrences
  require_terminating_rules
  enumerate_occurrences(start_time).to_a
end

#all_occurrences_enumeratorObject

Emit an enumerator based on the start time


158
159
160
# File 'lib/ice_cube/schedule.rb', line 158

def all_occurrences_enumerator
  enumerate_occurrences(start_time)
end

#conflicts_with?(other_schedule, closing_time = nil) ⇒ Boolean

Determine if this schedule conflicts with another schedule

Parameters:

  • other_schedule (IceCube::Schedule)
    • The schedule to compare to

  • closing_time (Time) (defaults to: nil)
    • the last time to consider

Returns:

  • (Boolean)

    whether or not the schedules conflict at all


255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
# File 'lib/ice_cube/schedule.rb', line 255

def conflicts_with?(other_schedule, closing_time = nil)
  closing_time = TimeUtil.ensure_time(closing_time)
  unless terminating? || other_schedule.terminating? || closing_time
    raise ArgumentError, "One or both schedules must be terminating to use #conflicts_with?"
  end
  # Pick the terminating schedule, and other schedule
  # No need to reverse if terminating? or there is a closing time
  terminating_schedule = self
  unless terminating? || closing_time
    terminating_schedule, other_schedule = other_schedule, terminating_schedule
  end
  # Go through each occurrence of the terminating schedule and determine
  # if the other occurs at that time
  #
  last_time = nil
  terminating_schedule.each_occurrence do |time|
    if closing_time && time > closing_time
      last_time = closing_time
      break
    end
    last_time = time
    return true if other_schedule.occurring_at?(time)
  end
  # Due to durations, we need to walk up to the end time, and verify in the
  # other direction
  if last_time
    last_time += terminating_schedule.duration
    other_schedule.each_occurrence do |time|
      break if time > last_time
      return true if terminating_schedule.occurring_at?(time)
    end
  end
  # No conflict, return false
  false
end

#durationObject


37
38
39
# File 'lib/ice_cube/schedule.rb', line 37

def duration
  end_time ? end_time - start_time : 0
end

#duration=(seconds) ⇒ Object


41
42
43
# File 'lib/ice_cube/schedule.rb', line 41

def duration=(seconds)
  @end_time = start_time + seconds
end

#each_occurrence(&block) ⇒ Object

Iterate forever


163
164
165
166
# File 'lib/ice_cube/schedule.rb', line 163

def each_occurrence(&block)
  enumerate_occurrences(start_time, &block).to_a
  self
end

#encode_with(coder) ⇒ Object

Hook for YAML.dump, enables to_yaml


342
343
344
# File 'lib/ice_cube/schedule.rb', line 342

def encode_with(coder)
  coder.represent_object nil, to_hash
end

#eql?(other) ⇒ Boolean Also known as: ==

Returns:

  • (Boolean)

394
395
396
# File 'lib/ice_cube/schedule.rb', line 394

def eql?(other)
  hash == other.hash
end

#exception_rulesObject Also known as: exrules

Get the exception rules


100
101
102
# File 'lib/ice_cube/schedule.rb', line 100

def exception_rules
  @all_exception_rules.reject { |r| r.is_a?(SingleOccurrenceRule) }
end

#exception_timesObject Also known as: extimes

Get the exception times that are on the schedule


126
127
128
# File 'lib/ice_cube/schedule.rb', line 126

def exception_times
  @all_exception_rules.select { |r| r.is_a?(SingleOccurrenceRule) }.map(&:time)
end

#first(n = nil) ⇒ Object

Get the first n occurrences, or the first occurrence if n is skipped


297
298
299
300
# File 'lib/ice_cube/schedule.rb', line 297

def first(n = nil)
  occurrences = enumerate_occurrences(start_time).take(n || 1)
  n.nil? ? occurrences.first : occurrences
end

#hashObject


386
387
388
389
390
391
392
# File 'lib/ice_cube/schedule.rb', line 386

def hash
  [
    TimeUtil.hash(start_time), duration,
    *@all_recurrence_rules.map(&:hash).sort!,
    *@all_exception_rules.map(&:hash).sort!
  ].hash
end

#last(n = nil) ⇒ Object

Get the final n occurrences of a terminating schedule or the final one if no n is given


304
305
306
307
308
# File 'lib/ice_cube/schedule.rb', line 304

def last(n = nil)
  require_terminating_rules
  occurrences = enumerate_occurrences(start_time).to_a
  n.nil? ? occurrences.last : occurrences[-n..]
end

#next_occurrence(from = nil, options = {}) ⇒ Object

The next occurrence after now (overridable)


175
176
177
178
179
180
# File 'lib/ice_cube/schedule.rb', line 175

def next_occurrence(from = nil, options = {})
  from = TimeUtil.match_zone(from, start_time) || TimeUtil.now(start_time)
  enumerate_occurrences(from + 1, nil, options).next
rescue StopIteration
  nil
end

#next_occurrences(num, from = nil, options = {}) ⇒ Object

The next n occurrences after now


169
170
171
172
# File 'lib/ice_cube/schedule.rb', line 169

def next_occurrences(num, from = nil, options = {})
  from = TimeUtil.match_zone(from, start_time) || TimeUtil.now(start_time)
  enumerate_occurrences(from + 1, nil, options).take(num)
end

#occurrences(closing_time) ⇒ Object

Get all of the occurrences from the start_time up until a given Time


147
148
149
# File 'lib/ice_cube/schedule.rb', line 147

def occurrences(closing_time)
  enumerate_occurrences(start_time, closing_time).to_a
end

#occurrences_between(begin_time, closing_time, options = {}) ⇒ Object

Occurrences between two times


211
212
213
# File 'lib/ice_cube/schedule.rb', line 211

def occurrences_between(begin_time, closing_time, options = {})
  enumerate_occurrences(begin_time, closing_time, options).to_a
end

#occurring_at?(time) ⇒ Boolean

Determine if the schedule is occurring at a given time

Returns:

  • (Boolean)

241
242
243
244
245
246
247
248
249
# File 'lib/ice_cube/schedule.rb', line 241

def occurring_at?(time)
  time = TimeUtil.match_zone(time, start_time) or raise ArgumentError, "Time required, got #{time.inspect}"
  if duration > 0
    return false if exception_time?(time)
    occurs_between?(time - duration + 1, time)
  else
    occurs_at?(time)
  end
end

#occurring_between?(opening_time, closing_time) ⇒ Boolean

Return a boolean indicating if an occurrence is occurring between two times, inclusive of its duration. This counts zero-length occurrences that intersect the start of the range and within the range, but not occurrences at the end of the range since none of their duration intersects the range.

Returns:

  • (Boolean)

228
229
230
# File 'lib/ice_cube/schedule.rb', line 228

def occurring_between?(opening_time, closing_time)
  occurs_between?(opening_time, closing_time, spans: true)
end

#occurs_at?(time) ⇒ Boolean

Determine if the schedule occurs at a specific time

Returns:

  • (Boolean)

292
293
294
# File 'lib/ice_cube/schedule.rb', line 292

def occurs_at?(time)
  occurs_between?(time, time)
end

#occurs_between?(begin_time, closing_time, options = {}) ⇒ Boolean

Return a boolean indicating if an occurrence falls between two times

Returns:

  • (Boolean)

216
217
218
219
220
221
# File 'lib/ice_cube/schedule.rb', line 216

def occurs_between?(begin_time, closing_time, options = {})
  enumerate_occurrences(begin_time, closing_time, options).next
  true
rescue StopIteration
  false
end

#occurs_on?(date) ⇒ Boolean

Return a boolean indicating if an occurrence falls on a certain date

Returns:

  • (Boolean)

233
234
235
236
237
238
# File 'lib/ice_cube/schedule.rb', line 233

def occurs_on?(date)
  date = TimeUtil.ensure_date(date)
  begin_time = TimeUtil.beginning_of_date(date, start_time)
  closing_time = TimeUtil.end_of_date(date, start_time)
  occurs_between?(begin_time, closing_time)
end

#previous_occurrence(from) ⇒ Object

The previous occurrence from a given time


183
184
185
186
187
# File 'lib/ice_cube/schedule.rb', line 183

def previous_occurrence(from)
  from = TimeUtil.match_zone(from, start_time) or raise ArgumentError, "Time required, got #{from.inspect}"
  return nil if from <= start_time
  enumerate_occurrences(start_time, from - 1).to_a.last
end

#previous_occurrences(num, from) ⇒ Object

The previous n occurrences before a given time


190
191
192
193
194
195
# File 'lib/ice_cube/schedule.rb', line 190

def previous_occurrences(num, from)
  from = TimeUtil.match_zone(from, start_time) or raise ArgumentError, "Time required, got #{from.inspect}"
  return [] if from <= start_time
  a = enumerate_occurrences(start_time, from - 1).to_a
  a.size > num ? a[-1 * num, a.size] : a
end

#recurrence_rulesObject Also known as: rrules

Get the recurrence rules


94
95
96
# File 'lib/ice_cube/schedule.rb', line 94

def recurrence_rules
  @all_recurrence_rules.reject { |r| r.is_a?(SingleOccurrenceRule) }
end

#recurrence_timesObject Also known as: rtimes

Get the recurrence times that are on the schedule


106
107
108
# File 'lib/ice_cube/schedule.rb', line 106

def recurrence_times
  @all_recurrence_rules.select { |r| r.is_a?(SingleOccurrenceRule) }.map(&:time)
end

#remaining_occurrences(from = nil, options = {}) ⇒ Object

The remaining occurrences (same requirements as all_occurrences)


198
199
200
201
202
# File 'lib/ice_cube/schedule.rb', line 198

def remaining_occurrences(from = nil, options = {})
  require_terminating_rules
  from ||= TimeUtil.now(@start_time)
  enumerate_occurrences(from, nil, options).to_a
end

#remaining_occurrences_enumerator(from = nil, options = {}) ⇒ Object

Returns an enumerator for all remaining occurrences


205
206
207
208
# File 'lib/ice_cube/schedule.rb', line 205

def remaining_occurrences_enumerator(from = nil, options = {})
  from ||= TimeUtil.now(@start_time)
  enumerate_occurrences(from, nil, options)
end

#remove_exception_rule(rule) ⇒ Object

Remove an exception rule


88
89
90
91
# File 'lib/ice_cube/schedule.rb', line 88

def remove_exception_rule(rule)
  res = @all_exception_rules.delete(rule)
  res.nil? ? [] : [res]
end

#remove_exception_time(time) ⇒ Object Also known as: remove_extime

Remove an exception time


134
135
136
137
138
139
140
# File 'lib/ice_cube/schedule.rb', line 134

def remove_exception_time(time)
  found = false
  @all_exception_rules.delete_if do |rule|
    found = true if rule.is_a?(SingleOccurrenceRule) && rule.time == time
  end
  time if found
end

#remove_recurrence_rule(rule) ⇒ Object

Remove a recurrence rule


75
76
77
78
# File 'lib/ice_cube/schedule.rb', line 75

def remove_recurrence_rule(rule)
  res = @all_recurrence_rules.delete(rule)
  res.nil? ? [] : [res]
end

#remove_recurrence_time(time) ⇒ Object Also known as: remove_rtime

Remove a recurrence time


114
115
116
117
118
119
120
# File 'lib/ice_cube/schedule.rb', line 114

def remove_recurrence_time(time)
  found = false
  @all_recurrence_rules.delete_if do |rule|
    found = true if rule.is_a?(SingleOccurrenceRule) && rule.time == time
  end
  time if found
end

#terminating?Boolean

Determine if the schedule will end

Returns:

  • (Boolean)

    true if ending, false if repeating forever


382
383
384
# File 'lib/ice_cube/schedule.rb', line 382

def terminating?
  @all_recurrence_rules.all?(&:terminating?)
end

#to_hashObject Also known as: to_h

Convert the schedule to a hash


355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
# File 'lib/ice_cube/schedule.rb', line 355

def to_hash
  data = {}
  data[:start_time] = TimeUtil.serialize_time(start_time)
  data[:start_date] = data[:start_time] if IceCube.compatibility <= 11
  data[:end_time] = TimeUtil.serialize_time(end_time) if end_time
  data[:rrules] = recurrence_rules.map(&:to_hash)
  data[:exrules] = exception_rules.map(&:to_hash) if exception_rules.any?
  data[:rtimes] = recurrence_times.map do |rt|
    TimeUtil.serialize_time(rt)
  end
  data[:extimes] = exception_times.map do |et|
    TimeUtil.serialize_time(et)
  end
  data
end

#to_ical(force_utc = false) ⇒ Object

Serialize this schedule to_ical


325
326
327
328
329
330
331
332
333
334
# File 'lib/ice_cube/schedule.rb', line 325

def to_ical(force_utc = false)
  pieces = []
  pieces << "DTSTART#{IcalBuilder.ical_format(start_time, force_utc)}"
  pieces.concat recurrence_rules.map { |r| "RRULE:#{r.to_ical}" }
  pieces.concat exception_rules.map { |r| "EXRULE:#{r.to_ical}" }
  pieces.concat recurrence_times_without_start_time.map { |t| "RDATE#{IcalBuilder.ical_format(t, force_utc)}" }
  pieces.concat exception_times.map { |t| "EXDATE#{IcalBuilder.ical_format(t, force_utc)}" }
  pieces << "DTEND#{IcalBuilder.ical_format(end_time, force_utc)}" if end_time
  pieces.join("\n")
end

#to_sObject

String serialization


311
312
313
314
315
316
317
318
319
320
321
322
# File 'lib/ice_cube/schedule.rb', line 311

def to_s
  pieces = []
  rd = recurrence_times_with_start_time - extimes
  pieces.concat rd.sort.map { |t| IceCube::I18n.l(t, format: IceCube.to_s_time_format) }
  pieces.concat rrules.map { |t| t.to_s }
  pieces.concat exrules.map { |t| IceCube::I18n.t("ice_cube.not", target: t.to_s) }
  pieces.concat extimes.sort.map { |t|
    target = IceCube::I18n.l(t, format: IceCube.to_s_time_format)
    IceCube::I18n.t("ice_cube.not_on", target: target)
  }
  pieces.join(IceCube::I18n.t("ice_cube.pieces_connector"))
end