defmodule Cocktail do
  @moduledoc """
  Top level types and convenience functions.

  This module holds some top-level types and a convenience function for
  creating a new schedule. Details available in the `Cocktail.Schedule` module.
  """

  alias Cocktail.{Schedule, Span}

  @type frequency :: :weekly   |
                     :daily    |
                     :hourly   |
                     :minutely |
                     :secondly

  @type day_number :: 0..6

  @type day_atom :: :monday    |
                    :tuesday   |
                    :wednesday |
                    :thursday  |
                    :friday    |
                    :saturday  |
                    :sunday

  @type day :: day_number | day_atom

  @type hour_number :: 0..23

  @type minute_number :: 0..59

  @type second_number :: 0..59

  @type schedule_option :: {:duration, pos_integer}

  @type schedule_options :: [schedule_option]

  @type rule_option :: {:frequency, frequency}     |
                       {:interval, pos_integer}    |
                       {:count, pos_integer}       |
                       {:until, time}              |
                       {:days, [day]}              |
                       {:hours, [hour_number]}     |
                       {:minutes, [minute_number]} |
                       {:seconds, [second_number]}

  @type rule_options :: [rule_option]

  @type time :: DateTime.t | NaiveDateTime.t

  @type occurrence :: time | Span.t

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

  see `Cocktail.Schedule.new/1` for details.
  """
  @spec schedule(time, schedule_options) :: Schedule.t
  def schedule(start_time, options \\ []), do: Schedule.new(start_time, options)
end