Configuration.Utils.ConfigFile

This module provides tools for defining configuration file parsers via instances of FromJSON.

Unlike normal FromJSON instances the parsers for configuration files are expected to yield an update function that takes a value and updates the value with the settings from the configuration file.

Assuming that

• all configuration types are nested Haskell records or simple types and
• that there are lenses for all record fields

usually the operators ..: and %.: are all that is needed from this module.

The module Configuration.Utils.Monoid provides tools for the case that a simple type is a container with a monoid instance, such as List or HashMap.

The module Configuration.Utils.Maybe explains the usage of optional Maybe values in configuration types.

Parsing of Configuration Files with Default Values

setProperty

Arguments

:: Lens' α β

a lens into the target that is updated by the parser

-> Text

the JSON property name

-> (Value -> Parser β)

the JSON Value parser that is used to parse the value of the property

-> Object

the parsed JSON Value Object

-> Parser (α -> α)

A JSON Value parser for a property of a given Object that updates a setter with the parsed value.

data Auth = Auth
    { _userId ∷ !Int
    , _pwd ∷ !String
    }

userId ∷ Functor φ ⇒ (Int → φ Int) → Auth → φ Auth
userId f s = (\u → s { _userId = u }) <$> f (_userId s)

pwd ∷ Functor φ ⇒ (String → φ String) → Auth → φ Auth
pwd f s = (\p → s { _pwd = p }) <$> f (_pwd s)

-- or with lenses and TemplateHaskell just:
-- $(makeLenses ''Auth)

instance FromJSON (Auth → Auth) where
    parseJSON = withObject "Auth" $ \o → id
        <$< setProperty user "user" p o
        <*< setProperty pwd "pwd" parseJSON o
      where
        p = withText "user" $ \case
            "alice" → pure (0 ∷ Int)
            "bob" → pure 1
            e → fail $ "unrecognized user " ⊕ e

(..:) :: FromJSON β => Lens' α β -> Text -> Object -> Parser (α -> α) infix 6

A variant of the setProperty that uses the default parseJSON method from the FromJSON instance to parse the value of the property. Its usage pattern mimics the usage pattern of the .: operator from the aeson library.

data Auth = Auth
    { _user ∷ !String
    , _pwd ∷ !String
    }

user ∷ Functor φ ⇒ (String → φ String) → Auth → φ Auth
user f s = (\u → s { _user = u }) <$> f (_user s)

pwd ∷ Functor φ ⇒ (String → φ String) → Auth → φ Auth
pwd f s = (\p → s { _pwd = p }) <$> f (_pwd s)

-- or with lenses and TemplateHaskell just:
-- $(makeLenses ''Auth)

instance FromJSON (Auth → Auth) where
    parseJSON = withObject "Auth" $ \o → id
        <$< user ..: "user" × o
        <*< pwd ..: "pwd" × o

(!..:) :: FromJSON β => Lens' α β -> Text -> Object -> Parser (α -> α)

This operator requires that a value is explicitly provided in a configuration file, thus preventing the default value from being used. Otherwise this operator does the same as '(..:)'.

updateProperty :: Lens' α β -> Text -> (Value -> Parser (β -> β)) -> Object -> Parser (α -> α)

A JSON parser for a function that modifies a property of a given Object and updates a setter with the parsed function.

data HttpURL = HttpURL
    { _auth ∷ !Auth
    , _domain ∷ !String
    }

auth ∷ Functor φ ⇒ (Auth → φ Auth) → HttpURL → φ HttpURL
auth f s = (\u → s { _auth = u }) <$> f (_auth s)

domain ∷ Functor φ ⇒ (String → φ String) → HttpURL → φ HttpURL
domain f s = (\u → s { _domain = u }) <$> f (_domain s)

path ∷ Functor φ ⇒ (String → φ String) → HttpURL → φ HttpURL
path f s = (\u → s { _path = u }) <$> f (_path s)

-- or with lenses and TemplateHaskell just:
-- $(makeLenses ''HttpURL)

instance FromJSON (HttpURL → HttpURL) where
    parseJSON = withObject "HttpURL" $ \o → id
        <$< auth %.: "auth" × o
        <*< domain ..: "domain" × o

(%.:) :: FromJSON (β -> β) => Lens' α β -> Text -> Object -> Parser (α -> α) infix 6

A variant of updateProperty that used the FromJSON instance for the update function. It mimics the aeson operator .:. It creates a parser that modifies a setter with a parsed function.

data HttpURL = HttpURL
    { _auth ∷ !Auth
    , _domain ∷ !String
    }

auth ∷ Functor φ ⇒ (Auth → φ Auth) → HttpURL → φ HttpURL
auth f s = (\u → s { _auth = u }) <$> f (_auth s)

domain ∷ Functor φ ⇒ (String → φ String) → HttpURL → φ HttpURL
domain f s = (\u → s { _domain = u }) <$> f (_domain s)

path ∷ Functor φ ⇒ (String → φ String) → HttpURL → φ HttpURL
path f s = (\u → s { _path = u }) <$> f (_path s)

-- or with lenses and TemplateHaskell just:
-- $(makeLenses ''HttpURL)

instance FromJSON (HttpURL → HttpURL) where
    parseJSON = withObject "HttpURL" $ \o → id
        <$< auth %.: "auth" × o
        <*< domain ..: "domain" × o

Configuration File Parsing Policy

data ConfigFile

Constructors

ConfigFileRequired

Fields

getConfigFile :: !Text

ConfigFileOptional

Fields

getConfigFile :: !Text

Instances

Eq ConfigFile

Ord ConfigFile

Read ConfigFile

Show ConfigFile

Typeable * ConfigFile

data ConfigFilesConfig

An internal type for the meta configuration that specifies how the configuration files are loaded and parsed.

Constructors

ConfigFilesConfig

Fields

_cfcHttpsPolicy :: !HttpsCertPolicy

Instances

Eq ConfigFilesConfig

Show ConfigFilesConfig

Typeable * ConfigFilesConfig

cfcHttpsPolicy :: Lens' ConfigFilesConfig HttpsCertPolicy

defaultConfigFilesConfig :: ConfigFilesConfig

pConfigFilesConfig :: MParser ConfigFilesConfig

Miscellaneous Utilities

dropAndUncaml :: Int -> String -> String

module Data.Aeson

Internal Tools for Parsing Configuration Files

parseConfigFiles

Arguments

:: (ConfigFileParser μ, FromJSON (α -> α))

=> ConfigFilesConfig

-> α

default configuration value

-> [ConfigFile]

list of configuration file paths

-> μ α