Modulecabal-install-3.16.0.0Haskell2010

Distribution.Client.ParseUtils

Parsing utilities.

3 types
16 values

Packagecabal-install-3.16.0.0
Exports19
LanguageHaskell2010
LicenceBSD-3-Clause
SourceParseUtils.hs

Fields and field utilities

9 declarations

datadata FieldDescr a

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

Constructors

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

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

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

valueaddFields :: [FieldDescr a] -> [FieldDescr a] -> [FieldDescr a]

Add fields to a field list.

valuealiasField

:: String
The existing field name.
-> String
The new field name.
-> [FieldDescr a]
-> [FieldDescr a]

Add a new field which is identical to an existing field but with a different name.

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

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

TODO: This makes it easy to footgun by providing a non-existent field name.

valuemapFieldNames :: (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.

valuecommandOptionToField :: OptionField a -> FieldDescr a

Reuse a command line OptionField as a config file FieldDescr.

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

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

Sections and utilities

2 declarations

datadata 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
- sectionName :: String
- sectionFields :: [FieldDescr b]
- sectionSubsections :: [SectionDescr b]
- sectionGet :: a -> [(String, b)]
- sectionSet :: LineNo -> String -> b -> a -> ParseResult a
- sectionEmpty :: b

valueliftSection :: (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

1 declaration

datadata FGSectionDescr (g :: Type -> Type -> Type) a

FieldGrammar section description

Constructors

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

Parsing and printing flat config

3 declarations

valueparseFields :: [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.

valueppFields :: [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.

valueppSection :: 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

2 declarations

valueparseFieldsAndSections

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

valueppFieldsAndSections

:: [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

valueparseConfig

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

valueshowConfig

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