Cocktail v0.5.0 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/0
s or
Cocktail.Span.t/0
s 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
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
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.
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 interval2
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>
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.
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.
Parses a string in iCalendar format into a Cocktail.Schedule.t/0
.
see Cocktail.Parser.ICalendar.parse/1
for details.
Parses a string of JSON into a Cocktail.Schedule.t/0
.
see Cocktail.Parser.JSON.parse/1
for details.
Parses JSON-like map into a Cocktail.Schedule.t/0
.
see Cocktail.Parser.JSON.parse_map/1
for details.
new(Cocktail.time, Cocktail.schedule_options) :: t
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<>
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:
- If the schedule’s start time is a
DateTime.t/0
, then it will produceDateTime.t/0
s - If the schedule’s start time is a
NaiveDateTime.t/0
, the it will produceNaiveDateTime.t/0
s - If a duration is supplied when creating the schedule, the stream will
produce
Cocktail.Span.t/0
s with:from
and:until
fields matching the type of the schedule’s start time
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]}]
Builds an iCalendar format string represenation of a Cocktail.Schedule.t/0
.
see Cocktail.Builder.ICalendar.build/1
for details.
Builds a human readable string represenation of a Cocktail.Schedule.t/0
.
see Cocktail.Builder.String.build/1
for details.