From 75b99869d46de19155369d508d011cc1feb3cff3 Mon Sep 17 00:00:00 2001 From: Kai-Philipp Nosper Date: Wed, 2 Feb 2022 19:00:14 +0100 Subject: [PATCH] Rework README - Add full language description - Fix variable name inconsistency --- README.md | 179 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 159 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 8548bee..bbe81a4 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,139 @@ # NEK-Lang +## Variables +Currently all variables are global and completely unscoped. That means no matter where a variable is declared, it remains over the whole remaining runtime of the progam. + +All variables are currently of type `i64` (64-bit signed integer) + +### Declaration +- Declare and initialize a new variable +- Declaring a previously declared variable again is currently equivalent to an assignment +- Declaration is needed before assignment or other usage +- The variable name is on the left side of the `<-` operator +- The assigned value is on the right side and can be any expression +``` +a <- 123; +``` +Create a new variable named `a` and assign the value `123` to it. + +### Assignment +- Assigning a value to a previously declared variable +- The variable name is on the left side of the `=` operator +- The assigned value is on the right side and can be any expression +``` +a = 123; +``` +The value `123` is assigned to the variable named `a`. `a` needs to be declared before this. + +## Expressions +The operator precedence is the same order as in `C` for all implemented operators. +Refer to the +[C Operator Precedence Table](https://en.cppreference.com/w/c/language/operator_precedence) +to see the different precedences. + +### General +- Parentheses `(` and `)` can be used to modify evaluation oder just like in any other +programming language. +- For example `(a + b) * c` will evaluate the addition before the multiplication, despite the multiplication having higher binding power + +### Mathematical Operators +Supported mathematical operations: +- Addition `a + b` +- Subtraction `a - b` +- Multiplication `a * b` +- Division `a / b` +- Modulo `a % b` +- Negation `-a` + +### Bitwise Operators +- And `a & b` +- Or `a | b` +- Xor `a ^ b` +- Bitshift left (by `b` bits) `a << b` +- Bitshift right (by `b` bits) `a >> b` +- "Bit flip" (One's complement) `~a` + +### Logical Operators +The logical operators evaluate the operands as `false` if they are equal to `0` and `true` if they are not equal to `0` +- And `a && b` +- Or `a || b` + +### Equality & Relational Operators +The equality and relational operations result in `1` if the condition is evaluated as `true` and in `0` if the condition is evaluated as `false`. +- Equality `a == b` +- Inequality `a != b` +- Greater than `a > b` +- Greater or equal than `a >= b` +- Less than `a < b` +- Less or equal than `a <= b` + +## Control-Flow +For conditions like in if or loops, every non zero value is equal to `true`, and `0` is `false`. + +### Loop +- There is currently only the `loop` keyword that can act like a `while` with optional advancement (an expression that is executed after the loop body) +- The `loop` keyword is followed by the condition (an expression) without needing parentheses +- *Optional:* If there is a `;` after the condition, there must be another expression which is used as the advancement +- The loops body is wrapped in braces (`{ }`) just like in C/C++ + +``` +// Print the numbers from 0 to 9 + +// Without advancement +i <- 0; +loop i < 10 { + print i; + i = i - 1; +} + +// With advancement +k <- 0; +loop k < 10; k = k - 1 { + print k; +} +``` + +### If / Else + +- The language supports `if` and an optional `else` +- After the `if` keyword must be the deciding condition, parentheses are not needed +- The block *if-true* block is wrapped in braces (`{ }`) +- *Optional:* If there is an `else` after the *if-block*, there must be a following *if-false*, aka. else block +``` +a <- 1; +b <- 2; +if a == b { + // a is equal to b + print 1; +} else { + // a is not equal to b + print 0; +} +``` + +## IO + +### Print +Printing is implemented via the `print` keyword +- The `print` keyword is followed by an expression, the value of which will be printed to the terminal. +- Print currently automatically adds a linebreak +``` +a <- 1; +print a; // Outputs `"1\n"` to the terminal +``` + +## Comments + +### Line comments +Line comments can be initiated by using `//` +- Everything after `//` up to the end of the current line is ignored and not parsed +``` +// This is a comment +``` + + +# Feature Tracker + ## High level Components - [x] Lexer: Transforms text into Tokens @@ -10,28 +144,31 @@ - [x] General expressions - [x] Arithmetic operations - - [x] Addition `X+Y` - - [x] Subtraction `X-Y` - - [x] Multiplication `X*Y` - - [x] Division `X/Y` - - [x] Modulo `X%Y` + - [x] Addition `a + b` + - [x] Subtraction `a - b` + - [x] Multiplication `a * b` + - [x] Division `a / b` + - [x] Modulo `a % b` - [x] Unary operators - - [x] Negate `-X` - - [x] Parentheses `(X+Y)*Z` + - [x] Negate `-a` + - [x] Parentheses `(a + b) * c` - [x] Logical boolean operators - - [x] Equal `==` - - [x] Not equal `!=` - - [x] Greater than `>` - - [x] Less than `<` - - [x] Greater than or equal `>=` - - [x] Less than or equal `<=` + - [x] Equal `a == b` + - [x] Not equal `a != b` + - [x] Greater than `a > b` + - [x] Less than `a < b` + - [x] Greater than or equal `a >= b` + - [x] Less than or equal `a <= b` + - [x] Logical operators + - [x] And `a && b` + - [x] Or `a || b` - [x] Bitwise operators - - [x] Bitwise AND `X&Y` - - [x] Bitwise OR `X|Y` - - [x] Bitwise XOR `X^Y` - - [x] Bitwise NOT `~X` - - [x] Bitwise left shift `X<>Y` + - [x] Bitwise AND `a & b` + - [x] Bitwise OR `a | b` + - [x] Bitwise XOR `a ^ b` + - [x] Bitwise NOT `~a` + - [x] Bitwise left shift `a << b` + - [x] Bitwise right shift `a >> b` - [x] Variables - [x] Declaration - [x] Assignment @@ -60,7 +197,9 @@ expr_equ = expr_rel (("==" | "!=") expr_rel)* expr_band = expr_equ ("&" expr_equ)* expr_bxor = expr_band ("^" expr_band)* expr_bor = expr_bxor ("|" expr_bxor)* -expr = expr_bor +expr_land = expr_bor ("&&" expr_bor)* +expr_lor = expr_land ("||" expr_land)* +expr = expr_lor ``` ### Statements