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


-- | The next generation of configuration management
--   
--   A configuration management library for programs and daemons.
--   
--   Features include:
--   
--   <ul>
--   <li>A simple, but flexible, configuration language, supporting several
--   of the most commonly needed types of data, along with interpolation of
--   strings from the configuration or the system environment (e.g.
--   <tt>$(HOME)</tt>).</li>
--   <li>An <tt>import</tt> directive allows the configuration of a complex
--   application to be split across several smaller files, or common
--   configuration data to be shared across several applications.</li>
--   <li>An expressive applicative/monadic high-level parsing interface to
--   gracefully scale to more complicated configuration needs, with
--   powerful diagnostic messaging mechanism.</li>
--   </ul>
--   
--   For details of the configuration file format, see
--   <a>http://hackage.haskell.org/packages/archive/configurator/latest/doc/html/Data-Configurator.html</a>.
@package configurator-ng
@version 0.0.0.1


-- | Types for working with configuration files.
module Data.Configurator.Types

-- | Directions for automatically reloading <tt>Config</tt> data.
data AutoConfig
AutoConfig :: Int -> (SomeException -> IO ()) -> AutoConfig

-- | Interval (in seconds) at which to check for updates to config files.
--   The smallest allowed interval is one second.
[interval] :: AutoConfig -> Int

-- | Action invoked when an attempt to reload a <tt>Config</tt> or notify a
--   <a>ChangeHandler</a> causes an exception to be thrown.
--   
--   If this action rethrows its exception or throws a new exception, the
--   modification checking thread will be killed. You may want your
--   application to treat that as a fatal error, as its configuration may
--   no longer be consistent.
[onError] :: AutoConfig -> SomeException -> IO ()

-- | Global configuration data. This is the top-level config from which
--   <tt>Config</tt> values are derived by choosing a root location.
data ConfigCache

-- | The name of a <tt>Config</tt> value.
type Name = Text

-- | A value in a <tt>Config</tt>.
data Value

-- | A Boolean. Represented in a configuration file as <tt>on</tt> or
--   <tt>off</tt>, <tt>true</tt> or <tt>false</tt> (case sensitive).
Bool :: Bool -> Value

-- | A Unicode string. Represented in a configuration file as text
--   surrounded by double quotes.
--   
--   Escape sequences:
--   
--   <ul>
--   <li><tt>\n</tt> - newline</li>
--   <li><tt>\r</tt> - carriage return</li>
--   <li><tt>\t</tt> - horizontal tab</li>
--   <li><tt>\\</tt> - backslash</li>
--   <li><tt>\"</tt> - quotes</li>
--   <li><tt>\u</tt><i>xxxx</i> - Unicode character, encoded as four
--   hexadecimal digits</li>
--   <li><tt>\u</tt><i>xxxx</i><tt>\u</tt><i>xxxx</i> - Unicode character
--   (as two UTF-16 surrogates)</li>
--   </ul>
String :: Text -> Value

-- | Integer.
Number :: Scientific -> Value

-- | Heterogeneous list. Represented in a configuration file as an opening
--   square bracket "<tt>[</tt>", followed by a comma-separated series of
--   values, ending with a closing square bracket "<tt>]</tt>".
List :: [Value] -> Value
data Worth a
Required :: a -> Worth a
[worth] :: Worth a -> a
Optional :: a -> Worth a
[worth] :: Worth a -> a

-- | An error occurred during the low-level parsing of a configuration
--   file.
data ParseError
ParseError :: FilePath -> String -> ParseError

