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

Config.Schema.Spec

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

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

Instances

 Source # Methodsfmap :: (a -> b) -> SectionSpecs a -> SectionSpecs b #(<$) :: a -> SectionSpecs b -> SectionSpecs a # Source # Methodspure :: a -> SectionSpecs a #(<*>) :: SectionSpecs (a -> b) -> SectionSpecs a -> SectionSpecs b #(*>) :: SectionSpecs a -> SectionSpecs b -> SectionSpecs b #(<*) :: SectionSpecs a -> SectionSpecs b -> SectionSpecs a # Arguments  :: Spec a => Text section name -> Text description -> SectionSpecs a Specification for a required section with an implicit value specification. Arguments  :: Spec a => Text section name -> Text description -> SectionSpecs (Maybe a) Specification for an optional section with an implicit value specification. Arguments  :: Text section name -> ValueSpecs a value specification -> Text description -> SectionSpecs a Specification for a required section with an explicit value specification. Arguments  :: Text section name -> ValueSpecs a value specification -> Text description -> SectionSpecs (Maybe a) Specification for an optional section with an explicit value specification. # Specifying values data 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. Multiple specifications can be combined using this type's Alt instance. Instances  Source # Methodsfmap :: (a -> b) -> ValueSpecs a -> ValueSpecs b #(<$) :: a -> ValueSpecs b -> ValueSpecs a # Source # Left-biased choice between two specifications Methods() :: ValueSpecs a -> ValueSpecs a -> ValueSpecs a #

class Spec a where Source #

Class of value specifications that don't require arguments.

Minimal complete definition

valuesSpec

Methods

Instances

 Source # Methods Source # Methods Source # Methods Source # Methods Spec a => Spec [a] Source # Methods (Spec a, Spec b) => Spec (Either a b) Source # Methods

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.

Arguments

 :: ValueSpecs a underlying specification -> ValueSpecs [(Text, a)]

Specification for a section list where the keys are user-defined. Values are matched against the underlying specification and returned as a list of section-name/value pairs.

Since: 0.3.0.0

Specification for matching a particular atom.

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.

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.

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

Specification for matching any text as a String

numSpec :: Num a => ValueSpecs a Source #

Specification for matching any integral number.

Specification for matching any fractional number.

Since: 0.2.0.0

Matches a non-empty list.

Since: 0.2.0.0

Matches a single element or a non-empty list.

Since: 0.2.0.0

# Executing specifications

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

Given an function that handles a single, primitive section specification; runSections will generate one that processes a whole SectionsSpec.

The results from each section will be sequence together using the Applicative instance in of the result type, and the results can be indexed by the type parameter of the specification.

For an example use of runSections, see Config.Schema.Load.

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

Given an function that handles a single, primitive section specification; runSections_ will generate one that processes a whole SectionsSpec.

The results from each section will be sequence together using the Monoid instance in of the result type, and the results will not be indexed by the type parameter of the specifications.

For an example use of runSections_, see Config.Schema.Docs.

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

Given an interpretation of a primitive value specification, extract a list of the possible interpretations of a disjunction of value specifications. Each of these primitive interpretations will be combined using the provided Alt instance.

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

Given an interpretation of a primitive value specification, extract a list of the possible interpretations of a disjunction of value specifications. Each of these primitive interpretations will be combined using the provided Semigroup instance.

# 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

Lift a single specification into a list of specifications.

Since: 0.2.0.0

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 AssocSpec :: ValueSpecs a -> ValueSpec [(Text, a)] Matches an arbitrary list of sections. Similar to SectionSpec except that that the section names are user-defined. 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

Lift a primitive value specification to ValueSpecs.

Since: 0.2.0.0