# Ling tutorial

Ling is a very simple language, where we take only most important and popular features from
other scripts and languages. In particular, we adopt _principle of minimal confusion_[^1].
In other word, the code usually works as expected when you see it. So, nothing unusual.

__Other documents to read__ maybe after this one:

- [Advanced topics](advanced_topics.md)
- [OOP notes](OOP.md)
- [math in Ling](math.md)
- Some class references: [List](List.md), [Real](Real.md), [Range](Range.md)

# Expressions

Everything is an expression in Ling. Even an empty block:

    // empty block
    >>> void

any block also returns it's last expression:

    if( true ) {
        2 + 2
        3 + 3
    }
    >>> 6

If you don't want block to return anything, use `void`:

    fn voidFunction() {
        3 + 4 // this will be ignored
        void
    }
    voidFunction()
    >>> void

otherwise, last expression will be returned:

    fn normalize(value, minValue, maxValue) {
        (value - minValue) / (maxValue-minValue)
    }
    normalize( 4, 0.0, 10.0)
    >>> 0.4

Every construction is an expression that returns something (or `void`):

    val x = 111 // or autotest will fail!
    val limited = if( x > 100 ) 100 else x
    limited
    >>> 100

You can use blocks in if statement, as expected:

    val x = 200
    val limited = if( x > 100 ) {
        100 + x * 0.1    
    }
    else 
        x
    limited
    >>> 120.0

When putting multiple statments in the same line it is convenient and recommended to use `;`:

    var from; var to
    from = 0; to = 100
    >>> 100

Notice: returned value is `100` as assignment operator returns its assigned value.
Most often you can omit `;`, but improves readability and prevent some hardly seen bugs.

## Assignments

Assignemnt is an expression that changes its lvalue and return assigned value:

    var x = 100
    x = 20
    println(5 + (x=6)) // 11: x changes its value!
    x
    >>> 11
    >>> 6

As the assignment itself is an expression, you can use it in strange ways. Just remember
to use parentheses as assignment operation insofar is left-associated and will not
allow chained assignments (we might fix it later). Use parentheses insofar:

    var x = 0
    var y = 0
    x = (y = 5)
    assert(x==5)
    assert(y==5)
    >>> void

Note that assignment operator returns rvalue, it can't be assigned.

## Modifying arithmetics

There is a set of assigning operations: `+=`, `-=`, `*=`, `/=` and even `%=`.

    var x = 5
    assert( 25 == (x*=5) )
    assert( 25 == x)
    assert( 24 == (x-=1) )
    assert( 12 == (x/=2) )
    x
    >>> 12

Notice the parentheses here: the assignment has low priority!

These operators return rvalue, unmodifiable.

## Assignment return r-value!

## Math

It is rather simple, like everywhere else:

    val x = 2.0
    sin(x * π/4) / 2.0
    >>> 0.5

See [math](math.md) for more on it. Notice using Greek as identifier, all languages are allowed.

Logical operation could be used the same

    var x = 10
    ++x >= 11
    >>> true

## Supported operators

|    op    | ass | args              | comments |
|:--------:|-----|-------------------|----------|
|    +     | +=  | Int or Real       |          |
|    -     | -=  | Int or Real       | infix    |
|    *     | *=  | Int or Real       |          |
|    /     | /=  | Int or Real       |          |
|    %     | %=  | Int or Real       |          |
|    &&    |     | Bool              |          |
|   \|\|   |     | Bool              |          |   
|    !x    |     | Bool              |          |
|    <     |     | String, Int, Real | (1)      |
|    <=    |     | String, Int, Real | (1)      |
|    >=    |     | String, Int, Real | (1)      |
|    >     |     | String, Int, Real | (1)      |
|    ==    |     | Any               | (1)      |
|   ===    |     | Any               | (2)      |
|   !==    |     | Any               | (2)      |
|    !=    |     | Any               | (1)      |
| ++a, a++ |     | Int               |          |
| --a, a-- |     | Int               |          |

(1)
: comparison are based on comparison operator which can be overloaded

(2)
: referential equality means left and right operands references exactly same instance of some object. Note that all
singleton object, like `null`, are referentially equal too, while string different literals even being equal are most
likely referentially not equal

Reference quality and object equality example:

    assert( null == null)  // singletons
    assert( null === null)
    // but, for non-singletons:
    assert( 5 == 5)
    assert( 5 !== 5)
    assert( "foo" !== "foo" )
    >>> void

# Variables

