7af73d6 · typeable/servant

git.iko.soy/typeable/servant

Explicit ignore

commit7af73d63ea6b9f47415c919fa3ad2dbf2b396417 authorJulian K. Arni <jkarni@gmail.com> dateWed 27 Jan 2016, 22:26 (11 years ago) parent5542ce8

5 files changed+30−30

compare with master

unifiedsplit

doc/tutorial/api-type.lhs+7−7 doc/tutorial/client.lhs+1−1 doc/tutorial/convert.hs+1−1 doc/tutorial/docs.lhs+1−1 doc/tutorial/server.lhs+20−20

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

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

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

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

9090

91−``` haskell

91+``` haskell ignore

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

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

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

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

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

117117decode the "captured value" to.

118118

119−``` haskell

119+``` haskell ignore

120120data Capture (s :: Symbol) a

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

122122```

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

153153

154154Here are the corresponding data type declarations:

155155

156−``` haskell

156+``` haskell ignore

157157data QueryParam (sym :: Symbol) a

158158data QueryParams (sym :: Symbol) a

159159data QueryFlag (sym :: Symbol)

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

171171

172172Corresponding data type declarations below.

173173

174−``` haskell

174+``` haskell ignore

175175data MatrixParam (sym :: Symbol) a

176176data MatrixParams (sym :: Symbol) a

177177data MatrixFlag (sym :: Symbol)

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

206206

207207Here's the data type declaration for it:

208208

209−``` haskell

209+``` haskell ignore

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

211211```

212212

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

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

236236textual representation), as illustrated below:

237237

238−``` haskell

238+``` haskell ignore

239239data Header (sym :: Symbol) a

240240```

241241

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

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

275275with it.

276276

277−``` haskell

277+``` haskell ignore

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

279279```

280280

doc/tutorial/client.lhs+1−1

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

8383

8484As 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:

8585

86−``` haskell

86+``` haskell ignore

8787-- | URI scheme to use

8888data Scheme =

8989 Http -- ^ http://

doc/tutorial/convert.hs+1−1

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

2626 go :: [String] -> [String]

2727 go (a : r)

2828 | ">" `isPrefixOf` a

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

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

3030 go x = x

doc/tutorial/docs.lhs+1−1

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

9494

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

9696

97−``` haskell

97+``` haskell ignore

9898markdown :: API -> String

9999```

100100

doc/tutorial/server.lhs+20−20

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

6868> import qualified Data.Aeson.Parser

6969> import qualified Text.Blaze.Html

7070

71−``` haskell

71+``` haskell ignore

7272{-# LANGUAGE TypeFamilies #-}

7373```

7474

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

107107

108108Let's also write our API type.

109109

110−``` haskell

110+``` haskell ignore

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

112112```

113113

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

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

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

326326

327−``` haskell

327+``` haskell ignore

328328class FromText a where

329329 fromText :: Text -> Maybe a

330330

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

363363

364364or writing the instances by hand:

365365

366−``` haskell

366+``` haskell ignore

367367instance FromText UserId where

368368 fromText = fmap UserId fromText

369369

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

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

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

396396

397−``` haskell

397+``` haskell ignore

398398data JSON

399399data PlainText

400400data FormUrlEncoded

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

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

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

417417

418−``` haskell

418+``` haskell ignore

419419-- for reference:

420420class Accept ctype where

421421 contentType :: Proxy ctype -> MediaType

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

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

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

430430

431−``` haskell

431+``` haskell ignore

432432class Accept ctype => MimeRender ctype a where

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

434434 -- alternatively readable as:

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

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

443443`Data.Aeson.encode`.

444444

445−``` haskell

445+``` haskell ignore

446446instance ToJSON a => MimeRender JSON a where

447447 mimeRender _ = encode

448448```

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

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

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

452452

453−``` haskell

453+``` haskell ignore

454454class Accept ctype => MimeUnrender ctype a where

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

456456 -- alternatively:

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

471471

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

473473

474−``` haskell

474+``` haskell ignore

475475instance FromJSON a => MimeUnrender JSON a where

476476 mimeUnrender _ = eitherDecodeLenient

477477```

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

627627

628628Let's recall some definitions.

629629

630−``` haskell

630+``` haskell ignore

631631-- from the Prelude

632632data Either e a = Left e | Right a

633633

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

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

645645importantly:

646646

647−``` haskell

647+``` haskell ignore

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

649649```

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

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

659659

660660Another 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:

661661

662−``` haskell

662+``` haskell ignore

663663class Monad m => MonadIO m where

664664 liftIO :: IO a -> m a

665665```

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

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

689689defined as:

690690

691−``` haskell

691+``` haskell ignore

692692data ServantErr = ServantErr

693693 { errHTTPCode :: Int

694694 , errReasonPhrase :: String

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

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

774774directory serving WAI application, namely:

775775

776−``` haskell

776+``` haskell ignore

777777-- exported by Servant and Servant.Server

778778serveDirectory :: FilePath -> Server Raw

779779```

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

809809

810810Here is our little server in action.

811811

812−``` haskell

812+``` haskell ignore

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

814814{-# LANGUAGE DataKinds #-}

815815{-# LANGUAGE TypeFamilies #-}

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

918918

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

920920

921−``` haskell

921+``` haskell ignore

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

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

924924

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

10761076

10771077Remember 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.

10781078

1079−``` haskell

1079+``` haskell ignore

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

10811081```

10821082

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

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

10911091do we have?

10921092

1093−``` haskell

1093+``` haskell ignore

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

10951095

10961096-- For example

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

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

11041104prepare is a function:

11051105

1106−``` haskell

1106+``` haskell ignore

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

11081108```

11091109