#nntrac: no-nonsense TRAC implementation in ANSI C

The nntrac language (all-lowercase) is a portable, lightweight (under 1000 SLOC of ANSI C) and embeddable derivative of the TRAC T-64 language originally designed by Calvin N. Mooers in the 1960's. Compared to the original, nntrac is created from scratch with modern systems in mind and adds several useful features to interact with current operating environments.

#Building

Just invoke your C compiler like this (replacing cc with the specific command and updating the flags if necessary):

cc [-static] -std=c99 -Os -s nntrac.c -o nntrac [-DNNT_EMBED] [-DNNT_NO_SHELLEXT] [-DNNT_SHARP="#"] [-DNNT_SYMNAMELEN=32]

where cc is the C compiler of your choice. Compilation was tested on GCC, Clang, Zig cc, TCC (dynamic linking only), Cproc and chibicc.

Supported compiler flags (all optional):

• -DNNT_EMBED: build nntrac without the main function (entry point). See "Embedding nntrac into your projects" section for more information on the embedded usage.
• -DNNT_NO_SHELLEXT: disable the os primitive. See "New primitives" section for more information.
• -DNNT_SHARP: change the # character (start of active or neutral function call) to something else.
• -DNNT_SYMNAMELEN: maximum length of TRAC form or primitive function names (default 32).

#Usage

The nntrac binary can be run interactively (with nntrac or echo 'script' | nntrac) or in the script invocation mode (./nntrac script.trac param1 param2 ...). In the first case, the default "idling program" #(ps,#(rs)) is run and the interpreter exits as soon as everything input until the first meta character (' by default) is executed and evaluated. In the second case, the script file is read and executed directly, with command line parameters passed to the special form names (see below).

#Main differences from the T-64 standard

