Stability | experimental |
---|---|
Portability | POSIX |
Safe Haskell | None |
Language | Haskell2010 |
Overview
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:
import Network.Gopher import Network.Gopher.Util main = dorunGopherPure
(GopherConfig
"localhost" 7000 Nothing) (\req ->FileResponse
(uEncode
req))
This server just returns the request string as a file.
There are three possibilities for a GopherResponse
:
FileResponse
: file type agnostic file response, takes aByteString
to support both text and binary filesMenuResponse
: a gopher menu (“directory listning”) consisting of a list ofGopherMenuItem
sErrorResponse
: gopher way to show an error (e. g. if a file is not found). AErrorResponse
results in a menu response with a single entry.
If you use runGopher
, it is the same story like in the example above, but you can do IO
effects. To see a more elaborate example, have a look at the server code in this package.
Note: In practice it is probably best to use record update syntax on defaultConfig
which won't break your application every time the config record fields are changed.
Synopsis
- runGopher :: GopherConfig -> (String -> IO GopherResponse) -> IO ()
- runGopherPure :: GopherConfig -> (String -> GopherResponse) -> IO ()
- runGopherManual :: IO (Socket Inet6 Stream TCP) -> IO () -> (Socket Inet6 Stream TCP -> IO ()) -> GopherConfig -> (String -> IO GopherResponse) -> IO ()
- data GopherConfig = GopherConfig {}
- defaultConfig :: GopherConfig
- gophermapToDirectoryResponse :: Gophermap -> GopherResponse
- setupGopherSocket :: GopherConfig -> IO (Socket Inet6 Stream TCP)
- data GopherResponse
- data GopherMenuItem = Item GopherFileType ByteString FilePath (Maybe ByteString) (Maybe Integer)
- data GopherFileType
- data GophermapEntry = GophermapEntry GopherFileType ByteString (Maybe FilePath) (Maybe ByteString) (Maybe Integer)
- type Gophermap = [GophermapEntry]
Main API
runGopher :: GopherConfig -> (String -> IO GopherResponse) -> IO () Source #
Run a gopher application that may cause effects in IO
.
The application function is given the gopher request (path)
and required to produce a GopherResponse.
runGopherPure :: GopherConfig -> (String -> GopherResponse) -> IO () Source #
Run a gopher application that may not cause effects in IO
.
runGopherManual :: IO (Socket Inet6 Stream TCP) -> IO () -> (Socket Inet6 Stream TCP -> IO ()) -> GopherConfig -> (String -> IO GopherResponse) -> IO () Source #
Same as runGopher
, but allows you to setup the Socket
manually
and calls an action of type IO ()
as soon as the server is ready
to accept requests. When the server terminates, it calls the action
of type Socket Inet6 Stream TCP -> IO ()
to clean up the socket.
Spacecookie assumes the Socket
is properly set up to listen on the
port and host specified in the GopherConfig
(i. e. bind
and
listen
have been called). This can be achieved using setupGopherSocket
.
This is intended for supporting systemd socket activation and storage. Only use, if you know what you are doing.
data GopherConfig Source #
necessary information to handle gopher requests
GopherConfig | |
|
defaultConfig :: GopherConfig Source #
Default GopherConfig
describing a server on localhost:70
.
Helper Functions
gophermapToDirectoryResponse :: Gophermap -> GopherResponse Source #
Convert a gophermap to a gopher menu response.
setupGopherSocket :: GopherConfig -> IO (Socket Inet6 Stream TCP) Source #
Auxiliary function that sets up the listening socket for
runGopherManual
correctly and starts to listen.
Representations
Responses
data GopherResponse Source #
MenuResponse [GopherMenuItem] | gopher menu, wrapper around a list of |
FileResponse ByteString | return the given |
ErrorResponse String | gopher menu containing a single error with the given |
Instances
Eq GopherResponse Source # | |
Defined in Network.Gopher.Types (==) :: GopherResponse -> GopherResponse -> Bool # (/=) :: GopherResponse -> GopherResponse -> Bool # | |
Show GopherResponse Source # | |
Defined in Network.Gopher.Types showsPrec :: Int -> GopherResponse -> ShowS # show :: GopherResponse -> String # showList :: [GopherResponse] -> ShowS # |
data GopherMenuItem Source #
entry in a gopher menu
Item GopherFileType ByteString FilePath (Maybe ByteString) (Maybe Integer) | file type, menu text, filepath (does not need to be a real file), server name (optional), port (optional) |
Instances
Eq GopherMenuItem Source # | |
Defined in Network.Gopher.Types (==) :: GopherMenuItem -> GopherMenuItem -> Bool # (/=) :: GopherMenuItem -> GopherMenuItem -> Bool # | |
Show GopherMenuItem Source # | |
Defined in Network.Gopher.Types showsPrec :: Int -> GopherMenuItem -> ShowS # show :: GopherMenuItem -> String # showList :: [GopherMenuItem] -> ShowS # |
data GopherFileType Source #
rfc-defined gopher file types plus info line and HTML
File | text file, default type |
Directory | a gopher menu |
PhoneBookServer | |
Error | error entry in menu |
BinHexMacintoshFile | |
DOSArchive | |
UnixUuencodedFile | |
IndexSearchServer | |
TelnetSession | |
BinaryFile | binary file |
RedundantServer | |
Tn3270Session | |
GifFile | gif |
ImageFile | image of any format |
InfoLine | menu entry without associated file |
Html | Special type for HTML, most commonly used for links to other protocols |
Instances
Gophermaps
data GophermapEntry Source #
A gophermap entry makes all values of a gopher menu item optional except for file type and description. When converting to a GopherMenuItem
, appropriate default values are used.
GophermapEntry GopherFileType ByteString (Maybe FilePath) (Maybe ByteString) (Maybe Integer) | file type, description, path, server name, port number |
Instances
Eq GophermapEntry Source # | |
Defined in Network.Gopher.Util.Gophermap (==) :: GophermapEntry -> GophermapEntry -> Bool # (/=) :: GophermapEntry -> GophermapEntry -> Bool # | |
Show GophermapEntry Source # | |
Defined in Network.Gopher.Util.Gophermap showsPrec :: Int -> GophermapEntry -> ShowS # show :: GophermapEntry -> String # showList :: [GophermapEntry] -> ShowS # |
type Gophermap = [GophermapEntry] Source #