Merge branch 'master' into 1.17

docs/scarpet/api/Entities.md

@@ -422,6 +422,10 @@ Numbers related to player's xp. `xp` is the overall xp player has, `xp_level` is
 
 Number indicating remaining entity health, or `null` if not applicable.
 
+### `query(e, 'language')`
+
+Returns `null` for any non-player entity, if not returns the player's language as a string.
+
 ### `query(e, 'holds', slot?)`
 
 Returns triple of short name, stack count, and NBT of item held in `slot`, or `null` if nothing or not applicable. Available options for `slot` are:

docs/scarpet/language/FunctionsAndControlFlow.md

@@ -267,6 +267,7 @@ but like everywhere else, doing that sounds like a bad idea.
   - `io_exception`: This is the parent for any exception that occurs due to an error handling external data.
     - `nbt_error`: Incorrect input/output NBT file.
     - `json_error`: Incorrect input/output JSON data.
+    - `b64_error`: Incorrect input/output b64 (base 64) string
   - `user_exception`: Exception thrown by default with `throw` function.
   
 Synopsis:

docs/scarpet/language/LoopsAndHigherOrderFunctions.md

@@ -146,3 +146,4 @@ it will be used from now on as a new value for the accumulator.
 reduce([1,2,3,4],_a+_,0)  => 10
 reduce([1,2,3,4],_a*_,1)  => 24
 </pre>
+

docs/scarpet/language/Operators.md

@@ -243,16 +243,34 @@ identical with `fun(1, 2, 3)`. For maps, it unpacks them to a list of key-value
 
 In function signatures it identifies a vararg parameter. 
 
-`fun(a, b, ... rest) -> [a, b, rest]; fun(1, 2, 3, 4)`  => `[1, 2, [3, 4]]`
+<pre>
+fun(a, b, ... rest) -> [a, b, rest]; fun(1, 2, 3, 4)    => [1, 2, [3, 4]]
+</pre>
 
 Effects of `...` can be surprisingly lasting. It is kept through the use of variables and function calls.
 
-`fun(a, b, ... rest) -> [a, b, ... rest]; fun(1, 2, 3, 4)`  => `[1, 2, 3, 4]`
-`args() -> ... [1, 2, 3]; sum(a, b, c) -> a+b+c; sum(args())` => `6`
-`a = ... [1, 2, 3]; sum(a, b, c) -> a+b+c; sum(a)` => `6`
+<pre>
+fun(a, b, ... rest) -> [a, b, ... rest]; fun(1, 2, 3, 4)    => [1, 2, 3, 4]
+args() -> ... [1, 2, 3]; sum(a, b, c) -> a+b+c; sum(args())   => 6
+a = ... [1, 2, 3]; sum(a, b, c) -> a+b+c; sum(a)   => 6
+</pre>
 
 Unpacking mechanics can be used for list and map constriction, not just for function calls.
 
-`[...range(5), pi, ...range(5,-1,-1)]` => `[0, 1, 2, 3, 4, 3.14159265359, 5, 4, 3, 2, 1, 0]`
-`{ ... map(range(5),  _  -> _*_ )}` => `{0: 0, 1: 1, 2: 4, 3: 9, 4: 16}`
-`{...{1 -> 2, 3 -> 4}, ...{5 -> 6, 7 -> 8}}` => `{1: 2, 3: 4, 5: 6, 7: 8}`
+<pre>
+[...range(5), pi, ...range(5,-1,-1)]   => [0, 1, 2, 3, 4, 3.14159265359, 5, 4, 3, 2, 1, 0]
+{ ... map(range(5),  _  -> _*_ )}   => {0: 0, 1: 1, 2: 4, 3: 9, 4: 16}
+{...{1 -> 2, 3 -> 4}, ...{5 -> 6, 7 -> 8}}   => {1: 2, 3: 4, 5: 6, 7: 8}
+</pre>
+
+Fine print: unpacking of argument lists happens just before functions are evaluated. 
+This means that in some situations, for instance 
+when an expression is expected (`map(list, expr)`), or a function should not evaluate some (most!) of its arguments (`if(...)`), 
+unpacking cannot be used, and will be ignored, leaving `... list` identical to `list`. 
+Functions that don't honor unpacking mechanics, should have no use for it at the first place
+ (i.e. have one, or very well-defined, and very specific parameters), 
+so some caution (prior testing) is advised. Some of these multi-argument built-in functions are
+ `if`, `try`, `sort_key`, `system_variable_get`, `synchronize`, `sleep`, `in_dimension`, 
+all container functions (`get`, `has`, `put`, `delete`), 
+and all loop functions (`while`, `loop`, `map`, `filter`, `first`, `all`, `c_for`, `for` and`reduce`).
+ 

docs/scarpet/language/SystemFunctions.md

@@ -350,6 +350,15 @@ This will give you a date:
 
 It is currently `hrs`:`mins` and `secs` seconds on the `date`th of `month`, `year`
 
+### `encode_b64(string)`, `decode_b64(string)`
+
+Encode or decode a string from b64, throwing a `b64_error` exception if it's invalid
+
+### `encode_json(value)`, `decode_json(string)`
+
+Encodes a value as a json string, and decodes a json string as a valid value, throwing a `json_error` exception if it 
+doesn't parse properly
+
 ### `profile_expr(expression)`
 
 Returns number of times given expression can be run in 50ms time. Useful to profile and optimize your code.