# `Plotto`
[🔗](https://github.com/altenwald/plotto/blob/v0.6.0/lib/plotto.ex#L1)

Plotto generates SVG and PNG charts in pure Elixir.

## Example

    chart = Plotto.BarChart.new!([%{name: "Sales", data: [%{label: "Jan", value: 10}]}], title: "Sales")
    svg = Plotto.to_svg!(chart)
    png = Plotto.to_png!(chart)

## Supported Charts

- `Plotto.BarChart` - Grouped or stacked bar charts.
- `Plotto.LineChart` - Line and trend charts.
- `Plotto.CandlestickChart` - Candlestick (OHLC) financial charts.

## Options

All chart modules accept standard options via `new/2`/`new!/2`: `:width`, `:height`,
`:title`, `:colors`, `:legend`. See `Plotto.BarChart`, `Plotto.LineChart`, and
`Plotto.CandlestickChart` for their chart-specific options (e.g. `:mode` for bar charts,
`:bullish_color` and `:bearish_color` for candlestick charts).

## Error handling

`to_svg/1` and `to_png/1` return `{:ok, result} | {:error, reason}` and never raise.
`to_svg!/1` and `to_png!/1` return the result directly and raise `ArgumentError` if
rendering fails.

# `to_png`

```elixir
@spec to_png(struct()) :: {:ok, binary()} | {:error, String.t()}
```

Renders a chart (`Plotto.BarChart`, `Plotto.LineChart`, or `Plotto.CandlestickChart`) to a PNG binary.

Returns `{:ok, png}` on success or `{:error, reason}` if rendering fails.

## Examples

    iex> chart = Plotto.BarChart.new!([%{name: "Sales", data: [%{label: "Jan", value: 10}]}])
    iex> {:ok, png} = Plotto.to_png(chart)
    iex> binary_part(png, 0, 8) == <<137, 80, 78, 71, 13, 10, 26, 10>>
    true

# `to_png!`

```elixir
@spec to_png!(struct()) :: binary()
```

Same as `to_png/1`, but returns the PNG binary directly and raises `ArgumentError`
if rendering fails.

## Examples

    iex> chart = Plotto.BarChart.new!([%{name: "Sales", data: [%{label: "Jan", value: 10}]}])
    iex> Plotto.to_png!(chart) |> binary_part(0, 8) == <<137, 80, 78, 71, 13, 10, 26, 10>>
    true

# `to_svg`

```elixir
@spec to_svg(struct()) :: {:ok, String.t()} | {:error, String.t()}
```

Renders a chart (`Plotto.BarChart`, `Plotto.LineChart`, or `Plotto.CandlestickChart`) to an SVG string.

Returns `{:ok, svg}` on success or `{:error, reason}` if rendering fails.

## Examples

    iex> chart = Plotto.BarChart.new!([%{name: "Sales", data: [%{label: "Jan", value: 10}]}])
    iex> {:ok, svg} = Plotto.to_svg(chart)
    iex> String.starts_with?(svg, "<svg")
    true

# `to_svg!`

```elixir
@spec to_svg!(struct()) :: String.t()
```

Same as `to_svg/1`, but returns the SVG string directly and raises `ArgumentError`
if rendering fails.

## Examples

    iex> chart = Plotto.BarChart.new!([%{name: "Sales", data: [%{label: "Jan", value: 10}]}])
    iex> Plotto.to_svg!(chart) |> String.starts_with?("<svg")
    true

---

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