Csv.Decode

CSV decoding, heavily inspired by [url-parser][].

Note this library does not include an underlying CSV parser. It assumes you are using something like [periodic/elm-csv][periodic] or [lovasoa/elm-csv][lovasoa] to get from String to Csv, where Csv is:

type alias Csv =
  { headers : List String
  , records : List (List String)
  }

This library gets you the rest of the way, to a list of your own types. It also collects errors together with the index of the record they occurred on.

You can think of this as analogous to Json.Decode. It lets you declaratively convert data from an intermediate representation (Json.Value or Csv) into your own types.

Basic usage

Using periodic/elm-csv (which returns a Result (List String) Csv):

Csv.parse rawData |> Csv.Decode.decode myDecoder

Using lovasoa/elm-csv (which returns a plain Csv):

Csv.parse rawData |> Csv.Decode.decodeCsv myDecoder

You can define decoders based on field position or on header name. See examples below.

Types

type alias Csv =

{ headers : List String

, records : List (List String)

}

The raw CSV data structure.

type Decoder a b

A value that encapsulates how to decode CSV records (List String)

Running

decode :

Decoder (a -> a) a

-> Result (List String) Csv

-> Result Errors (List a)

Decode the raw result of CSV parsing.

Typically you chain them together like this (using periodic/elm-csv):

Csv.parse rawData |> Csv.Decode.decode myDecoder

decodeCsv : Decoder (a -> a) a -> Csv -> Result Errors (List a)

Decode raw CSV data.

This is useful if you already have a Csv structure not wrapped in a Result, for instance lovasoa/elm-csv parses CSV strings this way.

Defining

next : (String -> Result String a) -> Decoder (a -> b) b

Decode the next field from the input: positional decoding.

Use this when you are certain of the order of the fields. It is faster than header-based decoding.

type alias Coordinates =
    { x : Float, y : Float, z : Float }


decodeCoordinates : Decoder (Coordinates -> a) a
decodeCoordinates =
    map Coordinates
        ( next String.toFloat
            </> next String.toFloat
            </> next String.toFloat
        )

field : String -> (String -> Result String a) -> Decoder (a -> b) b

Decode the named field from the input: header-based decoding.

Use this when you do not want to rely on the order of the fields, or when your source fields map to more than one target field.

type alias Nutrition =
   { name : String, calories : Int, protein : Float }


decodeNutrition : Decoder (Nutrition -> a) a
decodeNutrition =
    map Nutrition
        ( field "name" Ok
            </> field "calories"  String.toInt
            </> field "protein" String.toFloat
        )

Note that position- and header-based decoding can be combined, but it is not generally recommended.

assertNext : String -> Decoder a a

Decode the next field if it matches the given string.

This can be useful to decode a union type based on a field of the CSV. For example:

type Mailing
    = Letter Float
    | Parcel Float Dimensions


decodeMailing : Decoder (Mailing -> a) a
decodeMailing =
    oneOf
        [ map Letter
              ( assertNext "LETTER"
                  </> next String.toFloat
              )
        , map Parcel
              ( assertNext "PARCEL"
                  </> next String.toFloat
                  </> next parseDimensions
              )
        ]

(Note: If you are familiar with the url-parser library, this is structurally similar to the s function.)

assertField : String -> String -> Decoder a a

Decode a named field if it matches the given string.

The same example above, but for header-based decoding:

type Mailing
    = Letter Float
    | Parcel Float Dimensions


decodeMailing : Decoder (Mailing -> a) a
decodeMailing =
    oneOf
        [ map Letter
              ( assertField "type" "LETTER"
                  </> field "weight" String.toFloat
              )
        , map Parcel
              ( assertField "type" "PARCEL"
                  </> field "weight" String.toFloat
                  </> field "dimensions"  parseDimensions
              )
        ]

maybe : (String -> Result String a) -> String -> Result String (Maybe a)

A convenience function for converting empty strings to Nothing. Useful when you have optional fields.

type alias Letter =
    { weight = Float
    , insurance = Maybe CurrencyAmount
    }


decodeLetter : Decoder (Letter -> a) a
decodeLetter =
    map Letter
        ( field "weight" String.toFloat
            </> field "insurance"  (maybe parseCurrencyAmount)
        )

Combining

(</>) : Decoder a b -> Decoder b c -> Decoder a c

Decode multiple fields.

decodeCsv 
    (assertField "site" "blog" 
        </> field "id" String.toInt
    ) 
    data


-- { headers = [ "site", "id" ]
-- , records = [["blog","35"]] 
-- }   ==>  Ok [35]

oneOf : List (Decoder a b) -> Decoder a b

Try a bunch of different decoders, using the first one that succeeds.

type IntOrFloat
   = Int_ Int
   | Float_ Float


decode : Decoder (IntOrFloat -> a) a
decode =
    oneOf
      [ map Int_ <| next String.toInt
      , map Float_ <| next String.toFloat
      ]

map : a -> Decoder a b -> Decoder (b -> c) c

Transform a decoder.

Typically used to feed a bunch of parsed state into a type constructor.

type alias Comment = { author : String, id : Int }


decodeRawComment : Decoder (String -> Int -> a) a
decodeRawComment =
    field "author" Ok </> field "id" String.toInt


decodeComment : Decoder (Comment -> a) a
decodeComment =
    map Comment decodeRawComment

Errors

type Errors

= CsvErrors (List String)

| DecodeErrors (List ( Int, String ))

Errors can either be

Errors passed through from the underlying CSV parsing (CsvErrors), or
Errors in decoding a list of parsed records to models (DecodeErrors)

Note that the latter reports the record index together with the error message.

Modules

Csv.Decode

ericgj/elm-csv-decode/1.0.0