PIPELINE. Descriptor lookup, build, encode, send, decode, interpret.
Six steps, five of them pure. The single impure one is a call through
IGimpTransport, which is why the whole pipeline is testable end to end
against a scripted double and why no test in this repo redefines a var.
Every exit is an Outcome. A caller cannot receive a naked exception from
here, and cannot receive nil: a transport that threw, a parameter that would
not coerce and an error raised inside GIMP all arrive in the same shape,
distinguished by :reason.
PIPELINE. Descriptor lookup, build, encode, send, decode, interpret. Six steps, five of them pure. The single impure one is a call through `IGimpTransport`, which is why the whole pipeline is testable end to end against a scripted double and why no test in this repo redefines a var. Every exit is an `Outcome`. A caller cannot receive a naked exception from here, and cannot receive nil: a transport that threw, a parameter that would not coerce and an error raised inside GIMP all arrive in the same shape, distinguished by `:reason`.
(invoke transport command-or-tool)(invoke transport command-or-tool args)Run command-or-tool with kebab-case args. Returns an Outcome.
Accepts either vocabulary for the command name, for the reason given on
catalog/descriptor.
Two boundary compensations sit between the built command and the wire, and
both are here rather than in the pipeline because both need a round trip of
their own: a font the caller named is checked against the fonts GIMP has
before anything is drawn, and new_canvas recovers the image the reference
plug-in builds and then disowns. hive-gimp.guard explains what each one is
compensating for.
Run `command-or-tool` with kebab-case `args`. Returns an `Outcome`. Accepts either vocabulary for the command name, for the reason given on `catalog/descriptor`. Two boundary compensations sit between the built command and the wire, and both are here rather than in the pipeline because both need a round trip of their own: a font the caller named is checked against the fonts GIMP has before anything is drawn, and `new_canvas` recovers the image the reference plug-in builds and then disowns. `hive-gimp.guard` explains what each one is compensating for.
(invoke! transport command-or-tool)(invoke! transport command-or-tool args)Like invoke, but throws on failure and returns the value on success.
For REPL and script use, where a Result-shaped answer is friction and a stack trace is what you wanted anyway. Never call this from a tool handler: an MCP client needs the error as data.
Like `invoke`, but throws on failure and returns the value on success. For REPL and script use, where a Result-shaped answer is friction and a stack trace is what you wanted anyway. Never call this from a tool handler: an MCP client needs the error as data.
(send-command transport gimp-command)Send an already-built GimpCommand through transport. Returns an Outcome.
Separate from invoke because the exec escape hatch and the doctor both
need to send a command that no descriptor describes.
Send an already-built `GimpCommand` through `transport`. Returns an `Outcome`. Separate from `invoke` because the exec escape hatch and the doctor both need to send a command that no descriptor describes.
Send a built GimpCommand, compensating for a known defect of the plug-in
that answers it. Returns an Outcome.
Keyed by command name and open by construction: a defect found in a command
we do not own is a new defmethod, never an edit to invoke. The default
is a plain send, so a command with nothing to compensate pays nothing.
Send a built `GimpCommand`, compensating for a known defect of the plug-in that answers it. Returns an `Outcome`. Keyed by command name and open by construction: a defect found in a command we do not own is a new `defmethod`, never an edit to `invoke`. The default is a plain send, so a command with nothing to compensate pays nothing.
(unknown-command-outcome command-or-tool)The Outcome for a name no descriptor describes.
The contract ships ~80 commands in two vocabularies (place_text and
gimp_place_text), which is exactly the size where a typo is likely and a
bare refusal is useless. hive-help supplies the fleet's shared shape for
this, including edit-distance suggestions, so the reader is told what they
probably meant instead of being sent to go and read a catalog.
Lives here, at the boundary: hive-gimp.command answers the error VALUE
and is .cljc, so it cannot require hive-help.
The `Outcome` for a name no descriptor describes. The contract ships ~80 commands in two vocabularies (`place_text` and `gimp_place_text`), which is exactly the size where a typo is likely and a bare refusal is useless. hive-help supplies the fleet's shared shape for this, including edit-distance suggestions, so the reader is told what they probably meant instead of being sent to go and read a catalog. Lives here, at the boundary: `hive-gimp.command` answers the error VALUE and is .cljc, so it cannot require hive-help.
(unknown-font-outcome command wanted installed)The Outcome refusing a font GIMP does not have.
A refusal rather than a reported substitution, for two reasons. The native
plug-in's place_text already refuses, so both paths now answer the same
way; and the artefact is the layer, which a caller reads long after the
response that would have carried the notice. A caller who wants any face at
all leaves font out and takes the plug-in's default.
Lives at the boundary with unknown-command-outcome, for the same reason:
hive-gimp.guard answers the VERDICT and is .cljc, so it cannot require
hive-help.
The `Outcome` refusing a font GIMP does not have. A refusal rather than a reported substitution, for two reasons. The native plug-in's `place_text` already refuses, so both paths now answer the same way; and the artefact is the layer, which a caller reads long after the response that would have carried the notice. A caller who wants any face at all leaves `font` out and takes the plug-in's default. Lives at the boundary with `unknown-command-outcome`, for the same reason: `hive-gimp.guard` answers the VERDICT and is .cljc, so it cannot require hive-help.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |