-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Schema definitions for the config-value package
--   
--   This package makes it possible to define schemas for use when loading
--   configuration files using the config-value format. These schemas can
--   be used to process a configuration file into a Haskell value or to
--   automatically generate documentation for the file format.
@package config-schema
@version 1.3.0.0

-- | 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.
module Config.Schema.Types

-- | 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
data ValueSpec a

-- | The primitive specification descriptions for values. Specifications
--   built from these primitive cases are found in ValueSpec.
data PrimValueSpec a

-- | Matches any string literal
[TextSpec] :: PrimValueSpec Text

-- | Matches numbers
[NumberSpec] :: PrimValueSpec Number

-- | Matches any atom
[AtomSpec] :: PrimValueSpec Text

-- | Matches a list of the underlying specification
[ListSpec] :: forall a1. ValueSpec a1 -> PrimValueSpec [a1]

-- | Documentation identifier and sections specification
[SectionsSpec] :: forall a. Text -> SectionsSpec a -> PrimValueSpec a

-- | Matches an arbitrary list of sections. Similar to SectionsSpec
--   except that that the section names are user-defined.
[AssocSpec] :: forall a1. ValueSpec a1 -> PrimValueSpec [(Text, a1)]

-- | 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.
[CustomSpec] :: forall a. Text -> ValueSpec (Either Text a) -> PrimValueSpec a

-- | Label used to hide complex specifications in documentation.
[NamedSpec] :: forall a. Text -> ValueSpec a -> PrimValueSpec a

-- | Specific value to be matched
[ExactSpec] :: Value () -> PrimValueSpec ()

-- | Lift a primitive value specification to ValueSpec.
primValueSpec :: PrimValueSpec a -> ValueSpec a

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

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

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

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

-- | Required section: Name, Documentation, Specification
[ReqSection] :: forall a. Text -> Text -> ValueSpec a -> PrimSectionSpec a

-- | Optional section: Name, Documentation, Specification
[OptSection] :: forall a1. Text -> Text -> ValueSpec a1 -> PrimSectionSpec (Maybe a1)

-- | Lift a single specification into a list of specifications.
primSectionsSpec :: PrimSectionSpec a -> SectionsSpec a

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

-- | 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.
runSections_ :: Monoid m => (forall x. () => PrimSectionSpec x -> m) -> SectionsSpec a -> m
instance Data.Functor.Alt.Alt Config.Schema.Types.ValueSpec
instance GHC.Internal.Base.Applicative Config.Schema.Types.SectionsSpec
instance GHC.Internal.Base.Functor Config.Schema.Types.SectionsSpec
instance GHC.Internal.Base.Functor Config.Schema.Types.ValueSpec

-- | This module provides a set of types and operations for defining
--   configuration file schemas.
--   
--   These specifications are can 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.
module Config.Schema.Spec

-- | 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
data ValueSpec a

-- | 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.
customSpec :: Text -> ValueSpec a -> (a -> Either Text b) -> ValueSpec b

-- | Named value specification. This is useful for factoring complicated
--   value specifications out in the documentation to avoid repetition of
--   complex specifications.
namedSpec :: Text -> ValueSpec a -> ValueSpec a

-- | Match an exact value. This can be used to match a specific text
--   literal number literal, atom, list of exact things, etc.
exactSpec :: Value () -> ValueSpec ()

-- | Class of value specifications without parameters.
class HasSpec a
anySpec :: HasSpec a => ValueSpec 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.
sectionsSpec :: Text -> SectionsSpec a -> ValueSpec 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.
assocSpec :: ValueSpec a -> ValueSpec [(Text, a)]

-- | Primitive specification for matching any number.
numberSpec :: ValueSpec Number

-- | Specification for matching any integral number.
integerSpec :: ValueSpec Integer

-- | Specification for matching any number as a Rational.
rationalSpec :: ValueSpec Rational

-- | Specification for matching any non-negative, integral number
naturalSpec :: ValueSpec Natural

-- | Specification for matching any fractional number.
fractionalSpec :: Fractional a => ValueSpec a

-- | Specification for matching any integral number.
numSpec :: Num a => ValueSpec a

-- | Specification for matching any text literal
textSpec :: ValueSpec Text

