Skip to content

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 also serializeText(value), the inverse — when present, Save writes edits back to this exact text shape instead of falling back to a different format. serializeText may take a second argument, hints — {literals: [{path, text}]}, the text a user typed for the number at each path (2.0 rather than the JS number 2). The viewer keeps one copy of an interpreter per document and re-reads every text it saves, so a serializeText can 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 DOM Document, returning a plain JS value. Optionally also serializeXML(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:

const INTERPRETER_NAME = "Acme props format";
const INTERPRETER_VERSION = "1.0.0";

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;
}
  • value is the raw value your interpreter produced — a number, bigint, string, boolean or null — so 100 and "100" can be told apart.
  • ctx says where the value sits, always from its real place in the document, never from what happens to be drawn (a folded a/b box title, a link window, a diff's old → new key):
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)
  • options is a plain object of the current option values, keyed by the ids your INTERPRETER_OPTIONS declares — {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 null for no hint. Each line shows exactly as returned — a label such as hint: 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. hoverHint and the options are never passed to interpretXML/interpretText/serialize*, so convert() 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 hoverHint that 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/ interpretText left behind: in a diff, hoverHint may 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 any INTERPRETER_DOCS links;
  • Reads (text · toml, XML/HTML (as a DOM) · xml, or binary data), Saves (yes, or no (read-only) when there's no serialize* function), Links (the reference delimiters and id field it declares, or no), 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 page or carried over from the tab that saved this copy; Chosen — candidate 2 of 3 when 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, formats in millions: \1\2m (tooltip) and ≈ \1\2m (cells): a balance of 498250000 reads 498250000 ≈ $498.3m.
  • Another currency. The FX rate as the factor and the target currency's symbol: factor 0.92, symbol € shows a USD notional of 1000000 as €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:

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:

import structile as st

st.open("settings.props", interpreter="props-interpreter.js", format="ini")

(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.js file, or the structile.interpreter setting.

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:

import structile as st
st.open("settings.props")   # correct interpreter chosen automatically

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:

  1. Rename the distribution and the importable module. The zip's pyproject.toml calls the distribution structile-demo-plugin; the folder src/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 of structile_demo_plugin/structile-demo-plugin below needs to become your own package's name (acme_structile_formats in this walkthrough).
  2. Replace the interpreter script. Swap src/structile_demo_plugin/interpreters/demo_keyed.js for your own .js file (the props-interpreter.js from the worked example above, or your own) — keep it inside an interpreters/ subfolder of the package so the package-data line below can find it unchanged.
  3. 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
  1. Edit src/acme_structile_formats/__init__.py (renamed from structile_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.

  1. Install it locally and verify. From the package's own directory (wherever pyproject.toml is):
pip install -e .
python -c "import structile as st; print(st.plugins())"

Expect your package listed and marked loaded, not failed. Then prove it actually resolves a file:

python -c "import structile as st; st.open('example.props', renderer='text')"

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.

  1. Build and distribute it, exactly like any other Python package — nothing about structile.interpreters entry 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/:

{ ".props": "props-interpreter.js" }

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:

  1. Replace interpreters/demo_keyed.js with your own interpreter script.
  2. 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"
  }
}
  1. 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.

  1. Distribute it. Three options, not mutually exclusive:
  2. Hand out the .vsix directly — 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.
  3. 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.
  4. 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:

  1. Rename the package, same as the plugin walkthrough above: src/structile_demo_custom_distribution/ -> src/acme_structile_formats/, and every occurrence of that name in pyproject.toml/__init__.py/build_html.py.
  2. 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:

import structile as st
st.build_custom_html("manifest.json", output="acme_structile.html")

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 n when 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 (or python -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() (or python -m structile --plugins from the command line) lists every discovered plugin, valid or failed — a failed one shows its error rather than silently disappearing. Set STRUCTILE_DISABLE_PLUGINS to any truthy value to skip discovery entirely (explicit register_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.