Top-down

The triple script ecosystem benefits from programs that are written top-down. That is, it should be possible to open up a triple script, starting reading at the top of the file, and read down to the bottom in a more-or-less linear order, just like the pages in a book, and have a good understanding of the program. This is in contrast to languages like C where the conventions practically require a reader start at the bottom of the file and read to the top.

The top-down philosophy is on display in trplkt, triplescripts.org's reference compiler, where the first thing that a reader sees upon viewing the source is the primary class (TripleKit) that is the heart of the program. We advocate that other triple scripts be written the same way. If your Build.app.htm is just a copy of trplkt, then this can be achieved in one of two ways.

The first approach is to write in your project README your build instructions as:

   build -t Foo.src -m main.src

This will ensure that Foo appears first in the resulting triple script. (This example assumes that this is the module that you want to appear first, because it best corresponds with the heart of your program.)

Alternatively, you can make Foo the first import in your main.src shunting block, and simply give your instructions as:

   build -tm main.src

When implementing a class, we also advocate for keeping the top-down philosophy in mind when writing ordering methods within the file. If a method collate calls a method seed and collate is seed's only caller, then the former should appear nearer to the top of the file than the latter. When reading a triple script, it should seem like a picture that gets clearer, or a concept that gets more specific, where it originally starts out as a general outline of all that follows.

Program authors can even take advantage of function hoisting to get the same effect. Suppose you wanted to write the collate method but didn't want to create a separate seed method (or even a quasi-private _code). You might instead write:

   collate(collection) {
     if (!collection.size) {
       seed(collection);
     }
   
     /* ... actual collation implementation omitted ...*/
   
     return collection.size;
   
     // Add some base-level entries
     function seed(collection) {
       /* ... */
     }
   }

Notice how not only does the use of seed appear before its declaration, but our collate method also has a return statement that precedes the seed declaration. This is legal in the triple script dialect, and it works because seed gets "hoisted"—enabling us to write programs that read well top-down to great effect.

External links

Write code top-down — Lawrence Kesteloot