1. Overview
The Sym language is a very simple, lightweight stack-based programming language. Programs are written using numbers and symbols, and operations are performed on a stack.
This document describes how to use the Sym language, its instruction set, simple sample code, and examples of its applications.
2. Getting Started
Here are the basic steps to write your first program using the language.
2.1 Installation
Installation using Cargo
Sym is written in Rust and can be installed using Cargo. Run the following command to install it:
cargo install sym-lang
2.2 Hello World
As your first coding exercise in the Sym language, let's write a program that prints "Hello World".
10 13 100 108 114 111 87 32 111 108 108 101 72
13
& ! 1 - @ ~3
This code looks a bit complicated, but we'll break it down step by step. First, let's convert this code into a more understandable form.
`n` `\` `d` `l` `r` `o` `W` ` ` ` `o` `l` `l` `e` `H`
13
swap out 1 - dup jnz(3)
First, the premise is that the Sym language separates commands with spaces and newlines.
Line 1 Numbers are lined up. In the Sym language, only numbers (0 to 255) can be treated as data. Numbers can be pushed onto the stack by writing them as they are.
In the Sym language, there are no characters or strings, and ascii codes are handled in decimal notation.
These numbers are decimal ascii, and "Hello World\n" is pushed in reverse.
Also, the first 10 13 is a newline character.
Note: Characters, strings, and reverse operations are scheduled to be added in version 1.1.0.
Line 2 The number 13 is pushed onto the stack. This is the length of the string to be output. It will be used for loop control in later processing.
Line 3 The third line performs the process to output characters one by one. I will explain it step by step.
- &(swap): Swaps the number 13 (length of string) at the top of the stack with the first character 'H' (72) below it. This allows the next command to output a character.
- !(out): Outputs the character 'H' (72) at the top of the stack as ASCII.
- 1 -: Since one character has been output, subtract 1 from the length of the string. This will allow the remaining string to be known the next time the loop is performed.
- @(dup): Copies the value at the top of the stack that is the length of the string after subtraction. This value is used for the next command.
- ~3(jnz(3)) : If the value on the top of the stack is not 0, jump to the third line. This will cause the loop to repeat until the entire string has been printed.
3. Syntax Overview
Sym language commands are divided into six categories: stack operations, arithmetic operations, comparison, control flow, input/output, and debugging.
3.1 Stack Operations
Sym language uses a stack to manipulate data. Below are the commands related to stack operations.
| Command | Description | Usage example |
|---|---|---|
_ | Remove the value at the top of the stack. | _ |
@ | Copy the value at the top of the stack. | @ |
& | Swap the two values at the top of the stack. | & |
n | Push n onto the stack (e.g. 10). | 10 |
3.2 Arithmetic Operations
Sym language allows basic arithmetic operations to be performed on numbers in the stack. Arithmetic commands use the value at the top of the stack to perform operations.
| Command | Description | Example |
|---|---|---|
+ | Add the two values on the top of the stack. | + |
- | Subtract the two values on the top of the stack. | - |
* | Multiply the two values on the top of the stack. | * |
/ | Divide the two values on the top of the stack. | / |
% | Calculate the remainder of the two values on the top of the stack. | % |
3.3 Comparison Operations
The Sym language provides instructions for comparing values. These instructions compare the values on the top of the stack and push the result onto the stack (1 or 0).
| Command | Description | Example |
|---|---|---|
= | Compare whether the two values on the top of the stack are equal. | = |
> | Is the top value of the stack greater than the second value? | > |
< | Is the top value of the stack less than the second value? | < |
3.4 Control Flow
Control flow commands allow you to branch program execution. They allow you to jump or loop based on certain conditions.
| Command | Description | Usage example |
|---|---|---|
^n | Unconditionally jump to the specified line number n. | ^10 |
|n | If the top of the stack is 0, jump to line number n. | |10 |
~n | If the top of the stack is not 0, jump to line number n. | ~10 |
; | Stop the program. | ; |
3.5 Input/Output
The Sym language provides basic input/output commands. These allow you to receive values from standard input and display values on standard output.
| Command | Description | Example |
|---|---|---|
? | Receive a single value from standard input and push it onto the stack. | ? |
! | Print the top value on the stack to standard output. | ! |
3.6 Debugging
There are also several debugging commands. You can check the state of the stack while the program is running, and input and output debugging information.
| Command | Description | Example |
|---|---|---|
$? | Receive a number from standard input and push it onto the stack. | $? |
$! | Print the top value on the stack for debugging purposes. | $! |
3.7 Comments
A line is a comment only if the first character of the line is #.
The Sym language instruction set is designed to be simple and intuitive. Understanding these basic instructions will give you the foundations of programming in the Sym language.
4. Usage Examples
4.1 Down Counter
100
@ $! 1 - @ ~2
10 13 ! !
4.2 Up Counter
0
@ $! 1 + @ 100 > |2
10 13 ! !
4.3 Greeter
10 13 100 108 114 111 87 32 111 108 108 101 72
13
& ! 1 - @ ~3
5. Application Example
5.1 Fizz Buzz
0
@ 15 % |8
@ 5 % |9
@ 3 % |10
^12
122 122 117 66 122 122 105 70 8 ^13
122 122 117 66 4 ^13
122 122 105 70 4 ^13
@ $! ^16
& ! 1 - @ ~13
_
32 ! 1 + @ 20 > |3
10 13 ! !