-- | An error (or warning) from a higher-level parser of a configuration
--   file.
data ConfigError
ConfigError :: ConfigErrorLocation -> Maybe [ConversionError] -> ConfigError
[configErrorLocation] :: ConfigError -> ConfigErrorLocation
[configConversionError] :: ConfigError -> Maybe [ConversionError]
data ConfigErrorLocation
KeyMissing :: [Name] -> ConfigErrorLocation
Key :: FilePath -> Name -> ConfigErrorLocation
data ConversionError
ConversionError :: Text -> ConversionErrorWhy -> !(Maybe Value) -> !(Maybe TypeRep) -> !(Maybe Text) -> ConversionError
[conversionErrorLoc] :: ConversionError -> Text
[conversionErrorWhy] :: ConversionError -> ConversionErrorWhy
[conversionErrorVal] :: ConversionError -> !(Maybe Value)
[conversionErrorType] :: ConversionError -> !(Maybe TypeRep)
[conversionErrorMsg] :: ConversionError -> !(Maybe Text)
data ConversionErrorWhy
MissingValue :: ConversionErrorWhy
ExtraValues :: ConversionErrorWhy
ExhaustedValues :: ConversionErrorWhy
TypeError :: ConversionErrorWhy
ValueError :: ConversionErrorWhy
MonadFail :: ConversionErrorWhy
OtherError :: ConversionErrorWhy
defaultConversionError :: ConversionError

-- | An error occurred while lookup up the given <a>Name</a>.
data KeyError
KeyError :: Name -> KeyError

-- | A pattern specifying the name of a property that has changed.
--   
--   This type is an instance of the <a>IsString</a> class. If you use the
--   <tt>OverloadedStrings</tt> language extension and want to write a
--   <a>prefix</a>-matching pattern as a literal string, do so by suffixing
--   it with "<tt>.*</tt>", for example as follows:
--   
--   <pre>
--   "foo.*"
--   </pre>
--   
--   If a pattern written as a literal string does not end with
--   "<tt>.*</tt>", it is assumed to be <a>exact</a>.
data Pattern

-- | An action to be invoked if a configuration property is changed.
--   
--   If this action is invoked and throws an exception, the <a>onError</a>
--   function will be called.
type ChangeHandler = Name  Name of the changed property. -> Maybe Value  Its new value, or 'Nothing' if it has vanished. -> IO ()


module Data.Configurator.FromValue.Internal
type ConversionErrors = MultiErrors ConversionError

-- | An action to turn a <a>Value</a> into zero or one values of type
--   <tt>a</tt>, and possibly report errors/warnings.
newtype ValueParser a
ValueParser :: (Value -> (Maybe a, ConversionErrors)) -> ValueParser a
[unValueParser] :: ValueParser a -> Value -> (Maybe a, ConversionErrors)

-- | An action to turn a <a>Maybe</a> <a>Value</a> into zero or one values
--   of type <tt>a</tt>, and possibly report errors/warnings.
newtype MaybeParser a
MaybeParser :: (Maybe Value -> (Maybe a, ConversionErrors)) -> MaybeParser a
[unMaybeParser] :: MaybeParser a -> Maybe Value -> (Maybe a, ConversionErrors)
data ListParserResult a
NonListError :: ListParserResult a
ListError :: ListParserResult a
ListOk :: a -> [Value] -> ListParserResult a

-- | An action to turn a <tt>[<a>Value</a>]</tt> into zero or one values of
--   type <tt>a</tt>, and possibly report errors/warnings.
newtype ListParser a
ListParser :: ([Value] -> (ListParserResult a, ConversionErrors)) -> ListParser a
[unListParser] :: ListParser a -> [Value] -> (ListParserResult a, ConversionErrors)


module Data.Configurator.FromValue

-- | An action to turn a <a>Maybe</a> <a>Value</a> into zero or one values
--   of type <tt>a</tt>, and possibly report errors/warnings.
data MaybeParser a
runMaybeParser :: MaybeParser a -> Maybe Value -> (Maybe a, [ConversionError])
class FromMaybeValue a where fromMaybeValue = requiredValue fromValue
fromMaybeValue :: FromMaybeValue a => MaybeParser a
fromMaybeValue :: (FromMaybeValue a, Typeable a, FromValue a) => MaybeParser a

