TFEL

tfel is a deliberately cursed programming language runtime.

This project is a joke, on purpose. If you open TFEL code and your first reaction is "what is going on?", the design is working.

For the full design rant and spec, read TFEL_LANGUAGE_SPEC.md.

What TFEL does to your brain

• Execution order is upside down.
• Brackets are mirrored.
• Assignment is reversed.
• Many keywords are reversed.
• It is internally consistent enough to be usable, which is the worst part.

Quick start

cargo run -- examples/hello.tfel

Run logical (non-mirrored) TFEL directly:

cargo run -- --logical examples/hello.logical.tfel

Mirror a logical file into on-disk .tfel form:

cargo run -- mirror program.logical.tfel program.tfel

How code is processed

TFEL source files are intentionally stored in a mirrored form.

When you run a file, the runtime does this:

1. Reverse every line.
2. Reverse line order.
3. Tokenize with swapped brackets.
4. Parse and evaluate.

That means there are two views of TFEL:

• Logical TFEL syntax: what the parser effectively sees after preprocessing.
• On-disk TFEL syntax: the weird mirrored text in .tfel files.

Practical writing workflow

Write code in logical TFEL first, then mirror it into a .tfel file:

cargo run -- mirror program.logical.tfel program.tfel
cargo run -- program.tfel

You can also skip mirroring and run logical TFEL directly:

cargo run -- --logical program.logical.tfel

Logical TFEL syntax guide

Everything below is shown in logical syntax (after preprocessing).

Variables and assignment

10 = x;
"hello" = msg;

tel is the strict declaration keyword:

tel x = 10;

let exists for compatibility (disabled in --strict-tfel mode):

let x = 10;

Print

