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


-- | Cron datatypes and Attoparsec parser
--   
--   Cron data structure and Attoparsec parser. The idea is to embed it in
--   larger systems which want to roll their own scheduled tasks in a
--   format that people are used to. <a>System.Cron</a> is where all the
--   interesting datatypes live. You will also find <a>scheduleMatches</a>,
--   which you can use to compare a time against a <a>CronSchedule</a> to
--   see if an action needs to be performed. System.Cron.Parser is where
--   you will find the parsers <a>cronSchedule</a>, <a>crontabEntry</a> and
--   <a>cronTab</a>. To parse individual schedules up to full crontab
--   files.
@package cron
@version 0.4.0

module System.Cron.Types

-- | Specification for a cron expression
data CronSchedule
CronSchedule :: MinuteSpec -> HourSpec -> DayOfMonthSpec -> MonthSpec -> DayOfWeekSpec -> CronSchedule

-- | Which minutes to run. First field in a cron specification.
[minute] :: CronSchedule -> MinuteSpec

-- | Which hours to run. Second field in a cron specification.
[hour] :: CronSchedule -> HourSpec

-- | Which days of the month to run. Third field in a cron specification.
[dayOfMonth] :: CronSchedule -> DayOfMonthSpec

-- | Which months to run. Fourth field in a cron specification.
[month] :: CronSchedule -> MonthSpec

-- | Which days of the week to run. Fifth field in a cron specification.
[dayOfWeek] :: CronSchedule -> DayOfWeekSpec

-- | Crontab file, omitting comments.
newtype Crontab
Crontab :: [CrontabEntry] -> Crontab
[crontabEntries] :: Crontab -> [CrontabEntry]

-- | Essentially a line in a crontab file. It is either a schedule with a
--   command after it or setting an environment variable (e.g. FOO=BAR)
data CrontabEntry
CommandEntry :: CronSchedule -> CronCommand -> CrontabEntry
EnvVariable :: Text -> Text -> CrontabEntry

-- | Minutes field of a cron expression
data MinuteSpec
newtype CronCommand
CronCommand :: Text -> CronCommand
[cronCommand] :: CronCommand -> Text
minuteSpec :: MinuteSpec -> CronField
mkMinuteSpec :: CronField -> Maybe MinuteSpec

-- | Hours field of a cron expression
data HourSpec
hourSpec :: HourSpec -> CronField
mkHourSpec :: CronField -> Maybe HourSpec

-- | Month field of a cron expression
data MonthSpec
monthSpec :: MonthSpec -> CronField
mkMonthSpec :: CronField -> Maybe MonthSpec

-- | Day of month field of a cron expression
data DayOfMonthSpec
dayOfMonthSpec :: DayOfMonthSpec -> CronField
mkDayOfMonthSpec :: CronField -> Maybe DayOfMonthSpec

-- | Day of week field of a cron expression
data DayOfWeekSpec
dayOfWeekSpec :: DayOfWeekSpec -> CronField
mkDayOfWeekSpec :: CronField -> Maybe DayOfWeekSpec

-- | Individual field of a cron expression.
data BaseField

-- | Matches anything
Star :: BaseField

-- | Matches a specific value (e.g. 1)
SpecificField' :: SpecificField -> BaseField

-- | Matches a range of values (e.g. 1-3)
RangeField' :: RangeField -> BaseField
data SpecificField
specificField :: SpecificField -> Int
mkSpecificField :: Int -> Maybe SpecificField
data RangeField
rfBegin :: RangeField -> Int
rfEnd :: RangeField -> Int
mkRangeField :: Int -> Int -> Maybe RangeField
data CronField
Field :: BaseField -> CronField

-- | Matches a list of expressions.
ListField :: (NonEmpty BaseField) -> CronField

-- | Matches a stepped expression, e.g. (*/2).
StepField' :: StepField -> CronField
data StepField
sfField :: StepField -> BaseField
sfStepping :: StepField -> Int
mkStepField :: BaseField -> Int -> Maybe StepField

-- | Shorthand for every January 1st at midnight. Parsed with @yearly, 0 0
--   1 1 *
yearly :: CronSchedule

-- | Shorthand for every 1st of the month at midnight. Parsed with
--   @monthly, 0 0 1 * *
monthly :: CronSchedule

-- | Shorthand for every day at midnight. Parsed with @daily, 0 0 * * *
daily :: CronSchedule

-- | Shorthand for every sunday at midnight. Parsed with @weekly, 0 0 * * 0
weekly :: CronSchedule

-- | Shorthand for every hour on the hour. Parsed with @hourly, 0 * * * *
hourly :: CronSchedule

