-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Canonical JSON for signing and hashing JSON values
--   
--   An implementation of Canonical JSON.
--   
--   <a>http://wiki.laptop.org/go/Canonical_JSON</a>
--   
--   The "canonical JSON" format is designed to provide repeatable hashes
--   of JSON-encoded data. It is designed for applications that need to
--   hash, sign or authenitcate JSON data structures, including embedded
--   signatures.
--   
--   Canonical JSON is parsable with any full JSON parser, and it allows
--   whitespace for pretty-printed human readable presentation, but it can
--   be put into a canonical form which then has a stable serialised
--   representation and thus a stable hash.
@package canonical-json
@version 0.6.0.0


module Text.JSON.Canonical.Types
data JSValue
JSNull :: JSValue
JSBool :: !Bool -> JSValue
JSNum :: !Int54 -> JSValue
JSString :: !JSString -> JSValue
JSArray :: [JSValue] -> JSValue
JSObject :: [(JSString, JSValue)] -> JSValue

-- | 54-bit integer values
--   
--   JavaScript can only safely represent numbers between <tt>-(2^53 -
--   1)</tt> and <tt>2^53 - 1</tt>.
--   
--   TODO: Although we introduce the type here, we don't actually do any
--   bounds checking and just inherit all type class instance from Int64.
--   We should probably define <a>fromInteger</a> to do bounds checking,
--   give different instances for type classes such as <a>Bounded</a> and
--   <a>FiniteBits</a>, etc.
newtype Int54
Int54 :: Int64 -> Int54
[int54ToInt64] :: Int54 -> Int64

-- | Canonical JSON strings are in fact just bytes.
data JSString
toJSString :: String -> JSString
fromJSString :: JSString -> String
instance GHC.Base.Monoid Text.JSON.Canonical.Types.JSString
instance GHC.Base.Semigroup Text.JSON.Canonical.Types.JSString
instance Data.String.IsString Text.JSON.Canonical.Types.JSString
instance GHC.Classes.Ord Text.JSON.Canonical.Types.JSString
instance GHC.Classes.Eq Text.JSON.Canonical.Types.JSString
instance Text.Printf.PrintfArg Text.JSON.Canonical.Types.Int54
instance Foreign.Storable.Storable Text.JSON.Canonical.Types.Int54
instance Data.Bits.Bits Text.JSON.Canonical.Types.Int54
instance Data.Bits.FiniteBits Text.JSON.Canonical.Types.Int54
instance GHC.Ix.Ix Text.JSON.Canonical.Types.Int54
instance GHC.Real.Real Text.JSON.Canonical.Types.Int54
instance GHC.Classes.Ord Text.JSON.Canonical.Types.Int54
instance GHC.Num.Num Text.JSON.Canonical.Types.Int54
instance Data.Data.Data Text.JSON.Canonical.Types.Int54
instance GHC.Real.Integral Text.JSON.Canonical.Types.Int54
instance GHC.Classes.Eq Text.JSON.Canonical.Types.Int54
instance GHC.Enum.Enum Text.JSON.Canonical.Types.Int54
instance GHC.Classes.Ord Text.JSON.Canonical.Types.JSValue
instance GHC.Classes.Eq Text.JSON.Canonical.Types.JSValue
instance GHC.Read.Read Text.JSON.Canonical.Types.JSValue
instance GHC.Show.Show Text.JSON.Canonical.Types.JSValue
instance Control.DeepSeq.NFData Text.JSON.Canonical.Types.JSValue
instance GHC.Enum.Bounded Text.JSON.Canonical.Types.Int54
instance GHC.Show.Show Text.JSON.Canonical.Types.Int54
instance GHC.Read.Read Text.JSON.Canonical.Types.Int54
instance Control.DeepSeq.NFData Text.JSON.Canonical.Types.JSString
instance GHC.Show.Show Text.JSON.Canonical.Types.JSString
instance GHC.Read.Read Text.JSON.Canonical.Types.JSString
instance Text.Printf.PrintfArg Text.JSON.Canonical.Types.JSString


-- | Minimal implementation of Canonical JSON parsing and printing.
--   
--   <a>http://wiki.laptop.org/go/Canonical_JSON</a>
--   
--   TODO: Known bugs/limitations:
--   
--   <ul>
--   <li>Decoding/encoding Unicode code-points beyond <tt>U+00ff</tt> is
--   currently broken</li>
--   </ul>
module Text.JSON.Canonical.Parse

-- | Parse a canonical JSON format string as a JSON value. The input string
--   does not have to be in canonical form, just in the "canonical JSON"
--   format.
--   
--   Use <a>renderCanonicalJSON</a> to convert into canonical form.
parseCanonicalJSON :: ByteString -> Either String JSValue

