7af73d6 · servant · git.iko.soy

git.iko.soy/servant

on master help sign in

Explicit ignore

7af73d6Julian K. Arni11 years ago

doc/tutorial/api-type.lhs+7−7

compare with master

unifiedsplit

@@ -88,7 +88,7 @@ them amounts to `/`-separating them in a URL.

88These 5 combinators are very similar except that they each describe a

89different HTTP method. This is how they're declared

91−``` haskell

91+``` haskell ignore

92data Delete (contentTypes :: [*]) a

93data Get (contentTypes :: [*]) a

94data Patch (contentTypes :: [*]) a

@@ -116,7 +116,7 @@ The `Capture` combinator in servant takes a (type-level) string representing

116the "name of the variable" and a type, which indicates the type we want to

117decode the "captured value" to.

118

119−``` haskell

119+``` haskell ignore

120data Capture (s :: Symbol) a

121-- s :: Symbol just says that 's' must be a type-level string.

122```

@@ -153,7 +153,7 @@ active users whereas `/users` would list them all.

153

154Here are the corresponding data type declarations:

155

156−``` haskell

156+``` haskell ignore

157data QueryParam (sym :: Symbol) a

158data QueryParams (sym :: Symbol) a

159data QueryFlag (sym :: Symbol)

@@ -171,7 +171,7 @@ after *January 1st, 2005*.

171

172Corresponding data type declarations below.

173

174−``` haskell

174+``` haskell ignore

175data MatrixParam (sym :: Symbol) a

176data MatrixParams (sym :: Symbol) a

177data MatrixFlag (sym :: Symbol)

@@ -206,7 +206,7 @@ Request` or `Unsupported Content Type` as appropriate.

206

207Here's the data type declaration for it:

208

209−``` haskell

209+``` haskell ignore

210data ReqBody (contentTypes :: [*]) a

211```

212

@@ -235,7 +235,7 @@ The `Header` combinator in servant takes a type-level string for the header

235name and the type to which we want to decode the header's value (from some

236textual representation), as illustrated below:

237

238−``` haskell

238+``` haskell ignore

239data Header (sym :: Symbol) a

240```

241

@@ -274,7 +274,7 @@ headers too. *servant* provides a `Headers` combinator that carries a list of

274`Header` and can be used by simply wrapping the "return type" of an endpoint

275with it.

276

277−``` haskell

277+``` haskell ignore

278data Headers (ls :: [*]) a

279```

280

doc/tutorial/client.lhs+1−1

@@ -83,7 +83,7 @@ Each function makes available as an argument any value that the response may dep

84As you can see in the code above, we just "pattern match our way" to these functions. If we try to derive less or more functions than there are endpoints in the API, we obviously get an error. The `BaseUrl` value there is just:

86−``` haskell

86+``` haskell ignore

87-- | URI scheme to use

88data Scheme =

89 Http -- ^ http://

doc/tutorial/convert.hs+1−1

@@ -26,5 +26,5 @@ convert =

26 go :: [String] -> [String]

27 go (a : r)

28 | ">" `isPrefixOf` a

29− = "``` haskell" : map (drop 2) (a : r) ++ "```" : []

29+ = "``` haskell ignore" : map (drop 2) (a : r) ++ "```" : []

30 go x = x

doc/tutorial/docs.lhs+1−1

@@ -94,7 +94,7 @@ With all of this, we can derive docs for our API.

95*servant*'s markdown pretty printer is a function named `markdown`.

97−``` haskell

97+``` haskell ignore

98markdown :: API -> String

99```

100

doc/tutorial/server.lhs+20−20

@@ -68,7 +68,7 @@ need to have some language extensions and imports:

68> import qualified Data.Aeson.Parser

69> import qualified Text.Blaze.Html

71−``` haskell

71+``` haskell ignore

72{-# LANGUAGE TypeFamilies #-}

73```

@@ -107,7 +107,7 @@ Nothing funny going on here. But we now can define our list of two users.

107

108Let's also write our API type.

109

110−``` haskell

110+``` haskell ignore

111type UserAPI1 = "users" :> Get '[JSON] [User]

112```

113

@@ -324,7 +324,7 @@ decided to provide a pair of typeclasses, `FromText` and `ToText` which just

324let you say that you can respectively *extract* or *encode* values of some type

325*from*/*to* text. Here are the definitions:

326

327−``` haskell

327+``` haskell ignore

328class FromText a where

329 fromText :: Text -> Maybe a

330

@@ -363,7 +363,7 @@ your own.

363

364or writing the instances by hand:

365

366−``` haskell

366+``` haskell ignore

367instance FromText UserId where

368 fromText = fmap UserId fromText

369

@@ -394,7 +394,7 @@ The truth behind `JSON`

394What exactly is `JSON`? Like the 3 other content types provided out of the box

395by *servant*, it's a really dumb data type.

396

397−``` haskell

397+``` haskell ignore

398data JSON

399data PlainText

400data FormUrlEncoded

@@ -415,7 +415,7 @@ haddocks from this link, you can see that we just have to specify

415use `(//) :: ByteString -> ByteString -> MediaType`. The precise way to specify

416the `MediaType` is to write an instance for the `Accept` class:

417

418−``` haskell

418+``` haskell ignore

419-- for reference:

420class Accept ctype where

421 contentType :: Proxy ctype -> MediaType

@@ -428,7 +428,7 @@ The second step is centered around the `MimeRender` and `MimeUnrender` classes.

428These classes just let you specify a way to respectively encode and decode

429values respectively into or from your content-type's representation.

430

431−``` haskell

431+``` haskell ignore

432class Accept ctype => MimeRender ctype a where

433 mimeRender :: Proxy ctype -> a -> ByteString

434 -- alternatively readable as:

@@ -442,7 +442,7 @@ In the case of `JSON`, this is easily dealt with! For any type `a` with a

442`ToJSON` instance, we can render values of that type to JSON using

443`Data.Aeson.encode`.

444

445−``` haskell

445+``` haskell ignore

446instance ToJSON a => MimeRender JSON a where

447 mimeRender _ = encode

448```

@@ -450,7 +450,7 @@ instance ToJSON a => MimeRender JSON a where

450And now the `MimeUnrender` class, which lets us extract values from lazy

451`ByteString`s, alternatively failing with an error string.

452

453−``` haskell

453+``` haskell ignore

454class Accept ctype => MimeUnrender ctype a where

455 mimeUnrender :: Proxy ctype -> ByteString -> Either String a

456 -- alternatively:

@@ -471,7 +471,7 @@ you are curious.

471

472This function is exactly what we need for our `MimeUnrender` instance.

473

474−``` haskell

474+``` haskell ignore

475instance FromJSON a => MimeUnrender JSON a where

476 mimeUnrender _ = eitherDecodeLenient

477```

@@ -627,7 +627,7 @@ as interfaces to databases that we interact with in `IO`;

627

628Let's recall some definitions.

629

630−``` haskell

630+``` haskell ignore

631-- from the Prelude

632data Either e a = Left e | Right a

633

@@ -644,7 +644,7 @@ action that either returns an error or a result.

644The aforementioned `either` package is worth taking a look at. Perhaps most

645importantly:

646

647−``` haskell

647+``` haskell ignore

648left :: Monad m => e -> EitherT e m a

649```

650Allows you to return an error from your handler (whereas `return` is enough to

@@ -659,7 +659,7 @@ Performing IO

659

660Another important instance from the list above is `MonadIO m => MonadIO (EitherT e m)`. [`MonadIO`](http://hackage.haskell.org/package/transformers-0.4.3.0/docs/Control-Monad-IO-Class.html) is a class from the *transformers* package defined as:

661

662−``` haskell

662+``` haskell ignore

663class Monad m => MonadIO m where

664 liftIO :: IO a -> m a

665```

@@ -688,7 +688,7 @@ error message, all you have to do is use the `left` function mentioned above

688and provide it with the appropriate value of type `ServantErr`, which is

689defined as:

690

691−``` haskell

691+``` haskell ignore

692data ServantErr = ServantErr

693 { errHTTPCode :: Int

694 , errReasonPhrase :: String

@@ -773,7 +773,7 @@ under some path in your web API. As mentioned earlier in this document, the

773application". Well, servant-server provides a function to get a file and

774directory serving WAI application, namely:

775

776−``` haskell

776+``` haskell ignore

777-- exported by Servant and Servant.Server

778serveDirectory :: FilePath -> Server Raw

779```

@@ -809,7 +809,7 @@ In other words:

809

810Here is our little server in action.

811

812−``` haskell

812+``` haskell ignore

813$ curl http://localhost:8081/code/T1.hs

814{-# LANGUAGE DataKinds #-}

815{-# LANGUAGE TypeFamilies #-}

@@ -918,7 +918,7 @@ We can instead factor out the `userid`:

918

919However, you have to be aware that this has an effect on the type of the corresponding `Server`:

920

921−``` haskell

921+``` haskell ignore

922Server UserAPI3 = (Int -> EitherT ServantErr IO User)

923 :<|> (Int -> EitherT ServantErr IO ())

924

@@ -1076,7 +1076,7 @@ Using another monad for your handlers

1076

1077Remember how `Server` turns combinators for HTTP methods into `EitherT ServantErr IO`? Well, actually, there's more to that. `Server` is actually a simple type synonym.

1078

1079−``` haskell

1079+``` haskell ignore

1080type Server api = ServerT api (EitherT ServantErr IO)

1081```

1082

@@ -1090,7 +1090,7 @@ Natural transformations

1090If we have a function that gets us from an `m a` to an `n a`, for any `a`, what

1091do we have?

1092

1093−``` haskell

1093+``` haskell ignore

1094newtype m :~> n = Nat { unNat :: forall a. m a -> n a}

1095

1096-- For example

@@ -1103,7 +1103,7 @@ So if you want to write handlers using another monad/type than `EitherT

1103ServantErr IO`, say the `Reader String` monad, the first thing you have to

1104prepare is a function:

1105

1106−``` haskell

1106+``` haskell ignore

1107readerToEither :: Reader String :~> EitherT ServantErr IO

1108```

1109