polish up cabal file, add a README

This commit is contained in:
Alp Mestanogullari 2014-12-08 10:56:02 +01:00
parent 9c343face8
commit 55eb020d10
3 changed files with 114 additions and 4 deletions

25
README.md Normal file
View File

@ -0,0 +1,25 @@
# servant
[![Build Status](https://secure.travis-ci.org/haskell-servant/servant.svg)](http://travis-ci.org/haskell-servant/servant)
![servant](https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png)
These libraries provides a family of combinators to define webservices and automatically generate the documentation and client-side querying functions for each endpoint.
In order to minimize the dependencies depending on your needs, we provide these features under different packages.
- `servant`, which contains everything you need to *declare* a webservice and *implement* an HTTP server with handlers for each endpoint.
- `servant-client`, which lets you derive automatically Haskell functions that let you query each endpoint of a *servant* webservice.
- `servant-docs`, which lets you generate API docs for your webservice.
- `servant-jquery`, which lets you derive Javascript functions (based on jquery) to query your API's endpoints, in the same spirit as `servant-client`.
## Getting started
We've written a [Getting Started](http://haskell-servant.github.io/getting-started/) guide that introduces the core types and features of servant. After this article, you should be able to write your first servant webservices, learning the rest from the haddocks' examples.
## Repositories and Haddocks
- The core [servant](http://github.com/haskell-servant) package - [docs](http://haskell-servant.github.io/servant/)
- (Haskell) client-side function generation with [servant-client](http://github.com/haskell-servant/servant-client) - [docs](http://haskell-servant.github.io/servant-client/)
- (Javascript) client-side function generation with [servant-jquery](http://github.com/haskell-servant/servant-jquery) - [docs](http://haskell-servant.github.io/servant-jquery/)
- API docs generation with [servant-docs](http://github.com/haskell-servant/servant-docs) - [docs](http://haskell-servant.github.io/servant-docs/)

View File

@ -1,7 +1,89 @@
name: servant
version: 0.2
-- synopsis:
-- description:
synopsis: A family of combinators for defining webservices APIs and serving them
description:
A family of combinators for defining webservices APIs and serving them
.
You can learn about the basic in <http://haskell-servant.github.io/getting-started/ the getting started> guide.
.
Here's a runnable example, with comments that defines a dummy API and
implements a webserver that serves this API. You can find it <https://github.com/haskell-servant/servant/blob/master/example/greet.hs here> too.
.
> {-# LANGUAGE DataKinds #-}
> {-# LANGUAGE PolyKinds #-}
> {-# LANGUAGE TypeFamilies #-}
> {-# LANGUAGE DeriveGeneric #-}
> {-# LANGUAGE TypeOperators #-}
> {-# LANGUAGE OverloadedStrings #-}
>
> import Data.Aeson
> import Data.Monoid
> import Data.Proxy
> import Data.Text
> import GHC.Generics
> import Network.Wai
> import Network.Wai.Handler.Warp
>
> import Servant
>
> -- * Example
>
> -- | A greet message data type
> newtype Greet = Greet { msg :: Text }
> deriving (Generic, Show)
>
> instance FromJSON Greet
> instance ToJSON Greet
>
> -- API specification
> type TestApi =
> -- GET /hello/:name?capital={true, false}
-- returns a Greet as JSON
> "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet
>
> -- POST /greet with a Greet as JSON in the request body,
> -- returns a Greet as JSON
> :<|> "greet" :> ReqBody Greet :> Post Greet
>
> -- DELETE /greet/:greetid
> :<|> "greet" :> Capture "greetid" Text :> Delete
>
> testApi :: Proxy TestApi
> testApi = Proxy
>
> -- Server-side handlers.
> --
> -- There's one handler per endpoint, which, just like in the type
> -- that represents the API, are glued together using :<|>.
> --
> -- Each handler runs in the 'EitherT (Int, String) IO' monad.
> server :: Server TestApi
> server = helloH :<|> postGreetH :<|> deleteGreetH
>
> where helloH name Nothing = helloH name (Just False)
> helloH name (Just False) = return . Greet $ "Hello, " <> name
> helloH name (Just True) = return . Greet . toUpper $ "Hello, " <> name
>
> postGreetH greet = return greet
>
> deleteGreetH _ = return ()
>
> -- Turn the server into a WAI app. 'serve' is provided by servant,
> -- more precisely by the Servant.Server module.
> test :: Application
> test = serve testApi server
>
> -- Run the server.
> --
> -- 'run' comes from Network.Wai.Handler.Warp
> runTestServer :: Port -> IO ()
> runTestServer port = run port test
>
> -- Put this all to work!
> main :: IO ()
> main = runTestServer 8001
homepage: http://haskell-servant.github.io/
Bug-reports: http://github.com/haskell-servant/servant/issues
license: BSD3
license-file: LICENSE
author: Alp Mestanogullari, Sönke Hahn, Julian K. Arni
@ -11,6 +93,9 @@ category: Web
build-type: Simple
cabal-version: >=1.10
tested-with: GHC >= 7.8
source-repository head
type: git
location: http://github.com/haskell-servant/servant.git
library
exposed-modules:
@ -52,12 +137,12 @@ library
, warp
hs-source-dirs: src
default-language: Haskell2010
ghc-options: -O0 -Wall
ghc-options: -Wall
executable greet
main-is: greet.hs
hs-source-dirs: example
ghc-options: -O0 -Wall
ghc-options: -Wall
default-language: Haskell2010
build-depends:
base

BIN
servant.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB