-- 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.9.0


-- | The standard package for working with dates and times in Haskell,
--   <b>time</b>, is <i>awkward</i>. That's a subjective judgment, but over
--   the years there have been few areas more frustrating than trying to do
--   pragmatic things with calendars and clocks. This module represents
--   some opinionated approaches to working with times and dates, and a
--   place to collect some hard-won idioms for converting between things.
--   
--   Our original use was wanting to conveniently measure things happening
--   on distributed computer systems. Since machine clock cycles are in
--   units of nanoseconds, this has the nice property that, assuming the
--   system clock is not corrupted, two subsequent events from the same
--   source process are likely to have monotonically increasing timestamps.
--   And even if the system clock goes to hell, they're still decently
--   likely to be unique per device. Make for good keys.
--   
--   So the timestamp type herein <a>Time</a> is nanoseconds since the Unix
--   epoch; which in (signed) 64 bits means that you can represent times
--   between early in the morning of 21 September 1677 through just before
--   midnight on 11 April 2262. The primary use isn't doing calendaring,
--   though; it's just working with machine generated timestamps in
--   distributed systems and for conveying start and end times around in
--   your program.
--   
--   There are quite a few other time formats around the Haskell ecosystem.
--   You can use the <a>fromTime</a> and <a>intoTime</a> methods of the
--   <a>Instant</a> typeclass to convert from one to another if you need
--   to.
module Core.Data.Clock

-- | Number of nanoseconds since the Unix epoch.
--   
--   The <a>Show</a> and <a>Externalize</a> instances display the
--   <a>Time</a> as seconds with the nanosecond precision expressed as a
--   decimal amount after the interger, ie:
--   
--   <pre>
--   &gt;&gt;&gt; t &lt;- getCurrentTimeNanoseconds
--   
--   &gt;&gt;&gt; formatExternal t
--   "2014-07-31T23:09:35.274387031Z"
--   </pre>
--   
--   However this doesn't change the fact the underlying representation
--   counts nanoseconds since epoch:
--   
--   <pre>
--   &gt;&gt;&gt; show $ unTime t
--   "1406848175274387031"
--   </pre>
--   
--   There is a <tt>Externalize</tt> instance that is reasonably
--   accommodating:
--   
--   <pre>
--   &gt;&gt;&gt; parseExternal "2014-07-31T13:05:04.942089001Z" :: Maybe Time
--   Just 2014-07-31T13:05:04.942089001Z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseExternal "1406811904.942089001" :: Maybe Time
--   Just 2014-07-31T13:05:04.942089001Z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseExternal "1406811904" :: Maybe Time
--   Just 2014-07-31T13:05:04.000000000Z
--   </pre>
--   
--   In case you're wondering, the valid range of nanoseconds that fits
--   into the underlying <a>Int64</a> is:
--   
--   <pre>
--   &gt;&gt;&gt; formatExternal (minBound :: Time)
--   "1677-09-21T00:12:43.145224192Z"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; formatExternal (maxBound :: Time)
--   "2262-04-11T23:47:16.854775807Z"
--   </pre>
--   
--   so in a quarter millenium's time, yes, you'll have the Y2262 Problem.
--   Haskell code from today will, of course, still be running, so in the
--   mid Twenty-Third century you will need to replace this implementation
--   with something else.
data Time

-- | Get the current system time, expressed as a <a>Time</a> (which is to
--   say, number of nanoseconds since the Unix epoch).
getCurrentTimeNanoseconds :: IO Time

-- | Convert between different representations of time. Our <a>Time</a>
--   timestamp has nanosecond precision so converting from a type with
--   lesser or greater precision will require you to either pad with zeros
--   or to round to the nearest nanosecond (who the hell has picoseconds of
--   anything anyway?) if writing an instance of this type.
--   
--   The most important instance is probably the <a>UTCTime</a> one, as
--   many other Haskell libraries use this type to represent time.
class Instant a
fromTime :: Instant a => Time -> a
intoTime :: Instant a => a -> Time

-- | If you need to manipulate the date or calculate elapsed time then you
--   can dig out the underlying <a>Int64</a> here. We have <i>not</i>
--   provided instances of <a>Num</a>, <a>Real</a>, or <a>Integral</a> for
--   the timestamp type because adding two timestamps doesn't really make
--   sense. You can use <a>intoTime</a> to reconstruct a timestamp
--   subsequently if necessary.
unTime :: Time -> Int64

-- | The occasion of the Unix epoch, 1970-01-01T00:00:00.0Z.
epochTime :: Time
instance GHC.Generics.Generic Core.Data.Clock.Time
instance GHC.Enum.Bounded Core.Data.Clock.Time
instance GHC.Enum.Enum Core.Data.Clock.Time
instance GHC.Classes.Ord Core.Data.Clock.Time
instance GHC.Classes.Eq Core.Data.Clock.Time
instance Core.Data.Clock.Instant GHC.Int.Int64
instance Core.Data.Clock.Instant Data.Time.Clock.Internal.UTCTime.UTCTime
instance Core.Data.Clock.Instant Data.Time.Clock.Internal.POSIXTime.POSIXTime
instance Core.Data.Clock.Instant Time.Types.ElapsedP
instance Core.Data.Clock.Instant Data.Time.Calendar.Days.Day
instance GHC.Show.Show Core.Data.Clock.Time
instance GHC.Read.Read Core.Data.Clock.Time
instance Data.Aeson.Types.ToJSON.ToJSON Core.Data.Clock.Time
instance Data.Aeson.Types.FromJSON.FromJSON Core.Data.Clock.Time


