Crate rich_plugin_api 

The plugin contract for the rich Rust port.

A plugin implements Plugin: it describes itself with PluginMetadata and adds capabilities through a PluginRegistrar. A host (rs-rich-ext’s ExtensionRegistry) calls Plugin::register, checks the result, and then makes the capabilities available to consoles and commands.

This crate depends only on core rich, so a plugin never needs rs-rich-ext. Everything first-party plugins do goes through this same contract.

use rich_plugin_api::{Plugin, PluginError, PluginMetadata, PluginRegistrar};
use rich::Theme;

struct Solarized;

impl Plugin for Solarized {
    fn metadata(&self) -> PluginMetadata {
        PluginMetadata::new("solarized", "Solarized themes", "1.0.0")
    }
    fn register(&self, registrar: &mut dyn PluginRegistrar) -> Result<(), PluginError> {
        let theme = Theme::from_styles([("repr.number", "#268bd2")], true)
            .map_err(|e| PluginError::Other(e.to_string()))?;
        registrar.theme("solarized", theme);
        Ok(())
    }
}

Three ways to load a plugin. A host adds a plugin value it was given (add_plugin). A plugin crate can also register itself for link-time collection with export_plugin!, so that depending on it is enough (linked_plugins). And a plugin can be built as a native library or a WASM module and loaded at run time, through the text-only ABI in abi. See docs/design/plugin-loading.md.

Stability: at 0.0.x this contract still changes. Every breaking change bumps PLUGIN_API_VERSION, and hosts refuse a plugin built for another version rather than misbehaving.

Modules

abi

The runtime plugin ABI: what a native (dylib) or WASM plugin exports, and the one description, PluginAbi, both loaders decode it into.

Macros

export_dylib_plugin

Export a native plugin from a cdylib crate.

export_plugin

Register a plugin for link-time collection.

Structs

LinkedPlugin

One plugin submitted with export_plugin!.

PluginMetadata

Who a plugin is. Build it with PluginMetadata::new.

Enums

Capability

One thing a plugin registered, as a host reports it.

PluginError

Why a plugin could not be added, or a renderer failed.

Constants

PLUGIN_API_VERSION

The version of this contract. A host accepts a plugin only if the plugin’s PluginMetadata::api_version equals the host’s.

Traits

CustomAction

A custom action on interactive views (#491): list items, table rows, tree nodes and file entries. A host shows it in a view’s action menu, and on its key if it has one; when the user picks it, the view reports the action’s name and target, and the host may call run.

Plugin

Something that extends rich.

PluginRegistrar

What a plugin can add. Plugin::register receives one of these.

SourceRenderer

Turns source text into a renderable: a diagram, a data format, a report. Registered under a name with PluginRegistrar::renderer.

TextTransform

Rewrites a Text: keeps some lines, styles matches, masks secrets. Registered under a name with PluginRegistrar::transform; a host chains named transforms into a pipeline.

Functions

is_valid_name

Whether name is a valid plugin id or capability name: lowercase letters, digits, -, _ and ., starting with a letter or digit so it is never read as a flag (-x) or a path component (., ..).

linked_plugins

Every plugin exported with export_plugin! in this binary, in no particular order (a host sorts them by id).

Type Aliases

HighlighterFactory

Makes a fresh regex Highlighter each time a host installs it, so one registration can be installed onto many consoles.