Much like in kotlin, there are _variables_:

    var name = "Sergey"

Variables can be not initialized at declaration, in which case they must be assigned before use, or an exception
will be thrown:

    var foo
    // WRONG! Exception will be thrown at next line:
    foo + "bar"

Correct pattern is:

    foo = "foo"
    // now is OK:
    foo + bar

This is though a rare case when you need uninitialized variables, most often you can use conditional operators
and even loops to assign results (see below).

# Constants

Almost the same, using `val`:

    val foo = 1
    foo += 1 // this will throw exception

# Constants

Same as in kotlin:

    val HalfPi = π / 2

Note using greek characters in identifiers! All letters allowed, but remember who might try to read your script, most
likely will know some English, the rest is the pure uncertainty.

# Defining functions

    fun check(amount) {
        if( amount > 100 )
            "enough"
        else
            "more"
    }
    >>> Callable@...

Notice how function definition return a value, instance of `Callable`.

You can use both `fn` and `fun`. Note that function declaration _is an expression returning callable_.

There are default parameters in Ling:

    fn check(amount, prefix = "answer: ") {
        prefix + if( amount > 100 )
            "enough"
        else
            "more" 
    }
    assert( "do: more" == check(10, "do: ") )
    check(120)
    >>> "answer: enough"

## Closures

Each __block has an isolated context that can be accessed from closures__. For example:

    var counter = 1

    // this is ok: coumter is incremented
    fun increment(amount=1) {
        // use counter from a closure:
        counter = counter + amount
    }

    val taskAlias = fun someTask() {
        // this obscures global outer var with a local one
        var counter = 0
        // ...
        counter = 1
        // ...
        counter
    }
    >>> void

As was told, `fun` statement return callable for the function, it could be used as a parameter, or elsewhere
to call it:

    val taskAlias = fun someTask() {
        println("Hello")
    }
    // call the callable stored in the var
    taskAlias()
    // or directly:
    someTask()
    >>> Hello
    >>> Hello
    >>> void

If you need to create _unnamed_ function, use alternative syntax (TBD, like { -> } ?)

# Lists (aka arrays)

Ling has built-in mutable array class `List` with simple literals:

    [1, "two", 3.33].size
    >>> 3

[List] is an implementation of the type `Array`, and through it `Collection` and [Iterable].

Lists can contain any type of objects, lists too:

    val list = [1, [2, 3], 4]
    assert( list is List )      // concrete implementatino
    assert( list is Array )     // general interface
    assert(list.size == 3)
    // second element is a list too:
    assert(list[1].size == 2)
    >>> void

Notice usage of indexing. You can use negative indexes to offset from the end of the list; see more in [Lists](List.md).

When you want to "flatten" it to single array, you can use splat syntax:

    [1, ...[2,3], 4]
    >>> [1, 2, 3, 4]

Of course, you can splat from anything that is List (or list-like, but it will be defined later):

    val a = ["one", "two"]
    val b = [10.1, 20.2]
    ["start", ...b, ...a, "end"]
    >>> ["start", 10.1, 20.2, "one", "two", "end"]

Of course, you can set any list element:

    val a = [1, 2, 3]
    a[1] = 200
    a
    >>> [1, 200, 3]

Lists are comparable, and it works well as long as their respective elements are:

    assert( [1,2,3] == [1,2,3])
    
    // but they are _different_ objects:
    assert( [1,2,3] !== [1,2,3])
    
    // when sizes are different, but common part is equal,
    // longer is greater
    assert( [1,2,3] > [1,2] )

    // otherwise, where the common part is greater, the list is greater:
    assert( [1,2,3] < [1,3] )
    >>> void

The simplest way to concatenate lists is using `+` and `+=`:

    // + works to concatenate iterables: 
    assert( [5, 4] + ["foo", 2] == [5, 4, "foo", 2])
    var list = [1, 2]
    
    // append allow adding iterables: all elements of it:
    list += [2, 1]      
    // or you can append a single element:
    list += "end"
    assert( list == [1, 2, 2, 1, "end"])
    >>> void

***Important note***: the pitfall of using `+=` is that you can't append in [Iterable] instance as an object: it will always add all its contents. Use `list.add` to add a single iterable instance:

    var list = [1, 2]
    val other = [3, 4]

    // appending lists is clear:
    list += other
    assert( list == [1, 2, 3, 4] )
    
    // but appending other Iterables could be confusing:
    list += (10..12)
    assert( list == [1, 2, 3, 4, 10, 11, 12])
    >>> void

