BufferedSocket 0.2.0.0 → 0.2.1.0

raw patch · 4 files changed

+122/−17 lines, 4 filesdep ~basedep ~networkdep ~textPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

Dependency ranges changed: base, network, text

API changes (from Hackage documentation)

Files

• BufferedSocket.cabal +3/−3
• Network/BufferedSocket/Writer.hs +1/−13
• README +0/−1
• README.md +118/−0

@@ -10,7 +10,7 @@ -- PVP summary:      +-+------- breaking API changes --                   | | +----- non-breaking API additions --                   | | | +--- code changes with no API change-version:             0.2.0.0+version:             0.2.1.0  -- A short (one-line) description of the package. synopsis:            A socker wrapper that makes the IO of sockets much cleaner@@ -40,7 +40,7 @@  -- Extra files to be distributed with the package, such as examples or a  -- README.-extra-source-files:  README+extra-source-files:  README.md  -- Constraint on the version of Cabal needed to build this package. cabal-version:       >=1.10@@ -57,7 +57,7 @@   other-extensions:    OverloadedStrings, FlexibleInstances      -- Other library packages from which modules are imported.-  build-depends:       base >=4.7 && <4.8, bytestring >=0.10 && <0.11, text >=1.1 && <1.2, network >=2.4 && <2.5+  build-depends:       base >=4.7 && < 5.0, bytestring >=0.10 && <0.11, text >=1.1 && <1.3, network >=2.4 && <2.7      -- Directories containing source files.   -- hs-source-dirs:      

@@ -18,10 +18,7 @@ {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE FlexibleInstances #-} module Network.BufferedSocket.Writer-( sendText-, sendTextLazy-, sendString-, sendWord8+( sendWord8 , sendWord16 , sendWord32 , sendWord64@@ -106,15 +103,6 @@ sendLazy :: BS.BufferedSocket -> BL.ByteString -> IO () sendLazy bSocket lazyBytestring = sendLazyReal bSocket $ BL.toChunks lazyBytestring --sendText:: BS.BufferedSocket -> T.Text -> IO ()-sendText bSocket textData = BS.sendByteString bSocket $ ENC.encodeUtf8 textData--sendTextLazy:: BS.BufferedSocket -> TL.Text -> IO ()-sendTextLazy bSocket lazyText = sendLazy bSocket $ ENCL.encodeUtf8 lazyText--sendString:: BS.BufferedSocket -> String -> IO ()-sendString bSocket string = sendLazy bSocket $ fromString string   

@@ -1,1 +0,0 @@-This Package contains the source for a "BufferedSocket" These sockets are used as wrappers for normal network sockets but brings functions to easily manage the input and output of different kinds of data

@@ -0,0 +1,118 @@+### BufferedSocket+##### A wrapper for webSockets++This package is made to make reading and writing from network sockets easy in haskell.++To make a socket you need three things.++1. A socket made from the Network package (BufferedSockets doesn't meddle with your configuration so you have to do all this yourself)+2. Descide output buffer size ++3. Descide input buffer size++4. (party like it's 1969) ++this is done with the following function:+```haskell+makeBufferedSocket :: (Socket, SockAddr) -> InputBufferSize -> OutputBufferSize -> IO BufferedSocket+```+++###   The main functions for read and write:++#####  Reading:+```haskell+read :: BS.BufferedSocket -> IO r+```+The standard read is made to ready any basic data values.+This is amongst Word8 to Word64 and Int8 to Int64++```haskell+readString :: BS.BufferedSocket -> Int -> IO s+```+Thea readString funtcion can read both lazy and strict bytestrings. +But you need to provide the number of bytes to read.++To read any other kind of data is is reccomended to still use these functions. And then use decoding methods to get the data format you want. +++```haskell+readToByte :: BufferedSocket -> Word8 -> IO ByteString+readToByteMax :: BufferedSocket -> Word8 -> MaxLength -> IO (Maybe ByteString)++readToByteString :: BufferedSocket -> ByteString -> IO ByteString+readToByteStringMax :: BufferedSocket -> ByteString -> MaxLength -> IO (Maybe ByteString)+```+The above functions are made to scan the input buffer for specific bytes. All of them of course reads more data from the network if necesarry +However it is reccomended to use the "Max" verions of the functions as they put a limit to how much data may be read +++#####  Writing:+```haskell+send :: BS.BufferedSocket -> s -> IO ()+```+Sends any basic data type and both lazy and strict ByteStrings+If you wish to send any other kind of data use encoding methods for the data type.++```haskell+flush :: BufferedSocket -> IO ()+```+Data is not sent to the network unless:+1. The writing buffer is full+2. Flush is called+++###  Buffer functionalities +##### Input+The buffers are made to work is a fairly standard way. +Every time we read from the socket the socket first checks the buffer if data is available. If it is it will just aquire the data from the buffer. +If not then it will access the network and attempt to read for the ammount of bytes that are available in the buffer.+If not enthough space is available the first step is to see if clearing the offset will grant enoguh space. If not it will allow the  data to be saved elsewhere.+++##### Output+Is much simpler then Input. Simply puts the bytes together before sending. The actaul sending of data will only happend once the buffer is full OR the flush function is called++++###  Example code:+here under is some example code. Warning this is pretty pointless code!!! ++```haskell+{-# LANGUAGE OverloadedStrings #-}++import qualified Network.Socket as NS -- NS for "native socket"+import qualified BufferedSocket as BS +import qualified Data.ByteString as B++testServerPort = 1337+testHost = "localhost"+testServerMaxConnections = 1+++bufferSize = 1024 * 10++-- This is an example how to make a TCP server in haskell +-- Keep in mind that this is a pretty supid server ++makeTestTcpServer:: (BS.BufferedSocket -> IO ())  -> IO ()+makeTestTcpServer thunk  = NS.withSocketsDo $ do +    -- creates a tcp socket+    serverSock <- NS.socket NS.AF_INET NS.Stream 0+    -- Binds the socket to serve at address +    NS.bindSocket serverSock (NS.SockAddrInet testServerPort NS.iNADDR_ANY)++    NS.listen serverSock testServerMaxConnections+    socketData@(subSock,subSockaddr) <- NS.accept serverSock++    serverBSock <- BS.makeBufferedSocket socketData bufferSize bufferSize++    thunk serverBSock++    NS.sClose serverSock++main = makeTestTcpServer $ \bSock -> +            BS.send bSocket ("Hello world!" :: B.ByteString) +++```