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


-- | Tracable multi-source config management
--   
--   A library for handling multiple config files and keep track of where
--   config values came from.
--   
--   Config values can be read from json, yaml, or environment variables;
--   it is also possible to implement custom configuration sources via a
--   type class.
--   
--   Provenance of config values is tracked while reading them; an
--   application using this library can easily print a listing detailing
--   which files were read and which file provided (or failed to provide)
--   an individual value.
@package conftrack
@version 0.0.1

module Conftrack.Value

-- | to write values of <a>Key</a> easily
key :: QuasiQuoter

-- | A generic value read from a config source, to be parsed into a more
--   useful type (see the <a>ConfigValue</a> class).
data Value
ConfigString :: ByteString -> Value
ConfigInteger :: Integer -> Value

-- | A value which may be an integer, but the source cannot say for sure,
--   e.g. because its values are entirely untyped. Use <a>withString</a> to
--   handle such cases.
ConfigMaybeInteger :: ByteString -> Integer -> Value
ConfigOther :: Text -> Text -> Value
ConfigBool :: Bool -> Value
ConfigNull :: Value
data ConfigError
ParseError :: Text -> ConfigError
TypeMismatch :: Text -> Value -> ConfigError
NotPresent :: Key -> ConfigError
Shadowed :: ConfigError

-- | A configuration key is a non-empty list of parts. By convention, these
--   parts are separated by dots when written, although dots withing parts
--   are not disallowed.
--   
--   For writing values easily, consider enabling the <tt>QuasiQuotes</tt>
--   language extension to use <a>key</a>:
--   
--   <pre>
--   &gt;&gt;&gt; [key|foo.bar|]
--   foo.bar
--   </pre>
newtype Key
Key :: NonEmpty KeyPart -> Key

-- | Values which can be read from a config source must implement this
--   class
class ConfigValue a
fromConfig :: ConfigValue a => Value -> Either ConfigError a

-- | optionally, a function to pretty-print values of this type, used by
--   the functions of <a>Conftrack.Pretty</a>. If not given, defaults to
--   <tt>a</tt>'s <a>Show</a> instance.
prettyValue :: ConfigValue a => a -> Text

-- | optionally, a function to pretty-print values of this type, used by
--   the functions of <a>Conftrack.Pretty</a>. If not given, defaults to
--   <tt>a</tt>'s <a>Show</a> instance.
prettyValue :: (ConfigValue a, Show a) => a -> Text
data Origin
Origin :: a -> Text -> Origin
type KeyPart = Text
prefixedWith :: Key -> [KeyPart] -> Key
withString :: (ByteString -> Either ConfigError a) -> Value -> Either ConfigError a
instance GHC.Show.Show Conftrack.Value.Value
instance Language.Haskell.TH.Syntax.Lift Conftrack.Value.Key
instance GHC.Classes.Ord Conftrack.Value.Key
instance GHC.Classes.Eq Conftrack.Value.Key
instance GHC.Show.Show Conftrack.Value.ConfigError
instance GHC.Show.Show Conftrack.Value.Origin
instance Conftrack.Value.ConfigValue Data.Text.Internal.Text
instance Conftrack.Value.ConfigValue GHC.Num.Integer.Integer
instance Conftrack.Value.ConfigValue GHC.Types.Int
instance Conftrack.Value.ConfigValue GHC.Types.Bool
instance Conftrack.Value.ConfigValue a => Conftrack.Value.ConfigValue (GHC.Maybe.Maybe a)
instance Conftrack.Value.ConfigValue System.OsPath.Types.OsPath
instance Conftrack.Value.ConfigValue Data.ByteString.Lazy.Internal.ByteString
instance Conftrack.Value.ConfigValue Data.ByteString.Internal.Type.ByteString
instance GHC.Show.Show Conftrack.Value.Key

module Conftrack.Source

-- | An abstraction over "config sources". This might mean file formats,
--   environment variables, or any other kind of format that can be seen as
--   a key-value store.
class ConfigSource s where {
    
    -- | Some sources require state, e.g. to keep track of which values were
    --   already read.
    type SourceState s;
}

-- | read a single value from the source.
fetchValue :: ConfigSource s => Key -> s -> StateT (SourceState s) IO (Either ConfigError (Value, Text))

