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

-- | Configuration management
--   
--   A configuration management library for programs and daemons.
--   
--   Features include:
--   
--   
--   
- Automatic, dynamic reloading in response to modifications to
--   configuration files.
--   
- 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.
--   $(HOME)).
--   
- Subscription-based notification of changes to configuration
--   properties.
--   
- An import 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.
--   
--   
--   For details of the configuration file format, see
--   http://hackage.haskell.org/packages/archive/configurator/latest/doc/html/Data-Configurator.html.
@package configurator
@version 0.3.0.0

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

-- | Directions for automatically reloading Config 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 Config or notify a
--   ChangeHandler 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 ()

-- | Configuration data.
data Config

-- | The name of a Config value.
type Name = Text

-- | A value in a Config.
data Value

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

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

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

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

-- | This class represents types that can be automatically and safely
--   converted from a Value to a destination type. If
--   conversion fails because the types are not compatible, Nothing
--   is returned.
--   
--   For an example of compatibility, a Value of Bool
--   True cannot be converted to an Int.
class Configured a
convert :: Configured a => Value -> Maybe a
data Worth a
Required :: a -> Worth a
[worth] :: Worth a -> a
Optional :: a -> Worth a
[worth] :: Worth a -> a

-- | An error occurred while processing a configuration file.
data ConfigError
ParseError :: FilePath -> String -> ConfigError

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

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

-- | An action to be invoked if a configuration property is changed.
--   
--   If this action is invoked and throws an exception, the onError
--   function will be called.
type ChangeHandler = Name -> Maybe Value -> IO ()

-- | A simple (yet powerful) library for working with configuration files.
module Data.Configurator
data Worth a
Required :: a -> Worth a
[worth] :: Worth a -> a
Optional :: a -> Worth a
[worth] :: Worth a -> a

-- | Load a Config from the given FilePaths, and start a
--   reload thread.
--   
--   At intervals, a thread checks for modifications to both the original
--   files and any files they refer to in import directives, and
--   reloads the Config 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 onError 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
--   "$(HOME)/myapp.cfg".
autoReload :: AutoConfig -> [Worth FilePath] -> IO (Config, ThreadId)
autoReloadGroups :: AutoConfig -> [(Name, Worth FilePath)] -> IO (Config, ThreadId)

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

-- | A completely empty configuration.
empty :: Config

-- | Look up a name in the given Config. If a binding exists, and
--   the value can be converted to the desired type, return the
--   converted value, otherwise Nothing.
lookup :: Configured a => Config -> Name -> IO (Maybe a)

-- | Look up a name in the given Config. If a binding exists, and
--   the value can be converted to the desired type, return it, otherwise
--   return the default value.
lookupDefault :: Configured a => a -> Config -> Name -> IO a

-- | Look up a name in the given Config. If a binding exists, and
--   the value can be converted to the desired type, return the
--   converted value, otherwise throw a KeyError.
require :: Configured a => Config -> Name -> IO a

-- | A pattern that matches on a prefix of a property name. Given
--   "foo", this will match "foo.bar", but not
--   "foo" or "foobar".
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 :: Config -> Pattern -> ChangeHandler -> IO ()

-- | Create a Config 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
--   "$(HOME)/myapp.cfg".
load :: [Worth FilePath] -> IO Config

-- | Create a Config 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 Config

-- | Forcibly reload a Config. Throws an exception on error, such as
--   if files no longer exist or contain errors. If the provided
--   Config is a subconfig, this will reload the entire
--   top-level configuration, not just the local section.
reload :: Config -> IO ()

-- | Gives a Config corresponding to just a single group of the
--   original Config. The subconfig can be used just like the
--   original Config, but see the documentation for reload.
subconfig :: Name -> Config -> Config

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

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

-- | Perform a simple dump of a Config to stdout.
display :: Config -> IO ()

-- | Fetch the HashMap that maps names to values.
getMap :: Config -> IO (HashMap Name Value)