-- | Turns a <a>ValueParser</a> into a <a>MaybeParser</a>. If the
--   <a>Maybe</a> <a>Value</a> the parser is passed is <a>Nothing</a>
--   (which normally means a key was not found), then this returns the
--   <tt>Nothing</tt> value with no errors or warnings. Otherwise, it
--   passes the <a>Value</a> to the subparser. If the subparser returns a
--   result value, then this returns <a>Just</a> the value. Otherwise, if
--   the subparser does not return a value, then this does not return a
--   value.
--   
--   Any errors/warnings returned by the subparser are returned exactly
--   as-is.
optionalValue :: ValueParser a -> MaybeParser (Maybe a)

-- | Turns a <a>ValueParser</a> into a <a>MaybeParser</a>. If the
--   <a>Maybe</a> <a>Value</a> the parser is passed is <a>Nothing</a>
--   (which normally means a key was not found), then this does not return
--   a value and also returns a <a>missingValueError</a>. Otherwise, the
--   <a>Value</a> is passed to the subparser, and the result and any
--   errors/warnings are returned as-is.
requiredValue :: forall a. Typeable a => ValueParser a -> MaybeParser a

-- | An action to turn a <a>Value</a> into zero or one values of type
--   <tt>a</tt>, and possibly report errors/warnings.
data ValueParser a
runValueParser :: ValueParser a -> Value -> (Maybe a, [ConversionError])
class FromValue a
fromValue :: FromValue a => ValueParser a

-- | An action to turn a <tt>[<a>Value</a>]</tt> into zero or one values of
--   type <tt>a</tt>, and possibly report errors/warnings.
data ListParser a
class FromListValue a
fromListValue :: FromListValue a => ListParser a

-- | Turns a <a>ListParser</a> into a <a>ValueParser</a>. It first checks
--   that the <a>Value</a> the <a>ValueParser</a> is passed is a
--   <a>List</a> Value. If it's not, this returns no result as well as a
--   <a>typeError</a>. Otherwise, it passes the list of results to the
--   <a>ListParser</a> subparser.
--   
--   If the subparser consumes all of the list elements, this returns the
--   value and errors as-is. If there are leftover list elements, this
--   returns the value, and adds a message warning of the extra elements to
--   the list of errors.
--   
--   The difference from 'listValue\'' is that this returns values with
--   unconsumed list elements (discarding the list elements).
listValue :: forall a. Typeable a => ListParser a -> ValueParser a

-- | Turns a <a>ListParser</a> into a <a>ValueParser</a>. It first checks
--   that the <a>Value</a> the <a>ValueParser</a> is passed is a
--   <a>List</a> Value. If it's not, this returns no result as well as a
--   <a>typeError</a>. Otherwise, it passes the list of results to the
--   <a>ListParser</a> subparser.
--   
--   If the subparser consumes all of the list elements, this returns the
--   value and errors as-is. If there are leftover list elements, this
--   returns no value, and adds a message warning of the extra elements to
--   the list of errors.
--   
--   The difference from <a>listValue</a> is that this never returns a
--   value if there are unconsumed list elements. (discarding both the
--   value returned and the list element.)
listValue' :: forall a. Typeable a => ListParser a -> ValueParser a

