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

type ProgramInfo a = ProgramInfoValidate a []
programInfo :: String -> MParser a -> a -> ProgramInfo a
piDescription :: Lens' (ProgramInfoValidate a f) String
piHelpHeader :: Lens' (ProgramInfoValidate a f) (Maybe String)
piHelpFooter :: Lens' (ProgramInfoValidate a f) (Maybe String)
piOptionParser :: Lens' (ProgramInfoValidate a f) (MParser a)
piDefaultConfiguration :: Lens' (ProgramInfoValidate a f) a
piConfigurationFiles :: Lens' (ProgramInfoValidate a f) [ConfigFile]
type ConfigValidation a f = forall m. (MonadIO m, Functor m, Applicative m, MonadError Text m, MonadWriter (f Text) m) => a -> m ()
programInfoValidate :: String -> MParser a -> a -> ConfigValidation a f -> ProgramInfoValidate a f
runWithConfiguration :: (FromJSON (a -> a), ToJSON a, Foldable f, Monoid (f Text)) => ProgramInfoValidate a f -> (a -> IO ()) -> IO ()
type PkgInfo = (String, String, String, String)
runWithPkgInfoConfiguration :: (FromJSON (a -> a), ToJSON a, Foldable f, Monoid (f Text)) => ProgramInfoValidate a f -> PkgInfo -> (a -> IO ()) -> IO ()
parseConfiguration :: (Applicative m, MonadIO m, MonadError Text m, FromJSON (a -> a), ToJSON a, Foldable f, Monoid (f Text)) => Text -> ProgramInfoValidate a f -> [String] -> m a
module Configuration.Utils.CommandLine
module Configuration.Utils.ConfigFile
module Configuration.Utils.Operators
type Lens' s a = Lens s s a a
type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t
module Configuration.Utils.Maybe
module Configuration.Utils.Monoid
data ProgramInfoValidate a f
piValidateConfiguration :: Lens' (ProgramInfoValidate a f) (ConfigValidationFunction a f)
newtype ConfigValidationFunction a f = ConfigValidationFunction {
- runConfigValidation :: ConfigValidation a f
}
piOptionParserAndDefaultConfiguration :: Lens (ProgramInfoValidate a b) (ProgramInfoValidate c d) (MParser a, a, ConfigValidationFunction a b) (MParser c, c, ConfigValidationFunction c d)

Program Configuration

type ProgramInfo a = ProgramInfoValidate a [] Source #

programInfo Source #

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 Source #

Program Description

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

Help header

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

Help footer

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

Options parser for configuration

piDefaultConfiguration :: Lens' (ProgramInfoValidate a f) a Source #

Default configuration

piConfigurationFiles :: Lens' (ProgramInfoValidate a f) [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 a f = forall m. (MonadIO m, Functor m, Applicative m, MonadError Text m, MonadWriter (f Text) m) => a -> m () Source #

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 Source #

Smart constructor for ProgramInfo.

piHelpHeader and piHelpFooter are set to Nothing.

Running a Configured Application

runWithConfiguration Source #

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

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 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 s t a b = forall f. Functor f => (a -> f b) -> s -> f t 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 a f Source #

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

Validation Function

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

newtype ConfigValidationFunction a f 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 a f

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

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