Cabal-syntax-3.12.1.0: A library for working with .cabal files

Safe Haskell | None
Language | Haskell2010

Distribution.FieldGrammar

Contents

- Field grammar type
- Concrete grammar implementations
- Auxiliary
- Newtypes

Description

This module provides a way to specify a grammar of `.cabal` -like files.

Synopsis

- class (c SpecVersion, c TestedWith, c SpecLicense, c Token, c Token', c FilePathNT) => FieldGrammar (c :: Type -> Constraint) (g :: Type -> Type -> Type) | g -> c where
  - blurFieldGrammar :: ALens' a b -> g b d -> g a d
  - uniqueFieldAla :: (c b, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> g s a
  - booleanFieldDef :: FieldName -> ALens' s Bool -> Bool -> g s Bool
  - optionalFieldAla :: (c b, Newtype a b) => FieldName -> (a -> b) -> ALens' s (Maybe a) -> g s (Maybe a)
  - optionalFieldDefAla :: (c b, Newtype a b, Eq a) => FieldName -> (a -> b) -> ALens' s a -> a -> g s a
  - freeTextField :: FieldName -> ALens' s (Maybe String) -> g s (Maybe String)
  - freeTextFieldDef :: FieldName -> ALens' s String -> g s String
  - freeTextFieldDefST :: FieldName -> ALens' s ShortText -> g s ShortText
  - monoidalFieldAla :: (c b, Monoid a, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> g s a
  - prefixedFields :: FieldName -> ALens' s [(String, String)] -> g s [(String, String)]
  - knownField :: FieldName -> g s ()
  - hiddenField :: g s a -> g s a
  - deprecatedSince :: CabalSpecVersion -> String -> g s a -> g s a
  - removedIn :: CabalSpecVersion -> String -> g s a -> g s a
  - availableSince :: CabalSpecVersion -> a -> g s a -> g s a
  - availableSinceWarn :: CabalSpecVersion -> g s a -> g s a
- uniqueField :: forall (c :: Type -> Constraint) g a s. (FieldGrammar c g, c (Identity a)) => FieldName -> ALens' s a -> g s a
- optionalField :: forall (c :: Type -> Constraint) g a s. (FieldGrammar c g, c (Identity a)) => FieldName -> ALens' s (Maybe a) -> g s (Maybe a)
- optionalFieldDef :: forall (c :: Type -> Constraint) g s a. (FieldGrammar c g, Functor (g s), c (Identity a), Eq a) => FieldName -> ALens' s a -> a -> g s a
- monoidalField :: forall (c :: Type -> Constraint) g a s. (FieldGrammar c g, c (Identity a), Monoid a) => FieldName -> ALens' s a -> g s a
- data ParsecFieldGrammar s a
- type ParsecFieldGrammar' a = ParsecFieldGrammar a a
- parseFieldGrammar :: CabalSpecVersion -> Fields Position -> ParsecFieldGrammar s a -> ParseResult a
- fieldGrammarKnownFieldList :: ParsecFieldGrammar s a -> [FieldName]
- data PrettyFieldGrammar s a
- type PrettyFieldGrammar' a = PrettyFieldGrammar a a
- prettyFieldGrammar :: CabalSpecVersion -> PrettyFieldGrammar s a -> s -> [PrettyField ()]
- (^^^) :: a -> (a -> b) -> b
- data Section ann = MkSection !(Name ann) [SectionArg ann] [Field ann]
- type Fields ann = Map FieldName [NamelessField ann]
- partitionFields :: [Field ann] -> (Fields ann, [[Section ann]])
- takeFields :: [Field ann] -> (Fields ann, [Field ann])
- runFieldParser :: Position -> ParsecParser a -> CabalSpecVersion -> [FieldLine Position] -> ParseResult a
- runFieldParser' :: [Position] -> ParsecParser a -> CabalSpecVersion -> FieldLineStream -> ParseResult a
- defaultFreeTextFieldDefST :: forall g s (c :: Type -> Constraint). (Functor (g s), FieldGrammar c g) => FieldName -> ALens' s ShortText -> g s ShortText
- module Distribution.FieldGrammar.Newtypes

# Field grammar type

class (c SpecVersion, c TestedWith, c SpecLicense, c Token, c Token', c FilePathNT) => FieldGrammar (c :: Type -> Constraint) (g :: Type -> Type -> Type) | g -> c where Source #

`FieldGrammar` is parametrised by

- `s` which is a structure we are parsing. We need this to provide prettyprinter functionality
- `a` type of the field.

Note: We'd like to have `forall s. Applicative (f s)` context.

Minimal complete definition

blurFieldGrammar, uniqueFieldAla, booleanFieldDef, optionalFieldAla, optionalFieldDefAla, freeTextField, freeTextFieldDef, freeTextFieldDefST, monoidalFieldAla, prefixedFields, knownField, hiddenField, deprecatedSince, removedIn, availableSince

Methods

blurFieldGrammar :: ALens' a b -> g b d -> g a d Source #

Unfocus, zoom out, blur `FieldGrammar`.

uniqueFieldAla Source #

Arguments

:: (c b, Newtype a b) |
=> FieldName | field name
-> (a -> b) | `Newtype` pack
-> ALens' s a | lens into the field
-> g s a |

Field which should be defined, exactly once.

booleanFieldDef Source #

Arguments

:: FieldName | field name
-> ALens' s Bool | lens into the field
-> Bool | default
-> g s Bool |

Boolean field with a default value.

optionalFieldAla Source #

Arguments

:: (c b, Newtype a b) |
=> FieldName | field name
-> (a -> b) | `pack`
-> ALens' s (Maybe a) | lens into the field
-> g s (Maybe a) |

Optional field.

optionalFieldDefAla Source #

Arguments

:: (c b, Newtype a b, Eq a) |
=> FieldName | field name
-> (a -> b) | `Newtype` pack
-> ALens' s a | ``Lens'` s a`: lens into the field
-> a | default value
-> g s a |

Optional field with default value.

freeTextField Source #

Arguments

:: FieldName |
-> ALens' s (Maybe String) | lens into the field
-> g s (Maybe String) |

freeTextFieldDef Source #

Arguments

:: FieldName |
-> ALens' s String | lens into the field
-> g s String |

freeTextFieldDefST Source #

Arguments

:: FieldName |
-> ALens' s ShortText | lens into the field
-> g s ShortText |

Since: Cabal-syntax-3.2.0.0

monoidalFieldAla Source #

Arguments

:: (c b, Monoid a, Newtype a b) |
=> FieldName | field name
-> (a -> b) | `pack`
-> ALens' s a | lens into the field
-> g s a |

Monoidal field.

Values are combined with `mappend`.

Note: `optionalFieldAla` is a `monoidalField` with `Last` monoid.

prefixedFields Source #

Arguments

:: FieldName | field name prefix
-> ALens' s [(String, String)] | lens into the field
-> g s [(String, String)] |

Parser matching all fields with a name starting with a prefix.

knownField :: FieldName -> g s () Source #

Known field, which we don't parse, nor pretty print.

hiddenField :: g s a -> g s a Source #

Field which is parsed but not pretty printed.

deprecatedSince Source #

Arguments

:: CabalSpecVersion | version
-> String | deprecation message
-> g s a |
-> g s a |

Deprecated since

removedIn Source #

Arguments

:: CabalSpecVersion | version
-> String | removal message
-> g s a |
-> g s a |

Removed in. If we encounter removed field, parsing fails.

availableSince Source #

Arguments

:: CabalSpecVersion | spec version
-> a | default value
-> g s a |
-> g s a |

Annotate field with since spec-version.

availableSinceWarn Source #

Arguments

:: CabalSpecVersion | spec version
-> g s a |
-> g s a |

Annotate field with since spec-version. This is used to recognise, but warn about the field. It is used to process `other-extensions` field.

Default implementation is to not warn.

Since: Cabal-syntax-3.4.0.0

#### Instances

Instances details

FieldGrammar Parsec ParsecFieldGrammar Source # |

Instance details

Defined in Distribution.FieldGrammar.Parsec

Methods

blurFieldGrammar :: ALens' a b -> ParsecFieldGrammar b d -> ParsecFieldGrammar a d Source #

uniqueFieldAla :: (Parsec b, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> ParsecFieldGrammar s a Source #

booleanFieldDef :: FieldName -> ALens' s Bool -> Bool -> ParsecFieldGrammar s Bool Source #

optionalFieldAla :: (Parsec b, Newtype a b) => FieldName -> (a -> b) -> ALens' s (Maybe a) -> ParsecFieldGrammar s (Maybe a) Source #

optionalFieldDefAla :: (Parsec b, Newtype a b, Eq a) => FieldName -> (a -> b) -> ALens' s a -> a -> ParsecFieldGrammar s a Source #

freeTextField :: FieldName -> ALens' s (Maybe String) -> ParsecFieldGrammar s (Maybe String) Source #

freeTextFieldDef :: FieldName -> ALens' s String -> ParsecFieldGrammar s String Source #

freeTextFieldDefST :: FieldName -> ALens' s ShortText -> ParsecFieldGrammar s ShortText Source #

monoidalFieldAla :: (Parsec b, Monoid a, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> ParsecFieldGrammar s a Source #

prefixedFields :: FieldName -> ALens' s [(String, String)] -> ParsecFieldGrammar s [(String, String)] Source #

knownField :: FieldName -> ParsecFieldGrammar s () Source #

hiddenField :: ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

deprecatedSince :: CabalSpecVersion -> String -> ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

removedIn :: CabalSpecVersion -> String -> ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

availableSince :: CabalSpecVersion -> a -> ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

availableSinceWarn :: CabalSpecVersion -> ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

FieldGrammar Pretty PrettyFieldGrammar Source # |

Instance details

Defined in Distribution.FieldGrammar.Pretty

Methods

blurFieldGrammar :: ALens' a b -> PrettyFieldGrammar b d -> PrettyFieldGrammar a d Source #

uniqueFieldAla :: (Pretty b, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> PrettyFieldGrammar s a Source #

booleanFieldDef :: FieldName -> ALens' s Bool -> Bool -> PrettyFieldGrammar s Bool Source #

optionalFieldAla :: (Pretty b, Newtype a b) => FieldName -> (a -> b) -> ALens' s (Maybe a) -> PrettyFieldGrammar s (Maybe a) Source #

optionalFieldDefAla :: (Pretty b, Newtype a b, Eq a) => FieldName -> (a -> b) -> ALens' s a -> a -> PrettyFieldGrammar s a Source #

freeTextField :: FieldName -> ALens' s (Maybe String) -> PrettyFieldGrammar s (Maybe String) Source #

freeTextFieldDef :: FieldName -> ALens' s String -> PrettyFieldGrammar s String Source #

freeTextFieldDefST :: FieldName -> ALens' s ShortText -> PrettyFieldGrammar s ShortText Source #

monoidalFieldAla :: (Pretty b, Monoid a, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> PrettyFieldGrammar s a Source #

prefixedFields :: FieldName -> ALens' s [(String, String)] -> PrettyFieldGrammar s [(String, String)] Source #

knownField :: FieldName -> PrettyFieldGrammar s () Source #

hiddenField :: PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

deprecatedSince :: CabalSpecVersion -> String -> PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

removedIn :: CabalSpecVersion -> String -> PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

availableSince :: CabalSpecVersion -> a -> PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

availableSinceWarn :: CabalSpecVersion -> PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

uniqueField Source #

Arguments

:: forall (c :: Type -> Constraint) g a s. (FieldGrammar c g, c (Identity a)) |
=> FieldName | field name
-> ALens' s a | lens into the field
-> g s a |

Field which can be defined at most once.

optionalField Source #

Arguments

:: forall (c :: Type -> Constraint) g a s. (FieldGrammar c g, c (Identity a)) |
=> FieldName | field name
-> ALens' s (Maybe a) | lens into the field
-> g s (Maybe a) |

Field which can be defined at most once.

optionalFieldDef Source #

Arguments

:: forall (c :: Type -> Constraint) g s a. (FieldGrammar c g, Functor (g s), c (Identity a), Eq a) |
=> FieldName | field name
-> ALens' s a | ``Lens'` s a`: lens into the field
-> a | default value
-> g s a |

Optional field with default value.

monoidalField Source #

Arguments

:: forall (c :: Type -> Constraint) g a s. (FieldGrammar c g, c (Identity a), Monoid a) |
=> FieldName | field name
-> ALens' s a | lens into the field
-> g s a |

Field which can be define multiple times, and the results are `mappend`ed.

# Concrete grammar implementations

data ParsecFieldGrammar s a Source #

#### Instances

Instances details

FieldGrammar Parsec ParsecFieldGrammar Source # |

Instance details

Defined in Distribution.FieldGrammar.Parsec

Methods

blurFieldGrammar :: ALens' a b -> ParsecFieldGrammar b d -> ParsecFieldGrammar a d Source #

uniqueFieldAla :: (Parsec b, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> ParsecFieldGrammar s a Source #

booleanFieldDef :: FieldName -> ALens' s Bool -> Bool -> ParsecFieldGrammar s Bool Source #

optionalFieldAla :: (Parsec b, Newtype a b) => FieldName -> (a -> b) -> ALens' s (Maybe a) -> ParsecFieldGrammar s (Maybe a) Source #

optionalFieldDefAla :: (Parsec b, Newtype a b, Eq a) => FieldName -> (a -> b) -> ALens' s a -> a -> ParsecFieldGrammar s a Source #

freeTextField :: FieldName -> ALens' s (Maybe String) -> ParsecFieldGrammar s (Maybe String) Source #

freeTextFieldDef :: FieldName -> ALens' s String -> ParsecFieldGrammar s String Source #

freeTextFieldDefST :: FieldName -> ALens' s ShortText -> ParsecFieldGrammar s ShortText Source #

monoidalFieldAla :: (Parsec b, Monoid a, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> ParsecFieldGrammar s a Source #

prefixedFields :: FieldName -> ALens' s [(String, String)] -> ParsecFieldGrammar s [(String, String)] Source #

knownField :: FieldName -> ParsecFieldGrammar s () Source #

hiddenField :: ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

deprecatedSince :: CabalSpecVersion -> String -> ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

removedIn :: CabalSpecVersion -> String -> ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

availableSince :: CabalSpecVersion -> a -> ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

availableSinceWarn :: CabalSpecVersion -> ParsecFieldGrammar s a -> ParsecFieldGrammar s a Source #

Applicative (ParsecFieldGrammar s) Source # |

Instance details

Defined in Distribution.FieldGrammar.Parsec

Methods

pure :: a -> ParsecFieldGrammar s a #

(<*>) :: ParsecFieldGrammar s (a -> b) -> ParsecFieldGrammar s a -> ParsecFieldGrammar s b #

liftA2 :: (a -> b -> c) -> ParsecFieldGrammar s a -> ParsecFieldGrammar s b -> ParsecFieldGrammar s c #

(*>) :: ParsecFieldGrammar s a -> ParsecFieldGrammar s b -> ParsecFieldGrammar s b #

(<*) :: ParsecFieldGrammar s a -> ParsecFieldGrammar s b -> ParsecFieldGrammar s a #

Functor (ParsecFieldGrammar s) Source # |
Instance details Defined in Distribution.FieldGrammar.Parsec Methods fmap :: (a -> b) -> ParsecFieldGrammar s a -> ParsecFieldGrammar s b # (<$) :: a -> ParsecFieldGrammar s b -> ParsecFieldGrammar s a #

type ParsecFieldGrammar' a = ParsecFieldGrammar a a Source #

parseFieldGrammar :: CabalSpecVersion -> Fields Position -> ParsecFieldGrammar s a -> ParseResult a Source #

fieldGrammarKnownFieldList :: ParsecFieldGrammar s a -> [FieldName] Source #

data PrettyFieldGrammar s a Source #

#### Instances

Instances details

FieldGrammar Pretty PrettyFieldGrammar Source # |

Instance details

Defined in Distribution.FieldGrammar.Pretty

Methods

blurFieldGrammar :: ALens' a b -> PrettyFieldGrammar b d -> PrettyFieldGrammar a d Source #

uniqueFieldAla :: (Pretty b, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> PrettyFieldGrammar s a Source #

booleanFieldDef :: FieldName -> ALens' s Bool -> Bool -> PrettyFieldGrammar s Bool Source #

optionalFieldAla :: (Pretty b, Newtype a b) => FieldName -> (a -> b) -> ALens' s (Maybe a) -> PrettyFieldGrammar s (Maybe a) Source #

optionalFieldDefAla :: (Pretty b, Newtype a b, Eq a) => FieldName -> (a -> b) -> ALens' s a -> a -> PrettyFieldGrammar s a Source #

freeTextField :: FieldName -> ALens' s (Maybe String) -> PrettyFieldGrammar s (Maybe String) Source #

freeTextFieldDef :: FieldName -> ALens' s String -> PrettyFieldGrammar s String Source #

freeTextFieldDefST :: FieldName -> ALens' s ShortText -> PrettyFieldGrammar s ShortText Source #

monoidalFieldAla :: (Pretty b, Monoid a, Newtype a b) => FieldName -> (a -> b) -> ALens' s a -> PrettyFieldGrammar s a Source #

prefixedFields :: FieldName -> ALens' s [(String, String)] -> PrettyFieldGrammar s [(String, String)] Source #

knownField :: FieldName -> PrettyFieldGrammar s () Source #

hiddenField :: PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

deprecatedSince :: CabalSpecVersion -> String -> PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

removedIn :: CabalSpecVersion -> String -> PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

availableSince :: CabalSpecVersion -> a -> PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

availableSinceWarn :: CabalSpecVersion -> PrettyFieldGrammar s a -> PrettyFieldGrammar s a Source #

Applicative (PrettyFieldGrammar s) Source # |

Instance details

Defined in Distribution.FieldGrammar.Pretty

Methods

pure :: a -> PrettyFieldGrammar s a #

(<*>) :: PrettyFieldGrammar s (a -> b) -> PrettyFieldGrammar s a -> PrettyFieldGrammar s b #

liftA2 :: (a -> b -> c) -> PrettyFieldGrammar s a -> PrettyFieldGrammar s b -> PrettyFieldGrammar s c #

(*>) :: PrettyFieldGrammar s a -> PrettyFieldGrammar s b -> PrettyFieldGrammar s b #

(<*) :: PrettyFieldGrammar s a -> PrettyFieldGrammar s b -> PrettyFieldGrammar s a #

Functor (PrettyFieldGrammar s) Source # |
Instance details Defined in Distribution.FieldGrammar.Pretty Methods fmap :: (a -> b) -> PrettyFieldGrammar s a -> PrettyFieldGrammar s b # (<$) :: a -> PrettyFieldGrammar s b -> PrettyFieldGrammar s a #

type PrettyFieldGrammar' a = PrettyFieldGrammar a a Source #

prettyFieldGrammar :: CabalSpecVersion -> PrettyFieldGrammar s a -> s -> [PrettyField ()] Source #

We can use `PrettyFieldGrammar` to pp print the `s`.

Note: there is not trailing `($+$ text "")`.

# Auxiliary

(^^^) :: a -> (a -> b) -> b infixl 5 Source #

Reverse function application which binds tighter than `<$>` and `<*>`. Useful for refining grammar specification.

    <*> monoidalFieldAla "extensions"           (alaList' FSep MQuoted)       oldExtensions
        ^^^ deprecatedSince [1,12] "Please use 'default-extensions' or 'other-extensions' fields."

data Section ann Source #

The `Section` constructor of `Field`.

Constructors

MkSection !(Name ann) [SectionArg ann] [Field ann] |

#### Instances

Instances details

Functor Section Source # |
Instance details Defined in Distribution.FieldGrammar.Parsec Methods fmap :: (a -> b) -> Section a -> Section b # (<$) :: a -> Section b -> Section a #
Show ann => Show (Section ann) Source # |
Instance details Defined in Distribution.FieldGrammar.Parsec Methods showsPrec :: Int -> Section ann -> ShowS # show :: Section ann -> String # showList :: [Section ann] -> ShowS #
Eq ann => Eq (Section ann) Source # |
Instance details Defined in Distribution.FieldGrammar.Parsec Methods (==) :: Section ann -> Section ann -> Bool # (/=) :: Section ann -> Section ann -> Bool #

type Fields ann = Map FieldName [NamelessField ann] Source #

partitionFields :: [Field ann] -> (Fields ann, [[Section ann]]) Source #

Partition field list into field map and groups of sections.

takeFields :: [Field ann] -> (Fields ann, [Field ann]) Source #

Take all fields from the front.

runFieldParser :: Position -> ParsecParser a -> CabalSpecVersion -> [FieldLine Position] -> ParseResult a Source #

runFieldParser' :: [Position] -> ParsecParser a -> CabalSpecVersion -> FieldLineStream -> ParseResult a Source #

defaultFreeTextFieldDefST Source #

Arguments

:: forall g s (c :: Type -> Constraint). (Functor (g s), FieldGrammar c g) |
=> FieldName |
-> ALens' s ShortText | lens into the field
-> g s ShortText |

Default implementation for `freeTextFieldDefST`.

# Newtypes

module Distribution.FieldGrammar.Newtypes