rbaltrusch / natscript

The Natscript interpreter, a custom programming language, with a natural English-like syntax.

Natscript Interpreter

This is Natscript, a custom cross-platform, dynamic interpreted language with a free, natural language-like syntax that lends itself to prosaic code, such as:

define function main as {
    set squares to []
    for each number in range from 0 to 5 not equal to 3 {
        multiply it by itself, then append it to squares
    }
    return squares
}

# This will output [0, 1, 4, 16] to the console
print result of call main

The main implementation of the Natscript interpreter is currently written in Python, but may be shifted to C++ in the future for improved performance.

Available functionality

Currently available functionality includes:

• variables and operations
• conditionals
• loops (for-each, while)
• first-order functions
• module declarations and imports
• access modifiers (private, constant)
• recursion
• a bytecode compiler to speed up module loading
• precise stack traces for run-time exceptions

Language documentation can be found in the doc folder.

Getting started

To get a copy of this repository, clone it using git, then install all dependencies (currently none), as well as the natscript package itself:

git clone https://github.com/rbaltrusch/natscript
cd natscript
python -m pip install -r requirements.txt
python -m pip install -e .

To run the interpreter, run the natscript Python package, specifying a Natscript file to be executed, or nothing to enter an interactive shell session:

python -m natscript
python -m natscript doc\examples\helloworld.nat

Syntax highlighting

Github / Linguist

Currently, Natscript is in its early stages and not supported yet by Linguist (which, e.g. provides the syntax highlighting on Github). Powershell syntax highlighting seems to be an acceptable alternative.

Visual Studio Code

Language support in VS Code is in work, but not available yet. An early-stage VS Code extension with static syntax highlighting can be found here, but at the moment needs to be manually added to the VS Code extensions folder.

Notepad++

The syntax highlighting file for Natscript in Notepad++ can be found here. It can be imported to Notepad++ in the Languages menu (Languages -> User Language -> Define Your Language... -> Import).

Documentation

Language documentation, including examples and tutorials, can be found in the doc folder. It is currently a work in progress.

Examples

Below is one example of the natural syntax of Natscript:

define function fibonacci expecting [limit] as {
    set old to 1
    set current to 1
    set numbers to [old current]

    while checked that current is less than the limit {
        set temp to current
        add old to current then set old to temp
        append current to numbers
    }
    return the numbers
}

define function main as {
    return result of call fibonacci with [1000000]
}

# prints all fibonacci numbers from 1 to 1000000
call main and print result

A full list of code examples can be found here.

Tutorials

Tutorials can be found in the doc folder.

Interpreter CLI

The Natscript interpreter CLI has several configureable options:

usage: natscript [-h] [--debug] [--compile COMPILE] [--compiled-format {pickle,json}]
                             [--iterations ITERATIONS]
                             filepath

CLI for the Natscript interpreter

positional arguments:
  filepath              The path of the Natscript file to be run

optional arguments:
  -h, --help            show this help message and exit
  --debug, -d           Enables the interpreter debug mode
  --compile COMPILE, -c COMPILE
                        Enables the bytecode compiler
  --compiled-format {pickle,json}, -f {pickle,json}
                        Specifies the format of the bytecode-compiled file
  --iterations ITERATIONS, -i ITERATIONS
                        Specifies how often the script should be executed

The interpreter CLI help message can be shown by running:

python -m natscript -h

Pyinstaller

Packaging the interpreter using pyinstaller can speed up execution time of Natscript code by a factor of 2x. Simply bundle it using the command:

pyinstaller -n natscript natscript/__main__.py

This will generate an executable file called natscript.exe (with the same CLI as the python package) in the dist/natscript folder.

C++ Implementation

The C++ implementation (work in progress) of the Natscript interpreter can be found here. This may be abandoned in the future in favour of LLVM-based JIT acceleration for the Python implementation of Natscript.

Contributions

Contributions are welcome! For more details, please read the contribution guidelines.

Python

Written in Python 3.8.3.

License

This repository is open-source software available under the MIT license.

Contact

Please raise an issue for code changes. To reach out, please send an email to [email protected].

natscript's Issues

Float values are not parsed properly

Float values in the example script example2.nat are not parsed properly, as source code strings, such as "1.5", are preprocessed by the lexer and split into three parts ("1", ".", "5"), which then cannot be recognized as a proper float value. As a result the script fails, as it contains an unexpected token (".").

