# `CsvGenerator`
[🔗](https://github.com/Hermanverschooten/csv_generator/blob/v0.2.1/lib/csv_generator.ex#L1)

This library provides an easy way to generate CSV files.
It allows you to define the colums and their respective types.

## Example

    defmodule MyCSV do
      use CsvGenerator

      column :name, :string
      column :joined, :date, format: "%d-%m-%Y"
      column :points, :integer, label: "points earned"
      hardcoded :string, "Game", "domino"
    end

You would then render the CSV bij calling the `render/1` method with
the list of lines to render.

## Example

    iex> MyCSV.render([ 
       %{ name: "Chris McCord", joined: ~D[2020-01-01], points: 110},
       %{ name: "Jose Valim", joined: ~D[2020-03-29], points: 10} ])
    "\"name\",\"joined\",\"points earned\",\"Game\"\n\"Chris McCord\",01-01-2020,110,\"domino\"\n\"Jose Valim\",29-03-2020,10,\"domino\""

By default the CSV columns will be seperated by a `","`, the lines by a `"\n"`.
This can be changed by using `delimiter` and `line_ending`.

## Example

    defmodule MyCSV do
      use CsvGenerator

      delimiter ";"
      line_ending "\r\n"

      column :name, :string
      column :birthday, :date, format: "%d-%m-%Y"
      column :points, :integer
    end

    iex> MyCSV.render([ 
       %{ name: "Jose Valim", joined: ~D[2020-03-29], points: 10} ])
    "\"name\";\"joined\";\"points earned\"\n\"Jose Valim\";29-03-2020;10"

# Formatting

A formatter is included, to be able to have `mix format` use it, you have to add it to your own `.formatter.exs` in `import_deps`.

## Example

    [
      import_deps: [:ecto, :phoenix, :csv_generator],
      inputs: ["*.{ex,exs}", "priv/*/seeds.exs", "{config,lib,test}/**/*.{ex,exs}"],
      subdirectories: ["priv/*/migrations"]
    ]

# `column`
*macro* 

Defines a column in the CSV.

`column name, type, options`

The column name will be used to select the value from the given input.

The following types are currently supported:

Type         | Elixir type             | Default format
:----------- | :---------------------- | :------------------
`:string`    | `String`                | n/a
`:integer`   | `Integer`               | n/a
`:float`     | `Float`                 | n/a
`:date`      | `Date`                  | `"%Y-%m-%d"`
`:time`      | `DateTime` or `Integer` | `"%H:%M"`
`:datetime`  | `DateTime`              | `"%Y-%m-%d %H:%M:%S"`

For `:date`, `:time`, and `:datetime`, any of the Date(Time) types that
are compatible with `Calendar.strftime/2` are allowed.
`:time` also allows an `Integer` value that represents the time within a day.

## Options

  * `:header` - Use this instead of the name for column header.

  * `:format` - Supply a different format string, see `Calendar.strftime/2`.

  * `:digits` - Supply the number of digits for a `Float`.

  * `:with`   - Specifies a function to be called on the value before processing.
                column :value, :integer, with: &calc/1 or
                column :value, :integer, with: fn(x) -> x * 2 end
  * `:source` - Use another field as the source for this column, this allows you to use the same column multiple times.

## nil values

Columns with a `nil` value will be empty in the output.
If you do not want this, if you want some _default_ value, then use the `with:` option to supply a function that transforms the `nil` into something, formatting and rounding options will be applied.
    column :c3po, :integer, with: fn i -> if i == nil, do: 0, else: i end

# `decimal_point`
*macro* 

Specify the decimal point, default: "."

## Example

    decimal_point ","

# `delimiter`
*macro* 

Specify the character to use as column delimiter, default: ","

## Example

    delimiter ";"

# `hardcoded`
*macro* 

Defines a column in the CSV that will always have the same hardcoded value.

## Example

    hardcoded :string, "name", "John"

For `type` check out the possibilities in `column/3`.
Make sure the `value` is of `type`.

# `header`
*macro* 

Add the header to the generated CSV, default: true.

## Example

    header false

# `line_ending`
*macro* 

Specify the line ending to use, default: "\n".

## Example

    line_ending "\r\n"

---

*Consult [api-reference.md](api-reference.md) for complete listing*