-- | Turns a <a>ValueParser</a> into a <a>ListParser</a> that consumes a
--   single element.
--   
--   If there are no list elements left, this returns list error value and
--   an <a>ExhaustedValues</a> error.
--   
--   If there is an element left, it is passed to the value parser. If the
--   value parser returns a value, it is returned along with the errors
--   as-is. If the value parser returns no value, then this returns a
--   non-list error value and the list of errors returned by the value
--   parser.
--   
--   The difference between a "list error value" and a "non-list error
--   value", is that the <a>Alternative</a> instance for <a>ListParser</a>
--   recovers from "list error" values but does not recover from "non-list
--   error" values. This behavior was chosen so that the <a>optional</a>,
--   <a>some</a>, and <a>many</a> combinators work on <a>ListParser</a>s in
--   a way that is hopefully least surprising.
listElem :: forall a. (Typeable a) => ValueParser a -> ListParser a
data ConversionError
ConversionError :: Text -> ConversionErrorWhy -> !(Maybe Value) -> !(Maybe TypeRep) -> !(Maybe Text) -> ConversionError
[conversionErrorLoc] :: ConversionError -> Text
[conversionErrorWhy] :: ConversionError -> ConversionErrorWhy
[conversionErrorVal] :: ConversionError -> !(Maybe Value)
[conversionErrorType] :: ConversionError -> !(Maybe TypeRep)
[conversionErrorMsg] :: ConversionError -> !(Maybe Text)
data ConversionErrorWhy
MissingValue :: ConversionErrorWhy
ExtraValues :: ConversionErrorWhy
ExhaustedValues :: ConversionErrorWhy
TypeError :: ConversionErrorWhy
ValueError :: ConversionErrorWhy
MonadFail :: ConversionErrorWhy
OtherError :: ConversionErrorWhy
defaultConversionError :: ConversionError
boundedIntegerValue :: forall a. (Typeable a, Integral a, Bounded a) => ValueParser a
integralValue :: forall a. (Typeable a, Integral a) => ValueParser a
fractionalValue :: forall a. (Typeable a, Fractional a) => ValueParser a
realFloatValue :: forall a. (Typeable a, RealFloat a) => ValueParser a
fixedValue :: forall a. (Typeable a, HasResolution a) => ValueParser (Fixed a)
scientificValue :: ValueParser Scientific
textValue :: ValueParser Text
charValue :: ValueParser Char
typeError :: Text -> Value -> TypeRep -> ConversionError
valueError :: Text -> Value -> TypeRep -> Text -> ConversionError
extraValuesError :: Text -> [Value] -> TypeRep -> ConversionError
missingValueError :: Text -> TypeRep -> ConversionError


module Data.Configurator.Config.Internal

-- | A <a>Config</a> is a finite map from <a>Text</a> to <a>Value</a>.
newtype Config
Config :: (ConfigMap Value) -> Config
type ConfigMap a = ConfigPlan (CritBit Text a)
data ConfigPlan a
Subconfig :: Text -> (ConfigPlan a) -> ConfigPlan a
Superconfig :: Text -> (ConfigPlan a) -> ConfigPlan a
Union :: (ConfigPlan a) -> (ConfigPlan a) -> ConfigPlan a
ConfigPlan :: a -> ConfigPlan a
Empty :: ConfigPlan a
lookup :: Text -> ConfigMap a -> Maybe a
lookupWithName :: Name -> ConfigMap a -> Maybe (Name, a)
subgroups :: Text -> ConfigMap a -> [Text]

-- | FIXME: improve this implementation.
subassocs :: Text -> ConfigMap a -> [(Text, a)]
null :: ConfigPlan (CritBit Text a) -> Bool
subconfig :: Text -> ConfigMap a -> ConfigMap a
superconfig :: Text -> ConfigMap a -> ConfigMap a
union :: ConfigMap a -> ConfigMap a -> ConfigMap a
subassocs_ :: (Text -> a -> [(Text, b)]) -> Text -> ConfigPlan a -> [(Text, b)]
foldPlan :: b -> (b -> b -> b) -> (Text -> a -> b) -> Text -> ConfigPlan a -> b
submap :: Text -> CritBit Text a -> CritBit Text a
subgroupsMap :: Text -> CritBit Text a -> [Text]
addPrefix :: Name -> Name -> Name
stripPrefix :: Name -> Name -> Maybe Name


-- | This module provides the abstract data structure that backs
--   <tt>ConfigCache</tt> and that <tt>ConfigParser</tt>s operate on.
--   
--   It shouldn't be necessary to use this module much, if at all, in
--   client code. It might be considered semi-internal. Please file a issue
--   if you find a need to use it.
module Data.Configurator.Config

-- | A <a>Config</a> is a finite map from <a>Text</a> to <a>Value</a>.
data Config
empty :: Config
null :: Config -> Bool
lookup :: Name -> Config -> Maybe Value
lookupWithName :: Name -> Config -> Maybe (Name, Value)
subgroups :: Name -> Config -> [Name]
subassocs :: Name -> Config -> [(Name, Value)]
subassocs' :: Name -> Config -> [(Name, Value)]
union :: Config -> Config -> Config
subconfig :: Name -> Config -> Config
superconfig :: Name -> Config -> Config


