Writing interpreters
Structile understands JSON, Python-repr and CSV (including tab-separated text) natively — see CSV and tab-separated text for that one, which needs nothing from this page. Everything else — XML, HTML, INI, TOML, YAML, or any in-house format — goes through a small interpreter: a JavaScript file that says how to turn that format's text into a plain value, and (optionally) back again. This page covers writing one, trying it out, and then the four ways to get it to whoever else needs it — from "just send the file" up to "install a package and it's automatic."
This one page applies to all three ways of running Structile — the standalone viewer, the Python library, and the VS Code extension — since all three run the exact same interpreter script the exact same way.
Already have a script and just need to know which obj/format=/interpreter= combination to pass it with? See Choosing obj, format, interpreter instead — this page is about writing the script itself.
The contract
An interpreter defines one or two functions, depending on the kind of data:
- Any text format that isn't markup (INI, TOML, YAML, a custom DSL,
…):
interpretText(text), given the raw file text, returning a plain JS value. Optionally alsoserializeText(value), the inverse — when present, Save writes edits back to this exact text shape instead of falling back to a different format.serializeTextmay take a second argument,hints—{literals: [{path, text}]}, the text a user typed for the number at each path (2.0rather than the JS number2). The viewer keeps one copy of an interpreter per document and re-reads every text it saves, so aserializeTextcan patch the text its copy last read instead of rewriting the file: the bundled TOML, YAML and INI interpreters do, which is why a save through them changes only the edited lines and keeps comments, quoting and number spellings. - Markup (XML, or HTML — HTML is just XML-like markup with a looser
parsing mode):
interpretXML(xmlDocument), given a browser-parsed DOMDocument, returning a plain JS value. Optionally alsoserializeXML(value).
Only interpretText/interpretXML is required — read-only support (view
but not edit-and-save) is a perfectly reasonable place to stop.
One rule matters more than the shape of the code: fail loudly. If the
text doesn't actually look like your format, throw — don't guess and
return something meaningless. This is what makes it safe to hand
Structile a list of candidate interpreters for the same file: it tries
each in order and uses the first one that doesn't throw, so two
mutually-incompatible schemas can coexist without anyone having to say up
front which file is which.
An interpreter can also declare two optional constants, to self-identify:
Neither is required. When present, the standalone viewer's [?] About
popover shows them for whichever interpreter actually resolved the
currently loaded file — and, for a
custom/branded distribution,
lists every bundled interpreter's own name/version too, so a colleague
can tell what a given build actually contains without opening a file
first.
A script can also link to its own documentation — an internal wiki page,
the public spec it follows — with INTERPRETER_DOCS, an array of
{label, url, text?} entries:
const INTERPRETER_DOCS = [
{ label: "ACME Docs", text: "ACME-Confluence", url: "https://acme.example/wiki/ACME" },
];
Each entry becomes one extra row (ACME Docs: ACME-Confluence, linked)
right below the interpreter's name/version row — in the [?] popover, in
the puzzle-piece interpreter panel and in
structile.about.
text defaults to link; only http:, https: and mailto: URLs
become links, any other URL is shown as plain text; a malformed entry (no
label or url) is skipped rather than breaking anything. The bundled
generic_toml.js links the TOML spec version it targets, if you want a
real example.
Soft diagnostics. A throw means "this isn't my format" and sends the
viewer on to the next candidate. For a document that is your format
but breaks one of its own rules — a recommended element missing, a value
out of range — call __structileDiagnostic(severity, message, opts?)
from inside interpretXML/interpretText and still return a
best-effort value. severity is "info", "warning" or "error";
opts may carry {ruleId, path, line, offset}, all optional. Each call
lands in the viewer's message log (the ☰ button, with the rule id and
the location in the text), one short summary pops up after the load, and
the interpreter panel counts them in its Diagnostics row. Only the
interpreter that actually read the document gets its diagnostics shown;
a losing candidate's are discarded with it. generic_xml.js is the
bundled example.
Binary formats. An interpreter can read bytes rather than text. A
custom build marks its entry
"binary": true (or "format": "bin"), and the VS Code extension takes
"format": "bin" in the same places (see
the VS Code extension guide). Its
interpretText(text) then receives the file one character per byte —
text.charCodeAt(i) & 0xff is byte i — never decoded as text and never
line-ending-normalized, and the document opens read-only, since there's
no way back from the interpreted value to the bytes. The flag decides,
not what the bytes look like: a bespoke format whose bytes happen to
contain no NUL still takes the byte path. In the standalone viewer, an
interpreter you drop next to a binary file gets the bytes as a second
try when it rejects the file read as text, and a bundled binary
interpreter is tried on every binary file's bytes before the viewer asks
for one, whatever the file is called. LINK_OPEN/LINK_CLOSE/
LINK_ID_FIELD work for a binary interpreter too, so a reference such
as {{A}} can be a clickable link.
Selection sync
JSON and Python-repr always sync: clicking a value in the graph highlights the matching text in the source pane, and vice versa (the VS Code extension also folds/unfolds and edits in sync, live). Any interpreter can opt in to the same position map, but it must identify where its output values came from — there is no fixed grammar for the viewer to re-derive positions from on its own.
For markup (interpretXML), call the global
__structileTagSource(container, key, role, node, mode) right where you
already assign a value into its container:
out[key] = interpretNode(kid);
__structileTagSource(out, key, "value", kid); // whole element
__structileTagSource(out, key, "key", kid, "id"); // one attribute
__structileTagSource(out, key, "value", kid, "$text"); // trimmed text content
container/key— the object/array/Set and the key/index the value was just assigned under.role—"key"or"value", matching what's being tagged.node— the DOM element the value came from.mode— omit for the whole element's span, pass an attribute name for just that attribute's value, or"$text"for the element's trimmed text content.
For a raw-text (interpretText) format, your parser already knows the
character offsets it consumed. Record those directly with
__structileTagSourceRange(container, key, role, from, to):
out[key] = parsedValue;
__structileTagSourceRange(out, key, "key", keyFrom, keyTo);
__structileTagSourceRange(out, key, "value", valueFrom, valueTo);
from is inclusive and to is exclusive, in the LF-normalized text
passed to interpretText. The container, key, and role meanings are
the same as for markup. Tag both roles when your format has distinct key
and value spans; an array item commonly needs only a value span.
This is entirely optional — an interpreter that skips it still works
exactly as before, just graph-only, no error, no configuration needed
elsewhere. Every bundled XML/HTML interpreter under
interpreters/ opts in — generic_xml.js's own header comment walks
through a complete worked example — except for the *_no_sync.js
variants alongside them, kept specifically as a deliberately non-syncing
comparison point, not meant to be copied from. generic_toml.js and
generic_yaml.js are the complete raw-text examples.
Hover hints and interpreter options
An interpreter can add hover hints: extra lines in the tooltip of a
dict value or table cell, worked out from the value and where it sits in
the document. Hover 100 in {"Amount": 100} with the bundled
generic_xml.js and its scaled-amount option switched on (factor 158,
symbol ¥), and the tooltip reads Amount: 100 with hint: ¥15800 on
the next line. The interpreter decides what a hint says; the viewer
decides where it shows. This works the same in the standalone viewer, the
Jupyter widget and the VS Code extension, and in a diff.
Two optional declarations make it happen: a hoverHint function, and an
INTERPRETER_OPTIONS list describing the controls the viewer should draw
for it. Both are independent of interpretText/interpretXML — an
interpreter without them works exactly as before.
The hoverHint(value, ctx, options) function
const INTERPRETER_OPTIONS = [
{ section: "Scaled amounts" },
{ id: "on", label: "Show scaled amounts", type: "checkbox", default: false },
{ id: "match", label: "Key matches", type: "text", format: "regex", default: "amount|notional" },
{ id: "factor", label: "Factor", type: "number", default: 1, step: "any" },
];
function hoverHint(value, ctx, options){
if (!options.on || typeof value !== "number") return null;
if (!new RegExp(options.match, "i").test(ctx.key || "")) return null;
const scaled = String(value * options.factor);
return ctx.surface === "tooltip" ? "hint: " + scaled : scaled;
}
valueis the raw value your interpreter produced — a number,bigint, string, boolean ornull— so100and"100"can be told apart.ctxsays where the value sits, always from its real place in the document, never from what happens to be drawn (a foldeda/bbox title, a link window, a diff'sold → newkey):
| Field | Meaning |
|---|---|
where |
"dict", "table", "set" or "root" |
key |
the value's own key (for a table of records, its column key), else null |
column |
a table cell's column header, else null |
parentKey |
the nearest dict key above key, skipping list indices |
path |
the full path: string keys and number indices |
container |
the dict, row, array or Set holding the value — read it, don't change it |
side |
"left" or "right" in a two-document diff, else null |
surface |
"tooltip", or "inline" when the hint is being written into the cell (see Hints in cells) |
optionsis a plain object of the current option values, keyed by theids yourINTERPRETER_OPTIONSdeclares —{on: false, match: "amount|notional", factor: 1}above — whatever the user set in the panel, or the defaults.- Return a string (one line), an array of strings (one line each, at
most five are shown), or
nullfor no hint. Each line shows exactly as returned — a label such ashint:is yours to add or leave out.
What to expect from the viewer:
- Display only. A hint never reaches the data, the source pane,
search, copy or a save.
hoverHintand the options are never passed tointerpretXML/interpretText/serialize*, soconvert()and the viewer read a file identically whatever the options say. - Computed on hover, not while drawing. A hint is worked out the first time the pointer rests on a value, so a document with thousands of cells pays nothing until you hover.
- Errors are reported once. A
hoverHintthat throws is noted once in the message log (the ☰ button); the value simply shows no hint. - Keep it stateless. Don't rely on variables
interpretXML/interpretTextleft behind: in a diff,hoverHintmay run on a separately built copy of your script.
Declaring options: INTERPRETER_OPTIONS
INTERPRETER_OPTIONS is an array. Each entry is either a section header,
{ section: "Scaled amounts" }, or a control with an id (the key your
hoverHint reads it under), a label, a default, and optionally a
help text shown under it:
type |
Extra fields | What the user gets |
|---|---|---|
checkbox |
— | an on/off switch (default: true or false) |
number |
min, max, step ("any" allows decimals) |
a number field; a value outside min/max is clamped |
range |
min and max (both required), step |
a slider, with its current value shown beside it |
text |
maxLength, placeholder, format: "regex" |
a text field; with format: "regex", only a valid regular expression is accepted |
select |
options: strings, or {value, label} objects |
a dropdown |
A malformed entry — no id, an unknown type, a range without
min/max, a select without options — is skipped and reported once
in the message log; the rest of the controls still work. A typed value
that doesn't fit (not a number, too long, not a valid regular
expression) shows why under the field, and the last valid value stays in
effect.
The interpreter panel
Whenever the document on screen was read by an interpreter, a
puzzle-piece button appears in the viewer's header next to
{ } Source (tooltip: "Interpreter: details and options") — in the
standalone viewer, the Jupyter widget and the VS Code editor alike. It
opens the interpreter panel:
- its name and version (
INTERPRETER_NAME·INTERPRETER_VERSION) and anyINTERPRETER_DOCSlinks; - Reads (
text · toml,XML/HTML (as a DOM) · xml, orbinary data), Saves (yes, orno (read-only)when there's noserialize*function), Links (the reference delimiters and id field it declares, orno), Hover hints (yes/no) and Options (how many controls); - Source — where the script came from:
bundled with this viewer,added this session,reused from earlier this session,supplied by the host(Python or VS Code),saved with this pageorcarried over from the tab that saved this copy; Chosen —candidate 2 of 3when it was picked from a list; and a Diagnostics count when the interpreter reported any (see The contract); - the Options section: a Show hints in cells checkbox for every
interpreter with a
hoverHint, then your controls under their section headings, and Reset to defaults.
Changing an option takes effect on the next hover, with nothing redrawn
(or, with hints shown in cells, the cells are redrawn once). Values are
remembered in the browser per INTERPRETER_NAME, so every document that
interpreter reads gets the same settings; they also travel in an exported
settings file (Export settings / Load settings in the Settings
panel) and inside a Save as HTML… copy. An interpreter with no
INTERPRETER_NAME keeps its values for the current page only — the
panel's last line says which applies.
Hints in cells
Tick Show hints in cells in the panel and the viewer also calls
hoverHint with ctx.surface === "inline" while drawing, once per cell,
and writes the result after the value in one fixed color. The cell
widens to fit; in a compact box the hint is cut to valMax characters,
expanded views show all of it. It stays display only: a double-click on
it edits nothing, and it isn't selected, searched, copied or saved. The
switch is remembered together with the interpreter's options.
Hints in a diff
When comparing two files, each side's hint comes from that side's own
interpreter and value — the panel then shows one block per side (Left
side / Right side, or Both sides when one interpreter read
both). The unified view shows one hint when both sides agree and pairs
them when they don't: hint: 15800 → hint: 31600.
Worked example: amounts in millions or in another currency (generic_xml.js)
The bundled generic_xml.js
(INTERPRETER_NAME generic_xml) declares all of the above for one
feature: a number whose own key, parent key or table column matches a
pattern is shown multiplied by a factor, with an optional currency
symbol. It's off until you switch it on in the panel. Its controls, with
the option ids an exported settings file and interpreterOptions= (below)
refer to them by:
| Option id | Control | Default | Meaning |
|---|---|---|---|
scaleEnabled |
checkbox "Show scaled amounts" | off | the whole feature |
scaleMatch |
text (regular expression) "Key, parent key or column matches" | amount|notional |
which numbers get a hint |
scaleIgnoreCase |
checkbox "Ignore case" | on | how the pattern matches |
scaleFactor |
number "Factor" | 1 |
what the value is multiplied by |
scaleSymbol |
text "Symbol" (up to 8 characters) | empty | ¥, $, … |
scaleDecimals |
slider "Decimals", 0–8 | 2 |
decimals shown at most (trailing zeros dropped) |
scaleFormatTooltip |
text "Tooltip format" | hint: \1\2 |
the hint in the tooltip |
scaleFormatValue |
text "Format after a dict value" | \1\2 |
the hint in a key: value box, with "Show hints in cells" on |
scaleFormatCell |
text "Format after a table cell" | \1\2 |
the hint in a table cell, with "Show hints in cells" on |
In the three formats \1 stands for the symbol and \2 for the scaled
amount (\\ is a backslash; anything else is written as is, so \2 \1
puts the symbol after the amount), and a blank format means no hint in
that place. With a factor of 158 and the symbol ¥, the value 100
under an amount key shows hint: ¥15800 in its tooltip and ¥15800
in its cell. A whole-number factor keeps a big integer exact.
Two presets cover most uses:
- Amounts in millions. Factor
1e-6, symbol$, one decimal, formatsin millions: \1\2m(tooltip) and≈ \1\2m(cells): abalanceof498250000reads498250000 ≈ $498.3m. - Another currency. The FX rate as the factor and the target
currency's symbol: factor
0.92, symbol€shows a USDnotionalof1000000as€920000.
The live demo opens a portfolio
with the millions preset and the hints written in the cells; its
puzzle-piece panel changes the factor and the symbol on the spot. The
data file is sample_generic_xml__tables.xml,
and the study material's 11_interpreter_hints.ipynb builds the same
preset from Python.
Pre-setting options from Python: interpreterOptions=
The panel is for the person at the screen. From Python, the
interpreterOptions viewer option hands open() the values for one
document — a dict keyed by the interpreter's INTERPRETER_NAME, then by
option id; the special key "@inline": True switches Show hints in
cells on:
import structile as st
st.open(
"portfolio.xml", interpreter="generic_xml.js",
interpreterOptions={"generic_xml": { # amounts in millions
"scaleEnabled": True, "scaleMatch": "notional|balance|nav",
"scaleFactor": 1e-6, "scaleSymbol": "$", "scaleDecimals": 1,
"scaleFormatTooltip": r"in millions: \1\2m", "scaleFormatCell": r"≈ \1\2m",
"@inline": True, # write the hints in the cells too
}},
)
It's an ordinary viewer option, so config={"interpreterOptions": {...}}
and a module-wide st.set_option("interpreterOptions", {...}) work the
same way, and st.diff(left, right, interpreterOptions={...}) takes it
too — the one viewer option diff() has — applying it to both sides,
each side's interpreter reading its own entry. Values are bool, int, float or str — anything else
raises TypeError in Python — and the viewer checks each one against
its control, keeping the control's default for a value that doesn't fit.
They apply to that document only: nothing is written to the browser's
remembered options, so what the person at the screen set for the same
interpreter stays theirs. See
the Python library guide.
Seeing what an interpreter can do
Besides the panel: the [?] popover lists every interpreter bundled
into a custom build with its name and version (and marks the ones that
read binary files), and in Python structile.about — or python -m
structile --about in a terminal — lists each bundled or registered
interpreter's version, documentation links, what it can do (reads,
saves, links, hover hints) and its options with their defaults; see
What a viewer can do.
The study material's 11_interpreter_hints.ipynb walks through all of
this live — see Examples & study material.
Ready-made interpreters
Before writing one, check whether the format you have is already covered.
Every interpreter Structile ships is downloadable here, one file each —
they are plain .js files with no build step and no dependencies, so
"download" and "use" are the same act.
| Interpreter | Reads | Sample |
|---|---|---|
generic_ini.js |
INI: flat [section] blocks of key = value pairs |
.ini · demo |
generic_toml.js |
TOML: tables, dotted keys, arrays of tables, inline tables and arrays | .toml · demo |
generic_yaml.js |
YAML: block mappings and sequences, nested by indentation, single-line flow collections | .yaml · demo |
generic_xml.js |
XML: the general-purpose element/attribute mapping — plus the scaled-amount hint: amounts shown in millions, or converted to another currency | .xml · demo |
html.js |
HTML documents (markup is markup) | — |
tagged_xml.js |
An XML schema keyed by a tag attribute |
— |
keyed_xml.js |
An XML schema keyed by a key element |
— |
flat_attrs_xml.js |
XML where every value lives in an attribute | — |
implicit_xml.js |
XML with implicit repetition (repeated sibling elements as a list) | — |
ref_xml.js |
XML with cross-references between elements | — |
isda_ir_curve.js |
ISDA interest-rate curve XML | FpML · demo |
A *_no_sync.js variant sits next to several of the XML ones
(generic_xml_no_sync.js,
html_no_sync.js,
keyed_xml_no_sync.js,
tagged_xml_no_sync.js).
Those exist as a deliberate comparison point for selection
sync — what the same interpreter looks like without it —
not as a starting point to copy.
Prefer everything in one archive? All samples and interpreters, as a zip.
The viewer offers these for you
Dropping an .ini, .toml, .yaml, .xml or .html file into the
standalone viewer without an interpreter alongside
it offers the matching file from this page directly (a .csv/.tsv file
never gets this far — it simply opens):
- Use Structile's … fetches it and runs it for that session only, nothing written to disk;
- Download … hands you the same file to keep next to your data;
- or paste any URL of your own — your interpreter doesn't have to be one of these.
Nothing is fetched until you click: the viewer never reaches the network on its own.
CSV needs no interpreter
There used to be a generic_csv.js here. As of 6.27.0 the viewer parses
CSV and tab-separated text itself — one header row plus uniform data rows
become the array-of-records shape it renders as a table, with RFC 4180
quoting (including a quoted cell that spans lines), scalar coercion,
editable null cells, saving back to the same dialect, and two-way
graph/source selection sync. The sample is still here; nothing goes
with it:
- Download the sample CSV · the same table, tab-separated
- Open the self-contained sample · tab-separated demo
See CSV and tab-separated text for what the viewer does with it, including pasting a table straight out of Excel.
Writing an interpreter for your OWN delimited dialect still works exactly as this page describes, and takes precedence over the built-in parser.
A worked example
A minimal "flat properties" format — one key = value pair per line,
# for comments:
// props-interpreter.js — one key=value pair per line.
//
// interpretText(text) is the required half: raw text in, a plain JS
// value out. serializeText(value) is optional: the inverse, needed only
// if you want Save to write back to this exact shape.
function interpretText(text) {
const result = {};
const lines = text.split(/\r\n|\r|\n/);
for (let i = 0; i < lines.length; i++) {
const line = lines[i].trim();
if (line === "" || line.startsWith("#")) continue;
const eq = line.indexOf("=");
if (eq === -1) {
// Fail loudly: this line isn't "key = value", so this text
// probably isn't a props file at all.
throw new Error(`props interpreter: line ${i + 1} (${JSON.stringify(line)}) has no "="`);
}
result[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
}
return result;
}
function serializeText(value) {
if (value === null || typeof value !== "object" || Array.isArray(value)) {
throw new Error("props interpreter: can only serialize a flat object of key/value pairs");
}
return Object.keys(value).map((key) => `${key} = ${value[key]}`).join("\n") + "\n";
}
A markup interpreter has the same shape, just walking a DOM instead of splitting lines:
function interpretXML(xmlDocument) {
const root = xmlDocument.documentElement;
// ... read root's tag/attributes/children, return a plain JS value ...
// throw if root isn't the shape you expect.
}
function serializeXML(value) {
// ... the inverse: build an XML string from a plain JS value ...
}
Trying it out
Standalone viewer: drop (or paste) the data file and the interpreter
.js file onto the page together — either order. See the
standalone viewer guide.
Python:
(format= picks the text-vs-markup contract; for a file whose extension
you've registered — see below — it's inferred automatically.)
VS Code: name it settings.props.interpreter.js, right next to
settings.props — a sibling file always wins with no configuration at
all. See the VS Code extension guide.
Sharing one already-interpreted document
Everything below this point is about distributing the interpreter
script so someone else's structile can resolve future files in your
format. Sometimes that's the wrong problem — you just interpreted ONE
document and want to hand the result to a colleague who has neither
structile installed nor your interpreter file, with nothing else to set
up on their end.
out= writes a self-contained standalone HTML file for any renderer —
the data, the interpreter's own source text, and the current display
settings all inlined into one file
(window.__STRUCTILE_SNAPSHOT__ — the same shape a
custom/branded distribution
below injects for a whole set of interpreters, just for one document's
own single interpreter here):
import structile as st
st.open(
"settings.props", interpreter="props-interpreter.js", format="ini",
renderer="none", out="settings.html",
)
Open settings.html directly — double-click it, attach it to an email,
host it anywhere — no structile install, no companion .js file, no
repository checkout needed on the receiving end. renderer="browser"
(the default) does the same thing and also opens a tab; handle.save(path)
does it after the fact for a RenderHandle you already have (from any
renderer, including one that hasn't written a file yet — see the
Python library guide).
Standalone viewer: the Save as HTML… item next to the Save button does the same thing client-side, for whatever's currently loaded in the page — see the standalone viewer guide. The copy keeps the interpreter's name, version, documentation links, clickable references and current option values, and works for binary data too.
Distributing it
Just send the file
The simplest option, and often the right one: share the .js file
however you'd share any other file (chat, email, a shared drive, a repo
alongside the data it describes). Every environment can point at a bare
file path with no packaging step:
- Standalone viewer: drop it alongside the data, as above.
- Python:
interpreter="path/to/props-interpreter.js", or register it once so nobody has to remember the path again —st.register_interpreter(".props", "path/to/props-interpreter.js"). - VS Code: a sibling
<name>.interpreter.jsfile, or thestructile.interpretersetting.
This stops scaling once more than a couple of people need the same format — everyone has to independently know the file exists and keep their own copy in sync. The three options below solve that.
Python: an installable plugin
Distribute it as an ordinary pip install-able package, via a standard
entry point
in the group structile.interpreters — the same mechanism pytest and
Sphinx use for their own plugins. Once installed, it just works — no
import, no registration call, no wrapper API, for anyone who installs it:
Fastest path: download a working copy and rename it.
structile-demo-plugin.zip is a
complete, real package — the exact three files below, already wired up
and already proven to install and register correctly (it's a fixture the
structile test suite itself installs and exercises, not just a
made-up sample). Unzip it, then:
- Rename the distribution and the importable module. The zip's
pyproject.tomlcalls the distributionstructile-demo-plugin; the foldersrc/structile_demo_plugin/is the actual Python package (importable names use underscores, distribution names on PyPI conventionally use hyphens — that's normal, not a typo). Rename the folder and update every place its old name appears — every occurrence ofstructile_demo_plugin/structile-demo-pluginbelow needs to become your own package's name (acme_structile_formatsin this walkthrough). - Replace the interpreter script. Swap
src/structile_demo_plugin/interpreters/demo_keyed.jsfor your own.jsfile (theprops-interpreter.jsfrom the worked example above, or your own) — keep it inside aninterpreters/subfolder of the package so thepackage-dataline below can find it unchanged. - Edit
pyproject.toml— the full file, annotated:
[build-system]
requires = ["setuptools>=64"]
build-backend = "setuptools.build_meta"
[project]
name = "acme-structile-formats" # <- your distribution name (PyPI-style, hyphens)
version = "1.0.0"
description = "Acme's structile interpreter(s) — .props file support."
dependencies = ["structile"] # <- REQUIRED for a real plugin.
# The downloaded template deliberately OMITS this line (see its own
# comment) so it stays installable offline inside structile's own test
# suite. Copying the template without adding this line back is the
# single most common mistake here: your package will still install
# fine, but `from structile import InterpreterSource` in __init__.py
# will only work if something else already installed structile first.
[project.entry-points."structile.interpreters"]
# left of "=" is just a label (shown nowhere, can be anything unique in
# this table); right of "=" is "<your_package>:<entry point function>"
props = "acme_structile_formats:register"
[tool.setuptools]
package-dir = {"" = "src"}
[tool.setuptools.packages.find]
where = ["src"]
[tool.setuptools.package-data]
acme_structile_formats = ["interpreters/*.js"] # <- must match your renamed package
- Edit
src/acme_structile_formats/__init__.py(renamed fromstructile_demo_plugin) — the full file, annotated:
import importlib.resources
from structile import InterpreterSource
def register(registry) -> None:
"""The plugin entry point — must be named exactly what
pyproject.toml's entry-points table points at ("register" above).
`registry` is a small facade exposing only register_interpreter()."""
js_path = importlib.resources.files("acme_structile_formats") / "interpreters" / "props-interpreter.js"
text = js_path.read_text(encoding="utf-8")
# First argument: the file extension this interpreter owns, leading dot.
# name= is a label only, shown in logs/errors and st.plugins() below.
registry.register_interpreter(".props", InterpreterSource(text, name="acme_structile_formats"))
InterpreterSource(text, name=) wraps JS source loaded directly from
the installed package via importlib.resources (not a filesystem
path — the file may be inside a wheel/zip at runtime, so a plain
open(path) would break for some install methods). One package can
register more than one extension: call register_interpreter() more
than once inside the same register() function.
- Install it locally and verify. From the package's own directory
(wherever
pyproject.tomlis):
Expect your package listed and marked loaded, not failed. Then prove it actually resolves a file:
A plugin that fails to load or raises during registration is logged as
a warning and never applied, but never breaks anyone else's open()
call — and it still shows up in st.plugins() marked as failed, with
the error, rather than silently vanishing. python -m structile
--plugins prints the same thing from the command line, and
STRUCTILE_DISABLE_PLUGINS (any truthy value) skips discovery
entirely, for isolating "is my plugin the problem?" from everything
else.
- Build and distribute it, exactly like any other Python package —
nothing about
structile.interpretersentry points changes this part:
pip install build twine
python -m build # writes dist/*.whl and dist/*.tar.gz
twine upload dist/* # to PyPI — needs a PyPI account/token
For an internal-only format that shouldn't be public, upload to your
organisation's own package index instead (Artifactory, devpi, a simple
authenticated HTTP index, AWS CodeArtifact, …) and have colleagues
pip install --index-url https://your-internal-index/simple/
acme-structile-formats — the entry-point mechanism itself doesn't care
where the package came from, only that pip install put it on
sys.path.
Discovery is lazy (triggered by the first open()/diff()/convert()
call, never by import structile) and runs at most once per process.
Distributing to a VS Code team
Three ways this can go, in order of how often each one is actually the right call:
Most of the time: a personal setting, not a distributed file at all.
Structile is mainly for exploring data in ad-hoc projects — plenty of
them not yours to add tool-specific config to, the same reason
.vscode//.idea/ folders don't usually get committed either. Set
structile.interpreter at the User level (Ctrl+Shift+P ->
Preferences: Open User Settings (JSON)), not the Workspace level, and
it follows you instead of any one repo:
// User Settings (JSON) — personal to your profile, applies in every
// project you open from now on, commits nothing anywhere
"structile.interpreter": ["/home/you/tools/acme-interpreters/blotter.js"]
Configured once, it resolves .axml/whatever in every workspace you open
afterward — and it isn't workspace-trust-gated (only the workspace-local
option below is), so it works the moment you set it, in an untrusted
workspace too. A wiki page with the interpreter .js file attached and
this JSON snippet to paste is the whole distribution story for most
teams: nothing checked into any repo, no extension to build or install,
no coordination beyond "here's the file, here's the setting."
If the format genuinely belongs to one specific repo — its data files
just are that schema, the way a .eslintrc belongs to a JS project —
checking it in there is reasonable: .structile/interpreters.json in the
workspace root, mapping to .js files under .structile/interpreters/:
Only active in a trusted workspace — loading arbitrary JS out of a cloned repository into a webview is exactly the threat Workspace Trust exists for. Anyone who opens and trusts the repo gets it with zero setup of their own — but this commits Structile-specific config into a shared repo, so it's a call for whoever owns that repo to make, not a general distribution mechanism for a format that shows up across many unrelated projects.
If your organisation already builds and ships internal VS Code
extensions, a third option exists: any installed extension — including
one that does nothing else — can declare interpreters in its own
package.json, via the same public contributes extension point every
extension can use. Neither this nor the workspace option above needs the
Structile extension's own source — its vscode-extension/src/** stays
closed, and nothing here touches it; what you're building is a second,
independent extension of your own. This is real infrastructure most teams
don't have and don't need to build just for one interpreter — reach for
it only if your org already ships internal extensions for other tooling;
the two options above cover everything else.
Fastest path: download a working copy and rename it.
structile-demo-companion-extension.zip
is a complete, minimal, real VS Code extension that does nothing except
contribute one interpreter — no compile step, no main entry point, just
package.json + one .js file, on purpose. Unzip it, then:
- Replace
interpreters/demo_keyed.jswith your own interpreter script. - Edit
package.json— the full file, annotated:
{
"name": "acme-structile-formats-vscode", // <- rename
"displayName": "Acme Structile Formats", // <- rename
"description": "Ships Acme's .props interpreter for the Structile extension.",
"version": "1.0.0",
"publisher": "acme", // <- your Marketplace publisher id, if publishing
"license": "UNLICENSED",
"engines": { "vscode": "^1.85.0" },
"categories": ["Other"],
"contributes": {
"structileInterpreters": [
{
"extensions": [".props"], // <- your extension(s), leading dot
"path": "./interpreters/props-interpreter.js", // <- relative to this file
"name": "Acme props format", // <- shown in the two debug commands below
"format": "text", // "text" (interpretText/serializeText) | "xml" (interpretXML/serializeXML)
"priority": 0 // only matters if another installed extension also claims .props — higher wins
}
]
},
"scripts": {
"package": "vsce package --allow-missing-repository --no-rewrite-relative-links"
},
"devDependencies": {
"@vscode/vsce": "^3.9.2"
}
}
- Package and install it locally to verify:
npm install
npm run package # writes acme-structile-formats-vscode-1.0.0.vsix in this folder
code --install-extension acme-structile-formats-vscode-1.0.0.vsix
(Or, without a command line: VS Code -> Ctrl+Shift+P ->
Extensions: Install from VSIX... -> pick the .vsix.) Then open a
.props file and confirm: Structile: List Contributed Interpreters
should list your extension; Structile: Show Interpreter Resolution
on the open file should show it as used.
- Distribute it. Three options, not mutually exclusive:
- Hand out the
.vsixdirectly — exactly what this docs site does for the main extension itself (see the VS Code extension guide): host the file anywhere, colleagues run Install from VSIX.... No account, no review process, works today. - Publish to the VS Code Marketplace (
npx vsce publish— needs a Marketplace publisher account and a Personal Access Token) for discoverability via the Extensions view's search. - Publish to Open VSX (
npx ovsx publish) alongside or instead of the Marketplace, for VSCodium and other non-Microsoft-marketplace editors.
Building a custom/branded distribution
Every option above still asks a person to supply the interpreter
themselves — drop the .js file, pip install a plugin, install a VS
Code extension. Opening structile.html directly (no Python, no VS
Code — just double-clicking the file, or hosting it on a wiki) has no
registry to fall back on at all: dropping a data file with no matching
interpreter yet gets a prompt asking for one, every single session.
structile.build_custom_html() closes that gap by baking a curated,
build-time-chosen set of interpreters directly into a copy of
structile.html. Opening that file and dropping only a data file
resolves it immediately — no companion .js, ever, for the extensions
the build chose to bundle. A stock, unmodified structile.html is
unaffected either way.
For a single interpreter there's a no-Python shortcut: open a file
through it in the standalone viewer and pick
Save viewer with interpreter… from the Save menu. That writes a fresh
copy of the viewer with that interpreter built in and no data, which
recognises that format's own extension — binary formats included — so
whoever receives the one HTML file just drops matching files onto it.
build_custom_html() is the same idea for a curated set, at build time.
Fastest path: download a working copy and rename it.
structile-demo-custom-distribution.zip
combines this with the installable-plugin pattern above, driven from one
shared manifest.json instead of two separate interpreter lists. Unzip
it, then:
- Rename the package, same as the plugin walkthrough above:
src/structile_demo_custom_distribution/->src/acme_structile_formats/, and every occurrence of that name inpyproject.toml/__init__.py/build_html.py. - Edit
manifest.json— the one file both halves below read from:
{
"interpreters": [
{ "extensions": [".props"], "path": "interpreters/props-interpreter.js",
"name": "Acme props format", "format": "text" },
{ "extensions": [".axml"], "path": "interpreters/acme-blotter.js",
"name": "Acme blotter XML", "format": "xml" },
{ "extensions": [".acfg", ".acmerc"], "path": "interpreters/acme-config.js",
"name": "Acme config", "format": "acme_config" },
{ "extensions": [".abf"], "path": "interpreters/acme-abf.js",
"name": "Acme ABF", "format": "bin", "binary": true }
]
}
extensions/path/name/format mean exactly what they do in the VS
Code contribution shape above — format is "xml"/"html" for the
markup contract, anything else ("text", or a more specific string
like "ini") for interpretText/serializeText. Replace
interpreters/acme_config.js with your own script.
A build takes as many interpreters as you want. "interpreters" is
a list, and several formats in one branded viewer is the normal case,
not a special one — the example above bakes three. Each entry is
independent: its own extensions (one or several), its own format,
and the two contracts mix freely in one build. Two entries claiming the
same extension is not an error — the later one silently wins, so keep
the list unambiguous yourself. Extensions you don't list keep behaving
exactly as they do in the stock viewer, and the built-in
JSON/Python-repr/CSV formats need no entry at all.
An entry with "binary": true (implied by "format": "bin", so the
viewer's own Save viewer with interpreter… output for a binary
session needs no extra field) is for an interpreter that reads
bytes — the contract under The contract above: a
dropped file of one of its extensions goes straight to its
interpretText, one character per byte, never decoded as text. That
covers the file picker, a data file dropped together with a .js,
and comparing two such files. A binary file the entry rejects still
gets the ordinary hex-view / pick-an-interpreter prompt, and a binary
file under any other name still has every bundled binary interpreter
tried on its bytes before the viewer asks. The [?] popover marks the
bundled interpreters that read binary files.
3. Build the baked HTML — build_html.py calls
structile.build_custom_html() against manifest.json:
Open the result directly (file:// it, or host it anywhere) and drop
a .props file with no interpreter attached — it resolves on its own.
4. Wire up the Python side from the same manifest. __init__.py's
register() entry point (see "Python: an installable plugin" above
for the full mechanics) reads manifest.json too, so a colleague who
pip installs this package gets both halves for free: st.open()
resolves .props automatically, and (next) every renderer opens the
branded HTML.
5. Ship it as a thin wrapper, not a fork. The package depends on
structile normally and bundles the baked HTML as package data — one
line at import time points every renderer (open(), diff(),
.to_html(), the browser/file/widget renderers) at it:
# acme_structile_formats/__init__.py
import importlib.resources
import structile as st
st.set_viewer_html(importlib.resources.files("acme_structile_formats") / "acme_structile.html")
Colleagues who pip install acme-structile-formats get the branded,
pre-wired viewer automatically — no separate download, no fork of
structile to keep in sync with upstream releases. A full fork
(replacing structile's own bundled HTML in a copy of the whole
package under a new name) is the alternative if you need a fully
independent package identity — more control, at the cost of manually
re-merging every upstream change yourself.
Resolution order
When more than one of the above applies to the same file, the most specific one wins — how narrowly a declaration targets this exact file, not which mechanism supplied it:
Python, most to least direct:
| Rung | Source |
|---|---|
| 1 | An explicit interpreter= argument |
| 2 | A direct register_interpreter() call |
| 3 | A plugin registration (entry points) |
| 4 | Nothing — existing fallback, unchanged |
VS Code, most to least specific:
| Rung | Source |
|---|---|
| 1 | Sibling <name>.interpreter.js |
| 2 | structile.interpreter setting (workspace, then user scope) |
| 3 | Workspace .structile/interpreters/ mapping (trusted workspaces only) |
| 4 | Interpreters contributed by installed extensions (highest priority first) |
| 5 | Built-in .xml/.html fallback — opens with a warning and waits |
Within any rung that produces more than one candidate, the same "fail loudly, first non-throwing one wins" trial from above applies.
Debugging what's actually loaded
- Any environment: the puzzle-piece button's
interpreter panel names the interpreter that
read the document and its version, where it came from (bundled with
the viewer, added this session, supplied by the host, saved with the
page),
candidate i of nwhen it was chosen from a list, and how many diagnostics it reported. The[?]popover lists every interpreter bundled into the copy you're running. - Python:
structile.about(orpython -m structile --about) lists the viewer in use and every bundled, registered and plugin interpreter with what each can do — see What a viewer can do.st.plugins()(orpython -m structile --pluginsfrom the command line) lists every discovered plugin, valid or failed — a failed one shows its error rather than silently disappearing. SetSTRUCTILE_DISABLE_PLUGINSto any truthy value to skip discovery entirely (explicitregister_interpreter()calls are unaffected). - VS Code: Structile: Show Interpreter Resolution shows every candidate considered for the active file, each marked used, rejected, or not tried. Structile: List Contributed Interpreters lists every contribution from every installed extension. Structile: Reload Contributed Interpreters re-scans installed extensions after you edit a contributed interpreter's own content.