HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

ModuleCabal-syntax-3.12.1.0Haskell2010

Distribution.Fields.Parser

  • 4 types
  • 2 values

Types

4 declarations
datadata Field ann
#

A Cabal-like file consists of a series of fields (foo: bar) and sections (library ...).

Constructors

Instances7Functor, Foldable, Traversable, Foldable1, Eq, Ord, …
  • Functor FieldDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Foldable FieldDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Traversable FieldDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Foldable1 FieldDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Eq ann => Eq (Field ann)Defined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Ord ann => Ord (Field ann)Defined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Show ann => Show (Field ann)Defined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
datadata Name ann
#

A field name.

Invariant: ByteString is lower-case ASCII.

Constructors

Instances7Functor, Foldable, Traversable, Foldable1, Eq, Ord, …
  • Functor NameDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Foldable NameDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Traversable NameDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Foldable1 NameDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Eq ann => Eq (Name ann)Defined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Ord ann => Ord (Name ann)Defined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Show ann => Show (Name ann)Defined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
datadata FieldLine ann
#

A line of text representing the value of a field from a Cabal file. A field may contain multiple lines.

Invariant: ByteString has no newlines.

Constructors

Instances7Functor, Foldable, Traversable, Foldable1, Eq, Ord, …
  • Functor FieldLineDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Foldable FieldLineDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Traversable FieldLineDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Foldable1 FieldLineDefined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Eq ann => Eq (FieldLine ann)Defined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Ord ann => Ord (FieldLine ann)Defined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
  • Show ann => Show (FieldLine ann)Defined in Cabal-syntax-3.12.1.0 · Distribution.Fields.Field
datadata SectionArg ann
#

Section arguments, e.g. name of the library

Constructors

Instances7Functor, Foldable, Traversable, Foldable1, Eq, Ord, …

Grammar and parsing

2 declarations
CabalStyleFile ::= SecElems

SecElems       ::= SecElem* '\n'?
SecElem        ::= '\n' SecElemLayout | SecElemBraces
SecElemLayout  ::= FieldLayout | FieldBraces | SectionLayout | SectionBraces
SecElemBraces  ::= FieldInline | FieldBraces |                 SectionBraces
FieldLayout    ::= name : line? ('\n' line)*
FieldBraces    ::= name : '\n'? '{' content '}'
FieldInline    ::= name : content
SectionLayout  ::= name arg* SecElems
SectionBraces  ::= name arg* '\n'? '{' SecElems '}'

and the same thing but left factored...

SecElems              ::= SecElem*
SecElem               ::= '\n' name SecElemLayout
                        |      name SecElemBraces
SecElemLayout         ::= :   FieldLayoutOrBraces
                        | arg*  SectionLayoutOrBraces
FieldLayoutOrBraces   ::= '\n'? '{' content '}'
                        | line? ('\n' line)*
SectionLayoutOrBraces ::= '\n'? '{' SecElems '\n'? '}'
                        | SecElems
SecElemBraces         ::= : FieldInlineOrBraces
                        | arg* '\n'? '{' SecElems '\n'? '}'
FieldInlineOrBraces   ::= '\n'? '{' content '}'
                        | content

Note how we have several productions with the sequence:

'\\n'? '{'

That is, an optional newline (and indent) followed by a { token. In the SectionLayoutOrBraces case you can see that this makes it not fully left factored (because SecElems can start with a \n). Fully left factoring here would be ugly, and though we could use a lookahead of two tokens to resolve the alternatives, we can't conveniently use Parsec's try here to get a lookahead of only two. So instead we deal with this case in the lexer by making a line where the first non-space is { lex as just the { token, without the usual indent token. Then in the parser we can resolve everything with just one token of lookahead and so without using try.

valuereadFields :: ByteString -> Either ParseError [Field Position]
#

Parse cabal style ByteString into list of Fields, i.e. the cabal AST.

readFields assumes that input ByteString is valid UTF8, specifically it doesn't validate that file is valid UTF8. Therefore bytestrings inside returned Field will be invalid as UTF8 if the input were.

Example1 expression
readFields "foo: \223"Right [Field (Name (Position 1 1) "foo") [FieldLine (Position 1 6) "\223"]]

readFields won't (necessarily) fail on invalid UTF8 data, but the reported positions may be off.

You may get weird errors on non-UTF8 input, for example readFields will fail on latin1 encoded non-breaking space:

Example1 expression
isLeft (readFields "\xa0 foo: bar")True

That is rejected because parser thinks \xa0 is a section name, and section arguments may not contain colon. If there are just latin1 non-breaking spaces, they become part of the name:

Example1 expression
readFields "\xa0\&foo: bar"Right [Field (Name (Position 1 1) "\160foo") [FieldLine (Position 1 7) "bar"]]

The UTF8 non-breaking space is accepted as an indentation character (but warned about by readFields').

Example1 expression
readFields' "\xc2\xa0 foo: bar"Right ([Field (Name (Position 1 3) "foo") [FieldLine (Position 1 8) "bar"]],[LexWarning LexWarningNBSP (Position 1 1)])