Triple script file format

Triple scripts use one of the most portable executable file formats in the world.

A triple script is a concatenation of t-blocks. Each t-block begins and ends with a triple slash script delimiter. And each t-block corresponds to a source code module.

/// <script>
/* ... first module contents go here ... */
/// </script>
/// <script>
/* ... second module contents go here ... */
/// </script>
/// <script>
/* ... more ... */
/// </script>
/// <script>
/* ... shunting block contents go here ... */
/// </script>

The t-block in the tail position is called the "shunting block". By convention, the first t-block SHOULD correspond to the module that is the "heart" or "brain" of your program, for readability purposes.

Also by convention, triple scripts are usually given the extension .app.htm.

The .htm part of the file extension serves an important purpose: it ensures that when a program written as a triple script is opened in the browser it actually ends up running. Remember that, just like a Perl or Python or shell script, a triple script (despite its ability to run in the browser) is meant to be used offline—either saved directly to disk or having been cloned as a file checked in to some project repo—so there is no server sending a mimetype when accessing the file. A user should be able to double-click or navigate directly to, say, the Build.app.htm file from a project's source tree and be presented with a running instance of the program. The .htm file extension is by default configured to open in the browser on most systems and is what makes this work.

In reality, the file could use something ending with the .html extension—such as foo.html—and it would work just as well. However, we encourage the use of .app.htm as an easy way to distinguish triple scripts from HTML source code or web pages saved to disk, particularly since the main text of a triple script is the contents of its t-blocks, and not really HTML.

(Feel free to use the same .app.htm file extension if you experiment with the format, even if you're not creating proper triple scripts. It's the triple slash delimiter at the beginning of a file that signifies whether it's a triple script, not the file extension alone.)

How it works

The triple script format has been deliberately designed so it is parseable by any runtime implementing the ECMA-262 language standard, and it's also executable by browsers—which aren't designed to execute scripts directly, but instead expect them to be sourced or embedded within a document.

In environments that are not aware of triple scripts, such as engines like NodeJS, Graal, or GJS that are primarily concerned at the parser level with implementing ECMA-262, the format works because the triple slash delimiters will be treated as ordinary comments, and the t-blocks' contents will be evaluated as JS.

In other environments, such as browsers, the triple slashes from the delimiters will be initially drawn on the page and then immediately afterwards, the browser will parse and evaluate the t-blocks' contents as JS. The browser-specific system support modules compiled into the program should take care of blanking the page (to erase the triple slashes) and building the actual application UI as the app starts up.

The shunting block is meant to be the main entry point into the program, whether in the browser or in a command-line runtime. Since the triple script dialect mandates that top-level code throughout the script should be limited to things like declarations and static assignments, the shunting block's IIFE is generally the place where the script begins its first "real" execution—i.e. the evaluation of program text that isn't constrained to statically computable, logicless statements. The shunting block is so named because its role is to to detect the type of environment the script is running in, ensure that the correct platform-specific support modules get initialized, and then route execution along the appropriate path.

Self-contained

The philosophy behind triple scripts bears some similarity to the Golang ecosystem's stance on the use of static binaries—avoid dynamic linking.

All dependencies a triple script relies on to run are carried as t-block payloads within one self-contained file.

Triple scripts by convention do not load NodeJS-style CommonJS modules or make any assumptions about special directory hierarchies. Nor do they kick off network load events to pull in external files, as most web pages do.

The role of the triple script compiler (trplkt) is akin to a bundler. It takes the paths of one or more source files as explicit arguments, builds a dependency graph by recursively sniffing out the static imports, and does some straightforward preprocessing that ends with the program emitted in concatenated t-block format. The result is a triple script embodied in a single, self-contained file that can be run on the universal application runtime (the browser), or used from the terminal.

The triple script format allows authors to build and distribute programs without propping up any network-connected server to handle the app's needs on the backend. Everything takes place on the user's machine—just like much of the client software developed in the thriving ecosystem of the 80s and 90s.

Users who have saved programs in this format can run them offline; they can continue using triple scripts past the point where the original developer chooses to pull the plug on the project, since there is no infrastructure needed to support it; they can easily modify the program with local tweaks and user customizations; etc.

Offline

Triple scripts are meant to be usable offline, in the spirit outlined above. (See also: the three invariants for triple scripts.)

While there are no technical mechanisms currently in place to prevent authors from misusing the triple script format to create and distribute programs with an architecture similar to the way most mobile apps are developed (fat client coupled to network-connected services) you SHOULD NOT create such apps and try to pass them off as triple scripts.

If you'd like to do work to pursue interesting ideas that fall outside this prohibition, triplescripts.org encourages you to do so. As noted above, however, you SHOULD NOT use triple slash delimited t-blocks for such programs. (Try using two slashes instead, which works just as well as three.)

Future developments in the triple script ecosystem will most likely involve the creation of at least one runtime specifically meant for executing triple scripts in a capability-based environment where the default is to disallow any triple script from accessing the network. To create programs that ignore the self-containedness principle or otherwise access the network while passing them off as triple scripts means that those programs will appear to be broken when run in such an environment.

triplescripts.org has a strong commitment to backwards compatibility but will not take effort in the group's future work to preserve compatibility in programs that have ignored these guidelines.