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


-- | Cron datatypes and Attoparsec parser
--   
@package cron
@version 0.2.2


-- | 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 Eq CronField
instance Eq DayOfWeekSpec
instance Eq MonthSpec
instance Eq DayOfMonthSpec
instance Eq HourSpec
instance Eq MinuteSpec
instance Eq CronSchedule
instance Eq CrontabEntry
instance Eq Crontab
instance Show CronUnit
instance Eq CronUnit
instance Show CronField
instance Show DayOfWeekSpec
instance Show MonthSpec
instance Show DayOfMonthSpec
instance Show HourSpec
instance Show MinuteSpec
instance Show CrontabEntry
instance Show Crontab
instance Show CronSchedule


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