Configuration.Utils

This module provides a collection of utilities on top of the packages optparse-applicative, aeson, and yaml, for configuring libraries and applications in a composable way.

The main feature is the integration of command line option parsing and configuration files.

The purpose is to make management of configurations easy by providing an idiomatic style of defining and deploying configurations in a modular and composable way.

Usage

The module provides operators and functions that make the implementation of these entities easy for the common case that the configurations are encoded mainly as nested records.

For each data type that is used as as component in a configuration type the following must be provided:

1. a default value,
2. a FromJSON instance that yields a function that takes a value and updates that value with the parsed values,
3. a ToJSON instance, and
4. a command line options parser that yields a function that takes a value and updates that value with the values provided as command line options.

In addition to the above optionally a validation function may be provided that (recursively) validates a configuration value and returns either an error or a (possibly empty) list-like structure of warnings.

The modules

• Configuration.Utils.CommandLine,
• Configuration.Utils.ConfigFile, and
• Configuration.Utils.Operators

contain tools and examples for defining above prerequisites for using a type in a configuration type.

The provided functions and operators assume that lenses for the configuration record types are provided.

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.

Usage Example

Beside the examples that are provided in the haddock documentation there is a complete usage example in the file example/Example.hs of the cabal package.

Program Configuration

type ProgramInfo a = ProgramInfoValidate a []

programInfo

Arguments

:: String

program description

-> MParser a

parser for updating the default configuration

-> a

default configuration

-> ProgramInfo a

Smart constructor for ProgramInfo.

piHelpHeader and piHelpFooter are set to Nothing. The function piValidateConfiguration is set to const (return [])

piDescription :: Lens' (ProgramInfoValidate a f) String

Program Description

piHelpHeader :: Lens' (ProgramInfoValidate a f) (Maybe String)

Help header

piHelpFooter :: Lens' (ProgramInfoValidate a f) (Maybe String)

Help footer

piOptionParser :: Lens' (ProgramInfoValidate a f) (MParser a)

Options parser for configuration

piDefaultConfiguration :: Lens' (ProgramInfoValidate a f) a

Default configuration

piConfigurationFiles :: Lens' (ProgramInfoValidate a f) [ConfigFile]

Configuration files that are loaded in order before any command line argument is evaluated.

Program Configuration with Validation of Configuration Values

type ConfigValidation a f = forall m. (MonadIO m, Functor m, Applicative m, MonadError Text m, MonadWriter (f Text) m) => a -> m ()

A validation function. The type in the MonadWriter is excpected to be a Foldable structure for collecting warnings.

programInfoValidate :: String -> MParser a -> a -> ConfigValidation a f -> ProgramInfoValidate a f

Smart constructor for ProgramInfo.

piHelpHeader and piHelpFooter are set to Nothing.

Running a Configured Application

runWithConfiguration

Arguments

:: (FromJSON (a -> a), ToJSON a, Foldable f, Monoid (f Text))

=> ProgramInfoValidate a f

program info value; use programInfo to construct a value of this type

-> (a -> IO ())

computation that is given the configuration that is parsed from the command line.

-> IO ()

Run an IO action with a configuration that is obtained by updating the given default configuration the values defined via command line arguments.

In addition to the options defined by the given options parser the following options are recognized:

--config-file

Parse the given file path as a (partial) configuration in YAML or JSON format.

--print-config

Print the final parsed configuration to standard out and exit.

--print-config-as (full|minimal|diff)

Configures the application and prints the configuration in YAML format to standard out and exits. The printed configuration is exactly the configuration that otherwise would be used to run the application.

Arguments:

• full: print the complete configuration. Same as --print-config.
• minimal: print a minimal configuration that contains only those settings that are different from the default setting.
• diff: print a YAML document that shows the difference between the default configuration and the actual configuration.

--help, -h, -?

Print a help message and exit.

If the package is build with -f+remote-configs the following two options are available. They affect how configuration files are loaded from remote URLs.

--config-https-insecure=true|false

