A Decode e s a is for decoding some fields from a CSV row into our type a.

The second type parameter (s) is the input string type (usually ByteString or Text). The first type parameter (e) is the type of strings which occur in errors. Under most circumstances you want these type paraters to coincide, but they don't have to. They are two separate type parameters instead of one so that Decode can have a Profunctor instance.

There are primitive Decodes, and combinators for composing or otherwise manipulating them. In particular, Decode is an Applicative functor and an Alt from the semigroupoids package, also known as a SemiAlternative.

Decode is not a Monad, but we can perform monad-like operations on it with >>== or bindDecode

Decode' is Decode with the input and error types the same. You usually want them to be the same, and most primitives are set up this way.

DecodeValidation is the error-accumulating Applicative underlying Decode

DecodeError is a value indicating what went wrong during a parse or decode. Its constructor indictates the type of error which occured, and there is usually an associated string with more finely-grained details.

DecodeErrors is a Semigroup full of DecodeError. It is used as the error side of a DecodeValidation. When multiple errors occur, they will be collected.

Decodes a sv into a list of its values using the provided Decode

Build a Decode, given a function that returns Maybe.

Return the given error if the function returns Nothing.

Build a Decode, given a function that returns Either.

Build a Decode, given a function that returns Either, and a function to build the error.

Map over the errors of a Decode

To map over the other two parameters, use the Profunctor instance.

This transforms a Decode' s a into a Decode' t a. It needs functions in both directions because the errors can include fragments of the input.

alterInput :: (s -> t) -> (t -> s) -> Decode' s a -> Decode' t a

This is the primitive for building decoders that work with columns

Look for the column with the given name and run the given decoder on it

Infix alias for column

Mnemonic: Dot colon names Decoders, Equal colon names Encoders.

Get the contents of a field without doing any decoding. This never fails.

Get a field that's a single char. This will fail if there are mulitple characters in the field.

Get the contents of a field as a bytestring.

Alias for contents

Get the contents of a UTF-8 encoded field as Text

This will also work for ASCII text, as ASCII is a subset of UTF-8

Get the contents of a field as a lazy Text

Get the contents of a field as a lazy ByteString

Get the contents of a field as a String

Decode a UTF-8 ByteString field as an Int

Decode a UTF-8 ByteString field as an Integer

Decode a UTF-8 ByteString field as a Float

Decode a UTF-8 ByteString field as a Double

This is currently the fastest and most precise way to decode doubles.

Decode a UTF-8 ByteString as any Floating type (usually Double)

Decode a field as a Bool

This aims to be tolerant to different forms a boolean might take.

Decode a field as a Bool. This version lets you provide the fromString function that's right for you, since IsString on a ByteString will do the wrong thing in the case of many encodings such as UTF-16 or UTF-32.

This aims to be tolerant to different forms a boolean might take.

Throw away the contents of a field. This is useful for skipping unneeded fields.

Throw away the contents of a field, and return the given value.

Decode exactly the given string, or else fail.

Succeed only when the given field is the empty string.

The empty string surrounded in quotes or spaces is still the empty string.

Grab the whole row as a Vector

Choose the leftmost Decode that succeeds. Alias for <!>

Choose the leftmost Decode that succeeds. Alias for asum1

Try the given Decode. If it fails, succeed without consuming anything.

This usually isn't what you want. ignoreFailure and orEmpty are more likely what you are after.

Try the given Decode. If it fails, instead succeed with Nothing.

If the field is the empty string, succeed with Nothing. Otherwise try the given Decode.

Try the first, then try the second, and wrap the winner in an Either.

This is left-biased, meaning if they both succeed, left wins.

Try the given decoder, otherwise succeed with the given value.

Try the given decoder, or if it fails succeed with the given value, in an Either.

Decode categorical data, given a list of the values and the strings which match them.

Usually this is used with sum types with nullary constructors.

data TrafficLight = Red | Amber | Green
categorical [(Red, "red"), (Amber, "amber"), (Green, "green")]

Decode categorical data, given a list of the values and lists of strings which match them.

This version allows for multiple strings to match each value, which is useful for when the categories are inconsistently labelled.

data TrafficLight = Red | Amber | Green
categorical' [(Red, ["red", "R"]), (Amber, ["amber", "orange", "A"]), (Green, ["green", "G"])]

For another example of its usage, see the source for boolean.

This can be used to build a Decode whose value depends on the result of another Decode. This is especially useful since Decode is not a Monad.

If you need something like this but with more power, look at bindDecode

flipped >>==

Bind through a Decode.

This bind does not agree with the Applicative instance because it does not accumulate multiple error values. This is a violation of the Monad laws, meaning Decode is not a Monad.

That is not to say that there is anything wrong with using this function. It can be quite useful.

Build a Decode from a Read instance

Build a Decode from a Read instance.

This version takes a function which lets you build your own error message in the event of a failure.

Use the Readable instance to try to decode the given value.

Use the Readable instance to try to decode the given value, or fail with the given error message.

Use the Readable instance to try to decode the given value, or use the value to build an error message.

Build a Decode from a Trifecta parser

Build a Decode from an Attoparsec parser

Build a Decode from a Parsec parser

Build a Decode from a Data.Text Reader

Run a Decode, and based on its errors build a new Decode.

Build a failing DecodeValidation

Fail with UnexpectedEndOfRow

Fail with ExpectedEndOfRow. This takes the rest of the row, so that it can be displayed to the user.

Fail with UnknownCategoricalValue. It takes the unknown value and the list of good categorical values.

This mostly exists to be used by the categorical function.

Fail with BadParse with the given message. This is for when the parse step fails, and decoding does not even begin.

Fail with BadDecode with the given message. This is something of a generic error for when decoding a field goes wrong.

Build a DecodeValidation from an Either

Build a DecodeValidation from an Either, given a function to build the error.

Build a DecodeValidation from a Maybe. You have to supply an error to use in the Nothing case

Convenience to get the underlying function out of a Decode in a useful form

Convenient constructor for Decode that handles all the newtype noise for you.

Build a Decode from a function.

Promotes a Decode to work on a whole Record at once. This does not need to be called by the user. Instead use decode.

Promotes a Decode to work on a whole Record at once. This does not need to be called by the user. Instead use decode.

This version lets the error string and input string type pararms differ, but needs a function to convert between them.

Convenience to get the underlying function out of a NameDecode in a useful form

Promote a Decode to a NameDecode that doesn't look for any names

Given a header and a NameDecode, resolve header names to positions and return a Decode