-- | Specification for matching any text as a String
stringSpec :: ValueSpec String

-- | Primitive specification for matching a particular atom.
atomSpec :: Text -> ValueSpec ()

-- | Primitive specification for matching any atom. Matched atom is
--   returned.
anyAtomSpec :: ValueSpec Text

-- | Specification for using atoms yes and no to
--   represent booleans True and False respectively
yesOrNoSpec :: ValueSpec Bool

-- | Specification for using atoms true and false to
--   represent booleans True and False respectively.
trueOrFalseSpec :: ValueSpec Bool

-- | Primitive specification for matching a list of values each satisfying
--   a given element specification.
listSpec :: ValueSpec a -> ValueSpec [a]

-- | 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.
oneOrList :: ValueSpec a -> ValueSpec [a]

-- | Matches a non-empty list.
nonemptySpec :: ValueSpec a -> ValueSpec (NonEmpty a)

-- | Matches a single element or a non-empty list.
oneOrNonemptySpec :: ValueSpec a -> ValueSpec (NonEmpty a)

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

-- | Specification for a required section with an implicit value
--   specification.
reqSection :: HasSpec a => Text -> Text -> SectionsSpec a

-- | Specification for an optional section with an implicit value
--   specification.
optSection :: HasSpec a => Text -> Text -> SectionsSpec (Maybe a)

-- | Specification for a required section with an explicit value
--   specification.
reqSection' :: Text -> ValueSpec a -> Text -> SectionsSpec a

-- | Specification for an optional section with an explicit value
--   specification.
optSection' :: Text -> ValueSpec a -> Text -> SectionsSpec (Maybe a)

-- | Laws:
--   
--   
--   <!> is associative:             (a <!> b) <!> c = a <!> (b <!> c)
--   <$> left-distributes over <!>:  f <$> (a <!> b) = (f <$> a) <!> (f <$> b)
--   
--   
--   If extended to an Alternative then <!> should
--   equal <|>.
--   
--   Ideally, an instance of Alt also satisfies the "left
--   distribution" law of MonadPlus with respect to <.>:
--   
--   
--   <.> right-distributes over <!>: (a <!> b) <.> c = (a <.> c) <!> (b <.> c)
--   
--   
--   IO, Either a, ExceptT e m and
--   STM instead satisfy the "left catch" law:
--   
--   
--   pure a <!> b = pure a
--   
--   
--   Maybe and Identity satisfy both "left distribution" and
--   "left catch".
--   
--   These variations cannot be stated purely in terms of the dependencies
--   of Alt.
--   
--   When and if MonadPlus is successfully refactored, this class should
--   also be refactored to remove these instances.
--   
--   The right distributive law should extend in the cases where the a
--   Bind or Monad is provided to yield variations of the
--   right distributive law:
--   
--   
--   (m <!> n) >>- f = (m >>- f) <!> (m >>- f)
--   (m <!> n) >>= f = (m >>= f) <!> (m >>= f)
--   
class Functor f => Alt (f :: Type -> Type)

-- | <|> without a required empty
(<!>) :: Alt f => f a -> f a -> f a
some :: (Alt f, Applicative f) => f a -> f [a]
many :: (Alt f, Applicative f) => f a -> f [a]
infixl 3 <!>
instance Config.Schema.Spec.HasSpec GHC.Types.Double
instance (Config.Schema.Spec.HasSpec a, Config.Schema.Spec.HasSpec b) => Config.Schema.Spec.HasSpec (GHC.Internal.Data.Either.Either a b)
instance Config.Schema.Spec.HasSpec GHC.Types.Float
instance Config.Schema.Spec.HasSpec GHC.Types.Int
instance Config.Schema.Spec.HasSpec GHC.Internal.Int.Int16
instance Config.Schema.Spec.HasSpec GHC.Internal.Int.Int32
instance Config.Schema.Spec.HasSpec GHC.Internal.Int.Int64
instance Config.Schema.Spec.HasSpec GHC.Internal.Int.Int8
instance Config.Schema.Spec.HasSpec GHC.Num.Integer.Integer
instance Config.Schema.Spec.HasSpec a => Config.Schema.Spec.HasSpec [a]
instance Config.Schema.Spec.HasSpec GHC.Num.Natural.Natural
instance Config.Schema.Spec.HasSpec a => Config.Schema.Spec.HasSpec (GHC.Internal.Base.NonEmpty a)
instance GHC.Internal.Real.Integral a => Config.Schema.Spec.HasSpec (GHC.Internal.Real.Ratio a)
instance Config.Schema.Spec.HasSpec Data.Text.Internal.Text
instance Config.Schema.Spec.HasSpec GHC.Types.Word
instance Config.Schema.Spec.HasSpec GHC.Internal.Word.Word16
instance Config.Schema.Spec.HasSpec GHC.Internal.Word.Word32
instance Config.Schema.Spec.HasSpec GHC.Internal.Word.Word64
instance Config.Schema.Spec.HasSpec GHC.Internal.Word.Word8

