Catena files and sharing

When you write a sequence in Castiel, it lives inside the editor until you save it. Saving turns your work into a file on disk — and Catena uses four different file extensions, each for a different job. This chapter explains what a sequence is, what a collection of sequences is, and which of the four files (.cat, .cats, .catx, .nex) you reach for when you want to keep, bundle, or share your work.

If you only ever write sequences for yourself and never send them to anyone, you can get by knowing just .cat. The other three matter the moment you want to package several sequences together or hand them to someone else. Read the first two sections for the ideas, then use the table as a quick reference.

Two ideas: a sequence and a concatenation

Everything here rests on two words.

• A sequence is one program — a single named piece of Catena code, such as a VAT calculator or a compound-interest routine. One sequence does one job.
• A concatenation is a collection of sequences kept together, the way a project keeps several source files under one roof. When you have a set of related sequences — a small library of finance tools, say — a concatenation is how you package them as a unit.

The four Catena file types divide cleanly along this line. Two of them (.cat and, in a supporting role, .nex) describe the pieces; the other two (.cats and .catx) are the single-file bundles that carry a whole concatenation from one place to another.

The four file types

.cat — one sequence. A .cat file holds a single sequence, stored as plain-text JSON. Besides the code itself, it carries descriptive information about the sequence so it can be listed and understood without being run: its name, an optional description, the author, a version, tags and a category, and a stable identity that stays fixed even as you rename or revise it. That descriptive information is what lets the Library show you a tidy row for each sequence — name, description, tags, version — before you ever open it.

.cats — a portable library. A .cats file is a single bundle (a zip container) holding several .cat files together with one .nex manifest that lists them. It is the portable, one-file form of a concatenation: hand someone a single .cats and they have your whole collection. Opening a .cats does not run anything — it is a library. Its sequences sit there waiting to be browsed, imported, and called when you choose. Think of it as a folder of tools you have received but not yet picked up.

.catx — a library that runs itself. A .catx file is byte-for-byte the same bundle as a .cats — the same .cat files, the same manifest, the same container. Only two things differ: the extension, and what happens when you open it. A .catx is marked to run. Open one and Castiel immediately executes the sequence the bundle names as its default; if the bundle names no default, Castiel shows you the list of sequences inside and lets you pick one. Because the container is identical, turning a library into a self-running pack (or back again) is just a rename: .cats becomes .catx. Windows normally hides file extensions, so rather than make you rename the file by hand, Castiel offers the switch from inside the app.

.nex — the manifest. A .nex file is the project descriptor for a concatenation, stored as JSON — the part-list that ties a bundle together. It names the .cat files that belong to the collection and carries collection-level information: the concatenation's name and version, which sequence is the default (the one a .catx runs on open), the default language for labels, and any external services the sequences need. A .nex always travels inside a .cats or .catx bundle; it is what makes the loose .cat files into one coherent library rather than a pile of unrelated programs.

The single most useful thing to remember: .cats is a library you open at your leisure; .catx is the identical library that starts working the instant you open it. Same bytes, different intent.

Saving and sharing your work

You do not build these files by hand — you produce them from the app, in user terms.

Keep a sequence: save it to the Library. While a sequence is open in the editor, saving it to the Library gives it a name, a home, and a stable identity, so you can find it again, call it by name from any mode, and reuse it without retyping. On disk each saved sequence is a .cat. See Sequences and functions for calling a saved sequence by name.

Share one sequence: export it. From the Library you can export a single sequence as a .cat file and send it to someone. They import it into their own Library and it becomes one more sequence they can browse and call.

Share a collection: bundle a pack. When you want to hand over several related sequences as a set, bundle them into a single .cats — a portable library. The recipient uses Import pack in the Library to bring the whole collection in at once. If you want the pack to run a particular sequence the moment it is opened — a demo, or a one-shot tool — you mark a default sequence and save it as a .catx instead; Castiel offers this when you package the pack.

The Library chapter walks through the save, import, and export dialogs in full, including categories, tags, and web sources.

Why .catx runs itself — and the safety that surrounds it

A .catx exists for convenience: sometimes you want a bundle that does something the moment it is opened, without the recipient having to find and launch the right sequence. That is exactly what makes it worth a second thought.

Opening a .catx that someone else made means running code you did not write. So when you open a self-running pack you did not author, Castiel asks you to confirm before it runs — a trust prompt, the same caution any careful tool takes before executing an unfamiliar file. A .cats never raises this question, because it runs nothing; that is the safer default for anything you are merely browsing.

There is a second layer of protection underneath the prompt, and it is worth knowing because it is reassuring. A Catena sequence is sandboxed by design. It cannot reach into your file system, open network connections, or touch devices on its own — those capabilities simply are not part of the language. The only way a sequence can obtain outside data (a live exchange rate, for instance) is through the app itself, and any such request surfaces to you rather than happening silently in the background. Running a .catx is therefore never like running an arbitrary program from the internet: at worst it computes and shows you a result. The trust prompt is there so you decide when a received pack runs; the sandbox is there so that even a pack you trusted cannot misbehave.

Versions and compatibility

Every .cat and .nex records the Catena language version it was written for — the current version is 1.0. If you open a file written for a newer version than your copy of Castiel understands, it does not fail blindly: it scans the file, honours what it can, and warns you about anything it cannot. And if you edit an older file and add something newer than its recorded version, Castiel asks before bumping the file's version — because you may be keeping an older version deliberately, to stay compatible with an older app or another maker's tools.

A bundle, unpacked

It helps to picture what is actually inside a .cats (or the identical .catx). Suppose you package a small set of finance tools called FinancePack. As a single file it is FinancePack.cats; if you unzipped it, you would find:

FinancePack.cats
├── finance.nex          the manifest: names the pack "FinancePack",
│                        lists the three sequences below, and marks
│                        "vatTotal" as the default sequence
├── vatTotal.cat         one sequence — add VAT to a list of prices
├── compoundInterest.cat one sequence — grow a balance over time
└── loanPayment.cat      one sequence — the monthly payment on a loan

Rename that one file to FinancePack.catx and nothing about the contents changes — but now, opening it runs vatTotal straight away instead of simply adding the three tools to the recipient's Library. That single difference, extension and intent, is the whole of the .cats-versus-.catx distinction.

See also

• File types — every file Castiel reads and writes, including the .cast tape session, in one place.
• The sequence Library — saving, importing, exporting, and organising sequences and packs.
• Getting started with Catena — writing your first sequence before you save or share it.
• Sequences and functions — naming a sequence and calling it from anywhere in the app.