Use `list.add` to avoid confusion:

    var list = [1, 2]
    val other = [3, 4]

    // appending lists is clear:
    list.add(other)
    assert( list == [1, 2, [3, 4]] )
    
    // but appending other Iterables could be confusing:
    list.add(10..12)
    assert( list == [1, 2, [3, 4], (10..12)])
    >>> void


To add elements to the list:

    val x = [1,2]
    x.add(3)
    assert( x == [1,2,3])
    // same as x += ["the", "end"] but faster:
    x.add("the", "end")
    assert( x == [1, 2, 3, "the", "end"])
    >>> void

Self-modifying concatenation by `+=` also works:

    val x = [1, 2]
    x += [3, 4]
    assert( x == [1, 2, 3, 4])
    >>> void

You can insert elements at any position using `addAt`:

    val x = [1,2,3]
    x.addAt(1, "foo", "bar")
    assert( x == [1, "foo", "bar", 2, 3])
    >>> void

Using splat arguments can simplify inserting list in list:

    val x = [1, 2, 3]
    x.addAt( 1, ...[0,100,0])
    x
    >>> [1, 0, 100, 0, 2, 3]

Using negative indexes can insert elements as offset from the end, for example:

    val x = [1,2,3]
    x.addAt(-1, 10)
    x
    >>> [1, 2, 10, 3]

Note that to add to the end you still need to use `add` or positive index of the after-last element:

    val x = [1,2,3]
    x.addAt(3, 10)
    x
    >>> [1, 2, 3, 10]

## Removing list items

    val x = [1, 2, 3, 4, 5]
    x.removeAt(2)
    assert( x == [1, 2, 4, 5])
    // or remove range (start inclusive, end exclusive):
    x.removeRangeInclusive(1,2)    
    assert( x == [1, 5])
    >>> void

Again, you can use negative indexes. For example, removing last elements like:

    val x = [1, 2, 3, 4, 5]

    // remove last:
    x.removeAt(-1)
    assert( x == [1, 2, 3, 4])
    
    // remove 2 last:
    x.removeRangeInclusive(-2,-1)
    assert( x == [1, 2])
    >>> void

# Flow control operators

## if-then-else

As everywhere else, and as expression:

    val count = 11
    if( count > 10 )
        println("too much")
    else {
        // do something else
        println("just "+count)
    }
    >>> too much
    >>> void

Notice returned value `void`: it is because of `println` have no return value, e.g., `void`.

Or, more neat:

    var count = 3
    println( if( count > 10 ) "too much" else "just " + count )
    >>> just 3
    >>> void

## while

Regular pre-condition while loop, as expression, loop returns it's last line result:

    var count = 0
    while( count < 5 ) {
        count++
        count * 10
    }
    >>> 50

We can break as usual:

    var count = 0
    while( count < 5 ) {
        if( count < 5 ) break
        count = ++count * 10
    }
    >>> void

Why `void`? Because `break` drops out without the chute, not providing anything to return. Indeed, we should provide
exit value in the case:

    var count = 0
    while( count < 50 ) {
        if( count > 3 ) break "too much"
        count = ++count * 10
        "wrong "+count
    }
    >>> "too much"

### Breaking nested loops

If you have several loops and want to exit not the inner one, use labels:

    var count = 0
    // notice the label:
    outerLoop@ while( count < 5 ) {
        var innerCount = 0
        while( innerCount < 100 ) {
            innerCount = innerCount + 1

            if( innerCount == 5 && count == 2 )
                // and here we break the labelled loop:
                break@outerLoop "5/2 situation"
        }
        count = count + 1
        count * 10
    }
    >>> "5/2 situation"

### and continue

We can skip the rest of the loop and restart it, as usual, with `continue` operator.

    var count = 0
    var countEven = 0
    while( count < 10 ) {
        count = count + 1
        if( count % 2 == 1) continue
        countEven = countEven + 1
    }
    "found even numbers: " + countEven
    >>> "found even numbers: 5"

`continue` can't "return" anything: it just restarts the loop. It can use labeled loops to restart outer ones:

    var count = 0
    var total = 0
    // notice the label:
    outerLoop@ while( count < 5 ) {
        count = count + 1
        var innerCount = 0
        while( innerCount < 10 ) {
            innerCount = innerCount + 1
            if( innerCount == 10 )
                continue@outerLoop
        }
        // we don't reach it because continue above restarts our loop
        total = total + 1
    }
    total
    >>> 0

