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:

import "math";
from "math" import "answer";

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).

Builtins

User-facing builtins:

• input / tupni
• 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?)

__read_file / __write_file / __delete_file are blocked unless --allow-fs is passed.
__http_request is blocked unless --allow-net 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>
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)

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:

• http.request(method, url, body)
• http.get(url)
• http.post(url, body)
• http.status(url)

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.

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).