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


-- | Convenience wrappers around common data structures and encodings
--   
--   Wrappers around common data structures and encodings.
--   
--   This is part of a library intended to ease interoperability and assist
--   in building command-line programs, both tools and longer-running
--   daemons. A list of features and some background to the library's
--   design is contained in the <a>README</a> on GitHub.
@package core-data
@version 0.3.0.2


-- | Convenience wrappers around dictionary and collection types and tools
--   facilitating conversion between them and various map and set types in
--   common use in the Haskell ecosystem.
module Core.Data.Structures

-- | A mapping from keys to values.
--   
--   The keys in a map needs to be an instance of the <a>Key</a> typeclass.
--   Instances are already provided for many common element types.
--   
--   <a>Map</a> implements <a>Foldable</a>, <a>Monoid</a>, etc so many
--   common operations such as <a>foldr</a> to reduce the structure with a
--   right fold, <a>length</a> to get the number of key/value pairs in the
--   dictionary, <a>null</a> to test whether the map is empty, and
--   (<a>&lt;&gt;</a>) to join two maps together are available.
--   
--   To convert to other dictionary types see <a>fromMap</a> below.
--   
--   (this is a thin wrapper around <b>unordered-containers</b>'s
--   <a>HashMap</a>, but if you use the conversion functions to extract the
--   key/value pairs in a list the list will be ordered according to the
--   keys' <a>Ord</a> instance)
data Map κ ν

-- | A dictionary with no key/value mappings.
emptyMap :: Map κ ν

-- | Construct a dictionary with only a single key/value pair.
singletonMap :: Key κ => κ -> ν -> Map κ ν

-- | Insert a key/value pair into the dictionary. If the key is already
--   present in the dictionary, the old value will be discarded and
--   replaced with the value supplied here.
insertKeyValue :: Key κ => κ -> ν -> Map κ ν -> Map κ ν

-- | Does the dictionary contain the specified key?
containsKey :: Key κ => κ -> Map κ ν -> Bool

-- | If the dictionary contains the specified key, return the value
--   associated with that key.
lookupKeyValue :: Key κ => κ -> Map κ ν -> Maybe ν

-- | Types that represent key/value pairs that can be converted to
--   <a>Map</a>s. Haskell's ecosystem has several such. This typeclass
--   provides an adaptor to get between them. It also allows you to
--   serialize out to an association list.
--   
--   For example, to convert a <a>Map</a> to an "association list" of
--   key/value pairs, use <a>fromMap</a>:
--   
--   <pre>
--   answers :: <a>Map</a> <a>Rope</a> <a>Int</a>
--   answers = <a>singletonMap</a> "Life, The Universe, and Everything" 42
--   
--   list :: [(<a>Rope</a>,<a>Int</a>)]
--   list = <a>fromMap</a> answers
--   </pre>
--   
--   Instances are provided for <b>containers</b>'s <a>Map</a> and
--   <b>unordered-containers</b>'s <a>HashMap</a> in addition to the
--   instance for <tt>[(κ,ν)]</tt> lists shown above.
class Dictionary α where {
    type family K α :: *;
    type family V α :: *;
}
fromMap :: Dictionary α => Map (K α) (V α) -> α
intoMap :: Dictionary α => α -> Map (K α) (V α)

-- | A set of unique elements.
--   
--   The element type needs to be an instance of the same <a>Key</a>
--   typeclass that is used for keys in the <a>Map</a> type above.
--   Instances are already provided for many common element types.
--   
--   <a>Set</a> implements <a>Foldable</a>, <a>Monoid</a>, etc so many
--   common operations such as <a>foldr</a> to walk the elements and reduce
--   them, <a>length</a> to return the size of the collection, <a>null</a>
--   to test whether is empty, and (<a>&lt;&gt;</a>) to take the union of
--   two sets are available.
--   
--   To convert to other collection types see <a>fromSet</a> below.
--   
--   (this is a thin wrapper around <b>unordered-containers</b>'s
--   <a>HashSet</a>, but if you use the conversion functions to extract a
--   list the list will be ordered according to the elements' <a>Ord</a>
--   instance)
data Set ε

-- | An empty collection. This is used for example as an inital value when
--   building up a <a>Set</a> using a fold.
emptySet :: Key ε => Set ε

-- | Construct a collection comprising only the supplied element.
singletonSet :: Key ε => ε -> Set ε

-- | Insert a new element into the collection. Since the <a>Set</a> type
--   does not allow duplicates, inserting an element already in the
--   collection has no effect.
insertElement :: Key ε => ε -> Set ε -> Set ε

-- | Does the collection contain the specified element?
containsElement :: Key ε => ε -> Set ε -> Bool

-- | Types that represent collections of elements that can be converted to
--   <a>Set</a>s. Haskell's ecosystem has several such. This typeclass
--   provides an adaptor to convert between them.
--   
--   This typeclass also provides a mechanism to serialize a <a>Set</a> out
--   to a Haskell list. The list will be ordered according to the
--   <a>Ord</a> instance of the element type.
--   
--   Instances are provided for <b>containers</b>'s <a>Set</a> and
--   <b>unordered-containers</b>'s <a>HashSet</a> in addition to the
--   instance for <tt>[ε]</tt> lists described above.
class Collection α where {
    type family E α :: *;
}
fromSet :: Collection α => Set (E α) -> α
intoSet :: Collection α => α -> Set (E α)

-- | Types that can be used as keys in dictionaries or elements in
--   collections.
--   
--   To be an instance of <a>Key</a> a type must implement both
--   <a>Hashable</a> and <a>Ord</a>. This requirement means we can
--   subsequently offer easy conversion between different the dictionary
--   and collection types you might encounter when interacting with other
--   libraries.
--   
--   Instances for this library's <a>Rope</a> and <a>Bytes</a> are provided
--   here, along with many other common types.
class (Hashable κ, Ord κ) => Key κ
unMap :: Map κ ν -> HashMap κ ν
unSet :: Set ε -> HashSet ε
instance (GHC.Classes.Eq κ, GHC.Classes.Eq ν) => GHC.Classes.Eq (Core.Data.Structures.Map κ ν)
instance (GHC.Show.Show κ, GHC.Show.Show ν) => GHC.Show.Show (Core.Data.Structures.Map κ ν)
instance GHC.Classes.Eq ε => GHC.Classes.Eq (Core.Data.Structures.Set ε)
instance GHC.Show.Show ε => GHC.Show.Show (Core.Data.Structures.Set ε)
instance Core.Data.Structures.Key ε => Core.Data.Structures.Collection (Core.Data.Structures.Set ε)
instance Core.Data.Structures.Key ε => Core.Data.Structures.Collection (Data.HashSet.Internal.HashSet ε)
instance Core.Data.Structures.Key ε => Core.Data.Structures.Collection (Data.Set.Internal.Set ε)
instance Core.Data.Structures.Key ε => Core.Data.Structures.Collection [ε]
instance Data.Foldable.Foldable Core.Data.Structures.Set
instance Core.Data.Structures.Key ε => GHC.Base.Semigroup (Core.Data.Structures.Set ε)
instance Core.Data.Structures.Key ε => GHC.Base.Monoid (Core.Data.Structures.Set ε)
instance Core.Data.Structures.Key κ => Core.Data.Structures.Dictionary (Core.Data.Structures.Map κ ν)
instance Core.Data.Structures.Key κ => Core.Data.Structures.Dictionary (Data.HashMap.Internal.HashMap κ ν)
instance Core.Data.Structures.Key κ => Core.Data.Structures.Dictionary (Data.Map.Internal.Map κ ν)
instance Core.Data.Structures.Key κ => Core.Data.Structures.Dictionary [(κ, ν)]
instance Core.Data.Structures.Key GHC.Base.String
instance Core.Data.Structures.Key Core.Text.Rope.Rope
instance Core.Data.Structures.Key Core.Text.Bytes.Bytes
instance Core.Data.Structures.Key Data.Text.Internal.Text
instance Core.Data.Structures.Key Data.Text.Internal.Lazy.Text
instance Core.Data.Structures.Key GHC.Types.Char
instance Core.Data.Structures.Key GHC.Types.Int
instance Core.Data.Structures.Key Data.ByteString.Internal.ByteString
instance Core.Data.Structures.Key κ => GHC.Base.Semigroup (Core.Data.Structures.Map κ ν)
instance Core.Data.Structures.Key κ => GHC.Base.Monoid (Core.Data.Structures.Map κ ν)
instance Core.Data.Structures.Key κ => GHC.Exts.IsList (Core.Data.Structures.Map κ ν)
instance Data.Foldable.Foldable (Core.Data.Structures.Map κ)


-- | Wrappers and adaptors for various data structures common in the
--   Haskell ecosystem.
--   
--   This is intended to be used directly:
--   
--   <pre>
--   import <a>Core.Data</a>
--   </pre>
--   
--   as this module re-exports all of its various components.
module Core.Data


-- | Encoding and decoding UTF-8 JSON content.
--   
--   This module is a thin wrapper around the most excellent <b>aeson</b>
--   library, which has rich and powerful facilities for encoding Haskell
--   types into JSON.
--   
--   Quite often, however, you find yourself having to create a Haskell
--   type <i>just</i> to read some JSON coming from an external web service
--   or API. This can be challenging when the source of the JSON is complex
--   or varying its schema over time. For ease of exploration this module
--   simply defines an easy to use intermediate type representing JSON as a
--   format.
--   
--   Often you'll be working with literals directly in your code. While you
--   can write:
--   
--   <pre>
--   j = <a>JsonObject</a> (<a>intoMap</a> [(<a>JsonKey</a> "answer", <a>JsonNumber</a> 42)])
--   </pre>
--   
--   and it would be correct, enabling:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   {-# LANGUAGE OverloadedLists #-}
--   </pre>
--   
--   allows you to write:
--   
--   <pre>
--   j = <a>JsonObject</a> [("answer", 42)]
--   </pre>
--   
--   which you is somewhat less cumbersome in declaration-heavy code.
--   You're certainly welcome to use the constructors if you find it makes
--   for more readable code or if you need the type annotations.
module Core.Encoding.Json

-- | Given a JSON value, encode it to UTF-8 bytes
--   
--   I know we're not <i>supposed</i> to rely on types to document
--   functions, but really, this one does what it says on the tin.
encodeToUTF8 :: JsonValue -> Bytes

-- | Given a JSON value, encode it to a Rope (which, by definition, is
--   UTF-8 internally).
encodeToRope :: JsonValue -> Rope

-- | Given an array of bytes, attempt to decode it as a JSON value.
decodeFromUTF8 :: Bytes -> Maybe JsonValue

-- | Given an string that is full of a bunch of JSON, attempt to decode it.
decodeFromRope :: Rope -> Maybe JsonValue

-- | A JSON value.
data JsonValue
JsonObject :: Map JsonKey JsonValue -> JsonValue
JsonArray :: [JsonValue] -> JsonValue
JsonString :: Rope -> JsonValue
JsonNumber :: Scientific -> JsonValue
JsonBool :: Bool -> JsonValue
JsonNull :: JsonValue

-- | Keys in a JSON object.
newtype JsonKey
JsonKey :: Rope -> JsonKey

-- | Support for pretty-printing JSON values with syntax highlighting using
--   the <b>prettyprinter</b> library. To output a JSON structure to
--   terminal colourized with ANSI escape codes you can use the
--   <a>Render</a> instance:
--   
--   <pre>
--   debug "j" (render j)
--   </pre>
--   
--   will get you:
--   
--   <pre>
--   23:46:04Z (00.007) j =
--   {
--       "answer": 42
--   }
--   </pre>
data JsonToken
SymbolToken :: JsonToken
QuoteToken :: JsonToken
KeyToken :: JsonToken
StringToken :: JsonToken
EscapeToken :: JsonToken
NumberToken :: JsonToken
BooleanToken :: JsonToken
LiteralToken :: JsonToken

-- | Used by the <a>Render</a> instance to turn symbolic annotations into
--   ANSI colours annotations. If you're curious, the render pipeline looks
--   like:
--   
--   <pre>
--   render = <tt>intoText</tt> . <tt>renderStrict</tt> . <tt>reAnnotateS</tt> <a>colourize</a>
--               . <tt>layoutPretty</tt> <tt>defaultLayoutOptions</tt> . <a>prettyValue</a>
--   </pre>
colourizeJson :: JsonToken -> AnsiColour
prettyKey :: JsonKey -> Doc JsonToken
prettyValue :: JsonValue -> Doc JsonToken
instance GHC.Classes.Ord Core.Encoding.Json.JsonKey
instance Data.String.IsString Core.Encoding.Json.JsonKey
instance GHC.Generics.Generic Core.Encoding.Json.JsonKey
instance GHC.Show.Show Core.Encoding.Json.JsonKey
instance GHC.Classes.Eq Core.Encoding.Json.JsonKey
instance GHC.Generics.Generic Core.Encoding.Json.JsonValue
instance GHC.Show.Show Core.Encoding.Json.JsonValue
instance GHC.Classes.Eq Core.Encoding.Json.JsonValue
instance Core.Text.Utilities.Render Core.Encoding.Json.JsonValue
instance Core.Text.Utilities.Render Core.Encoding.Json.JsonKey
instance Data.String.IsString Core.Encoding.Json.JsonValue
instance GHC.Num.Num Core.Encoding.Json.JsonValue
instance GHC.Real.Fractional Core.Encoding.Json.JsonValue
instance Prettyprinter.Internal.Pretty Core.Encoding.Json.JsonValue
instance Data.Hashable.Class.Hashable Core.Encoding.Json.JsonKey
instance Core.Data.Structures.Key Core.Encoding.Json.JsonKey
instance Core.Text.Rope.Textual Core.Encoding.Json.JsonKey
instance Prettyprinter.Internal.Pretty Core.Encoding.Json.JsonKey


-- | Various formats used for serialization, data transfer, and
--   configuration.
--   
--   This can be used by simply importing the top level module:
--   
--   <pre>
--   import <a>Core.Encoding</a>
--   </pre>
--   
--   although the individual formats are quite usable indepedently.
--   
--   Each of these encodings are backed by a popular and well tuned library
--   in wide use across the Haskell community; these modules are here as
--   wrappers providing for ease of use and interoperability across the
--   various tools in this package.
module Core.Encoding