-- | A set of combinators for high-level configuration parsing.
module Data.Configurator.Parser

-- | A <a>ConfigParser</a> computation produces a value of type
--   <tt><a>Maybe</a> a</tt> from a given <a>Config</a>, in addition to a
--   list of diagnostic messages, which may be interpreted as warnings or
--   errors as deemed appropriate. The type class abstracts over
--   <a>ConfigParserM</a> and <a>ConfigParserA</a> variants, which are
--   isomorphic but have different <a>Applicative</a> and <a>Monad</a>
--   instances. This is intended to be a closed typeclass, without any
--   additional instances.
class Applicative m => ConfigParser m
runParser :: ConfigParser m => m a -> Config -> (Maybe a, [ConfigError])

-- | After executing a subcomputation that returns a <a>Nothing</a> value,
--   computations of type <a>ConfigParserA</a> will continue to run in
--   order to produce more error messages. For this reason,
--   <a>ConfigParserA</a> does not have a proper <a>Monad</a> instance.
--   (But see <a>unsafeBind</a>)
data ConfigParserA a

-- | Exactly the same as <a>runParser</a>, except less polymorphic
runParserA :: ConfigParserA a -> Config -> (Maybe a, [ConfigError])

-- | Lift a <a>ConfigParserA</a> action into a generic <a>ConfigParser</a>
--   action. Note that this does not change the semantics of the argument,
--   it just allows a <a>ConfigParserA</a> computation to be embedded in
--   another <a>ConfigParser</a> computation of either variant.
parserA :: ConfigParser m => ConfigParserA a -> m a

-- | The purpose of this function is to make it convenient to use
--   do-notation with <a>ConfigParserA</a>, either by defining a Monad
--   instance or locally rebinding <a>&gt;&gt;=</a>. Be warned that this is
--   an abuse, and incorrect usage can result in exceptions. A safe way to
--   use this function would be to treat is as applicative-do notation. A
--   safer alternative would be to use the <tt>ApplicativeDo</tt> language
--   extension available in GHC 8.0 and not use this function at all.

-- | <i>Deprecated: Use the ApplicativeDo language extension instead</i>
unsafeBind :: ConfigParserA a -> (a -> ConfigParserA b) -> ConfigParserA b

-- | If the value returned by a computation is <a>Nothing</a>, then no
--   subsequent actions (e.g. via <a>&lt;*&gt;</a> or <a>&gt;&gt;=</a>)
--   will be performed.
data ConfigParserM a

-- | Exactly the same as <a>runParser</a>, except less polymorphic
runParserM :: ConfigParserM a -> Config -> (Maybe a, [ConfigError])

-- | Lift a <a>ConfigParserM</a> action into a generic <a>ConfigParser</a>
--   action. Note that this does not change the semantics of the argument,
--   it just allows a <a>ConfigParserM</a> computation to be embedded in
--   another <a>ConfigParser</a> computation of either variant.
parserM :: ConfigParser m => ConfigParserM a -> m a

-- | Given the expression <tt><a>recover</a> action</tt>, the
--   <tt>action</tt> will be run, and if it returns no value, <tt>recover
--   action</tt> will return <a>Nothing</a>. If <tt>action</tt> returns the
--   value <tt>a</tt>, then <tt>recover action</tt> will return the value
--   <tt><a>Just</a> a</tt>. Any errors or warnings are passed through
--   as-is.
recover :: ConfigParser m => m a -> m (Maybe a)

-- | Look up a given value in the current configuration context, and
--   convert the value using the <a>fromMaybeValue</a> method.
key :: (ConfigParser m, FromMaybeValue a) => Name -> m a

-- | Look up a given value in the current configuration context, and
--   convert the value using the <a>MaybeParser</a> argument.
keyWith :: (ConfigParser m) => Name -> MaybeParser a -> m a

