Text.ConfigParser

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:

• Keys and values are parsed with configurable parsec parsers, resulting in flexible syntax and pretty error messages.
• Custom parsers can be created with parsec to handle values of any type.
• Keys that aren't explicitly handled result in parse errors.

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

Documentation

type Key = String

Key-value pair to parse from a config file.

data ConfigOption c

Constructors

ConfigOption

Fields

• key :: Key

  Key name.

• required :: Bool

  Whether it is an error to omit this key.

• parser :: Parser a

  Parser for the given value type.

• action :: a -> c -> c

  How the value should change the state c.

data ConfigParser 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.

Constructors

ConfigParser

Fields

• keyValue :: forall a. Parser Key -> Parser a -> Parser a

  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).

• lineCommentInit :: [String]

  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 \--.

• keyIdentifier :: Parser Key

  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 =").

• defaults :: c

  Initial c to fold each ConfigOption action over.

• options :: [ConfigOption 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.

optionalCO :: Key -> Parser a -> (a -> c -> c) -> ConfigOption c

requiredCO :: Key -> Parser a -> (a -> c -> c) -> ConfigOption c

configParser :: c -> [ConfigOption c] -> ConfigParser c

Smart constructor for a ConfigParser that uses a default syntax like key = value and line comments starting with #.

defaultKeyValue :: Parser Key -> Parser a -> Parser a

Default syntax like key = value.

defaultLineCommentInit :: [String]

Default line comment like # comment text.

config :: ConfigParser c -> Parser c

Parse a config file as specified by a ConfigParser.

string :: IsString s => Parser s

Parse a string surrounded by quotes. Quotes within the string must be escaped with backslashes.

integer :: Parser Integer

Parse an integer.

boundedIntegral :: forall n. (Show n, Bounded n, Integral n) => Parser n

Parse a bounded integer. Fail to parse with a descriptive message if the value is out of bounds.

bool :: Parser Bool

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.

list :: Parser a -> Parser [a]

Parse a list of values surrounded by [ and ], and separated by commas. The list can contain whitespace and newlines.

parseFromText :: ConfigParser c -> SourceName -> Text -> Either ParseError c

parseFromFile :: ConfigParser c -> SourceName -> IO (Either ParseError c)