Network/Stream.hs

-----------------------------------------------------------------------------
-- |
-- Module : Network.Stream
-- Copyright : See LICENSE file
-- License : BSD
--
-- Maintainer : Ganesh Sittampalam <ganesh@earth.li>
-- Stability : experimental
-- Portability : non-portable (not tested)
--
-- An library for creating abstract streams. Originally part of Gray's\/Bringert's
-- HTTP module.
--
-- * Changes by Robin Bate Boerop <robin@bateboerop.name>:
-- - Removed unnecessary import statements.
-- - Moved Debug code to StreamDebugger.hs
-- - Moved Socket-related code to StreamSocket.hs.
--
-- * Changes by Simon Foster:
-- - Split Network.HTTPmodule up into to separate
-- Network.[Stream,TCP,HTTP] modules
-----------------------------------------------------------------------------
module Network.Stream
 ( Stream(..)
 , ConnError(..)
 , Result
 , bindE
 , fmapE

 , failParse -- :: String -> Result a
 , failWith -- :: ConnError -> Result a
 , failMisc -- :: String -> Result a
 ) where

import Control.Monad.Error

data ConnError 
 = ErrorReset 
 | ErrorClosed
 | ErrorParse String
 | ErrorMisc String
 deriving(Show,Eq)

instance Error ConnError where
 noMsg = strMsg "unknown error"
 strMsg x = ErrorMisc x

-- in GHC 7.0 the Monad instance for Error no longer
-- uses fail x = Left (strMsg x). failMisc is therefore
-- used instead.
failMisc :: String -> Result a
failMisc x = failWith (strMsg x)

failParse :: String -> Result a
failParse x = failWith (ErrorParse x)

failWith :: ConnError -> Result a
failWith x = Left x

bindE :: Result a -> (a -> Result b) -> Result b
bindE (Left e) _ = Left e
bindE (Right v) f = f v

fmapE :: (a -> Result b) -> IO (Result a) -> IO (Result b)
fmapE f a = do
 x <- a
 case x of
 Left e -> return (Left e)
 Right r -> return (f r) 
 
-- | This is the type returned by many exported network functions.
type Result a = Either ConnError {- error -}
 a {- result -}

-- | Streams should make layering of TLS protocol easier in future,
-- they allow reading/writing to files etc for debugging,
-- they allow use of protocols other than TCP/IP
-- and they allow customisation.
--
-- Instances of this class should not trim
-- the input in any way, e.g. leave LF on line
-- endings etc. Unless that is exactly the behaviour
-- you want from your twisted instances ;)
class Stream x where 
 readLine :: x -> IO (Result String)
 readBlock :: x -> Int -> IO (Result String)
 writeBlock :: x -> String -> IO (Result ())
 close :: x -> IO ()
 closeOnEnd :: x -> Bool -> IO ()
 -- ^ True => shutdown the connection when response has been read / end-of-stream
 -- has been reached.