Copyright	Copyright © 2015 PivotCloud, Inc.
License	MIT
Maintainer	Lars Kuhtz <lkuhtz@pivotmail.com>
Stability	experimental
Safe Haskell	None
Language	Haskell2010

Configuration.Utils.ConfigFile

Contents

Parsing of Configuration Files with Default Values
Configuration File Parsing Policy
Miscellaneous Utilities

Description

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.

Synopsis

Parsing of Configuration Files with Default Values

setProperty Source

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 Source

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 (α -> α) Source

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 (α -> α) Source

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 Source

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 Source

Constructors

ConfigFileRequired
Fields getConfigFile :: !Text
ConfigFileOptional
Fields getConfigFile :: !Text

Instances

Eq ConfigFile
Ord ConfigFile
Read ConfigFile
Show ConfigFile
Typeable * ConfigFile

data ConfigFilesConfig Source

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 Source

defaultConfigFilesConfig :: ConfigFilesConfig Source

pConfigFilesConfig :: MParser ConfigFilesConfig Source

Miscellaneous Utilities

dropAndUncaml :: Int -> String -> String Source

module Data.Aeson