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

module Conferer.Types

-- | Core interface for library provided configuration, basically consists
--   of getting a <a>Key</a> and informing returning a maybe signaling the
--   value and if it's present in that specific provider
data Provider
Provider :: (Key -> IO (Maybe Text)) -> Provider
[getKeyInProvider] :: Provider -> Key -> IO (Maybe Text)

-- | The way to index <a>Provider</a>s, basically list of names that will
--   be adapted to whatever the provider needs
newtype Key
Path :: [Text] -> Key
[unKey] :: Key -> [Text]

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

-- | Core type that the user of this library interact with, in the future
--   it may contain more this besides a list of providers
data Config
Config :: [Provider] -> Map Key Text -> Config
[providers] :: Config -> [Provider]
[defaults] :: Config -> Map Key Text

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

-- | Main typeclass for defining the way to get values from config, hiding
--   the <a>Text</a> based nature of the <a>Provider</a>s
--   
--   Here a <a>Nothing</a> means that the value didn't appear in the
--   config, some instances never return a value since they have defaults
--   that can never fail
class FetchFromConfig a
fetch :: FetchFromConfig a => Key -> Config -> IO (Maybe a)
fetch :: (FetchFromConfig a, DefaultConfig a, UpdateFromConfig a) => Key -> Config -> IO (Maybe a)

-- | Here implementing this typeclass means that this type has some kind of
--   default that is both always valid and has always the same semantics,
--   for example: Warp.Settings has a default since it's always use in the
--   same way (to configure a warp server) but for example an Int could
--   mean many things depending on the context so it doesn't really make
--   sense to implement it for it
--   
--   It's also used for the <a>Generic</a> implementation, if you have a
--   Record made up from types that implement <a>FetchFromConfig</a> you
--   can derive the <a>FetchFromConfig</a> automatically by implementing
--   <a>DefaultConfig</a> and deriving (using <a>Generic</a>)
--   <a>UpdateFromConfig</a>
class DefaultConfig a
configDef :: DefaultConfig a => a

-- | This class only exist for the <tt>Generics</tt> machinery, it means
--   that a value can get updated using a config, so for example a
--   Warp.Settings can get updated from a config, but that doesn't make
--   much sense for something like an <a>Int</a>
--   
--   You'd normally would never implement this typeclass, if you want to
--   implement <a>FetchFromConfig</a> you should implement that directly,
--   and if you want to use <a>DefaultConfig</a> and
--   <a>UpdateFromConfig</a> to implement <a>FetchFromConfig</a> you should
--   let the default <tt>Generics</tt> based implementation do it's thing
class Typeable a => UpdateFromConfig a
updateFromConfig :: UpdateFromConfig a => Key -> Config -> a -> IO a
updateFromConfig :: (UpdateFromConfig a, Generic a, UpdateFromConfigG (Rep a), DefaultConfig a) => Key -> Config -> a -> IO a

-- | Purely <tt>Generics</tt> machinery, ignore...
class UpdateFromConfigG f
updateFromConfigG :: UpdateFromConfigG f => Key -> Config -> f a -> IO (f a)
data ConfigParsingError
ConfigParsingError :: Key -> Text -> TypeRep -> ConfigParsingError
data FailedToFetchError
FailedToFetchError :: Key -> TypeRep -> FailedToFetchError
instance GHC.Classes.Eq Conferer.Types.FailedToFetchError
instance GHC.Classes.Eq Conferer.Types.ConfigParsingError
instance GHC.Classes.Ord Conferer.Types.Key
instance GHC.Classes.Eq Conferer.Types.Key
instance GHC.Show.Show Conferer.Types.Key
instance GHC.Show.Show Conferer.Types.FailedToFetchError
instance GHC.Exception.Type.Exception Conferer.Types.FailedToFetchError
instance GHC.Show.Show Conferer.Types.ConfigParsingError
instance GHC.Exception.Type.Exception Conferer.Types.ConfigParsingError
instance Data.String.IsString Conferer.Types.Key

module Conferer.Provider.Simple

-- | Make a <a>Provider</a> from <tt>List</tt> of <a>Key</a>, <a>Text</a>
--   pairs
mkMapProvider :: [(Key, Text)] -> ProviderCreator

-- | Make a <a>ProviderCreator</a> from a <a>Map</a>
mkMapProvider' :: Map Key Text -> ProviderCreator

-- | Make a <a>Provider</a> from a <a>Map</a>
mkPureMapProvider :: Map Key Text -> Provider

module Conferer.Provider.Null

-- | Create a null <a>Provider</a>
mkNullProvider :: ProviderCreator

module Conferer.Provider.Namespaced

-- | Create a <a>ProviderCreator</a> from a prefix and another
--   <a>ProviderCreator</a>
mkNamespacedProvider :: Key -> ProviderCreator -> ProviderCreator