-- | Returns all the non-empty value groupings that is directly under the
--   argument grouping in the current configuration context. For example,
--   given the following context:
--   
--   <pre>
--   foo { }
--   bar {
--     a {
--       x = 1
--     }
--     b {
--       c {
--         y = 2
--       }
--     }
--   }
--   default
--     a {
--       x = 3
--     }
--   }
--   </pre>
--   
--   Then the following arguments to <a>subgroups</a> would return the
--   following lists:
--   
--   <pre>
--   subgroups ""         ==&gt;  [ "bar", "default" ]
--   subgroups "bar"      ==&gt;  [ "bar.a", "bar.b" ]
--   subgroups "bar.b"    ==&gt;  [ "bar.b.c" ]
--   subgroups "default"  ==&gt;  [ "default.a" ]
--   </pre>
--   
--   All other arguments to <tt>subgroups</tt> would return <tt>[]</tt> in
--   the given context.
subgroups :: ConfigParser m => Name -> m [Name]

-- | Returns all the value bindings from the current configuration context
--   that is contained within the given subgroup, in lexicographic order.
--   For example, given the following context:
--   
--   <pre>
--   x = 1
--   foo {
--     x = 2
--     bar {
--       y = on
--     }
--   }
--   foo = "Hello"
--   </pre>
--   
--   Then the following arguments to <a>subassocs</a> would return the
--   following lists:
--   
--   <pre>
--   subassocs ""         ==&gt;  [("foo",String "Hello"),("x",Number 1)]
--   subassocs "foo"      ==&gt;  [("foo.x",Number 2)]
--   subassocs "foo.bar"  ==&gt;  [("foo.bar.x",Bool True)]
--   </pre>
--   
--   All other arguments to <tt>subassocs</tt> would return <tt>[]</tt> in
--   the given context.
subassocs :: ConfigParser m => Name -> m [(Name, Value)]

-- | Returns all the value bindings from the current configuration context
--   that is contained within the given subgroup and all of it's subgroups
--   in lexicographic order. For example, given the following context:
--   
--   <pre>
--   x = 1
--   foo {
--     x = 2
--     bar {
--       y = on
--     }
--   }
--   foo = "Hello"
--   </pre>
--   
--   Then the following arguments to 'subassocs\'' would return the
--   following lists:
--   
--   <pre>
--   subassocs' ""         ==&gt;  [ ("foo"       , String "Hello")
--                              , ("foo.bar.y" , Bool True     )
--                              , ("foo.x"     , Number 2      )
--                              , ("x"         , Number 1      )
--                              ]
--   subassocs' "foo"      ==&gt;  [ ("foo.bar.y" , Bool True     )
--                              , ("foo.x"     , Number 2      )
--                              ]
--   subassocs' "foo.bar"  ==&gt;  [ ("foo.bar.y" , Bool True     )
--                              ]
--   </pre>
--   
--   All other arguments to <tt>subassocs'</tt> would return <tt>[]</tt> in
--   the given context.
subassocs' :: ConfigParser m => Name -> m [(Name, Value)]

-- | A <a>Config</a> is a finite map from <a>Text</a> to <a>Value</a>.
data Config

-- | Conceptually, a <a>ConfigTransform</a> is a function <a>Config</a>
--   <tt>-&gt;</tt> <a>Config</a>. It's a restricted subset of such
--   functions as to preserve the possibility of reliable dependency
--   tracking in later versions of configurator-ng.
data ConfigTransform

-- | Modifies the <a>Config</a> that a subparser is operating on. This is
--   perfectly analogous to <a>local</a>.
localConfig :: ConfigParser m => ConfigTransform -> m a -> m a

-- | Conceptually, <tt><a>union</a> f g = \config -&gt; union' (f config)
--   (g config)</tt>, where <tt>union'</tt> is the left-biased union of two
--   <a>Config</a>s.
union :: ConfigTransform -> ConfigTransform -> ConfigTransform

