-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Patterns for recurring events
--   
--   This package contains a set of primitives and combinators for event
--   patterns. Example:
--   
--   <pre>
--   &gt;&gt; import qualified Prelude as P
--   &gt;&gt; let sundays = every 2 sunday
--   &gt;&gt; let today = fromGregorian 2013 12 01
--   &gt;&gt; P.take 2 $ instancesFrom today sundays
--   [2013-12-08, 2013-12-22]
--   </pre>
--   
--   See <tt>Data.Time.Patterns</tt> for more examples.
@package time-patterns
@version 0.1.4.3


-- | Internal stuff for time patterns
module Data.Time.Patterns.Internal

-- | A sequence of intervals, starting from a point. If the argument to
--   <tt>nextInterval</tt> is part of an interval, then the result should
--   be the interval containing it.
newtype IntervalSequence t s
IntervalSequence :: t -> Maybe (Interval s, IntervalSequence t s) -> IntervalSequence t s
[nextInterval] :: IntervalSequence t s -> t -> Maybe (Interval s, IntervalSequence t s)

-- | IntervalSequences that can be evaluated repeatedly.
type IntervalSequence' t = IntervalSequence t t

-- | A sequence with no occurrences
never :: IntervalSequence t s

-- | Occurrences from both intervals. The difference between <tt>union</tt>
--   and <tt>diag</tt> is that <tt>union</tt> preserves the order of the
--   results
union :: Ord s => IntervalSequence t s -> IntervalSequence t s -> IntervalSequence t s

-- | Merge two sequences into one by switching between them
diag :: IntervalSequence t s -> IntervalSequence t s -> IntervalSequence t s

-- | End a sequence after n occurrences
take :: (Num i, Ord i) => i -> IntervalSequence t s -> IntervalSequence t s

-- | Repeat a point infinitely
cycle :: Interval s -> IntervalSequence t s

-- | Take occurrences until an interval containing the argument is reached
stopAt :: Ord s => Interval s -> IntervalSequence t s -> IntervalSequence t s

-- | Take occurrences until an interval whose supremum is greater than the
--   argument is reached.
stopAt' :: Ord s => s -> IntervalSequence t s -> IntervalSequence t s

-- | Stop as soon as a result greater than or equal to the parameter is
--   produced
before :: Ord s => Interval s -> IntervalSequence t s -> IntervalSequence t s

-- | Prepend an interval to an interval sequence
andThen :: Interval s -> IntervalSequence t s -> IntervalSequence t s

-- | Take every nth occurrence
every :: (Num i, Ord i) => i -> IntervalSequence' t -> IntervalSequence' t

-- | Accept results which satisfy a condition
filter :: (Interval t -> Bool) -> IntervalSequence' t -> IntervalSequence' t

-- | Check if a point is covered by an interval sequence
elementOf :: Ord t => t -> IntervalSequence' t -> Bool

-- | The sequence of occurrences from an initial point.
occurrencesFrom :: t -> IntervalSequence' t -> [Interval t]

-- | Elements covered by an interval sequence from an initial point.
elementsFrom :: Enum t => t -> IntervalSequence' t -> [t]
mapSequence :: (a -> b) -> IntervalSequence t a -> IntervalSequence t b

-- | Skip the first n occurrences of a sequence
skip :: (Num i, Ord i) => i -> IntervalSequence' t -> IntervalSequence' t

-- | Skip intervals until the infimum of the argument is reached.
--   
--   If the intervals in the sequence are not ordered, then this function
--   might not terminate.
skipUntil :: Ord t => Interval t -> IntervalSequence' t -> IntervalSequence' t

-- | Skip over a point in the sequence. All occurrences of this datum are
--   removed.
except :: (Enum t, Ord t) => t -> IntervalSequence' t -> IntervalSequence' t

-- | Skip over all intervals which contain the parameter
except' :: Ord t => Interval t -> IntervalSequence' t -> IntervalSequence' t

-- | Search for the first result within the specified interval, starting
--   from a point.
--   
--   If the intervals in the sequence are not ordered, then this function
--   might not terminate.
firstOccurrenceIn :: (Enum t, Ord t) => t -> Interval t -> IntervalSequence' t -> Maybe (Interval t, IntervalSequence' t)

-- | Return intervals that are exactly the same
intersect :: (Ord t, Enum t) => IntervalSequence' t -> IntervalSequence' t -> IntervalSequence' t
elements :: Enum a => Interval a -> [a]
instance GHC.Classes.Ord s => GHC.Base.Semigroup (Data.Time.Patterns.Internal.IntervalSequence t s)
instance GHC.Classes.Ord s => GHC.Base.Monoid (Data.Time.Patterns.Internal.IntervalSequence t s)