-- | Render a JSON value in canonical form. This rendered form is canonical
--   and so allows repeatable hashes.
--   
--   For pretty printing, see prettyCanonicalJSON.
--   
--   NB: Canonical JSON's string escaping rules deviate from RFC 7159 JSON
--   which requires
--   
--   "All Unicode characters may be placed within the quotation marks,
--   except for the characters that must be escaped: quotation mark,
--   reverse solidus, and the control characters (<tt>U+0000</tt> through
--   <tt>U+001F</tt>)."
--   
--   Whereas the current specification of Canonical JSON explicitly
--   requires to violate this by only escaping the quotation mark and the
--   reverse solidus. This, however, contradicts Canonical JSON's statement
--   that "Canonical JSON is parsable with any full JSON parser"
--   
--   Consequently, Canonical JSON is not a proper subset of RFC 7159.
renderCanonicalJSON :: JSValue -> ByteString

-- | Render a JSON value in a reasonable human-readable form. This rendered
--   form is <i>not the canonical form</i> used for repeatable hashes, use
--   <a>renderCanonicalJSON</a> for that.
prettyCanonicalJSON :: JSValue -> String


-- | Type classes and utilities for converting to and from <a>JSValue</a>.
module Text.JSON.Canonical.Class
class ToJSON m a
toJSON :: ToJSON m a => a -> m JSValue
class FromJSON m a
fromJSON :: FromJSON m a => JSValue -> m a

-- | Used in the <a>ToJSON</a> instance for <a>Map</a>
class ToObjectKey m a
toObjectKey :: ToObjectKey m a => a -> m JSString

-- | Used in the <a>FromJSON</a> instance for <a>Map</a>
class FromObjectKey m a
fromObjectKey :: FromObjectKey m a => JSString -> m (Maybe a)

-- | Monads in which we can report schema errors
class (Applicative m, Monad m) => ReportSchemaErrors m
expected :: ReportSchemaErrors m => Expected -> Maybe Got -> m a
type Expected = String
type Got = String
expectedButGotValue :: ReportSchemaErrors m => Expected -> JSValue -> m a
fromJSObject :: ReportSchemaErrors m => JSValue -> m [(JSString, JSValue)]

-- | Extract a field from a JSON object
fromJSField :: (ReportSchemaErrors m, FromJSON m a) => JSValue -> JSString -> m a
fromJSOptField :: (ReportSchemaErrors m, FromJSON m a) => JSValue -> JSString -> m (Maybe a)
mkObject :: forall m. Monad m => [(JSString, m JSValue)] -> m JSValue
instance Text.JSON.Canonical.Class.ReportSchemaErrors m => Text.JSON.Canonical.Class.FromJSON m Text.JSON.Canonical.Types.JSString
instance Text.JSON.Canonical.Class.ReportSchemaErrors m => Text.JSON.Canonical.Class.FromJSON m GHC.Base.String
instance Text.JSON.Canonical.Class.ReportSchemaErrors m => Text.JSON.Canonical.Class.FromJSON m Text.JSON.Canonical.Types.Int54
instance (Text.JSON.Canonical.Class.ReportSchemaErrors m, Text.JSON.Canonical.Class.FromJSON m a) => Text.JSON.Canonical.Class.FromJSON m [a]
instance (Text.JSON.Canonical.Class.ReportSchemaErrors m, GHC.Classes.Ord k, Text.JSON.Canonical.Class.FromObjectKey m k, Text.JSON.Canonical.Class.FromJSON m a) => Text.JSON.Canonical.Class.FromJSON m (Data.Map.Internal.Map k a)
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.FromObjectKey m Text.JSON.Canonical.Types.JSString
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.FromObjectKey m GHC.Base.String
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.ToObjectKey m Text.JSON.Canonical.Types.JSString
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.ToObjectKey m GHC.Base.String
instance (GHC.Base.Monad m, Text.JSON.Canonical.Class.ToObjectKey m k, Text.JSON.Canonical.Class.ToJSON m a) => Text.JSON.Canonical.Class.ToJSON m (Data.Map.Internal.Map k a)
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.FromJSON m Text.JSON.Canonical.Types.JSValue
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.ToJSON m Text.JSON.Canonical.Types.JSValue
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.ToJSON m Text.JSON.Canonical.Types.JSString
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.ToJSON m GHC.Base.String
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.ToJSON m Text.JSON.Canonical.Types.Int54
instance (GHC.Base.Monad m, Text.JSON.Canonical.Class.ToJSON m a) => Text.JSON.Canonical.Class.ToJSON m [a]