-- | given <tt>s</tt>, determine if any keys are "left over" and were not
--   used. This is used to produce warnings for unknown configuration
--   options; since not all sources can support this, this function's
--   return type includes <tt>Maybe</tt> and sources are free to return
--   <tt>Nothing</tt> if they cannot determine if any unknown keys are
--   present.
leftovers :: ConfigSource s => s -> StateT (SourceState s) IO (Maybe [Key])

-- | An opaque type for any kind of config sources. Values of this type can
--   be acquired from they <tt>Conftrack.Source.*</tt> modules, or by
--   implementing the <a>ConfigSource</a> type class.
data SomeSource
SomeSource :: (source, SourceState source) -> SomeSource


-- | A trivial source reading from a <tt>Map Key Value</tt>, only useful as
--   a demonstration or for tests.
module Conftrack.Source.Trivial
newtype Trivial
Trivial :: Map Key Value -> Trivial
mkTrivialSource :: [(Key, Value)] -> SomeSource
instance Conftrack.Source.ConfigSource Conftrack.Source.Trivial.Trivial

module Conftrack.Source.Env
data EnvSource
EnvSource :: (Key -> OsString) -> Text -> EnvSource
[envSourceModifier] :: EnvSource -> Key -> OsString
[envSourceDescription] :: EnvSource -> Text
mkEnvSource :: Text -> SomeSource
instance GHC.Show.Show Conftrack.Source.Env.EnvSource
instance Conftrack.Source.ConfigSource Conftrack.Source.Env.EnvSource


-- | Functions for producing sources reading from json strings or files,
--   using the aeson library.
module Conftrack.Source.Aeson

-- | Make a source from an aeson value
mkJsonSource :: Value -> SomeSource

-- | same as <a>mkJsonSource</a>, but with an additional description to be
--   shown in output of <a>printConfigOrigins</a>.
mkJsonSourceWith :: Text -> Value -> SomeSource

-- | Make a source from a json file.
mkJsonFileSource :: OsPath -> IO (Maybe SomeSource)
data JsonSource
JsonSource :: Value -> Text -> JsonSource
[jsonSourceValue] :: JsonSource -> Value
[jsonSourceDescription] :: JsonSource -> Text
instance GHC.Show.Show Conftrack.Source.Aeson.JsonSource
instance Conftrack.Source.ConfigSource Conftrack.Source.Aeson.JsonSource


-- | Functions for producing sources reading from yaml strings or files,
--   using the aeson library.
module Conftrack.Source.Yaml
newtype YamlSource
YamlSource :: JsonSource -> YamlSource
mkYamlSource :: Value -> SomeSource
mkYamlSourceWith :: Text -> Value -> SomeSource
mkYamlFileSource :: OsPath -> IO (Either ParseException SomeSource)
instance GHC.Show.Show Conftrack.Source.Yaml.YamlSource
instance Conftrack.Source.ConfigSource Conftrack.Source.Yaml.YamlSource


-- | A typeclass-based library for reading in configuration values from
--   multiple sources, attempting to be simple, avoid unecessarily complex
--   types, and be able to track where each value came from.
module Conftrack

-- | A class to model configurations. See <a>Conftrack</a>'s documention
--   for a usage example
class Config a
readConfig :: Config a => Fetch a

-- | read in a config value, or give the given default value if it is not
--   present.
readValue :: forall a. ConfigValue a => a -> Key -> Fetch a

-- | read an optional config value, resulting in a <tt>Just</tt> if it is
--   present and a <tt>Nothing</tt> if it is not.
--   
--   This is distinct from using <a>readValue</a> to produce a value of
--   type <tt>Maybe a</tt>: the latter will require the key to be present,
--   but allow it to be <tt>null</tt> or similarly empty.
readOptionalValue :: forall a. ConfigValue a => Key -> Fetch (Maybe a)

-- | read in a config value, and produce an error if it is not present.
readRequiredValue :: ConfigValue a => Key -> Fetch a

-- | read a nested set of configuration values, prefixed by a given key.
--   This corresponds to nested objects in json.
readNested :: forall a. Config a => Key -> Fetch a

-- | same as <a>readNested</a>, but produce <tt>Nothing</tt> if the nested
--   keys are not present. This can be used for optionally configurable
--   sub-systems or similar constructs.
--   
--   If only some but not all keys of the nested configuration are given,
--   this will produce an error.
readNestedOptional :: forall a. (Show a, Config a) => Key -> Fetch (Maybe a)

