Cocktail v0.5.2 Cocktail.Schedule View Source

Struct used to represent a schedule of recurring events.

Use the new/2 function to create a new schedule, and the add_recurrence_rule/2 function to add rules to describe how to repeat.

Currently, Cocktail supports the following types of repeat rules:

  • Weekly - Every week, relative to the schedule’s start time
  • Daily - Every day at the schedule’s start time
  • Hourly - Every hour, starting at the schedule’s start time
  • Minutely - Every minute, starting at the schedule’s start time
  • Secondly - Every second, starting at the schedule’s start time

Once a schedule has been created, you can use occurrences/2 to generate a stream of occurrences, which are either Cocktail.time/0s or Cocktail.Span.t/0s if a duration option was given to the schedule.

Various options can be given to modify the way the repeat rule and schedule behave. See add_recurrence_rule/3 for details on them.

Link to this section Summary

Types

t()

Struct used to represent a schedule of recurring events

Functions

Adds an exception time to the schedule

Adds a recurrence rule of the given frequency to a schedule

Adds a one-off recurrence time to the schedule

Add an end time to all recurrence rules in the schedule

Parses a string in iCalendar format into a Cocktail.Schedule.t/0

Parses a string of JSON into a Cocktail.Schedule.t/0

Parses JSON-like map into a Cocktail.Schedule.t/0

Creates a new schedule using the given start time and options

Creates a stream of occurrences from the given schedule

Builds an iCalendar format string represenation of a Cocktail.Schedule.t/0

Builds a human readable string represenation of a Cocktail.Schedule.t/0

Link to this section Types

Struct used to represent a schedule of recurring events.

This type is opaque, so its fields shouldn’t be modified directly. Instead, use the functions provided in this module to create and manipulate schedules.

Fields:

  • :start_time - The schedule’s start time
  • :duration - The duration of each occurrence (in seconds)

Link to this section Functions

Link to this function add_exception_time(schedule, time) View Source
add_exception_time(t, Cocktail.time) :: t

Adds an exception time to the schedule.

This exception time will cancel out any occurrence generated from the schedule’s recurrence rules or recurrence times.

Link to this function add_recurrence_rule(schedule, frequency, options \\ []) View Source
add_recurrence_rule(t, Cocktail.frequency, Cocktail.rule_options) :: t

Adds a recurrence rule of the given frequency to a schedule.

The frequency can be one of :weekly, :daily, :hourly, :minutely or :secondly.

NOTE: more frequencies are planned to be supported in the future. (e.g. :monthly)

Options

  • :interval - How often to repeat, given the frequency. For example a :daily rule with interval 2 would be “every other day”.
  • :count - The number of times this rule can produce an occurrence. (not yet support)
  • :until - The end date/time after which the rule will no longer produce occurrences.
  • :days - Restrict this rule to specific days. (e.g. [:monday, :wednesday, :friday])
  • :hours - Restrict this rule to certain hours of the day. (e.g. [10, 12, 14])
  • :minutes - Restrict this rule to certain minutes of the hour. (e.g. [0, 15, 30, 45])
  • :seconds - Restrict this rule to certain seconds of the minute. (e.g. [0, 30])

NOTE: more options are planned to be supported in the future. (e.g. :days_of_month)

Examples

iex> start_time = ~N[2017-01-01 06:00:00]
...> start_time |> new() |> add_recurrence_rule(:daily, interval: 2, hours: [10, 14])
#Cocktail.Schedule<Every 2 days on the 10th and 14th hours of the day>
Link to this function add_recurrence_time(schedule, time) View Source
add_recurrence_time(t, Cocktail.time) :: t

Adds a one-off recurrence time to the schedule.

This recurrence time can be any time after (or including) the schedule’s start time. When generating occurrences from this schedule, the given time will be included in the set of occurrences alongside any recurrence rules.

Link to this function end_all_recurrence_rules(schedule, end_time) View Source
end_all_recurrence_rules(t, Cocktail.time) :: t

