Parser for a field. TODO: define what a field is

If you want to build more complex parsers, use the attoparsecText and attoparsecBytes functions to build a parser from a bytestring.

If you want to nest parsers, e.g. first want to decode to Text via utf-8 and then parse the Text, use the Semigroupoid/Category instances to chain parsers.

As a general rule, when you create an error message, try to include the value (or a shortened version of the value) that was not accepted. Otherwise the error will be hard to debug.

An alias for FieldParser' for the common case where err = Error.

Execute the field parser.

Change the type of the err in a field Parser.`

Turn a FieldParser Value directly into a valid parseJSON implementation.

If you want to parse any objects or lists, it’s better to use toAesonParser with jsonParser instead, but for simple json scalars this one is better.

Turn a FieldParser' ErrorTree Value directly into a valid parseJSON implementation.

If you want to parse any objects or lists, it’s better to use toAesonParser with jsonParser instead, but for simple json scalars this one is better.

Turn a FieldParser Value into an ParseT which parses this value.

parse a json boolean from a Value

parse a json null from a Value

parse a json number from a Value

parse a json string from a Value

Parse field as Text

Assert that the string is not empty

A decimal number with an optional + or - sign character.

A decimal natural number; does not allow for a +-sign.

A signed, decimal, natural number.

e.g. 12345, 0, or +12, but not -12.

Parse any integral into a natural number, fails if the integral is negative.

Parse any integral to an Integer. This can never fail, but is here to mirror integralToNatural.

An arbitrary-precision number in scientific notation.

Parse a scientific into a bounded integral type.

Scientific can be *very* big, (think 1e10000) so this function makes sure we * don’t wrap around the bound * don’t fill up all our memory by e.g. parsing into Integer or Natural.

So if you want to go to Natural, you have to first set an intermediate type with a bound you want to accept (e.g. 64 bits via Int) and then go from that to the unbounded type (e.g. via integralToNatural).

err is added as context around the bounded error.

Parse a scientific into a bounded floating point type.

Scientific can be *very* big, (think 1e10000) so this function makes sure we * don’t wrap around the bound * don’t fill up all our memory * Fit into the available floating point representation space

Parse an integer into a bounded integral type.

err is added as context around the bounded error.

ex: 2021-02-23

Parse a timestamp into a UTC time, accepting only UTC timestamps like yyyy-mm-ddThh:mm:ss[.sss]Z (ISO 8601:2004(E) sec. 4.3.2 extended format)

Parse a timestamp into a UTC time, accepting multiple timezone formats. Do not use this if you can force the input to use the Z UTC notation (e.g. in a CSV), use utcTime instead.

Accepts

• UTC timestamps: yyyy-mm-ddThh:mm:ss[.sss]Z
• timestamps with time zone: yyyy-mm-ddThh:mm:ss[.sss]±hh:mm

( both ISO 8601:2004(E) sec. 4.3.2 extended format)

The time zone of the second kind of timestamp is taken into account, but normalized to UTC (it’s not preserved what the original time zone was)

Example of how to create a more “complicated” parser that checks whether a value is between two other values.

oneOf prettyFrom oneOfMap

Takes a oneOf, which is a list of possibilities that this parser accepts. The comparison is done with (==), and then the according to value is returned.

In case of an error prettyFrom is used to pretty-print the available choices and actual input.

If you want to match on an Enum-like type, you should probably use invertPretty or invertPrettyCaseInsensitive instead, which allows for exhaustiveness checks.

oneOf, but takes a map directly.

| oneOfMap prettyFrom oneOfMap

Takes a oneOfMap, which is a map of possibilities that this parser accepts.

In case of an error prettyFrom is used to pretty-print the available choices and actual input.

Parse into an enum from a textual description of the fields.

The given function is inverted with inverseMap and then used as the parsing function.

Try to run the first parser, or if it fails run the second one; return an Either.

Try to run the first parser, or if it fails run the next one; They have to return the same value.

Parse into Nothing if the Monoid (e.g. Text, Map etc.) was empty

Given a pretty printing function, it will create a parser that uses the inverse function to parse the field.

The pretty printing function must create a different output for different inputs! Otherwise which value is returned is undefined.

Given a pretty printing function, it will create a parser that uses the inverse function to parse the field. The parsed text is compared case-insensitively.

The pretty printing function must create a different output for different inputs! This also means two outputs should not match if compared case-insensitively. Otherwise which value is returned is undefined.

oneOf but only one value possible

Takes a parser and lifts it to parse every element in a list.

Wrap a FieldParser with some descriptions for generating better error messages.

Splits the input string into multiple elements based on the given separator string.

Each element is then passed to the provided innerParser.

This returns a descriptive tree of errors containing the errors of each sub-parser that failed.

Ignore whitespace around a text.

Shows how to use the profunctor instance to do pure transformations (that cannot throw any errors).

Alternatively this could be implemented in the FieldParser pipeline like ignore = FieldParser $ t -> Right (Text.strip t)

Given an error message and an attoparsec parser, “clamp” the parser that it expects to match until the end of the string, then run the parser and put the given error message on error.

This function works on Data.Attoparsec.Text parsers.

Given an error message and an attoparsec parser, “clamp” the parser that it expects to match until the end of the string, then run the parser and put the given error message on error.

This function works on Data.Attoparsec.ByteString parsers.

Parse a literal value at compile time. This is used with Template Haskell, like so:

$$("2023-07-27" & literal hyphenatedDay) :: Time.Day

You need the double $$!

ATTN: This needs an instance of the Lift class for the output type. Many library types don’t yet implement this class, so we have to provide the instances ourselves. See NOTE: Lift for library types