Basalt is a minimalist stack-oriented programming language designed to teach the fundamentals of stack-based computing. No parentheses. No indentation. No noise — just the pure mechanics of a stack.
Basalt strips programming down to its raw fundamentals. Every operation is an explicit manipulation of a single data structure — the stack. There are no hidden abstractions, no syntactic sugar hiding complexity. What you see is exactly what the interpreter executes.
Written in Python 3 with a custom-built Lexer and Parser, Basalt is fully open source. You can read every line of the interpreter and trace exactly how your code is processed — from raw text to executed output.
Get Basalt running on your machine in under a minute. All you need is Python 3.
Make sure you have Python 3 installed on your system. Download it from python.org if you haven't already.
Download the repository as a .zip archive from GitHub and extract it to a folder of your choice.
Navigate to the Basalt folder and run a .b file using the interpreter. See the example on the right.
Look through the tests/ folder for example programs. Modify them, break them, and learn how the stack works.
# Navigate to the basalt directory cd basalt # Run a Basalt program python main.py tests/math.b # Output: 49
# Push two numbers and add them 7 42 + print # Output: 49
Every operation in Basalt interacts directly with the stack. Click a category to explore its operations in detail.
Core stack manipulation: push, pop, duplicate, swap, and more. The foundation of every Basalt program.
Arithmetic and comparison operators that pop operands from the stack, compute a result, and push it back.
Print values to stdout, read user input, and interact with the outside world from within your stack program.
Conditionals, loops, and user-defined functions. Control the direction of execution using stack values.
Manipulate text: concatenation, length, and string conversion utilities built into the language.
| Operation | Stack Effect | Description |
|---|---|---|
| push <val> | → [val] | Push a literal value onto the top of the stack. Numbers and strings can be pushed directly by writing them. |
| pop | [a] → | Remove the top element from the stack and discard it. |
| dup | [a] → [a a] | Duplicate the top element of the stack. |
| swap | [a b] → [b a] | Swap the top two elements on the stack. |
| over | [a b] → [a b a] | Copy the second element to the top of the stack. |
| rot | [a b c] → [b c a] | Rotate the top three elements, bringing the third to the top. |
| Operation | Stack Effect | Description |
|---|---|---|
| + | [a b] → [a+b] | Pop two values, push their sum. |
| - | [a b] → [a−b] | Pop two values, push their difference (second minus top). |
| * | [a b] → [a×b] | Pop two values, push their product. |
| / | [a b] → [a÷b] | Pop two values, push integer division result. |
| % | [a b] → [a%b] | Pop two values, push the modulo (remainder). |
| == | [a b] → [0|1] | Push 1 if the top two values are equal, 0 otherwise. |
| < | [a b] → [0|1] | Push 1 if second is less than top, 0 otherwise. |
| > | [a b] → [0|1] | Push 1 if second is greater than top, 0 otherwise. |
| Operation | Stack Effect | Description |
|---|---|---|
| [a] → | Pop the top value and print it to standard output. | |
| println | [a] → | Pop the top value and print it followed by a newline. |
| input | → [str] | Read a line of text from standard input and push it onto the stack. |
| Operation | Stack Effect | Description |
|---|---|---|
| if … else … end | [cond] → | Pop a condition. If truthy (non-zero), execute the if block; otherwise, execute the else block. |
| while … end | [cond] → | Repeatedly evaluate the condition and execute the body while it is truthy. |
| def name … end | — | Define a named function. The body between def and end runs when the function name is called. |
| name | varies | Call a previously defined function by name. The function operates on the current stack. |
| Operation | Stack Effect | Description |
|---|---|---|
| "text" | → [str] | A string literal. Anything enclosed in double quotes is pushed onto the stack as a string. |
| concat | [a b] → [ab] | Pop two strings and push their concatenation. |
| len | [str] → [n] | Pop a string, push its length as a number. |
| tostr | [a] → [str] | Convert the top value to its string representation. |
Basalt is built in Python 3 using a custom Lexer and Parser. The pipeline is intentionally simple so you can follow every step from source code to execution.
Your .b file is read as raw text
Tokenizes the source into a stream of tokens
Transforms tokens into an abstract syntax tree
Walks the AST and executes each node, managing the stack
Results are printed or the final stack state is returned
# The interpreter processes .b files through # the lexer → parser → interpreter pipeline # To view the actual implementation, check: # - src/lexer.py # - src/parser.py # - src/interpreter.py # - main.py (entry point)
Example programs demonstrating the core concepts of stack-based programming. Check the tests/ folder in the repo for more.
# Basic arithmetic operations # Numbers are pushed onto the stack, operators consume them 7 42 + print # → 49 100 37 - print # → 63 6 8 * print # → 48 144 12 / print # → 12 17 5 % print # → 2
Numbers are pushed onto the stack left-to-right. Operators pop their operands and push the result back. The print operation pops and displays the top value.
# Compute factorial recursively def factorial dup 1 > if dup 1 - factorial * else pop 1 end end # Compute 5! = 120 5 factorial print
Functions are defined with def name … end and called by name. This recursive factorial duplicates the value, checks if it's greater than 1, and recurses or returns 1.
# Demonstrate core stack operations 10 dup # stack: [10 10] print print # prints: 10, then 10 1 2 swap # stack: [2 1] print print # prints: 1, then 2 3 4 over # stack: [3 4 3] print print print # prints: 3, 4, 3 5 6 7 rot # stack: [6 7 5] print print print # prints: 5, 7, 6
dup copies the top, swap exchanges the top two, over copies the second element to the top, and rot rotates the top three. These are the building blocks of all stack manipulation.
Have a question, idea, or just want to say hi? We'd love to hear from you.