Add an end time to all recurrence rules in the schedule.

This has the same effect as if you’d passed the :until option when adding all recurrence rules to the schedule.

Link to this function from_i_calendar(i_calendar_string) View Source
from_i_calendar(String.t) :: {:ok, t} | {:error, term}

Parses a string in iCalendar format into a Cocktail.Schedule.t/0.

see Cocktail.Parser.ICalendar.parse/1 for details.

Link to this function from_json(json_string) View Source
from_json(String.t) :: {:ok, t} | {:error, term}

Parses a string of JSON into a Cocktail.Schedule.t/0.

see Cocktail.Parser.JSON.parse/1 for details.

Link to this function from_map(map) View Source
from_map(map) :: {:ok, t} | {:error, term}

Parses JSON-like map into a Cocktail.Schedule.t/0.

see Cocktail.Parser.JSON.parse_map/1 for details.

Creates a new schedule using the given start time and options.

This schdule will be empty and needs recurrence rules added to it before it is useful. Use add_recurrence_rule/3 to add rules to a schedule.

Options

  • :duration - The duration of each event in the schedule (in seconds).

Examples

iex> new(~N[2017-01-01 06:00:00], duration: 3_600)
#Cocktail.Schedule<>
Link to this function occurrences(schedule, start_time \\ nil) View Source
occurrences(t, Cocktail.time | nil) :: Enumerable.t

Creates a stream of occurrences from the given schedule.

An optional start_time can be supplied to not start at the schedule’s start time.

The occurrences that are produced by the stream can be one of several types:

Examples

# using a NaiveDateTime
iex> start_time = ~N[2017-01-01 06:00:00]
...> schedule = start_time |> new() |> add_recurrence_rule(:daily, interval: 2, hours: [10, 14])
...> schedule |> occurrences() |> Enum.take(3)
[~N[2017-01-01 10:00:00],
 ~N[2017-01-01 14:00:00],
 ~N[2017-01-03 10:00:00]]

# using an alternate start time
iex> start_time = ~N[2017-01-01 06:00:00]
...> schedule = start_time |> new() |> add_recurrence_rule(:daily, interval: 2, hours: [10, 14])
...> schedule |> occurrences(~N[2017-10-01 06:00:00]) |> Enum.take(3)
[~N[2017-10-02 10:00:00],
 ~N[2017-10-02 14:00:00],
 ~N[2017-10-04 10:00:00]]

# using a DateTime with a time zone
iex> start_time = Timex.to_datetime(~N[2017-01-02 10:00:00], "America/Los_Angeles")
...> schedule = start_time |> new() |> add_recurrence_rule(:daily)
...> schedule |> occurrences() |> Enum.take(3) |> Enum.map(&Timex.format!(&1, "{ISO:Extended}"))
["2017-01-02T10:00:00-08:00",
 "2017-01-03T10:00:00-08:00",
 "2017-01-04T10:00:00-08:00"]

# using a NaiveDateTime with a duration
iex> start_time = ~N[2017-02-01 12:00:00]
...> schedule = start_time |> new(duration: 3_600) |> add_recurrence_rule(:weekly)
...> schedule |> occurrences() |> Enum.take(3)
[%Cocktail.Span{from: ~N[2017-02-01 12:00:00], until: ~N[2017-02-01 13:00:00]},
 %Cocktail.Span{from: ~N[2017-02-08 12:00:00], until: ~N[2017-02-08 13:00:00]},
 %Cocktail.Span{from: ~N[2017-02-15 12:00:00], until: ~N[2017-02-15 13:00:00]}]
Link to this function to_i_calendar(schedule) View Source
to_i_calendar(t) :: String.t

Builds an iCalendar format string represenation of a Cocktail.Schedule.t/0.

see Cocktail.Builder.ICalendar.build/1 for details.

Link to this function to_string(schedule) View Source
to_string(t) :: String.t

Builds a human readable string represenation of a Cocktail.Schedule.t/0.

see Cocktail.Builder.String.build/1 for details.