cabal-install-3.12.1.0: The command-line interface for Cabal and Hackage.
Maintainercabal-devel@haskell.org
Portabilityportable
Safe HaskellSafe-Inferred
LanguageHaskell2010

Distribution.Client.ParseUtils

Description

Parsing utilities.

Synopsis

Fields and field utilities

data FieldDescr a Source #

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 Source #

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

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

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

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

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 Source #

Reuse a command line OptionField as a config file FieldDescr.

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

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

Sections and utilities

data SectionDescr a Source #

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

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

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 Source #

FieldGrammar section description

Constructors

forall s. FGSectionDescr 

Fields

Parsing and printing flat config

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

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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