-- | An opaque type for any kind of config sources. Values of this type can
--   be acquired from they <tt>Conftrack.Source.*</tt> modules, or by
--   implementing the <a>ConfigSource</a> type class.
data SomeSource
runFetchConfig :: forall a. Config a => NonEmpty SomeSource -> IO (Either [ConfigError] (a, Map Key [Origin], [Warning]))

-- | A value of type <tt>Fetch a</tt> can be used to read in a value
--   <tt>a</tt>, with configuration sources handled implicitly.
--   
--   Note that this is an instance of <a>Applicative</a> but not
--   <a>Monad</a>. In practical terms this means that values read from the
--   configuration sources cannot be inspected while reading the rest of
--   the config, and in particular which keys are read cannot depend on
--   another key's value. This allows for introspection functions like
--   <a>configKeysOf</a>.
--   
--   For configuration keys whose presence depends on each other, use
--   <a>readNestedOptional</a> to model similar behaviour.
data Fetch a

-- | A generic value read from a config source, to be parsed into a more
--   useful type (see the <a>ConfigValue</a> class).
data Value
ConfigString :: ByteString -> Value
ConfigInteger :: Integer -> Value

-- | A value which may be an integer, but the source cannot say for sure,
--   e.g. because its values are entirely untyped. Use <a>withString</a> to
--   handle such cases.
ConfigMaybeInteger :: ByteString -> Integer -> Value
ConfigOther :: Text -> Text -> Value
ConfigBool :: Bool -> Value
ConfigNull :: Value

-- | Values which can be read from a config source must implement this
--   class
class ConfigValue a
fromConfig :: ConfigValue a => Value -> Either ConfigError a

-- | optionally, a function to pretty-print values of this type, used by
--   the functions of <a>Conftrack.Pretty</a>. If not given, defaults to
--   <tt>a</tt>'s <a>Show</a> instance.
prettyValue :: ConfigValue a => a -> Text

-- | optionally, a function to pretty-print values of this type, used by
--   the functions of <a>Conftrack.Pretty</a>. If not given, defaults to
--   <tt>a</tt>'s <a>Show</a> instance.
prettyValue :: (ConfigValue a, Show a) => a -> Text

-- | A configuration key is a non-empty list of parts. By convention, these
--   parts are separated by dots when written, although dots withing parts
--   are not disallowed.
--   
--   For writing values easily, consider enabling the <tt>QuasiQuotes</tt>
--   language extension to use <a>key</a>:
--   
--   <pre>
--   &gt;&gt;&gt; [key|foo.bar|]
--   foo.bar
--   </pre>
newtype Key
Key :: NonEmpty KeyPart -> Key
newtype Warning
Warning :: Text -> Warning
data ConfigError
ParseError :: Text -> ConfigError
TypeMismatch :: Text -> Value -> ConfigError
NotPresent :: Key -> ConfigError
Shadowed :: ConfigError

-- | a list of all keys which will be read when running
--   <tt>runFetchConfig</tt> to produce a value of type <tt>a</tt>.
--   
--   This runs inside the <a>IO</a> monad, but does not do any actual IO.
configKeysOf :: forall a. Config a => IO [Key]

-- | to write values of <a>Key</a> easily
key :: QuasiQuoter
instance GHC.Show.Show Conftrack.Warning
instance GHC.Base.Functor Conftrack.Fetch
instance GHC.Base.Applicative Conftrack.Fetch


-- | This module contains convenience functions to print the values
--   returned by <a>runFetchConfig</a>.
--   
--   These functions can be used as-is in programs using this library, or
--   serve as examples for people who wish to display the results some
--   another way.
module Conftrack.Pretty

-- | A convenience function, to be <tt>&gt;&gt;=</tt>'d with
--   <a>runFetchConfig</a>.
--   
--   It prints any errors in case of failure and then aborts the program,
--   and prints any warnings (and, if the first argument is <tt>True</tt>,
--   also each value's origin) and returns the config in case of success.
unwrapConfigResult :: forall a. Config a => Bool -> Either [ConfigError] (a, Map Key [Origin], [Warning]) -> IO a
printConfigOrigins :: Map Key [Origin] -> IO ()
printConfigWarnings :: [Warning] -> IO ()
printConfigErrors :: [ConfigError] -> IO ()
displayError :: ConfigError -> Text