Merge pull request #37 from peek-travel/x-tensions

Add a new proprietary extension: X-BYRANGE

Author: doughsay

CHANGELOG.md

@@ -5,6 +5,12 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased][]
+### Breaking
+-   The `BYTIME` option of `RRULE`s in the iCalendar output is now `X-BYTIME` to better follow the standard's extensions policy
+
+### Added
+-   "time range" option (e.g. `Schedule.add_recurrence_rules(:daily, time_range: %{start_time: ~T[09:00:00], end_time: ~T[11:00:00], interval_seconds: 1_800})`; this serializes to `X-BYRANGE` in iCalendar format, using the extension prefix to signal that it's a proprietary extension)
+
 ### Changed
 -   Formatted code-base with the new Elixir 1.6 code formatter
 -   Changed `Schedule.t()` to not be an opaque type, which fixed the few missing typespecs

README.md

@@ -27,7 +27,7 @@ by adding `cocktail` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:cocktail, "~> 0.7"}
+    {:cocktail, "~> 0.8"}
   ]
 end
 ```

lib/cocktail.ex

@@ -22,6 +22,12 @@ defmodule Cocktail do
 
   @type second_number :: 0..59
 
+  @type time_range :: %{
+          start_time: Time.t(),
+          end_time: Time.t(),
+          interval_seconds: second_number()
+        }
+
   @type schedule_option :: {:duration, pos_integer}
 
   @type schedule_options :: [schedule_option]
@@ -36,6 +42,7 @@ defmodule Cocktail do
           | {:minutes, [minute_number]}
           | {:seconds, [second_number]}
           | {:times, [Time.t()]}
+          | {:time_range, time_range}
 
   @type rule_options :: [rule_option]
 

lib/cocktail/builder/i_calendar.ex

@@ -6,7 +6,7 @@ defmodule Cocktail.Builder.ICalendar do
   """
 
   alias Cocktail.{Rule, Schedule, Validation}
-  alias Cocktail.Validation.{Interval, Day, HourOfDay, MinuteOfHour, SecondOfMinute, TimeOfDay}
+  alias Cocktail.Validation.{Interval, Day, HourOfDay, MinuteOfHour, SecondOfMinute, TimeOfDay, TimeRange}
 
   @time_format_string "{YYYY}{0M}{0D}T{h24}{m}{s}"
 
@@ -92,7 +92,7 @@ defmodule Cocktail.Builder.ICalendar do
   @spec build_rule(Rule.t()) :: String.t()
   defp build_rule(%Rule{validations: validations_map, until: until, count: count}) do
     parts =
-      for key <- [:interval, :day, :hour_of_day, :minute_of_hour, :second_of_minute, :time_of_day],
+      for key <- [:interval, :day, :hour_of_day, :minute_of_hour, :second_of_minute, :time_of_day, :time_range],
           validation = validations_map[key],
           !is_nil(validation) do
         build_validation_part(key, validation)
@@ -110,6 +110,7 @@ defmodule Cocktail.Builder.ICalendar do
   defp build_validation_part(:minute_of_hour, %MinuteOfHour{minutes: minutes}), do: minutes |> build_minutes()
   defp build_validation_part(:second_of_minute, %SecondOfMinute{seconds: seconds}), do: seconds |> build_seconds()
   defp build_validation_part(:time_of_day, %TimeOfDay{times: times}), do: times |> build_times()
+  defp build_validation_part(:time_range, %TimeRange{} = time_range), do: time_range |> build_time_range()
 
   @spec build_until(Cocktail.time() | nil) :: [String.t()]
   defp build_until(nil), do: []
@@ -193,14 +194,26 @@ defmodule Cocktail.Builder.ICalendar do
     times_list =
       times
       |> Enum.sort()
-      |> Enum.map(fn {hour, min, sec} ->
-        hours = String.pad_leading("#{hour}", 2, "0")
-        mins = String.pad_leading("#{min}", 2, "0")
-        secs = String.pad_leading("#{sec}", 2, "0")
-        "#{hours}#{mins}#{secs}"
-      end)
+      |> Enum.map(&format_erl_time/1)
       |> Enum.join(",")
 
-    "BYTIME=#{times_list}"
+    "X-BYTIME=#{times_list}"
   end
+
+  defp format_erl_time({hour, min, sec}) do
+    hours = String.pad_leading("#{hour}", 2, "0")
+    mins = String.pad_leading("#{min}", 2, "0")
+    secs = String.pad_leading("#{sec}", 2, "0")
+
+    "#{hours}#{mins}#{secs}"
+  end
+
+  # "time range" validation
+
+  @spec build_time_range(TimeRange.t()) :: String.t()
+  defp build_time_range(%TimeRange{start_time: start_time, end_time: end_time, interval_seconds: interval}) do
+    "X-BYRANGE=" <> ([format_time(start_time), format_time(end_time), interval] |> Enum.join(","))
+  end
+
+  defp format_time(time), do: time |> Time.to_erl() |> format_erl_time
 end

lib/cocktail/parser/i_calendar.ex

@@ -183,12 +183,18 @@ defmodule Cocktail.Parser.ICalendar do
     end
   end
 
-  defp parse_rrule_option("BYTIME=" <> times_string) do
+  defp parse_rrule_option("X-BYTIME=" <> times_string) do
     with {:ok, times} <- parse_times_string(times_string) do
       {:ok, {:times, times |> Enum.reverse()}}
     end
   end
 
+  defp parse_rrule_option("X-BYRANGE=" <> range_string) do
+    with {:ok, time_range} <- parse_range_string(range_string) do
+      {:ok, {:time_range, time_range}}
+    end
+  end
+
   defp parse_rrule_option(_), do: {:error, :unknown_rrulparam}
 
   @spec parse_frequency(String.t()) :: {:ok, Cocktail.frequency()} | {:error, :invalid_frequency}
@@ -364,16 +370,56 @@ defmodule Cocktail.Parser.ICalendar do
     |> parse_times([])
   end
 
-  @spec parse_times([String.t()], [Time.t()]) :: {:ok, [Time.t()]}
+  @spec parse_times([String.t()], [Time.t()]) :: {:ok, [Time.t()]} | {:error, :invalid_time_format}
   defp parse_times([], times), do: {:ok, times}
 
   defp parse_times([time_string | rest], times) do
-    with {:ok, datetime} <- Timex.parse(time_string, @time_format) do
-      time = NaiveDateTime.to_time(datetime)
+    with {:ok, time} <- parse_time(time_string) do
       parse_times(rest, [time | times])
     end
   end
 
+  @spec parse_time(String.t()) :: {:ok, Time.t()} | {:error, :invalid_time_format}
+  defp parse_time(time_string) do
+    with {:ok, datetime} <- Timex.parse(time_string, @time_format) do
+      {:ok, NaiveDateTime.to_time(datetime)}
+    else
+      _ ->
+        {:error, :invalid_time_format}
+    end
+  end
+
+  # time range
+
+  @spec parse_range_string(String.t()) :: {:ok, Cocktail.time_range()} | {:error, :invalid_time_range}
+  defp parse_range_string(""), do: {:error, :invalid_time_range}
+
+  defp parse_range_string(range_string) do
+    range_string
+    |> String.split(",")
+    |> parse_range()
+  end
+
+  @spec parse_range([String.t()]) :: {:ok, Cocktail.time_range()}
+  defp parse_range([start_time_string, end_time_string, interval_seconds_string]) do
+    with {:ok, start_time} <- parse_time(start_time_string),
+         {:ok, end_time} <- parse_time(end_time_string),
+         {interval_seconds, _} <- Integer.parse(interval_seconds_string) do
+      time_range = %{
+        start_time: start_time,
+        end_time: end_time,
+        interval_seconds: interval_seconds
+      }
+
+      {:ok, time_range}
+    else
+      _ ->
+        {:error, :invalid_time_range}
+    end
+  end
+
+  defp parse_range(_), do: {:error, :invalid_time_range}
+
   # rdates and exdates
 
   @spec parse_rdate(String.t(), Schedule.t(), non_neg_integer) :: {:ok, Schedule.t()} | {:error, term}

lib/cocktail/rule_state.ex

@@ -24,6 +24,7 @@ defmodule Cocktail.RuleState do
     :base_hour,
     :hour_of_day,
     :time_of_day,
+    :time_range,
     :base_wday,
     :day,
     :interval

lib/cocktail/validation.ex

@@ -8,7 +8,8 @@ defmodule Cocktail.Validation do
     HourOfDay,
     MinuteOfHour,
     SecondOfMinute,
-    TimeOfDay
+    TimeOfDay,
+    TimeRange
   }
 
   @type validation_key ::
@@ -21,6 +22,7 @@ defmodule Cocktail.Validation do
           | :minute_of_hour
           | :second_of_minute
           | :time_of_day
+          | :time_range
           | :interval
 
   @type validations_map :: %{validation_key => t}
@@ -33,6 +35,7 @@ defmodule Cocktail.Validation do
           | MinuteOfHour.t()
           | SecondOfMinute.t()
           | TimeOfDay.t()
+          | TimeRange.t()
 
   @spec build_validations(Cocktail.rule_options()) :: validations_map
   def build_validations(options) do
@@ -125,6 +128,15 @@ defmodule Cocktail.Validation do
     |> apply_options(rest)
   end
 
+  defp apply_options(map, [{:time_range, time_range} | rest]) do
+    map
+    |> Map.delete(:base_sec)
+    |> Map.delete(:base_min)
+    |> Map.delete(:base_hour)
+    |> Map.put(:time_range, TimeRange.new(time_range))
+    |> apply_options(rest)
+  end
+
   # unhandled option, just discard and continue
   defp apply_options(map, [{_, _} | rest]), do: map |> apply_options(rest)
 end

lib/cocktail/validation/time_range.ex

@@ -0,0 +1,79 @@
+defmodule Cocktail.Validation.TimeRange do
+  @moduledoc false
+
+  alias Cocktail.Validation.TimeOfDay
+
+  @type t :: %__MODULE__{
+          start_time: Time.t(),
+          end_time: Time.t(),
+          interval_seconds: Cocktail.second_number(),
+          time_of_day: TimeOfDay.t()
+        }
+
+  @enforce_keys [:start_time, :end_time, :interval_seconds]
+  defstruct start_time: nil,
+            end_time: nil,
+            interval_seconds: nil,
+            time_of_day: nil
+
+  @spec new(Cocktail.time_range()) :: t()
+  def new(attrs) do
+    time_range = struct!(__MODULE__, attrs)
+    times = generate_times(time_range)
+
+    %{time_range | time_of_day: TimeOfDay.new(times)}
+  end
+
+  @spec generate_times(t()) :: [Time.t()]
+  defp generate_times(%__MODULE__{} = time_range) do
+    time_range.start_time
+    |> Stream.unfold(fn time ->
+      case Time.compare(time, time_range.end_time) do
+        :gt ->
+          nil
+
+        _ ->
+          {time, time_add(time, time_range.interval_seconds)}
+      end
+    end)
+    |> Enum.to_list()
+  end
+
+  @spec next_time(t(), Cocktail.time(), Cocktail.time()) :: Cocktail.Validation.Shift.result()
+  def next_time(%__MODULE__{time_of_day: time_of_day}, time, start_time),
+    do: TimeOfDay.next_time(time_of_day, time, start_time)
+
+  if Version.compare(System.version(), "1.6.0") == :lt do
+    # Yanked from Elixir 1.6.1 source code.  Remove once we drop support for Elixir < 1.6.
+    @spec time_add(Calendar.time(), integer, System.time_unit()) :: t
+    defp time_add(%{calendar: calendar} = time, number, unit \\ :second) when is_integer(number) do
+      number = System.convert_time_unit(number, unit, :microsecond)
+      iso_days = {0, to_day_fraction(time)}
+      total = Calendar.ISO.iso_days_to_unit(iso_days, :microsecond) + number
+      iso_ppd = 86_400_000_000
+      parts = Integer.mod(total, iso_ppd)
+
+      {hour, minute, second, microsecond} = calendar.time_from_day_fraction({parts, iso_ppd})
+
+      %Time{
+        hour: hour,
+        minute: minute,
+        second: second,
+        microsecond: microsecond,
+        calendar: calendar
+      }
+    end
+
+    defp to_day_fraction(%{
+           hour: hour,
+           minute: minute,
+           second: second,
+           microsecond: {_, _} = microsecond,
+           calendar: calendar
+         }) do
+      calendar.time_to_day_fraction(hour, minute, second, microsecond)
+    end
+  else
+    defp time_add(time, amount, unit \\ :second), do: Time.add(time, amount, unit)
+  end
+end

mix.exs

@@ -1,7 +1,7 @@
 defmodule Cocktail.Mixfile do
   use Mix.Project
 
-  @version "0.7.0"
+  @version "0.8.0"
 
   def project do
     [
@@ -69,7 +69,6 @@ defmodule Cocktail.Mixfile do
       {:excoveralls, "~> 0.7", only: :test},
       {:inch_ex, ">= 0.0.0", only: :docs},
       {:mix_test_watch, "~> 0.3", only: :dev, runtime: false},
-      {:poison, ">= 2.0.0"},
       {:timex, "~> 3.1"}
     ]
   end

test/cocktail/reversibility_test.exs

@@ -90,6 +90,16 @@ defmodule Cocktail.ReversibilityTest do
     |> assert_reversible()
   end
 
+  test "time range option" do
+    ~N[2017-09-09 09:00:00]
+    |> Schedule.new()
+    |> Schedule.add_recurrence_rule(
+      :daily,
+      time_range: %{start_time: ~T[09:00:00], end_time: ~T[11:00:00], interval_seconds: 1_800}
+    )
+    |> assert_reversible()
+  end
+
   test "empty days" do
     ~N[2017-09-09 09:00:00] |> Schedule.new() |> Schedule.add_recurrence_rule(:daily, days: []) |> assert_reversible()
   end

test/cocktail/validation/time_range_test.exs

@@ -0,0 +1,50 @@
+defmodule Cocktail.TimeRangeTest do
+  use ExUnit.Case
+
+  alias Cocktail.{Schedule}
+
+  import Cocktail.TestSupport.DateTimeSigil
+
+  test "a daily schedule with a time range option" do
+    schedule =
+      ~N[2017-09-09 09:00:00]
+      |> Schedule.new()
+      |> Schedule.add_recurrence_rule(
+        :daily,
+        time_range: %{start_time: ~T[09:00:00], end_time: ~T[11:00:00], interval_seconds: 1_800}
+      )
+
+    times = schedule |> Schedule.occurrences() |> Enum.take(6)
+
+    assert times == [
+             ~N[2017-09-09 09:00:00],
+             ~N[2017-09-09 09:30:00],
+             ~N[2017-09-09 10:00:00],
+             ~N[2017-09-09 10:30:00],
+             ~N[2017-09-09 11:00:00],
+             ~N[2017-09-10 09:00:00]
+           ]
+  end
+
+  test "a daily schedule with a zoned datetime and a time range option" do
+    schedule =
+      ~N[2017-09-09 09:00:00]
+      |> Timex.to_datetime("America/Chicago")
+      |> Schedule.new()
+      |> Schedule.add_recurrence_rule(
+        :daily,
+        time_range: %{start_time: ~T[09:00:00], end_time: ~T[11:00:00], interval_seconds: 1_800}
+      )
+
+    times = schedule |> Schedule.occurrences() |> Enum.take(6)
+
+    assert times == [
+             ~Y[2017-09-09 09:00:00 America/Chicago],
+             ~Y[2017-09-09 09:30:00 America/Chicago],
+             ~Y[2017-09-09 10:00:00 America/Chicago],
+             ~Y[2017-09-09 10:30:00 America/Chicago],
+             ~Y[2017-09-09 11:00:00 America/Chicago],
+             ~Y[2017-09-10 09:00:00 America/Chicago]
+           ]
+  end
+end