# `Cauldron2D.Ledger`
[🔗](https://github.com/jaman/cauldron/blob/v0.1.3/cauldron_2d/lib/cauldron_2d/ledger.ex#L1)

Every player's results, kept on disk, and the boards made from them.

    {:ok, ledger} = Cauldron2D.Ledger.start_link(path: Cauldron2D.Paths.data(:my_game, "ledger.dets"), metrics: [kills: {:sum, :kills}, ratio: {:ratio, :kills, :deaths}, wins: {:count, :won?}])
    Cauldron2D.Ledger.record(ledger, "Pit", %{id: "alice", name: "alice", kills: 3, deaths: 1, won?: true})
    Cauldron2D.Ledger.board(ledger, :week, :kills, arena: "Pit")

A result is a map with the player's account as `:id` (their `:name` when there is no
id), the name they played under as `:name`, and whatever fields the metrics read. A
result whose id is `{:robot, n}` is not kept. `Cauldron2D.Ledger.Recorder` takes
them from a world's events.

## Metrics

The game declares its metrics as a keyword list, each one of:

  * `{:sum, field}` — the field summed over the rounds
  * `{:max, field}` — the field's largest value
  * `{:count, field}` — how many rounds had the field true
  * `{:ratio, field, by}` — the sum of `field` over the sum of `by`, to two places;
    the sum of `field` alone when `by` sums to zero
  * a function of the rounds returning a number

A board is the accounts of a period — `:day` (since midnight UTC), `:week` (the last
seven days) or `:all` — ranked by one metric, each with every metric's value, the
rounds counted and the name last played under, twenty at most. Boards are computed from
the table and kept for ten seconds.

# `entry`

```elixir
@type entry() :: %{
  name: String.t(),
  account: term(),
  value: number(),
  rounds: pos_integer(),
  values: %{required(metric()) => number()}
}
```

# `metric`

```elixir
@type metric() :: atom()
```

# `period`

```elixir
@type period() :: :day | :week | :all
```

# `board`

```elixir
@spec board(GenServer.server(), period(), metric(), keyword()) :: [entry()]
```

The board of `period` by `metric`; `arena:` narrows it to one arena.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `count`

```elixir
@spec count(GenServer.server()) :: non_neg_integer()
```

How many results are kept.

# `forget`

```elixir
@spec forget(GenServer.server(), (map() -> boolean())) :: non_neg_integer()
```

Drop every result `keep_out?` is true of — a function of the row as it was recorded, with its `:arena` and `:at` — and say how many went.

# `metrics`

```elixir
@spec metrics(GenServer.server()) :: [metric()]
```

The metrics the ledger was started with, in order.

# `record`

```elixir
@spec record(GenServer.server(), String.t(), map(), DateTime.t()) :: :ok
```

Keep a result from `arena`, taken `at` (default now).

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Start the ledger.

## Options

  * `:path` — the DETS file. Required
  * `:metrics` — the metrics, as the module documentation describes. Required
  * `:name` — the registered name; default the module, `nil` for none

---

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