# `Ascii.Pieces.Candlesticks`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/pieces/candlesticks.ex#L1)

Hollow up candles, solid down ones, the last one forming live.

A price chart of five-minute candles, hollow when the price rose and solid
when it fell. As upstream draws it, a made-up market trades: the last
candle forms live, then the chart steps. Give it `candles` and it charts
your prices instead, standing still until you give it more.

## Options

Give them to `Ascii.new/2` as `options:`, and new ones while it plays
with `Ascii.put_options/2` (or a Phoenix player's `options`): the chart
is drawn anew from them, so give the whole list again as candles come and
close.

  * `candles` - your prices, each `[open, high, low, close]`, oldest
    first, the last being the one now forming. The last 15 show, against
    the axis. Default `[]`: upstream's market.
  * `times` - a label a candle, as `"09:30"`, its first five characters
    shown under every fourth candle. Default `[]`.
  * `digits` - decimals in the prices, 0 to 8. Default 2.
  * `start` - the price upstream's market starts from. Default 100.
  * `seed` - the seed of upstream's market, for another walk. Default 3.

With candles given, the price scale steps by 1, 2, 2.5 or 5 times a power
of ten, whatever the prices; upstream's steps stop at 100. A price too wide
for its place, which upstream writes past the frame's edge, is written to
fit (see `Ascii.Kit.Number`): on the axis, and the last price beside
it, with fewer decimals, then compactly (`16.6M`), the axis's prices all
alike; in the quote, the four prices alike, when it would run past the
frame. `start` and the candles take prices up to 10^15 either way. The
frame is always 70 by 22.

## Colours

In one ink, or a gradient, with `:ink` and `:gradient` (see
`Ascii.Ink`); part by part with `:parts` (see `Ascii.Parts`),
`parts: true` taking the colours suggested here:

  * `label` - the quote's names for its prices, `o`, `h`, `l` and `c`,
    grey.
  * `value` - the quote's prices.
  * `change.up`, `change.down` - the quote's change by its sign, green
    and red (just `change` for an open of zero).
  * `candle.up`, `candle.down` - each candle, wicks and all, hollow and
    green as the price rose, solid and red as it fell.
  * `price` - the last price's line out to the axis and its figure, blue.
  * `axis` - the axis and its ticks, grey.
  * `scale` - the prices and times along it, grey.

A wick whose body is off the chart, as a far-off `start` can put it, is in
no part.

## Keys and clicks

It takes none: it shows prices, and `Ascii.handle_event/2` ignores
every event. A Phoenix player given `interactive` and `notify` still tells
your LiveView where it was clicked, and on which part
(`Ascii.part_at/4`): a `candle.up`, say, or the `price`.

## Screen readers

`Ascii.describe/1` reads the candles given, how many, and the last
one's time, prices and change: "candlesticks: 2 candles, the last at
09:35: open 103.00, high 105.00, low 101.00, close 102.50, -0.49%".
Playing upstream's market, it gives the piece's name and note.

## Example

```elixir
candles = [[100, 104, 96, 103], [103, 105, 101, 102.5]]
chart = Ascii.new!("candlesticks", options: %{candles: candles, times: ["09:30", "09:35"]}, parts: true)

{frame, _chart} = Ascii.frame(chart, 0.0)
frame.text =~ "c 102.50"
#=> true

Ascii.describe(chart)
#=> "candlesticks: 2 candles, the last at 09:35: open 103.00, high 105.00, low 101.00, close 102.50, -0.49%"
```

```heex
<Ascii.Phoenix.live_player id="price" piece="candlesticks" options={%{candles: @candles, times: @times}} parts />
```

Ported from `src/pieces/candlesticks.ts` in bas3line/ascii (MIT).

---

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