spade-0.1.0.1: docs/language-reference.md

## Language Reference

### Variables

Variables are initialized using `let` statement. For example

```
let a = 10
```

### Conditionals

#### if-then

This is used to conditionally execute parts of a program. For example

```
if age > 10 then
    println("Greater than 10")
endif
```

#### if-then-else

This is used to provide an alternative if the condition does not hold.

```
if age > 10
  then
    println("Greater than 10")
  else
    println("Less than or equal to 10")
endif
```

#### if-then-elseif-else

This is like if-else statemebt but can be used to provide many alternative branches.

```
if age > 10
  then
    println("Greater than 10")
  elseif age > 5 then
    println("Greater than 5")
  elseif age > 2 then
    println("Greater than 2")
  else
    println("Less than or equal to 2")
endif
```

### Loops

Loops are using to execute a sequence of statements repeatedly. Following
looping constructs are available.

#### for statement

This loop can be used to execute some group of statements repeatedly,
while incrementing a variable at each iteration.

Example:

```
for i = 1 to 100
  println(i)
endfor
```

The `break` statement can be used to break out of the loop.

#### while statement

This loop execute a group of statements repeatedly as long as the specified
condition hold.

Example:

```
let i = 10
while i < 0
  println(i)
  let i = i + 1
endwhile
```

The `break` statement can be used to break out of the loop.

#### loop statement

This is an unconditional looping statement.
The only way to exit from the loop is by using a `break` statement.

Example:

```
let l = 0
loop
  println(l)
  let l = l + 1
  if l > 10 then break endif
endloop
getkey()
```

### Functions/Procedures

Functions are declared using the `proc` keyword. For example

```
proc multiply(a, b)
  return a * b
endproc

println(multiply(5, 2))
```

### Expressions

Expressions are things that can be evaluated to a value. Following types
of expressions are available in the language.


#### Literals

The language support the following literals.

Integers -> `1500`
Boolean -> `true`, `false`
Floating -> `12.34`
Bytes -> `0x21`
String -> `"SPADE"`
List -> `[12, 34, 56]`
Dictionary -> `{name : "John", age: 34}`
Anonymous function -> `fn(x) x * 2 endfn`

#### Variables

These refer to a variable, and evaluate to the same value that is held
by the variable.

#### If-then-else

These provide conditional evaluation, for example.

```
let x = if x == 0 then 1 else x
```

#### Binary operators

The following binary operators are available.

##### Numeric operators

`+` : addition operator
`-` : substraction operator
`*` : multiplication operator
`/` : division operator

##### Boolean operators

`<`   : less than
`>`   : greater then
`<=`  : less then or equal
`>=`  : greater than or equal
`==`  : equality check
`!==` : non-equality check
`and` : boolean AND
`or`  : boolean OR

The boolean 'not' operation is provided as a function #link: not#.

#### Function calls

Evaluates to the value returned by the function, for example,

```
proc multiply(a, b)
  return a * b
endproc

let a = multiply(5,2)
```

#### Index access

An index in a list expression can be accessed using the index accessor.
For example,

```
let list = [1,2,3,4]
print(list[2]) -- prints 2.
```

NOTE: List indexes starts from 1.

Index accessor can be attached to any expression, for example a function
returning a list. For example,

```
proc myFunc()
 return [1,2,3]
endproc
print(myFunc()[2]) -- prints 2.
```

#### Key access

An key in a dictionary expression can be accessed using the key accessor.
For example,

```
let person = { name: "John", age : 39 }
print(person.name) -- prints "John"
print(person.age) -- prints 39
```

Key accessor can be attached to any expression, for example a function
returning a dictionary. For example,

```
proc myFunc()
 return { name: "John", age : 39 }
endproc
print(myFunc().name) -- prints "John"
```

### Builtin data types

#### Numbers

Numbers are either represented as integers (which can be as big as required)
or double precision floating point values.

Mathematical operations convert from integer to floating point values as required.

```
let age = 45
let price = 0.23
```

#### Strings

Strings represent a sequence of unicode code points.

```
let name = "SPADE"
```

#### Bytes

Bytes represent some sequence of bytes.

```
let somebytes = 0xFFAB
```

#### Lists

Lists can hold a sequence of values.

```
let mylist = [ "SPADE", 10]

```

Item at an index `x` in list `l` can be accessed using notation `l[x]`.
Indexes start at `1`, so to access the first item in a list use `l[1]`.

See #link: List Functions#

#### Dictionary

Dictionaries are containers that can hold content at a string key.
For example, the data for a person can be held in a dictionary.

```
let person = { name: "John", age: 45}
```

indvidual items can be accessed using the key access notation. For example
to print the name of the person, we can do something like the following.

See #link: Dictionary Functions#

```
println(person.name)
```