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


-- | Configuration management library
--   
--   Library to abstract the parsing of many haskell config values from
--   different config sources
@package conferer
@version 1.0.0.0


-- | Internal module for Key related features
module Conferer.Key.Internal

-- | This type is used extensivelly as a way to point into a <a>Source</a>
--   and in turn into a <a>Config</a>. The intended way to create them is
--   is using <a>mkKey</a>.
--   
--   It's a list of alphanumeric words and each <a>Source</a> can interpret
--   it as it sees fit.
newtype Key
Key :: [Text] -> Key
[unKey] :: Key -> [Text]

-- | Helper function to create <a>Key</a>s, this function always works, but
--   since <a>Key</a>s reject some string this function transforms the
--   input to provide lawful <a>Key</a>s instead of throwing.
--   
--   For example:
--   
--   <pre>
--   'mkKey' "sOmE.KEy" == "some.key"
--   'mkKey' "1.key" == "1.key"
--   'mkKey' "1_thing.key" == "1thing.key"
--   'mkKey' "some....key" == "some.key"
--   'mkKey' ".." == ""
--   </pre>
mkKey :: String -> Key

-- | Same as <a>mkKey</a> but for <a>Text</a>
fromText :: Text -> Key

-- | Collapse a key into a textual representation
keyName :: Key -> Text

-- | This function tells if a key is a subkey of another key based using
--   key fragments instead of letters as units
--   
--   <pre>
--   'isKeyPrefixOf' "foo" "foo.bar" == True
--   'isKeyPrefixOf' "foo" "foo" == True
--   'isKeyPrefixOf' "foo" "fooa" == False
--   </pre>
isKeyPrefixOf :: Key -> Key -> Bool

-- | Given k1 and k2 this function drops k1 as a prefix from k2, if k1 is
--   not a prefix of k2 it returns <a>Nothing</a>
--   
--   <pre>
--   'keyPrefixOf' "foo" "foo.bar" == Just "bar"
--   'keyPrefixOf' "foo" "foo" == Just ""
--   'keyPrefixOf' "foo" "fooa" == Nothing
--   'keyPrefixOf' "" k == Just k
--   </pre>
stripKeyPrefix :: Key -> Key -> Maybe Key

-- | Concatenate two keys
(/.) :: Key -> Key -> Key

-- | Get raw components from a key, usually to do some manipulation
rawKeyComponents :: Key -> [Text]

-- | Get first component of a key and the rest of the key
unconsKey :: Key -> Maybe (Text, Key)
instance GHC.Classes.Ord Conferer.Key.Internal.Key
instance GHC.Classes.Eq Conferer.Key.Internal.Key
instance GHC.Show.Show Conferer.Key.Internal.Key
instance Data.String.IsString Conferer.Key.Internal.Key


-- | Public API for Key related features
module Conferer.Key

-- | This type is used extensivelly as a way to point into a <a>Source</a>
--   and in turn into a <a>Config</a>. The intended way to create them is
--   is using <a>mkKey</a>.
--   
--   It's a list of alphanumeric words and each <a>Source</a> can interpret
--   it as it sees fit.
data Key

-- | Helper function to create <a>Key</a>s, this function always works, but
--   since <a>Key</a>s reject some string this function transforms the
--   input to provide lawful <a>Key</a>s instead of throwing.
--   
--   For example:
--   
--   <pre>
--   'mkKey' "sOmE.KEy" == "some.key"
--   'mkKey' "1.key" == "1.key"
--   'mkKey' "1_thing.key" == "1thing.key"
--   'mkKey' "some....key" == "some.key"
--   'mkKey' ".." == ""
--   </pre>
mkKey :: String -> Key

-- | Same as <a>mkKey</a> but for <a>Text</a>
fromText :: Text -> Key

-- | Concatenate two keys
(/.) :: Key -> Key -> Key

-- | Given k1 and k2 this function drops k1 as a prefix from k2, if k1 is
--   not a prefix of k2 it returns <a>Nothing</a>
--   
--   <pre>
--   'keyPrefixOf' "foo" "foo.bar" == Just "bar"
--   'keyPrefixOf' "foo" "foo" == Just ""
--   'keyPrefixOf' "foo" "fooa" == Nothing
--   'keyPrefixOf' "" k == Just k
--   </pre>
stripKeyPrefix :: Key -> Key -> Maybe Key

-- | This function tells if a key is a subkey of another key based using
--   key fragments instead of letters as units
--   
--   <pre>
--   'isKeyPrefixOf' "foo" "foo.bar" == True
--   'isKeyPrefixOf' "foo" "foo" == True
--   'isKeyPrefixOf' "foo" "fooa" == False
--   </pre>
isKeyPrefixOf :: Key -> Key -> Bool

-- | Get raw components from a key, usually to do some manipulation
rawKeyComponents :: Key -> [Text]

-- | Get first component of a key and the rest of the key
unconsKey :: Key -> Maybe (Text, Key)


-- | Internal module for Key related features
module Conferer.Source.Internal

-- | Concrete type for <a>IsSource</a>
data Source
Source :: s -> Source

-- | Main interface for interacting with external systems that provide
--   configuration which will be used by <a>FromConfig</a> to fetch values.
class IsSource s

-- | This function is used by the <a>Config</a> to get values from this
--   <a>Source</a>.
getKeyInSource :: IsSource s => s -> Key -> IO (Maybe Text)

-- | This function is used by the <a>Config</a> to list possible values
--   from the <a>Source</a> that if the user <a>getKeyInSource</a>, it will
--   be found.
getSubkeysInSource :: IsSource s => s -> Key -> IO [Key]
instance GHC.Show.Show Conferer.Source.Internal.Source
instance Conferer.Source.Internal.IsSource Conferer.Source.Internal.Source


-- | Core types for Config (here because of depedency cycles)
module Conferer.Config.Internal.Types

-- | This type acts as the entry point for most of the library, it's main
--   purpouse is to expose a uniform interface into multiple configuration
--   sources (such as env vars, cli args, and many others including use
--   defined ones using the <a>Source</a> interface)
data Config
Config :: [Source] -> Map Key Dynamic -> [(Key, Key)] -> Config
[configSources] :: Config -> [Source]
[configDefaults] :: Config -> Map Key Dynamic
[configKeyMappings] :: Config -> [(Key, Key)]

-- | Result of a key lookup in a <a>Config</a>
data KeyLookupResult
MissingKey :: [Key] -> KeyLookupResult
FoundInSources :: Key -> Text -> KeyLookupResult
FoundInDefaults :: Key -> Dynamic -> KeyLookupResult

-- | The type for creating a source given a <a>Config</a>, some sources
--   require a certain configuration to be initialized (for example: the
--   redis source needs connection info to connect to the server)
type SourceCreator = Config -> IO Source
instance GHC.Show.Show Conferer.Config.Internal.Types.Config
instance GHC.Show.Show Conferer.Config.Internal.Types.KeyLookupResult


-- | Public API module for Source related features
module Conferer.Source

-- | Concrete type for <a>IsSource</a>
data Source
Source :: s -> Source

-- | Main interface for interacting with external systems that provide
--   configuration which will be used by <a>FromConfig</a> to fetch values.
class IsSource s

-- | This function is used by the <a>Config</a> to get values from this
--   <a>Source</a>.
getKeyInSource :: IsSource s => s -> Key -> IO (Maybe Text)

-- | This function is used by the <a>Config</a> to list possible values
--   from the <a>Source</a> that if the user <a>getKeyInSource</a>, it will
--   be found.
getSubkeysInSource :: IsSource s => s -> Key -> IO [Key]

-- | The type for creating a source given a <a>Config</a>, some sources
--   require a certain configuration to be initialized (for example: the
--   redis source needs connection info to connect to the server)
type SourceCreator = Config -> IO Source


-- | In memory source mostly used for testing
module Conferer.Source.InMemory

-- | A <a>Source</a> mostly use for mocking which is configured directly
--   using a <a>Map</a>
newtype InMemorySource
InMemorySource :: Map Key Text -> InMemorySource
[configMap] :: InMemorySource -> Map Key Text

-- | Create a <a>SourceCreator</a> from a list of associations
fromConfig :: [(Key, Text)] -> SourceCreator

-- | Create a <a>Source</a> from a <a>Map</a>
fromMap :: Map Key Text -> Source

-- | Create a <a>Source</a> from a list of associations
fromAssociations :: [(Key, Text)] -> Source
instance GHC.Classes.Eq Conferer.Source.InMemory.InMemorySource
instance GHC.Show.Show Conferer.Source.InMemory.InMemorySource
instance Conferer.Source.Internal.IsSource Conferer.Source.InMemory.InMemorySource


-- | Environment based source
module Conferer.Source.Env

-- | Source that interfaces with the environment transforming keys by
--   uppercasing and interspersing underscores, and using a prefix to avoid
--   clashing with system env vars
--   
--   so with "app" prefix, <tt>"some.key"</tt> turns into
--   <tt>APP_SOME_KEY</tt>
data EnvSource
EnvSource :: RawEnvironment -> Prefix -> Source -> EnvSource
[environment] :: EnvSource -> RawEnvironment
[keyPrefix] :: EnvSource -> Prefix
[innerSource] :: EnvSource -> Source

-- | Type alias for the environment
type RawEnvironment = [(String, String)]

-- | Type alias for the env vars prefix
type Prefix = Text

-- | Create a <a>SourceCreator</a> using <a>fromEnv</a>
fromConfig :: Prefix -> SourceCreator

-- | Create a <a>Source</a> using the real environment
fromEnv :: Prefix -> IO Source

-- | Create a <a>Source</a> using a hardcoded list of env vars
fromEnvList :: RawEnvironment -> Prefix -> Source

-- | Get the env name from a prefix and a key by uppercasing and
--   intercalating underscores
keyToEnvVar :: Prefix -> Key -> Text

-- | The opossite of <a>keyToEnvVar</a>
envVarToKey :: Prefix -> Text -> Maybe Key
instance GHC.Show.Show Conferer.Source.Env.EnvSource
instance Conferer.Source.Internal.IsSource Conferer.Source.Env.EnvSource


-- | Command line arguments based source
module Conferer.Source.CLIArgs

-- | This source provides keys from the command line arguments passed into
--   the program. It only accepts arguments with <tt>--</tt> and an equals,
--   for example: <tt>./awesomeapp --warp.port=5000</tt>
data CLIArgsSource
CLIArgsSource :: RawCLIArgs -> Source -> CLIArgsSource
[originalCliArgs] :: CLIArgsSource -> RawCLIArgs
[innerSource] :: CLIArgsSource -> Source

-- | Type alias for cli args
type RawCLIArgs = [String]

-- | Create a <a>SourceCreator</a> using <a>fromEnv</a>
fromConfig :: SourceCreator

-- | Create a <a>Source</a> using <a>fromArgs</a> but using real cli args
fromEnv :: IO Source

-- | Create a <a>Source</a> using cli args passed as parameter
fromArgs :: RawCLIArgs -> Source

-- | Parse an argument list into a dictionary suitable for a <a>Source</a>
parseArgsIntoKeyValue :: [String] -> [(Key, Text)]
instance GHC.Show.Show Conferer.Source.CLIArgs.CLIArgsSource
instance Conferer.Source.Internal.IsSource Conferer.Source.CLIArgs.CLIArgsSource


-- | Internal module providing Config functionality
module Conferer.Config.Internal

-- | This function runs lookups on the <a>Config</a>, first in
--   <a>Source</a>s in order and then on the <a>Dynamic</a> based defaults.
getKey :: Key -> Config -> IO KeyLookupResult

-- | Alias for a mapping from one key to another used for transforming keys
type KeyMapping = (Key, Key)

-- | A key that has been transformed using one or many <a>KeyMapping</a>s,
--   so that that process can be reversed.
data MappedKey
MappedKey :: [KeyMapping] -> Key -> MappedKey
[mappingsChain] :: MappedKey -> [KeyMapping]
[mappedKey] :: MappedKey -> Key

-- | This function lists all available keys under some key, that could be
--   fetched successfully.
listSubkeys :: Key -> Config -> IO [Key]

-- | This function lists subkeys in some <a>Source</a>s and combines the
--   results
listRawSubkeysInSources :: Key -> [Source] -> IO [Key]

-- | This function reverses the mappings in a <a>MappedKey</a> to retrieve
--   the original key.
--   
--   Assumes that mappings were really used, otherwise it ignores bad
--   values
undoMappings :: MappedKey -> Key

-- | This utility function run a list of IO actions and returns the first
--   that return a <a>Just</a>, if no one does, returns <a>Nothing</a>
untilJust :: [IO (Maybe a)] -> IO (Maybe a)

-- | This function tries to apply a list of mappings to a key meaning
--   replace the prefix with the new value from the mapping, if the mapping
--   isn't a prefix that mapping is ignored
--   
--   This function always terminates even in presence of recursive
--   mappings, since it removes the mapping after it was first used, and
--   that causes that eventually the function will run out of keymappings
--   and terminate.
getKeysFromMappings :: [KeyMapping] -> Key -> [MappedKey]

-- | This utility function splits a list based on a <tt>cond</tt> function
--   and returns a tuple of previous value, next values and the mapped
--   found value.
findAndSplitList :: forall a b. (a -> Maybe b) -> [a] -> [([a], b, [a])]

-- | This function gets a value from <a>Source</a>s but ignores mappings
--   and defaults
getRawKeyInSources :: Key -> Config -> IO (Maybe (Key, Text))

-- | This function gets values from the defaults
getKeyFromDefaults :: Key -> Config -> Maybe Dynamic

-- | The empty configuration, this <a>Config</a> is used as the base for
--   most config creating functions.
emptyConfig :: Config

-- | This function adds some key mappings to a <a>Config</a>
addKeyMappings :: [KeyMapping] -> Config -> Config

-- | This function adds defaults to a <a>Config</a>
addDefaults :: [(Key, Dynamic)] -> Config -> Config

-- | This function adds one default of a custom type to a <a>Config</a>
--   
--   Note that unlike <a>addDefaults</a> this function does the toDyn so no
--   need to do it on the user's side
addDefault :: Typeable a => Key -> a -> Config -> Config

-- | This function removes a key default from a <a>Config</a>
removeDefault :: Key -> Config -> Config

-- | Instantiate a <a>Source</a> using an <a>SourceCreator</a> and a
--   <a>Config</a> and add to the config
addSource :: SourceCreator -> Config -> IO Config
instance GHC.Classes.Eq Conferer.Config.Internal.MappedKey
instance GHC.Show.Show Conferer.Config.Internal.MappedKey


-- | Internal module providing FromConfig functionality
module Conferer.FromConfig.Internal

-- | The typeclass for defining the way to get values from a <a>Config</a>,
--   hiding the <a>Text</a> based nature of the <a>Source</a>s and parse
--   whatever value as the types sees fit
--   
--   Some of these instances are provided in different packages to avoid
--   the heavy dependencies.
--   
--   It provides a reasonable default using <a>Generic</a>s so most of the
--   time user need not to implement this typeclass.
class FromConfig a

-- | This function uses a <a>Config</a> and a scoping <a>Key</a> to get a
--   value.
--   
--   Some conventions:
--   
--   <ul>
--   <li>When some <a>Key</a> is missing this function should throw
--   <a>MissingRequiredKey</a></li>
--   <li>For any t it should hold that <tt>fetchFromConfig k (config &amp;
--   addDefault k t) == t</tt> meaning that a default on the same key with
--   the right type should be used as a default and with no configuration
--   that value should be returned</li>
--   <li>Try desconstructing the value in as many keys as possible since is
--   allows easier partial overriding.</li>
--   </ul>
fetchFromConfig :: FromConfig a => Key -> Config -> IO a

-- | This function uses a <a>Config</a> and a scoping <a>Key</a> to get a
--   value.
--   
--   Some conventions:
--   
--   <ul>
--   <li>When some <a>Key</a> is missing this function should throw
--   <a>MissingRequiredKey</a></li>
--   <li>For any t it should hold that <tt>fetchFromConfig k (config &amp;
--   addDefault k t) == t</tt> meaning that a default on the same key with
--   the right type should be used as a default and with no configuration
--   that value should be returned</li>
--   <li>Try desconstructing the value in as many keys as possible since is
--   allows easier partial overriding.</li>
--   </ul>
fetchFromConfig :: (FromConfig a, Typeable a, Generic a, IntoDefaultsG (Rep a), FromConfigG (Rep a)) => Key -> Config -> IO a

-- | Utility only typeclass to smooth the naming differences between
--   default values for external library settings
--   
--   This typeclass is not used internally it's only here for convinience
--   for users
class DefaultConfig a
configDef :: DefaultConfig a => a

-- | A newtype wrapper for a <a>FilePath</a> to allow implementing
--   <a>FromConfig</a> with something better than just a <a>String</a>
newtype File
File :: FilePath -> File

-- | Helper function to parse a <a>Bool</a> from <a>Text</a>
parseBool :: Text -> Maybe Bool

-- | Helper function to implement fetchFromConfig using the <a>Read</a>
--   instance
fetchFromConfigByRead :: (Typeable a, Read a) => Key -> Config -> IO a

-- | Helper function to implement fetchFromConfig using the <a>IsString</a>
--   instance
fetchFromConfigByIsString :: (Typeable a, IsString a) => Key -> Config -> IO a

-- | Helper function to implement fetchFromConfig using some parsing
--   function
fetchFromConfigWith :: forall a. Typeable a => (Text -> Maybe a) -> Key -> Config -> IO a

-- | Helper function does the plumbing of desconstructing a default into
--   smaller defaults, which is usefull for nested <a>fetchFromConfig</a>.
addDefaultsAfterDeconstructingToDefaults :: forall a. Typeable a => (a -> [(Key, Dynamic)]) -> Key -> Config -> IO Config

-- | Exception to show that a value couldn't be parsed properly
data ConfigParsingError
ConfigParsingError :: Key -> Text -> TypeRep -> ConfigParsingError

-- | Helper function to throw <a>ConfigParsingError</a>
throwConfigParsingError :: forall a b. Typeable a => Key -> Text -> IO b

-- | Helper function to create a <a>ConfigParsingError</a>
configParsingError :: forall a. Typeable a => Key -> Text -> ConfigParsingError

-- | Exception to show that some non optional <a>Key</a> was missing while
--   trying to <a>fetchFromConfig</a>
data MissingRequiredKey
MissingRequiredKey :: [Key] -> TypeRep -> MissingRequiredKey

-- | Simplified helper function to throw a <a>MissingRequiredKey</a>
throwMissingRequiredKey :: forall t a. Typeable t => Key -> IO a

-- | Simplified helper function to create a <a>MissingRequiredKey</a>
missingRequiredKey :: forall t. Typeable t => Key -> MissingRequiredKey

-- | Helper function to throw a <a>MissingRequiredKey</a>
throwMissingRequiredKeys :: forall t a. Typeable t => [Key] -> IO a

-- | Helper function to create a <a>MissingRequiredKey</a>
missingRequiredKeys :: forall a. Typeable a => [Key] -> MissingRequiredKey

-- | Exception to show that the provided default had the wrong type, this
--   is usually a programmer error and a user that configures the library
--   can not do much to fix it.
data TypeMismatchWithDefault
TypeMismatchWithDefault :: Key -> Dynamic -> TypeRep -> TypeMismatchWithDefault

-- | Helper function to throw a <a>TypeMismatchWithDefault</a>
throwTypeMismatchWithDefault :: forall a b. Typeable a => Key -> Dynamic -> IO b

-- | Helper function to create a <a>TypeMismatchWithDefault</a>
typeMismatchWithDefault :: forall a. Typeable a => Key -> Dynamic -> TypeMismatchWithDefault

-- | Fetch from value from the defaults map of a <a>Config</a> or else
--   throw
fetchRequiredFromDefaults :: forall a. Typeable a => Key -> Config -> IO a

-- | Fetch from value from the defaults map of a <a>Config</a> or else
--   return a <a>Nothing</a>
fetchFromDefaults :: forall a. Typeable a => Key -> Config -> IO (Maybe a)

-- | Same as <a>fetchFromConfig</a> using the root key
fetchFromRootConfig :: forall a. FromConfig a => Config -> IO a

-- | Same as <a>fetchFromConfig</a> but adding a user defined default
--   before <a>fetchFromConfig</a>ing so it doesn't throw a MissingKeyError
fetchFromConfigWithDefault :: forall a. (Typeable a, FromConfig a) => Config -> Key -> a -> IO a

-- | Same as <a>fetchFromConfigWithDefault</a> using the root key
fetchFromRootConfigWithDefault :: forall a. (Typeable a, FromConfig a) => Config -> a -> IO a

-- | Purely <a>Generic</a>s machinery, ignore...
class FromConfigG f
fetchFromConfigG :: FromConfigG f => Key -> Config -> IO (f a)

-- | Purely <a>Generic</a>s machinery, ignore...
class FromConfigWithConNameG f
fetchFromConfigWithConNameG :: FromConfigWithConNameG f => String -> Key -> Config -> IO (f a)

-- | Purely <a>Generic</a>s machinery, ignore...
class IntoDefaultsG f
intoDefaultsG :: IntoDefaultsG f => Key -> f a -> [(Key, Dynamic)]

-- | Purely <a>Generic</a>s machinery, ignore...
class IntoDefaultsWithConNameG f
intoDefaultsWithConNameG :: IntoDefaultsWithConNameG f => String -> Key -> f a -> [(Key, Dynamic)]
instance GHC.Read.Read Conferer.FromConfig.Internal.File
instance GHC.Classes.Ord Conferer.FromConfig.Internal.File
instance GHC.Classes.Eq Conferer.FromConfig.Internal.File
instance GHC.Show.Show Conferer.FromConfig.Internal.File
instance GHC.Classes.Eq Conferer.FromConfig.Internal.ConfigParsingError
instance GHC.Classes.Eq Conferer.FromConfig.Internal.MissingRequiredKey
instance (Conferer.FromConfig.Internal.IntoDefaultsWithConNameG inner, GHC.Generics.Constructor constructor) => Conferer.FromConfig.Internal.IntoDefaultsG (GHC.Generics.C1 constructor inner)
instance (Conferer.FromConfig.Internal.IntoDefaultsWithConNameG left, Conferer.FromConfig.Internal.IntoDefaultsWithConNameG right) => Conferer.FromConfig.Internal.IntoDefaultsWithConNameG (left GHC.Generics.:*: right)
instance (Conferer.FromConfig.Internal.IntoDefaultsG inner, GHC.Generics.Selector selector) => Conferer.FromConfig.Internal.IntoDefaultsWithConNameG (GHC.Generics.S1 selector inner)
instance Data.Typeable.Internal.Typeable a => Conferer.FromConfig.Internal.FromConfig a
instance Conferer.FromConfig.Internal.FromConfig ()
instance Conferer.FromConfig.Internal.FromConfig GHC.Base.String
instance (Data.Typeable.Internal.Typeable a, Conferer.FromConfig.Internal.FromConfig a) => Conferer.FromConfig.Internal.FromConfig [a]
instance Conferer.FromConfig.Internal.FromConfig GHC.Types.Int
instance Conferer.FromConfig.Internal.FromConfig GHC.Integer.Type.Integer
instance Conferer.FromConfig.Internal.FromConfig GHC.Types.Float
instance Conferer.FromConfig.Internal.FromConfig Data.ByteString.Internal.ByteString
instance Conferer.FromConfig.Internal.FromConfig Data.ByteString.Lazy.Internal.ByteString
instance (Data.Typeable.Internal.Typeable a, Conferer.FromConfig.Internal.FromConfig a) => Conferer.FromConfig.Internal.FromConfig (GHC.Maybe.Maybe a)
instance Conferer.FromConfig.Internal.FromConfig Data.Text.Internal.Text
instance Conferer.FromConfig.Internal.FromConfig GHC.Types.Bool
instance Conferer.FromConfig.Internal.FromConfig Conferer.FromConfig.Internal.File
instance Conferer.FromConfig.Internal.FromConfig inner => Conferer.FromConfig.Internal.FromConfigG (GHC.Generics.Rec0 inner)
instance Conferer.FromConfig.Internal.IntoDefaultsG inner => Conferer.FromConfig.Internal.IntoDefaultsG (GHC.Generics.D1 metadata inner)
instance Data.Typeable.Internal.Typeable inner => Conferer.FromConfig.Internal.IntoDefaultsG (GHC.Generics.Rec0 inner)
instance (Conferer.FromConfig.Internal.FromConfigWithConNameG inner, GHC.Generics.Constructor constructor) => Conferer.FromConfig.Internal.FromConfigG (GHC.Generics.C1 constructor inner)
instance (Conferer.FromConfig.Internal.FromConfigWithConNameG left, Conferer.FromConfig.Internal.FromConfigWithConNameG right) => Conferer.FromConfig.Internal.FromConfigWithConNameG (left GHC.Generics.:*: right)
instance (Conferer.FromConfig.Internal.FromConfigG inner, GHC.Generics.Selector selector) => Conferer.FromConfig.Internal.FromConfigWithConNameG (GHC.Generics.S1 selector inner)
instance Conferer.FromConfig.Internal.FromConfigG inner => Conferer.FromConfig.Internal.FromConfigG (GHC.Generics.D1 metadata inner)
instance GHC.Classes.Eq Conferer.FromConfig.Internal.TypeMismatchWithDefault
instance GHC.Exception.Type.Exception Conferer.FromConfig.Internal.TypeMismatchWithDefault
instance GHC.Show.Show Conferer.FromConfig.Internal.TypeMismatchWithDefault
instance GHC.Exception.Type.Exception Conferer.FromConfig.Internal.MissingRequiredKey
instance GHC.Show.Show Conferer.FromConfig.Internal.MissingRequiredKey
instance GHC.Exception.Type.Exception Conferer.FromConfig.Internal.ConfigParsingError
instance GHC.Show.Show Conferer.FromConfig.Internal.ConfigParsingError
instance Data.String.IsString Conferer.FromConfig.Internal.File


