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


-- | A streamable, seekable, zoomable cache file format
--   
--   This library provides a monadic writing and iteratee reading interface
--   for zoom-cache files.
@package zoom-cache
@version 0.2.1.1


-- | The minimum and maximum positive, finite floats.
module Numeric.FloatMinMax

-- | The minimum positive, denormalized float.
floatMin :: RealFloat a => a

-- | The maximum denormalized float.
floatMaxDenorm :: RealFloat a => a

-- | The minimum positive, normalized float.
floatMinNorm :: RealFloat a => a

-- | The maximum finite float.
floatMax :: RealFloat a => a


-- | Types used throughout zoom-cache
module Data.ZoomCache.Common
data HeaderType
GlobalHeader :: HeaderType
TrackHeader :: HeaderType
PacketHeader :: HeaderType
SummaryHeader :: HeaderType
data TimeStamp
TS :: !Integer -> TimeStamp
unTS :: TimeStamp -> !Integer
data TrackType
ZDouble :: TrackType
ZInt :: TrackType

-- | Constant or Variable datarate. For constant datarate, timestamps are
--   implied as incrementing by 1/datarate For variable datarate, explicit
--   timestamps are attached to each datum, encoded as a separate block of
--   timestamps in the Raw Data packet.
data DataRateType
ConstantDR :: DataRateType
VariableDR :: DataRateType
type TrackNo = Int
data Global
Global :: Version -> Int -> Rational -> Rational -> Maybe Int -> Global
version :: Global -> Version
noTracks :: Global -> Int
presentationTime :: Global -> Rational
baseTime :: Global -> Rational
baseUTC :: Global -> Maybe Int

-- | Magic identifier at the beginning of a zoom-cache file.
globalHeader :: ByteString

-- | Global and track headers for a zoom-cache file
data CacheFile
CacheFile :: Global -> IntMap TrackSpec -> CacheFile
cfGlobal :: CacheFile -> Global
cfSpecs :: CacheFile -> IntMap TrackSpec

-- | Create an empty <a>CacheFile</a> using the given <a>Global</a>
mkCacheFile :: Global -> CacheFile

-- | Determine whether all tracks of a <a>CacheFile</a> are specified
fiFull :: CacheFile -> Bool
data Version
Version :: Int -> Int -> Version

-- | The major version encoded by this library
versionMajor :: Int

-- | The minor version encoded by this library
versionMinor :: Int

-- | A map of all track numbers to their <a>TrackSpec</a>
type TrackMap = IntMap TrackSpec

-- | A specification of the type and name of each track
data TrackSpec
TrackSpec :: TrackType -> DataRateType -> Rational -> ByteString -> TrackSpec
specType :: TrackSpec -> TrackType
specDRType :: TrackSpec -> DataRateType
specRate :: TrackSpec -> Rational
specName :: TrackSpec -> ByteString

-- | Identifier for track headers
trackHeader :: ByteString

-- | Identifier for packet headers
packetHeader :: ByteString

-- | Identifier for summary headers
summaryHeader :: ByteString
instance Eq TimeStamp
instance Ord TimeStamp
instance Show TimeStamp
instance Eq Version
instance Show Version
instance Show Global
instance Eq TrackType
instance Show TrackType
instance Show DataRateType
instance Show TrackSpec


-- | ZoomCache Summary definition
module Data.ZoomCache.Summary

-- | A recorded block of summary data
data Summary
SummaryDouble :: TrackNo -> Int -> TimeStamp -> TimeStamp -> Double -> Double -> Double -> Double -> Double -> Double -> Summary
summaryTrack :: Summary -> TrackNo
summaryLevel :: Summary -> Int
summaryEntryTime :: Summary -> TimeStamp
summaryExitTime :: Summary -> TimeStamp
summaryDoubleEntry :: Summary -> Double
summaryDoubleExit :: Summary -> Double
summaryDoubleMin :: Summary -> Double
summaryDoubleMax :: Summary -> Double
summaryAvg :: Summary -> Double
summaryRMS :: Summary -> Double
SummaryInt :: TrackNo -> Int -> TimeStamp -> TimeStamp -> Int -> Int -> Int -> Int -> Double -> Double -> Summary
summaryTrack :: Summary -> TrackNo
summaryLevel :: Summary -> Int
summaryEntryTime :: Summary -> TimeStamp
summaryExitTime :: Summary -> TimeStamp
summaryIntEntry :: Summary -> Int
summaryIntExit :: Summary -> Int
summaryIntMin :: Summary -> Int
summaryIntMax :: Summary -> Int
summaryAvg :: Summary -> Double
summaryRMS :: Summary -> Double

-- | The duration covered by a summary, in units of 1 / the track's
--   datarate
summaryDuration :: Summary -> Integer

-- | Append two Summaries, merging statistical summary data. XXX: summaries
--   are only compatible if tracks and levels are equal
appendSummary :: Summary -> Summary -> Summary
instance Show Summary


-- | ZoomCache packet definition
module Data.ZoomCache.Packet
data Packet
Packet :: TrackNo -> TimeStamp -> TimeStamp -> Int -> PacketData -> [TimeStamp] -> Packet
packetTrack :: Packet -> TrackNo
packetEntryTime :: Packet -> TimeStamp
packetExitTime :: Packet -> TimeStamp
packetCount :: Packet -> Int
packetData :: Packet -> PacketData
packetTimeStamps :: Packet -> [TimeStamp]
data PacketData
PDDouble :: [Double] -> PacketData
PDInt :: [Int] -> PacketData


