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


-- | gopher server daemon
--   
--   simple gopher server daemon
@package spacecookie
@version 0.2.0.1


-- | Helper utilities used within the library and the server which also
--   could be useful for other application code.
module Network.Gopher.Util

-- | Normalise a path and prevent <a>directory traversal attacks</a>.
santinizePath :: FilePath -> FilePath
santinizeIfNotUrl :: FilePath -> FilePath

-- | <a>ord</a> a <a>Word8</a>
asciiOrd :: Char -> Word8

-- | <a>chr</a> a <a>Word8</a>
asciiChr :: Word8 -> Char

-- | Encode a <a>String</a> to a UTF-8 <a>ByteString</a>
uEncode :: String -> ByteString

-- | Decode a UTF-8 <a>ByteString</a> to a <a>String</a>
uDecode :: ByteString -> String

-- | Strip <tt>\r</tt> and <tt>\n</tt> from <a>ByteString</a>s
stripNewline :: ByteString -> ByteString


-- | This module implements a parser for <a>gophermap files</a>.
--   
--   Example usage:
--   
--   <pre>
--   import Network.Gopher.Util.Gophermap
--   import qualified Data.ByteString as B
--   import Data.Attoparsec.ByteString
--   
--   main = do
--     file &lt;- B.readFile "gophermap"
--     print $ parseOnly parseGophermap file
--   </pre>
module Network.Gopher.Util.Gophermap

-- | Attoparsec <a>Parser</a> for the <a>gophermap file format</a>
parseGophermap :: Parser Gophermap

-- | A gophermap entry makes all values of a gopher menu item optional
--   except for file type and description. When converting to a
--   <a>GopherMenuItem</a>, appropriate default values are used.
data GophermapEntry

-- | file type, description, path, server name, port number
GophermapEntry :: GopherFileType -> ByteString -> Maybe FilePath -> Maybe ByteString -> Maybe Integer -> GophermapEntry
type Gophermap = [GophermapEntry]

-- | Convert a gophermap to a gopher menu response.
gophermapToDirectoryResponse :: Gophermap -> GopherResponse
instance GHC.Classes.Eq Network.Gopher.Util.Gophermap.GophermapEntry
instance GHC.Show.Show Network.Gopher.Util.Gophermap.GophermapEntry


-- | <h1>Overview</h1>
--   
--   This is the main module of the spacecookie library. It allows to write
--   gopher applications by taking care of handling gopher requests while
--   leaving the application logic to a user-supplied function.
--   
--   For a small tutorial an example of a trivial pure gopher application:
--   
--   <pre>
--   import Network.Gopher
--   import Network.Gopher.Util
--   
--   main = do
--     <a>runGopherPure</a> (<a>GopherConfig</a> "localhost" 7000 Nothing) (\req -&gt; <a>FileResponse</a> (<a>uEncode</a> req))
--   </pre>
--   
--   This server just returns the request string as a file.
--   
--   There are three possibilities for a <a>GopherResponse</a>:
--   
--   <ul>
--   <li><a>FileResponse</a>: file type agnostic file response, takes a
--   <a>ByteString</a> to support both text and binary files</li>
--   <li><a>MenuResponse</a>: a gopher menu (“directory listning”)
--   consisting of a list of <a>GopherMenuItem</a>s</li>
--   <li><a>ErrorResponse</a>: gopher way to show an error (e. g. if a file
--   is not found). A <a>ErrorResponse</a> results in a menu response with
--   a single entry.</li>
--   </ul>
--   
--   If you use <a>runGopher</a>, it is the same story like in the example
--   above, but you can do <a>IO</a> effects. To see a more elaborate
--   example, have a look at the server code in this package.
module Network.Gopher

-- | Run a gopher application that may cause effects in <a>IO</a>. The
--   application function is given the gopher request (path) and required
--   to produce a GopherResponse.
runGopher :: GopherConfig -> (String -> IO GopherResponse) -> IO ()

-- | Run a gopher application that may not cause effects in <a>IO</a>.
runGopherPure :: GopherConfig -> (String -> GopherResponse) -> IO ()

-- | necessary information to handle gopher requests
data GopherConfig
GopherConfig :: ByteString -> Integer -> Maybe String -> GopherConfig

-- | “name” of the server (either ip address or dns name)
[cServerName] :: GopherConfig -> ByteString

-- | port to listen on
[cServerPort] :: GopherConfig -> Integer

-- | user to run the process as
[cRunUserName] :: GopherConfig -> Maybe String

-- | Convert a gophermap to a gopher menu response.
gophermapToDirectoryResponse :: Gophermap -> GopherResponse
data GopherResponse

-- | gopher menu, wrapper around a list of <a>GopherMenuItem</a>s
MenuResponse :: [GopherMenuItem] -> GopherResponse

-- | return the given <a>ByteString</a> as a file
FileResponse :: ByteString -> GopherResponse

-- | gopher menu containing a single error with the given <a>String</a> as
--   text
ErrorResponse :: String -> GopherResponse

-- | entry in a gopher menu
data GopherMenuItem

-- | file type, menu text, filepath (does not need to be a real file),
--   server name (optional), port (optional)
Item :: GopherFileType -> ByteString -> FilePath -> Maybe ByteString -> Maybe Integer -> GopherMenuItem

-- | rfc-defined gopher file types plus info line and HTML
data GopherFileType

-- | text file, default type
File :: GopherFileType

-- | a gopher menu
Directory :: GopherFileType
PhoneBookServer :: GopherFileType

-- | error entry in menu
Error :: GopherFileType
BinHexMacintoshFile :: GopherFileType
DOSArchive :: GopherFileType
UnixUuencodedFile :: GopherFileType
IndexSearchServer :: GopherFileType
TelnetSession :: GopherFileType

-- | binary file
BinaryFile :: GopherFileType
RedundantServer :: GopherFileType
Tn3270Session :: GopherFileType

-- | gif
GifFile :: GopherFileType

-- | image of any format
ImageFile :: GopherFileType

-- | menu entry without associated file
InfoLine :: GopherFileType

-- | Special type for HTML, most commonly used for <a>links to other
--   protocols</a>
Html :: GopherFileType

-- | A gophermap entry makes all values of a gopher menu item optional
--   except for file type and description. When converting to a
--   <a>GopherMenuItem</a>, appropriate default values are used.
data GophermapEntry

-- | file type, description, path, server name, port number
GophermapEntry :: GopherFileType -> ByteString -> Maybe FilePath -> Maybe ByteString -> Maybe Integer -> GophermapEntry
type Gophermap = [GophermapEntry]
instance Control.Monad.Error.Class.MonadError GHC.IO.Exception.IOException Network.Gopher.GopherM
instance Control.Monad.Reader.Class.MonadReader Network.Gopher.Env Network.Gopher.GopherM
instance Control.Monad.IO.Class.MonadIO Network.Gopher.GopherM
instance GHC.Base.Monad Network.Gopher.GopherM
instance GHC.Base.Applicative Network.Gopher.GopherM
instance GHC.Base.Functor Network.Gopher.GopherM
instance System.Log.FastLogger.LogStr.ToLogStr Network.Gopher.LogMessage