Merge 15499a4 into d3f2fcf

CONTRIBUTING.md

@@ -8,7 +8,7 @@ repository.
 
 Since we follow [semver](https://semver.org/),
 when a new feature is released we don't backport it but simply
-create a new version branch, such as `1.7.x`. Bugs, instead,
+create a new version branch, such as `1.8.x`. Bugs, instead,
 might be backported from `1.1.0` to, for example, `1.0.x` and we
 will have a new [release](https://github.com/abs-lang/abs/releases),
 say `1.0.1` for the `1.0.x` version branch.

README.md

@@ -83,7 +83,7 @@ if !res.ok {
 ip = res.json().ip
 total = ip.split(".").map(int).sum()
 if total > 100 {
-    echo("The sum of [%s] is a large number, %s.", ip, total)
+    echo("The sum of [$ip] is a large number, $total.")
 }
 ```
 

docs/README.md

@@ -80,7 +80,7 @@ if !res.ok {
 ip = res.json().ip
 total = ip.split(".").map(int).sum()
 if total > 100 {
-    echo("The sum of [%s] is a large number, %s.", ip, total)
+    echo("The sum of [$ip] is a large number, $total.")
 }
 ```
 

docs/installer.sh

@@ -27,7 +27,7 @@ if [ "${MACHINE_TYPE}" = 'x86_64' ]; then
   ARCH="amd64"
 fi
 
-VERSION=1.7.0
+VERSION=1.8.0
 
 echo "Trying to detect the details of your architecture."
 echo ""

docs/types/array.md

@@ -22,14 +22,21 @@ notation:
 array[3]
 ```
 
-Accessing an index that does not exist returns null.
+Accessing an index that does not exist returns `null`.
+
+You can also access the Nth last element of an array by
+using a negative index:
+
+``` bash
+["a", "b", "c", "d"][-2] # "c"
+```
 
 You can also access a range of indexes with the `[start:end]` notation:
 
 ``` bash
 array = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 
-array[0:2] // [0, 1, 2]
+array[0:2] # [0, 1, 2]
 ```
 
 where `start` is the starting position in the array, and `end` is
@@ -38,14 +45,14 @@ and if `end` is omitted it is assumed to be the last index in the
 array:
 
 ``` bash
-array[:2] // [0, 1, 2]
-array[7:] // [7, 8, 9]
+array[:2] # [0, 1, 2]
+array[7:] # [7, 8, 9]
 ```
 
 If `end` is negative, it will be converted to `length of array - end`:
 
 ``` bash
-array[:-3] // [0, 1, 2, 3, 4, 5, 6]
+array[:-3] # [0, 1, 2, 3, 4, 5, 6]
 ```
 
 To concatenate arrays, "sum" them:
@@ -113,7 +120,7 @@ a # [1, 2, 3, 4, 99, 55, 66]
 An array is defined as "homogeneous" when all its elements
 are of a single type:
 
-```
+``` bash
 [1, 2, 3] # homogeneous
 [null, 0, "", {}] # heterogeneous
 ```
@@ -291,6 +298,47 @@ Sums the elements of the array. Only supported on arrays of numbers:
 [1, 1, 1].sum() # 3
 ```
 
+### tsv([separator], [header])
+
+Formats the array into TSV:
+
+``` bash
+[["LeBron", "James"], ["James", "Harden"]].tsv()
+LeBron	James
+James	Harden
+```
+
+You can also specify the separator to be used if you
+prefer not to use tabs:
+
+``` bash
+[["LeBron", "James"], ["James", "Harden"]].tsv(",")
+LeBron,James
+James,Harden
+```
+
+The input array needs to be an array of arrays or hashes. If
+you use hashes, their keys will be used as heading of the TSV:
+
+```bash
+[{"name": "Lebron", "last": "James", "jersey": 23}, {"name": "James", "last": "Harden"}].tsv()
+jersey	last	name
+23	James	Lebron
+null	Harden	James
+```
+
+The heading will, by default, be a combination of all keys present in the hashes,
+sorted alphabetically. If a key is missing in an hash, `null` will be used as value.
+If you wish to specify the output format, you can pass a list of keys to be used
+as header:
+
+```bash
+[{"name": "Lebron", "last": "James", "jersey": 23}, {"name": "James", "last": "Harden"}].tsv("\t", ["name", "last", "jersey", "additional_key"])
+name	last	jersey	additional_key
+Lebron	James	23	null
+James	Harden	null	null
+```
+
 ### unique()
 
 Returns an array with unique values:

docs/types/builtin-function.md

@@ -229,15 +229,54 @@ Halts the process for as many `ms` you specified:
 sleep(1000) # sleeps for 1 second
 ```
 
-### source(path_to_file) aka require(path_to_file) 
+### require(path_to_file.abs)
 
-Evaluates the script at `path_to_file` in the context of the ABS global
-environment. The results of any expressions in the file become
-available to other commands in the REPL command line or to other
+Evaluates the script at `path_to_file.abs`, and makes
+its return value available to the caller.
+
+For example, suppose we have a `module.abs` file:
+
+``` bash
+adder = f(a, b) { a + b }
+multiplier = f(a, b) { a * b }
+
+return {"adder": adder, "multiplier": multiplier}
+```
+
+and a `main.abs` such as:
+
+``` bash
+mod = require("module.abs")
+
+echo(mod.adder(1, 2)) # 3
+```
+
+This is mostly useful to create external library
+functions, like NPM modules or PIP packages, that
+do not have access to the global environment. Any
+variable set outside of the module will not be
+available inside it, and vice-versa. The only
+variable available to the caller (the script requiring
+the module) is the module's return value.
+
+Note that `require` uses paths that are relative to
+the current script. Say that you have 2 files (`a.abs` and `b.abs`)
+in the `/tmp` folder, `a.abs` can `require("./b.abs")`
+without having to specify the full path (eg. `require("/tmp/b.abs")`).
+
+### source(path_to_file.abs)
+
+Evaluates the script at `path_to_file.abs` in the context of the 
+ABS global environment. The results of any expressions in the file
+become available to other commands in the REPL command line or to other
 scripts in the current script execution chain. 
 
-This is most useful for creating `library functions` in a script
-that can be used by many other scripts. Often the library functions
+This is very similar to `require`, but allows the module to access
+and edit the global environment. Any variable set inside the module
+will also be available outside of it.
+
+This is most useful for creating library functions in a startup script,
+or variables that can be used by many other scripts. Often these library functions
 are loaded via the ABS Init File `~/.absrc` (see [ABS Init File](/introduction/how-to-run-abs-code)).
 
 For example:
@@ -251,7 +290,7 @@ $ cat ~/.absrc
 source("~/abs/lib/library.abs")
 
 $ abs
-Hello user, welcome to the ABS (1.7.0) programming language!
+Hello user, welcome to the ABS (1.8.0) programming language!
 Type 'quit' when you are done, 'help' if you get lost!
 ⧐ adder(1, 2)
 3
@@ -291,6 +330,7 @@ For example an ABS Init File may contain:
 ABS_SOURCE_DEPTH = 15
 source("~/path/to/abs/lib")
 ```
+
 This will limit the source inclusion depth to 15 levels for this
 `source()` statement and will also apply to future `source()`
 statements until changed.

docs/types/string.md

@@ -32,7 +32,14 @@ with the index notation:
 "hello world"[1] # e
 ```
 
-Accessing an index that does not exist returns null.
+Accessing an index that does not exist returns an empty string.
+
+You can access the Nth last character of the string using a
+negative index:
+
+``` bash
+"string"[-2] # "n"
+```
 
 You can also access a range of the string with the `[start:end]` notation:
 
@@ -42,7 +49,8 @@ You can also access a range of the string with the `[start:end]` notation:
 
 where `start` is the starting position in the array, and `end` is
 the ending one. If `start` is not specified, it is assumed to be 0,
-and if `end` is omitted it is assumed to be the character in the string:
+and if `end` is omitted it is assumed to be the last character in the
+string:
 
 ``` bash
 "string"[0:3] // "str"
@@ -75,6 +83,25 @@ To test for the existence of substrings within strings use the `in` operator:
 "xyz" in "string"   # false
 ```
 
+## Interpolation
+
+You can also replace parts of the string with variables
+declared within your program using the `$` symbol:
+
+``` bash
+file = "/etc/hosts"
+x = "File name is: $file"
+echo(x) # "File name is: /etc/hosts"
+```
+
+If you need `$` literals in your command, you
+simply need to escape them with a `\`:
+
+``` bash
+"$non_existing_var" # "" since the ABS variable 'non_existing_var' doesn't exist
+"\$non_existing_var" # "$non_existing_var"
+```
+
 ## Special characters embedded in strings
 
 Double and single quoted strings behave differently if the string contains