-- | Public API module providing FromConfig functionality
module Conferer.FromConfig

-- | The typeclass for defining the way to get values from a <a>Config</a>,
--   hiding the <a>Text</a> based nature of the <a>Source</a>s and parse
--   whatever value as the types sees fit
--   
--   Some of these instances are provided in different packages to avoid
--   the heavy dependencies.
--   
--   It provides a reasonable default using <a>Generic</a>s so most of the
--   time user need not to implement this typeclass.
class FromConfig a

-- | This function uses a <a>Config</a> and a scoping <a>Key</a> to get a
--   value.
--   
--   Some conventions:
--   
--   <ul>
--   <li>When some <a>Key</a> is missing this function should throw
--   <a>MissingRequiredKey</a></li>
--   <li>For any t it should hold that <tt>fetchFromConfig k (config &amp;
--   addDefault k t) == t</tt> meaning that a default on the same key with
--   the right type should be used as a default and with no configuration
--   that value should be returned</li>
--   <li>Try desconstructing the value in as many keys as possible since is
--   allows easier partial overriding.</li>
--   </ul>
fetchFromConfig :: FromConfig a => Key -> Config -> IO a

-- | This function uses a <a>Config</a> and a scoping <a>Key</a> to get a
--   value.
--   
--   Some conventions:
--   
--   <ul>
--   <li>When some <a>Key</a> is missing this function should throw
--   <a>MissingRequiredKey</a></li>
--   <li>For any t it should hold that <tt>fetchFromConfig k (config &amp;
--   addDefault k t) == t</tt> meaning that a default on the same key with
--   the right type should be used as a default and with no configuration
--   that value should be returned</li>
--   <li>Try desconstructing the value in as many keys as possible since is
--   allows easier partial overriding.</li>
--   </ul>
fetchFromConfig :: (FromConfig a, Typeable a, Generic a, IntoDefaultsG (Rep a), FromConfigG (Rep a)) => Key -> Config -> IO a

-- | Utility only typeclass to smooth the naming differences between
--   default values for external library settings
--   
--   This typeclass is not used internally it's only here for convinience
--   for users
class DefaultConfig a
configDef :: DefaultConfig a => a

-- | Same as <a>fetchFromConfig</a> but adding a user defined default
--   before <a>fetchFromConfig</a>ing so it doesn't throw a MissingKeyError
fetchFromConfigWithDefault :: forall a. (Typeable a, FromConfig a) => Config -> Key -> a -> IO a

-- | Same as <a>fetchFromConfig</a> using the root key
fetchFromRootConfig :: forall a. FromConfig a => Config -> IO a

-- | Same as <a>fetchFromConfigWithDefault</a> using the root key
fetchFromRootConfigWithDefault :: forall a. (Typeable a, FromConfig a) => Config -> a -> IO a

-- | Helper function to implement fetchFromConfig using the <a>IsString</a>
--   instance
fetchFromConfigByIsString :: (Typeable a, IsString a) => Key -> Config -> IO a

-- | Helper function to implement fetchFromConfig using the <a>Read</a>
--   instance
fetchFromConfigByRead :: (Typeable a, Read a) => Key -> Config -> IO a

-- | Helper function to implement fetchFromConfig using some parsing
--   function
fetchFromConfigWith :: forall a. Typeable a => (Text -> Maybe a) -> Key -> Config -> IO a

-- | Helper function does the plumbing of desconstructing a default into
--   smaller defaults, which is usefull for nested <a>fetchFromConfig</a>.
addDefaultsAfterDeconstructingToDefaults :: forall a. Typeable a => (a -> [(Key, Dynamic)]) -> Key -> Config -> IO Config

-- | Exception to show that some non optional <a>Key</a> was missing while
--   trying to <a>fetchFromConfig</a>
data MissingRequiredKey

-- | Simplified helper function to throw a <a>MissingRequiredKey</a>
throwMissingRequiredKey :: forall t a. Typeable t => Key -> IO a

