Raxol.Core.Runtime.Plugins.API (Raxol v0.2.0)

View Source

Public API for Raxol plugins to interact with the core system.

This module provides standardized interfaces for plugins to:

  • Register event handlers
  • Access runtime services
  • Register commands
  • Access rendering capabilities
  • Modify application state in approved ways

Plugin developers should only use these API functions for interacting with the Raxol system to ensure forward compatibility when the internal system changes.

Summary

Functions

Broadcast an event to all subscribers.

Get the current application configuration.

Log a message from a plugin.

Get the path to the plugin data directory.

Register a command that can be executed from the terminal.

Unregister a previously registered command.

Unsubscribe from runtime events.

Functions

broadcast(event_type, payload)

@spec broadcast(atom(), map()) :: :ok

Broadcast an event to all subscribers.

Parameters

  • event_type - The type of event to broadcast
  • payload - Data to include with the event

Returns

  • :ok if broadcast was successful

get_config(key, default \\ nil)

@spec get_config(atom() | String.t(), term()) :: term()

Get the current application configuration.

Parameters

  • key - The configuration key to retrieve
  • default - Default value if the key is not found

Returns

The configuration value or default

log(plugin_id, level, message)

@spec log(String.t(), atom(), String.t()) :: :ok

Log a message from a plugin.

Parameters

  • plugin_id - The ID of the plugin
  • level - Log level (:debug, :info, :warn, :error)
  • message - The message to log

Returns

:ok

plugin_data_dir(plugin_id)

@spec plugin_data_dir(String.t()) :: String.t()

Get the path to the plugin data directory.

Parameters

  • plugin_id - The ID of the plugin

Returns

String path to the plugin's data directory

register_command(command_name, handler, help_text, options \\ [])

@spec register_command(String.t(), module(), String.t(), keyword()) ::
  :ok | {:error, term()}

Register a command that can be executed from the terminal.

Parameters

  • command_name - String name of the command
  • handler - Module that will handle the command
  • help_text - Description of the command for help documentation
  • options - Additional options for the command

Returns

  • :ok if command was registered
  • {:error, reason} if registration failed

Example

API.register_command("myplugin:hello", MyPlugin.Commands,
  "Displays a hello message from myplugin")

subscribe(event_type, handler, function \\ :handle_event)

@spec subscribe(atom(), module(), atom()) :: :ok | {:error, term()}

Subscribe to runtime events.

Parameters

  • event_type - The type of event to subscribe to
  • handler - Module that will handle the event
  • function - Function in the handler module that will be called (default: :handle_event)

Returns

  • :ok if successful
  • {:error, reason} if subscription failed

Example

API.subscribe(:key_press, MyPluginHandlers)

unregister_command(command_name)

@spec unregister_command(String.t()) :: :ok | {:error, term()}

Unregister a previously registered command.

Parameters

  • command_name - String name of the command to unregister

Returns

  • :ok if command was unregistered
  • {:error, reason} if unregistration failed

unsubscribe(event_type, handler)

@spec unsubscribe(atom(), module()) :: :ok | {:error, term()}

Unsubscribe from runtime events.

Parameters

  • event_type - The type of event to unsubscribe from
  • handler - Module to unsubscribe

Returns

  • :ok if successful
  • {:error, reason} if unsubscription failed