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 b

a lens into the target that is updated by the parser

-> Text

the JSON property name

-> (Value -> Parser b)

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

-> Object

the parsed JSON Value Object

-> Parser (a -> a)

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 f ⇒ (Int → f Int) → Auth → f Auth
userId f s = (\u → s { _userId = u }) <$> f (_userId s)

pwd ∷ Functor f ⇒ (String → f String) → Auth → f 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 b => Lens' a b -> Text -> Object -> Parser (a -> a) 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 f ⇒ (String → f String) → Auth → f Auth
user f s = (\u → s { _user = u }) <$> f (_user s)

pwd ∷ Functor f ⇒ (String → f String) → Auth → f 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 b => Lens' a b -> Text -> Object -> Parser (a -> a)

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' a b -> Text -> (Value -> Parser (b -> b)) -> Object -> Parser (a -> a)

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

This function is useful when a FromJSON instance isn't available. When a FromJSON instance exists, the %.: provides a more ideomatic alternative.

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

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

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

path ∷ Functor f ⇒ (String → f String) → HttpURL → f 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
        <$< updateProperty auth "auth" parseJSON o
        <*< setProperty domain "domain" parseJSON o

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

A variant of updateProperty that uses 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 f ⇒ (Auth → f Auth) → HttpURL → f HttpURL
auth f s = (\u → s { _auth = u }) <$> f (_auth s)

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

path ∷ Functor f ⇒ (String → f String) → HttpURL → f 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

Methods

(==) :: ConfigFile -> ConfigFile -> Bool

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

Ord ConfigFile

Methods

compare :: ConfigFile -> ConfigFile -> Ordering

(<) :: ConfigFile -> ConfigFile -> Bool

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

(>) :: ConfigFile -> ConfigFile -> Bool

(>=) :: ConfigFile -> ConfigFile -> Bool

max :: ConfigFile -> ConfigFile -> ConfigFile

min :: ConfigFile -> ConfigFile -> ConfigFile

Read ConfigFile

Methods

readsPrec :: Int -> ReadS ConfigFile

readList :: ReadS [ConfigFile]

readPrec :: ReadPrec ConfigFile

readListPrec :: ReadPrec [ConfigFile]

Show ConfigFile

Methods

showsPrec :: Int -> ConfigFile -> ShowS

show :: ConfigFile -> String

showList :: [ConfigFile] -> ShowS

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

Methods

(==) :: ConfigFilesConfig -> ConfigFilesConfig -> Bool

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

Show ConfigFilesConfig

Methods

showsPrec :: Int -> ConfigFilesConfig -> ShowS

show :: ConfigFilesConfig -> String

showList :: [ConfigFilesConfig] -> ShowS

cfcHttpsPolicy :: Lens' ConfigFilesConfig HttpsCertPolicy

defaultConfigFilesConfig :: ConfigFilesConfig

pConfigFilesConfig :: MParser ConfigFilesConfig

Miscellaneous Utilities

dropAndUncaml :: Int -> String -> String

module Data.Aeson