Copyright	Copyright © 2014-2015 PivotCloud, Inc.
License	MIT
Maintainer	Lars Kuhtz <lkuhtz@pivotmail.com>
Stability	experimental
Safe Haskell	None
Language	Haskell2010
Extensions	Cpp ScopedTypeVariables OverloadedStrings DisambiguateRecordFields RecordWildCards DeriveDataTypeable FlexibleContexts UnicodeSyntax RankNTypes ExplicitForAll

Configuration.Utils

Contents

Program Configuration
Program Configuration with Validation of Configuration Values
Running a Configured Application
Command Line Option Parsing with Default Values
Parsing of Configuration Files with Default Values
Miscellaneous Utilities
Configuration of Optional Values
Configuration of Monoids
Low-level Configuration Validation

Description

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:

a default value,
a FromJSON instance that yields a function that takes a value and updates that value with the parsed values,
a ToJSON instance, and
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

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.

Synopsis

Program Configuration

type ProgramInfo α = ProgramInfoValidate α [] Source

programInfo Source

Arguments

:: String	program description
-> MParser α	parser for updating the default configuration
-> α	default configuration
-> ProgramInfo α

Smart constructor for ProgramInfo.

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

piDescription :: Lens' (ProgramInfoValidate α λ) String Source

Program Description

piHelpHeader :: Lens' (ProgramInfoValidate α λ) (Maybe String) Source

Help header

piHelpFooter :: Lens' (ProgramInfoValidate α λ) (Maybe String) Source

Help footer

piOptionParser :: Lens' (ProgramInfoValidate α λ) (MParser α) Source

Options parser for configuration

piDefaultConfiguration :: Lens' (ProgramInfoValidate α λ) α Source

Default configuration

piConfigurationFiles :: Lens' (ProgramInfoValidate α λ) [ConfigFile] Source

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

Program Configuration with Validation of Configuration Values

type ConfigValidation α λ = (MonadIO μ, Functor μ, Applicative μ, MonadError Text μ, MonadWriter (λ Text) μ) => α -> μ () Source

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

programInfoValidate :: String -> MParser α -> α -> ConfigValidation α λ -> ProgramInfoValidate α λ Source

Smart constructor for ProgramInfo.

piHelpHeader and piHelpFooter are set to Nothing.

Running a Configured Application

runWithConfiguration Source

Arguments

:: (FromJSON (α -> α), ToJSON α, Foldable λ, Monoid (λ Text))
=> ProgramInfoValidate α λ	program info value; use `programInfo` to construct a value of this type
-> (α -> 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.
--help, -h: Print a help message and exit.

As long as the package wasn't 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) Source

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 Source

Arguments

:: (FromJSON (α -> α), ToJSON α, Foldable λ, Monoid (λ Text))
=> ProgramInfoValidate α λ	program info value; use `programInfo` to construct a value of this type
-> PkgInfo
-> (α -> 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.
--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.

As long as the package wasn't 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 Source

Arguments

:: (Applicative m, MonadIO m, MonadBaseControl IO m, MonadError Text m, FromJSON (α -> α), ToJSON α, Foldable λ, Monoid (λ Text))
=> Text	program name (used in error messages)
-> ProgramInfoValidate α λ	program info value; use `programInfo` to construct a value of this type
-> [String]	command line arguments
-> m α

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' σ α = Lens σ σ α α Source

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 σ τ α β = Functor φ => (α -> φ β) -> σ -> φ τ Source

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 α λ Source

piValidateConfiguration :: Lens' (ProgramInfoValidate α λ) (ConfigValidationFunction α λ) Source

Validation Function

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

newtype ConfigValidationFunction α λ Source

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 α λ

piOptionParserAndDefaultConfiguration :: Lens (ProgramInfoValidate α λ) (ProgramInfoValidate β γ) (MParser α, α, ConfigValidationFunction α λ) (MParser β, β, ConfigValidationFunction β γ) Source

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