luxferre/nntrac
1
0
Fork 0
Code Actions Activity

initial upload

Browse Source
This commit is contained in:
Luxferre
2023-08-09 21:41:34 +03:00
commit 255ba2c015
3 changed files with 1392 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
COPYING
+24
View File
@@ -0,0 +1,24 @@
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.
In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
For more information, please refer to <https://unlicense.org>
README.md
+192
View File
@@ -0,0 +1,192 @@
# 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 feature 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
### 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
Name|Args|Implemented?|UTF-8 safe?|Meaning
----|----|------------|-----------|-------
`rs`|1 |yes |yes |Read string
`rc`|1 |yes |no |Read char
`cm`|2 |yes |no |Change meta
`ps`|var |yes |yes |Print string
`ds`|3 |yes |yes |Define string
`dd`|var |yes |yes |Delete definition
`da`|1 |yes |yes |Delete all
`ss`|var |yes |yes |Segment string
`cl`|var |yes |yes |Call string
`cs`|3 |yes |yes |Call segment
`cc`|3 |yes |no |Call character
`cn`|4 |yes |no |Call N characters
`cr`|2 |yes |yes |Call [pointer] restore
`in`|4 |yes |yes |Initial
`eq`|5 |yes |yes |String equality
`gr`|5 |yes |yes |Greater than
`ad`|3, 4|yes |yes |Add
`su`|3, 4|yes |yes |Subtract
`ml`|3, 4|yes |yes |Multiply
`dv`|3, 4|yes |yes |Divide
`bu`|3 |yes |yes |Bitwise union (OR)
`bi`|3 |yes |yes |Bitwise intersection (AND)
`bc`|2 |yes |yes |Bitwise complement (NOT)
`br`|3 |yes |yes |Bitwise rotation
`bs`|3 |yes |yes |Bitwise shift
`sb`|var |yes |yes |Store block (file): `#(sb,fname,f1,f2...)`
`fb`|2 |yes |yes |Fetch block (file): `#(fb,fname)`
`eb`|2 |yes |yes |Erase block (file): `#(eb,fname)`
`ln`|2 |yes |yes |List names
`pf`|2 |yes |yes |Print form
`tn`|1 |yes |yes |Trace on
`tf`|1 |yes |yes |Trace off
`hl`|1 |yes |yes |Halt
`mo`|2, 3|yes |yes |Mode (see below)
### 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 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 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"](http://web.archive.org/web/20040531054816/http://tracfoundation.org/trac64/docs/T64definition.pdf) by Calvin N. Mooers (1972).
nntrac.c
+1176
View File
File diff suppressed because it is too large Load Diff