Skip to content
Kward Search API index

Class: Kward::PluginRegistry::DSL

Inherits:
Object
  • Object
show all
Defined in:
lib/kward/plugin_registry.rb

Overview

Public DSL object yielded by Kward.plugin blocks.

Plugin files normally interact with this object only through a block:

Examples:

Register a plugin command

Kward.plugin do |plugin|
  plugin.command "hello", description: "Say hello" do |args, ctx|
    name = args.strip.empty? ? "there" : args.strip
    ctx.say "Hello, #{name}."
  end
end

Instance Method Summary collapse

Constructor Details

#initialize(registry, path) ⇒ DSL

Creates an object for trusted plugin loading and dispatch.



122
123
124
125
 
# File 'lib/kward/plugin_registry.rb', line 122

def initialize(registry, path)
  @registry = registry
  @path = path
end

Instance Method Details

#command(name, description: "", argument_hint: "") {|args, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a slash command.

The command is available in the interactive CLI and through the RPC command bridge. Command names do not include the leading /.

Parameters:

  • name (String, #to_s) —

    command name without the leading slash

  • description (String) (defaults to: "") —

    short text shown in command listings

  • argument_hint (String) (defaults to: "") —

    optional usage hint for arguments

Yield Parameters:

  • args (String) —

    text after the command name

  • ctx (Context) —

    plugin execution context



139
140
141
 
# File 'lib/kward/plugin_registry.rb', line 139

def command(name, description: "", argument_hint: "", &block)
  @registry.register_command(name, description: description, argument_hint: argument_hint, path: @path, &block)
end

#footer {|ctx| ... } ⇒ void

This method returns an undefined value.

Registers or replaces the custom footer renderer.

Only one footer renderer is active. If multiple plugins register one, the later renderer replaces the earlier renderer.

Yield Parameters:

  • ctx (Context) —

    plugin execution context



151
152
153
 
# File 'lib/kward/plugin_registry.rb', line 151

def footer(&block)
  @registry.register_footer(path: @path, &block)
end

#interactive_command(name, rows:, fps: 30, description: "", argument_hint: "") {|ui, ctx| ... } ⇒ void

This method returns an undefined value.

Registers an interactive command that takes over the composer region with a Kward-driven render and input loop. The handler receives an interactive controller object with a canvas API for drawing colored cells and reading keys. Useful for games, dashboards, and viewers.

Parameters:

  • name (String, #to_s) —

    command name without the leading slash

  • rows (Integer) —

    fixed canvas height in terminal rows

  • fps (Numeric) (defaults to: 30) —

    frame rate for tick callbacks (1-120, default 30)

  • description (String) (defaults to: "") —

    short text shown in command listings

  • argument_hint (String) (defaults to: "") —

    optional usage hint for arguments

Yield Parameters:

  • ui (Object) —

    interactive controller with canvas and key API

  • ctx (Context) —

    plugin execution context



194
195
196
 
# File 'lib/kward/plugin_registry.rb', line 194

def interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", &block)
  @registry.register_interactive_command(name, rows: rows, fps: fps, description: description, argument_hint: argument_hint, path: @path, &block)
end

#on_transcript_event {|event, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a live transcript event observer.

Observer errors are caught and reported as warnings so a plugin cannot crash the active turn by raising from an event handler.

Yield Parameters:



164
165
166
 
# File 'lib/kward/plugin_registry.rb', line 164

def on_transcript_event(&block)
  @registry.register_transcript_event(path: @path, &block)
end

#prompt_context {|ctx| ... } ⇒ void

This method returns an undefined value.

Registers prompt context text injected into future system prompts.

Keep this text short and never include secrets. The returned string can be sent to the active model as part of Kward's system instructions.

Yield Parameters:

  • ctx (Context) —

    plugin execution context



176
177
178
 
# File 'lib/kward/plugin_registry.rb', line 176

def prompt_context(&block)
  @registry.register_prompt_context(path: @path, &block)
end