-- 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.3.1


-- | Toplevel module for Cron specifying a cron schedule and several
--   convenience functions for dealing with cron schedules
--   
--   <pre>
--   import Control.Concurrent
--   import Control.Monad
--   import Data.Time.Clock
--   import System.Cron
--   
--   main :: IO ()
--   main = forever $ do
--            now &lt;- getCurrentTime
--            when (scheduleMatches schedule now) doWork
--            putStrLn "sleeping"
--            threadDelay 100000
--          where doWork   = putStrLn "Time to work"
--                schedule = hourly
--   </pre>
module System.Cron

-- | 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

-- | 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 -> Text -> CrontabEntry
[schedule] :: CrontabEntry -> CronSchedule
[command] :: CrontabEntry -> Text
EnvVariable :: Text -> Text -> CrontabEntry
[varName] :: CrontabEntry -> Text
[varValue] :: CrontabEntry -> Text

-- | Minutes field of a cron expression
data MinuteSpec
Minutes :: CronField -> MinuteSpec

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

-- | Month field of a cron expression
data MonthSpec
Months :: CronField -> MonthSpec

-- | Day of month field of a cron expression
data DayOfMonthSpec
DaysOfMonth :: CronField -> DayOfMonthSpec

-- | Day of week field of a cron expression
data DayOfWeekSpec
DaysOfWeek :: CronField -> DayOfWeekSpec

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

-- | Matches anything
Star :: CronField

-- | Matches a specific value (e.g. 1)
SpecificField :: Int -> CronField

-- | Matches a range of values (e.g. 1-3)
RangeField :: Int -> Int -> CronField

-- | Matches a list of expressions. Recursive lists are invalid and the
--   parser will never produce them.
ListField :: [CronField] -> CronField

-- | Matches a stepped expression, e.g. (*/2). Recursive steps or stepped
--   lists are invalid and the parser will never produce them.
StepField :: CronField -> Int -> CronField

-- | 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

-- | Determines if the given time is matched by the given schedule. A
--   periodical task would use this to determine if an action needs to be
--   performed at the current time or not.
scheduleMatches :: CronSchedule -> UTCTime -> Bool
instance GHC.Classes.Eq System.Cron.CronUnit
instance GHC.Show.Show System.Cron.CronUnit
instance GHC.Classes.Eq System.Cron.Crontab
instance GHC.Classes.Eq System.Cron.CrontabEntry
instance GHC.Classes.Eq System.Cron.CronSchedule
instance GHC.Classes.Eq System.Cron.MinuteSpec
instance GHC.Classes.Eq System.Cron.HourSpec
instance GHC.Classes.Eq System.Cron.DayOfMonthSpec
instance GHC.Classes.Eq System.Cron.MonthSpec
instance GHC.Classes.Eq System.Cron.DayOfWeekSpec
instance GHC.Classes.Eq System.Cron.CronField
instance GHC.Show.Show System.Cron.CronSchedule
instance GHC.Show.Show System.Cron.Crontab
instance GHC.Show.Show System.Cron.CrontabEntry
instance GHC.Show.Show System.Cron.MinuteSpec
instance GHC.Show.Show System.Cron.HourSpec
instance GHC.Show.Show System.Cron.DayOfMonthSpec
instance GHC.Show.Show System.Cron.MonthSpec
instance GHC.Show.Show System.Cron.DayOfWeekSpec
instance GHC.Show.Show System.Cron.CronField


-- | Attoparsec parser combinator for cron schedules. See cron
--   documentation for how those are formatted.
--   
--   <pre>
--   import Data.Attoparsec.Text (parseOnly)
--   import System.Cron.Parser
--   
--   main :: IO ()
--   main = do
--     print $ parseOnly cronSchedule "*/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


-- | <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
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)