aeson / Data / Aeson / Parser.hs

The default branch has multiple heads

{-# LANGUAGE BangPatterns, OverloadedStrings #-}

-- |
-- Module:      Data.Aeson.Parser
-- Copyright:   (c) 2012 Bryan O'Sullivan
--              (c) 2011 MailRank, Inc.
-- License:     Apache
-- Maintainer:  Bryan O'Sullivan <bos@serpentine.com>
-- Stability:   experimental
-- Portability: portable
--
-- Efficiently and correctly parse a JSON string.  The string must be
-- encoded as UTF-8.
--
-- It can be useful to think of parsing as occurring in two phases:
--
-- * Identification of the textual boundaries of a JSON value.  This
--   is always strict, so that an invalid JSON document can be
--   rejected as soon as possible.
--
-- * Conversion of a JSON value to a Haskell value.  This may be
--   either immediate (strict) or deferred (lazy); see below for
--   details.
--
-- The question of whether to choose a lazy or strict parser is
-- subtle, but it can have significant performance implications,
-- resulting in changes in CPU use and memory footprint of 30% to 50%,
-- or occasionally more.  Measure the performance of your application
-- with each!

module Data.Aeson.Parser
    (
    -- * Lazy parsers
    -- $lazy
      json
    , value
    , jstring
    -- * Strict parsers
    -- $strict
    , json'
    , value'
    ) where

import Data.Aeson.Parser.Internal (json, json', jstring, value, value')

-- $lazy
--
-- The 'json' and 'value' parsers decouple identification from
-- conversion.  Identification occurs immediately (so that an invalid
-- JSON document can be rejected as early as possible), but conversion
-- to a Haskell value is deferred until that value is needed.
--
-- This decoupling can be time-efficient if only a smallish subset of
-- elements in a JSON value need to be inspected, since the cost of
-- conversion is zero for uninspected elements.  The trade off is an
-- increase in memory usage, due to allocation of thunks for values
-- that have not yet been converted.

-- $strict
--
-- The 'json'' and 'value'' parsers combine identification with
-- conversion.  They consume more CPU cycles up front, but have a
-- smaller memory footprint.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.