class Rooibos::Runtime

Runs the Model-View-Update event loop.

Applications need a render loop. You poll events, update state, redraw. Every frame. The boilerplate is tedious and error-prone.

This class handles the loop. You provide the model, view, and update. It handles the rest.

Use it to build applications with predictable state.

Example

Rooibos.run(
  model: { count: 0 }.freeze,
  view: ->(model, tui) { tui.paragraph(text: model[:count].to_s) },
  update: ->(message, model) { message.q? ? [model, Command.exit] : [model, nil] }
)

Constants

QUIT: Sentinel value avoids accidentally quitting from application exceptions.

Public Class Methods

normalize_init (result)

Source

# File lib/rooibos/runtime.rb, line 167
def self.normalize_init(result)
  Transition.from(result, nil).to_a
end

Normalizes Init callable return value to [model, command] tuple.

Init callables return initial state and optional startup command. They can use DWIM (Do What I Mean) syntax: return just a model, just a command, or a full tuple.

This method handles all formats. Use it when composing child fragment Inits.

result: The Init return value (model, command, or [model, command] tuple).

Examples

# Just model
model, cmd = Rooibos.normalize_init(Model.new(...))
# => [Model.new(...), nil]

# Just command
model, cmd = Rooibos.normalize_init(Command.http(...))
# => [nil, Command.http(...)]

# Tuple (already normalized)
model, cmd = Rooibos.normalize_init([Model.new(...), Command.http(...)])
# => [Model.new(...), Command.http(...)]

run (root_fragment = nil, fps: 60, model: nil, view: nil, update: nil, command: nil)

Source

# File lib/rooibos/runtime.rb, line 127
def self.run(root_fragment = nil, fps: 60, model: nil, view: nil, update: nil, command: nil)
  @fragment = fragment_from_kwargs(root_fragment, model:, view:, update:, command:)
  @view = @fragment::View
  @update = @fragment::Update
  @init_callable = init_callable
  @timeout = 1.0 / fps

  start_runtime
end

Starts the MVU event loop.

Runs until the update function returns a Command.exit command.

Pass a fragment module with Init, Update, and View constants. This allows your application to do work at startup, and your Update will be called with the result. It also allows you to create a more complex model with access to ARGV and ENV.

module MyApp
  # Init is any callable, and returns an immutable Model and/or Command, according to your application's needs.
  # The Model is your application's initial state, and the Command is any command to run at startup.
  Init = -> () {
    # To do work at startup:
    return [Data.define(:count).new(count: 0), Command.http("https://api.example.com/data")]
    # To start idle:
    return Data.define(:count).new(count: 0)
  }

  # Update has access to a single Message, and your fragment's latest immutable Model.
  # It returns a new Model and/or a Command, according to your application's needs.
  Update = ->(message, model) {
    [model, Command.exit]
  }

  # View has access to your fragment's latest immutable Model, and a RatatuiRuby::TUI.
  # It returns a tree of RatatuiRuby::Widget and/or Custom Widgets.
  View = ->(model, tui) {
    tui.paragraph(text: model.count.to_s)
  }
end

Rooibos.run(MyApp)

Root Fragment with auto-Init

Pass a fragment module with a Model class and Update and View constants. Your application will be idle until a RatatuiRuby::Event message is sent to your Update.

module MyApp
  # Model is anything that responds to <tt>new</tt>.
  Model = Data.define(:count).new(count: 0)

  # Update has access to a single Message, and your fragment's latest immutable Model.
  # It returns a new Model and/or a Command, according to your application's needs.
  Update = ->(message, model) {
    [model, Command.exit]
  }

  # View has access to your fragment's latest immutable Model, and a RatatuiRuby::TUI.
  # It returns a tree of RatatuiRuby::Widget and/or Custom Widgets.
  View = ->(model, tui) {
    tui.paragraph(text: model.count.to_s)
  }
end

Rooibos.run(MyApp)

Explicit Parameters API

Tests need deterministic state. Init reads from the filesystem, network, or environment—sources that change between runs. Injecting a known model makes tests reproducible.

Pass model:, view:, and update: directly. The runtime skips Init and uses your model as the starting state.

Rooibos.run(
  model: Ractor.make_shareable(MyApp::Model.new(count: 0)),
  view: MyApp::View,
  update: MyApp::Update
)

Parameters

root_fragment: Module with Model, Init, Update, View constants. *Mutually exclusive with model/view/update.*
fps: Target frames per second for the application. Higher values feel more responsive, but may spike CPU usage.
model: Initial application state (immutable). *Required if fragment not provided.*
view: Callable receiving (model, tui), returns a widget. *Required if fragment not provided.*
update: Callable receiving (message, model), returns [new_model, command] or just new_model. *Required if fragment not provided.*
command: Optional callable to run at startup. Returns a message for update.

Raises

Rooibos::Error::Invariant: If both fragment and any of (model, view, update, command) are provided.