Distribution.Fields

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

A field name.

Invariant: ByteString is lower-case ASCII.

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.

Section arguments, e.g. name of the library

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.

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

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

>>> 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').

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

Like readFields but also return lexer warnings.

This type is used to discern when a comment block should go before or after a cabal-like file field, otherwise it would be hardcoded to a single position. It is often used in conjunction with PrettyField.

Prettyprint a list of fields.

Note: the first argument should return Strings without newlines and properly prefixes (with --) to count as comments. This unsafety is left in place so one could generate empty lines between comment lines.