git.iko.soy/typeable/http-api-data
on master help sign in
Add haddock documentation and examples for HttpApiData
264331dNickolay Kudasov
Web/HttpApiData.hs+45
compare with master
unifiedsplit
@@ -2,9 +2,17 @@
2{-# LANGUAGE FlexibleInstances #-}
2{-# LANGUAGE FlexibleInstances #-}
3{-# LANGUAGE OverloadedStrings #-}
3{-# LANGUAGE OverloadedStrings #-}
4{-# LANGUAGE TypeSynonymInstances #-}
4{-# LANGUAGE TypeSynonymInstances #-}
5+-- |
6+-- Convert Haskell values to and from HTTP API data
7+-- such as URL pieces, headers and query parameters.
5module Web.HttpApiData (
8module Web.HttpApiData (
9+ -- * Examples
10+ -- $examples
11+
12+ -- * Classes
6 ToHttpApiData (..),
13 ToHttpApiData (..),
7 FromHttpApiData (..),
14 FromHttpApiData (..),
15+ -- * Utility functions
8 parseMaybeHttpApiData,
16 parseMaybeHttpApiData,
9 showUrlPiece,
17 showUrlPiece,
10 readMaybeUrlPiece,
18 readMaybeUrlPiece,
@@ -29,6 +37,11 @@ import Data.Time (Day)
29
37
30import Text.Read (readMaybe)
38import Text.Read (readMaybe)
31
39
40+-- $setup
41+--
42+-- >>> :set -XOverloadedStrings
43+-- >>> import Data.Time
44+
32-- | Convert value to HTTP API data.
45-- | Convert value to HTTP API data.
33class ToHttpApiData a where
46class ToHttpApiData a where
34 -- | Convert to URL path piece.
47 -- | Convert to URL path piece.
@@ -117,3 +130,35 @@ instance FromHttpApiData String where parseUrlPiece = Right . Text.unpack
117instance FromHttpApiData Text where parseUrlPiece = Right
130instance FromHttpApiData Text where parseUrlPiece = Right
118instance FromHttpApiData TL.Text where parseUrlPiece = Right . TL.fromStrict
131instance FromHttpApiData TL.Text where parseUrlPiece = Right . TL.fromStrict
119instance FromHttpApiData Day where parseUrlPiece = readEitherUrlPiece
132instance FromHttpApiData Day where parseUrlPiece = readEitherUrlPiece
133+
134+-- $examples
135+--
136+-- Booleans:
137+--
138+-- >>> toUrlPiece True
139+-- "True"
140+-- >>> parseUrlPiece "False" :: Either Text Bool
141+-- Right False
142+-- >>> parseUrlPiece "something else" :: Either Text Bool
143+-- Left "could not convert: `something else'"
144+--
145+-- Numbers:
146+--
147+-- >>> toUrlPiece 45.2
148+-- "45.2"
149+-- >>> parseUrlPiece "452" :: Either Text Int
150+-- Right 452
151+--
152+-- Strings:
153+--
154+-- >>> toHeader "hello"
155+-- "hello"
156+-- >>> parseHeader "world" :: Either Text String
157+-- Right "world"
158+--
159+-- Calendar day:
160+--
161+-- >>> toQueryParam (fromGregorian 2015 10 03)
162+-- "2015-10-03"
163+-- >>> toGregorian <$> parseQueryParam "2016-12-01"
164+-- Right (2016,12,1)
Web/PathPieces.hs+9−7
@@ -2,12 +2,14 @@
2{-# LANGUAGE FlexibleInstances #-}
2{-# LANGUAGE FlexibleInstances #-}
3{-# LANGUAGE OverloadedStrings #-}
3{-# LANGUAGE OverloadedStrings #-}
4{-# LANGUAGE TypeSynonymInstances #-}
4{-# LANGUAGE TypeSynonymInstances #-}
5+-- |
6+-- Convert Haskell values to and from route pieces.
5−module Web.PathPieces
7+module Web.PathPieces (
6− ( PathPiece (..)
8+ PathPiece (..),
7− , PathMultiPiece (..)
9+ PathMultiPiece (..),
8− , readFromPathPiece
10+ readFromPathPiece,
9− , showToPathPiece
11+ showToPathPiece,
10− ) where
12+) where
11
13
12import Data.Int
14import Data.Int
13import Data.Word
15import Data.Word
@@ -18,7 +20,7 @@ import Text.Read (readMaybe)
18
20
19import Web.HttpApiData
21import Web.HttpApiData
20
22
21−-- | Convert Haskell values to and from route pieces.
23+-- | Convert Haskell values to and from route piece.
22class PathPiece s where
24class PathPiece s where
23 -- | Convert from route piece.
25 -- | Convert from route piece.
24 fromPathPiece :: S.Text -> Maybe s
26 fromPathPiece :: S.Text -> Maybe s