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