The Elements of Computing Systems, My Workbook for the NAND to Tetris course.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
nand2tetris/compiler/README.md

11 KiB

Jack Language Specification

Class Structure

class name {
  field and static variable declarations //must precede subroutine
  subroutine declarations  // constructor, method, and function

  // subroutines can be of three types:
  constructor|method|function name (param-list) {
    local variable declarations
    statements
  }

}

Comments

// comment to end of line
/* Comment until closing */
/** Documentation comment */

Symbols

Symbol Usage
() arithmetic expressions and parameter lists and argument lists
[] array indexing
{} grouping program units and statements
, variable list separator
; statement terminator
= assignment and comparison operator
. class membership
`+-*/ &~<>`

Reserved Keywords

class, constructor, method, function
int, boolean, char, void
var, static, field
let, do, if, else, while, return
true, false, null
this

Constants

  • Integer constants can only be positive. negastive constants are expressions with the minus operator on a integer constant.
  • String constants need "double quotes". Cannot contain newline or doublequote.
  • Boolean constants are true, and false
  • null signifies a null reference

Identifiers

  • A-Z, a-z, 0-9, _. First character can't be a digit.
  • Language is case-sensitive

Main

  • There must be a Main class. THis class must have atleast one function named main.

Variables

  • Must be declared before usage.
  • Data types can be primitive (int, char, boolean) or object type. String|Array types are provided by standard library.
  • char is "unicode"!
  • Creation of object type only creates a reference null pointer. Creating a new instance using the constructor creates the actual memory allocation.

Types

  1. Static
  2. Field
  3. Local
  4. Parameter

Arrays

  • Array entries do not have a declared type, and different entries in the same array may have different types.

Type conversions

  • automatic for char/int dual-ways.
  • integers can be used as memory addresses.
  • classes mostly behave as C structures for memory allocation. So using a class object with array syntax will give you the correct result. (Need to check if assignment is by reference here or by value)

Statements

  • let variable = expression;
  • let variable[expression1] = expression2;
  • if (expression) {s1} [else {s2}]
  • while (expression) {statements}
  • do function-or-method-call;
  • return [expression];

curly brackets are always mandatory

Expression

See Figure 9.9

Standard Library

Class Provides
Math provides basic mathematical operations
String implements the String type and string-related operations
Array implements the Array type and array-related operations
Output handles text output to the screen
Screen handles graphic output to the screen
Keyboard handles user input from the keyboard
Memory handles memory operations
Sys provides some execution-related services.

Math

This class enables various mathematical operations. Everything is a function

  • void init (): for internal use only.
  • int abs (int x): returns the absolute value of x.
  • int multiply(int x, int y): returns the product of x and y.
  • int divide(int x, int y): returns the integer part of x/y.
  • int min(int x, int y): returns the minimum of x and y.
  • int max(int x, int y): returns the maximum of x and y.
  • int sqrt(int x): returns the integer part of the square root of x.

String

This class implements the String data type and various string-related operations.  

Constructors

  • String new(int maxLength): constructs a new empty string (of length zero) that can contain at most maxLength characters;

Methods

  • void dispose(): disposes this string;
  • int length(): returns the length of this string;
  • char charAt(int j): returns the character at location j of this string;
  • void setCharAt(int j, char c): sets the j-th element of this string to c;
  • String appendChar(char c): appends c to this string and returns this string;
  • void eraseLastChar(): erases the last character from this string;
  • int intValue(): returns the integer value of this string (or of the string prefix until a non-digit character is detected);
  • void setInt(int j): sets this string to hold a representation of j;

