improved list docs

docs/basics/blocks.md

@@ -1,19 +1,27 @@
 # Code blocks
 
-## Inlining
+The main logic compartmentalization mechanism in Blombly are code blocks; these are flexible coding segments that can be treated as methods, used to define various control flows, or called inline. 
+Code blocks are declared by enclosing some code in brackets and assigning them to a variable. 
+
+There is no trailing semicolon, and the compiler will create an error if you do try to add one so that only one syntax is promoted. 
+Block declaration only sets a variable and does not execute code. As a good practice, prefer making blocks final for visibility and to ensure logic safety.
 
-The main logic compartmentalization mechanism in Blombly are code blocks; these are flexible coding segments that can be treated as methods, used to define various control flows, or called inline. Code blocks are declared by enclosing them in brackets and assigning them to a variable, like below. Notice that there is no trailing semicolon, and the compiler will create an error if you do try to add one, under the principle of "one solution". The declaration can also be final to make sure that the same variable always points to the particular block in the current scope, and that method calls starting from the scope have access to it.
 
-The declaration itself only sets a variable. But you can effectively "paste" a block's internal code to the current position by using the block's name followed by double dots ()`:`). This is called inline execution and demonstrated below. Inlining has full access to variables in the current scope (both for usage and modification). The main usage pattern is to enrich your current code with a snippet defined elsewhere, which may also change dynamically.
+## Inlining
+
+One can "paste" a block's internal code to the current position by using the block's name followed by double dots (`:`). 
+This is called inlining and demonstrated below. The inlined block has full access to variables for usage and modification. 
+This way, it enriches the current code with a snippet that is defined elsewhere, and which may also change dynamically.
 
 ```java
 // main.bb
-test = { 
+final test = {
     print("Hello world"); 
 } 
 test:
 ```
 
+
 ## Specifications
 
 We tackle usage of code blocks as methods in the next section. For now, let us see how to declare and retrieve some specification for them. In the simplest case, Blombly offers the dot . notation, like the language's structs described in section 2.5 to read and write specification data. The latter differ from struct fields in that they declare immutable properties, like documentation and source code versions. When assigning specifications without evoking a preprocessor directive, use the final keyword to signify their immutable nature. For logic safety, an error will occur otherwise. Here is an example usage:

docs/basics/iterables.md

@@ -9,18 +9,21 @@ that helps loops iterate through elements.
 
 Declare lists by separating values with a comma and access and set
 its elements with square brackets (`[...]`) where element indexes
-start from zero. Here is an example:
+start from zero. Here is an example that also demonstrates usage of
+the `len` builtin to obtain the number of list elements:
 
 ```java
 // main.bb
 A = 1,2,3;
 A[0] = 4;
 print(A);
+print(len(A));
 ```
 
 ```bash
 > blombly main.bb
 [4, 2, 3]
+3
 ```
 
 You may initialize lists based on their size and gradually fill
@@ -43,7 +46,50 @@ Element at position 1 not set
 [0,  ,  , 0, 0]
 ```
 
+The above examples do not modify list size while running. 
+But Blombly also offers operators that do so, and in fact let you treat lists 
+like stacks or queues too. In particular, use the `next` and `pop` operators 
+to extract and remove the first and last list elements. These yield a missing value
+if the list is empty, so the `as` operator in a loop can
+extract list elements until either a missing one is found or the whole
+list is consumed:
+
+```bash
+// main.bb
+A = 1,2,3;
+while(a as next(A)) 
+    print(a);
+```
+
+```bash
+> blombly main.bb
+1
+2
+3
+```
+
+Append list elements using the `push` operator.  This 
+
 ## Iterators
 
-*This section is under construction.*
+Given any data structure, such as a list, that accepts an element getter and length methods,
+you can create an iterator to travers through its elements wihtout modifying the structure. 
+Obtain an iterator with the `iter` operation as in the example below. Iterators admit only the 
+`next` operator and cannot modify data, expose random access, or restart.
+
+```java
+// main.bb
+A = 1,2,3;
+it = iter(A);
+while(i as next(it)) 
+    print(i);
+```
+
+
+## Vectors
+
+*This segment is unders construction.*
+
+## Maps
 
+*This segment is unders construction.*

main.bb

@@ -6,7 +6,6 @@ test = {
 show = {
     while(i as next(it)) 
         print(i);
-
 }
 
 final it = test();

src/utils/parser.cpp

@@ -673,7 +673,7 @@ class Parser {
                 return var;
             }
 
-            if (first_name == "std::push") {
+            if (first_name == "std::push" || first_name=="push") {
                 bbassert(tokens[start + 1].name == "(", "Missing ( just after `" + first_name+"`.\n"+show_position(start+1));
                 bbassert(find_end(start + 2, end, ")") == end, "Leftover code after the last `)` for `" + first_name+"`.\n"+show_position(start+2));
                 int separator = find_end(start + 2, end, ",");
@@ -687,14 +687,14 @@ class Parser {
             if (first_name == "std::len" || first_name == "std::iter" || 
                 first_name == "std::int" || first_name == "std::float" || 
                 first_name == "std::str" || first_name == "std::bool" || 
-                first_name == "std::push" || first_name == "std::pop" || 
+                first_name == "std::pop" || 
                 first_name == "std::file" || first_name == "std::next" || 
                 first_name == "std::list" || first_name == "std::map" || 
                 first_name == "std::server" || first_name == "std::vector" ||
                 first_name == "len" || first_name == "iter" || 
                 first_name == "int" || first_name == "float" || 
                 first_name == "str" || first_name == "bool" || 
-                first_name == "push" || first_name == "pop" || 
+                first_name == "pop" || 
                 first_name == "file" || first_name == "next" || 
                 first_name == "list" || first_name == "map" || 
                 first_name == "server" || first_name == "vector") {