-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Simplify static Networking tasks
--
-- A Networking library for static Networking tasks.
--
-- To learn about how to use this library in general, see
-- http://github.com/DanBurton/netspec#readme
@package netspec
@version 0.2.0.0
-- | Use Text to send and receive messages. For this module, a
-- message is a single line; the newline character acts as the
-- end-of-message flag.
module Network.NetSpec.Text
-- | Receive a Text message from a Handle.
receive :: MonadIO io => Handle -> io Text
-- | The staple for sending a message. ! is typeclassed so that
-- you can send or broadcast using the same simple syntax.
-- The CanSend typeclass is not exposed. Instances of CanSend
-- include Handle and Traversable t => t Handle.
--
-- ! produces an IO action lifted into any
-- MonadIO, so can be used without the extra cruft of
-- liftIO for most monad stacks. ! is declared as
-- infix 2.
--
-- Usage:
--
--
-- destination ! someText
--
(!) :: (CanSend h, MonadIO io) => h -> Text -> io ()
-- | Send a Text message to exactly one Handle.
send :: MonadIO io => Handle -> Text -> io ()
-- | Broadcast a Text message to multiple Handles.
broadcast :: MonadIO io => Foldable f => f Handle -> Text -> io ()
instance Foldable f => CanSend (f Handle)
instance CanSend Handle
-- | Use Lazy ByteStrings to send and receive messages. For this
-- module, a message is prefixed by a 64-bit little-endian signed
-- integer, indicating the length in bytes of the remaining message.
module Network.NetSpec.ByteString
-- | Receive a ByteString message from a Handle.
receive :: MonadIO io => Handle -> io ByteString
-- | The staple for sending a message. ! is typeclassed so that
-- you can send or broadcast using the same simple syntax.
-- The CanSend typeclass is not exposed. Instances of CanSend
-- include Handle and Traversable t => t Handle.
--
-- ! produces an IO action lifted into any
-- MonadIO, so can be used without the extra cruft of
-- liftIO for most monad stacks. ! is declared as
-- infix 2.
--
-- Usage:
--
--
-- destination ! someByteString
--
(!) :: (CanSend h, MonadIO io) => h -> ByteString -> io ()
-- | Send a ByteString message to exactly one Handle.
send :: MonadIO io => Handle -> ByteString -> io ()
-- | Broadcast a ByteString message to multiple Handles.
broadcast :: MonadIO io => Foldable f => f Handle -> ByteString -> io ()
instance Foldable f => CanSend (f Handle)
instance CanSend Handle
-- | Use Lazy ByteStrings of JSON to send and receive messages. For
-- this module, a message is prefixed by a 64-bit little-endian signed
-- integer, indicating the length in bytes of the remaining message,
-- which is encoded in JSON format.
module Network.NetSpec.Json
-- | Receive a JSON message from a Handle. Unlike Text and
-- ByteString, the result of this MonadIO action is wrapped in a
-- Maybe. Nothing means that the data received could not be
-- parsed from JSON to the correct data type. It is up to you to decide
-- whether or not to explicitly handle the Nothing case.
--
-- Notice that this action is polymorphic in its return type. Type
-- annotations are usually unnecessary, since type inference can usually
-- determine the correct target type. Example usage:
--
--
-- do Just m <- receive h
-- case m of Foo x y -> handleFoo x y
-- Bar z -> handleBar z
--
--
-- Here m is inferred to have whatever type Foo and
-- Bar belong to. This example code assumes that the JSON parse
-- will succeed. The fail function will be invoked for the Monad
-- you are working in if such a pattern match fails.
receive :: (MonadIO io, FromJSON j) => Handle -> io (Maybe j)
-- | The staple for sending a message. ! is typeclassed so that
-- you can send or broadcast using the same simple syntax.
-- The CanSendJson typeclass is not exposed. Instances of
-- CanSendJson include Handle and Traversable t => t
-- Handle.
--
-- ! produces an IO action lifted into any
-- MonadIO, so can be used without the extra cruft of
-- liftIO for most monad stacks. ! is declared as
-- infix 2.
--
-- Usage:
--
--
-- destination ! someData
--
--
-- Anything that is an instance of ToJSON can be used on the
-- right-hand side of !.
(!) :: (CanSendJson h, MonadIO io) => ToJSON j => h -> j -> io ()
-- | Send a JSON message to exactly one Handle.
send :: MonadIO io => ToJSON j => Handle -> j -> io ()
-- | Broadcast a JSON message to multiple Handles.
broadcast :: MonadIO io => (ToJSON j, Foldable f) => f Handle -> j -> io ()
-- | Derives ToJSON and FromJSON instances for your data
-- types. These are necessary in order to use the functions this module
-- provides with your custom data types.
--
-- Usage:
--
--
-- {-# LANGUAGE TemplateHaskell #-}
-- data Foo = Bar | Baz { quux :: Int }
-- $(deriveJson id ''Foo)
--
--
-- Alteratively, you could write your own instances.
deriveJson :: (String -> String) -> Name -> Q [Dec]
instance Foldable f => CanSendJson (f Handle)
instance CanSendJson Handle
-- | Simplify static Networking tasks.
module Network.NetSpec
-- | Define the specification of your networking task as a begin, loop, and
-- end proceedure. Run your NetSpec with runSpec.
--
-- t indicates the Traversable structure used.
-- [] is recommended for simplicity, but you are at liberty to
-- use any Traversable you see fit.
--
-- s indicates the type used for state. Use () for a
-- stateless specification.
--
-- A server must specify which ports to listen on, while a client instead
-- specifies tuples of (hostname, port) to connect to.
data NetSpec t s
ServerSpec :: t PortID -> (t Handle -> IO s) -> (t Handle -> s -> IO (SpecState s)) -> (t Handle -> s -> IO ()) -> NetSpec t s
_ports :: NetSpec t s -> t PortID
_begin :: NetSpec t s -> t Handle -> IO s
_loop :: NetSpec t s -> t Handle -> s -> IO (SpecState s)
_end :: NetSpec t s -> t Handle -> s -> IO ()
ClientSpec :: t (String, PortID) -> (t Handle -> IO s) -> (t Handle -> s -> IO (SpecState s)) -> (t Handle -> s -> IO ()) -> NetSpec t s
_conns :: NetSpec t s -> t (String, PortID)
_begin :: NetSpec t s -> t Handle -> IO s
_loop :: NetSpec t s -> t Handle -> s -> IO (SpecState s)
_end :: NetSpec t s -> t Handle -> s -> IO ()
-- | Indicate whether to Continue or Stop with a given
-- state
data SpecState s
Continue :: s -> SpecState s
Stop :: s -> SpecState s
-- | Run a NetSpec.
--
-- Running a spec will step through your Traversable of connection
-- descriptions, and replace each one with a Handle, preserving
-- the structure of the Traversable otherwise.
--
-- Regardless of exceptions, all Handles and Sockets opened by the spec
-- will be closed at the end of the run; you should not need to close any
-- of the Handles given to you by the spec.
--
-- (Note runSpec calls withSocketsDo for you)
runSpec :: Traversable t => NetSpec t s -> IO ()
-- | Continue with a given state
continue :: Monad m => s -> m (SpecState s)
-- | Continue (statless)
continue_ :: Monad m => m (SpecState ())
-- | Conditionally continue with a given state, based on that state and
-- additional given information.
--
-- Recommended usage:
--
--
-- _loop = \handles -> continueIf f .: runStateT $ do ...
--
continueIf :: Monad m => (a -> s -> Bool) -> m (a, s) -> m (SpecState s)
-- | Conditionally continue with a given state, based solely on that state.
--
-- Recommended usage:
--
--
-- _loop = \handles -> continueIf' f .: execStateT $ do ...
--
continueIf' :: Monad m => (s -> Bool) -> m s -> m (SpecState s)
-- | Conditionally continue statelessly, based on given information.
--
-- Recommended usage
--
--
-- _loop = \handles () -> continueIf_ f $ do ...
--
continueIf_ :: Monad m => (a -> Bool) -> m a -> m (SpecState ())
-- | Stop with a given state
stop :: Monad m => s -> m (SpecState s)
-- | Stop (stateless)
stop_ :: Monad m => m (SpecState ())
-- | Conditionally stop with a given state, based on that state and
-- additional given information.
stopIf :: Monad m => (a -> s -> Bool) -> m (a, s) -> m (SpecState s)
-- | Conditionally stop with a given state, based solely on that state.
stopIf' :: Monad m => (s -> Bool) -> m s -> m (SpecState s)
-- | Conditionally stop statlessly, based on given information.
stopIf_ :: Monad m => (a -> Bool) -> m a -> m (SpecState ())
-- | Compose two functions, similar to . from Prelude. If
-- h = f .: g then h x y = f (g x y).
(.:) :: (a -> b) -> (c -> d -> a) -> c -> d -> b
-- | Lift a state function into a StateT monad stack
stateT :: Monad m => (s -> (a, s)) -> StateT s m a
instance Functor SpecState