A way to specify what kind of thing you want to decode into. For example, if you have a Pet data type, you'd want a Decoder Pet.

Decode a string from a CSV.

decodeCsv NoFieldNames string "a" --> Ok [ "a" ]

Unless you specify otherwise (e.g. with column) this will assume there is only one column in the CSV and try to decode that.

decodeCsv NoFieldNames string "a,b"
--> Err (DecodingError { row = 0, problem = AmbiguousColumn })

Decode an integer from a CSV.

decodeCsv NoFieldNames int "1" --> Ok [ 1 ]


decodeCsv NoFieldNames int "-1" --> Ok [ -1 ]


decodeCsv NoFieldNames int "volcano"
--> Err (DecodingError { row = 0, problem = ExpectedInt "volcano" })

Unless you specify otherwise (e.g. with column) this will assume there is only one column in the CSV and try to decode that.

decodeCsv NoFieldNames int "1,2"
--> Err (DecodingError { row = 0, problem = AmbiguousColumn })

Decode an integer from a CSV.

decodeCsv NoFieldNames float "3" --> Ok [ 3.0 ]


decodeCsv NoFieldNames float "3.14" --> Ok [ 3.14 ]


decodeCsv NoFieldNames float "mimesis"
--> Err (DecodingError { row = 0, problem = ExpectedFloat "mimesis" })

Unless you specify otherwise (e.g. with column) this will assume there is only one column in the CSV and try to decode that.

decodeCsv NoFieldNames float "1.0,2.0"
--> Err (DecodingError { row = 0, problem = AmbiguousColumn })

Handle blank fields by making them into Maybes.

decodeCsv NoFieldNames (blank int) "\r\n1"
--> Ok [ Nothing, Just 1 ]


decodeCsv NoFieldNames (blank int) "not a number"
--> Err (DecodingError { row = 0, problem = ExpectedInt "not a number" })

Parse a value at a numbered column in the CSV, starting from 0.

decodeCsv NoFieldNames (column 0 string) "Argentina" --> Ok [ "Argentina" ]


decodeCsv NoFieldNames (column 1 int) "1,2,3" --> Ok [ 2 ]


decodeCsv NoFieldNames (column 100 float) "3.14"
--> Err (DecodingError { row = 0, problem = ExpectedColumn 100 })

Parse a value at a named column in the CSV. There are a number of ways to provide these names, see FieldNames

decodeCsv
    FieldNamesFromFirstRow
    (field "Country" string)
    "Country\r\nArgentina"
--> Ok [ "Argentina" ]


decodeCsv
    (CustomFieldNames [ "a", "b", "c" ])
    (field "b" int)
    "1,2,3"
--> Ok [ 2 ]


decodeCsv
    (CustomFieldNames [ "Constant" ])
    (field "Nonexistent" float)
    "3.14"
--> Err (DecodingError { row = 0, problem = ExpectedField "Nonexistent" })

Where do we get names for use with field?

• NoFieldNames: don't get field names at all. field will always fail.
• CustomFieldNames: use the provided field names in order (so ["Id", "Name"] will mean that "Id" is in column 0 and "Name" is in column 1.)
• FieldNamesFromFirstRow: use the first row of the CSV as the source of field names.

Convert a CSV string into some type you care about using the Decoders in this module!

Convert something shaped roughly like a CSV. For example, to decode tab-separated values where the row separator is a single newline character:

decodeCustom
    { rowSeparator = "\n"
    , fieldSeparator = "\t"
    }
    NoFieldNames
    (map2 Tuple.pair
        (column 0 int)
        (column 1 string)
    )
    "1\tBrian\n2\tAtlas"
    --> Ok [ ( 1, "Brian" ), ( 2, "Atlas" ) ]

Sometimes things go wrong. This is how we tell you what happened. If you need to present this to somone, you can get a human-readable version with errorToString

Some more detail:

