Implementations

Nothing on this page is privileged by the format. The specification is public domain, an implementation needs no permission and no blessing, and the only thing that makes one correct is the specification itself. The programs below are the ones that exist today; the list is open, and a pull request adds to it.

The reference implementation

slpc-rust is a Rust workspace holding two crates: slpc, the library that reads, writes and validates containers, and slipcase, the command-line tool built on it. It is a reference implementation in the strict sense — it exists to show that the specification is implementable, and to be checked against it. Where the two disagree, the specification is right.

slipcase pack report.pdf --meta owner.toml       # writes report.pdf.slpc
slipcase info report.pdf.slpc                    # prints the flyleaf
slipcase repack report.pdf.slpc --meta new.toml  # changes it in place, keeping the rest
slipcase validate report.pdf.slpc                # exit 0 if conformant
slipcase unpack report.pdf.slpc --dest ./out     # writes the content file and nothing else

Wherever a file is read, - names standard input, and wherever one is written it names standard output. Exit codes tell success from bad input, from a bad command line, from a container the build cannot judge.

On Debian and Ubuntu it is sudo apt install slipcase from the Excelano apt repository; on macOS and Linux with Homebrew, brew install excelano/tap/slipcase; from source, cargo install slipcase. Windows, the curl installer and the plain release archives are covered in the repository's README, which is where the current instructions live rather than here. MIT licensed.

Applications

Slipcase Desktop opens a container, says whether it is conformant, shows the content file and the flyleaf traveling with it, lets the flyleaf be edited in place, and hands the content file to whatever the operating system already opens that kind of file with. It is on the Mac App Store, on the Microsoft Store as Slipcase, in the Excelano apt repository as slipcase-desktop, and in source at excelano/slipcase-desktop. It parses no containers itself: every read, every write and every verdict comes from slpc.

Slipcase Open takes the other half of the job: double-click a container and the content file opens in whatever application normally handles it, with every save repacked into the container. No flyleaf window and no container browsing. A repack preserves the flyleaf and any members it does not recognize, as §3 requires. It is on the Microsoft Store, on macOS as a Homebrew cask, in the Excelano apt repository as slipcase-open, and in source at excelano/slipcase-open. MIT licensed.

Slipcase Query asks a folder of containers a question. Name a folder, write a SlipQL query, and the containers that answer come back as rows, one column per flyleaf key. Selecting a row shows the content file and the whole flyleaf beside the table, and a button hands the content file to whatever the operating system opens that kind of file with. It only reads: there is no Save in it, and no path through it that writes a container. Every query is a fresh scan, so there is no index to go stale. It is on the Mac App Store, on the Microsoft Store, in the Excelano apt repository as slipcase-query, on crates.io, and in source at excelano/slipcase-query. MIT licensed.

slipcase-common is not a program. It is the media type declaration and the icon a container is drawn with, packaged once so that every Slipcase product on a Linux machine can depend on it — two packages cannot ship the same path, and an icon named for a media type is one file at one path. Without it a container draws as a blank generic document, which is the first thing somebody sees of a file format they were sent and did not ask for.

Querying a folder

SlipQL is a query language over flyleaves, and a command that runs it. Point slipql at a directory of containers and ask in select, from and where: each container is a row, each flyleaf key a column. The clauses come from SQL and the literals from TOML, so anyone who can write a flyleaf can write a query against one.

slipql> select @path, title, governance.owner where status = "draft" or tags contains "legal"

It reads each flyleaf in place through slpc, never unpacks a content file, keeps no index and changes nothing, so every answer is what is on disk now. A key a container lacks is an empty cell, and a file it cannot read is skipped and counted rather than failing the query. It runs as a prompt, with -e for one query, or over piped standard input, and writes tables, CSV, TSV or JSON. The crate is also a library, which is how Slipcase Query below uses it.

On Debian and Ubuntu it is sudo apt install slipql from the Excelano apt repository; on macOS and Linux with Homebrew, brew install excelano/tap/slipql; from source, cargo install slipql. GRAMMAR.md is the language reference. MIT licensed.

Writing your own

Read §2 for what a container is and §3 for what a program handling one must do. The second is the part that is easy to skip and is where the interesting requirements are: locate the content file by content.file and never by position, establish uniqueness by enumerating central directory entries rather than by a name-keyed lookup, preserve flyleaf keys and archive members you do not recognize, write only the content file when extracting unless the caller asks for more, and never apply the permission bits recorded in the archive.

Read §6 before anything that runs unattended. Identifying a container is a parse of untrusted input — a reader cannot know whether a file is a container without decompressing the flyleaf and parsing it as TOML, and it must do that before anything about the file has been established. An indexer, a scanner or a shell preview handler is invoked on whatever happens to be in the directory, so the bound on what it will spend has to be in place before it knows what it is holding.

Then check yourself against the conformance corpus: eighty-seven containers with declared verdicts, built by a generator that needs nothing but Python 3.11. It covers the cases a hand-written test suite tends not to reach — a local file header disagreeing with the central directory, a CP437 name with the UTF-8 flag clear, duplicate member names, an entry that is not a regular file. It is not normative. Where a case and the specification disagree, the specification wins and the case is a bug worth reporting.

If the specification cannot answer a question you actually hit, that is the most valuable thing you can send back. Open an issue.

Adding to this list

Open a pull request against this site's repository. What is wanted is a program someone can actually obtain, a note of which version of the specification it implements, and a link to its source or its listing. Completeness is not a bar — a library that only reads containers is worth listing, and the listing should say so.