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


-- | Reduced parser for configurator-ng config files
--   
--   This module provides a simplified and updated interface to the
--   configuration file format of <a>configurator</a> and
--   <a>configurator-ng</a>. Its aim is primarily to allow updating
--   programs that depend on configurator-ng to new versions of GHC without
--   changing the configuration file format.
@package configurator-pg
@version 0.2.5


-- | A simplified library for reading configuration files in the format of
--   <a>configurator-ng</a>.
module Data.Configurator

-- | The left-hand side of a configuration binding.
type Key = Text

-- | A general right-hand side value of a configuration binding.
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

-- | A number.
Number :: Scientific -> Value

-- | A 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

-- | An evaluated configuation.
type Config = Map Key Value

-- | Read and parse a configuration file.
--   
--   This may cause IO exceptions for reading this file or imported files,
--   and <a>ParseError</a> if there is a problem with parsing or evaluating
--   the file.
load :: FilePath -> IO Config

-- | An error that occurred during the low-level parsing of a configuration
--   file.
newtype ParseError
ParseError :: Text -> ParseError

-- | A generic parser.
--   
--   A <tt><a>Parser</a> a b</tt> knows how to extract a <tt>b</tt> from an
--   <tt>a</tt>. Typical instances are <tt><a>Parser</a> <a>Value</a>
--   a</tt>, which handles the parsing of individual configuration values,
--   and <tt><a>Parser</a> <a>Config</a> a</tt>, which handles extracting
--   data from a full keyed configuration file.
data Parser a b

-- | Run a parser.
--   
--   <tt><a>runParser</a> p x</tt> runs the parser <tt>p</tt> on the input
--   <tt>x</tt>, returning a value <tt><a>Right</a> v</tt> on success, or
--   <tt><a>Left</a> err</tt> on error.
runParser :: Parser a b -> a -> Either Text b

-- | Extract a boolean value.
--   
--   <a>bool</a> expects the given value to be boolean.
bool :: Parser Value Bool

-- | Extract an integer value.
--   
--   <a>int</a> expects the given value to be an <a>Int</a>.
int :: Parser Value Int

-- | Extract a string value.
--   
--   <a>string</a> expects the given value to be a string.
string :: Parser Value Text

-- | Extract a raw value.
--   
--   <a>value</a> returns a configuration value in its raw form.
value :: Parser Value Value

-- | Parse a list of values.
--   
--   <tt><a>list</a> p</tt> expects a list value, and parses each entry
--   with <tt>p</tt>.
list :: Parser Value a -> Parser Value [a]

-- | Parse an optional configuration field.
--   
--   <tt><a>optional</a> key p</tt> returns <a>Nothing</a> if the field
--   <tt>key</tt> is not present. Otherwise it returns <tt><a>Just</a>
--   v</tt>, where <tt>v</tt> is the result of parsing the field value with
--   <tt>p</tt>.
optional :: Key -> Parser Value a -> Parser Config (Maybe a)

-- | Parse a required configuration field.
--   
--   <tt><a>required</a> key p</tt> expects the field <tt>key</tt> to be
--   present, and parses its value with <tt>p</tt>.
required :: Key -> Parser Value a -> Parser Config a

-- | Parse a set of fields with a shared prefix.
--   
--   <tt><a>subassocs</a> prefix p</tt> extracts all configuration keys one
--   level below <tt>prefix</tt>, and collects pairs of the full keys and
--   the corresponding field values parsed with <tt>p</tt>.
subassocs :: Key -> Parser Value a -> Parser Config [(Key, a)]