-- | 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 ν

-- | Remove a key/value pair if present in the dictionary.
removeKeyValue :: Key κ => κ -> Map κ ν -> Map κ ν

-- | 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 K α :: Type;
    type V α :: Type;
}
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

-- | Remove an element from the collection if present.
removeElement :: Key ε => ε -> Set ε -> Set ε

-- | 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 E α :: Type;
}
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 Data.Bifoldable.Bifoldable Core.Data.Structures.Map
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.Conc.Sync.ThreadId
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


-- | Quite frequently you will find yourself needing to convert between a
--   rich semantic Haskell data type and a textual representation of that
--   type which we call the <i>external</i> representation of a value. The
--   external representation of the value is authoriative and is meant to
--   be re-readable even in the face of changing implemetations on the
--   program side.
--   
--   Note that <i>externalizing</i> is not quite the same as
--   <i>serializing</i>. If you have more complex data structures (ie rich
--   types or nesting) then a simple text string will probably not be
--   sufficient to convey sufficient information to represent it
--   accurately. Serializing is focused on both performance encoding and
--   decoding, and efficiency of the representation when transmitted over
--   the wire. Of course, the obvious benefits of efficiency didn't stop
--   the entire computer industry from near universal adoption of JSON as
--   an interchange format, so there is, perhaps, no hope for us.
--   
--   You can, however, regain some of your sanity by ensuring that the
--   individual fields of a larger structure are safe, and that's where the
--   externalizing machinery in this module comes in.
--   
--   If you have read this far and think we are describing something
--   similar to Haskell's <a>Show</a>, Python's <tt>repr()</tt> or Java's
--   <tt>toString()</tt> you would be correct, but at the level of
--   primative and simple types we are providing the ability to marshall
--   them to a clean UTF-8 representation and to unmarshall them back into
--   Haskell values again.
--   
--   The other major use case for this module is as a helper to read user
--   input; see <a>queryOptionValue'</a> for an example that makes use of
--   this.
--   
--   <i>Notes for implementators</i>
--   
--   Postel's dictum to "be conservative in what you produce but liberal in
--   what you accept" describes the intent of this module. If you are
--   implementing an instance of <a>Externalize</a> then you might consider
--   being flexible as possible when parsing with <a>parseExternal</a>,
--   within the constraints of having to read a given value with exact
--   fidelity. But when outputing a value with <a>formatExternal</a> you
--   should be correcting the representation of the value to a canonical,
--   stable form, even if the original input was written differently. See
--   the discussion of creating <a>Time</a> types from varying inputs for
--   an example.
module Core.Encoding.External

-- | Convert between the internal Haskell representation of a data type and
--   an external, textual form suitable for visualization, onward
--   transmission, or archival storage.
--   
--   It is expected that a valid instance of <a>Externalize</a> allows you
--   to round-trip through it:
--   
--   <pre>
--   &gt;&gt;&gt; formatExternal (42 :: Int))
--   "42"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromJust (parseExternal "42") :: Int
--   42
--   </pre>
--   
--   with the usual caveat about needing to ensure you've given enough
--   information to the type-checker to know which instance you're asking
--   for.
--   
--   There is a general implementatation that goes though <a>Show</a> and
--   <a>Read</a> via <a>String</a> but if you know you have a direct way to
--   render or parse a type into a sequence of characters then you can
--   offer an instance of <a>Externalize</a> which does so more
--   efficiently.
class Externalize ξ

-- | Convert a value into an authoritative, stable textual representation
--   for use externally.
formatExternal :: Externalize ξ => ξ -> Rope

-- | Attempt to read an external textual representation into a Haskell
--   value.
parseExternal :: Externalize ξ => Rope -> Maybe ξ
instance (GHC.Read.Read a, GHC.Show.Show a) => Core.Encoding.External.Externalize a
instance Core.Encoding.External.Externalize Core.Text.Rope.Rope
instance Core.Encoding.External.Externalize GHC.Base.String
instance Core.Encoding.External.Externalize GHC.Types.Int
instance Core.Encoding.External.Externalize GHC.Int.Int8
instance Core.Encoding.External.Externalize GHC.Int.Int16
instance Core.Encoding.External.Externalize GHC.Int.Int32
instance Core.Encoding.External.Externalize GHC.Int.Int64
instance Core.Encoding.External.Externalize GHC.Word.Word8
instance Core.Encoding.External.Externalize GHC.Word.Word16
instance Core.Encoding.External.Externalize GHC.Word.Word32
instance Core.Encoding.External.Externalize GHC.Word.Word64
instance Core.Encoding.External.Externalize GHC.Types.Float
instance Core.Encoding.External.Externalize GHC.Types.Double
instance Core.Encoding.External.Externalize Data.UUID.Types.Internal.UUID
instance Core.Encoding.External.Externalize Core.Data.Clock.Time
instance Core.Encoding.External.Externalize Data.Time.Calendar.Days.Day
instance Core.Encoding.External.Externalize Data.Scientific.Scientific


-- | 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
instance Data.Aeson.Types.FromJSON.FromJSON Core.Text.Rope.Rope


-- | 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