Functions

  • char backSpace(): returns the backspace character;
  • char doubleQuote(): returns the double quote (") character;
  • char newLine(): returns the newline character.  

Array

This class enables the construction and disposal of arrays.

  • function Array new(int size): constructs a new array of the given size;
  • method void dispose(): disposes this array.  

Output

This class allows writing text on the screen. Everything is a function.

  • void init(): for internal use only;
  • void moveCursor(int i, int j): moves the cursor to the j-th column of the i-th row, and erases the character displayed there;
  • void printChar(char c): prints c at the cursor location and advances the cursor one column forward;
  • void printString(String s): prints s starting at the cursor location and advances the cursor appropriately;
  • void printInt(int i): prints i starting at the cursor location and advances the cursor appropriately;
  • void println(): advances the cursor to the beginning of the next line;
  • void backSpace(): moves the cursor one column back.  

Screen

This class allows drawing graphics on the screen. Column indices start at 0 and are left-to-right. Row indices start at 0 and are top-to-bottom. The screen size is hardware-dependant (in the Hack platform: 256 rows by 512 columns).  

  • void init(): for internal use only;
  • void clearScreen(): erases the entire screen;
  • void setColor(boolean b): sets a color (white = false, black = true) to be used for all further drawXXX commands;
  • void drawPixel(int x, int y): draws the (x,y) pixel;
  • void drawLine(int x1, int y1, int x2, int y2): draws a line from pixel (x1,y1) to pixel (x2,y2);
  • void drawRectangle(int x1, int y1, int x2, int y2): draws a filled rectangle whose top left corner is (x1,y1) and bottom right corner is (x2,y2);
  • void drawCircle(int x, int y, int r): draws a filled circle of radius r <= 181 around (x,y).  

Keyboard

This class allows reading inputs from a standard keyboard. Everything is a function.

  • void init(): for internal use only;
  • char keyPressed(): returns the character of the currently pressed key on the keyboard; if no key is currently pressed, returns 0;
  • char readChar(): waits until a key is pressed on the keyboard and released, then echoes the key to the screen and returns the character of the pressed key;
  • String readLine(String message): prints the message on the screen, reads the line (text until a newline character is detected) from the keyboard, echoes the line to the screen, and returns its value. This function also handles user backspaces;
  • int readInt(String message): prints the message on the screen, reads the line (text until a newline character is detected) from the keyboard, echoes the line to the screen, and returns its integer value (until the first nondigit character in the line is detected). This function also handles user backspaces.  

Memory

This class allows direct access to the main memory of the host platform. Everything is a function.

  • void init(): for internal use only;
  • int peek(int address): returns the value of the main memory at this address;
  • void poke(int address, int value): sets the contents of the main memory at this address to value;
  • Array alloc(int size): finds and allocates from the heap a memory block of the specified size and returns a reference to its base address;
  • void deAlloc(Array o): De-allocates the given object and frees its memory space.  

Sys

This class supports some execution-related services. Everything is a function.

  • void init(): calls the init functions of the other OS classes and then calls the Main.main () function. For internal use only;
  • void halt(): halts the program execution;
  • void error(int errorCode): prints the error code on the screen and halts; ■ function void wait(int duration): waits approximately duration milliseconds and returns.

Error Codes

  1. Sys.wait: Duration must be positive
  2. Array.new: Array size must be positive
  3. Math.divide: Division by zero
  4. Math.sqrt: Cannot compute square root of a negative number
  5. Memory.alloc: Allocated memory size must be positive
  6. Memory.alloc: Heap overflow
  7. Screen.drawPixel: Illegal pixel coordinates
  8. Screen.drawLine: Illegal line coordinates
  9. Screen.drawRectangle: Illegal rectangle coordinates
  10. Screen.drawCircle: Illegal center coordinates
  11. Screen.drawCircle: Illegal radius
  12. String.new: Maximum length must be non-negative
  13. String.charAt: String index out of bounds
  14. String.setCharAt: String index out of bounds
  15. String.appendChar: String is full
  16. String.eraseLastChar: String is empty
  17. String.setInt: Insufficient string capacity
  18. Output.moveCursor: Illegal cursor location

Jack Grammar Specification

This comes from Figure 10.5

Lexical Elements

keyword

class constructor function method
field static var int char boolean void
true false null this
let do if else while return

symbol

{}()[].;+-*/&|<>=~

integerConstant

A decimal number in the range 0..32767

stringConstant

A sequence of unicode characters not including double quote or newline

identifier

A sequence of letters, digits, and underscore, not starting with a digit

Program Structure

  • A Jack program is a collection of classes
  • Each class appears in a separate file
  • The compilation unit is a class
  • A class is a sequence of tokens as per follow context-free syntax:

class

class className {
  classVarDec*
  subRoutineDec*
}

classVarDec

(static|field) type varName (, varName)* ;

type

int | char | boolean | className

subRoutineDec

(constructor | function | method)
(void | type)
subRoutineName
( parameterList )
subroutineBody

parameterList

(
  (type varName) (, type varName)*
)?

subroutineBody

{
  varDec*
  statements
}

varDec

var type varName (, varName)* ;

className, subroutineName, varName

identifier

Statements

statements

statement*

statement

letStatement | ifStatement | whileStatement | doStatement | returnStatement

letStatement

let varName ([ expression])? = expression ;

ifStatement

if (expression) { statements }
(else {statements})?

whileStatement

while (expression) {statements}

doStatement

do subroutineCall;

returnStatement

return expression?;

Expressions

TODO

Terminal / Non-Terminal Keywords

Terminal Non-Terminal
keyword,symbol,integerConstant,stringConstant,identifier class,classVarDec,subroutineDec,parameterList,subroutineBody,varDec
statements,whileStatement,ifStatement,returnStatement,letStatement,doStatement
expression,term,expressionList