Conferer

Public and stable API for the most basic usage of this library

How to use this doc

This doc is mostly for reference, so you probably won't learn how to use conferer by reading it. For more detailed and guided documentation the best place is the webpage: https://conferer.ludat.io/docs

Creating a Config

mkConfig :: Text -> IO Config

Create a Config which reads from command line arguments, env vars and property files that depend on the environment (config/development.properties) by default

mkConfig' :: Defaults -> [SourceCreator] -> IO Config

Create a Config with the given defaults and source creators. The sources will take precedence by the order they have in the list (earlier in the list means it's tried first). If the requested key is not found in any source it'll be looked up in the defaults.

Getting values from a config

These functions allow you to get any type that implements FromConfig

fetch :: forall a. (FromConfig a, Typeable a, DefaultConfig a) => Config -> IO a

Use the FromConfig instance to get a value of type a 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 ("abc" as an Int) but that depends on the FromConfig implementation for the type.

fetch' :: forall a. (FromConfig a, Typeable a) => Config -> a -> IO a

Same as fetch but it accepts the default as a parameter instead of using the default from configDef

fetchKey :: forall a. (FromConfig a, Typeable a) => Config -> Key -> a -> IO a

Same as fetch' but you can specify a Key instead of the root key which allows you to fetch smaller values when you need them instead of a big one at initialization time.

fetchFromConfig :: forall a. (FromConfig a, Typeable a) => Key -> Config -> IO a

safeFetchKey :: forall a. (FromConfig a, Typeable a) => Config -> Key -> IO (Maybe a)

Same as fetchKey but it returns a Nothing when the value isn't present

unsafeFetchKey :: forall a. (FromConfig a, Typeable a) => Config -> Key -> IO a

Same as fetchKey but it throws when the value isn't present.

class DefaultConfig a where

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

Methods

configDef :: a

class FromConfig a

The typeclass for defining the way to get values from a Config, hiding the Text based nature of the Sources 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 Generics so most of the time user need not to implement this typeclass.

Instances

FromConfig Bool

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO Bool

FromConfig Float

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO Float

FromConfig Int

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO Int

FromConfig Integer

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO Integer

FromConfig ()

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO ()

Typeable a => FromConfig a

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO a

FromConfig String

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO String

FromConfig ByteString

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO ByteString

FromConfig ByteString

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO ByteString

FromConfig Text

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO Text

FromConfig File

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO File

(Typeable a, FromConfig a) => FromConfig [a]

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO [a]

(Typeable a, FromConfig a) => FromConfig (Maybe a)

Defined in Conferer.FromConfig.Internal

Methods

fromConfig :: Key -> Config -> IO (Maybe a)

Some useful types

data 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 Source interface)

Instances

Show Config

Defined in Conferer.Config.Internal.Types

Methods

showsPrec :: Int -> Config -> ShowS

show :: Config -> String

showList :: [Config] -> ShowS

data Key

This type is used extensivelly as a way to point into a Source and in turn into a Config. The intended way to create them is is using mkKey.

It's a list of alphanumeric words and each Source can interpret it as it sees fit.

Instances

Eq Key

Defined in Conferer.Key.Internal

Methods

(==) :: Key -> Key -> Bool

(/=) :: Key -> Key -> Bool

Ord Key

Defined in Conferer.Key.Internal

Methods

compare :: Key -> Key -> Ordering

(<) :: Key -> Key -> Bool

(<=) :: Key -> Key -> Bool

(>) :: Key -> Key -> Bool

(>=) :: Key -> Key -> Bool

max :: Key -> Key -> Key

min :: Key -> Key -> Key

Show Key

Defined in Conferer.Key.Internal

Methods

showsPrec :: Int -> Key -> ShowS

show :: Key -> String

showList :: [Key] -> ShowS

IsString Key

Defined in Conferer.Key.Internal

Methods

fromString :: String -> Key