config-schema-0.1.0.0: Schema definitions for the config-value package

Copyright(c) Eric Mertens 2017
LicenseISC
Maintaineremertens@gmail.com
Safe HaskellNone
LanguageHaskell2010

Config.Schema.Spec

Contents

Description

This module provides a set of types and operations for defining configuration file schemas. These schemas can be built up using Applicative operations.

These specifications are suitable for be consumed by Config.Schema.Load and Config.Schema.Docs.

This is the schema system used by the glirc IRC client https://hackage.haskell.org/package/glirc. For a significant example, visit the Client.Configuration and Client.Configuration.Colors modules.

Synopsis

Specifying sections

newtype SectionSpecs a Source #

A list of section specifications used to process a whole group of key-value pairs. Multiple section specifications can be combined using this type's Applicative instance.

Constructors

MkSectionSpecs (Ap SectionSpec a) 

reqSection Source #

Arguments

:: Spec a 
=> Text

section name

-> Text

description

-> SectionSpecs a 

Specification for a required section with an implicit value specification.

optSection Source #

Arguments

:: Spec a 
=> Text

section name

-> Text

description

-> SectionSpecs (Maybe a) 

Specification for an optional section with an implicit value specification.

reqSection' Source #

Arguments

:: Text

section name

-> Text

description

-> ValueSpecs a

value specification

-> SectionSpecs a 

Specification for a required section with an explicit value specification.

optSection' Source #

Arguments

:: Text

section name

-> Text

description

-> ValueSpecs a

value specification

-> SectionSpecs (Maybe a) 

Specification for an optional section with an explicit value specification.

Specifying values

newtype ValueSpecs a Source #

Non-empty disjunction of value specifications. This type is the primary way to specify expected values. Use the Spec class to generate ValueSpecs for simple types.

Instances

Functor ValueSpecs Source # 

Methods

fmap :: (a -> b) -> ValueSpecs a -> ValueSpecs b #

(<$) :: a -> ValueSpecs b -> ValueSpecs a #

Alt ValueSpecs Source #

Left-biased choice between two specifications

class Spec a where Source #

Class of value specifications that don't require arguments.

Minimal complete definition

valuesSpec

sectionsSpec Source #

Arguments

:: Text

unique documentation identifier

-> SectionSpecs a

underlying specification

-> ValueSpecs a 

Named subsection value specification. The unique identifier will be used for generating a documentation section for this specification and should be unique within the scope of the specification being built.

atomSpec :: Text -> ValueSpecs () Source #

Specification for matching a particular atom.

anyAtomSpec :: ValueSpecs Text Source #

Specification for matching any atom. Matched atom is returned.

listSpec :: ValueSpecs a -> ValueSpecs [a] Source #

Specification for matching a list of values each satisfying a given element specification.

customSpec :: Text -> ValueSpecs a -> (a -> Maybe b) -> ValueSpecs b Source #

The custom specification allows an arbitrary function to be used to validate the value extracted by a specification. If Nothing is returned the value is considered to have failed validation.

namedSpec Source #

Arguments

:: Text

name

-> ValueSpecs a

underlying specification

-> ValueSpecs a 

Named value specification. This is useful for factoring complicated value specifications out in the documentation to avoid repetition of complex specifications.

Derived specifications

oneOrList :: ValueSpecs a -> ValueSpecs [a] Source #

Specification that matches either a single element or multiple elements in a list. This can be convenient for allowing the user to avoid having to specify singleton lists in the configuration file.

numSpec :: Num a => ValueSpecs a Source #

Specification for matching any integral number.

yesOrNoSpec :: ValueSpecs Bool Source #

Specification for using yes and no to represent booleans True and False respectively

stringSpec :: ValueSpecs String Source #

Specification for matching any text as a String

Executing specifications

runSections :: Applicative f => (forall x. SectionSpec x -> f x) -> SectionSpecs a -> f a Source #

runSections_ :: Monoid m => (forall x. SectionSpec x -> m) -> SectionSpecs a -> m Source #

runValueSpecs :: Functor f => (forall x. ValueSpec x -> f x) -> ValueSpecs a -> NonEmpty (f a) Source #

Given an interpretation of a primitive value specification, extract a list of the possible interpretations of a disjunction of value specifications.

Unlike runValueSpecs_, this allows the result of the interpretation to be indexed by the type of the primitive value specifications.

runValueSpecs_ :: (forall x. ValueSpec x -> m) -> ValueSpecs a -> NonEmpty m Source #

Given an interpretation of a primitive value specification, extract a list of the possible interpretations of a disjunction of value specifications.

Primitive specifications

data SectionSpec :: * -> * where Source #

Specifications for single configuration sections.

The fields are section name, documentation text, value specification. Use ReqSection for required key-value pairs and OptSection for optional ones.

Constructors

ReqSection :: Text -> Text -> ValueSpecs a -> SectionSpec a

Required section: Name, Documentation, Specification

OptSection :: Text -> Text -> ValueSpecs a -> SectionSpec (Maybe a)

Optional section: Name, Documentation, Specification

data ValueSpec :: * -> * where Source #

The primitive specification descriptions for values. Specifications built from these primitive cases are found in ValueSpecs.

Constructors

TextSpec :: ValueSpec Text

Matches any string literal

IntegerSpec :: ValueSpec Integer

Matches integral numbers

RationalSpec :: ValueSpec Rational

Matches any number

AnyAtomSpec :: ValueSpec Text

Matches any atom

AtomSpec :: Text -> ValueSpec ()

Specific atom to be matched

ListSpec :: ValueSpecs a -> ValueSpec [a]

Matches a list of the underlying specification

SectionSpecs :: Text -> SectionSpecs a -> ValueSpec a

Documentation identifier and section specification

CustomSpec :: Text -> ValueSpecs (Maybe a) -> ValueSpec a

Documentation text, underlying specification

NamedSpec :: Text -> ValueSpecs a -> ValueSpec a

Label used to hide complicated specs in documentation