cabal-install-3.12.1.0: The command-line interface for Cabal and Hackage.

Maintainer | cabal-devel@haskell.org
Portability | portable
Safe Haskell | None
Language | Haskell2010

Distribution.Client.ParseUtils

Contents

- Fields and field utilities
- Sections and utilities
- FieldGrammar sections
- Parsing and printing flat config
- Parsing and printing config with sections and subsections
  - Top level of config files

Description

Parsing utilities.

Synopsis

- data FieldDescr a = FieldDescr {
  - fieldName :: String
  - fieldGet :: a -> Doc
  - fieldSet :: LineNo -> String -> a -> ParseResult a
  }
- 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]
- mapFieldNames :: (String -> String) -> [FieldDescr a] -> [FieldDescr a]
- commandOptionToField :: OptionField a -> FieldDescr a
- commandOptionsToFields :: [OptionField a] -> [FieldDescr a]
- data SectionDescr a = SectionDescr {
  - 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
- data FGSectionDescr (g :: Type -> Type -> Type) a = FGSectionDescr {
  - fgSectionName :: String
  - fgSectionGrammar :: g s s
  - fgSectionGet :: a -> [(String, s)]
  - fgSectionSet :: LineNo -> String -> s -> a -> ParseResult a
  }
- parseFields :: [FieldDescr a] -> a -> [Field] -> ParseResult a
- ppFields :: [FieldDescr a] -> Maybe a -> a -> Doc
- ppSection :: String -> String -> [FieldDescr a] -> Maybe a -> a -> Doc
- parseFieldsAndSections :: [FieldDescr a] -> [SectionDescr a] -> [FGSectionDescr ParsecFieldGrammar a] -> a -> [Field] -> ParseResult a
- ppFieldsAndSections :: [FieldDescr a] -> [SectionDescr a] -> [FGSectionDescr PrettyFieldGrammar a] -> a -> Doc
- parseConfig :: [FieldDescr a] -> [SectionDescr a] -> [FGSectionDescr ParsecFieldGrammar a] -> a -> ByteString -> ParseResult a
- showConfig :: [FieldDescr a] -> [SectionDescr a] -> [FGSectionDescr PrettyFieldGrammar a] -> a -> Doc

# 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 `OptionField`s as config file `FieldDescr`s.

# 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

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 :: Type -> Type -> Type) a #

`FieldGrammar` section description

Constructors

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 `Field`s 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 `SectionDescr`s.

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.