Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Doc improvements.

  • Loading branch information...
commit 2acc2ceb51fc897dfabe3d7606a3236197019455 1 parent 0e03c09
@bos authored
Showing with 39 additions and 10 deletions.
  1. +8 −6 Data/Aeson.hs
  2. +28 −4 Data/Aeson/Types/Internal.hs
  3. +3 −0  aeson.cabal
View
14 Data/Aeson.hs
@@ -12,8 +12,11 @@
module Data.Aeson
(
+ -- * Encoding and decoding
+ decode
+ , encode
-- * Core JSON types
- Value(..)
+ , Value(..)
, Array
, Object
-- * Convenience types
@@ -28,20 +31,19 @@ module Data.Aeson
, (.:)
, (.:?)
, object
- -- * Encoding and decoding
- , decode
- , encode
-- * Parsing
, json
) where
-import Data.Aeson.Encode
-import Data.Aeson.Parser
+import Data.Aeson.Encode (encode)
+import Data.Aeson.Parser (json)
import Data.Aeson.Types
import qualified Data.ByteString.Lazy as L
import qualified Data.Attoparsec.Lazy as L
-- | Efficiently deserialize a JSON value from a lazy 'L.ByteString'.
+-- If this fails due to incomplete or invalid input, 'Nothing' is
+-- returned.
decode :: (FromJSON a) => L.ByteString -> Maybe a
decode s = case L.parse json s of
L.Done _ v -> case fromJSON v of
View
32 Data/Aeson/Types/Internal.hs
@@ -304,13 +304,25 @@ object = Object . M.fromList
--
-- An example type and instance:
--
--- @data Coord { x :: Double, y :: Double }
+-- @{-\# LANGUAGE OverloadedStrings #-}
+--
+-- data Coord { x :: Double, y :: Double }
--
-- instance ToJSON Coord where
-- toJSON (Coord x y) = 'object' [\"x\" '.=' x, \"y\" '.=' y]
-- @
--
--- This example assumes the OverloadedStrings language option is enabled.
+-- We use the @OverloadedStrings@ language extension so that we can
+-- write 'Text' values as normal double-quoted strings.
+--
+-- If you do not want to write your own 'ToJSON' instances, you have
+-- two options:
+--
+-- * The 'Data.Aeson.TH' module will automatically derive an instance
+-- for you with a single line of code.
+--
+-- * The 'Data.Aeson.Generic' module will work with most data types
+-- that are instances of 'Data' (but note, this can be slow).
class ToJSON a where
toJSON :: a -> Value
@@ -328,7 +340,9 @@ class ToJSON a where
--
-- An example type and instance:
--
--- @data Coord { x :: Double, y :: Double }
+-- @{-\# LANGUAGE OverloadedStrings #-}
+--
+-- data Coord { x :: Double, y :: Double }
--
-- instance FromJSON Coord where
-- parseJSON ('Object' v) = Coord '<$>'
@@ -339,7 +353,17 @@ class ToJSON a where
-- parseJSON _ = 'mzero'
-- @
--
--- This example assumes the OverloadedStrings language option is enabled.
+-- We use the @OverloadedStrings@ language extension so that we can
+-- write 'Text' values as normal double-quoted strings.
+--
+-- If you do not want to write your own 'FromJSON' instances, you have
+-- two options:
+--
+-- * The 'Data.Aeson.TH' module will automatically derive an instance
+-- for you with a single line of code.
+--
+-- * The 'Data.Aeson.Generic' module will work with most data types
+-- that are instances of 'Data' (but note, this can be slow).
class FromJSON a where
parseJSON :: Value -> Parser a
View
3  aeson.cabal
@@ -17,6 +17,9 @@ description:
A JSON parsing and encoding library optimized for ease of use
and high performance.
.
+ To get started, see the documentation for the @Data.Aeson@ module
+ below.
+ .
/Note/: if you use GHCi or Template Haskell, please see the
@README@ file for important details about building this package,
and other packages that depend on it:
Please sign in to comment.
Something went wrong with that request. Please try again.