Character encodings

This module is intended for parsing text that is
represented using an 8-bit character set, e.g. ASCII or
ISO-8859-15. It does not make any attempt to deal with character
encodings, multibyte characters, or wide characters. In
particular, all attempts to use characters above code point U+00FF
will give wrong answers.

Code points below U+0100 are simply translated to and from their
numeric values, so e.g. the code point U+00A4 becomes the byte
0xA4 (which is the Euro symbol in ISO-8859-15, but the generic
currency sign in ISO-8859-1). Haskell Char values above U+00FF
are truncated, so e.g. U+1D6B7 is truncated to the byte 0xB7.

The parse failed. The t parameter is the
input that had not yet been consumed when the
failure occurred. The [String] is a list of
contexts in which the error occurred. The
String is the message describing the error, if
any.

Note: This predicate only gives correct answers for the ASCII
encoding. For instance, it does not recognise U+00A0 (non-breaking
space) as a space character, even though it is a valid ISO-8859-15
byte. For a Unicode-aware and only slightly slower predicate,
use isSpace

Efficient string handling

string s parses a sequence of bytes that identically match
s. Returns the parsed string (i.e. s). This parser consumes no
input if it fails (even if a partial match).

Note: The behaviour of this parser is different to that of the
similarly-named parser in Parsec, as this one is all-or-nothing.
To illustrate the difference, the following parser will fail under
Parsec given an input of "for":

string "foo" <|> string "for"

The reason for its failure is that the first branch is a
partial match, and will consume the letters 'f' and 'o'
before failing. In Attoparsec, the above parser will succeed on
that input, because the failed first branch will consume nothing.

A stateful scanner. The predicate consumes and transforms a
state argument, and each transformed state is passed to successive
invocations of the predicate on each byte of the input until one
returns Nothing or the input ends.

This parser does not fail. It will return an empty string if the
predicate returns Nothing on the first byte of input.

Note: Because this parser does not fail, do not use it with
combinators such as many, because such parsers loop until a
failure occurs. Careless use will thus result in an infinite loop.

Consume input as long as the predicate returns False
(i.e. until it returns True), and return the consumed input.

This parser does not fail. It will return an empty string if the
predicate returns True on the first byte of input.

Note: Because this parser does not fail, do not use it with
combinators such as many, because such parsers loop until a
failure occurs. Careless use will thus result in an infinite loop.

String combinators

The .*> and <*. combinators are intended for use with the
OverloadedStrings language extension. They simplify the common
task of matching a statically known string, then immediately
parsing something else.

If we were to try to use *> above instead, the type checker would
not be able to tell which IsString instance to use for the text
in quotes. We would have to be explicit, using either a type
signature or the string parser.

Note: This function is almost ten times faster than rational,
but is slightly less accurate.

The Double type supports about 16 decimal places of accuracy.
For 94.2% of numbers, this function and rational give identical
results, but for the remaining 5.8%, this function loses precision
around the 15th decimal place. For 0.001% of numbers, this
function will lose precision at the 13th or 14th decimal place.

This function does not accept string representations of "NaN" or
"Infinity".

This parser accepts an optional leading sign character, followed by
at least one decimal digit. The syntax similar to that accepted by
the read function, with the exception that a trailing '.' or
'e'not followed by a number is not consumed.

Examples with behaviour identical to read, if you feed an empty
continuation to the first result: