frendsick / torth

Stack based programming language

Torth

Stack based programming language inspired by Porth that uses Reverse Polish notation.

• Compiled
• Statically typed
• Native (Linux x86_64)
• Stack-based (just like Porth)
• Turing complete
• Self-hosted

Documentation

• Getting started
• Intrinsics
• Keywords
• Types
• Control flow statements
• Syntax highlighting

Usage

$ cat hello.torth
include "std"
function main :
  "Hello, World!\n" puts
end
$ ./torth -r hello.torth
Hello, World!
$ ./torth --help
Usage: ./torth [-h] [--out FILE] [-r] [-s] [-v] code_file

Torth compiler

Positional arguments:
  code_file             Input file

Options:
  -h                    Show this help message and exit
  --out FILE            Output file
  -r                    Run program after compilation
  -s                    Save files generated during compilation
  -v                    Output compilation steps

Examples

More examples are found from the examples-folder.

Hello World

include "std"
function main :
    "Hello, World!\n" puts
end

FizzBuzz

// === FIZZBUZZ ===
// Print integers 1 to N with some exceptions:
// => Print “Fizz” if an integer is divisible by 3
// => Print “Buzz” if an integer is divisible by 5
// => Print “FizzBuzz” if an integer is divisible by both 3 and 5

// The standard library implements common functions, for example:
// puts => Output string
// %    => Modulo-operator
include "std"

// Returns the sum of numbers not divisible by 3 or 5
function FizzBuzz limit:int -> int :
    // Push the initial values to stack
    0   // sum
    1   // index

    // Save two topmost values from the stack to variables
    // => TAKE keyword also removes the values from the stack
    // => PEEK keyword would instead save the values without removing them from the stack
    take index sum in

    // Loop while index <= limit
    WHILE index limit <= DO

        // Newlines inside IF condition are just for readability
        // => The whole program could be in one line
        IF
            index 3 % 0 ==
            index 5 % 0 ==
            &&
        DO
            "FizzBuzz\n" puts
        ELIF index 3 % 0 == DO
            "Fizz\n" puts
        ELIF index 5 % 0 == DO
            "Buzz\n" puts
        ELSE
            // Print the current index
            index putu "\n" puts

            // Add index to sum
            sum index + sum =
        ENDIF

        // Increment loop's index
        index 1 + index =
    DONE
    sum // Return sum
end

// Program execution starts from MAIN function (case-insensitive)
function main :
    // Call FizzBuzz with one integer parameter
    // FizzBuzz(limit=30)
    30 FizzBuzz

    // Save the return value to variable called sum and print it with text
    take sum in
    "Sum of all numbers not divisible by 3 or 5: " puts
    sum putu "\n" puts
end

torth's Issues

Implement type checking

Type checking of sorts were implemented in compiler/program.py inside function type_check_program using compile-time virtual stack. That stack however were not enough to provide accurate enough type checking for programs with different kinds of control clauses (IF, WHILE) or functions. Type checking should be re-implemented so that it takes code branching properly into account.

Document intrinsics

Document at least this information from intrinsics:

• Name
• Description
• Python meta code
• Assembly code

Document classes

Add documentation on how to use the CLASS keyword and create objects.

[BUG] Compiler cannot compile itself after fixing recursion

Describe the bug
The Torth compiler cannot compile itself with the compiler version merged in PR #58, which enabled using recursion by introducing proper local variables to functions. The compiler version can compile any other known programs but itself correctly.

To Reproduce
Steps to reproduce the behavior:

1. Compile the bootstrap compiler: make
2. Compile the Torth compiler with the bootstrapped compiler: ./torth torth.torth
3. Compile the Torth compiler again ./torth torth.torth
4. After that the current torth executable is unable to compile any other programs due to segfault

Expected behavior
The Torth compiler should be able to compile itself again and again.

Screenshots

Additional context
This issue was introduced when function recursion was implemented in PR #58

Implement type checking for function parameters and return types

At the moment the language does not care about the function parameter and return types or even how many of them are there. Implement type checking for function signatures to ensure the function takes and returns the expected types.

[BUG] Function parameter and variable values are shared between recursive function calls

Describe the bug
Function parameter and variable values are shared between recursive function calls. This is a problem, at least if the function has multiple recursive calls to itself. This happens because each function's function parameters and variables are statically named memory locations.

To Reproduce
Steps to reproduce the behavior:

1. Compile and run the example program below ./torth -r fibonacci.torth
2. It prints wrong values to both its parameter num and the variable variable

include "std"
function Fib num:int -> int :
  NULL take variable in
  if num 1 <= do num return endif

  num 1 - Fib
  1337 variable =
  num 2 - Fib +

  // Expected variable value: 1337
  // Got: NULL
  "Variable value is: " puts
  variable print "\n" puts
end

function main :
  // Expected: 55
  // Got: 18446744073709551536
  10 Fib print
end

Expected behavior
Variables and function parameters should be separate for each recursive function call.

Screenshots

The output of the example program

The function parameters and variables are statically named memory locations in Assembly.

Additional context
We would need a way to have parameters that are not statically named in the assembly. For example, in C, this is done by pushing each variable to the stack, but I am not sure if that is feasible in the already stack-based language. Maybe?

Allow calling a macro from within another macro

Make it possible to call a macro from within another macro

[BUG] Compiler gives incorrect errors when a file does not exist

Describe the bug
The compiler gives ambiguous error messages when the file given to the compiler as code_file parameter does not exist. The error message indicates that the file could not be included, which is kinda true, but it would be better just to tell the user that the file does not exist.

To Reproduce
Steps to reproduce the behavior:

• Try to compile a file that does not exist that has any other file extension than '.torth'
  ./torth nonexistent.txt
• Compiler gives the following error message:

Compiler Error UNSUPPORTED_FILE_EXTENSION:
File 'nonexistent.txt' has unsupported file extension
Only .torth files are supported

• Try to compile a file that does not exist that has the '.torth' file extension
  ./torth nonexistent.torth
• Compiler gives the following error message:

Compiler Error INCLUDE_ERROR:
File 'nonexistent.torth' cannot be included.

Expected behavior
In both above cases, the compiler should indicate that compiling the file fails because the file is not found. The error message could be something like the following:

Compiler Error FILE_NOT_FOUND:
File 'nonexistent.txt' is not found

Screenshots

Document libraries

Document at least the following information from libraries:

• Name
• Description
• Included functions, constants, memories, etc and their descriptions
  • Probably no need to document the function contents anywhere else than in the code