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. export, 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 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.

export

The export export: renders one of the manifest’s [[exporters]] formats from the story, and returns the file’s bytes.

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.

images

Image references in Markdown. Hammer shows a project image as ![image](hammer://image/<id>), or with the destination in angle brackets, <hammer://image/<id>>. The alt text means nothing: Hammer shows the image’s own name.

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.

server

Requests to a service on the user’s own Hammer sync server, such as languagetool, through hammer_server_request. Hammer sends them as the signed-in user, so the plugin never holds their credentials, and only to the services the manifest names under permissions.hammerServer. languagetool has typed functions for the languagetool service.

Structs

Word

A word in a text: text, from byte start up to end, the offsets a diagnose::Diagnostic takes.

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.

words

The words in text, in order. A word is a run of letters, with any combining marks on them, so accents, Indic vowel signs, and Arabic vowel marks stay in their word. An apostrophe (' or ’), the Catalan middle dot, Hebrew’s geresh and gershayim, ZWNJ, ZWJ, or a soft hyphen between two letters stays inside too, so “don’t”, “l’arbre”, and “col·lecció” are one word each. Digits, hyphens, and everything else end a word.

Type Aliases

Error

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

Result