module Conferer.Provider.Mapping

-- | Create a <a>ProviderCreator</a> using a <a>Map</a> <a>Key</a>
--   <a>Key</a> to transform the supplied keys and another
--   <a>ProviderCreator</a>
mkMappingProvider :: Map Key Key -> ProviderCreator -> ProviderCreator

-- | Create a <a>ProviderCreator</a> using a function to transform the
--   supplied keys and another <a>ProviderCreator</a>
mkMappingProvider' :: (Key -> Maybe Key) -> ProviderCreator -> ProviderCreator

module Conferer.Provider.Env

-- | <a>ProviderCreator</a> for env <a>Provider</a> that uses the real
--   <a>lookupEnv</a> function
mkEnvProvider :: Prefix -> ProviderCreator

-- | <a>ProviderCreator</a> for env <a>Provider</a> that allows
--   parameterizing the function used to lookup for testing
mkEnvProvider' :: LookupEnvFunc -> Prefix -> ProviderCreator

-- | A text to namespace env vars
type Prefix = Text

-- | Type alias for the function to lookup env vars
type LookupEnvFunc = String -> IO (Maybe String)

-- | Get the env name from a prefix and a key by uppercasing and
--   intercalating underscores
--   
--   <pre>
--   &gt;&gt;&gt; keyToEnVar "awesomeapp" "warp.port"
--   "AWESOMEAPP_WARP_PORT"
--   </pre>
keyToEnvVar :: Prefix -> Key -> Text

module Conferer.Provider.CLIArgs

-- | Same as <a>mkCLIArgsProvider'</a> but using <a>getArgs</a> to provide
--   the argument list
mkCLIArgsProvider :: ProviderCreator

-- | Create a <a>ProviderCreator</a> for CLIArgs from a argument list
mkCLIArgsProvider' :: [String] -> ProviderCreator

-- | Parse an argument list into a dictionary suitable for a
--   <a>Provider</a>
parseArgsIntoKeyValue :: [String] -> [(Key, Text)]

module Conferer.Core

-- | Most Basic function to interact directly with a <a>Config</a>. It
--   always returns <a>Text</a> in the case of success and implements the
--   logic to traverse providers inside the <a>Config</a>.
getKey :: Key -> Config -> IO (Maybe Text)

-- | Fetch a value from a config key that's parsed using the
--   FetchFromConfig instance.
--   
--   This function throws an exception if the key is not found.
getFromConfig :: forall a. (Typeable a, FetchFromConfig a) => Key -> Config -> IO a

-- | Create a new <a>Key</a> by concatenating two existing keys.
(/.) :: Key -> Key -> Key

-- | The empty configuration, this <a>Config</a> is used as the base for
--   most config creating functions.
emptyConfig :: Config
withDefaults :: [(Key, Text)] -> Config -> Config

-- | Instantiate a <a>ProviderCreator</a> using the <a>emptyConfig</a>
mkStandaloneProvider :: ProviderCreator -> IO Provider

-- | Instantiate a <a>Provider</a> using an <tt>ProviderCretor</tt> and a
--   <a>Config</a> and add to the config
addProvider :: ProviderCreator -> Config -> IO Config

-- | Same as <a>getKey</a> but it throws if the <a>Key</a> isn't found
unsafeGetKey :: Key -> Config -> IO Text

module Conferer.FetchFromConfig.Basics
fetchFromConfigByRead :: (Typeable a, Read a) => Key -> Config -> IO (Maybe a)
fromValueWith :: (Text -> Maybe a) -> Text -> Maybe a
fetchFromConfigWith :: forall a. Typeable a => (Text -> Maybe a) -> Key -> Config -> IO (Maybe a)

