Bubble Tea Ruby

In the Bubble Tea architecture, Command objects are used to trigger side effects (like I/O, timers, or quitting) from within your update function. Instead of performing the action directly, you return a Command object, which the runtime then executes.

You should use the convenience methods provided on the Bubbletea::Command class to instantiate these objects.

# Example of returning a command in an update loop
# (Conceptual usage)
def update(msg)
  case msg
  when KeyDown
    Bubbletea::Command.quit
  end
end

The bubbletea gem provides a Ruby implementation of the Bubble Tea framework (based on The Elm Architecture) for building interactive terminal applications. It automatically selects the appropriate backend based on your Ruby version for optimized performance.

To use it in your project, require the main module:

require 'bubbletea'

To start a TUI application, use Bubbletea.run(model, **options). This method initializes a Runner instance with your model and starts the event loop, managing terminal setup, rendering, and message processing.

Your model must implement the standard Elm Architecture interface: init, update(message), and view.

# Assuming your model implements init, update, and view
Bubbletea.run(MyModel.new)

The KeyMessage class is used to represent keyboard events in the update loop. You can inspect the message to determine which key was pressed using predicate methods like .enter?, .esc?, .up?, etc., or by checking the .runes for character input.

Common key constants include:

• KeyMessage::KEY_ENTER
• KeyMessage::KEY_ESC
• KeyMessage::KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT
• KeyMessage::KEY_BACKSPACE
• KeyMessage::KEY_SPACE
• KeyMessage::KEY_RUNES (for character input)

For character input, use the .char method to retrieve the string representation of the pressed runes.

# Example of handling a KeyMessage in an update loop
case msg
when KeyMessage
  if msg.enter?
    # Handle Enter key
  elsif msg.up?
    # Handle Up arrow
  elsif msg.runes?
    puts "Typed: #{msg.char}"
  end
end

The Bubbletea::Model module provides the following method signatures for implementation:

• init: Returns [self, nil] by default.
• update(message): Returns [self, nil] by default. Accepts a message object.
• view: Returns "" (an empty string) by default.

While the Runner manages the loop, you can manually inject messages into the processing queue using the send(message) method on a Runner instance. This is useful if you have external asynchronous processes that need to trigger an update in your TUI model.

runner = Bubbletea::Runner.new(MyModel.new)
# ... in some other context ...
runner.send(MyCustomMessage.new)
runner.run

Use Bubbletea.parse_event(hash) to convert a raw event hash (typically from a Go-to-Ruby bridge) into a concrete Message object. The hash must contain a "type" key.

Supported types:

• "key": Returns a KeyMessage.
• "mouse": Returns a MouseMessage.
• "focus": Returns a FocusMessage.
• "blur": Returns a BlurMessage.

# Example parsing a key event hash
event_hash = {
  "type" => "key",
  "key_type" => 13,
  "alt" => false
}

msg = Bubbletea.parse_event(event_hash)
puts msg.class # => KeyMessage
puts msg.enter? # => true

Use Bubbletea::Command.exec(callable, message: nil) to run a Ruby callable (such as a Proc or a lambda) as a side effect. This is useful for long-running tasks or I/O operations that shouldn't block the main update loop. If a message is provided, it will be sent back to the update function once the callable finishes execution.

# Running a proc that returns a message
Bubbletea::Command.exec(-> { 
  # Perform heavy work here
  "Result of work"
}, message: :work_completed)

The MouseMessage class represents mouse interactions. It provides coordinates, button information, and action types.

Actions:

• MouseMessage::ACTION_PRESS
• MouseMessage::ACTION_RELEASE
• MouseMessage::ACTION_MOTION

Buttons:

• MouseMessage::BUTTON_LEFT
• MouseMessage::BUTTON_MIDDLE
• MouseMessage::BUTTON_RIGHT
• MouseMessage::BUTTON_WHEEL_UP
• MouseMessage::BUTTON_WHEEL_DOWN

Predicate Methods:

• .press?, .release?, .motion?
• .left?, .right?, .middle?
• .wheel? (returns true if the button is a scroll wheel action)

Attributes available via attr_reader: x, y, button, action, shift, alt, ctrl.

case msg
when MouseMessage
  if msg.press? && msg.left?
    puts "Clicked at #{msg.x}, #{msg.y}"
  elsif msg.wheel?
    puts "Scrolled!"
  end
end