poka.sh

 Docs

Route an extension to an existing parser

how-to

Many formats are plain text, code, INI, XML or a zip that an existing module already reads. Do not write a crate for them, and do not leave them as a hex stub. This page routes such a format to the module that reads it.

Before you start

  • A corpus sample of the format in poka-samples.
  • The wasm module you want to reuse, built for wasm32-wasip1 (see Write a parser).

Steps

  1. Run the candidate module on the sample. Use wasmtime and read the output. Route the format only if the preview is right, not merely non-empty.

  2. Pick the form of the route.

    • It is genuinely the same format as the module's own (.ppsx on poka-pptx): add the extension to the aliases list of that module's plugin.json.
    • It needs its own id, name or registry row (poka-xlt on poka-xls.wasm, poka-docm on poka-docx.wasm): add one line to parsers/aliases.toml.

  3. Write the aliases.toml line (skip this step for an aliases entry):

    poka-xlt = { module = "poka-xls", ext = ".xlt", name = ".xlt Preview" }

    The caps, viewer and wasm come from the module's own manifest. Set memory_mb and max_time_ms only where they differ. aliases and disabled_reason are the other optional keys.

  4. Update the format's FILE_FORMATS.csv row: WasmModules, Viewer, ParserType and WasmRoute.

  5. Add a case to scripts/test-routed-samples.py: the route id, the corpus sample and two or three strings taken from the sample's own content. The script resolves the sample's extension through the expanded manifests, runs the route's wasm under wasmtime with the route's caps, and fails unless the module reported those strings. --dump <route-id> prints what the module reported, to pick them from.

  6. Run the checks:

    cargo build --release --target wasm32-wasip1 -p <module>
python3 scripts/test-routed-samples.py <route-id>
python3 scripts/check-parser-invariants.py
python3 scripts/test-manifests.py
python3 scripts/sync-file-formats.py --check
python3 scripts/scorecard.py        # then commit docs/scorecard.md

Do not

  • Do not create a parsers/poka-<ext>/ directory that holds only a plugin.json. With no Cargo.toml it breaks every cargo command with "failed to load manifest for workspace member".
  • Do not claim an extension that another module already owns. One handler per file extension; test-manifests.py fails on a clash.

The checks and the release archive expand aliases.toml lines into manifests with scripts/_manifests.py, so a route cannot drift from the binary it runs.

See also

  • SPEC.md — routing rules in the parser contract.
  • Test a parser — check the routed format on the corpus.