-- 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: -- -- -- -- 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 1.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: -- -- -- -- 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. -- --

Example:

-- -- By default, this library parses flat config like the following: -- -- 
--   a_string = "blah, blah, blah\nmore blah"
--   a_number = 9001
--   a_list   = [1,2,3,4,5]
--   # This is a comment
--
-- -- If you wanted to parse the above file, saved as ./config.txt, -- you might do so as follows: -- -- 
--   import Text.ConfigParser
--   
--   cp :: ConfigParser (Maybe String, Maybe Integer, [Integer])
--   cp = configParser (Nothing, Nothing, [])
--       [ ConfigOption
--           { key    = "a_string"
--           , parser = string
--           , action = \s (_,n,ns) -> (Just s, n, ns)
--           }
--       , ConfigOption
--           { key    = "a_number"
--           , parser = integer
--           , action = \n (s,_,ns) -> (s, Just n, ns)
--           }
--       , ConfigOption
--           { key    = "a_list"
--           , parser = list integer
--           , action = \ns (s,n,_) -> (s, n, ns)
--           }
--       ]
--   
--   main :: IO ()
--   main = parseFromFile cp "./config.txt" >>= print
--
module Text.ConfigParser -- | Key-value pair to parse from a config file. type Key = String data ConfigOption c ConfigOption :: Key -> Bool -> Parser a -> (a -> c -> c) -> ConfigOption c -- | Key name. [key] :: ConfigOption c -> Key -- | Whether it is an error to omit this key. [required] :: ConfigOption c -> Bool -- | Parser for the given value type. [parser] :: ConfigOption c -> Parser a -- | How the value should change the state c. [action] :: ConfigOption c -> a -> c -> c -- | Parameters for a parser that takes a config file and produces a -- c. Use the ConfigParser constructor if you want to -- specify your own lineParser or commentStart. -- Otherwise, use the configParser smart constructor. data ConfigParser c ConfigParser :: (forall a. Parser Key -> Parser a -> Parser a) -> [String] -> Parser Key -> c -> [ConfigOption c] -> ConfigParser c -- | Specifies how a key and a value parser should be represented in the -- config file, e.g., key = value, or key: value. The -- first parameter will be either be Text.Parsec.string (key -- (co::ConfigOption c)) or keyIdentifier. The second -- parameter will be parser (co::ConfigOption c). [keyValue] :: ConfigParser c -> forall a. Parser Key -> Parser a -> Parser a -- | Strings to start a line comment, such as #, --, or -- //. All characters following this string up to the following -- newline or EOF will be removed. You can use the string without -- starting a comment by escaping it with a backslash, e.g. \# -- or \--. [lineCommentInit] :: ConfigParser c -> [String] -- | This is the general form of an identifier to be passed as the first -- parameter of keyValue. Having a general form allows us to -- correctly detect invalid (e.g., typoed) keys. For example, the -- keyIdentifier corresponding to defaultKeyValue is -- many1 (noneOf "\r\v\n\t ="). [keyIdentifier] :: ConfigParser c -> Parser Key -- | Initial c to fold each ConfigOption action over. [defaults] :: ConfigParser c -> c -- | List of key-value pairs to parse from the config file. Any key in the -- config file that doesn't appear here will result in parse error. [options] :: ConfigParser c -> [ConfigOption c] optionalCO :: Key -> Parser a -> (a -> c -> c) -> ConfigOption c requiredCO :: Key -> Parser a -> (a -> c -> c) -> ConfigOption c -- | Smart constructor for a ConfigParser that uses a default syntax -- like key = value and line comments starting with #. configParser :: c -> [ConfigOption c] -> ConfigParser c -- | Default syntax like key = value. defaultKeyValue :: Parser Key -> Parser a -> Parser a -- | Default line comment like # comment text. defaultLineCommentInit :: [String] -- | Parse a config file as specified by a ConfigParser. 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 bounded integer. Fail to parse with a descriptive message if -- the value is out of bounds. boundedIntegral :: forall n. (Show n, Bounded n, Integral n) => Parser n -- | Parse a boolean. Valid synonyms for True are true, -- yes, Yes, on, and On. Valid -- synonyms for False are false, no, -- No, off, and Off. bool :: Parser Bool -- | Parse a list of values surrounded by [ and ], and -- separated by commas. The list can contain whitespace and newlines. list :: (Parser a) -> Parser [a] parseFromText :: ConfigParser c -> SourceName -> Text -> Either ParseError c parseFromFile :: ConfigParser c -> SourceName -> IO (Either ParseError c)