Complete recurrence generation

.credo.exs

@@ -4,6 +4,9 @@
     %{
       name: "default",
       checks: %{
+        extra: [
+          {Credo.Check.Refactor.Nesting, [max_nesting: 3]}
+        ],
         disabled: [
           {Credo.Check.Design.AliasUsage, []}
         ]

CHANGELOG.md

@@ -4,29 +4,33 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## vNEXT
+## v2.0.0
 
-This release drops support for Elixir 1.15 and 1.16 in order to gain
-access to the improved date and calendaring APIs introduced in 1.17. 
+The minimum version of Elixir required is 1.17. Support for Elixir 1.15 and 1.16 was
+dropped so `ICal` may use the improved date and calendaring APIs introduced in 1.17.
 
-Timex was also removed as a dependency, along with its transitive dependencies
-such as gettext. 
-
-It is recommended to add a timezone database such as `tz` to applications that use 
+It is recommended to add a timezone database such as `tz` to applications that use
 ICal in order to benefit fully from these changes.
 
 - Improvements
+  - Recurrence generation was re-written and is now feature complete
+    - The entirety of the RFC5545 RRULE specification is supported
+    - Works with `ICal.Event`, `ICal.Todo` and `ICal.Journal`
+    - Recurrence dates (`RDATE`) are included
+    - Excluded dates (`EXDATE`) are respected
   - New functions in `ICal.Alarm`
     - `next_activation/2`: calculates when an alarm should next activate (if ever)
     - `next_alarms/1`: returns all next alarms with activation times for a compoonent with
       alarms (`ICal.Event`, `ICal.Todo`)
-  - Recurrence now supports `ICal.Todo`
 - Fixes
   - Gap and ambiguous times are properly handled when a datetime lands in a timezone shift period
+  - Properly parse lists of excluded dates
+  - Fix serializing of components with status of draft
 - Janitorial
+  - The dependency on `Timex` was removed
   - Documentation improvements
 
-Contributors to this release included:
+Contributors to this release include:
 - [Matthew Lehner](https://github.com/matthewlehner)
 - [Patrick Wendo](https://github.com/W3NDO)
 

README.md

@@ -13,7 +13,8 @@ A library for reading and writing iCalendar data.
   * Journals
   * Timezones
   * Alarms
-* Recurrence calculations (currrently only `BYDAY` is supported)
+* Recurrence calculations
+* Alarm calculations
 * Compatibility
   * RFC 5545 compliant
   * Support for common non-standard properties, including:
@@ -28,11 +29,6 @@ Components that will eventually be supported (in rough order):
 
 * Free/busy (VFREEBUSY)
 
-Planned features:
-
-* Alarm calculation
-* Expanded recurrency calculation
-
 ## Usage
 
 Full documentation can be found on [Hexdocs](https://hexdocs.pm/ical).
@@ -75,41 +71,31 @@ Inline attachments can be decoded via `ICal.Attachment.decoded_data/1`.
 
 ## Installation
 
-- Add `:ical` to your list of dependencies in `mix.exs`:
+- Add `:ical` to your list of dependencies in `mix.exs`, along with a timezone database:
 
   ```elixir
   def deps do
     [{:ical, "~> 1.0"}]
-  end
-  ```
-
-- ICal needs a timezone database for timezone-aware operations (parsing events
-  with `TZID`, recurrence calculations, etc.). Add a package that implements the
-  `Calendar.TimeZoneDatabase` behaviour to your dependencies:
-
-  ```elixir
-  def deps do
-    [
       {:ical, "~> 1.0"},
-      {:tzdata, "~> 1.1"}
+      {:tz, "~> 1.1"}
     ]
   end
   ```
 
-  Then configure it in your `config/config.exs`:
+  Then configure the timezone database in e.g. `config/config.exs`:
 
   ```elixir
-  config :elixir, :time_zone_database, Tzdata.TimeZoneDatabase
+  config :elixir, :time_zone_database, Tz.TimeZoneDatabase
   ```
+  For auto-updating the timezone database at runtime, check the documentation for the timezone
+  library you are using.
 
-  The following timezone database packages are known to be compatible:
+  The following timezone database packages are known to work well with ICal:
 
   | Package | Module |
   |---|---|
-  | [`tzdata`](https://hex.pm/packages/tzdata) | `Tzdata.TimeZoneDatabase` |
   | [`tz`](https://hex.pm/packages/tz) | `Tz.TimeZoneDatabase` |
   | [`time_zone_info`](https://hex.pm/packages/time_zone_info) | `TimeZoneInfo.TimeZoneDatabase` |
-  | [`zoneinfo`](https://hex.pm/packages/zoneinfo) | `Zoneinfo.TimeZoneDatabase` |
 
   See [tzdb_test](https://github.com/mathieuprog/tzdb_test) for more
   information on the available timezone database libraries.

config/config.exs

@@ -4,3 +4,8 @@ if Mix.env() == :dev do
   config :mix_test_watch,
     extra_extensions: [".ics"]
 end
+
+if Mix.env() == :dev or Mix.env() == :test do
+  config :ical, show_test_timings: false
+  config :elixir, :time_zone_database, Tz.TimeZoneDatabase
+end

lib/ical.ex

@@ -119,4 +119,41 @@ defmodule ICal do
   def encode_to_iodata!(calendar, _options \\ []) do
     to_ics(calendar)
   end
+
+  @doc false
+  @spec as_valid_datetime(Date.t(), Time.t(), timezone :: String.t()) :: DateTime.t() | nil
+  def as_valid_datetime(date, time, timezone) do
+    case DateTime.new(date, time, timezone) do
+      {:ok, dt} -> dt
+      {:ambiguous, first, _second} -> first
+      {:gap, just_before, just_after} -> adjust_to_gap(time, just_before, just_after)
+      _ -> nil
+    end
+  rescue
+    _ -> nil
+  end
+
+  defp adjust_to_gap(original_time, before_gap, after_gap) do
+    before_gap =
+      before_gap
+      |> DateTime.to_time()
+      |> round_off_micros()
+
+    diff = Time.diff(original_time, before_gap)
+
+    time = Time.shift(DateTime.to_time(after_gap), second: diff)
+
+    DateTime.new!(DateTime.to_date(after_gap), time, after_gap.time_zone)
+  end
+
+  defp round_off_micros(time) do
+    # gap times are often 59.9999 seconds, the moment RIGHT before.
+    # snug those times up to the minute
+    {ms, precision} = time.microsecond
+    offset = round(ms / Integer.pow(10, precision))
+
+    time
+    |> Time.truncate(:second)
+    |> Time.shift(second: offset)
+  end
 end

lib/ical/alarm.ex

@@ -35,8 +35,13 @@ defmodule ICal.Alarm do
       |> Enum.take(1)
 
     case recurrences do
-      [recurrence] -> calculate_alarms(recurrence)
-      _ -> []
+      [recurrence] ->
+        recurrence
+        |> ICal.Recurrence.apply(component)
+        |> calculate_alarms()
+
+      _ ->
+        []
     end
   end
 

lib/ical/deserialize.ex

@@ -489,12 +489,7 @@ defmodule ICal.Deserialize do
       # DATE-TIME value is interpreted using the UTC offset before the gap."
       # e.g. 2:30 AM in a spring-forward gap → apply pre-gap offset (EST) to
       # get UTC, then express in the post-gap offset (EDT) → 3:30 AM EDT.
-      case DateTime.new(date, time, timezone) do
-        {:ok, dt} -> dt
-        {:ambiguous, first, _second} -> first
-        {:gap, just_before, just_after} -> adjust_to_gap(time, just_before, just_after)
-        _ -> nil
-      end
+      ICal.as_valid_datetime(date, time, timezone)
     else
       _ -> nil
     end
@@ -542,28 +537,4 @@ defmodule ICal.Deserialize do
   def status(%ICal.Journal{}, "FINAL"), do: :final
   def status(_, "CANCELLED"), do: :cancelled
   def status(_, _), do: nil
-
-  defp adjust_to_gap(original_time, before_gap, after_gap) do
-    before_gap =
-      before_gap
-      |> DateTime.to_time()
-      |> round_off_micros()
-
-    diff = Time.diff(original_time, before_gap)
-
-    time = Time.shift(DateTime.to_time(after_gap), second: diff)
-
-    DateTime.new!(DateTime.to_date(after_gap), time, after_gap.time_zone)
-  end
-
-  defp round_off_micros(time) do
-    # gap times are often 59.9999 seconds, the moment RIGHT before.
-    # snug those times up to the minute
-    {ms, precision} = time.microsecond
-    offset = round(ms / Integer.pow(10, precision))
-
-    time
-    |> Time.truncate(:second)
-    |> Time.shift(second: offset)
-  end
 end

lib/ical/deserialize/recurrence.ex

@@ -9,14 +9,6 @@ defmodule ICal.Deserialize.Recurrence do
     add_frequency(%ICal.Recurrence{}, params)
   end
 
-  @spec from_event(map | ICal.Event.t()) :: ICal.Recurrence.t() | nil
-  def from_event(%ICal.Event{rrule: %ICal.Recurrence{} = rule}), do: rule
-  def from_event(%ICal.Event{rrule: nil}), do: nil
-
-  def from_event(%ICal.Event{} = event) do
-    add_frequency(%ICal.Recurrence{}, event.rrule)
-  end
-
   defp add_frequency(recurrence, params) do
     with freq when not is_nil(freq) <- Map.get(params, "FREQ"),
          {:ok, frequency} <- to_frequency_atom(freq) do
@@ -25,6 +17,7 @@ defmodule ICal.Deserialize.Recurrence do
         %{recurrence | frequency: frequency},
         &add_to_recurrence/2
       )
+      |> ICal.Recurrence.normalize()
     else
       _ -> nil
     end
@@ -50,7 +43,7 @@ defmodule ICal.Deserialize.Recurrence do
   defp add_to_recurrence({"WKST", value}, recurrence) do
     case to_weekday(value) do
       :error -> recurrence
-      {weekday_atom, _} -> %{recurrence | weekday: weekday_atom}
+      {weekday_atom, _} -> %{recurrence | week_start_day: weekday_atom}
     end
   end
 
@@ -61,17 +54,17 @@ defmodule ICal.Deserialize.Recurrence do
   # sets of numbres, except BYDAY which is extra complicated.
   # see to_weekdays for more on that.
   defp add_by_list_to_recurrence("SECOND", value, recurrence) do
-    number_list = to_clamped_numbers(value, 0, 59)
+    number_list = parse_number_list(value)
     %{recurrence | by_second: number_list}
   end
 
   defp add_by_list_to_recurrence("MINUTE", value, recurrence) do
-    number_list = to_clamped_numbers(value, 0, 59)
+    number_list = parse_number_list(value)
     %{recurrence | by_minute: number_list}
   end
 
   defp add_by_list_to_recurrence("HOUR", value, recurrence) do
-    number_list = to_clamped_numbers(value, 0, 23)
+    number_list = parse_number_list(value)
     %{recurrence | by_hour: number_list}
   end
 
@@ -81,27 +74,27 @@ defmodule ICal.Deserialize.Recurrence do
   end
 
   defp add_by_list_to_recurrence("MONTH", value, recurrence) do
-    number_list = to_clamped_numbers(value, 1, 12)
+    number_list = parse_number_list(value)
     %{recurrence | by_month: number_list}
   end
 
   defp add_by_list_to_recurrence("MONTHDAY", value, recurrence) do
-    number_list = to_clamped_numbers(value, -31, 31)
+    number_list = parse_number_list(value)
     %{recurrence | by_month_day: number_list}
   end
 
   defp add_by_list_to_recurrence("YEARDAY", value, recurrence) do
-    number_list = to_clamped_numbers(value, -366, 366)
+    number_list = parse_number_list(value)
     %{recurrence | by_year_day: number_list}
   end
 
   defp add_by_list_to_recurrence("WEEKNO", value, recurrence) do
-    number_list = to_clamped_numbers(value, -53, 53)
+    number_list = parse_number_list(value)
     %{recurrence | by_week_number: number_list}
   end
 
   defp add_by_list_to_recurrence("SETPOS", value, recurrence) do
-    number_list = to_clamped_numbers(value, -366, 366)
+    number_list = parse_number_list(value)
     %{recurrence | by_set_position: number_list}
   end
 
@@ -112,33 +105,33 @@ defmodule ICal.Deserialize.Recurrence do
     end
   end
 
-  defp to_clamped_numbers(string, min, max) do
-    to_clamped_numbers(string, min, max, "", [])
+  def parse_number_list(string) do
+    string
+    |> accumulate_numbers("", [])
+    |> Enum.sort()
+    |> Enum.uniq()
   end
 
-  defp to_clamped_numbers(<<>>, min, max, value, acc) do
-    clamp_number(value, min, max, acc)
+  defp accumulate_numbers(<<>>, value, acc) do
+    accumulate_if_number(value, acc)
   end
 
-  defp to_clamped_numbers(<<?,, string::binary>>, min, max, value, acc) do
-    acc = clamp_number(value, min, max, acc)
-    to_clamped_numbers(string, min, max, "", acc)
+  defp accumulate_numbers(<<?,, string::binary>>, value, acc) do
+    acc = accumulate_if_number(value, acc)
+    accumulate_numbers(string, "", acc)
   end
 
-  defp to_clamped_numbers(<<c, string::binary>>, min, max, value, acc) do
-    to_clamped_numbers(string, min, max, <<value::binary, c>>, acc)
+  defp accumulate_numbers(<<c, string::binary>>, value, acc) do
+    accumulate_numbers(string, <<value::binary, c>>, acc)
   end
 
-  defp clamp_number(value, min, max, acc) do
+  defp accumulate_if_number(value, acc) do
     # zeros are only allowed when the min value is also zero:
     # a negative min means no zeros, and if the min is above zero, obviously
     # zero is not ok
     case Deserialize.to_integer(value) do
-      0 when min == 0 ->
-        acc ++ [0]
-
-      number when is_number(number) and number != 0 and number <= max and number >= min ->
-        acc ++ [number]
+      number when is_number(number) ->
+        [number | acc]
 
       _ ->
         acc
@@ -168,7 +161,7 @@ defmodule ICal.Deserialize.Recurrence do
   # no offset, so just send it in with a 0 for the offset, which the user will ignore
   # in a {0, someweekday} tuple
   defp to_weekdays(string, acc) do
-    to_weekday_with_offset(string, nil, acc)
+    to_weekday_with_offset(string, 0, acc)
   end
 
   # doing an entry with an offset, and we have more numbers,  so keep going