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


-- | Support library to enable TAI usage on systems with time kept in UTC.
--   
--   This library manages leap second data to allow using TAI time inspite
--   of the system clock being kept in UTC.
@package tai
@version 0

module Data.Time.Clock.TAI.Parser

-- | Parse a leap second list
parseLeapSecondList :: String -> Either String LeapSecondList
data LeapSecondList
LeapSecondList :: Day -> Day -> String -> [(Day, Int32)] -> LeapSecondList
[expirationDate] :: LeapSecondList -> Day
[lastUpdate] :: LeapSecondList -> Day
[expectedHash] :: LeapSecondList -> String
[leapSeconds] :: LeapSecondList -> [(Day, Int32)]
instance GHC.Show.Show Data.Time.Clock.TAI.Parser.LeapSecondList
instance GHC.Classes.Ord Data.Time.Clock.TAI.Parser.LeapSecondList
instance GHC.Classes.Eq Data.Time.Clock.TAI.Parser.LeapSecondList
instance GHC.Show.Show Data.Time.Clock.TAI.Parser.TAIEntry
instance GHC.Classes.Ord Data.Time.Clock.TAI.Parser.TAIEntry
instance GHC.Classes.Eq Data.Time.Clock.TAI.Parser.TAIEntry

module Data.Time.Clock.TAI.LeapData

-- | A support type for deperating out the protocol over which to retrieve
--   data.
data SourceType
File :: SourceType
HTTPS :: SourceType

-- | A leap second list location tagged with a protocol for retrieving it.
data LeapSource
LeapSource :: SourceType -> String -> LeapSource
[sourceType] :: LeapSource -> SourceType
[source] :: LeapSource -> String

-- | LeapSources is a list of strings, specifying URIs the program can
--   potentially access up-to-date leap-second.lists from. Each source
--   begins with a protocol: For local sources "file://" followed by a path
--   to the local file. For remote source sources "<a>https://"</a>
--   prefixed URIs.
type LeapSources = [LeapSource]

-- | Convert a string source to a LeapSource
parseLeapSource :: String -> Maybe LeapSource

-- | Given a LeapSource, perform the actual aquasition and parsing
mayRetrieveList :: LeapSource -> IO (Maybe LeapSecondList)

-- | Parse a leap second list file, failing if it is expired.
parseFileMaybe :: Day -> String -> Maybe LeapSecondList

-- | A few places we should be able to download up-to-date
--   leap-seconds.list data.
leapSources :: LeapSources

-- | Aquire leap-seconds files and parse them, Trying the provided list of
--   sources in order from local, to secure remote (HTTPS), until an
--   up-to-date source is aquired or all options are exausted.
--   
--   Currently only local and HTTPS has been implimented.
sourceLeapData :: LeapSources -> IO LeapSecondList
instance GHC.Classes.Ord Data.Time.Clock.TAI.LeapData.LeapSource
instance GHC.Classes.Eq Data.Time.Clock.TAI.LeapData.LeapSource
instance GHC.Read.Read Data.Time.Clock.TAI.LeapData.LeapSource
instance GHC.Show.Show Data.Time.Clock.TAI.LeapData.LeapSource
instance GHC.Classes.Ord Data.Time.Clock.TAI.LeapData.SourceType
instance GHC.Enum.Enum Data.Time.Clock.TAI.LeapData.SourceType
instance GHC.Enum.Bounded Data.Time.Clock.TAI.LeapData.SourceType
instance GHC.Classes.Eq Data.Time.Clock.TAI.LeapData.SourceType
instance GHC.Read.Read Data.Time.Clock.TAI.LeapData.SourceType
instance GHC.Show.Show Data.Time.Clock.TAI.LeapData.SourceType

module Data.Time.Clock.TAI.Support

-- | Our data about TAI in relation to UTC and this system.
data TAISync

-- | A function that enacts the periodic update of the LeapSecondList leap
--   second data. Usually periodicBackgroundDownload will satisfy a user's
--   needs, but some enviroments may want another policy.
type UpdatePolicy = IO (IORef LeapSecondList)

-- | Given an UpdatePolicy, generate a TAISync to be used to interact with
--   TAI though the other library functions.
initSync :: MonadIO m => UpdatePolicy -> m TAISync

-- | Get the current TAI time.
getTAI :: MonadIO m => TAISync -> m AbsoluteTime

-- | Given our information about leap seconds, generate a UTC time from a
--   TAI time as a total function. As the relation between TAI is only
--   known for a specific time range, we give a best-guess outside said
--   time range. Specificly we only know the offset after some point in the
--   past, and up to about 6 months into the future. Outside this range we
--   assume the last known mapping between UTC and TAI doesn't drift.
absGuessUtc :: MonadIO m => TAISync -> AbsoluteTime -> m UTCTime

-- | Given our information about leap seconds, generate a TAI time rom a
--   UTC time as a total function. As the relation between TAI is only
--   known for a specific time range, we give a best-guess outside said
--   time range. Specificly we only know the offset after some point in the
--   past, and up to about 6 months into the future. Outside this range we
--   assume the last known mapping between UTC and TAI doesn't drift.
utcGuessAbs :: MonadIO m => TAISync -> UTCTime -> m AbsoluteTime

-- | Gets the current leap second data in a <tt>time</tt> compatable form.
currentLeapMap :: MonadIO m => TAISync -> m LeapSecondTable

-- | Update the leap second table by redownloading the tables periodicly in
--   the background. This policy uses the TimeoutManager to check for a new
--   table every dbetween days, trying again dretry if there is a failure.
--   Recomended values are 30 and 1 for these. Given the validity period
--   for leap second data, this should generally suffice. There can be
--   problems with local files being near their expiration though.
--   
--   This policy requires a threaded runtime.
periodicBackgroundDownload :: LeapSources -> Int -> Int -> UpdatePolicy
instance GHC.Exception.Exception Data.Time.Clock.TAI.Support.TimeSyncException
instance GHC.Show.Show Data.Time.Clock.TAI.Support.TimeSyncException