-- | This module provides a complete skeleton of the failures that occurred
--   when trying to match a Value against a ValueSpec
--   allowing custom error rendering to be implemented.
--   
--   The structure is you get a single value and a list of one-or-more
--   primitive specifications that it failed to match along with an
--   enumeration of why that specification failed to match. Some failures
--   are due to failures in nested specifications, so the whole error
--   structure can form a tree.
module Config.Schema.Load.Error

-- | Newtype wrapper for schema load errors.
data ValueSpecMismatch p

-- | Problem value and list of specification failures
ValueSpecMismatch :: p -> Text -> NonEmpty (PrimMismatch p) -> ValueSpecMismatch p

-- | Type for errors that can be encountered while decoding a value
--   according to a specification. The error includes a key path indicating
--   where in the configuration file the error occurred.
data PrimMismatch p

-- | spec description and problem
PrimMismatch :: Text -> Problem p -> PrimMismatch p

-- | Problems that can be encountered when matching a Value against
--   a ValueSpec.
data Problem p

-- | missing section name
MissingSection :: Text -> Problem p

-- | unused section names
UnusedSections :: NonEmpty Text -> Problem p

-- | nested error in given section
SubkeyProblem :: Text -> ValueSpecMismatch p -> Problem p

-- | nested error in given list element
ListElementProblem :: Int -> ValueSpecMismatch p -> Problem p

-- | generic nested error
NestedProblem :: ValueSpecMismatch p -> Problem p

-- | value and spec type mismatch
TypeMismatch :: Problem p

-- | custom spec error message
CustomProblem :: Text -> Problem p

-- | values didn't match
WrongExact :: Problem p

-- | Class for rendering position annotations within the
--   prettyValueSpecMismatch
class (Typeable a, Show a) => ErrorAnnotation a
displayAnnotation :: ErrorAnnotation a => a -> Doc

-- | Pretty-printer for ValueSpecMismatch showing the position and
--   type of value that failed to match along with details about each
--   specification that it didn't match.
prettyValueSpecMismatch :: ErrorAnnotation p => ValueSpecMismatch p -> Doc

-- | Pretty-printer for PrimMismatch showing a summary of the
--   primitive specification that didn't match followed by a more detailed
--   error when appropriate.
prettyPrimMismatch :: ErrorAnnotation p => PrimMismatch p -> Doc

-- | Pretty-printer for Problem that generates a summary line as
--   well as a detailed description (depending on the error)
prettyProblem :: ErrorAnnotation p => Problem p -> (Doc, Doc)

-- | Describe outermost shape of a PrimValueSpec
describeSpec :: PrimValueSpec a -> Text

-- | Describe outermost shape of a Value
describeValue :: Value p -> Text

-- | Simplify a ValueSpecMismatch by collapsing long nested error
--   cases and by assuming that if a type matched that the other mismatched
--   type alternatives are uninteresting. This is used in the
--   implementation of displayException.
simplifyValueSpecMismatch :: ValueSpecMismatch p -> ValueSpecMismatch p
instance Config.Schema.Load.Error.ErrorAnnotation Config.Macro.FilePosition
instance Config.Schema.Load.Error.ErrorAnnotation Config.Tokens.Position
instance Config.Schema.Load.Error.ErrorAnnotation ()
instance Config.Schema.Load.Error.ErrorAnnotation p => GHC.Internal.Exception.Type.Exception (Config.Schema.Load.Error.ValueSpecMismatch p)
instance GHC.Internal.Show.Show p => GHC.Internal.Show.Show (Config.Schema.Load.Error.PrimMismatch p)
instance GHC.Internal.Show.Show p => GHC.Internal.Show.Show (Config.Schema.Load.Error.Problem p)
instance GHC.Internal.Show.Show p => GHC.Internal.Show.Show (Config.Schema.Load.Error.ValueSpecMismatch p)

