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

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] -> Config
[providers] :: Config -> [Provider]

-- | 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 an error means that the value couldn't be parsed and that a
--   reasonable default was not possible.
class FetchFromConfig a
fetch :: FetchFromConfig a => Key -> Config -> IO (Either Text a)
instance GHC.Classes.Ord Conferer.Types.Key
instance GHC.Classes.Eq Conferer.Types.Key
instance GHC.Show.Show Conferer.Types.Key
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>Provider</a> from a <a>Map</a>
mkMapProvider' :: Map Key Text -> ProviderCreator

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 (Either Text 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 :: 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

-- | 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 :: Read a => Key -> Config -> IO (Either Text a)
fromValueWith :: (Text -> Maybe a) -> Key -> Text -> Either Text a
fetchFromConfigWith :: (Text -> Maybe a) -> Key -> Config -> IO (Either Text a)

-- | Concatenate many transformations to the config based on keys and
--   functions
findKeyAndApplyConfig :: FetchFromConfig newvalue => Config -> Key -> Key -> (newvalue -> config -> config) -> Either Text config -> IO (Either Text config)
instance Conferer.Types.FetchFromConfig GHC.Types.Int
instance Conferer.Types.FetchFromConfig GHC.Types.Float
instance Conferer.Types.FetchFromConfig Data.ByteString.Internal.ByteString
instance Conferer.Types.FetchFromConfig GHC.Base.String
instance Conferer.Types.FetchFromConfig Data.Text.Internal.Text
instance Conferer.Types.FetchFromConfig GHC.Types.Bool

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


-- | 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 an error means that the value couldn't be parsed and that a
--   reasonable default was not possible.
class FetchFromConfig 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 (Either Text 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 :: 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

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

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