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

Copyright | (c) Eric Mertens 2017
License | ISC
Maintainer | emertens@gmail.com
Safe Haskell | None
Language | Haskell2010

Config.Schema.Types

Contents

- Value specification
- Unordered section-value pairs specification

Description

This module defines the syntax of value specifications.

Specifications can be defined using Config.Schema.Spec and can be consumed with Config.Schema.Load and Config.Schema.Doc.

This module defines high-level `ValueSpec` and `SectionsSpec` types that are intended to be used by normal library users. This types are implemented in terms of primitive `PrimValueSpec` and `PrimSectionSpec` types. These primitives are what consumers of specifications will need to use.

Synopsis

- data ValueSpec a
- data PrimValueSpec a where
  - TextSpec :: PrimValueSpec Text
  - NumberSpec :: PrimValueSpec Number
  - AtomSpec :: PrimValueSpec Text
  - ListSpec :: forall a1. ValueSpec a1 -> PrimValueSpec [a1]
  - SectionsSpec :: forall a. Text -> SectionsSpec a -> PrimValueSpec a
  - AssocSpec :: forall a1. ValueSpec a1 -> PrimValueSpec [(Text, a1)]
  - CustomSpec :: forall a. Text -> ValueSpec (Either Text a) -> PrimValueSpec a
  - NamedSpec :: forall a. Text -> ValueSpec a -> PrimValueSpec a
  - ExactSpec :: Value () -> PrimValueSpec ()
- primValueSpec :: PrimValueSpec a -> ValueSpec a
- runValueSpec :: Alt f => (forall x. PrimValueSpec x -> f x) -> ValueSpec a -> f a
- runValueSpec_ :: Semigroup m => (forall x. PrimValueSpec x -> m) -> ValueSpec a -> m
- data SectionsSpec a
- data PrimSectionSpec a where
  - ReqSection :: forall a. Text -> Text -> ValueSpec a -> PrimSectionSpec a
  - OptSection :: forall a1. Text -> Text -> ValueSpec a1 -> PrimSectionSpec (Maybe a1)
- primSectionsSpec :: PrimSectionSpec a -> SectionsSpec a
- runSections :: Applicative f => (forall x. PrimSectionSpec x -> f x) -> SectionsSpec a -> f a
- runSections_ :: Monoid m => (forall x. PrimSectionSpec x -> m) -> SectionsSpec a -> m

# Value specification

data ValueSpec a Source #

Non-empty disjunction of value specifications. This type is the primary way to specify expected values.

Multiple specifications can be combined using this type's `Alt` instance.

To create `ValueSpec` values see Config.Schema.Spec

#### Instances

Instances details

Functor ValueSpec Source # |
Instance details Defined in Config.Schema.Types Methods fmap :: (a -> b) -> ValueSpec a -> ValueSpec b Source # (<$) :: a -> ValueSpec b -> ValueSpec a Source #
Alt ValueSpec Source # | Left-biased choice between two specifications
Instance details Defined in Config.Schema.Types Methods (<!>) :: ValueSpec a -> ValueSpec a -> ValueSpec a Source # some :: Applicative ValueSpec => ValueSpec a -> ValueSpec [a] Source # many :: Applicative ValueSpec => ValueSpec a -> ValueSpec [a] Source #

data PrimValueSpec a where Source #

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

Constructors

TextSpec :: PrimValueSpec Text | Matches any string literal
NumberSpec :: PrimValueSpec Number | Matches numbers
AtomSpec :: PrimValueSpec Text | Matches any atom
ListSpec :: forall a1. ValueSpec a1 -> PrimValueSpec [a1] | Matches a list of the underlying specification
SectionsSpec :: forall a. Text -> SectionsSpec a -> PrimValueSpec a | Documentation identifier and sections specification
AssocSpec :: forall a1. ValueSpec a1 -> PrimValueSpec [(Text, a1)] | Matches an arbitrary list of sections. Similar to `SectionsSpec` except that that the section names are user-defined.
CustomSpec :: forall a. Text -> ValueSpec (Either Text a) -> PrimValueSpec a | Documentation text and underlying specification. This specification will match values where the underlying specification returns a `Right` value. Otherwise a `Left` should contain a short failure explanation.
NamedSpec :: forall a. Text -> ValueSpec a -> PrimValueSpec a | Label used to hide complex specifications in documentation.
ExactSpec :: Value () -> PrimValueSpec () | Specific value to be matched

primValueSpec :: PrimValueSpec a -> ValueSpec a Source #

Lift a primitive value specification to `ValueSpec`.

Since: 0.2.0.0

runValueSpec :: Alt f => (forall x. PrimValueSpec x -> f x) -> ValueSpec 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.

runValueSpec_ :: Semigroup m => (forall x. PrimValueSpec x -> m) -> ValueSpec 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.

# Unordered section-value pairs specification

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

To create `SectionsSpec` values see Config.Schema.Spec

#### Instances

Instances details

Applicative SectionsSpec Source # |
Instance details Defined in Config.Schema.Types Methods pure :: a -> SectionsSpec a Source # (<*>) :: SectionsSpec (a -> b) -> SectionsSpec a -> SectionsSpec b Source # liftA2 :: (a -> b -> c) -> SectionsSpec a -> SectionsSpec b -> SectionsSpec c Source # (*>) :: SectionsSpec a -> SectionsSpec b -> SectionsSpec b Source # (<*) :: SectionsSpec a -> SectionsSpec b -> SectionsSpec a Source #
Functor SectionsSpec Source # |
Instance details Defined in Config.Schema.Types Methods fmap :: (a -> b) -> SectionsSpec a -> SectionsSpec b Source # (<$) :: a -> SectionsSpec b -> SectionsSpec a Source #

data PrimSectionSpec a 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 :: forall a. Text -> Text -> ValueSpec a -> PrimSectionSpec a | Required section: Name, Documentation, Specification
OptSection :: forall a1. Text -> Text -> ValueSpec a1 -> PrimSectionSpec (Maybe a1) | Optional section: Name, Documentation, Specification

primSectionsSpec :: PrimSectionSpec a -> SectionsSpec a Source #

Lift a single specification into a list of specifications.

Since: 0.2.0.0

runSections :: Applicative f => (forall x. PrimSectionSpec x -> f x) -> SectionsSpec 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. PrimSectionSpec x -> m) -> SectionsSpec 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.