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


-- | Configuration management
--   
--   A configuration management library for programs and daemons.
--   
--   Features include:
--   
--   <ul>
--   <li>Automatic, dynamic reloading in response to modifications to
--   configuration files.</li>
--   <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>Subscription-based notification of changes to configuration
--   properties.</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>
--   </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
@version 0.3.0.0


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

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

-- | Configuration data.
data Config

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

-- | A value in a <a>Config</a>.
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 :: Rational -> 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

-- | This class represents types that can be automatically and safely
--   converted <i>from</i> a <a>Value</a> <i>to</i> a destination type. If
--   conversion fails because the types are not compatible, <a>Nothing</a>
--   is returned.
--   
--   For an example of compatibility, a <a>Value</a> of <a>Bool</a>
--   <a>True</a> cannot be <a>convert</a>ed to an <a>Int</a>.
class Configured a where convertList (List xs) = mapM convert xs convertList _ = Nothing
convert :: Configured a => Value -> Maybe 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 <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 ()


-- | 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 <a>Config</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>Config</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 (Config, ThreadId)
autoReloadGroups :: AutoConfig -> [(Name, Worth FilePath)] -> IO (Config, 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 completely empty configuration.
empty :: Config

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

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

-- | 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 :: Config -> Pattern -> ChangeHandler -> IO ()

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

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

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

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

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

-- | Add additional files to named groups in a <a>Config</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)] -> Config -> IO ()

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

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