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


-- | JSON parser that uses byte strings.
--   
--   This parser consumes lazy ByteStrings to produce JSON in a simple,
--   efficient format backed with strict ByteStrings, Rationals and
--   ByteString tries. See the schema generation tools and the command line
--   JSON schema generator (in the examples subdir) for an example of how
--   to use the parsing tools.
--   
--   Have you considered <tt>aeson</tt>
--   (<a>http://hackage.haskell.org/package/aeson</a>), a newer,
--   extensively benchmarked JSON parsing library?
@package JSONb
@version 1.0.7

module Text.JSON.Escape

-- | Class of JSON escapable text. The solidus (<tt>/</tt>) is always
--   escaped, as are all ASCII control characters. Non-ASCII control
--   characters and Unicode printable characters above ASCII are left as
--   is.
class Escape t
escape :: Escape t => t -> t

-- | Escapes an individual character for embedding in a JSON string.
esc :: Char -> String
instance Escape String
instance Escape ByteString
instance Escape ByteString


-- | JSON datatype definition.
module Text.JSONb.Simple

-- | A monomorphic JSON datatype, backed with <a>Rational</a>, strict
--   <a>ByteString</a> and <a>ByteString</a> <a>Trie</a>.
data JSON
Object :: (Trie JSON) -> JSON
Array :: [JSON] -> JSON
String :: ByteString -> JSON
Number :: Rational -> JSON
Boolean :: Bool -> JSON
Null :: JSON
instance Eq JSON
instance Show JSON


-- | Parse UTF-8 JSON into native Haskell types.
module Text.JSONb.Decode

-- | Interpret a <a>ByteString</a> as any JSON literal.
decode :: ByteString -> Either String JSON

-- | Split out the first parseable JSON literal from the input, returning
--   the result of the attempt along with the remainder of the input or the
--   whole input if no parseable item was discovered.
break :: ByteString -> (Either String JSON, ByteString)

-- | Tries to parse any JSON literal.
json :: Parser JSON

-- | Parse a JSON object (dictionary).
object :: Parser JSON

-- | Parse a JSON array.
array :: Parser JSON

-- | Parses a string literal, unescaping as it goes.
string :: Parser JSON

-- | Parses a numeric literal to a <tt>Rational</tt>.
number :: Parser JSON

-- | Parse a JSON Boolean literal.
boolean :: Parser JSON

-- | Parse a JSON null literal.
null :: Parser JSON

-- | Per RFC 4627, section 2 <a>JSON Grammar</a>, only a limited set of
--   whitespace characters actually count as insignificant whitespace.
whitespace :: Parser ()

-- | Parse a JSON string literal and unescape it but don't wrap it in a
--   string constructor (we might wrap it as a dict key instead).
string_literal :: Parser ByteString

module Text.JSONb.Encode

-- | Encode <a>JSON</a> as a strict <a>ByteString</a>. All strings are
--   treated as UTF-8; ASCII control characters are escaped and UTF-8
--   multi-char sequences are simply passed through.
encode :: Style -> JSON -> ByteString

-- | Style of serialization. Compact is the only one that is implemented at
--   present.
data Style
Compact :: Style

-- | Escape a <a>ByteString</a> representing a JSON string and wrap it in
--   quote marks.
stringify :: ByteString -> ByteString
instance Eq Style
instance Show Style

module Text.JSONb.Schema

-- | The type of JSON schemas. We treat the atomic types simply whereas
--   objects and arrays are treated specially.
--   
--   Objects are treated as maps of keys to sets of schema types. Say a
--   certain type of object sometimes has a string at a certain key and
--   sometimes has a null at that key; we should merge them and say the
--   schema of that key is a union of string and null.
--   
--   Arrays admit measure in the sense of how many elements there are of a
--   certain kind. We support three measures at present: any, one or more
--   and individual counts. We expect the <a>any</a> measure to prevail
--   practice. Arrays are also ordered; so one can distinguish an array
--   that interleaves strings and ints from one that is all strings and
--   then all ints.
data Schema counter
Num :: Schema counter
Str :: Schema counter
Bool :: Schema counter
Null :: Schema counter
Obj :: (Props counter) -> Schema counter
Arr :: (Elements counter) -> Schema counter

-- | Determine a schema for one JSON data item.
schema :: Counter counter => JSON -> Schema counter
props :: Counter counter => Trie JSON -> Props counter

-- | Develop a schema for a list of JSON data, collating schemas according
--   to the measure, a well-ordered semigroup.
schemas :: Counter counter => [JSON] -> [(counter, Schema counter)]

-- | Collate a list of counted schemas. Alike counted schemas that are
--   adjacent are replaced by a counted schema with an incremented counter.
--   This operation is mutually recursive with <a>merge</a>, in order to
--   merge comaptible object definitions before collating.
collate :: (Counter counter, Counter counter') => (counter, Schema counter') -> [(counter, Schema counter')] -> [(counter, Schema counter')]
data Props counter
Props :: (Trie (Set (Schema counter))) -> Props counter

-- | Merge two property sets. This operation is mutually recursive with our
--   <a>collate</a> and relies on polymorphic recusion in <a>collate</a>.
merge :: Counter counter => Props counter -> Props counter -> Props counter
match :: Counter counter => Props counter -> Props counter -> Bool
data Elements counter
Elements :: [(counter, Schema counter)] -> Elements counter
data OneMany
One :: OneMany
Many :: OneMany

-- | A well-ordered semigroup has a minimal element and an associative
--   operation. These are used to provide measures for schema. At present,
--   we allow three measures: whether there is one or more of a schema
--   (measured with '()'), whether there is one or more than one of an item
--   (measured with <a>OneMany</a>) and positive counts of items (measured
--   with <a>Word</a>).
class (Eq t, Show t, Ord t) => Counter t
bottom :: Counter t => t
plus :: Counter t => t -> t -> t
instance Show OneMany
instance Ord OneMany
instance Eq OneMany
instance Ord counter => Ord (Elements counter)
instance Eq counter => Eq (Elements counter)
instance Eq counter => Eq (Props counter)
instance Ord counter => Ord (Schema counter)
instance Eq counter => Eq (Schema counter)
instance Counter ()
instance Counter Word
instance Counter OneMany
instance Ord counter => Ord (Props counter)

module Text.JSONb.Schema.Display
class Display t
bytes :: Display t => t -> ByteString
instance Display counter => Show (Schema counter)
instance Display counter => Display (counter, Schema counter)
instance Display Word
instance Display OneMany
instance Display ()
instance Display counter => Display (Schema counter)


-- | ByteString parser for a simple, monomorphic JSON datatype.
module Text.JSONb

-- | A monomorphic JSON datatype, backed with <a>Rational</a>, strict
--   <a>ByteString</a> and <a>ByteString</a> <a>Trie</a>.
data JSON
Object :: (Trie JSON) -> JSON
Array :: [JSON] -> JSON
String :: ByteString -> JSON
Number :: Rational -> JSON
Boolean :: Bool -> JSON
Null :: JSON

-- | Interpret a <a>ByteString</a> as any JSON literal.
decode :: ByteString -> Either String JSON

-- | Split out the first parseable JSON literal from the input, returning
--   the result of the attempt along with the remainder of the input or the
--   whole input if no parseable item was discovered.
break :: ByteString -> (Either String JSON, ByteString)

-- | Style of serialization. Compact is the only one that is implemented at
--   present.
data Style
Compact :: Style

-- | Encode <a>JSON</a> as a strict <a>ByteString</a>. All strings are
--   treated as UTF-8; ASCII control characters are escaped and UTF-8
--   multi-char sequences are simply passed through.
encode :: Style -> JSON -> ByteString

-- | The type of JSON schemas. We treat the atomic types simply whereas
--   objects and arrays are treated specially.
--   
--   Objects are treated as maps of keys to sets of schema types. Say a
--   certain type of object sometimes has a string at a certain key and
--   sometimes has a null at that key; we should merge them and say the
--   schema of that key is a union of string and null.
--   
--   Arrays admit measure in the sense of how many elements there are of a
--   certain kind. We support three measures at present: any, one or more
--   and individual counts. We expect the <a>any</a> measure to prevail
--   practice. Arrays are also ordered; so one can distinguish an array
--   that interleaves strings and ints from one that is all strings and
--   then all ints.
data Schema counter

-- | Determine a schema for one JSON data item.
schema :: Counter counter => JSON -> Schema counter

-- | Develop a schema for a list of JSON data, collating schemas according
--   to the measure, a well-ordered semigroup.
schemas :: Counter counter => [JSON] -> [(counter, Schema counter)]
data OneMany
One :: OneMany
Many :: OneMany
class Display t
bytes :: Display t => t -> ByteString

-- | Class of JSON escapable text. The solidus (<tt>/</tt>) is always
--   escaped, as are all ASCII control characters. Non-ASCII control
--   characters and Unicode printable characters above ASCII are left as
--   is.
class Escape t
escape :: Escape t => t -> t
escaped :: Char -> Bool