CSV

Add {:csv, "~> 3.2"} to your dependencies in mix.exs to use the library in your Elixir project.

defp deps do
  [{:csv, "~> 3.2"}]
end

For large files, performance is best when streaming with :read_ahead in byte mode. While 1000 bytes is a common default, you should tune this based on your environment.

File.stream!("data.csv", [read_ahead: 100_000], 1000) |> CSV.decode()

Use CSV.encode/1 to transform a table (a two-dimensional list) into a stream of lines ready for output (e.g., writing to a file or IO).

# Writing a table to a file
table_data |> CSV.encode |> Enum.each(&IO.write(file, &1))

You can implement the CSV.Encode protocol to define how custom data types should be encoded into CSV format.

defimpl CSV.Encode, for: MyData do
  def encode(%MyData{has: fun}, env \ []) do
    "so much #{fun}" |> CSV.Encode.encode(env)
  end
end

Use CSV.decode!/1 for strict mode. This returns a two-dimensional list (a list of lists) and will raise an exception immediately upon encountering the first error, aborting the operation.

You can use the unredact_exceptions: true option to ensure the source data is included in any exceptions thrown.

# Strict mode returns a list of lists and raises on error
File.stream!("data.csv") |> CSV.decode!

# Unredact source data in exceptions
File.stream!("data.csv") |> CSV.decode!(unredact_exceptions: true)

When calling CSV.decode/2 or CSV.decode!/2, you can pass an options keyword list to customize parsing:

• separator: Specify a custom separator (e.g., separator: ?;).
• escape_character: Specify a custom escape character (e.g., escape_character: ?@).
• field_transform: A function applied to each field during parsing (e.g., field_transform: &String.trim/1).
• unescape_formulas: Boolean to unescape formulas that have been escaped.
• redact_errors: Boolean to redact source data in error tuples produced by decode/1.

# Example: custom separator and field transformation
stream |> CSV.decode(separator: ?;, field_transform: &String.trim/1)

# Example: unescaping formulas
stream |> CSV.decode(unescape_formulas: true)

# Example: redacting errors
stream |> CSV.decode(redact_errors: true)

Customize the encoding process using CSV.encode/2:

• separator: Specify a custom separator (e.g., separator: ?;).
• escape_character: Specify a custom escape character (e.g., escape_character: ?@).
• headers:
  • Provide a list of strings to encode map values into specific positions: headers: ["z", "a"].
  • Provide a keyword list where keys are the map keys and values are the header names: headers: [a: "x", b: "y"].

# Using a semicolon separator
your_data |> CSV.encode(separator: ?;)

# Encoding maps with specific header positions
[%{"a" => "value!"}] |> CSV.encode(headers: ["z", "a"])
# Output: ["z,a\r\n", ",value!\r\n"]

# Encoding maps with custom header names via keyword list
[%{a: "value!"}] |> CSV.encode(headers: [a: "x", b: "y"])
# Output: ["x,y\r\n", "value!,\r\n"]

You can override the default comma separator and CRLF delimiter by passing :separator (as a codepoint) and :delimiter (as a string) to the encode/2 function.

[["a\nb", "\tc"], ["de", "\tf\""]]
|> CSV.Encoding.Encoder.encode(separator: ?\t, delimiter: "\n")
|> Enum.take(2)
# => ["\"a\nb\"\t\"\tc\"\n", "de\t\"\tf\"\"\"\n"]

When your input stream consists of maps, set headers: true to automatically extract keys from the first map to create a header row, followed by the values of each map as data rows.

[%{"a" => 1, "b" => 2}, %{"a" => 3, "b" => 4}]
|> CSV.Encoding.Encoder.encode(headers: true)
|> Enum.to_list()
# => ["a,b\r\n", "1,2\r\n", "3,4\r\n"]

To support custom data types in CSV generation, implement the CSV.Encode protocol. The encode/2 function receives the data to be encoded and an env keyword list containing the current encoding context (such as the separator and delimiter).

By default, the protocol falls back to Any, which converts the data to a string and then uses the BitString encoding implementation.

defimpl CSV.Encode, for: MyCustomType do
  def encode(data, env \ []) do
    # Your custom encoding logic here
    # env can contain :separator, :escape_character, :delimiter, etc.
  end
end