configuration-tools-0.6.0: Tools for specifying and parsing configurations

Configuration.Utils

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:

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

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

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 [])

Program Description

Help footer

Options parser for configuration

Default configuration

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

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.

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.

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.

# Miscellaneous Utilities

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.

# Low-level Configuration Validation

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 FieldsrunConfigValidation :: ConfigValidation a f

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