@@ -47,16 +47,17 @@ import qualified Data.ByteString.Unsafe as B
4747import qualified Data.HashMap.Strict as H
4848
4949-- | Parse a top-level JSON value. This must be either an object or
50−-- an array.
50+-- an array, per RFC 4627.
5151--
52−-- The conversion of parsed values to Haskell values is deferred.
53−-- This may improve performance if not all of the results of
54−-- conversions are needed, but at a cost in thunk allocation.
52+-- The conversion of a parsed value to a Haskell value is deferred
53+-- until the Haskell value is needed. This may improve performance if
54+-- only a subset of the results of conversions are needed, but at a
55+-- cost in thunk allocation.
5556json :: Parser Value
5657json = json_ object_ array_
5758
5859-- | Parse a top-level JSON value. This must be either an object or
59−-- an array.
60+-- an array, per RFC 4627.
6061--
6162-- This is a strict version of 'json' which avoids building up thunks
6263-- during parsing; it performs all conversions immediately. Prefer
@@ -111,8 +112,15 @@ arrayValues val = do
111112{-# INLINE arrayValues #-}
112113
113114-- | Parse any JSON value. You should usually 'json' in preference to
114−-- this function. This is only safe to use if you are parsing data
115−-- from an untrusted source.
115+-- this function, as this function relaxes the object-or-array
116+-- requirement of RFC 4627.
117+--
118+-- In particular, be careful in using this function if you think your
119+-- code might interoperate with Javascript. A naïve Javascript
120+-- library that parses JSON data using @eval@ is vulnerable to attack
121+-- unless the encoded data represents an object or an array. JSON
122+-- implementations in other languages conform to that same restriction
123+-- to preserve interoperability and security.
116124value :: Parser Value
117125value = most <|> (Number <$> number)
118126 where