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

CopyrightCopyright © 2014-2015 PivotCloud, Inc.
LicenseMIT
MaintainerLars Kuhtz <lkuhtz@pivotmail.com>
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010
Extensions
  • Cpp
  • ScopedTypeVariables
  • OverloadedStrings
  • DisambiguateRecordFields
  • RecordWildCards
  • DeriveDataTypeable
  • FlexibleContexts
  • UnicodeSyntax
  • RankNTypes
  • ExplicitForAll

Configuration.Utils

Contents

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

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

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 α λ = forall μ. (MonadIO μ, Functor μ, Applicative μ, MonadError Text μ, MonadWriterText) μ) => α -> μ () 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 λ, MonoidText)) 
=> 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 λ, MonoidText)) 
=> 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 λ, MonoidText)) 
=> 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

Parsing of Configuration Files with Default Values

Miscellaneous Utilities

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 σ τ α β = forall φ. 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

Configuration of Monoids

Low-level Configuration Validation

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.

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.