Raxol.Core.Runtime.Command (Raxol v0.3.0)

View Source

Provides a way to handle side effects in a pure functional way.

Commands are used to describe side effects that should be performed by the runtime system. This keeps the application's update function pure while still allowing necessary side effects to occur.

Types of Commands

  • :none - No side effect
  • :task - Asynchronous task that will send a message when complete
  • :batch - Multiple commands to be executed in sequence
  • :delay - Delayed message delivery
  • :broadcast - Send a message to all components
  • :system - System-level operations (file, network, etc.)
  • :quit - Signals the runtime to quit
  • :clipboard_write - Write text to the system clipboard
  • :clipboard_read - Request text from the system clipboard (will result in a message)
  • :notify - Send a system notification

Examples

# No side effect
Command.none()

# Run an async task
Command.task(fn ->
  # Do something expensive
  result = expensive_operation()
  {:operation_complete, result}
end)

# Multiple commands
Command.batch([
  Command.task(fn -> {:fetch_data, api_call()} end),
  Command.delay(:refresh, 1000)
])

# Delayed message
Command.delay(:timeout, 5000)

# Broadcast to all components
Command.broadcast(:data_updated)

# System operation
Command.system(:file_write, path: "data.txt", content: "Hello")

# Signal the runtime to quit
Command.quit()

# Write to clipboard
Command.clipboard_write("Copied text")

# Read from clipboard (expects a {:clipboard_content, text} message later)
Command.clipboard_read()

# Send notification
Command.notify("Task Complete", "Your background job finished.")

Summary

Functions

Creates a command that will execute multiple commands in sequence.

Creates a command that will broadcast a message to all components.

Creates a command to read text from the system clipboard. This will eventually result in a {:command_result, {:clipboard_content, content}} message being sent back to the application's update function.

Creates a command to write text to the system clipboard.

Creates a command that will send a message after the specified delay in milliseconds.

Executes a command within the given context. This is used by the runtime system and should not be called directly by applications.

Maps a function over a command's result message. This is useful for namespacing messages or transforming them before they reach the update function.

Creates a new command. This is the low-level constructor, prefer using the specific command constructors unless you need custom behavior.

Returns a command that does nothing.

Creates a command to send a system notification.

Returns a command that signals the runtime to quit.

Creates a command for system-level operations like file I/O or network requests. The operation type and options specify what should be done.

Creates a command that will execute the given function asynchronously. The function should return a message that will be sent back to the update function when the task completes.

Types

t()

@type t() :: %Raxol.Core.Runtime.Command{
  data: term(),
  type:
    :none
    | :task
    | :batch
    | :delay
    | :broadcast
    | :system
    | :quit
    | :clipboard_write
    | :clipboard_read
    | :notify
}

Functions

batch(commands)

Creates a command that will execute multiple commands in sequence.

broadcast(msg)

Creates a command that will broadcast a message to all components.

clipboard_read()

Creates a command to read text from the system clipboard. This will eventually result in a {:command_result, {:clipboard_content, content}} message being sent back to the application's update function.

clipboard_write(text)

Creates a command to write text to the system clipboard.

delay(msg, delay_ms)

Creates a command that will send a message after the specified delay in milliseconds.

execute(command, context)

Executes a command within the given context. This is used by the runtime system and should not be called directly by applications.

map(cmd, mapper)

Maps a function over a command's result message. This is useful for namespacing messages or transforming them before they reach the update function.

Example

# Transform the task's result message
Command.task(fn -> {:data, fetch_data()} end)
|> Command.map(fn {:data, result} -> {:processed_data, process(result)} end)

new(type, data \\ nil)

Creates a new command. This is the low-level constructor, prefer using the specific command constructors unless you need custom behavior.

none()

Returns a command that does nothing.

notify(title, body)

Creates a command to send a system notification.

quit()

Returns a command that signals the runtime to quit.

system(operation, opts \\ [])

Creates a command for system-level operations like file I/O or network requests. The operation type and options specify what should be done.

task(fun)

Creates a command that will execute the given function asynchronously. The function should return a message that will be sent back to the update function when the task completes.