• ConfigError: decodeCustom got a bad separator character
• ParsingError: there was a problem parsing the data (the most common issue is problems with quoted fields. Check that any quoted fields are closed and that quotes are escaped by doubling.)
• DecodingError: we couldn't decode a value using the specified decoder. See Problem for more details.

Want an human-readable version of an Error? Here we are!

Things that went wrong specifically while decoding.

• NoFieldNamesOnFirstRow: we tried to get the field names from the first row (using FieldNames) but couldn't find any, probably because the input was blank.
• ExpectedColumn Int and ExpectedField String: we looked for a value at a specific column, but couldn't find it. The argument specifies where we tried to look.
• AmbiguousColumn: basic decoders expect to find a single value. If there are multiple fields in a row, and you don't specify which one to use with column or field, you'll get this error.
• ExpectedInt String and ExpectedFloat String: we tried to parse a string into a number, but couldn't. The arguments specify the strings we got.
• Failure: messages from fail end up here.
• ManyProblems: when there are multiple failures, messages from oneOf end up here.

Decode a value, then transform it before returning.

decodeCsv NoFieldNames (map (\i -> i * 2) int) "15" --> Ok [ 30 ]


decodeCsv NoFieldNames (map String.reverse string) "slap" --> Ok [ "pals" ]

Combine two decoders to make something else, for example a tuple:

decodeCsv NoFieldNames
    (map2 Tuple.pair
        (column 0 int)
        (column 1 string)
    )
    "1,Atlas"
    --> Ok [ (1, "Atlas") ]

Like map2, but with three decoders. map4 and beyond don't exist in this package. Use pipeline to decode records instead!

decodeCsv NoFieldNames
    (map3 (\r g b -> (r, g, b))
        (column 0 int)
        (column 1 int)
        (column 2 int)
    )
    "255,255,0"
    --> Ok [ (255, 255, 0) ]

Need to decode into an object? Use a pipeline. The way this works: you provide a function that takes as many arguments as you need, and then send it values by providing decoders.

type alias Pet =
    { id : Int
    , name : String
    , species : String
    , weight : Float
    }


petDecoder : Decoder Pet
petDecoder =
    pipeline Pet
        |> required (column 0 int)
        |> required (column 1 string)
        |> required (column 2 string)
        |> required (column 3 float)

Now you can decode pets like this:

decodeCsv NoFieldNames petDecoder "1,Atlas,cat,14.5"
--> Ok [ { id = 1, name = "Atlas", species = "cat", weight = 14.5 } ]

See pipeline.

Try several possible decoders in sequence, committing to the first one that passes.

decodeCsv NoFieldNames (oneOf (map Just int) [ succeed Nothing ]) "1"
--> Ok [ Just 1 ]


decodeCsv NoFieldNames (oneOf (map Just int) [ succeed Nothing ]) "a"
--> Ok [ Nothing ]

Always succeed, no matter what. Mostly useful with andThen.

Always fail with the given message, no matter what. Mostly useful with andThen.

Decode some value and then make a decoding decision based on the outcome. For example, if you wanted to reject negative numbers, you might do something like this:

positiveInt : Decoder Int
positiveInt =
    int
        |> andThen
            (\rawInt ->
                if rawInt < 0 then
                    Decode.fail "Only positive numbers allowed!"


                else
                    Decode.succeed rawInt
            )

You could then use it like this:

decodeCsv NoFieldNames positiveint "1" -- Ok [ 1 ]


decodeCsv NoFieldNames positiveInt "-1"
-- Err { row = 0, problem = Failure "Only positive numbers allowed!" }

Make creating custom decoders a little easier. If you already have a function that parses a string into something you care about, you can probably provide it here and avoid having to build your own with andThen.

For example, here's how you could parse a hexadecimal number with rtfeldman/elm-hex:

import Hex


hex : Decoder Int
hex =
    fromResult Hex.fromString


decodeCsv NoFieldNames hex "ff"
--> Ok [ 255 ]