-- | Concatenate many transformations to the config based on keys and
--   functions
findKeyAndApplyConfig :: forall newvalue config. FetchFromConfig newvalue => Config -> Key -> Key -> (newvalue -> config -> config) -> config -> IO config
class UpdateFromConfigWithConNameG f
updateFromConfigWithConNameG :: UpdateFromConfigWithConNameG f => String -> Key -> Config -> f a -> IO (f a)
instance (Conferer.FetchFromConfig.Basics.UpdateFromConfigWithConNameG inner, GHC.Generics.Constructor constructor) => Conferer.Types.UpdateFromConfigG (GHC.Generics.C1 constructor inner)
instance (Conferer.FetchFromConfig.Basics.UpdateFromConfigWithConNameG left, Conferer.FetchFromConfig.Basics.UpdateFromConfigWithConNameG right) => Conferer.FetchFromConfig.Basics.UpdateFromConfigWithConNameG (left GHC.Generics.:*: right)
instance (Conferer.Types.UpdateFromConfigG inner, GHC.Generics.Selector selector) => Conferer.FetchFromConfig.Basics.UpdateFromConfigWithConNameG (GHC.Generics.S1 selector inner)
instance Conferer.Types.FetchFromConfig GHC.Types.Int
instance Conferer.Types.FetchFromConfig GHC.Integer.Type.Integer
instance Conferer.Types.FetchFromConfig GHC.Types.Float
instance Conferer.Types.FetchFromConfig Data.ByteString.Internal.ByteString
instance Conferer.Types.FetchFromConfig a => Conferer.Types.FetchFromConfig (GHC.Maybe.Maybe a)
instance Conferer.Types.FetchFromConfig GHC.Base.String
instance Conferer.Types.FetchFromConfig Data.Text.Internal.Text
instance Conferer.Types.FetchFromConfig GHC.Types.Bool
instance Conferer.Types.UpdateFromConfigG inner => Conferer.Types.UpdateFromConfigG (GHC.Generics.D1 metadata inner)
instance Conferer.Types.FetchFromConfig inner => Conferer.Types.UpdateFromConfigG (GHC.Generics.Rec0 inner)

module Conferer.Provider.Files
fromRight :: a -> Either e a -> a
getFilePathFromEnv :: Config -> String -> IO FilePath

module Conferer.Provider.PropertiesFile

-- | <a>ProviderCreator</a> for properties file <a>Provider</a> that read
--   from a config file in <tt>config/{env}.properties</tt> and parses it
--   as a properties file with <tt>some.key=a value</tt> lines
mkPropertiesFileProvider :: ProviderCreator

-- | <a>ProviderCreator</a> for properties file <a>Provider</a> that only
--   parses a given <a>Text</a> as a properties file
mkPropertiesFileProvider' :: Text -> ProviderCreator

-- | Transform a line into a key/value pair (or not)
lineToKeyValue :: Text -> Maybe (Key, Text)


-- | Types and functions for managing configuration effectively
module Conferer

-- | Main typeclass for defining the way to get values from config, hiding
--   the <a>Text</a> based nature of the <a>Provider</a>s
--   
--   Here a <a>Nothing</a> means that the value didn't appear in the
--   config, some instances never return a value since they have defaults
--   that can never fail
class FetchFromConfig a
fetch :: FetchFromConfig a => Key -> Config -> IO (Maybe a)
fetch :: (FetchFromConfig a, DefaultConfig a, UpdateFromConfig a) => Key -> Config -> IO (Maybe a)

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

-- | Core type that the user of this library interact with, in the future
--   it may contain more this besides a list of providers
data Config

-- | The way to index <a>Provider</a>s, basically list of names that will
--   be adapted to whatever the provider needs
newtype Key
Path :: [Text] -> Key
[unKey] :: Key -> [Text]

-- | Core interface for library provided configuration, basically consists
--   of getting a <a>Key</a> and informing returning a maybe signaling the
--   value and if it's present in that specific provider
data Provider
Provider :: (Key -> IO (Maybe Text)) -> Provider
[getKeyInProvider] :: Provider -> Key -> IO (Maybe Text)

-- | Most Basic function to interact directly with a <a>Config</a>. It
--   always returns <a>Text</a> in the case of success and implements the
--   logic to traverse providers inside the <a>Config</a>.
getKey :: Key -> Config -> IO (Maybe Text)

-- | Fetch a value from a config key that's parsed using the
--   FetchFromConfig instance.
--   
--   This function throws an exception if the key is not found.
getFromConfig :: forall a. (Typeable a, FetchFromConfig a) => Key -> Config -> IO a

-- | Create a new <a>Key</a> by concatenating two existing keys.
(/.) :: Key -> Key -> Key

-- | The empty configuration, this <a>Config</a> is used as the base for
--   most config creating functions.
emptyConfig :: Config
withDefaults :: [(Key, Text)] -> Config -> Config

-- | Instantiate a <a>Provider</a> using an <tt>ProviderCretor</tt> and a
--   <a>Config</a> and add to the config
addProvider :: ProviderCreator -> Config -> IO Config

-- | Same as <a>getKey</a> but it throws if the <a>Key</a> isn't found
unsafeGetKey :: Key -> Config -> IO Text

-- | Default config which reads from command line arguments, env vars and
--   property files
defaultConfig :: Text -> IO Config

-- | Default config which reads from command line arguments, env vars,
--   property files and some default key/values
defaultConfigWithDefaults :: Text -> [(Key, Text)] -> IO Config

-- | The way to index <a>Provider</a>s, basically list of names that will
--   be adapted to whatever the provider needs
newtype Key
Path :: [Text] -> Key
[unKey] :: Key -> [Text]

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