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


-- | Very simple config file reading
--   
--   This package contains modules for runtime reading of very simple
--   config files of the `key=value` style or as a Haskell data structure
--   to be deserialized with <a>Read</a>. The modules support files with
--   blank lines and simple single-line comments, but nothing else.
@package tce-conf
@version 1.3


-- | Simple key/value style config file loading
--   
--   This module was motived by the desire to factor this repetitive
--   configuration file parsing code out of several of my projects.
--   
--   These functions offer very simple behavior which may be fine for many
--   tasks. For those needing something that does more, including building
--   and saving config data and .ini-style [section]s, may I suggest
--   Data.ConfigFile <a>http://hackage.haskell.org/package/ConfigFile</a>.
--   
--   Example:
--   
--   <pre>
--   import Data.Map ( lookup )
--   import Prelude hiding ( lookup )
--   import TCE.Data.KVConf ( parseToMap )
--   
--   main = do
--      -- Parse a String into a KVConf datatype
--      conf &lt;- parseToMap &lt;$&gt; readFile "kv-example.conf"
--   
--      -- It's just a map, so use Data.Map functions to access
--      print $ lookup "foo" conf
--      print $ lookup "baz-blorp" conf
--   </pre>
--   
--   An example config file is given below.
module TCE.Data.KVConf

-- | Convenience type synonym. Config data is just a simple Map
type KVConf = Map String String

-- | Parse config file data into a simple (Map String String).
--   
--   For example, this:
--   
--   <pre>
--   --- file start ---
--   foo=one
--   # a comment
--   
--   bar
--   baz-blorp=2
--   
--   # spaces are permitted around the =
--   qux = false
--   --- file end ---
--   </pre>
--   
--   becomes:
--   
--   <pre>
--   fromList [("foo","one"),("bar",""),("baz-blorp","2"),("qux","false")]
--   </pre>
--   
--   Comments (prefixed with #) and blank lines in the config file are
--   discarded.
parseToMap :: String -> KVConf

-- | Parse config file data into what looks like long args on a command
--   line.
--   
--   Sometimes it's convenient to be able to supply commonly used long args
--   in a config file. The idea here is you can prepend this [String] to
--   your other command line args and send the whole mess to your
--   System.Console.GetOpt-based code.
--   
--   For example, this:
--   
--   <pre>
--   --- file start ---
--   foo=one
--   # a comment
--   
--   bar
--   baz-blorp=2
--   
--   # spaces are permitted around the =
--   qux = false
--   --- file end ---
--   </pre>
--   
--   becomes:
--   
--   <pre>
--   [ "--foo=one", "--bar", "--baz-blorp=2", "--qux=false" ]
--   </pre>
--   
--   As above, comments (prefixed with #) and blank lines in the config
--   file are discarded.
parseToArgs :: String -> [String]


-- | Read a serialized (as in the Read typeclass) config data structure
--   from a string
--   
--   This is handy for the case where you need a strongly-typed, possibly
--   hierarchical configuration. It's not a revolutionary idea to use Read
--   deserialization of a text file but I found it useful to support
--   comments and also wrapping possible failure in Either.
--   
--   Example:
--   
--   <pre>
--   import TCE.Data.ReadConf ( readConfig )
--   
--   -- Write your own custom data structure for config, like this:
--   data Config = Config
--      { foo :: String
--      , bar :: Int
--      , baz :: [String]
--      , qux :: Bool
--      }
--      deriving Read  -- Make it an instance of Read
--   
--   main = do
--      -- Parse a String containing a single instance of the above data type
--      econf &lt;- readConfig &lt;$&gt; readFile "read-example.conf"
--   
--      -- The result is an Either String Config
--      either
--         print  -- Failure is reported as a Left
--         (\c -&gt; (print $ bar c) &gt;&gt; (print $ qux c))
--         econf
--   </pre>
--   
--   And then file.conf could contain this Haskell source code:
--   
--   <pre>
--   -- An example config file
--   
--   Config
--      { foo = "some data"
--   
--      --, bar = 0
--      , bar = 42
--   
--      , baz =
--         [ "dogs"
--         , "cats"
--         ]
--   
--      , qux = True
--      }
--   </pre>
module TCE.Data.ReadConf

-- | Attempt to read a String into an instance of a data structure.
readConfig :: (Read r) => String -> Either String r