Bypass certificate validation for all HTTPS connections to all services.

--config-https-allow-cert=HOSTNAME:PORT:FINGERPRINT

Unconditionally trust the certificate for connecting to the service.

type PkgInfo = (String, String, String, String)

Information about the cabal package. The format is:

(info message, detailed info message, version string, license text)

See the documentation of Configuration.Utils.Setup for a way how to generate this information automatically from the package description during the build process.

runWithPkgInfoConfiguration

Arguments

:: (FromJSON (a -> a), ToJSON a, Foldable f, Monoid (f Text))

=> ProgramInfoValidate a f

program info value; use programInfo to construct a value of this type

-> PkgInfo

-> (a -> IO ())

computation that is given the configuration that is parsed from the command line.

-> IO ()

Run an IO action with a configuration that is obtained by updating the given default configuration the values defined via command line arguments.

In addition to the options defined by the given options parser the following options are recognized:

--config-file, -c

Parse the given file path as a (partial) configuration in YAML or JSON format.

--print-config, -p

Print the final parsed configuration to standard out and exit.

--print-config-as (full|minimal|diff)

Configures the application and prints the configuration in YAML format to standard out and exits. The printed configuration is exactly the configuration that otherwise would be used to run the application.

Arguments:

• full: print the complete configuration. Same as --print-config.
• minimal: print a minimal configuration that contains only those settings that are different from the default setting.
• diff: print a YAML document that shows the difference between the default configuration and the actual configuration.

--help, -h, -?

Print a help message and exit.

--version, -v

Print the version of the application and exit.

--info, -i

Print a short info message for the application and exit.

--long-info

Print a detailed info message for the application and exit.

--license

Print the text of the license of the application and exit.

If the package is build with -f+remote-configs the following two options are available. They affect how configuration files are loaded from remote URLs.

--config-https-insecure=true|false

Bypass certificate validation for all HTTPS connections to all services.

--config-https-allow-cert=HOSTNAME:PORT:FINGERPRINT

Unconditionally trust the certificate for connecting to the service.

parseConfiguration

Arguments

:: (Applicative m, MonadIO m, MonadError Text m, FromJSON (a -> a), ToJSON a, Foldable f, Monoid (f Text))

=> Text

program name (used in error messages)

-> ProgramInfoValidate a f

program info value; use programInfo to construct a value of this type

-> [String]

command line arguments

-> m a

Parse the command line arguments.

Any warnings from the configuration function are discarded. The options --print-config and --help are just ignored.

Command Line Option Parsing with Default Values

module Configuration.Utils.CommandLine

Parsing of Configuration Files with Default Values

module Configuration.Utils.ConfigFile

Miscellaneous Utilities

module Configuration.Utils.Operators

type Lens' s a = Lens s s a a

This is the same type as the type from the lens library with the same name.

In case it is already import from the lens package this should be hidden from the import.

type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t

This is the same type as the type from the lens library with the same name.

In case it is already import from the lens package this should be hidden from the import.

Configuration of Optional Values

module Configuration.Utils.Maybe

Configuration of Monoids

module Configuration.Utils.Monoid

Low-level Configuration Validation

data ProgramInfoValidate a f

piValidateConfiguration :: Lens' (ProgramInfoValidate a f) (ConfigValidationFunction a f)

Validation Function

The Right result is interpreted as a Foldable structure of warnings.

newtype ConfigValidationFunction a f

A newtype wrapper around a validation function. The only purpose of this type is to avoid ImpredicativeTypes when storing the function in the ProgramInfoValidate record.

Constructors

ConfigValidationFunction

Fields

• runConfigValidation :: ConfigValidation a f

piOptionParserAndDefaultConfiguration :: Lens (ProgramInfoValidate a b) (ProgramInfoValidate c d) (MParser a, a, ConfigValidationFunction a b) (MParser c, c, ConfigValidationFunction c d)

Lens for simultaneous query and update of piOptionParser and piDefaultConfiguration. This supports to change the type of ProgramInfo with over and set.