Notice that `total` remains 0 as the end of the outerLoop@ is not reachable: `continue` is always called and always make
Ling to skip it.

## else statement

The while and for loops can be followed by the else block, which is executed when the loop
ends normally, without breaks. It allows override loop result value, for example,
to not calculate it in every iteration. See for loop example just below.

## For loops

For loop are intended to traverse collections, and all other objects that supports
size and index access, like lists:

    var letters = 0
    for( w in ["hello", "wolrd"]) {
        letters += w.length
    }
    "total letters: "+letters
    >>> "total letters: 10"

For loop support breaks the same as while loops above:

    fun search(haystack, needle) {    
        for(ch in haystack) {
            if( ch == needle) 
                break "found"
        }
        else null
    }
    assert( search("hello", 'l') == "found")
    assert( search("hello", 'z') == null)
    >>> void

We can use labels too:

    fun search(haystacks, needle) {    
        exit@ for( hs in haystacks ) {
                for(ch in hs ) {
                    if( ch == needle) 
                        break@exit "found"
                }
            }
            else null
    }
    assert( search(["hello", "world"], 'l') == "found")
    assert( search(["hello", "world"], 'z') == null)
    >>> void

# Self-assignments in expression

There are auto-increments and auto-decrements:

    var counter = 0
    assert(counter++ * 100 == 0)
    assert(counter == 1)
    >>> void

but:

    var counter = 0
    assert( ++counter * 100 == 100)
    assert(counter == 1)
    >>> void

The same with `--`:

    var count = 100
    var sum = 0
    while( count > 0 ) sum = sum + count--
    sum
    >>> 5050

There are self-assigning version for operators too:

    var count = 100
    var sum = 0
    while( count > 0 ) sum += count--
    sum
    >>> 5050

# Ranges

Ranges are convenient to represent the interval between two values:

    5 in (0..100)
    >>> true

It could be open and closed:

    assert( 5 in (1..5) )
    assert( 5 !in (1..<5) )
    >>> void

Ranges could be inside other ranges:

    assert( (2..3) in (1..10) )
    >>> void

There are character ranges too:

    'd' in 'a'..'e'
    >>> true

and you can use ranges in for-loops:

    for( x in 'a' ..< 'c' ) println(x)
    >>> a
    >>> b
    >>> void

See [Ranges](Range.md) for detailed documentation on it.

# Comments

    // single line comment
    var result = null // here we will store the result
    >>> void

# Integral data types

| type   | description                     | literal samples     |
|--------|---------------------------------|---------------------|
| Int    | 64 bit signed                   | `1` `-22` `0x1FF`   |
| Real   | 64 bit double                   | `1.0`, `2e-11`      |
| Bool   | boolean                         | `true` `false`      |
| Char   | single unicode character        | `'S'`, `'\n'`       |
| String | unicode string, no limits       | "hello" (see below) |
| List   | mutable list                    | [1, "two", 3]       |
| Void   | no value could exist, singleton | void                |
| Null   | missing value, singleton        | null                |
| Fn     | callable type                   |                     |

See also [math operations](math.md)

## Character details

The type for the character objects is `Char`.

### Char literal escapes

Are the same as in string literals with little difference:

| escape | ASCII value       |
|--------|-------------------|
| \n     | 0x10, newline     |
| \t     | 0x07, tabulation  |
| \\     | \ slash character |
| \'     | ' apostrophe      |

### Char instance members

    assert( 'a'.code == 0x61 ) 
    >>> void

| member | type | meaning                        |
|--------|------|--------------------------------|
| code   | Int  | Unicode code for the character |
|        |      |                                |


## String details

### String operations

Concatenation is a `+`: `"hello " + name` works as expected. No confusion.

### Literals

String literal could be multiline:

    "Hello
    World"

though multiline literals is yet work in progress.

# Built-in functions

See [math functions](math.md). Other general purpose functions are:

| name                                         | description                                              |
|----------------------------------------------|----------------------------------------------------------|
| assert(condition,message="assertion failed") | runtime code check. There will be an option to skip them |
| println(args...)                             | Open for overriding, it prints to stdout.                |

# Built-in constants

| name                                | description                  |
|-------------------------------------|------------------------------|
| Real, Int, List, String, List, Bool | Class types for real numbers |
| π                                   | See [math](math.md)          |

[List]: List.md
[Iterable]: Iterable.md
[Iterator]: Iterator.md
[Real]: Real.md
[Range]: Range.md