+list + / += Iterable

+CLI app started

docs/Iterable.md

@@ -15,7 +15,13 @@ Just remember at this stage typed declarations are not yet supported.
 
 Having `Iterable` in base classes allows to use it in for loop. Also, each `Iterable` has some utility functions available:
 
-## toList()
+## Abstract methods
+
+    fun iterator(): Iterator
+
+## Instance methods
+
+### toList()
 
 Creates a list by iterating to the end. So, the Iterator should be finite to be used with it.
 

docs/Iterator.md

@@ -0,0 +1,29 @@
+# Iterator interface
+
+Iterators are representing the [Iterable] entity, to access its contents
+sequentially. 
+
+To implement the iterator you need to implement only two abstract methods:
+
+## Abstract methods
+
+### hasNext(): Bool
+
+Should return `true` if call to `next()` will return valid next element.
+
+### next(): Obj
+
+Should return next object in the iterated entity. If there is no next method,
+must throw `ObjIterationFinishedError`.
+
+## Usage
+
+Iterators are returned when implementing [Iterable] interface.
+
+## Implemented for classes:
+
+- [List], [Range]
+
+[List]: List.md
+[Range]: Range.md
+[Iterable]: Iterable.md

docs/List.md

@@ -30,9 +30,35 @@ __Important__ negative indexes works wherever indexes are used, e.g. in insertio
 
 ## Concatenation
 
+You can concatenate lists or iterable objects:
+
     assert( [4,5] + [1,2] == [4,5,1,2])
+    assert( [4,5] + (1..3) == [4, 5, 1, 2, 3])
     >>> void
 
+## Appending
+
+To append to lists, use `+=` with elements, lists and any [Iterable] instances, but beware it will concatenate [Iterable] objects instead of appending them. To append [Iterable] instance itself, use `list.add`:
+
+    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])
+
+    // now adding list as sublist:
+    list.add(other)
+    assert( list == [1, 2, 3, 4, 10, 11, 12, [3,4]])
+
+    >>> void
+
+
+
 ## Comparisons
 
     assert( [1, 2] != [1, 3])

docs/Range.md

@@ -77,7 +77,6 @@ You can use Char as both ends of the closed range:
     val r = 'a' .. 'c'
     assert( 'b' in r)
     assert( 'e' !in r)
-    assert( 'c' == r[2] )
     for( ch in r )
         println(ch)
     >>> a

docs/tutorial.md

@@ -278,9 +278,13 @@ 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)
@@ -307,7 +311,7 @@ Of course, you can set any list element:
     a
     >>> [1, 200, 3]
 
-Lists are comparable, as long as their respective elements are:
+Lists are comparable, and it works well as long as their respective elements are:
 
     assert( [1,2,3] == [1,2,3])
     
@@ -322,11 +326,48 @@ Lists are comparable, as long as their respective elements are:
     assert( [1,2,3] < [1,3] )
     >>> void
 
-All comparison operators with list are working ok. Also, you can concatenate lists:
+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]
@@ -696,6 +737,10 @@ See [math functions](math.md). Other general purpose functions are:
 | 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