@@ -3,61 +3,61 @@
3{-# LANGUAGE PatternGuards, ScopedTypeVariables #-}
3{-# LANGUAGE PatternGuards, ScopedTypeVariables #-}
4{-# LANGUAGE RecordWildCards #-}
4{-# LANGUAGE RecordWildCards #-}
6−------------------------------------------------------------------------------
6+{- |
8−-- Module: Database.PostgreSQL.Simple.FromField
7+Module: Database.PostgreSQL.Simple.FromField
9−-- Copyright: (c) 2011 MailRank, Inc.
8+Copyright: (c) 2011 MailRank, Inc.
10−-- (c) 2011-2012 Leon P Smith
9+ (c) 2011-2012 Leon P Smith
11−-- License: BSD3
10+License: BSD3
12−-- Maintainer: Leon P Smith <leon@melding-monads.com>
11+Maintainer: Leon P Smith <leon@melding-monads.com>
13−-- Stability: experimental
12+Stability: experimental
14−-- Portability: portable
13+Portability: portable
16−-- The 'FromField' typeclass, for converting a single value in a row
15+The 'FromField' typeclass, for converting a single value in a row
17−-- returned by a SQL query into a more useful Haskell representation.
16+returned by a SQL query into a more useful Haskell representation.
19−-- A Haskell numeric type is considered to be compatible with all
18+A Haskell numeric type is considered to be compatible with all
20−-- PostgreSQL numeric types that are less accurate than it. For instance,
19+PostgreSQL numeric types that are less accurate than it. For instance,
21−-- the Haskell 'Double' type is compatible with the PostgreSQL's 32-bit
20+the Haskell 'Double' type is compatible with the PostgreSQL's 32-bit
22−-- @int@ type because it can represent a @int@ exactly. On the other hand,
21+@int@ type because it can represent a @int@ exactly. On the other hand,
23−-- since a 'Double' might lose precision if representing PostgreSQL's 64-bit
22+since a 'Double' might lose precision if representing PostgreSQL's 64-bit
24−-- @bigint@, the two are /not/ considered compatible.
23+@bigint@, the two are /not/ considered compatible.
26−-- Because 'FromField' is a typeclass, one may provide conversions to
25+Because 'FromField' is a typeclass, one may provide conversions to
27−-- additional Haskell types without modifying postgresql-simple. This is
26+additional Haskell types without modifying postgresql-simple. This is
28−-- particularly useful for supporting PostgreSQL types that postgresql-simple
27+particularly useful for supporting PostgreSQL types that postgresql-simple
29−-- does not support out-of-box. Here's an example of what such an instance
28+does not support out-of-box. Here's an example of what such an instance
30−-- might look like for a UUID type that implements the @Read@ class:
29+might look like for a UUID type that implements the @Read@ class:
33−-- import Data.UUID ( UUID )
32+import Data.UUID ( UUID )
34−-- import Database.PostgreSQL.Simple.BuiltinTypes
33+import Database.PostgreSQL.Simple.BuiltinTypes
35−-- ( BuiltinType(UUID), builtin2oid )
34+ ( BuiltinType(UUID), builtin2oid )
36−-- import qualified Data.ByteString as B
35+import qualified Data.ByteString as B
38−-- instance FromField UUID where
37+instance FromField UUID where
39−-- fromField f mdata =
38+ fromField f mdata =
40−-- if typeOid f /= builtin2oid UUID
39+ if typeOid f /= builtin2oid UUID
41−-- then returnError Incompatible f ""
40+ then returnError Incompatible f \"\"
42−-- else case B.unpack `fmap` mdata of
41+ else case B.unpack \`fmap\` mdata of
43−-- Nothing -> returnError UnexpectedNull f ""
42+ Nothing -> returnError UnexpectedNull f \"\"
44−-- Just data ->
43+ Just data ->
45−-- case [ x | (x,t) <- reads data, ("","") <- lex t ] of
44+ case [ x | (x,t) <- reads data, (\"\",\"\") <- lex t ] of
46−-- [x] -> Ok x
45+ [x] -> Ok x
47−-- _ -> returnError ConversionError f data
46+ _ -> returnError ConversionError f data
50−-- Note that because PostgreSQL's @uuid@ type is built into postgres and is
49+Note that because PostgreSQL's @uuid@ type is built into postgres and is
51−-- not provided by an extension, the 'typeOid' of @uuid@ does not change and
50+not provided by an extension, the 'typeOid' of @uuid@ does not change and
52−-- thus we can examine it directly. Here, we simply pull the type oid out
51+thus we can examine it directly. Here, we simply pull the type oid out
53−-- of the static table provided by postgresql-simple.
52+of the static table provided by postgresql-simple.
55−-- On the other hand if the type is provided by an extension, such as
54+On the other hand if the type is provided by an extension, such as
56−-- @PostGIS@ or @hstore@, then the 'typeOid' is not stable and can vary from
55+@PostGIS@ or @hstore@, then the 'typeOid' is not stable and can vary from
57−-- database to database. In this case it is recommended that FromField
56+database to database. In this case it is recommended that FromField
58−-- instances use 'typename' instead.
57+instances use 'typename' instead.
60−------------------------------------------------------------------------------
59+-}
62module Database.PostgreSQL.Simple.FromField
62module Database.PostgreSQL.Simple.FromField