Locks

[Note: I made this during my first sem at uni, so expect some not-so-well-written code ;)] Locks is an imperative, dynamically typed, procedure oriented scripting language based on the lox language. Locks-py is the python implementation of locks. While locks and lox share almost the same grammar, the locks implementation is not based on that of lox. This was made as a project for an introductory programming course.

Contents

• Usage
• The Locks language
  • IO
  • Comments
  • Keywords and Identifiers
  • Datatypes
  • Variables
  • Statements
    • Expression Statement
    • Assign Statement
    • If Statement
  • Loops
    • While loop
    • For loop
  • Functions
  • Builtin functions
    • IO functions
    • String and Array functions
      • String
      • Both
    • Type conversion
• The Locks VM
  • Byte code Format
    • Constants Pool
  • Opcodes
• Editor
  • Opening files
  • Saving files
  • Running Locks programs
  • Visualizing The AST from the Editor
  • Customizing
  • Keyboard shortcuts
• Visualizing The AST
• Known Bugs

Usage

Note: You will need to have python 3 installed. This project was tested with python 3.8.3.

To start the editor, clone this repo and run

python locks-editor.py

An editor window should pop up. Start coding! You can find examples at examples/. To run a program, open a locks file through File -> Open, and choose Run -> Run(debug) from the menu bar. For more details, check the Editor section.

To run a locks program from the command line, run

python locks-interpreter.py <path-to-locks-file>

To be able to visualize the AST, the requests, cairosvg, and Pillow libraries will have to be installed.

pip install requests
pip install cairosvg
pip install Pillow

If these are not installed, the visualizer will generate a dot file, the contents of which can be pasted at GraphViz Online to render it. For more information, see Visualizing The AST.

The interpreter will use the VM to run the program by default.

locks-interpreter.py accepts the following options:

The Locks language

IO

The print() function prints arguments to stdout. println adds a trailing newline character.

print("Hello World");
println("Hello World");

The input() function accepts input from stdin. It accepts a prompt as string, and returns the inputted string.

input("");  // no prompt
input("Enter something");  // input with prompt

var x = input("Enter something");  // store input in a variable (as a string)

Comments

Locks supports single line and multi-line C-style comments. Multi-line comments cannot be nested.

// single line comment
/*
    Multi-line comment
*/

Keywords and Identifiers

The following are reserved keywords in Locks:

var, fun, if, elsif, else, while, for, return, continue, break, and, or, true, false, nil

A valid Locks identifier may contain alphanumeric and '_' characters, and may not begin with a number.

var _a123_;  //valid
var 12r; //invalid!

Datatypes

Locks supports the following datatypes:

• Nil: Used to define a null value, denoted by the nil keyword
• Number: Can be 64 bit signed integer, or double precision floating-point numbers. For example: 135, 31.63, -1331
• String: Sequence of ascii characters surrounded by ". For example: "Hello!"
• Boolean: Can be true or false
• Array: A sequence of Locks datatypes, surrounded by [ and ] and separated by ,. For example: [1, "hello", [true, 2]]

The following are falsey values in locks: 0, "", [], false, nil, and functions.

Variables

Variables are declared using the var keyword.

var a;  // declare
a = 5;  // assign
var b = 5;  // declare and assign

Statements

Locks supports the following statements (apart from loops, return, continue and break statements):

• Expression Statement
• Assign Statement
• If Statement

Expression Statement

Locks supports the following operators for arithmetic and logical expressions:

• +: Adds two numbers or concatenates two strings. Both operands must be of the same type (i.e. String or Number)

• -: Subtracts right operand from left operand. Both operands must be numbers. Can also function as a unary negation operator.

• *: Multiplies two numbers

• \: Divides two numbers

• %: Gives remainder when left operand is divided by right operand (modulo)

• ==: Returns true if left operand is equal to right operand, otherwise false

• !=: Returns true if left operand is not equal to right operand, otherwise false

• <: Returns true if left operand is less than right operand, otherwise false. Both operands must be numbers

• >: Returns true if left operand is equal to right operand, otherwise false. Both operands must be numbers

• <=: Returns true if left operand is equal to right operand, otherwise false. Both operands must be numbers

• >=: Returns true if left operand is equal to right operand, otherwise false. Both operands must be numbers

