Crate hammer 

Hammer’s plugin kit for Rust. See hammer-editor’s docs/CLIENT-PLUGINS.md for the exports a plugin provides (export, action, command, diagnose) and the JSON each one is given, which always includes locale, the UI’s language tag, for replying in the user’s language. action and diagnose have types for theirs.

An export is a #[unsafe(no_mangle)] pub extern "C" fn returning i32, whose body is run:

#[unsafe(no_mangle)]
pub extern "C" fn action() -> i32 {
    hammer::run(|| {
        let request: Request = hammer::input_json()?;
        Reply::message(format!("Hello, {}", request.project)).to_json()
    })
}

Modules

action

The action export: an item on the menus of the screens in the manifest entry’s places. Hammer asks for any [[actions.field]]s first, then calls it, and every call returns a Reply as JSON. A reply with a Page shows it in the action’s dialog; pressing one of the page’s buttons calls the action again with the button’s id, the page’s values as Request::input, and the page’s state. A reply with errors keeps the user on the page they were on, one with open ends the action and goes to an item, and one with none of these ends the action. A message is shown briefly either way.

base64

Binary content, such as an exported file or an entry’s image, which operations carry as base64 text.

diagnose

The diagnose export: Hammer sends paragraphs of a scene, and the plugin replies with the issues in them, which the editor underlines. A check’s manifest scope says which paragraphs: paragraph, the default, sends only those whose text the check has not seen; scene sends every paragraph of the scene each time, blank ones included, for issues that depend on other paragraphs.

http

HTTP requests, through Extism’s http_request. Hammer allows only the hosts the manifest names under permissions.http, which the user approves at install; a request to any other fails.

log

ops

Hammer’s operations, typed. Each function runs one operation, as crate::call would. A plugin may call only those its manifest’s [permissions] ask for: each function’s documentation names what it needs.

Structs

ZeroingAllocator

An allocator that zeroes memory as it is freed. A module pre-initialized with Wizer keeps only its memory’s non-zero bytes, so with this it carries what start-up kept, not what it threw away.

Constants

API_VERSION

The host API version this kit targets; the manifest’s api must match.

CACHE_MAX_KEY

CACHE_MAX_VALUE

Functions

cache_get

The value cached under key, or None when there is none.

cache_set

Caches value under key; an empty value removes it. False, storing nothing, when either is over its limit.

call

Runs a Hammer operation the manifest has permission for, such as call::<Tree>("scene.tree", &json!({"project": name})). A failure’s message starts with its kind: NotFound, InvalidInput, PermissionDenied, or Failed.

char_byte_offsets

The UTF-8 byte offset of each character of text, plus one for its end, so a range counted in characters becomes the byte range Hammer expects.

input

input_json

progress

Reports how far an action has got: fraction from 0 to 1 when known, and a line saying what it is doing. Hammer shows it while the action runs. When the user has stopped the run, the call does not return: the action ends there.

resource

Reads a file from the package’s resources/ by its path there, such as words/en.txt: None when the package has none by that name, or it is empty. Hammer reads it from the package on every call, so keep one you use often.

run

Runs an export’s body: its output on success, its message on failure, and a panic’s message too.

Type Aliases

Error

A failure to report to the user. ? converts any error into one, and .into() a message.

Result