-- | Simplified helper function to create a <a>MissingRequiredKey</a>
missingRequiredKey :: forall t. Typeable t => Key -> MissingRequiredKey

-- | Exception to show that a value couldn't be parsed properly
data ConfigParsingError

-- | Helper function to throw <a>ConfigParsingError</a>
throwConfigParsingError :: forall a b. Typeable a => Key -> Text -> IO b

-- | Helper function to create a <a>ConfigParsingError</a>
configParsingError :: forall a. Typeable a => Key -> Text -> ConfigParsingError

-- | Exception to show that the provided default had the wrong type, this
--   is usually a programmer error and a user that configures the library
--   can not do much to fix it.
data TypeMismatchWithDefault

-- | Helper function to throw a <a>TypeMismatchWithDefault</a>
throwTypeMismatchWithDefault :: forall a b. Typeable a => Key -> Dynamic -> IO b

-- | Helper function to create a <a>TypeMismatchWithDefault</a>
typeMismatchWithDefault :: forall a. Typeable a => Key -> Dynamic -> TypeMismatchWithDefault

-- | This type is used extensivelly as a way to point into a <a>Source</a>
--   and in turn into a <a>Config</a>. The intended way to create them is
--   is using <a>mkKey</a>.
--   
--   It's a list of alphanumeric words and each <a>Source</a> can interpret
--   it as it sees fit.
data Key

-- | Concatenate two keys
(/.) :: Key -> Key -> Key

-- | A newtype wrapper for a <a>FilePath</a> to allow implementing
--   <a>FromConfig</a> with something better than just a <a>String</a>
newtype File
File :: FilePath -> File

-- | Result of a key lookup in a <a>Config</a>
data KeyLookupResult
MissingKey :: [Key] -> KeyLookupResult
FoundInSources :: Key -> Text -> KeyLookupResult
FoundInDefaults :: Key -> Dynamic -> KeyLookupResult

-- | Fetch from value from the defaults map of a <a>Config</a> or else
--   return a <a>Nothing</a>
fetchFromDefaults :: forall a. Typeable a => Key -> Config -> IO (Maybe a)

-- | Fetch from value from the defaults map of a <a>Config</a> or else
--   throw
fetchRequiredFromDefaults :: forall a. Typeable a => Key -> Config -> IO a


-- | Public API providing Config functionality
module Conferer.Config

-- | This type acts as the entry point for most of the library, it's main
--   purpouse is to expose a uniform interface into multiple configuration
--   sources (such as env vars, cli args, and many others including use
--   defined ones using the <a>Source</a> interface)
data Config

-- | This function runs lookups on the <a>Config</a>, first in
--   <a>Source</a>s in order and then on the <a>Dynamic</a> based defaults.
getKey :: Key -> Config -> IO KeyLookupResult

-- | Result of a key lookup in a <a>Config</a>
data KeyLookupResult
MissingKey :: [Key] -> KeyLookupResult
FoundInSources :: Key -> Text -> KeyLookupResult
FoundInDefaults :: Key -> Dynamic -> KeyLookupResult

-- | This function lists all available keys under some key, that could be
--   fetched successfully.
listSubkeys :: Key -> Config -> IO [Key]

-- | The empty configuration, this <a>Config</a> is used as the base for
--   most config creating functions.
emptyConfig :: Config

-- | Instantiate a <a>Source</a> using an <a>SourceCreator</a> and a
--   <a>Config</a> and add to the config
addSource :: SourceCreator -> Config -> IO Config

-- | This function adds one default of a custom type to a <a>Config</a>
--   
--   Note that unlike <a>addDefaults</a> this function does the toDyn so no
--   need to do it on the user's side
addDefault :: Typeable a => Key -> a -> Config -> Config

-- | This function adds defaults to a <a>Config</a>
addDefaults :: [(Key, Dynamic)] -> Config -> Config

-- | This function adds some key mappings to a <a>Config</a>
addKeyMappings :: [KeyMapping] -> Config -> Config

-- | <a>&amp;</a> is a reverse application operator. This provides
--   notational convenience. Its precedence is one higher than that of the
--   forward application operator <a>$</a>, which allows <a>&amp;</a> to be
--   nested in <a>$</a>.
--   
--   <pre>
--   &gt;&gt;&gt; 5 &amp; (+1) &amp; show
--   "6"
--   </pre>
(&) :: a -> (a -> b) -> b
infixl 1 &


-- | Public API module providing some helper functions related to files
module Conferer.Source.Files

-- | Helper function to get a file from the config specifying the extension
--   and using current env
getFilePathFromEnv :: Key -> String -> Config -> IO FilePath


-- | Source that namespaces an inner source
module Conferer.Source.Namespaced

-- | This source takes a source and returns a new source that always checks
--   that the <a>Key</a> given always starts with certain <a>Key</a> and
--   then strips that prefix before consulting its inner Source
data NamespacedSource
NamespacedSource :: Key -> Source -> NamespacedSource
[scopeKey] :: NamespacedSource -> Key
[innerSource] :: NamespacedSource -> Source

-- | Create a <a>SourceCreator</a> from a prefix and another
--   <a>SourceCreator</a>
fromConfig :: Key -> SourceCreator -> SourceCreator

-- | Create a <a>Source</a> from a prefix and another <a>Source</a>
fromInner :: Key -> Source -> Source
instance GHC.Show.Show Conferer.Source.Namespaced.NamespacedSource
instance Conferer.Source.Internal.IsSource Conferer.Source.Namespaced.NamespacedSource


-- | Do nothing source
module Conferer.Source.Null

-- | Stub source that has no keys
data NullSource
NullSource :: NullSource

-- | Create <a>SourceCreator</a>
fromConfig :: SourceCreator

-- | Create a <a>Source</a>
empty :: Source
instance GHC.Classes.Eq Conferer.Source.Null.NullSource
instance GHC.Show.Show Conferer.Source.Null.NullSource
instance Conferer.Source.Internal.IsSource Conferer.Source.Null.NullSource


-- | Properties file source
module Conferer.Source.PropertiesFile

-- | <a>Source</a> that uses a config file in
--   <tt>config/{env}.properties</tt> and parses it as a properties file
--   with <tt>some.key=a value</tt> lines
data PropertiesFileSource
PropertiesFileSource :: FilePath -> Source -> PropertiesFileSource
[originalFilePath] :: PropertiesFileSource -> FilePath
[innerSource] :: PropertiesFileSource -> Source

-- | Create a <a>SourceCreator</a> using <a>getFilePathFromEnv</a> to get
--   the path to file and <a>fromFilePath</a>
fromConfig :: Key -> SourceCreator

-- | Create a <a>Source</a> reading the file and using that as a properties
--   file, but if the file doesn't exist do nothing.
fromFilePath :: FilePath -> IO Source

-- | Create a <a>Source</a> using some content as a properties file
fromFileContent :: FilePath -> Text -> Source

-- | Transform a line into a key/value pair (or not)
lineToKeyValue :: Text -> Maybe (Key, Text)
instance GHC.Show.Show Conferer.Source.PropertiesFile.PropertiesFileSource
instance Conferer.Source.Internal.IsSource Conferer.Source.PropertiesFile.PropertiesFileSource


-- | Public and stable API for the most basic usage of this library
module Conferer

-- | Create a <a>Config</a> which reads from command line arguments, env
--   vars and property files that depend on the environment
--   (<tt>config/development.properties</tt>) by default
mkConfig :: Text -> IO Config

-- | Use the <a>FromConfig</a> instance to get a value of type <tt>a</tt>
--   from the config using some default fallback. The most common use for
--   this is creating a custom record and using this function to fetch it
--   at initialization time.
--   
--   This function throws only parsing exceptions when the values are
--   present but malformed somehow (<tt>"abc"</tt> as an Int) but that
--   depends on the <a>FromConfig</a> implementation for the type.
fetch :: forall a. (FromConfig a, Typeable a, DefaultConfig a) => Config -> IO a

-- | Same as <a>fetch</a> but it accepts the default as a parameter instead
--   of using the default from <a>configDef</a>
fetch' :: forall a. (FromConfig a, Typeable a) => Config -> a -> IO a

-- | Same as <a>fetch'</a> but you can specify a <a>Key</a> instead of the
--   root key which allows you to fetch smaller values when you need them
--   instead of a big one at initialization time.
fetchKey :: forall a. (FromConfig a, Typeable a) => Config -> Key -> a -> IO a

-- | Same as <a>fetchKey</a> but it returns a <a>Nothing</a> when the value
--   isn't present
safeFetchKey :: forall a. (FromConfig a, Typeable a) => Config -> Key -> IO (Maybe a)

-- | Same as <a>fetchKey</a> but it throws when the value isn't present.
unsafeFetchKey :: forall a. FromConfig a => Config -> Key -> IO a

-- | Utility only typeclass to smooth the naming differences between
--   default values for external library settings
--   
--   This typeclass is not used internally it's only here for convinience
--   for users
class DefaultConfig a
configDef :: DefaultConfig a => a

-- | The typeclass for defining the way to get values from a <a>Config</a>,
--   hiding the <a>Text</a> based nature of the <a>Source</a>s and parse
--   whatever value as the types sees fit
--   
--   Some of these instances are provided in different packages to avoid
--   the heavy dependencies.
--   
--   It provides a reasonable default using <a>Generic</a>s so most of the
--   time user need not to implement this typeclass.
class FromConfig a

-- | This type acts as the entry point for most of the library, it's main
--   purpouse is to expose a uniform interface into multiple configuration
--   sources (such as env vars, cli args, and many others including use
--   defined ones using the <a>Source</a> interface)
data Config

-- | This type is used extensivelly as a way to point into a <a>Source</a>
--   and in turn into a <a>Config</a>. The intended way to create them is
--   is using <a>mkKey</a>.
--   
--   It's a list of alphanumeric words and each <a>Source</a> can interpret
--   it as it sees fit.
data Key


-- | Some testing utilities
module Conferer.Test

-- | Create a Config mostly used for testing <a>FromConfig</a> instances
--   without having to create a full config
configWith :: [(Key, Dynamic)] -> [(Key, Text)] -> IO Config