Merge branch '1.8.x'

.gitignore

@@ -1,7 +1,9 @@
 docs/_site
 *.ignore
+test-ignore-*
 vendor
 builds/*
 !builds/.gitkeep
 .idea/
 .vscode/
+packages.abs.json

.travis.yml

@@ -6,7 +6,7 @@ os:
   - osx
 
 go:
-  - "1.12.x"
+  - "1.13.x"
 
 before_script:
 - go get -u 

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.

Dockerfile

@@ -1,4 +1,4 @@
-FROM golang:1.12
+FROM golang:1.13
 
 RUN apt-get update
 RUN apt-get install bash make git curl jq -y

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/_includes/toc.md

@@ -28,6 +28,7 @@
 
 ## Miscellaneous
 
+* [Installing 3rd party libraries](/misc/3pl)
 * [Errors](/misc/error)
 * [Configuring the REPL](/misc/configuring-the-repl)
 * [Runtime](/misc/runtime)

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/misc/3pl.md

@@ -0,0 +1,92 @@
+# Installing 3rd party libraries
+
+The ABS interpreter comes with a built-in installer for 3rd party libraries,
+very similar to `npm install`, `pip install` or `go get`.
+
+The installer, budled since the `1.8.0` release, is currently **experimental**
+and a few things might change.
+
+In order to install a package, you simply need to run `abs get`:
+
+``` bash
+$ abs get github.com/abs-lang/abs-sample-module 
+🌘  - Downloading archive
+Unpacking...
+Creating alias...
+Install Success. You can use the module with `require("abs-sample-module")`
+```
+
+Modules will be saved under the `vendor/$MODULE-master` directory. Each module
+also gets an alias to facilitate requiring them in your code, meaning that
+both of these forms are supported:
+
+```
+⧐  require("abs-sample-module/sample.abs")
+{"another": f() {return hello world;}}
+
+⧐  require("vendor/github.com/abs-lang/abs-sample-module-master/sample.abs")
+{"another": f() {return hello world;}}
+```
+
+Note that the `-master` prefix [will be removed](https://github.com/abs-lang/abs/issues/286) in future versions of ABS.
+
+Module aliases are saved in the `packages.abs.json` file
+which is created in the same directory where you run the
+`abs get ...` command:
+
+```
+$ abs get github.com/abs-lang/abs-sample-module
+🌗  - Downloading archive
+Unpacking...
+Creating alias...
+Install Success. You can use the module with `require("abs-sample-module")`
+
+$ cat packages.abs.json 
+{
+    "abs-sample-module": "./vendor/github.com/abs-lang/abs-sample-module-master"
+}
+```
+
+If an alias is already taken, the installer will let you know that you
+will need to use the full path when requiring the module:
+
+```
+$ echo '{"abs-sample-module": "xyz"}' > packages.abs.json 
+
+$ abs get github.com/abs-lang/abs-sample-module
+🌘  - Downloading archive
+Unpacking...
+Creating alias...This module could not be aliased because module of same name exists
+
+Install Success. You can use the module with `require("./vendor/github.com/abs-lang/abs-sample-module-master")`
+```
+
+When requiring a module, ABS will try to load the `index.abs` file unless
+another file is specified:
+
+```
+$ ~/projects/abs/builds/abs                                          
+Hello alex, welcome to the ABS (1.8.0) programming language!
+Type 'quit' when you're done, 'help' if you get lost!
+
+⧐  require("abs-sample-module")
+{"another": f() {return hello world;}}
+
+⧐  require("abs-sample-module/index.abs")
+{"another": f() {return hello world;}}
+
+⧐  require("abs-sample-module/another.abs")
+f() {return hello world;}
+```
+
+## Supported hosting platforms
+
+Currently, the installer supports modules hosted on:
+
+* GitHub
+
+## Next
+
+That's about it for this section!
+
+You can now head over to read a little bit about [errors](/misc/error).

docs/misc/technical-details.md

@@ -1,6 +1,6 @@
 # A few technical details...
 
-The ABS interpreter is built with Golang version `1.11`, and is mostly based on [the interpreter book](https://interpreterbook.com/) written by [Thorsten Ball](https://twitter.com/thorstenball).
+The ABS interpreter is built with Golang version `1.13`, and is mostly based on [the interpreter book](https://interpreterbook.com/) written by [Thorsten Ball](https://twitter.com/thorstenball).
 
 ABS is extremely different from Monkey, the "fictional" language the reader builds throughout the book, but the base structure (lexer, parser, evaluator) are still very much based on Thorsten's work.
 

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.
@@ -299,4 +339,4 @@ statements until changed.
 
 That's about it for this section!
 
-You can now head over to read a little bit about [errors](/misc/error).
+You can now head over to read a little bit about [how to install 3rd party libraries](/misc/3pl).