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


-- | Parse config files using parsec and generate parse errors
--   on unhandled keys
--   
--   This is yet another entry in Haskell's enourmous collection of
--   config-file parsing libraries. It lacks many of the bells and whistles
--   of other config-file parsing libraries, such as hierarchical sections
--   and on-the-fly reloading. On the other hand, it has a combination of
--   features I was unable to find in other libraries:
--   
--   <ul>
--   <li>Keys and values are parsed with configurable parsec parsers,
--   resulting in flexible syntax and pretty error messages.</li>
--   <li>Custom parsers can be created with parsec to handle values of any
--   type.</li>
--   <li>Keys that aren't explicitly handled result in parse errors.</li>
--   </ul>
--   
--   If you don't need all of these features, there are probably better
--   libraries out there for you. If you're free to use its idiosyncratic
--   file format, the config-value library, in particular, is excelent.
@package config-parser
@version 0.2.0.0


-- | This is yet another entry in Haskell's enourmous collection of
--   config-file parsing libraries. It lacks many of the bells and whistles
--   of other config-file parsing libraries, such as hierarchical sections
--   and on-the-fly reloading. On the other hand, it has a combination of
--   features I was unable to find in other libraries:
--   
--   <ul>
--   <li>Keys and values are parsed with configurable parsec parsers,
--   resulting in flexible syntax and pretty error messages.</li>
--   <li>Custom parsers can be created with parsec to handle values of any
--   type.</li>
--   <li>Keys that aren't explicitly handled result in parse errors.</li>
--   </ul>
--   
--   If you don't need all of these features, there are probably better
--   libraries out there for you. If you're free to use its idiosyncratic
--   file format, the config-value library, in particular, is excelent.
--   
--   <h1>Example:</h1>
--   
--   By default, this library parses flat config like the following:
--   
--   <pre>
--   a_string = "blah, blah, blah\nmore blah"
--   a_number = 9001
--   a_list   = [1,2,3,4,5]
--   # This is a comment
--   </pre>
--   
--   If you wanted to parse the above file, saved as <tt>./config.txt</tt>,
--   you might do so as follows:
--   
--   <pre>
--   import Text.ConfigParser
--   
--   cp :: ConfigParser (Maybe String, Maybe Integer, [Integer])
--   cp = configParser (Nothing, Nothing, [])
--       [ ConfigOption
--           { key    = "a_string"
--           , parser = string
--           , action = \s (_,n,ns) -&gt; (Just s, n, ns)
--           }
--       , ConfigOption
--           { key    = "a_number"
--           , parser = integer
--           , action = \n (s,_,ns) -&gt; (s, Just n, ns)
--           }
--       , ConfigOption
--           { key    = "a_list"
--           , parser = list integer
--           , action = \ns (s,n,_) -&gt; (s, n, ns)
--           }
--       ]
--   
--   main :: IO ()
--   main = parseFromFile cp "./config.txt" &gt;&gt;= print
--   </pre>
module Text.ConfigParser
type Key = String
data ConfigOption c
ConfigOption :: Key -> Parser a -> (a -> c -> c) -> ConfigOption c

-- | Key name.
[key] :: ConfigOption c -> Key

-- | Parser for the given value type.
[parser] :: ConfigOption c -> Parser a

-- | How the value should change the state <tt>c</tt>.
[action] :: ConfigOption c -> a -> c -> c

-- | Parameters for a parser that takes a config file and produces a
--   <tt>c</tt>. Use the <a>configParser_</a> constructor if you want to
--   specify your own <tt>lineParser</tt> or <tt>commentStart</tt>.
--   Otherwise, use the <a>configParser</a> smart constructor.
data ConfigParser c

-- | Smart constructor to check that <a>options</a> doesn't contain any
--   duplicate keys before creating a <a>ConfigParser</a>.
configParser_ :: (forall a. Key -> Parser a -> Parser a) -> [String] -> c -> [ConfigOption c] -> ConfigParser c

-- | Smart constructor for a <a>ConfigParser</a> that uses a default syntax
--   like <tt>key = value</tt> and line comments starting with <tt>#</tt>.
configParser :: c -> [ConfigOption c] -> ConfigParser c

-- | Default syntax like <tt>key = value</tt>.
defaultKeyValue :: Key -> Parser a -> Parser a

-- | Default line comment like <tt># comment text</tt>.
defaultLineCommentInit :: [String]
config :: ConfigParser c -> Parser c

-- | Parse a string surrounded by quotes. Quotes within the string must be
--   escaped with backslashes.
string :: IsString s => Parser s

-- | Parse an integer.
integer :: Parser Integer

-- | Parse a boolean. Valid synonyms for <tt>True</tt> are <tt>true</tt>,
--   <tt>yes</tt>, <tt>Yes</tt>, <tt>on</tt>, and <tt>On</tt>. Valid
--   synonyms for <tt>False</tt> are <tt>false</tt>, <tt>no</tt>,
--   <tt>No</tt>, <tt>off</tt>, and <tt>Off</tt>.
bool :: Parser Bool

-- | Parse a list of values surrounded by <tt>[</tt> and <tt>]</tt>, and
--   separated by commas. The list can contain whitespace and newlines.
list :: (Parser a) -> Parser [a]
parseFromFile :: ConfigParser c -> SourceName -> IO (Either ParseError c)