module RatatuiRuby::Tea::Cmd

Commands represent side effects.

The MVU pattern separates logic from effects. Your update function returns a pure model transformation. Side effects go in commands. The runtime executes them.

Commands produce messages, not callbacks. The tag argument names the message so your update function can pattern-match on it. This keeps all logic in update and ensures messages are Ractor-shareable.

Examples

# Terminate the application
[model, Cmd.quit]

# Run a shell command; produces [:got_files, {stdout:, stderr:, status:}]
[model, Cmd.exec("ls -la", :got_files)]

# No side effect
[model, nil]

Constants

Exec

Command to run a shell command via Open3.

The runtime executes the command and produces a message: [tag, {stdout:, stderr:, status:}]

The status is the integer exit code (0 = success).

Quit

Sentinel value for application termination.

The runtime detects this before dispatching. It breaks the loop immediately.

Public Class Methods

exec (command, tag)

Source

# File lib/ratatui_ruby/tea/cmd.rb, line 83
def self.exec(command, tag)
  Exec.new(command:, tag:)
end

Creates a shell execution command.

command: Shell command string to execute.
tag: Symbol or class to tag the result message.

When the command completes, the runtime sends [tag, {stdout:, stderr:, status:}] to update.

Example

# Return this from update:
[model.with(loading: true), Cmd.exec("ls -la", :got_files)]

# Then handle it later:
def update(msg, model)
  case msg
  in [:got_files, {stdout:, status: 0}]
    [model.with(files: stdout.lines), nil]
  in [:got_files, {stderr:, status:}]
    [model.with(error: stderr), nil]
  end
end

quit ()

Source

# File lib/ratatui_ruby/tea/cmd.rb, line 49
def self.quit
  Quit.new
end

Creates a quit command.

Returns a sentinel the runtime detects to terminate the application.

Example

def update(msg, model)
  case msg
  in { type: :key, code: "q" }
    [model, Cmd.quit]
  else
    [model, nil]
  end
end