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


-- | Data structure agnostic JSON serialization
--   
--   Most json packages dictate a data structure that corresponds to json
--   values. To serialize other values to json, then that value must be
--   marshalled into the specified structure.
--   
--   This library avoids this marshalling step, and is thus potentially
--   more efficient when serializing arbitrary data structures.
--   Unfortunately json-builder cannot yet read or process json data, and
--   it's not clear to me yet how pull a similar kind of trick to avoid
--   unnecessary data structures when parsing json data into arbitrary data
--   types.
@package json-builder
@version 0.3


-- | Internal bits. By using the constructors provided in this module, you
--   can break the abstraction that json-builder provides and emit invalid
--   JSON syntax. Also, this module is not as stable as the public
--   interface and can change at any time.
module Data.Json.Builder.Internal

-- | The <a>Json</a> type represents valid json syntax. It cannot be
--   directly analyzed, however it can be turned into a <a>Builder</a> via
--   <a>toBuilder</a>, a (lazy) <a>ByteString</a> via <a>toJsonBS</a> or
--   <a>toJsonLBS</a>, or used as a component of a json <a>Array</a> or
--   json <a>Object</a> using <a>element</a> or <a>row</a>.
newtype Json
Json :: Builder -> Json

-- | The <a>Object</a> type represents syntax for a json object. It has a
--   singleton constructor <a>row</a>, and an instance of <a>Monoid</a>, so
--   that <a>mempty</a> represents the empty object and <a>mappend</a>
--   concatinates two objects. Arbitrary objects can be constructed using
--   these operators.
--   
--   Note that duplicate field names will appear in the output, so it is up
--   to the user of this interface to avoid duplicate field names.
newtype Object
Object :: CommaMonoid -> Object

-- | The <a>Array</a> type represents syntax for a json array. It has been
--   given a singleton constructor <a>element</a> and an instance of
--   <a>Monoid</a>, so that <a>mempty</a> represents the empty array and
--   <a>mappend</a> concatinates two arrays. Arbitrary arrays can be
--   constructed using these operators.
newtype Array
Array :: CommaMonoid -> Array

-- | The <a>Escaped</a> type represents json string syntax. The purpose of
--   this type is so that json strings can be efficiently constructed from
--   multiple Haskell strings without superfluous conversions or
--   concatinations.
--   
--   Internally, it is just a <a>Builder</a> value which must produce a
--   UTF-8 encoded bytestring with backslashes, quotes, and control
--   characters appropriately escaped. It also must not render the opening
--   or closing quote, which are instead rendered by <a>toJson</a>.
newtype Escaped
Escaped :: Builder -> Escaped

-- | A <a>CommaMonoid</a> inserts commas between builders. In order to
--   satisify the <a>Monoid</a> identity laws, <a>Empty</a> must be
--   distinguished from <tt><a>Comma</a> <a>mempty</a></tt>. To demonstrate
--   the difference:
--   
--   <pre>
--   mconcat ["foo", ""    , "bar"]  ==  "foo,,bar"
--   mconcat ["foo", Empty , "bar"]  ==  "foo,bar"
--   </pre>
--   
--   The strings in this example denote <tt>CommaMonoids</tt> via
--   <tt><a>fromString</a> = Comma . <a>fromString</a></tt>. Thus
--   <tt>""</tt> is equivalent to <tt>Comma mempty</tt>.
data CommaMonoid
Empty :: CommaMonoid
Comma :: !Builder -> CommaMonoid


-- | Data structure agnostic JSON serialization
module Data.Json.Builder

-- | The <a>Json</a> type represents valid json syntax. It cannot be
--   directly analyzed, however it can be turned into a <a>Builder</a> via
--   <a>toBuilder</a>, a (lazy) <a>ByteString</a> via <a>toJsonBS</a> or
--   <a>toJsonLBS</a>, or used as a component of a json <a>Array</a> or
--   json <a>Object</a> using <a>element</a> or <a>row</a>.
data Json
toBuilder :: Value a => a -> Builder
toJsonBS :: Value a => a -> ByteString
toJsonLBS :: Value a => a -> ByteString

-- | The <a>Value</a> typeclass represents types that can be rendered into
--   valid json syntax.
class Value a
toJson :: Value a => a -> Json

-- | this renders as Json's <tt>null</tt> value.
jsNull :: Json

-- | The <a>Array</a> type represents syntax for a json array. It has been
--   given a singleton constructor <a>element</a> and an instance of
--   <a>Monoid</a>, so that <a>mempty</a> represents the empty array and
--   <a>mappend</a> concatinates two arrays. Arbitrary arrays can be
--   constructed using these operators.
data Array

-- | The <a>element</a> function constructs a json array consisting of
--   exactly one value. These arrays can be concatinated using
--   <a>mappend</a>.
element :: Value a => a -> Array
class JsArray a
toArray :: JsArray a => a -> Array

-- | The <a>Object</a> type represents syntax for a json object. It has a
--   singleton constructor <a>row</a>, and an instance of <a>Monoid</a>, so
--   that <a>mempty</a> represents the empty object and <a>mappend</a>
--   concatinates two objects. Arbitrary objects can be constructed using
--   these operators.
--   
--   Note that duplicate field names will appear in the output, so it is up
--   to the user of this interface to avoid duplicate field names.
data Object

-- | The <a>row</a> function constructs a json object consisting of exactly
--   one field. These objects can be concatinated using <a>mappend</a>.
row :: (JsString k, Value a) => k -> a -> Object
class JsObject a
toObject :: JsObject a => a -> Object

-- | The <a>Escaped</a> type represents json string syntax. The purpose of
--   this type is so that json strings can be efficiently constructed from
--   multiple Haskell strings without superfluous conversions or
--   concatinations.
--   
--   Internally, it is just a <a>Builder</a> value which must produce a
--   UTF-8 encoded bytestring with backslashes, quotes, and control
--   characters appropriately escaped. It also must not render the opening
--   or closing quote, which are instead rendered by <a>toJson</a>.
data Escaped

-- | The <a>JsString</a> typeclass represents types that can be render into
--   json string syntax. They are special because only strings can appear
--   as field names of json objects.
class Value a => JsString a
escape :: JsString a => a -> Escaped

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following laws:
--   
--   <ul>
--   <li><pre>mappend mempty x = x</pre></li>
--   <li><pre>mappend x mempty = x</pre></li>
--   <li><pre>mappend x (mappend y z) = mappend (mappend x y) z</pre></li>
--   <li><pre>mconcat = <a>foldr</a> mappend mempty</pre></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <tt>Sum</tt> and <tt>Product</tt>.
class Monoid a

-- | Identity of <a>mappend</a>
mempty :: Monoid a => a

-- | An associative operation
mappend :: Monoid a => a -> a -> a

-- | Fold a list using the monoid. For most types, the default definition
--   for <a>mconcat</a> will be used, but the function is included in the
--   class definition so that an optimized version can be provided for
--   specific types.
mconcat :: Monoid a => [a] -> a
