git.iko.soy/typeable/aeson
on 1.1.x help sign in
typeable/aeson/Data/Aeson/Parser.hs
70 lines 2.3 kB history raw
1{-# LANGUAGE OverloadedStrings #-}
3-- |
4-- Module: Data.Aeson.Parser
5-- Copyright: (c) 2012-2016 Bryan O'Sullivan
6-- (c) 2011 MailRank, Inc.
7-- License: BSD3
8-- Maintainer: Bryan O'Sullivan <bos@serpentine.com>
9-- Stability: experimental
10-- Portability: portable
11--
12-- Efficiently and correctly parse a JSON string. The string must be
13-- encoded as UTF-8.
14--
15-- It can be useful to think of parsing as occurring in two phases:
16--
17-- * Identification of the textual boundaries of a JSON value. This
18-- is always strict, so that an invalid JSON document can be
19-- rejected as soon as possible.
20--
21-- * Conversion of a JSON value to a Haskell value. This may be
22-- either immediate (strict) or deferred (lazy); see below for
23-- details.
24--
25-- The question of whether to choose a lazy or strict parser is
26-- subtle, but it can have significant performance implications,
27-- resulting in changes in CPU use and memory footprint of 30% to 50%,
28-- or occasionally more. Measure the performance of your application
29-- with each!
31module Data.Aeson.Parser
32 (
33 -- * Lazy parsers
34 -- $lazy
35 json
36 , value
37 , jstring
38 -- * Strict parsers
39 -- $strict
40 , json'
41 , value'
42 -- * Decoding without FromJSON instances
43 , decodeWith
44 , decodeStrictWith
45 , eitherDecodeWith
46 , eitherDecodeStrictWith
47 ) where
49import Prelude ()
51import Data.Aeson.Parser.Internal (decodeStrictWith, decodeWith, eitherDecodeStrictWith, eitherDecodeWith, json, json', jstring, value, value')
53-- $lazy
54--
55-- The 'json' and 'value' parsers decouple identification from
56-- conversion. Identification occurs immediately (so that an invalid
57-- JSON document can be rejected as early as possible), but conversion
58-- to a Haskell value is deferred until that value is needed.
59--
60-- This decoupling can be time-efficient if only a smallish subset of
61-- elements in a JSON value need to be inspected, since the cost of
62-- conversion is zero for uninspected elements. The trade off is an
63-- increase in memory usage, due to allocation of thunks for values
64-- that have not yet been converted.
66-- $strict
67--
68-- The 'json'' and 'value'' parsers combine identification with
69-- conversion. They consume more CPU cycles up front, but have a
70-- smaller memory footprint.