-- | <tt><a>subconfig</a> group</tt> restricts the configuration to those
--   values that are contained within <tt>group</tt> (either directly, or
--   contained within a descendant value grouping), and removes the
--   <tt>group</tt> prefix from all of the keys in the map. It's analogous
--   to the <tt>cd</tt> (change directory) command on common operating
--   systems, except that <tt>subconfig</tt> can only descend down the
--   directory tree, and cannot ascend into a parent directory.
subconfig :: Text -> ConfigTransform -> ConfigTransform

-- | <tt><a>superconfig</a> group</tt> adds the <tt>group</tt> prefix to
--   all keys in the map. It is vaguely analogous to the <tt>mount</tt>
--   command on unix operating systems.
superconfig :: Text -> ConfigTransform -> ConfigTransform

-- | An error (or warning) from a higher-level parser of a configuration
--   file.
data ConfigError
ConfigError :: ConfigErrorLocation -> Maybe [ConversionError] -> ConfigError
[configErrorLocation] :: ConfigError -> ConfigErrorLocation
[configConversionError] :: ConfigError -> Maybe [ConversionError]
data ConfigErrorLocation
KeyMissing :: [Name] -> ConfigErrorLocation
Key :: FilePath -> Name -> ConfigErrorLocation
data ConversionError
ConversionError :: Text -> ConversionErrorWhy -> !(Maybe Value) -> !(Maybe TypeRep) -> !(Maybe Text) -> ConversionError
[conversionErrorLoc] :: ConversionError -> Text
[conversionErrorWhy] :: ConversionError -> ConversionErrorWhy
[conversionErrorVal] :: ConversionError -> !(Maybe Value)
[conversionErrorType] :: ConversionError -> !(Maybe TypeRep)
[conversionErrorMsg] :: ConversionError -> !(Maybe Text)
data ConversionErrorWhy
MissingValue :: ConversionErrorWhy
ExtraValues :: ConversionErrorWhy
ExhaustedValues :: ConversionErrorWhy
TypeError :: ConversionErrorWhy
ValueError :: ConversionErrorWhy
MonadFail :: ConversionErrorWhy
OtherError :: ConversionErrorWhy


module Data.Configurator.Parser.Internal
type RMW r w a = r -> (Maybe a, w)
type ConfigErrors = Maybe (DList ConfigError)

-- | A <a>ConfigParser</a> computation produces a value of type
--   <tt><a>Maybe</a> a</tt> from a given <a>Config</a>, in addition to a
--   list of diagnostic messages, which may be interpreted as warnings or
--   errors as deemed appropriate. The type class abstracts over
--   <a>ConfigParserM</a> and <a>ConfigParserA</a> variants, which are
--   isomorphic but have different <a>Applicative</a> and <a>Monad</a>
--   instances. This is intended to be a closed typeclass, without any
--   additional instances.
class Applicative m => ConfigParser m
configParser_ :: ConfigParser m => RMW Config ConfigErrors a -> m a
unConfigParser_ :: ConfigParser m => m a -> RMW Config ConfigErrors a

-- | If the value returned by a computation is <a>Nothing</a>, then no
--   subsequent actions (e.g. via <a>&lt;*&gt;</a> or <a>&gt;&gt;=</a>)
--   will be performed.
newtype ConfigParserM a
ConfigParserM :: RMW Config ConfigErrors a -> ConfigParserM a
[unConfigParserM] :: ConfigParserM a -> RMW Config ConfigErrors a

-- | After executing a subcomputation that returns a <a>Nothing</a> value,
--   computations of type <a>ConfigParserA</a> will continue to run in
--   order to produce more error messages. For this reason,
--   <a>ConfigParserA</a> does not have a proper <a>Monad</a> instance.
--   (But see <a>unsafeBind</a>)
newtype ConfigParserA a
ConfigParserA :: RMW Config ConfigErrors a -> ConfigParserA a
[unConfigParserA] :: ConfigParserA a -> RMW Config ConfigErrors a

