Cocktail v0.2.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 a recurrence rule of the given frequency to a 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_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]
)
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>
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)
[Timex.to_datetime(~N[2017-01-02 10:00:00], "America/Los_Angeles"),
Timex.to_datetime(~N[2017-01-03 10:00:00], "America/Los_Angeles"),
Timex.to_datetime(~N[2017-01-04 10:00:00], "America/Los_Angeles")]
# 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.