5 The Language

5 - The Lanugage

5.1 - Lexical Conventions

CSpydr is free-form, meaning that spaces and comments are ignored, except in strings, in characters and as delimiters between tokens. Spaces are recognized as whitespaces, carriage returns and tabs. Only ASCII characters are accepted.

Identifiers consist of a series of alphanumeric characters or underscores, not starting with a digit. Next to that, CSpydr is case-sensitive. meaning that myid and myID are two different identifiers. When compiled with the C backend identifiers may not start with __csp_. CSpydr has a series of keywords, which cannot be used as identifiers

Keywords:

true      false  nil    let     fn
loop      while  for    if      else
ret       match  type   struct  union
enum      import const  extern  macro
namespace sizeof typeof alignof break
continue  noop   len    asm     using
with      do     unless

Symbols:

++  +=  +   --  -=  -   *=  *
%=  %   /=  /   &=  &&  &   ^
^=  <<= >>= <<  >>  ||  |=  |>
|   ==  =>  =   !=  !   >=  <=
<-  <   >   (   )   {   }   [
]   ~   ,   ;   _   ::  ... ²
³   $ `

Strings & Characters:

String literals are delimited by double quotes (") and can contain any amount of any character except non-escaped double quotes. Character literals are delimited by single quotes (') and can only contain one single character, or an escape sequence. These escape sequences include the following:

Literal characters	Interpreted character
\a	Bell (alert)
\b	Backspace
\f	Form Feed
\n	Newline
\r	Carriage return
\t	Horizontal Tab
\v	Vertical Tab
\'	Single Quote
\"	Double Quote
\\	Backslash
\0	Null character

Numbers:

An integer constant can be written as decimal, hexadecimal, binary or octal. Floating-point constants can only be written in decimal and must include a radix point. All number literals can contain as many underscores _ as you like for better visual parsing. Examples of valid numerical constants are the following:

99   1        1_000_000
0xff 0xabcdef 0x3d
0o77 0o7234   0o0
0b11 0b10010  0b11011
1.2  3.1415  1_234.567 

Comments:

Comments can be either single-line or blocks. Single-line comments are denoted by a hashtag # and include the rest of the line, while block comments are denoted by #[ and go on until ]#.

5.2 - Variables, Members and Arguments

Variables:

As most programming languages, CSpydr supports variables, which are named storage areas that can be manipulated. Each variable has its own type and can be assigned or referenced anywhere in the same or a deeper scope after its declaration. The name of the variable must be an identifier that is not also a type (see 5.1 - Lexical Conventions). Variables can be declared with or without an initial value and type using the let or const keyword:

let foo = 0;  # initialization with value and implicit type
let bar: i64; # initialization without value and explicit type
const baz = 3; # initialization using `const`, making the variable immutable

Arguments:

Arguments are a type of local variables defined in a function or lambda declaration used for passing values to them:

fn foo(bar: i32, baz: &char) {} 

Members:

Members are named memory-offsets in structs and unions:

struct {
    foo: i32,  # offset 0 bytes
    bar: f64,  # offset 4 bytes
    baz: &char # offset 12 bytes
}

5.3 - Statements

Like almost any procedural language, CSpydr has statements. Statements are constructs used for defining control flow and -behaviour.

These are all statements in CSpydr:

5.3.1 - Blocks

Blocks group multiple statements together while also creating a new scope for variables. Like in C, they start by { and end with }

{
    # statements here
}

Blocks can contain using statements, which can pull functions and variables from a given namespace into the current scope, making function names more precise.

using std::io;
puts("..."); # we can now use puts() defined in std::io, rather than std::io::puts()

5.3.2 - Loops

CSpydr has three loop types: loop for an endless loop, while for loops with a single exit condition and for-loops for more complex loop behaviours.

loop

loop {
    # statement gets repeated endlessly
}

while

while condition {
    # statement gets repeated until `condition` is false (0)
}

for

For-loops consist of 3 parts: the initializer statement, condition- and counter-expression seperated by semicolons ;:

for init; condition; counter; {
}

The init-statement gets run once at the beginning, whereas counter after every iteration. The loop iterates, as long as condition is true (not 0).

do-while:

The do-while loop is semanthically equivalent to C's do {} while();. It executes the do-block first and repeats it until condition is false.

do {

} while condition;

5.3.3 - Control Flow

CSpydr offers the following control statements:

if   match   ret   break   continue   with   asm    defer    do-unless    do-while

These statements can change the flow of programs, create new branches or merge them. Statements, that don't end in } require a semicolon ; after them.

if: If statements execute a statement if a given condition is true (not 0). If the statement is false (0), the if statement may execute the statement defined after else. Defining else is optional, however.

if condition {
    # if condition is not 0, execute this
}
else {
    # if condition is 0, execute this (not necessary)
}

do-unless:

The do-unless provides a reversed-order notation compared to the if-statement. It is generally used for early returning out of functions and follows this scheme:

do {
    # do this unless "condition" is true
} unless condition;

match:

Match statements work similar to C's switch statement. They are used when the program branches into many directions when different conditions are met. In the match statement, you define different "cases", each with their own value to compare. _ is the default case and gets executed if no other case matched the condition.

match condition {
    0 => # if condition is 0, execute this
    1 => # if condition is 1, execute this
    _ => # if none of these conditions match, execute this
}

ret:

The return-statement (ret) exits and returns a value from the current function or lambda. It can be written in two different ways using ret or <-

ret 0; # return 0
<- 1; # return 1

break:

The break-statement breaks out of the current loop.

break;

continue:

The continue-statement starts the next loop iteration immediately.

continue;

with:

The with-statement can be used in conjunction with IO types for easy error handling and memory management. It assigns a given value to a given value, checking if the value is not 0. Finally, it executes a predefined function for freeing memory or similar. The exit-function for a given type can be set using the exit_fn compiler directive: [exit_fn("your_exit_function": your_type)]. Exactly as if-statements, the with-statement can be followed by else, executed if the variable assignment was not successful.

with ptr = alloc(10) {
    # do something with ptr, it will be automatically freed.
}
else {
    # if memory allocation failed, execute this (not necessary)
}

asm:

The asm-statement can inject inline x86_64-bit GNU Assembly. This statement is mostly used for low-level functions like system calls and can be highly unsafe. The body of the assembly statement consists of strings, but also can have integer literals or variable identifiers. The values/addresses of which will be automatically substituted.

asm "mov %rax, " foo;

defer:

The defer-statement moves code written in it's body to the back of the current block.

Currently, this is only done at compile-time, so it won't respect loops or any other control flow.

{
    defer {
        # move statements in here to the end of the surrounding block statement.
        std::io::printf("A")
    }
    std::io::printf("B")
}

5.3.4 - Expression Statements

Some expressions can be used like statements. The expressions include:

• function calls
• assignments
• ++ and --
• pipes

5.3.5 - Variable Declarations

Local variables can be declared in any block statement using the let or const keyword. Variables defined with const are immutable.

let x = 0;
let y: i32 = 0;
let z: &char;

5.4 - Expressions

CSpydr features many expressions. Expressions are used to fetch, evaluate, modify and store data. They mostly behave like mathematical operators, variables and constants.

5.4.1 - Literals

Literals form the most basic expressions of CSpydr. They represent constant values for their type.

boolean literals:

Boolean literals are the simplest kind of CSpydr's literals: They represent a value of type bool (1-byte integer) and can either be

true # 1

or

false # 0

integer and float literals:

Integer and float literals represent constant (non-changing) number values in code. Here are some valid examples:

# integer literals
99   1        1_000_000 
0xff 0xabcdef 0x3d
0o77 0o7234   0o0
0b11 0b10010  0b11011

# float literals:
1.2  3.1415  1_234.567

Integer literals have the default type of i32, float literals f32. To use these literals with other types, use type casting:

(0xff: u8)
(3.1415: f64)

character literals:

Character literals are a special form of integer literals, representing a single char (1-byte integer) value in a more readable, ASCII-decoded form.

Character literals are delimited by ' and can contain escape codes.

'a' # ASCII "a" value (decimal value 97)
'A' # "A" (decimal 65)
'0' # "0" (decimal 48, NOT 0)
'\n' # new-line character using an escape code

string literals:

String literals represent an immutable array of characters in ASCII-decoded form. They are delimited by " and can contain escape codes as well.

The last character, '\n' (null-character) is appended implicitly. The length of string values can be calculated using the len operator.

"hello" # simple string literal with length 6 (5 letters + 1 null character)
"first line\nsecond line" # longer string with a line break using escape-codes

nil literal:

The nil literal represents a pointer to address 0, indicating a non-existant or missing value. It has the type &void.

array literals:

Array literals provide an easy way of initializing arrays. The array type is inferred corresponding to its first element. All following elements will be casted to this type.

Note: Array literals represent CSpydr-style arrays, not C-like arrays!

[0, 1, 2, 3, 5.5] # represents an array of type i32[5]. The last value `5.5` will be casted to an integer.

struct literals:

Struct literals provide an easy way of initializing structs. They come in two flavours:

1. Explicitly-typed:

Explicitly-typed struct literals are used to create variables on a known type. It Allows better type checking and is generally preferred over the second type.

type X: struct {
    a: i32, b: i32, c: i32
}

X::{2, 3.3, 4} # represents value of struct `X`, whose members are three integers.
               # The second argument will be casted accordingly.

1. Implicitly-typed:

Implicitly-typed struct literals are used to create structs which don't have a typedef'ed alias. They are generally discouraged because of their worse readability and unsafer type handling.

{2, 3.3, 4} # represents a value of an anonymous struct with two integer and one float-typed members.
            # The second argument will not be casted to `i32`!

5.4.2 - Operator Precedence

Operator precedence is the ability of an operator to pull it's operands towards it, making it execute after operators with lower precedence. The precedence decides the order, in which operations are executed.

CSpydr has the following precedence table: (the higher the precedence, the latter the operator is executed!)

Precedence	Operator	Name
1	=	Assignment
2	|>	Pipe
3	||	Logical OR
4	&&	Logical AND
5	ident	Infix function call
6	:	Type cast
7	|	Bitwise OR
8	^	Bitwise XOR
9	&	Bitwise AND
10	==	Equals
11	<, <=	Less than (or equals)
12	>, >=	Greater than (or equals)
13	<<, >>	Left & Right Bitshift
14	+, -	Plus, Minus
15	*, /	Multiplication, Division
16	%	Modulo
17	- (unary), ~ (unary), & (unary), * (unary)	(unary) Minus, Bitwise Negation, Reference, Dereference
18	²	Power
19	--, ++	Increment, Decrement
20	alignof, sizeof, typeof	Align of, Size of, Type of
21	foo()	Function call
22	foo[x]	Index
23	foo.bar	Member

5.4.3 - Infix Operators

A binary expression contains two operands separated by one operator.

All binary operators have left-to-right associativity, but not all binary operators have the same precedence. See the precedence table above for more information.

a + b # addition
a - b # subtraction
a * b # multiplication
a / b # division
a % b # modulo
a == b # equality
a != b # inequality
a > b, a >= b # greater than (or equal)
a < b, a <= b # less than (or equal)
a && b # logical AND
a || b # logical OR
a << b, a >> b # bit shift (left/right)
a & b # bitwise AND
a ^ b # bitwise XOR
a | b # bitwise OR
a = b # assignment

CSpydr's binary operators are divisible into four groups:

1. The mathematical operators +, -, *, /, % work on numbers of any type (except % only on int). These operators are used in mathematical equations and calculations.
2. The logical operators ==, !=, >, >=, <, <=, && and || are used to compare two values to each other: they return true, if the values match together with the operator and false otherwise.
3. The bitwise operators <<, >>, &, | and ^ allow to modify individual bits of integer values. See Bitwise operation (Wikipedia) for more information.
4. The assignment (=) operator sets value of the left operand to the value of the right argument.

5.4.4 - Unary Operators

Unary operators contain one argument after the operator.

-a # negation
!a # logical NOT
~a # bitwise NOT
&a # reference operator
*a # dereference operator

1. The negation (-) operator is meant to be used on integers and floats and makes positive values negative and negative values positive.
2. The logical not (!) operator returns false if the argument is truthy and true of the argument is falsy.
3. The bitwise not (~) operator turns all binary bits of the argument around. An integer like 0b01101011 gets converted to 0b10010100.
4. The memory operators & and * are used to get the memory address of a value or get the value of an address (pointer).

5.4.5 - Postfix Operators

Postfix operators contain one argument before the operator.

a++ # increment
a-- # decrement

The only two postfix operators are increment/decrement, which increment or decrement a given value by 1, while returning the value before. These operators are commonly used in loops and other repeating code structures.