-- | An implementation of Canonical JSON.
--   
--   <a>http://wiki.laptop.org/go/Canonical_JSON</a>
--   
--   The "canonical JSON" format is designed to provide repeatable hashes
--   of JSON-encoded data. It is designed for applications that need to
--   hash, sign or authenitcate JSON data structures.
--   
--   The format is an extended subset of the normal JSON format.
--   
--   Canonical JSON is parsable with any full JSON parser, and it allows
--   whitespace for pretty-printed human readable presentation, but it can
--   be put into a canonical form which then has a stable serialised
--   representation and thus a stable hash.
--   
--   The basic concept is that a file in the canonical JSON format can be
--   read using <a>parseCanonicalJSON</a>. Note that this input file does
--   <i>not</i> itself need to be in canonical form, it just needs to be in
--   the canonical JSON format. Then the <a>renderCanonicalJSON</a>
--   function is used to render into the canonical form. This is then the
--   form that can be hashed or signed etc.
--   
--   The <a>prettyCanonicalJSON</a> is for convenience to render in a human
--   readable style, since the canoncal form eliminates unnecessary white
--   space which makes the output hard to read. This style is again
--   suitable to read using <a>parseCanonicalJSON</a>. So this is suitable
--   to use for producing output that has to be later hashed or otherwise
--   checked.
--   
--   Known bugs/limitations:
--   
--   <ul>
--   <li>Decoding/encoding Unicode code-points beyond <tt>U+00ff</tt> is
--   currently broken</li>
--   </ul>
module Text.JSON.Canonical
data JSValue
JSNull :: JSValue
JSBool :: !Bool -> JSValue
JSNum :: !Int54 -> JSValue
JSString :: !JSString -> JSValue
JSArray :: [JSValue] -> JSValue
JSObject :: [(JSString, JSValue)] -> JSValue

-- | 54-bit integer values
--   
--   JavaScript can only safely represent numbers between <tt>-(2^53 -
--   1)</tt> and <tt>2^53 - 1</tt>.
--   
--   TODO: Although we introduce the type here, we don't actually do any
--   bounds checking and just inherit all type class instance from Int64.
--   We should probably define <a>fromInteger</a> to do bounds checking,
--   give different instances for type classes such as <a>Bounded</a> and
--   <a>FiniteBits</a>, etc.
data Int54

-- | Canonical JSON strings are in fact just bytes.
data JSString

-- | Parse a canonical JSON format string as a JSON value. The input string
--   does not have to be in canonical form, just in the "canonical JSON"
--   format.
--   
--   Use <a>renderCanonicalJSON</a> to convert into canonical form.
parseCanonicalJSON :: ByteString -> Either String JSValue

-- | Render a JSON value in canonical form. This rendered form is canonical
--   and so allows repeatable hashes.
--   
--   For pretty printing, see prettyCanonicalJSON.
--   
--   NB: Canonical JSON's string escaping rules deviate from RFC 7159 JSON
--   which requires
--   
--   "All Unicode characters may be placed within the quotation marks,
--   except for the characters that must be escaped: quotation mark,
--   reverse solidus, and the control characters (<tt>U+0000</tt> through
--   <tt>U+001F</tt>)."
--   
--   Whereas the current specification of Canonical JSON explicitly
--   requires to violate this by only escaping the quotation mark and the
--   reverse solidus. This, however, contradicts Canonical JSON's statement
--   that "Canonical JSON is parsable with any full JSON parser"
--   
--   Consequently, Canonical JSON is not a proper subset of RFC 7159.
renderCanonicalJSON :: JSValue -> ByteString

-- | Render a JSON value in a reasonable human-readable form. This rendered
--   form is <i>not the canonical form</i> used for repeatable hashes, use
--   <a>renderCanonicalJSON</a> for that.
prettyCanonicalJSON :: JSValue -> String
class ToJSON m a
toJSON :: ToJSON m a => a -> m JSValue
class FromJSON m a
fromJSON :: FromJSON m a => JSValue -> m a

-- | Used in the <a>ToJSON</a> instance for <a>Map</a>
class ToObjectKey m a
toObjectKey :: ToObjectKey m a => a -> m JSString

-- | Used in the <a>FromJSON</a> instance for <a>Map</a>
class FromObjectKey m a
fromObjectKey :: FromObjectKey m a => JSString -> m (Maybe a)

-- | Monads in which we can report schema errors
class (Applicative m, Monad m) => ReportSchemaErrors m
expected :: ReportSchemaErrors m => Expected -> Maybe Got -> m a
type Expected = String
type Got = String
expectedButGotValue :: ReportSchemaErrors m => Expected -> JSValue -> m a
toJSString :: String -> JSString
fromJSString :: JSString -> String
fromJSObject :: ReportSchemaErrors m => JSValue -> m [(JSString, JSValue)]

-- | Extract a field from a JSON object
fromJSField :: (ReportSchemaErrors m, FromJSON m a) => JSValue -> JSString -> m a
fromJSOptField :: (ReportSchemaErrors m, FromJSON m a) => JSValue -> JSString -> m (Maybe a)
mkObject :: forall m. Monad m => [(JSString, m JSValue)] -> m JSValue