-- | Pretty-printing of zoom-cache types
module Data.ZoomCache.Pretty

-- | Pretty-print a <a>Global</a>
prettyGlobal :: Global -> String

-- | Pretty-print a <a>TrackSpec</a>
prettyTrackSpec :: TrackNo -> TrackSpec -> String

-- | Pretty-print a <a>TimeStamp</a>, given a datarate
prettyTimeStamp :: Rational -> TimeStamp -> String

-- | Pretty-print a <a>Summary</a>, given a datarate
prettySummary :: Rational -> Summary -> String


-- | Iteratee reading of ZoomCache files.
module Data.Iteratee.ZoomCache
data Stream
StreamPacket :: CacheFile -> TrackNo -> Packet -> Stream
strmFile :: Stream -> CacheFile
strmTrack :: Stream -> TrackNo
strmPacket :: Stream -> Packet
StreamSummary :: CacheFile -> TrackNo -> Summary -> Stream
strmFile :: Stream -> CacheFile
strmTrack :: Stream -> TrackNo
strmSummary :: Stream -> Summary
StreamNull :: Stream

-- | Parse only the global and track headers of a zoom-cache file,
--   returning a <a>CacheFile</a>
iterHeaders :: (Functor m, MonadIO m) => Iteratee [Word8] m CacheFile

-- | An enumeratee of a zoom-cache file, from the global header onwards.
--   The global and track headers will be transparently read, and the
--   <a>CacheFile</a> visible in the <a>Stream</a> elements.
enumCacheFile :: (Functor m, MonadIO m) => Enumeratee [Word8] Stream m a

-- | An enumeratee of zoom-cache data, after global and track headers have
--   been read, or if the <a>CacheFile</a> has been acquired elsewhere.
enumStream :: (Functor m, MonadIO m) => CacheFile -> Enumeratee [Word8] Stream m a

-- | Map a monadic <a>Stream</a> processing function over an entire
--   zoom-cache file.
mapStream :: (Functor m, MonadIO m) => (Stream -> m ()) -> Iteratee [Word8] m ()

-- | Map a monadic <a>Packet</a> processing function over an entire
--   zoom-cache file.
mapPackets :: (Functor m, MonadIO m) => (Packet -> m ()) -> Iteratee [Word8] m ()

-- | Map a monadic <a>Summary</a> processing function over an entire
--   zoom-cache file.
mapSummaries :: (Functor m, MonadIO m) => (Summary -> m ()) -> Iteratee [Word8] m ()
instance ZReadable Int
instance ZReadable Double
instance NullPoint Stream
instance Nullable Stream


-- | Reading of ZoomCache files.
module Data.ZoomCache.Read
zoomDumpFile :: TrackNo -> FilePath -> IO ()
zoomDumpSummary :: TrackNo -> FilePath -> IO ()
zoomDumpSummaryLevel :: TrackNo -> Int -> FilePath -> IO ()
zoomInfoFile :: FilePath -> IO ()


-- | Blaze-builder utility functions for writing ZoomCache files.
module Data.ZoomCache.Binary
encInt :: Integral a => a -> Builder
encInt64 :: Integral a => a -> Builder
encDbl :: Double -> Builder
fromRational64 :: Rational -> Builder
fromGlobal :: Global -> Builder
fromTrackType :: TrackType -> Builder
fromDataRateType :: DataRateType -> Builder
fromTrackNo :: TrackNo -> Builder
fromSummary :: Summary -> Builder
toWord64 :: Double -> Word64


-- | Writing of ZoomCache files.
module Data.ZoomCache.Write

-- | The ZoomWrite class provides <a>write</a>, a method to write a Haskell
--   value to an open ZoomCache file.
class ZoomWrite t
write :: ZoomWrite t => TrackNo -> t -> ZoomW ()

-- | A StateT IO monad for writing a ZoomCache file
type ZoomW = StateT ZoomWHandle IO

-- | Run a <tt>ZoomW ()</tt> action on a given file handle, using the
--   specified <a>TrackMap</a> specification
withFileWrite :: TrackMap -> Bool -> ZoomW () -> FilePath -> IO ()

-- | Force a flush of ZoomCache summary blocks to disk. It is not usually
--   necessary to call this function as summary blocks are transparently
--   written at regular intervals.
flush :: ZoomW ()
data ZoomWHandle

-- | Open a new ZoomCache file for writing, using a specified
--   <a>TrackMap</a>.
openWrite :: TrackMap -> Bool -> FilePath -> IO ZoomWHandle

-- | Query the maximum number of data points to buffer for a given track
--   before forcing a flush of all buffered data and summaries.
watermark :: TrackNo -> ZoomW (Maybe Int)

-- | Set the maximum number of data points to buffer for a given track
--   before forcing a flush of all buffered data and summaries.
setWatermark :: TrackNo -> Int -> ZoomW ()

-- | Create a track map for a stream of a given type, as track no. 1
oneTrack :: TrackType -> DataRateType -> Rational -> ByteString -> TrackMap
instance ZoomWrite (TimeStamp, Int)
instance ZoomWrite (TimeStamp, Double)
instance ZoomWrite Int
instance ZoomWrite Double