-- | Conceptually, a <a>ConfigTransform</a> is a function <a>Config</a>
--   <tt>-&gt;</tt> <a>Config</a>. It's a restricted subset of such
--   functions as to preserve the possibility of reliable dependency
--   tracking in later versions of configurator-ng.
newtype ConfigTransform
ConfigTransform :: (ConfigPlan ()) -> ConfigTransform
interpConfigTransform :: ConfigTransform -> Config -> Config


-- | A simple (yet powerful) library for working with configuration files.
--   
--   Note that while the <a>Data.Configurator.Parser</a> and
--   <a>Data.Configurator.FromValue</a> should be quite stable at this
--   point, this module is likely to be subjected to significant breaking
--   changes in subsequent versions of configurator-ng. So please do file
--   an issue if you have any opinions or especially needs with regards to
--   configuration (re)loading, change notifications, etc.
module Data.Configurator
data Worth a
Required :: a -> Worth a
[worth] :: Worth a -> a
Optional :: a -> Worth a
[worth] :: Worth a -> a

-- | Load a <a>ConfigCache</a> from the given <a>FilePath</a>s, and start a
--   reload thread.
--   
--   At intervals, a thread checks for modifications to both the original
--   files and any files they refer to in <tt>import</tt> directives, and
--   reloads the <a>ConfigCache</a> if any files have been modified.
--   
--   If the initial attempt to load the configuration files fails, an
--   exception is thrown. If the initial load succeeds, but a subsequent
--   attempt fails, the <a>onError</a> handler is invoked.
--   
--   File names have any environment variables expanded prior to the first
--   time they are opened, so you can specify a file name such as
--   <tt>"$(HOME)/myapp.cfg"</tt>.
autoReload :: AutoConfig -> [Worth FilePath] -> IO (ConfigCache, ThreadId)
autoReloadGroups :: AutoConfig -> [(Name, Worth FilePath)] -> IO (ConfigCache, ThreadId)

-- | Defaults for automatic <a>Config</a> reloading when using
--   <a>autoReload</a>. The <a>interval</a> is one second, while the
--   <a>onError</a> action ignores its argument and does nothing.
autoConfig :: AutoConfig

-- | A pattern that matches on a prefix of a property name. Given
--   <tt>"foo"</tt>, this will match <tt>"foo.bar"</tt>, but not
--   <tt>"foo"</tt> or <tt>"foobar"</tt>.
prefix :: Text -> Pattern

-- | A pattern that must match exactly.
exact :: Text -> Pattern

-- | Subscribe for notifications. The given action will be invoked when any
--   change occurs to a configuration property matching the supplied
--   pattern.
subscribe :: ConfigCache -> Pattern -> ChangeHandler -> IO ()

-- | Create a <a>ConfigCache</a> from the contents of the named files.
--   Throws an exception on error, such as if files do not exist or contain
--   errors.
--   
--   File names have any environment variables expanded prior to the first
--   time they are opened, so you can specify a file name such as
--   <tt>"$(HOME)/myapp.cfg"</tt>.
load :: [Worth FilePath] -> IO ConfigCache

-- | Create a <a>ConfigCache</a> from the contents of the named files,
--   placing them into named prefixes. If a prefix is non-empty, it should
--   end in a dot.
loadGroups :: [(Name, Worth FilePath)] -> IO ConfigCache

-- | Forcibly reload a <a>ConfigCache</a>. Throws an exception on error,
--   such as if files no longer exist or contain errors.
reload :: ConfigCache -> IO ()

-- | Add additional files to a <a>ConfigCache</a>, causing it to be
--   reloaded to add their contents.
addToConfig :: [Worth FilePath] -> ConfigCache -> IO ()

-- | Add additional files to named groups in a <a>ConfigCache</a>, causing
--   it to be reloaded to add their contents. If the prefixes are
--   non-empty, they should end in dots.
addGroupsToConfig :: [(Name, Worth FilePath)] -> ConfigCache -> IO ()

-- | Perform a simple dump of a <a>ConfigCache</a> to <tt>stdout</tt>.
display :: ConfigCache -> IO ()

-- | Read the current configuration stored in the cache.
readConfig :: ConfigCache -> IO Config