To Reproduce

1. Run example2.nat
2. See error:

Traceback (most recent call last):

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\main.py", line 23, in <module>
!    tokens = list(lex.lex(file_contents))

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\lexer.py", line 16, in lex
!    token = self.token_factory.create_token(s)

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\token_.py", line 35, in create_token
-    raise exceptions.LexError(token, self.line_number)

LexError: Line 8: . was not expected at this time!

Expected behavior
Float values shouldnt be split by the preprocessing logic in the Lexer.

Occurs on main branch (commit 60a8bf9).

The bug should be caused by commit 96b8248.

A bug found when trying to execute conditionals.nat example

Describe the bug
Index out of range exception raised

To Reproduce
Steps to reproduce the behavior:

1. Copy examples\conditionals.nat to test.nat for proper executing
2. Run python interpreter\main.py
3. See error

Expected behavior
A character '6' printed to console was expected.

Screenshots

If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: Windows NT 10 Home
• Browser: I dont think this is needed.
• Version: current sources (trunk)

Smartphone (please complete the following information):
I don't think this is neded.

Additional context
I think that that the 1 should be replaced with -1 in this snippet:

        while self.token_stack and self.token_stack[1].satisfied:
            yield self.token_stack.pop()

(lines 39-40 in parse() in interpreter\parsing.py), because it works then and the rest of scripts that had worked before work too.

File I/O

The language currently does not support file input or output commands. Even simple file handling, such as open, read, write and close would significantly add to the usefulness and useability of the language.

Example implementation:

open example.txt and read it
close it

open example.txt as file
write my_data to file
close it

It would be ideal if files would automatically close once the file action is successfully done and the file handle is no longer needed (or an error occured), similar to how context managers work in Python.

Extending natscript wrapping for Python builtins

Accessing Python attributes of type builtin_function_or_method in natscript using wrapped Python objects does not work.

Language documentation

Currently there is no documentation of the language features, besides some example scripts.

Language features should be documented in the wiki to elaborate on the details of the language.

Blank lines throw errors

Extra blank lines between statements produce errors.

The following code runs fine:

set a to 1
print it

The following code throws an Interpreter error:

set a to 1
//(blank line)
print it
- InterpreterError: The following block had no type to be interpreted: Syntax Tree containing [Token(LINEBREAK, None), Token(PRINT, None)]!

Extra blank lines should not cause the interpreter to not be able to parse the *.nat file anymore and should instead be ignored.

Windows 10.

Input arguments and return values

Functions currently do not support input arguments or return values, which significantly limit their usefulness.

Function definitions should optionally include required input arguments or keyword arguments, e.g.

define function my_function taking arg1 and arg2 as {
...
}

Function calls should optionally include passed arguments, e.g.:

call my_function for arg1

Support lists and iteration

Currently, the language only supports scalar integer and float types. Lists and iteration through them via a for-loop, for-each or a map statement would significantly increase the flexibility and usefulness of the language.

Clauses do not have access to outer scopes

Inner scopes do not have access to variables defined in outer scopes. This makes it impossible to access global variables, define closures or even call a function inside another function defined elsewhere, e.g.

define function a as {
    print 1
}

define function b as {
    #this will fail because it doesnt have access to outer scope
    call a
}

To reproduce this example, run the following code, which assigns 1 to a global variable b, then tries to access this variable b to print it inside an inner scope.

set b to 1
set a to {print b} and call it

The example above results in the following exception:

Traceback (most recent call last):

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\main.py", line 25, in <module>
!    inter.interpret(syntax_block)

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\interpreter.py", line 26, in interpret
!    raise e

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\interpreter.py", line 23, in interpret
!    token.run(self)

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\token_.py", line 75, in run
!    function(interpreter)

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\tokens.py", line 188, in _run
!    function.get_value()(interpreter)

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\tokens.py", line 164, in run_tokens
!    token.run(interpreter)

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\token_.py", line 75, in run
!    function(interpreter)

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\tokens.py", line 73, in _run
!    print(value.get_value())

  File "D:\Alle_Dateien\Code\Python\NatScript Interpreter\interpreter\token_.py", line 152, in get_value
!    raise exceptions.UndefinedVariableException(self)

- UndefinedVariableException: Line 2: Tried to access undefined variable b!

Tested with Python 3.8.3, Win10.