print)"hello"(;
print)msg(;

Conditions

if)x > 0(} print)"positive"(; { else } print)"zero or negative"(; {

Loops

elihw)i < 5(} i + 1 = i; {
rof item ni range)0, 3(} print)item(; {

Loop control:

kaerb;
eunitnoc;

Comparisons include <= and >=.

Functions

fed add)a, b(} nruter a + b; {
add)2, 3(;

Objects (maps)

}"name": "tfel", count: 2{ = user;
user]"name"[;

Object keys support quoted strings and bare identifiers. Indexing objects requires a string key.

String interpolation

10 = n;
"fib(${n}) => ${n + 1}";

Imports

"math" tropmi;
"answer" morf "math" tropmi;
lib/file tropmi;

Aliases also work:

"answer" morf "math" tropmi;

Note the shape: the module atom comes first, the keyword last — English keyword spellings are accepted outside --strict-tfel, but the position is not). import "math"; is not valid logical syntax.

In --strict-tfel mode, only mirrored keywords are accepted (tropmi, morf).

Import-all exposes module namespace aliases too:

lib/emit tropmi;
emit.lamron)(;

Exports

Modules can define explicit exports:

tropxe answer, format;
40 = answer;

If no tropxe statement is present, all non-builtin top-level names are exported (legacy behavior).

vNext — NEW SYNTAX DESIGN (agreed,, not implemented)

Tracked in TFEL_LANGUAGE_SPEC.md §4.8 — the full redesign of the syntax,, frozen as a design agreement,, awaiting implementation. The one rule:values first,, operation last — every operation consumes the expression to its right.

• Declarations are normal: int x = 10; string message = "…";
• Assignment is normal direction: x = value; [0] xs = value; ["name"] user = "Bob";
• Calls are postfix: (a,, b)add; ("hello")print;
• Indexing/field access is prefix: [0] numbers [-1] numbers (second element),, ["name"] user; chain freely: ["name"] ["profile"] user
• Control-flow bodies live ABOVE their condition/iteration expr: { BODY } (cond)if; { BODY } (item in col)for; { BODY } (cond)while;
• Functions: body above signature: { ... } fn add(int a,, int b);
• Replacements: tel→typed decl,, fed→fn,, nruter→return,, eurt→true,, etc.
• Execution direction stays bottom-to-top — that is the point.

Open grammar items,, tracked in spec §8.

Builtins

User-facing builtins:

• input / tupni
• args / sgra — script arguments as an array of strings (interpreter: everything after the script path; compiled binaries: argv[1..])
• len / nel
• to_number / rebmun_ot
• range / egnar
• type_of / fo_epyt
• to_string / gnirts_ot

Internal primitives used by libraries:

• time/date: __emit_time, __lamron_time, __etad_today
• file I/O: __read_file, __write_file, __delete_file
• network: __http_request(method, url, body?) (response body), __http_status(method, url, body?) (numeric status code)
• C FFI (Unix, --allow-run): __c_load(path) → handle int, __c_call(handle, symbol, ret, argtypes, args) → any, __c_unload(handle) → bool. Type tags: "int", "double", "string", plus "void" for returns. Fixed-arity (max 4 args), non-variadic only; a wrong signature is C-level undefined behavior. See examples/ffi_demo.tfel.

__read_file / __write_file / __delete_file are blocked unless --allow-fs is passed.
__http_request / __http_status are blocked unless --allow-net is passed. __run_command and the C FFI are blocked unless --allow-run is passed. When embedding TFEL as a library, runtime permissions default to restricted (fs/network off) unless you explicitly enable them in EvaluatorOptions.

CLI modes

cargo run -- [--logical] [--strict-tfel] [--allow-fs] [--allow-net] [--module-path <dir>]... <path> [script-args...]
cargo run -- mirror <logical-input> <mirrored-output>

• --logical: parse input as logical TFEL (skip mirror preprocessing)
• --strict-tfel: disable compatibility syntax and require explicit declarations before assignment
• --allow-fs: enable filesystem builtins
• --allow-net: enable network builtin
• --module-path <dir>: add extra module search directories for imports (repeatable)

Building native binaries

tfel build is not available in this version: only the interpreter is shipped. (tfel build ... exits with a message saying so.)

Libraries in this repo

Local library examples:

• examples/lib/emit.tfel
• examples/lib/file.tfel

External-style library examples:

• examples/lit/http/client.tfel
• examples/lit/http/index.tfel

Why lit and not lib? I typo'd the folder name, laughed, and promoted the typo to official TFEL canon.

lit/http API (import what you need, e.g. "get" from "lit/http" import;):

• request(method, url, body) — response body string
• get(url) — response body string
• post(url, body) — response body string
• status(url) — numeric status code (its own request)

Notes:

• HTTP is done with raw TCP in the runtime.
• HTTPS is done via system openssl s_client (no Rust HTTP/TLS dependency crate).

Example programs

Run all top-level examples with expected-failure classification:

./scripts/run_examples.sh

Recommended first real example:

cargo run -- examples/weekly_report_showcase.tfel

A more real-world-ish mini project:

cargo run -- examples/service_health_report.tfel

Network + filesystem showpiece:

cargo run -- --allow-net --allow-fs examples/service_health_reporter.tfel

examples/http_demo.tfel, examples/api_request_demo.tfel, and examples/service_health_reporter.tfel default to offline-safe mode. Set run_network = true / run_live_checks = true inside those files for live requests.

cargo run -- examples/hello.tfel
cargo run -- examples/fibonacci.tfel
cargo run -- examples/cursed_demo.tfel
cargo run -- examples/complex_logic.tfel
cargo run -- examples/random_gen.tfel
cargo run -- examples/if_else_demo.tfel
cargo run -- examples/complex_branch_chain.tfel
cargo run -- examples/function_add.tfel
cargo run -- examples/closure_demo.tfel
cargo run -- examples/input_demo.tfel
cargo run -- examples/while_sum.tfel
cargo run -- examples/for_range_sum.tfel
cargo run -- examples/while_print_1_to_100.tfel
cargo run -- examples/builtins_demo.tfel
cargo run -- examples/import_all_demo.tfel
cargo run -- examples/from_import_demo.tfel
cargo run -- examples/import_lib_lint_sat_demo.tfel
cargo run -- examples/indexing_demo.tfel
cargo run -- examples/types_demo.tfel
cargo run -- examples/emit_demo.tfel
cargo run -- examples/emit_normal_demo.tfel
cargo run -- examples/file_demo.tfel
cargo run -- examples/weekly_report_showcase.tfel
cargo run -- examples/service_health_report.tfel
cargo run -- --allow-net --allow-fs examples/service_health_reporter.tfel
cargo run -- examples/http_demo.tfel
cargo run -- examples/api_request_demo.tfel

Intentional error demos:

cargo run -- examples/error_hint_demo.tfel
cargo run -- examples/error_context_demo.tfel

Maintainer note

This is a fun side project. Some parts are fully vib-coded, some parts are manual, and fixes are mixed too.

There is no support commitment and no guaranteed roadmap. If I feel like adding something because it is fun or I want to learn it, I will add it. If not, I will not.

Like many side projects, I may forget about this in a month or two.

Final warning

TFEL is here to teach interpreter architecture while politely attacking every coding instinct you have.

Dependency policy

TFEL stays deliberately minimal on dependencies:

• The Rust crate has zero third-party dependencies, and Cargo.lock should stay dependency-free.
• HTTP uses raw TCP sockets and HTTPS shells out to the system openssl s_client — no HTTP/TLS crates.
• tfel build shells out to the system C compiler instead of embedding a compiler-as-a-library crate.

New dependencies need a very good reason, and preferably a joke attached.

Development checks

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

Editor support

A lightweight VS Code syntax package lives at:

editors/vscode-tfel

It includes TextMate highlighting plus a minimal language-server stub (hover + heuristic parse diagnostics).

Local install instructions are in:

editors/vscode-tfel/README.md

License

Apache-2.0 (LICENSE).