-- | This module automates the extraction of a decoded value from a
--   configuration value according to a specification as built using
--   Config.Schema.Spec.
module Config.Schema.Load

-- | Match a Value against a ValueSpec and return either the
--   interpretation of that value or the list of errors encountered.
loadValue :: ValueSpec a -> Value p -> Either (ValueSpecMismatch p) a

-- | Read a configuration file, parse it, and validate it according to the
--   given specification.
--   
--   Throws IOError, ParseError, or ValueSpecMismatch
loadValueFromFile :: ValueSpec a -> FilePath -> IO a

-- | Newtype wrapper for schema load errors.
data ValueSpecMismatch p

-- | Problem value and list of specification failures
ValueSpecMismatch :: p -> Text -> NonEmpty (PrimMismatch p) -> ValueSpecMismatch p

-- | Type for errors that can be encountered while decoding a value
--   according to a specification. The error includes a key path indicating
--   where in the configuration file the error occurred.
data PrimMismatch p

-- | spec description and problem
PrimMismatch :: Text -> Problem p -> PrimMismatch p

-- | Problems that can be encountered when matching a Value against
--   a ValueSpec.
data Problem p

-- | missing section name
MissingSection :: Text -> Problem p

-- | unused section names
UnusedSections :: NonEmpty Text -> Problem p

-- | nested error in given section
SubkeyProblem :: Text -> ValueSpecMismatch p -> Problem p

-- | nested error in given list element
ListElementProblem :: Int -> ValueSpecMismatch p -> Problem p

-- | generic nested error
NestedProblem :: ValueSpecMismatch p -> Problem p

-- | value and spec type mismatch
TypeMismatch :: Problem p

-- | custom spec error message
CustomProblem :: Text -> Problem p

-- | values didn't match
WrongExact :: Problem p

-- | This module generates a simple textual documentation format for a
--   configuration schema. Each subsection and named value specification
--   will generate it's own top-level component in the documentation.
--   
--   This module is only one of the ways one could generate documentation
--   for a particular configuration specification. All of the defintions
--   would would need to be able to generate another form are exported by
--   Config.Schema.Spec.
--   
--   
--   configSpec :: ValueSpec (Text,Maybe Int)
--   configSpec = sectionsSpec ""
--              $ liftA2 (,)
--                  (reqSection "username" "Name used to login")
--                  (optSection "attempts" "Number of login attempts")
--   
--   generateDocs configSpec
--   
--   -- Top-level configuration file fields:
--   --     username: REQUIRED text
--   --        Name used to login
--   --     attempts: integer
--   --        Number of login attempts
--   
module Config.Schema.Docs

-- | Default documentation generator.
generateDocs :: ValueSpec a -> Doc
instance GHC.Internal.Base.Applicative Config.Schema.Docs.DocBuilder
instance GHC.Internal.Base.Functor Config.Schema.Docs.DocBuilder
instance GHC.Internal.Base.Monad Config.Schema.Docs.DocBuilder
instance (GHC.Internal.Base.Semigroup a, GHC.Internal.Base.Monoid a) => GHC.Internal.Base.Monoid (Config.Schema.Docs.DocBuilder a)
instance GHC.Internal.Base.Semigroup a => GHC.Internal.Base.Semigroup (Config.Schema.Docs.DocBuilder a)

-- | This package makes it possible to define schemas for configuration
--   files. These schemas can be used to generate a validating
--   configuration file loader, and to produce documentation about the
--   supported format.
--   
--   For documentation on the config-value file format, see the
--   Config module.
--   
--   Config.Schema.Spec provides definitions used to make new
--   schemas.
--   
--   Config.Schema.Load uses schemas to match schemas against
--   configuration values.
--   
--   Config.Schema.Docs generates textual documentation for a
--   schema.
module Config.Schema