• the ps (print string) primitive can accept multiple arguments (concatenating them on the output);
• default call results can be neutral and don't differ from explicit call results in any way;
• up to 255 segment ordinals are supported (from 1 to 255);
• extended operation mode (#(mo,E)) is the default one;
• arithmetic primitives operate on 63-bit signed integers (if the target architecture allows, otherwise it's 31-bit signed integers) and accept numbers in any base supported by C's strtoll function in base autodetection mode (i.e. decimal, octal and hexadecimal) but they don't support prepending any string prefixes to the output and always return the result in base-10;
• in arithmetic primitives, overflow argument is fully optional (in this case, a null value is returned if an overflow occurs);
• all bitwise primitive results are returned in base-10 as well and truncated to unsigned 32-bit values, and br bit rotations are also done on 32 bits width;
• form storage primitives (fb, sb, eb) directly accept a filename instead of a form name with the address (like in Nat Kuhn's Trac-in-Python);
• the trace mode (tn, tf) is fully non-interactive and just prints out every function run into stderr, also it doesn't trace the tn, tf and hl primitives call;
• other diagnostic functions (ln, pf) output to stdout;
• 9 new primitives have been added (see below).

#Original T-64 primitives implementation status

#New primitives

• bx: bitwise XOR. 3 arguments: #(bx,A,B). Returns the operation result. Invocation is the same as for the bi or bu primitives.
• ac: ASCII code. 2 arguments: #(ac,S). Returns the numeric unsigned value of the first character in S.
• av: ASCII value. 2 arguments: #(av,N). Returns the single byte corresponding to the ASCII code N (unsigned).
• fn: format number. 3 arguments: #(fn,fmt,N). Returns the sprintf-formatted string representation of the number N according to the format fmt.
• sf: store (raw) file. 3 arguments: #(sf,fname,form). Stores the raw value from form into a named file. The value is always written in its entirety (the form pointer is ignored) and segment gap bytes, if there are any, are written "as is". Returns a null value. The form doesn't get deleted from the internal form storage. The file is fully overwritten if it already exists.
• ff: fetch (raw) file. 3 arguments: #(ff,fname,form). Reads a raw string from the named file into form. Returns null value (check the target form afterwards).
• tm: local/UTC/Epoch time. 2 or 3 arguments: #(tl,fmt[,U]). Returns the local (or UTC, if the third parameter U is specified) time formatted according to the strftime-compatible fmt string or E format. If the format string is just E (Epoch), returns the amount of seconds since 00:00:00 UTC, January 1, 1970.
• rn: random number. 3 arguments: #(rn,n1,n2). Returns a (pseudo-)random integer number in the range n1 (included) to n2 (not included). Implemented using the double-pass xorshift64* algorithm.
• os: run an OS command. 2 arguments: #(os,cmd). Runs a command in the external OS shell (the one determined by the system() C call) and returns the command exit code. The output is not captured.

For self-contained nntrac environments that have no external shell (or the shell is nntrac itself), you can disable the os primitive by building nntrac with the -DNNT_NO_EXTSHELL flag.

#Modes

The nntrac processor can run in one of the three modes that can be switched with the mo primitive:

• E (extended): all primitives are available, including the custom ones — this mode is the default one (unlike the original spec);
• L (legacy): only the original 34 primitives from T-64 standard are available, no (built-in) extensions are permitted;
• S (secure): all primitives are available except those that can interact with the filesystem and outside operating environment (sb, fb, eb, sf, ff, os).

To lock the mode set with #(mo,L) or #(mo,S) until the end of the program, use the third L parameter (#(mo,S,L) or #(mo,L,L)). This way, no code inside will be able to extend nntrac's privileges back to unsafe level.

#Accessing command-line parameters from nntrac scripts

On normal script invocation (nntrac script.trac [param1 param2 ...]), nntrac automatically creates two forms: nnt-argc and nnt-argv. The nnt-argc form is a number containing the amount of command-line parameters (the script file name + everything after it, akin to Python). The nnt-argv form contains the parameters themselves and already is segmented so that you can use the cs primitive for easier parameter access.

#Embedding nntrac into your projects

Besides being lightweight, nntrac is also fully embeddable. You can use it as the smallest scripting engine that can be tailored for the specific needs of your own software.

#Invoking nntrac from other C code

Place nntrac.c and nntrac-embed.h files inside your project. In your C source code, append #include "nntrac-embed.h" to the top. Then, the following prototypes are available to you:

• void nnt_init(): allocate the forms and primitives storage, register the basic primitives and prepare the engine for work. You must start every session with the nnt_init(); call before being able to call other functions in this list.
• void nnt_regprimitive(const char *name, void *handler): register your own primitive function to the nntrac interpreter. See below for details.
• void nnt_proc(char *prog, unsigned int len): run a script contained in the string prog of length len. Any #(hl) call will exit this function.
• void nnt_finish(): free all forms and primitive function resources. Must be called when you no longer need the nntrac engine.

Then, you must build your project along with the nntrac.c file with the -DNNT_EMBED compiler flag. This flag disables the main() function in the nntrac source code itself.

#Extending nntrac with your own primitives

For your project scripting needs, you might have to introduce your own primitive functions to nntrac. First, define your functions according to the following prototype: char* handler(char *arglist, char *res, int *reslen);, and your handler must do two things to be a valid primitive: return the res pointer back and, if necessary, update the *reslen field, which is 0 by default, with the actual result string length. Also, to resize the res buffer, you must only use realloc! Doing otherwise will eventually lead to segfaults or memory leaks.

E.g. the function pr_custom might look like this:

char* pr_custom(char *arglist, char *res, int *reslen) {
  /* ...some actions that update the result string... */
  *reslen = strlen(res);
  return res;
}

Then, in your main code, somewhere between the calls to nnt_init and nnt_proc, you register the pointer to your primitive function with the name of your choice using the nnt_regprimitive call:

nnt_init();
/* ... */
nnt_regprimitive("my-custom", &pr_custom);

And the #(my-custom) call becomes available in your nntrac script code.

Now, how do we process the function arguments in our custom primitive definition? The arglist parameter is a string of function arguments (starting with the registered primitive name itself) delimited with a special NNT_ADEL character. For usage with strtok C function, it's more convenient to use a predefined null-terminated string with the same delimiter, called NNT_ADEL_S. Both NNT_ADEL and NNT_ADEL_S definitions are available in the nntrac-embed.h header, as well as the inclusion of stdlib.h and string.h for your convenience.

Here's an example of how we would implement some RGB light API for nntrac, returning the status:

char *pr_rgbled(char *arglist, char *res, int *reslen) {
  char *arg = strtok(arglist, NNT_ADEL_S), *r, *g, *b;
  r = strtok(NULL, NNT_ADEL_S); /* get the first parameter */
  g = strtok(NULL, NNT_ADEL_S); /* get the second parameter */
  b = strtok(NULL, NNT_ADEL_S); /* get the third parameter */
  if(r != NULL && g != NULL && b != NULL) { /* all read successfully */
    int val_r = atoi(r), val_g = atoi(g), val_b = atoi(b); /* convert to int */
    rgbled_set_lights(val_r, val_g, val_b); /* call your internal API */
    rgbled_get_lights(&val_r, &val_g, &val_b); /* read back the status */
    char *fmt = "R=%d, G=%d, B=%d\n"; /* set the formatting string */
    /* estimate the size and initialize the resulting buffer */
    res = realloc(res, (*reslen) = 1 + snprintf(NULL, 0, fmt, val_r, val_g, val_b));
    memset(res, 0, *reslen); /* zero it out */
    snprintf(res, *reslen, fmt, val_r, val_g, val_b); /* render */
    res = realloc(res, (*reslen) = strlen(res)); /* resize to the actual written size */
  }
  return res; /* return the result pointer */
}

Then you can register this primitive with nnt_regprimitive("rgb", &pr_rgbled); in your main C code, and then, calling ##(rgb,43,67,133) in your script will return the string R=43, G=67, B=133 if the API succeeds.

#FAQ

#Why reimplement TRAC and not another scripting language?

Because this is probably the only functional scripting language that can be fully, and even with some useful extensions, be implemented in under 1000 SLOC of ANSI C in a truly portable manner. Besides, C implementations of other embeddable scripting languages are easy to find and pick up, but for TRAC, at the time of nntrac creation, there existed nothing like that except a GPL-ed T-84 version that's hard to build with any modern C compiler.

#Why was T-64 standard chosen as the basis, not T-84 or T2001?

While having more "batteries included", T-84/T2001 had diverged from the original elegant design by switching to name suffixes to decide what to do with the function return value. This is much less flexible and less convenient for large-scale programs. T-64, on the other hand, can be easily extended (when really necessary) to do all the same things as T-84 allowed out of the box without sacrificing its core simplicity and flexibility.

#Is nntrac binary-safe?

In general, no. All nntrac programs are expected to not contain null bytes and the bytes from 248 to 255. Since nntrac, like all other TRAC dialects, is fully homoiconic and any piece of data can be treated as code, your data must not contain these bytes either. Emitting bytes with these values using the av primitive can and most probably will result in undefined behavior.

To process arbitrary binary data in nntrac script, it is mandatory to convert it into readable format (like hex or dec) with external tools (like od or xxd) before feeding it to the script. The nntrac interpreter contains all features required for your script to be able to process this kind of data.

#Is nntrac UTF-8-safe?

Mostly. All the internal meta characters are chosen so that they never occur in any valid UTF-8 sequence. All primitives, however, operate on individual bytes, so the primitives that allow you to input/output/manipulate a single byte or some numbered bytes are not UTF-8-safe. These include rc, cm, cc, cn, ac and av primitives.

#Why do rc and rs primitives require pressing Return (Enter) even after the metacharacter (') was entered?

They don't require it, your OS does. If you absolutely need per-character input then you need to set your terminal into the unbuffered input mode. For Unix-like systems, it can be done using a wrapper shell script with stty command.

#Why doesn't the os primitive capture the shell command output?

Because there is no truly portable way to do this. For capturing the output, it's recommended to redirect the command into a file (usually with > or >> shell operator) and then read the file contents with the ff primitive.

#Credits

Implemented by Luxferre in 2023, released into public domain with no warranty.

Based on the original specification according to "Definition and Standard for TRAC T-64 Language" by Calvin N. Mooers (1972).