-- | Patterns for recurring events. Use the <tt>DatePattern</tt> type to
--   build up a pattern, and the functions <tt>elementOf</tt>,
--   <tt>instancesFrom</tt> and <tt>intervalsFrom</tt> to evaluate it.
--   Simple example:
--   
--   <pre>
--   import Control.Lens
--   import Data.Time.Calendar (fromGregorian)
--   import Data.Time.Patterns
--   import qualified Prelude as P
--   Module Main where
--   
--   main = do
--     -- get the 6th of April for the next ten years
--     let april6 = (take 1 $ skip 5 day) `inEach` april
--     let today =  fromGregorian 2013 12 01
--     print $ P.take 10 $ instancesFrom today april6
--   </pre>
--   
--   <tt>DatePattern</tt>s can be combined using <tt>union</tt>,
--   <tt>intersect</tt> with their obvious meanings and <tt>inEach</tt>
--   which repeats one pattern inside another one. For example,
--   
--   <pre>
--   ((take 1 day) `inEach` august) `intersect` sunday
--   </pre>
--   
--   will give the 1st of August in years when it falls on a Sunday.
module Data.Time.Patterns

-- | A <a>DatePattern</a> describes a sequence of intervals of type
--   <a>Day</a>.
type DatePattern = IntervalSequence' Day

-- | An event that occurs every day.
day :: DatePattern

-- | Weeks, starting on Monday
mondayWeek :: DatePattern

-- | Weeks, starting on Sunday.
sundayWeek :: DatePattern

-- | An event that occurs every month.
month :: DatePattern

-- | Years, starting from Jan. 1
year :: DatePattern

-- | Every January.
january :: DatePattern

-- | Every February.
february :: DatePattern

-- | Every March.
march :: DatePattern

-- | Every April.
april :: DatePattern

-- | Every May.
may :: DatePattern

-- | Every June.
june :: DatePattern

-- | Every July.
july :: DatePattern

-- | Every August.
august :: DatePattern

-- | Every September.
september :: DatePattern

-- | Every October.
october :: DatePattern

-- | Every November.
november :: DatePattern

-- | Every December.
december :: DatePattern

-- | Every Monday.
monday :: DatePattern

-- | Every Tuesday.
tuesday :: DatePattern

-- | Every Wednesday.
wednesday :: DatePattern

-- | Every Thursday.
thursday :: DatePattern

-- | Every Friday.
friday :: DatePattern

-- | Every Saturday.
saturday :: DatePattern

-- | Every Sunday.
sunday :: DatePattern

-- | An event that never occurs
never :: DatePattern

-- | Take every nth occurrence
every :: (Num i, Ord i) => i -> DatePattern -> DatePattern

-- | Shift all the results by a number of day
shiftBy :: Integer -> DatePattern -> DatePattern

-- | The first pattern repeated for each interval of the second pattern.
--   E.g.:
--   
--   <pre>
--   (take 3 $ every 4 monday) `inEach` year
--   </pre>
--   
--   will give the fourth, eighth and twelveth Monday in each year
inEach :: DatePattern -> DatePattern -> DatePattern

-- | Stop after n occurrences
take :: (Num i, Ord i) => i -> DatePattern -> DatePattern

-- | Skip the first n occurrences
skip :: (Num i, Ord i) => i -> DatePattern -> DatePattern

-- | Skip over all occurrences of a day. If the pattern describes a period
--   longer than a day, the entire period will be skipped.
except :: Day -> DatePattern -> DatePattern

-- | Return only occurrences that are present in both patterns
--   
--   <pre>
--   let myBirthday = (take 1 day) `inEach` august
--   let s = intersect myBirthday sunday
--   </pre>
--   
--   Will return August 1 in years when it falls on a Sunday
intersect :: DatePattern -> DatePattern -> DatePattern

-- | Occurrences of both patterns.
--   
--   <pre>
--   union april june
--   </pre>
--   
--   Will return the months April and June in each year
--   
--   <pre>
--   let fifteenth = (take 1 $ skip 14 day) `inEach` month
--   let third = (take 1 $ skip 2 day) `inEach` month
--   union fifteenth third
--   </pre>
--   
--   Will return the 3rd and the 15th of each month
union :: DatePattern -> DatePattern -> DatePattern

-- | Only include date intervals that end before the given date.
--   
--   <pre>
--   &gt;&gt; let third = (take 1 $ skip 2 day) `inEach` month
--   &gt;&gt; let pattern = third `until` (fromGregorian 2020 12 01)
--   &gt;&gt; instancesFrom (fromGregorian 2017 01 01) pattern
--   [2017-01-03,2017-02-03 ... 2020-10-03,2020-11-03]
--   </pre>
until :: DatePattern -> Day -> DatePattern

-- | Check if a date is covered by a DatePattern
elementOf :: Day -> DatePattern -> Bool

-- | Get occurrences of an event starting with a given day
instancesFrom :: Day -> DatePattern -> [Day]

-- | Get the date intervals described by the pattern, starting from the
--   specified date.
--   
--   The intervals range from the first day included by the pattern to the
--   first day after it, so a single day <tt>d</tt> would be described as
--   <tt>(d ... succ d)</tt> and the interval for a month will go from the
--   1st of the month to the 1st of the next month.
intervalsFrom :: Day -> DatePattern -> [Interval Day]