fixed some comments

doc/manual.md

@@ -55,20 +55,18 @@ Vyse supports the following operators, from highest to lowest precedence:
 ```
 
 ## Variables
-
 Variables behave very similar to javascript. Can be declared with `let` and `const`,
 and can hold values of any type.
 
 ```lua
-let mynum = 123; -- mutable declaration is done with 'let'
-mynum = 456; -- assignment with '='
+let mynum = 123;        --  mutable declaration is done with 'let'
+mynum = 456;            -- assignment with '='
 const my_other_num = 1; -- variables declared with `const` cannot be reassigned to.
 ```
 
 ## Control Flow.
-
 Vyse supports the following control flow statements:
-if-else if-else, for, while, do..while.
+if-else if-else, for, while.
 
 If statements are very straightforward:
 
@@ -133,7 +131,6 @@ for item in my_array {
 ```
 
 ## Functions
-
 Functions are declared using the `fn` keyword and like most languages,
 called using the `()` operator.
 
@@ -181,8 +178,7 @@ Output: `Hello, Bob. Good morning!`
 Functions can be called with less or more number of arguments
 than mentioned in the definition.
 
-1. When called with fewer arguments, the missing arguments are assumed to be
-   `nil`.
+1. When called with fewer arguments, the missing arguments are assumed to be `nil`.
 2. When called with more arguments, the extra parameters are simply ignored.
 
 For example:
@@ -198,13 +194,12 @@ log(5, 10); -- 5
 ```
 
 ## Rest parameter.
-
 Functions can optionally contain a `rest` parameter, which can stand for any
 number of parameters. Note that the `rest` parameter must be the last in
 parameter list.
 
 ```rs
