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

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 Show CronCommand
instance Eq CronCommand
instance Ord CronCommand
instance ShowT CronCommand
instance Eq SpecificField
instance ShowT SpecificField
instance Eq RangeField
instance Eq BaseField
instance Eq StepField
instance Eq DayOfWeekSpec
instance ShowT DayOfWeekSpec
instance Eq MonthSpec
instance ShowT MonthSpec
instance Eq DayOfMonthSpec
instance ShowT DayOfMonthSpec
instance Eq HourSpec
instance ShowT HourSpec
instance Eq MinuteSpec
instance ShowT MinuteSpec
instance Eq CronSchedule
instance Eq CrontabEntry
instance Eq Crontab
instance Show StepField
instance ShowT StepField
instance Show CronField
instance ShowT CronField
instance Eq CronField
instance Show RangeField
instance ShowT RangeField
instance Show SpecificField
instance Show BaseField
instance ShowT BaseField
instance Show DayOfWeekSpec
instance Show MonthSpec
instance Show DayOfMonthSpec
instance Show HourSpec
instance Show MinuteSpec
instance Show CrontabEntry
instance ShowT CrontabEntry
instance Show Crontab
instance ShowT Crontab
instance ShowT CronSchedule
instance Show CronSchedule
instance ShowT Int
instance ShowT Text


-- | 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 Show 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 Show ScheduleError
instance Functor m => Functor (ScheduleT m)
instance (Monad m, Functor m) => Applicative (ScheduleT m)
instance Monad m => Monad (ScheduleT m)
instance Monad m => MonadState Jobs (ScheduleT m)
instance Monad m => MonadError ScheduleError (ScheduleT m)
instance Monad m => MonadSchedule (ScheduleT m)
instance Show Job

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