Distribution.Client.ParseUtils

Parsing utilities.

Fields and field utilities

data FieldDescr a

Field descriptor. The parameter a parameterizes over where the field's value is stored in.

Constructors

FieldDescr

Fields

• fieldName :: String
• fieldGet :: a -> Doc
• fieldSet :: LineNo -> String -> a -> ParseResult a

  fieldSet n str x Parses the field value from the given input string str and stores the result in x if the parse was successful. Otherwise, reports an error on line number n.

liftField :: (b -> a) -> (a -> b -> b) -> FieldDescr a -> FieldDescr b

liftFields :: (b -> a) -> (a -> b -> b) -> [FieldDescr a] -> [FieldDescr b]

filterFields :: [String] -> [FieldDescr a] -> [FieldDescr a]

Given a collection of field descriptions, keep only a given list of them, identified by name.

mapFieldNames :: (String -> String) -> [FieldDescr a] -> [FieldDescr a]

Apply a name mangling function to the field names of all the field descriptions. The typical use case is to apply some prefix.

commandOptionToField :: OptionField a -> FieldDescr a

Reuse a command line OptionField as a config file FieldDescr.

commandOptionsToFields :: [OptionField a] -> [FieldDescr a]

Reuse a bunch of command line OptionFields as config file FieldDescrs.

Sections and utilities

data SectionDescr a

The description of a section in a config file. It can contain both fields and optionally further subsections. See also FieldDescr.

Constructors

forall b. SectionDescr

Fields

• sectionName :: String
• sectionFields :: [FieldDescr b]
• sectionSubsections :: [SectionDescr b]
• sectionGet :: a -> [(String, b)]
• sectionSet :: LineNo -> String -> b -> a -> ParseResult a
• sectionEmpty :: b

liftSection :: (b -> a) -> (a -> b -> b) -> SectionDescr a -> SectionDescr b

To help construction of config file descriptions in a modular way it is useful to define fields and sections on local types and then hoist them into the parent types when combining them in bigger descriptions.

This is essentially a lens operation for SectionDescr to help embedding one inside another.

FieldGrammar sections

data FGSectionDescr g a

FieldGrammar section description

Constructors

forall s. FGSectionDescr

Fields

• fgSectionName :: String
• fgSectionGrammar :: g s s
• fgSectionGet :: a -> [(String, s)]
• fgSectionSet :: LineNo -> String -> s -> a -> ParseResult a

Parsing and printing flat config

parseFields :: [FieldDescr a] -> a -> [Field] -> ParseResult a

Parse a bunch of semi-parsed Fields according to a set of field descriptions. It accumulates the result on top of a given initial value.

This only covers the case of flat configuration without subsections. See also parseFieldsAndSections.

ppFields :: [FieldDescr a] -> Maybe a -> a -> Doc

This is a customised version of the functions from Distribution.Deprecated.ParseUtils that also optionally print default values for empty fields as comments.

ppSection :: String -> String -> [FieldDescr a] -> Maybe a -> a -> Doc

Pretty print a section.

Since ppFields does not cover subsections you can use this to add them. Or alternatively use a SectionDescr and use ppFieldsAndSections.

Parsing and printing config with sections and subsections

parseFieldsAndSections

Arguments

:: [FieldDescr a]

field

-> [SectionDescr a]

legacy sections

-> [FGSectionDescr ParsecFieldGrammar a]

FieldGrammar sections

-> a

-> [Field]

-> ParseResult a

Much like parseFields but it also allows subsections. The permitted subsections are given by a list of SectionDescrs.

ppFieldsAndSections :: [FieldDescr a] -> [SectionDescr a] -> [FGSectionDescr PrettyFieldGrammar a] -> a -> Doc

Much like ppFields but also pretty prints any subsections. Subsection are only shown if they are non-empty.

Note that unlike ppFields, at present it does not support printing default values. If needed, adding such support would be quite reasonable.

Top level of config files

parseConfig :: [FieldDescr a] -> [SectionDescr a] -> [FGSectionDescr ParsecFieldGrammar a] -> a -> ByteString -> ParseResult a

Parse a string in the config file syntax into a value, based on a description of the configuration file in terms of its fields and sections.

It accumulates the result on top of a given initial (typically empty) value.

showConfig :: [FieldDescr a] -> [SectionDescr a] -> [FGSectionDescr PrettyFieldGrammar a] -> a -> Doc

Render a value in the config file syntax, based on a description of the configuration file in terms of its fields and sections.