-fn log(...xs) {
+fn log(xs...) {
   for x in xs {
     print(x)
   }
@@ -279,13 +274,12 @@ parmeter passed to the function is the caller itself. In this case, it is
 exactly identical to saying `Cat.meow(Cat)`.
 
 ## Parent objects.
-
 An object can have parent objects, when a certain property is not found
 in an object itself, the parent is queried for the property.
 
 ```lua
 const t_parent = { a: 1, b: 2 };
-const t_child = { a: 3 };
+const t_child  = { a: 3 };
 
 print(t_child.a, t_child.b); -- 3, nil
 setproto(t_child, t_parent); -- set t_child's prototype to t_parent
@@ -296,7 +290,6 @@ This design is inspired by Lua and can be used to simulate some OOP features,
 like method overriding.
 
 ## Operator overloads
-
 Many vyse operators can be overloaded to perform different actions.
 The overloading methods must exist somewhere up in the parent object hierarchy.
 Eg -
@@ -317,14 +310,14 @@ let c = a + b
 
 Upon running the above code, we get:
 ```
-ERROR: cannot use operator '+' on operands of type 'table' and 'table'.
+ERROR: Bad operand types for operator '+': 'table' and 'table'.
 ```
 
 The above code will throw an error since we can't add two tables.
-To remedy the error, we introduce a metamethod that overloads the `+` operator:
+To remedy the error, we introduce a magic method that overloads the `+` operator:
 
 ```rs
-fn Point.__add(a, b) {
+Point.__add = fn (a, b) {
   return Point:init(a.x + b.x, a.y + b.y);
 }
 
@@ -340,7 +333,6 @@ and the method names is listed below for reference:
 | Operator   | Method     | Arity |
 | :--------- | :--------- | :---- |
 | +          | \_\_add    | 2     |
-| + (unary)  | \_\_unp    | 1     |
 | -          | \_\_sub    | 2     |
 | - (unary)  | \_\_unm    | 1     |
 | /          | \_\_div    | 2     |
@@ -357,9 +349,10 @@ and the method names is listed below for reference:
 | <<         | \_\_bsl    | 2     |
 | >>         | \_\_bsr    | 2     |
 | ~          | \_\_bnot   | 1     |
-| .          | \_\_indx   | 2     |
+| .          | \_\_get    | 2     |
+| []         | \_\_index  | 2     |
 | ==         | \_\_eq     | 2     |
 | !=         | \_\_neq    | 2     |
 | ..         | \_\_concat | 2     |
 | ()         | \_\_call   | any   |
-| (tostring) | \_\_tostr  | 1     |
+| (tostring) | \_\_str    | 1     |

lang/include/vyse/x_opcode.hpp

@@ -25,7 +25,7 @@ OP(get_upval, 1, 1),
 OP(make_func, -1, 1), /* special arity */
 OP(prep_method_call, 1, 1),
 
-// Note that calling function pushes a new call 
+// Note that calling function pushes a new call
 // frame onto the stack, therefore it does not count
 // as incrementing the stack size of the *current*
 // closure.
@@ -56,7 +56,7 @@ OP(lte, 0, -1),
 /// Insert the value at PEEK(1) into the array PEEK(2)
 /// and pop top
 /// el = POP()
-/// arr = PEEK(1) 
+/// arr = PEEK(1)
 /// arr:push(el)
 OP(list_append, 0, -1),
 
@@ -73,21 +73,50 @@ OP(return_val, 0, 0), /* special stack effect */
 
 
 // table indexing
-OP(new_table, 0, 1),
-OP(new_list, 0, 1),
+OP(new_table, 0, 1), // create a new table and push it onto the stack
+OP(new_list, 0, 1),  // create a new list  and push it onto the stack
+
+/// value = POP()
+/// k     = POP()
+/// t     = POP()
+/// t[k]  = value
+/// PUSH(value)
 OP(index_set, 0, -2),
+
+// when the stack state is [ LIST, KEY, VALUE ],
+// VALUE = POP(); KEY = POP(); LIST = POP();
+// LIST[KEY] = VALUE
 OP(table_add_field, 0, -2),
+
+// INDEX = POP(); LIST = POP();
+// PUSH(LIST[INDEX])
 OP(index, 0, -1),
+
+// INDEX = PEEK(1); LIST = PEEK(2);
+// PUSH(LIST[INDEX])
 OP(index_no_pop, 0, 1),
 
+// A  = NEXT(); B = NEXT();
+// ip = ip + AB
 OP(jmp, 2, 0),
+
+// A  = NEXT(); B = NEXT();
+// ip = ip - AB
 OP(jmp_back, 2, 0),
 OP(jmp_if_false_or_pop, 2, 0), /* -1 if TOS is truthy */
 OP(jmp_if_true_or_pop, 2, 0),  /* -1 if TOS is falsy */
 OP(pop_jmp_if_false, 2, -1),
 
 
-/// TODO: explain stuff
+/// Ensures the counter, limit, and step are numbers,
+/// and pushes the counter variable used by the user
+/// onto the stack. At this point, the state of the stack is:
+/// [ counter, limit, step ]
+/// i_      = PEEK(3)
+/// step    = PEEK(1)
+/// counter = counter - step
+/// PUSH(counter) ; this is the variable i, that is used by the user
+/// ip = ip + FETCH_SHORT()
 OP(for_prep, 2, 1),
 
 /// Operands:  A, B (Jump distance)
@@ -101,4 +130,5 @@ OP(for_prep, 2, 1),
 ///   ip -= AB
 OP(for_loop, 2, 0),
 
-OP(no_op, -1, 0),
+OP(no_op, -1, 0),
+

lang/src/loadlib.cpp

@@ -89,7 +89,7 @@ void DynLoader::init_loaders(VM& vm) const {
 	CClosure& cached_lib_loader = vm.make<CClosure>(load_cached_module);
 	loaders.append(VYSE_OBJECT(&cached_lib_loader));
 
-	// // Add the default standard library module loader.
+	// Add the default standard library module loader.
 	CClosure& stdlib_loader = vm.make<CClosure>(load_std_module);
 	loaders.append(VYSE_OBJECT(&stdlib_loader));
 }