DicEx.Result (dicEx v0.1.0)

Copy Markdown View Source

The outcome of a roll: a structured, AI/consumer-friendly record plus helpers to reduce it to plain data (to_map/1) or flatten its kept dice (kept_values/1).

A result is made of one or more groups. Each group is either a dice pool (e.g. 2d20kh1) or a constant modifier (e.g. 5). Dice groups carry the individual die outcomes so you can render them, show advantage/disadvantage, or feed them to an LLM as structured data.

Example

iex> DicEx.roll("2d20kh1 + 5")
%DicEx.Result{
  expression: "2d20kh1 + 5",
  total: 23,
  groups: [
    %{kind: :dice, notation: nil, sides: 20, subtotal: 18,
      modifiers: [{:keep_high, 1}],
      rolls: [%{value: 18, kept: true, exploded: false},
              %{value: 7, kept: false, exploded: false}]},
    %{kind: :modifier, notation: nil, sides: nil, subtotal: 5,
      modifiers: [], rolls: []}
  ]
}

Note the per-group notation is left nil; the full expression is on the top-level expression field.

Summary

Types

group()
roll()
t()

Functions

kept_values(result)

Extracts just the flat list of kept die values across all dice groups, ignoring modifiers and dropped dice. Useful for quick sanity checks.

to_map(result)

Reduces a result to a plain map, ready for Phoenix.json/LLM consumption.

to_roll_event(result)

Builds the payload the JavaScript hook expects for a roll animation: %{expression, total, groups: [%{sides, subtotal, rolls: [%{value, kept, exploded}]}]}.

Types

group()

@type group() :: %{
  kind: :dice | :modifier,
  notation: String.t() | nil,
  sides: pos_integer() | nil,
  subtotal: integer(),
  modifiers: [term()],
  rolls: [roll()]
}

roll()

@type roll() :: %{value: pos_integer(), kept: boolean(), exploded: boolean()}

t()

@type t() :: %DicEx.Result{
  expression: String.t() | nil,
  groups: [group()],
  total: integer()
}

Functions

kept_values(result)

Extracts just the flat list of kept die values across all dice groups, ignoring modifiers and dropped dice. Useful for quick sanity checks.

to_map(result)

Reduces a result to a plain map, ready for Phoenix.json/LLM consumption.

to_roll_event(result)

Builds the payload the JavaScript hook expects for a roll animation: %{expression, total, groups: [%{sides, subtotal, rolls: [%{value, kept, exploded}]}]}.