Documentation

A prism which attempts to parse a ByteString into a structured Csv' Name.

This uses the first row of the csv as headers.

Note that this prism will silently fail to match if your CSV is malformed. Follow up with rows, row, or headers

>>> :t  myCsv ^? namedCsv
myCsv ^? namedCsv :: Maybe (Csv' Name)

A prism which attempts to parse a ByteString into a structured Csv' Int.

Use this with CSVs which don't have a header row.

Note that this prism will silently fail to match if your CSV is malformed. Follow up with rows or row

>>> :t  myCsv ^? csv
myCsv ^? csv :: Maybe (Csv' Int)

An indexed fold over the CSV headers of a named CSV. Indexed by the column number starting at 0.

>>> myCsv ^.. namedCsv . headers
["state_code","population"]

>>> myCsv ^@.. namedCsv . headers
[(0,"state_code"),(1,"population")]

An indexed traversal over each row of the csv as a CsvRecord. Passes through a type witness signifying whether the records are Name or Int indexed.

Traversing rows of a named csv results in named records:

>>> myCsv ^.. namedCsv . rows
[NamedCsvRecord (fromList [("population","19540000"),("state_code","NY")]),NamedCsvRecord (fromList [("population","39560000"),("state_code","CA")])]

Traversing rows of an indexed csv results in indexed records:

>>> myCsv ^.. csv . dropping 1 rows
[CsvRecord (["NY","19540000"]),CsvRecord (["CA","39560000"])]

Traverse a specific row of the csv by row number.

Parse and traverse the fields of a CsvRecord into the inferred FromField type. Focuses are indexed by either the column headers or column number accordingly.

Be careful to provide appropriate type hints to columns so that it knows which Field type to parse into, any fields which fail to parse will be simply ignored, you can use this strategically to select all fields of a given type within a record.

>>> myCsv ^.. namedCsv . row 0 . columns @String
["19540000","NY"]

>>> myCsv ^.. namedCsv . row 0 . columns @Int
[19540000]

columns is indexed, you can use the column number or column header.

>>> myCsv ^@.. namedCsv . row 0 . columns @String
[("population","19540000"),("state_code","NY")]

>>> myCsv ^@.. namedCsv . row 0 . columns @Int
[("population",19540000)]

>>> BL.lines (myCsv & namedCsv . rows . columns @Int %~ subtract 1)
["state_code,population\r","NY,19539999\r","CA,39559999\r"]

A more flexible version of columns which allows the focused field to change types. Affords worse type inference, so prefer columns when possible.

See columns for usage examples

Select a specific column of a record by the appropriate index type, either Name for namedCsvs or Int for csvs

See columns for more usage ideas.

>>> myCsv ^.. namedCsv . rows . column @Int "population"
[19540000,39560000]

>>> myCsv ^.. csv . dropping 1 rows . column @String 0
["NY","CA"]

A more flexible version of column which allows the focused field to change types. Affords worse type inference, so prefer column when possible.

See column for usage examples

A prism which attempt to parse the given record into a type using FromRecord.

Tuples implement FromRecord:

>>> myCsv ^.. csv . row 1 . _Record @(String, Int)
[("NY",19540000)]

If we parse each row into a tuple record we can swap the positions and it will write back into a valid CSV.

>>> import Data.Tuple (swap)
>>> BL.lines (myCsv & csv . rows . _Record @(String, String) %~ swap)
["population,state_code\r","19540000,NY\r","39560000,CA\r"]

A more flexible version of _Record which allows the focus to change types. Affords worse type inference, so prefer _Record when possible.

See _Record for usage examples

Attempt to parse the given record into a type using FromNamedRecord.

>>> myCsv ^? namedCsv . row 0 . _NamedRecord @(M.Map String String)
Just (fromList [("population","19540000"),("state_code","NY")])

A more flexible version of _NamedRecord which allows the focus to change types. Affords worse type inference, so prefer _NamedRecord when possible.

See _NamedRecord for usage examples

Attempt to parse the given Field into a type using FromField.

You usually won't need this, column, columns, _Record, and _NamedRecord are usually more flexible and provide more power.

A more flexible version of _Field which allows the focus to change types. Affords worse type inference, so prefer _Field when possible.

You usually won't need this, column, columns, _Record, and _NamedRecord are usually more flexible and provide more power.

Csv' is a wrapper around cassava's csv type which carries the appropriate indexing and column header information.

A CSV Record which carries a type-level witness of whether the record is named or not.

A csv record with named columns has type CsvRecord Name where Name is simply an alias for ByteString

A csv record with numbered columns has type CsvRecord Int

An iso between the results of decode or decodeWith and a Csv' for use with this library.

You should typically just use namedCsv, but this can be helpful if you want to provide special options to provide custom decoding options.

>>> S.decodeByName  myCsv ^.. _Right . from cassavaNamed . rows . column @String "state_code"
["NY","CA"]

An iso between the results of decodeByName or decodeByNameWith and a Csv' for use with this library.

>>> S.decode HasHeader myCsv ^.. from cassavaUnnamed  . rows . column @String 0
["NY","CA"]

Allows rewritingaddingremoving headers on the CSV both before serializing Note that rewriting a header name DOES NOT affect any of the records, it only affects the choice and order of the columns in the output CSV. If you want to rename a column header you must also rename the name of that field on all rows in the csv.

This is a limitation of cassava itself.

Examples:

Drop the first column:

>>> BL.lines (myCsv & namedCsv . adjustingOutputHeaders (view _tail) %~ id)
["population\r","19540000\r","39560000\r"]

Add a new column with the population in millions

>>> import Data.Char (toLower)
>>> addStateLower m = M.insert "state_lower" (m ^. ix "state_code" . to (map toLower)) m
>>> :{
 BL.lines (myCsv
   & namedCsv
   -- Add "state_lower" to output headers so it will be serialized
   . adjustingOutputHeaders (<> pure "state_lower")
   . rows
   . _NamedRecord @(M.Map String String)
   -- Add "state_lower" to each record
   %~ addStateLower
          )
:}
["state_code,population,state_lower\r","NY,19540000,ny\r","CA,39560000,ca\r"]

Reverse column order >>> BL.lines (myCsv & namedCsv . adjustingOutputHeaders (view reversed) %~ id) ["population,state_coder","19540000,NYr","39560000,CAr"]