-- | Shorthand for an expression that always matches. Parsed with * * * * *
everyMinute :: CronSchedule
serializeCronSchedule :: CronSchedule -> Text
serializeCrontab :: Crontab -> Text
instance GHC.Classes.Eq System.Cron.Types.Crontab
instance GHC.Classes.Eq System.Cron.Types.CrontabEntry
instance GHC.Classes.Eq System.Cron.Types.CronSchedule
instance System.Cron.Types.ShowT System.Cron.Types.MinuteSpec
instance GHC.Classes.Eq System.Cron.Types.MinuteSpec
instance System.Cron.Types.ShowT System.Cron.Types.HourSpec
instance GHC.Classes.Eq System.Cron.Types.HourSpec
instance System.Cron.Types.ShowT System.Cron.Types.DayOfMonthSpec
instance GHC.Classes.Eq System.Cron.Types.DayOfMonthSpec
instance System.Cron.Types.ShowT System.Cron.Types.MonthSpec
instance GHC.Classes.Eq System.Cron.Types.MonthSpec
instance System.Cron.Types.ShowT System.Cron.Types.DayOfWeekSpec
instance GHC.Classes.Eq System.Cron.Types.DayOfWeekSpec
instance GHC.Classes.Eq System.Cron.Types.StepField
instance GHC.Classes.Eq System.Cron.Types.BaseField
instance GHC.Classes.Eq System.Cron.Types.RangeField
instance System.Cron.Types.ShowT System.Cron.Types.SpecificField
instance GHC.Classes.Eq System.Cron.Types.SpecificField
instance System.Cron.Types.ShowT System.Cron.Types.CronCommand
instance GHC.Classes.Ord System.Cron.Types.CronCommand
instance GHC.Classes.Eq System.Cron.Types.CronCommand
instance GHC.Show.Show System.Cron.Types.CronCommand
instance System.Cron.Types.ShowT Data.Text.Internal.Text
instance System.Cron.Types.ShowT GHC.Types.Int
instance GHC.Show.Show System.Cron.Types.CronSchedule
instance System.Cron.Types.ShowT System.Cron.Types.CronSchedule
instance System.Cron.Types.ShowT System.Cron.Types.Crontab
instance GHC.Show.Show System.Cron.Types.Crontab
instance System.Cron.Types.ShowT System.Cron.Types.CrontabEntry
instance GHC.Show.Show System.Cron.Types.CrontabEntry
instance GHC.Show.Show System.Cron.Types.MinuteSpec
instance GHC.Show.Show System.Cron.Types.HourSpec
instance GHC.Show.Show System.Cron.Types.DayOfMonthSpec
instance GHC.Show.Show System.Cron.Types.MonthSpec
instance GHC.Show.Show System.Cron.Types.DayOfWeekSpec
instance System.Cron.Types.ShowT System.Cron.Types.BaseField
instance GHC.Show.Show System.Cron.Types.BaseField
instance GHC.Show.Show System.Cron.Types.SpecificField
instance System.Cron.Types.ShowT System.Cron.Types.RangeField
instance GHC.Show.Show System.Cron.Types.RangeField
instance GHC.Classes.Eq System.Cron.Types.CronField
instance System.Cron.Types.ShowT System.Cron.Types.CronField
instance GHC.Show.Show System.Cron.Types.CronField
instance System.Cron.Types.ShowT System.Cron.Types.StepField
instance GHC.Show.Show System.Cron.Types.StepField


-- | Attoparsec parser combinator for cron schedules. See cron
--   documentation for how those are formatted.
--   
--   <pre>
--   import System.Cron.Parser
--   
--   main :: IO ()
--   main = don
--     print $ parseCronSchedule "*/2 * 3 * 4,5,6"
--   </pre>
module System.Cron.Parser

-- | Attoparsec Parser for a cron schedule. Complies fully with the
--   standard cron format. Also includes the following shorthand formats
--   which cron also supports: @yearly, @monthly, @weekly, @daily, @hourly.
--   Note that this parser will fail if there is extraneous input. This is
--   to prevent things like extra fields. If you want a more lax parser,
--   use <a>cronScheduleLoose</a>, which is fine with extra input.
cronSchedule :: Parser CronSchedule

-- | Same as <a>cronSchedule</a> but does not fail on extraneous input.
cronScheduleLoose :: Parser CronSchedule

-- | Parses a full crontab file, omitting comments and including
--   environment variable sets (e.g FOO=BAR).
crontab :: Parser Crontab

-- | Parses an individual crontab line, which is either a scheduled command
--   or an environmental variable set.
crontabEntry :: Parser CrontabEntry
parseCronSchedule :: Text -> Either String CronSchedule
parseCrontab :: Text -> Either String Crontab
parseCrontabEntry :: Text -> Either String CrontabEntry

module System.Cron.Internal.Check

-- | Will return the next time from the given starting point where this
--   schedule will match. Returns Nothing if the schedule will never match.
--   Note that this function is not inclusive of the given time: the result
--   will always be at least 1 minute beyond the given time. This is
--   usually used to implement absolute timestamp schedulers. If you need
--   to see multiple matches ahead, just keep feeding the result into
--   nextMatch. Note that because nextMatch only returns Nothing on a
--   schedule that will *never* be matched, it is safe to assume that if a
--   schedule returns a Just once, it will always return a Just.
nextMatch :: CronSchedule -> UTCTime -> Maybe UTCTime
nextMatches :: [Day] -> Expanded -> UTCTime -> [UTCTime]
dowMatch :: UTCTime -> EField -> Bool

-- | ISO8601 maps Sunday as 7 and Monday as 1, we want Sunday as 0
getDOW :: Day -> Int
validDays :: EField -> EField -> Day -> [Day]

-- | Guarantees: the Expanded will be satisfiable (no invalid dates, no
--   empties). dow 7 will be normalized to 0 (Sunday)
expand :: CronSchedule -> Maybe Expanded
expandF :: (Int, Int) -> CronField -> Maybe EField
expandBFStepped :: (Int, Int) -> BaseField -> Int -> Maybe EField
fillTo :: (Int, Int) -> Int -> [Int]
expandBF :: (Int, Int) -> BaseField -> Maybe EField
validTODs :: EField -> EField -> [DiffTime]
todToDiffTime :: Int -> Int -> DiffTime
timeOfDay :: DiffTime -> (Int, Int)
hasValidForMonth :: Int -> EField -> Bool
data Expanded
Expanded :: EField -> EField -> EField -> EField -> EField -> Expanded
[minF] :: Expanded -> EField
[hourF] :: Expanded -> EField
[domF] :: Expanded -> EField
[monthF] :: Expanded -> EField
[dowF] :: Expanded -> EField
type EField = NonEmpty Int

-- | Does the given cron schedule match for the given timestamp? This is
--   usually used for implementing polling-type schedulers like cron
--   itself.
scheduleMatches :: CronSchedule -> UTCTime -> Bool
restricted :: CronField -> Bool
isStar :: CronField -> Bool
instance GHC.Show.Show System.Cron.Internal.Check.Expanded


-- | <pre>
--   main :: IO ()
--   main = do
--          ...
--          tids &lt;- execSchedule $ do
--              addJob job1 "* * * * *"
--              addJob job2 "0 * * * *"
--          print tids
--          ...
--   
--   job1 :: IO ()
--   job1 = putStrLn "Job 1"
--   
--   job2 :: IO ()
--   job2 = putStrLn "Job 2"
--   </pre>
module System.Cron.Schedule

-- | Scheduling Monad
data Job
Job :: CronSchedule -> (IO ()) -> Job
data ScheduleError
ParseError :: String -> ScheduleError
type Schedule = ScheduleT Identity
newtype ScheduleT m a
ScheduleT :: StateT Jobs (ExceptT ScheduleError m) a -> ScheduleT m a
[unSchedule] :: ScheduleT m a -> StateT Jobs (ExceptT ScheduleError m) a
class MonadSchedule m
addJob :: MonadSchedule m => IO () -> String -> m ()
runSchedule :: Schedule a -> Either ScheduleError (a, [Job])
runScheduleT :: ScheduleT m a -> m (Either ScheduleError (a, [Job]))

-- | Schedule all of the jobs to run at appropriate intervals. Each job
--   that is launched gets a scheduling thread to itself. Each time a
--   scheduling thread launches a job, the job is forked onto a new thread.
--   This means that if a job throws an excpetion in IO, its thread will be
--   killed, but it will continue to be scheduled in the future.
execSchedule :: Schedule () -> IO [ThreadId]
instance GHC.Base.Monad m => Control.Monad.Error.Class.MonadError System.Cron.Schedule.ScheduleError (System.Cron.Schedule.ScheduleT m)
instance GHC.Base.Monad m => Control.Monad.State.Class.MonadState System.Cron.Schedule.Jobs (System.Cron.Schedule.ScheduleT m)
instance GHC.Base.Monad m => GHC.Base.Monad (System.Cron.Schedule.ScheduleT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (System.Cron.Schedule.ScheduleT m)
instance GHC.Base.Functor m => GHC.Base.Functor (System.Cron.Schedule.ScheduleT m)
instance GHC.Show.Show System.Cron.Schedule.ScheduleError
instance GHC.Show.Show System.Cron.Schedule.Job
instance GHC.Base.Monad m => System.Cron.Schedule.MonadSchedule (System.Cron.Schedule.ScheduleT m)

module System.Cron

-- | Does the given cron schedule match for the given timestamp? This is
--   usually used for implementing polling-type schedulers like cron
--   itself.
scheduleMatches :: CronSchedule -> UTCTime -> Bool

-- | Will return the next time from the given starting point where this
--   schedule will match. Returns Nothing if the schedule will never match.
--   Note that this function is not inclusive of the given time: the result
--   will always be at least 1 minute beyond the given time. This is
--   usually used to implement absolute timestamp schedulers. If you need
--   to see multiple matches ahead, just keep feeding the result into
--   nextMatch. Note that because nextMatch only returns Nothing on a
--   schedule that will *never* be matched, it is safe to assume that if a
--   schedule returns a Just once, it will always return a Just.
nextMatch :: CronSchedule -> UTCTime -> Maybe UTCTime