• and: Returns true if both left and right operands are truthy, otherwise false

• or: Returns true if either the left or the right operand is truthy, otherwise false

• !: Performs a logical not on its operand

Assign Statement

Unlike Lox, variable assignment is a statement in Locks rather than an expression. The left operand for the = (assign) operator can be either an identifier, or an indexed identifier that refers to an array.

var a;
// assignment statements
a = [1,2,3,4,5];
a[3] = 7;

If Statement

The if-elsif-else statement is similar to that of C.

var a = 3;
var b;

if(a < 10){
    b = 0;
}elsif(a >= 10 and a < 20){
    b = a;
}else{
    b = 1;
}

Loops

While loop

A conventional C-style while loop, in which the body is executed while the expression specified in parentheses evaluates to true.

var i = 0;

while(i < 10){
    println(i);
    i = i + 1;
}

For loop

Locks supports C-style for loops. However, it must be noted that new scopes are created only when a function is called, so a variable if declared once in a for loop, it must not be declared again.

// infinite loop!
for(;;) println("Hello");

// Ok. Note that locks does not have a '+=' or '++' shorthand
for(var i = 0; i < 10; i = i + 1){
    println("Hello");
}

// Ok.
for(i = 0; i < 10; i = i + 1){
    println("Hello");
}

// ERROR! Duplicate declaration of variable 'i'
for(var i = 0; i < 10; i = i + 1){
    println("Hello");
}

Functions

Functions in Locks are declared using the fun keyword. The parameters must be comma separated identifiers, and are specified in parentheses after the function name.

fun add(b, c, d){
    println(b + c + d);
}

add(1, 3, 5);

A value can be returned at any point from a function using the return keyword.

// "fun fact"! :D
fun fact(n){
    if(n == 1) return 1;
    return n*fact(n-1);
}

println(fact(6));

Note that while functions can be declared inside functions, they cannot be returned from a function or assigned to a variable.

fun a(){
    // Ok.
    fun b(){
        return 5;
    }
    println(b());
    return b;  // ERROR! can't return a function from within a function
}

var x = a; // ERROR! can't assign a function to a variable

Builtin functions

IO functions

• print: Accepts 1 argument and prints it to stdout
• println: Accepts 1 argument and prints it to stdout, with newline
• input: Accepts 1 argument and prints it to stdout, and accepts input from stdin

For usage of these functions, check IO.

String and Array functions

String

• isinteger: Accepts a string as argument, returns true if the string is a valid integer, false otherwise

Both

• len: Accepts a string or an array as argument, and returns its length

Type conversion

• int: Accepts 1 argument, converts it to an integer, and returns it
• str: Accepts 1 argument, converts it to a string, and returns it

The Locks VM

The Locks VM is inspired by the JVM and the Python VM.

Byte code Format

Byte code for the Locks VM always begins with the magic number 0x04D69686F, followed by the constants pool count (2 bytes) followed by constants. This is then followed by the function count (2 bytes) and then the functions. Each function begins with an argument count (2 bytes) followed by the length of the function code (2 bytes).

For example:

0x4d 0x69 0x68 0x6f  // magic number

0x00 0x03  // constants pool count

0x08 0x48 0x65 0x6c 0x6c 0x6f 0x21 0x00       // constant 1 - string
0x03 0x00 0x00 0x00 0x00 0x00 0x00 0x01 0xf4  // constant 2 - int
0x06 0x00 0x20 0x00 0x00 0x00 0x00 0x01 0x3a  // constant 3 - float

0x00 0x02  // function count

// function 1
0x00 0x00  // arg count
0x00 0x12  // code length (in bytes)

0x64 0x0 0x0
0x64 0x0 0x1
0x64 0x0 0x2
0x10 0x03
0x10 0x04
0x83 0x01
0x84 0x01
0xff

// function 2
0x00 0x02  // arg count
0x00 0x0a  // code length (in bytes)

0x5a 0x00
0x5a 0x01
0x52 0x00
0x52 0x01
0x17
0x53

This is the code generated for:

// constants to demonstrate constants pool
"Hello!";
500;
3.14;

fun add(a, b){
    return a + b;
}

println(add(3,4));

Constants Pool

The constants pool stores all strings, negative integers and integers greater than 255, and floating-point numbers. Each constant is tagged to denote their type:

Negative integers are stored in their two's complement representation. For example, -1729 will be stored as 0xff 0xff 0xff 0xff 0xff 0xff 0xf9 0x3f.

Strings are stored as null-terminated strings. For example, "Hello" will be stored as 0x48 0x65 0x6c 0x6c 0x6f 0x21 0x00.

Floting point numbers are stored according to the following representation:

For example, 3.14 will be stored as 0x00 0x20 0x00 0x00 0x00 0x00 0x01 0x3a.

Opcodes

Editor

The Locks Editor is a minimal text editor made with tkinter, with which you can open, edit, save, and run locks files.

Opening files

A file can be opened through the File -> Open option. Note that opening a new file will override the current open file, so make sure it is saved first.

Saving files

A file can be saved through the File -> Save or File -> Save As option, as a text(.txt) or a locks(.lks) file.

Running Locks programs

A currently open locks file can be run through Run -> Run or Run -> Run (debug). Run will run the program through the VM, and Run (debug) will run the program through the tree walk interpreter.

A new terminal window will be opened on Windows for code execution. Note that running the program through the VM exits the terminal as soon as execution is complete, an input("") can be added to the end of the locks program to stop this from happening.

On linux, the locks program will execute in the terminal that the editor was run from.

Visualizing The AST from the Editor

The AST can be visualized from the editor by selecting the Run -> Visualize AST option. This will attempt to create and render a dot file. Any error or message is shown on a separate console window. On linux, the messages are shown on the same console that the editor was run from.

Customizing

The font size and theme can be changed from Options -> Preferences.

The default dark and light themes were inspired by the Cyberpunk 2077 and the Atom One light syntax theme. If you don't like either, switch to the notepad theme or create your own.

You can create your own theme files by following the format below and saving the json file in the editor/theme folder. Note that (as of now) the editor does not check for the validity of the theme files.

Theme example: defaultDark.json

{
    "name": "Default Dark",
    "background": "#030d22",
    "foreground": "#ffffff",
    "selectBackground": "#35008b",
    "inactiveselectbackground": "#310072",
    "cursorColor": "#ee0077",
    "keywords": "#ff2cf1",
    "functionName": "#ffd400",
    "strings": "#0ef3ff",
    "comments": "#0098df"
}

Note: Syntax highlighting for multiline comments is disabled for now since it may cause other syntax highlighting problems. See known bugs.

Keyboard shortcuts

• Ctrl+o: Open file
• Ctrl+s: Save currently open file
• Tab and Shift+Tab: Add/remove 4-space indent to selection or current line

Visualizing The AST

The interpreter can be used to visualize the AST of an input program as a graph. This can be done as follows:

python locks-interpreter.py <path-to-locks-file> -g <write-dot-to-file>

For example:

python locks-interpreter.py examples/fibonacci.lks -g fib.dot

The interpreter will write the generated dot code to a file at the location specified by the argument (which must be a filename). It will then try to use the QuickChart GraphViz API to generate and get an svg file from the dot file, use chairo to convert it to a png file, and then show the image on a window through Pillow and Tkinter. Pillow, requests, and chairo will need to be installed separately using pip for this to work. If not installed, the dot file alone will be generated. The generated code can be pasted to GraphViz Online to render it.

The AST can also be visualized from the editor by selecting the Run -> Visualize AST option.

Known Bugs

• The tree walk interpreter crashes when the lvalue of an assign statement tries to index a nested list.

  var a = [1,2,[3,4],5]
  a[2][1] = 8;  // Crash!!

  This works in the VM, however.

• If an operand of a comparision expression with is a function, it works fine in the VM. If either operand is a function, the tree walk interpreter throws a type error. If the left operand is a function and the result of the expression is assigned to a variable, the semantic analyser throws a type error.

  fun a(){
      print("hello");
  }
  
  // works in the VM, but tree walk interpreter throws a type error
  println(a == a);
  
  // semantic analyzer throws a type error
  var l = a and 4;

• The VM does nothing and continues with execution if there is a return statement outside a function. The tree walk interpreter throws a 'return outside function' syntax error.

• Multiline comments are not correctly highlighted in the Editor. They only work when /**/ is typed in first, and then the comment is written. When highlighted correctly, their foreground doesn't change even on change of theme. For now, syntax highlighting for multiline comments will be disabled.