Copyright | (c) Eric Mertens 2017 |
---|---|
License | ISC |
Maintainer | emertens@gmail.com |
Safe Haskell | None |
Language | Haskell2010 |
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.
- data SectionSpecs a
- reqSection :: Spec a => Text -> Text -> SectionSpecs a
- optSection :: Spec a => Text -> Text -> SectionSpecs (Maybe a)
- reqSection' :: Text -> ValueSpecs a -> Text -> SectionSpecs a
- optSection' :: Text -> ValueSpecs a -> Text -> SectionSpecs (Maybe a)
- data ValueSpecs a
- class Spec a where
- sectionsSpec :: Text -> SectionSpecs a -> ValueSpecs a
- assocSpec :: ValueSpecs a -> ValueSpecs [(Text, a)]
- atomSpec :: Text -> ValueSpecs ()
- anyAtomSpec :: ValueSpecs Text
- listSpec :: ValueSpecs a -> ValueSpecs [a]
- customSpec :: Text -> ValueSpecs a -> (a -> Maybe b) -> ValueSpecs b
- namedSpec :: Text -> ValueSpecs a -> ValueSpecs a
- oneOrList :: ValueSpecs a -> ValueSpecs [a]
- yesOrNoSpec :: ValueSpecs Bool
- stringSpec :: ValueSpecs String
- numSpec :: Num a => ValueSpecs a
- fractionalSpec :: Fractional a => ValueSpecs a
- nonemptySpec :: ValueSpecs a -> ValueSpecs (NonEmpty a)
- oneOrNonemptySpec :: ValueSpecs a -> ValueSpecs (NonEmpty a)
- runSections :: Applicative f => (forall x. SectionSpec x -> f x) -> SectionSpecs a -> f a
- runSections_ :: Monoid m => (forall x. SectionSpec x -> m) -> SectionSpecs a -> m
- runValueSpecs :: Alt f => (forall x. ValueSpec x -> f x) -> ValueSpecs a -> f a
- runValueSpecs_ :: Semigroup m => (forall x. ValueSpec x -> m) -> ValueSpecs a -> m
- data SectionSpec :: * -> * where
- ReqSection :: Text -> Text -> ValueSpecs a -> SectionSpec a
- OptSection :: Text -> Text -> ValueSpecs a -> SectionSpec (Maybe a)
- liftSectionSpec :: SectionSpec a -> SectionSpecs a
- data ValueSpec :: * -> * where
- TextSpec :: ValueSpec Text
- IntegerSpec :: ValueSpec Integer
- RationalSpec :: ValueSpec Rational
- AnyAtomSpec :: ValueSpec Text
- AtomSpec :: Text -> ValueSpec ()
- ListSpec :: ValueSpecs a -> ValueSpec [a]
- SectionSpecs :: Text -> SectionSpecs a -> ValueSpec a
- AssocSpec :: ValueSpecs a -> ValueSpec [(Text, a)]
- CustomSpec :: Text -> ValueSpecs (Maybe a) -> ValueSpec a
- NamedSpec :: Text -> ValueSpecs a -> ValueSpec a
- liftValueSpec :: ValueSpec a -> ValueSpecs a
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.
:: Spec a | |
=> Text | section name |
-> Text | description |
-> SectionSpecs a |
Specification for a required section with an implicit value specification.
:: Spec a | |
=> Text | section name |
-> Text | description |
-> SectionSpecs (Maybe a) |
Specification for an optional section with an implicit value specification.
:: Text | section name |
-> ValueSpecs a | value specification |
-> Text | description |
-> SectionSpecs a |
Specification for a required section with an explicit value specification.
:: 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.
Functor ValueSpecs Source # | |
Alt ValueSpecs Source # | Left-biased choice between two specifications |
Class of value specifications that don't require arguments.
valuesSpec :: ValueSpecs a Source #
:: 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.
:: 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
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.
:: 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.
stringSpec :: ValueSpecs String Source #
Specification for matching any text as a String
numSpec :: Num a => ValueSpecs a Source #
Specification for matching any integral number.
fractionalSpec :: Fractional a => ValueSpecs a Source #
Specification for matching any fractional number.
Since: 0.2.0.0
nonemptySpec :: ValueSpecs a -> ValueSpecs (NonEmpty a) Source #
Matches a non-empty list.
Since: 0.2.0.0
oneOrNonemptySpec :: ValueSpecs a -> ValueSpecs (NonEmpty a) Source #
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.
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 |
liftSectionSpec :: SectionSpec a -> SectionSpecs a Source #
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
.
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 |
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 |
liftValueSpec :: ValueSpec a -> ValueSpecs a Source #
Lift a primitive value specification to ValueSpecs
.
Since: 0.2.0.0