Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fix haddocks in FromField module

  • Loading branch information...
commit 9a3fc7c0d879c6f1c7df0788ade3e22e6d594614 1 parent 14d7a3b
Leon P Smith authored
Showing with 55 additions and 55 deletions.
  1. +55 −55 src/Database/PostgreSQL/Simple/FromField.hs
110 src/Database/PostgreSQL/Simple/FromField.hs
View
@@ -3,61 +3,61 @@
{-# LANGUAGE PatternGuards, ScopedTypeVariables #-}
{-# LANGUAGE RecordWildCards #-}
-------------------------------------------------------------------------------
--- |
--- Module: Database.PostgreSQL.Simple.FromField
--- Copyright: (c) 2011 MailRank, Inc.
--- (c) 2011-2012 Leon P Smith
--- License: BSD3
--- Maintainer: Leon P Smith <leon@melding-monads.com>
--- Stability: experimental
--- Portability: portable
---
--- The 'FromField' typeclass, for converting a single value in a row
--- returned by a SQL query into a more useful Haskell representation.
---
--- A Haskell numeric type is considered to be compatible with all
--- PostgreSQL numeric types that are less accurate than it. For instance,
--- the Haskell 'Double' type is compatible with the PostgreSQL's 32-bit
--- @int@ type because it can represent a @int@ exactly. On the other hand,
--- since a 'Double' might lose precision if representing PostgreSQL's 64-bit
--- @bigint@, the two are /not/ considered compatible.
---
--- Because 'FromField' is a typeclass, one may provide conversions to
--- additional Haskell types without modifying postgresql-simple. This is
--- particularly useful for supporting PostgreSQL types that postgresql-simple
--- does not support out-of-box. Here's an example of what such an instance
--- might look like for a UUID type that implements the @Read@ class:
---
--- @
--- import Data.UUID ( UUID )
--- import Database.PostgreSQL.Simple.BuiltinTypes
--- ( BuiltinType(UUID), builtin2oid )
--- import qualified Data.ByteString as B
---
--- instance FromField UUID where
--- fromField f mdata =
--- if typeOid f /= builtin2oid UUID
--- then returnError Incompatible f ""
--- else case B.unpack `fmap` mdata of
--- Nothing -> returnError UnexpectedNull f ""
--- Just data ->
--- case [ x | (x,t) <- reads data, ("","") <- lex t ] of
--- [x] -> Ok x
--- _ -> returnError ConversionError f data
--- @
---
--- Note that because PostgreSQL's @uuid@ type is built into postgres and is
--- not provided by an extension, the 'typeOid' of @uuid@ does not change and
--- thus we can examine it directly. Here, we simply pull the type oid out
--- of the static table provided by postgresql-simple.
---
--- On the other hand if the type is provided by an extension, such as
--- @PostGIS@ or @hstore@, then the 'typeOid' is not stable and can vary from
--- database to database. In this case it is recommended that FromField
--- instances use 'typename' instead.
---
-------------------------------------------------------------------------------
+{- |
+Module: Database.PostgreSQL.Simple.FromField
+Copyright: (c) 2011 MailRank, Inc.
+ (c) 2011-2012 Leon P Smith
+License: BSD3
+Maintainer: Leon P Smith <leon@melding-monads.com>
+Stability: experimental
+Portability: portable
+
+The 'FromField' typeclass, for converting a single value in a row
+returned by a SQL query into a more useful Haskell representation.
+
+A Haskell numeric type is considered to be compatible with all
+PostgreSQL numeric types that are less accurate than it. For instance,
+the Haskell 'Double' type is compatible with the PostgreSQL's 32-bit
+@int@ type because it can represent a @int@ exactly. On the other hand,
+since a 'Double' might lose precision if representing PostgreSQL's 64-bit
+@bigint@, the two are /not/ considered compatible.
+
+Because 'FromField' is a typeclass, one may provide conversions to
+additional Haskell types without modifying postgresql-simple. This is
+particularly useful for supporting PostgreSQL types that postgresql-simple
+does not support out-of-box. Here's an example of what such an instance
+might look like for a UUID type that implements the @Read@ class:
+
+@
+import Data.UUID ( UUID )
+import Database.PostgreSQL.Simple.BuiltinTypes
+ ( BuiltinType(UUID), builtin2oid )
+import qualified Data.ByteString as B
+
+instance FromField UUID where
+ fromField f mdata =
+ if typeOid f /= builtin2oid UUID
+ then returnError Incompatible f \"\"
+ else case B.unpack \`fmap\` mdata of
+ Nothing -> returnError UnexpectedNull f \"\"
+ Just data ->
+ case [ x | (x,t) <- reads data, (\"\",\"\") <- lex t ] of
+ [x] -> Ok x
+ _ -> returnError ConversionError f data
+@
+
+Note that because PostgreSQL's @uuid@ type is built into postgres and is
+not provided by an extension, the 'typeOid' of @uuid@ does not change and
+thus we can examine it directly. Here, we simply pull the type oid out
+of the static table provided by postgresql-simple.
+
+On the other hand if the type is provided by an extension, such as
+@PostGIS@ or @hstore@, then the 'typeOid' is not stable and can vary from
+database to database. In this case it is recommended that FromField
+instances use 'typename' instead.
+
+-}
+
module Database.PostgreSQL.Simple.FromField
(
Please sign in to comment.
Something went wrong with that request. Please try again.