Merge branch 'master' of https://github.com/gnembon/fabric-carpet

docs/scarpet/Full.md

@@ -20,9 +20,9 @@ or an OVERLY complex example:
 /script run
     block_check(x1, y1, z1, x2, y2, z2, block_to_check) ->
     (
-        l(minx, maxx) = sort(l(x1, x2));
+        [minx, maxx] = sort([x1, x2]);
-        l(miny, maxy) = sort(l(y1, y2));
+        [miny, maxy] = sort([y1, y2]);
-        l(minz, maxz) = sort(l(z1, z2));
+        [minz, maxz] = sort([z1, z2]);
         'Need to compute the size of the area of course';
         'Cause this language doesn\'t support comments in the command mode';
         xsize = maxx - minx + 1;
@@ -46,7 +46,7 @@ or an OVERLY complex example:
     check_area_around_closest_player_for_block(block_to_check) ->
     (
         closest_player = player();
-        l(posx, posy, posz) = query(closest_player, 'pos');
+        [posx, posy, posz] = query(closest_player, 'pos');
         total_count = block_check( posx-8,1,posz-8, posx+8,17,posz+8, block_to_check);
         print('There is '+total_count+' of '+block_to_check+' around you')
     )
@@ -69,7 +69,7 @@ Writing a program, is like writing a `2+3`, just a bit longer.
 ## Basic language components
 
 Programs consist of constants, like `2`, `3.14`, `pi`, or `'foo'`, operators like `+`, `/`, `->`, variables which you 
-can define, like `foo` or special ones that will be defined for you, like `_x`, or `_` , which I specific to a each
+can define, like `foo` or special ones that will be defined for you, like `_x`, or `_` , which are specific to each
 built in function, and functions with name, and arguments in the form of `f(a,b,c)`, where `f` is the function name,
 and `a, b, c` are the arguments which can be any other expression. And that's all the parts of the language, so all
 in all - sounds quite simple.
@@ -470,6 +470,9 @@ in the output map.
 Functional forms of `-` and `/` have less intuitive multi-nary interpretation, but they might be useful in some situations.
 `x-y-z` resolves to `difference(x, y, z)`.
 
+`/` always produces a properly accurate result, fully reversible with `*` operator. To obtain a integer 'div' result, use
+`floor(x/y)`.
+
 Examples:
 
 <pre>
@@ -487,11 +490,15 @@ b = [100,63,100]; b+[10,0,10]  => [110,63,110]
 
 ### Just Operators `%`, `^`
 
-The modulo and exponent (power) operators work only if both operands are numbers
+The modulo and exponent (power) operators work only if both operands are numbers. `%` is a proper (and useful) 'modulus' operator,
+not a useless 'reminder' operator that you would expect from anything that touches Java. While typically modulus is reserved
+to integer numbers, scarpet expands them to floats with as much sense as possible.
 
 <pre>pi^pi%euler  => 1.124....
--9 % 4  => -1
+-9 % 4  => 3
-9 % -4  => 0 ¯\_(ツ)_/¯ Java
+9 % -4  => -3
+9.1 % -4.2  => -3.5
+9.1 % 4.2  => 0.7
 -3 ^ 2  => 9
 -3 ^ pi => // Error
 </pre>
@@ -573,8 +580,8 @@ flips boolean condition of the expression. Equivalent of `bool(expr)==false`
 !false  => true
 !null  => true
 !5  => false
-!l() => true
+![] => true
-!l(null) => false
+![null] => false
 </pre>
 
 ### `Unpacking Operator ...`
@@ -678,8 +685,8 @@ Interesting bit - `min` and `max` don't remove variable associations from argume
 LHS of assignments (obvious case), or argument spec in function definitions (far less obvious).
 
 <pre>
-a = 1; b = 2; min(a,b) = 3; l(a,b)  => [3, 2]
+a = 1; b = 2; min(a,b) = 3; [a,b]  => [3, 2]
-a = 1; b = 2; fun(x, min(a,b)) -> l(a,b); fun(3,5)  => [5, 0]
+a = 1; b = 2; fun(x, min(a,b)) -> [a,b]; fun(3,5)  => [5, 0]
 </pre>
 
 Absolutely no idea, how the latter might be useful in practice. But since it compiles, can ship it.
@@ -760,8 +767,8 @@ represent binary values.
 bool(pi) => true
 bool(false) => false
 bool('') => false
-bool(l()) => false
+bool([]) => false
-bool(l('')) => true
+bool(['']) => true
 bool('foo') => true
 bool('false') => false
 bool('nulL') => false
@@ -778,8 +785,8 @@ number(false) => 0
 number(true) => 1
 number('') => null
 number('3.14') => 3.14
-number(l()) => 0
+number([]) => 0
-number(l('')) => 1
+number(['']) => 1
 number('foo') => null
 number('3bar') => null
 number('2')+number('2') => 4
@@ -791,7 +798,7 @@ If called with one argument, returns string representation of such value.
 
 Otherwise, returns a formatted string representing the expression. Arguments for formatting can either be provided as
  each consecutive parameter, or as a list which then would be the only extra parameter. To format one list argument
- , you can use `str(list)`, or `str('foo %s', l(list))`.
+ , you can use `str(list)`, or `str('foo %s', [list])`.
 
 Accepts formatting style accepted by `String.format`. 
 Supported types (with `"%<?>"` syntax):
@@ -958,8 +965,8 @@ or length of the list
 length(pi) => 1
 length(pi*pi) => 1
 length(pi^pi) => 2
-length(l()) => 0
+length([]) => 0
-length(l(1,2,3)) => 3
+length([1,2,3]) => 3
 length('') => 0
 length('foo') => 3
 </pre>
@@ -1049,11 +1056,11 @@ Unlike the previous function, this can be used to get exact time, but it varies
 
 ### `convert_date(milliseconds)`
 ### `convert_date(year, month, date, hours?, mins?, secs?)`
-### `convert_date(l(year, month, date, hours?, mins?, secs?))`
+### `convert_date([year, month, date, hours?, mins?, secs?])`
 
 If called with a single argument, converts standard POSIX time to a list in the format: 
 
-`l(year, month, date, hours, mins, secs, day_of_week, day_of_year, week_of_year)`
+`[year, month, date, hours, mins, secs, day_of_week, day_of_year, week_of_year]`
 
 eg: `convert_date(1592401346960) -> [2020, 6, 17, 10, 42, 26, 3, 169, 25]`
 
@@ -1072,9 +1079,9 @@ Example editing:
 <pre>
 date = convert_date(unix_time());
 
-months = l('Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec');
+months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
 
-days = l('Mon','Tue','Wed','Thu','Fri','Sat','Sun');
+days = ['Mon','Tue','Wed','Thu','Fri','Sat','Sun'];
 
 print(
   str('Its %s, %d %s %d, %02d:%02d:%02d', 
@@ -1137,7 +1144,7 @@ used for object counting
 <pre>
 /script run
 $ count_blocks(ent) -> (
-$   l(cx, cy, cz) = query(ent, 'pos');
+$   [cx, cy, cz] = query(ent, 'pos');
 $   scan(cx, cy, cz, 16, 16, 16, var('count_'+_) += 1);
 $   for ( sort_key( vars('count_'), -var(_)),
 $     print(str( '%s: %d', slice(_,6), var(_) ))
@@ -1234,7 +1241,7 @@ Evaluates expression `expr`, `num` number of times. code>expr receives `_` syste
 
 <pre>
 loop(5, game_tick())  => repeat tick 5 times
-list = l(); loop(5, x = _; loop(5, list += l(x, _) ) ); list
+list = []; loop(5, x = _; loop(5, list += [x, _] ) ); list
   // double loop, produces: [[0, 0], [0, 1], [0, 2], [0, 3], [0, 4], [1, 0], [1, 1], ... , [4, 2], [4, 3], [4, 4]]
 </pre>
 
@@ -1242,7 +1249,7 @@ In this small example we will search for first 10 primes, apparently including 0
 
 <pre>
 check_prime(n) -> !first( range(2, sqrt(n)+1), !(n % _) );
-primes = l();
+primes = [];
 loop(10000, if(check_prime(_), primes += _ ; if (length(primes) >= 10, break())));
 primes
 // outputs: [0, 1, 2, 3, 5, 7, 11, 13, 17, 19]
@@ -1363,7 +1370,7 @@ and with `player` scope, each player hosts its own state for each app, so functi
 
 
 <pre>
-/script run a() -> global_list+=1; global_list = l(1,2,3); a(); a(); global_list  // => [1, 2, 3, 1, 1]
+/script run a() -> global_list+=1; global_list = [1,2,3]; a(); a(); global_list  // => [1, 2, 3, 1, 1]
 /script run a(); a(); global_list  // => [1, 2, 3, 1, 1, 1, 1]
 </pre>
 
@@ -1392,7 +1399,7 @@ a unique name, which you can pass somewhere else to get this function `call`ed.
 by their value and `call` method.
 
 <pre>
-a(lst) -> lst+=1; list = l(1,2,3); a(list); a(list); list  // => [1,2,3]
+a(lst) -> lst+=1; list = [1,2,3]; a(list); a(list); list  // => [1,2,3]
 </pre>
 
 In case the inner function wants to operate and modify larger objects, lists from the outer scope, but not global, 
@@ -1418,14 +1425,14 @@ which variables you want to use, and borrow
 This mechanism can be used to use static mutable objects without the need of using `global_...` variables
 
 <pre>
-list = l(1,2,3); a(outer(list)) -> list+=1;  a(); a(); list  // => [1,2,3,1,1]
+list = [1,2,3]; a(outer(list)) -> list+=1;  a(); a(); list  // => [1,2,3,1,1]
 </pre>
 
 The return value of a function is the value of the last expression. This as the same effect as using outer or 
 global lists, but is more expensive
 
 <pre>
-a(lst) -> lst+=1; list = l(1,2,3); list=a(list); list=a(list); list  // => [1,2,3,1,1]
+a(lst) -> lst+=1; list = [1,2,3]; list=a(list); list=a(list); list  // => [1,2,3,1,1]
 </pre>
 
 Ability to combine more statements into one expression, with functions, passing parameters, and global and outer 
@@ -1518,11 +1525,11 @@ programmers with their own lambda arguments
 
 <pre>
 my_map(list, function) -> map(list, call(function, _));
-my_map(l(1,2,3), _(x) -> x*x);    // => [1,4,9]
+my_map([1,2,3], _(x) -> x*x);    // => [1,4,9]
-profile_expr(my_map(l(1,2,3), _(x) -> x*x));   // => ~32000
+profile_expr(my_map([1,2,3], _(x) -> x*x));   // => ~32000
-sq(x) -> x*x; profile_expr(my_map(l(1,2,3), 'sq'));   // => ~36000
+sq(x) -> x*x; profile_expr(my_map([1,2,3], 'sq'));   // => ~36000
-sq = (_(x) -> x*x); profile_expr(my_map(l(1,2,3), sq));   // => ~36000
+sq = (_(x) -> x*x); profile_expr(my_map([1,2,3], sq));   // => ~36000
-profile_expr(map(l(1,2,3), _*_));   // => ~80000
+profile_expr(map([1,2,3], _*_));   // => ~80000
 </pre>
 
 ## Control flow
@@ -1832,7 +1839,7 @@ It returns a new sorted list, not affecting the list passed to the argument
 
 <pre>sort(3,2,1)  => [1, 2, 3]
 sort('a',3,11,1)  => [1, 3, 11, 'a']
-list = l(4,3,2,1); sort(list)  => [1, 2, 3, 4]
+list = [4,3,2,1]; sort(list)  => [1, 2, 3, 4]
 </pre>
 
 ### `sort_key(list, key_expr)`
@@ -1842,15 +1849,15 @@ Sorts a copy of the list in the order or keys as defined by the `key_expr` for e
 <pre>
 sort_key([1,3,2],_)  => [1, 2, 3]
 sort_key([1,3,2],-_)  => [3, 2, 1]
-sort_key(l(range(10)),rand(1))  => [1, 0, 9, 6, 8, 2, 4, 5, 7, 3]
+sort_key([range(10)],rand(1))  => [1, 0, 9, 6, 8, 2, 4, 5, 7, 3]
-sort_key(l(range(20)),str(_))  => [0, 1, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 2, 3, 4, 5, 6, 7, 8, 9]
+sort_key([range(20)],str(_))  => [0, 1, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 2, 3, 4, 5, 6, 7, 8, 9]
 </pre>
 
 ### `range(to), range(from, to), range(from, to, step)`
 
 Creates a range of numbers from `from`, no greater/larger than `to`. The `step` parameter dictates not only the 
 increment size, but also direction (can be negative). The returned value is not a proper list, just the iterator 
-but if for whatever reason you need a proper list with all items evaluated, use `l(range(to))`. 
+but if for whatever reason you need a proper list with all items evaluated, use `[range(to)]`. 
 Primarily to be used in higher order functions
 
 <pre>
@@ -1877,7 +1884,7 @@ arguments is a list of lists, they have to have two elements each, and then firs
 
 In map creation context (directly inside `{}` or `m{}` call), `->` operator acts like a pair constructor for simpler
 syntax providing key value pairs, so the invocation to `{foo -> bar, baz -> quux}` is equivalent to
-`{l(foo, bar), l(baz, quux)}`, which is equivalent to somewhat older, but more traditional functional form of
+`{[foo, bar], [baz, quux]}`, which is equivalent to somewhat older, but more traditional functional form of
 `m(l(foo, bar),l(baz, quuz))`.
 
 Internally, `{?}`(list syntax) and `m(?)`(function syntax) are equivalent. `{}` is simply translated to 
@@ -2230,7 +2237,7 @@ which only returns players in current dimension, or use `in_dimension(expr)` fun
 
 ## Specifying blocks
 
-### `block(x, y, z)`, `block(l(x,y,z))`, `block(state)`
+### `block(x, y, z)`, `block([x,y,z])`, `block(state)`
 
 Returns either a block from specified location, or block with a specific state (as used by `/setblock` command), 
 so allowing for block properties, block entity data etc. Blocks otherwise can be referenced everywhere by its simple 
@@ -2284,7 +2291,7 @@ Throws `unknown_block` if provided block to set is not valid
 
 <pre>
 set(0,5,0,'bedrock')  => bedrock
-set(l(0,5,0), 'bedrock')  => bedrock
+set([0,5,0], 'bedrock')  => bedrock
 set(block(0,5,0), 'bedrock')  => bedrock
 scan(0,5,0,0,0,0,set(_,'bedrock'))  => 1
 set(pos(player()), 'bedrock')  => bedrock
@@ -2319,7 +2326,7 @@ generator. The following code causes a cascading effect as blocks placed on chun
 loaded to full, thus generated:
 
 <pre>
-__config() -> m(l('scope', 'global'));
+__config() -> {'scope' -> 'global'};
 __on_chunk_generated(x, z) -> (
   scan(x,0,z,0,0,0,15,15,15,
     if (perlin(_x/16, _y/8, _z/16) > _y/16,
@@ -2332,7 +2339,7 @@ __on_chunk_generated(x, z) -> (
 The following addition resolves this issue, by not allowing block updates past chunk borders:
 
 <pre>
-__config() -> m(l('scope', 'global'));
+__config() -> {'scope' -> 'global'};
 __on_chunk_generated(x, z) -> (
   without_updates(
     scan(x,0,z,0,0,0,15,15,15,
@@ -2430,7 +2437,7 @@ mine(x,y,z) ->
   slot = p~'selected_slot';
   item_tuple = inventory_get(p, slot);
   if (!item_tuple, destroy(x,y,z,'air'); return()); // empty hand, just break with 'air'
-  l(item, count, tag) = item_tuple;
+  [item, count, tag] = item_tuple;
   tag_back = destroy(x,y,z, item, tag);
   if (tag_back == false, // failed to break the item
     return(tag_back)
@@ -2482,8 +2489,8 @@ Returns a triple of coordinates of a specified block or entity. Technically enti
 and the same can be achieved with `query(entity,'pos')`, but for simplicity `pos` allows to pass all positional objects.
 
 <pre>
-pos(block(0,5,0)) => l(0,5,0)
+pos(block(0,5,0)) => [0,5,0]
-pos(player()) => l(12.3, 45.6, 32.05)
+pos(player()) => [12.3, 45.6, 32.05]
 pos(block('stone')) => Error: Cannot fetch position of an unrealized block
 </pre>
 
@@ -2493,8 +2500,8 @@ Returns a coords triple that is offset in a specified `direction` by `amount` of
 1 block. To offset into opposite facing, use negative numbers for the `amount`.
 
 <pre>
-pos_offset(block(0,5,0), 'up', 2)  => l(0,7,0)
+pos_offset(block(0,5,0), 'up', 2)  => [0,7,0]
-pos_offset(l(0,5,0), 'up', -2 ) => l(0,3,0)
+pos_offset([0,5,0], 'up', -2 ) => [0,3,0]
 </pre>
 
 ### `(Deprecated) block_properties(pos)`
@@ -2779,7 +2786,7 @@ Returns spawn potential at a location (1.16+ only)
 
 Sends full chunk data to clients. Useful when lots stuff happened and you want to refresh it on the clients.
 
-### `reset_chunk(pos)`, `reset_chunk(from_pos, to_pos)`, `reset_chunk(l(pos, ...))`
+### `reset_chunk(pos)`, `reset_chunk(from_pos, to_pos)`, `reset_chunk([pos, ...])`
 Removes and resets the chunk, all chunks in the specified area or all chunks in a list at once, removing all previous
 blocks and entities, and replacing it with a new generation. For all currently loaded chunks, they will be brought
 to their current generation status, and updated to the player. All chunks that are not in the loaded area, will only
@@ -3050,7 +3057,6 @@ with the game and assumed not changing.
 
 `custom_dimension` is experimental and considered a WIP. More customization options besides the seed will be added in
 the future.
-
 # Iterating over larger areas of blocks
 
 These functions help scan larger areas of blocks without using generic loop functions, like nested `loop`.
@@ -3209,7 +3215,7 @@ which in this case can be radically simplified:
 
 <pre>
 query(p, 'name') <=> p ~ 'name'     // much shorter and cleaner
-query(p, 'holds', 'offhand') <=> p ~ l('holds', 'offhand')    // not really but can be done
+query(p, 'holds', 'offhand') <=> p ~ ['holds', 'offhand']    // not really but can be done
 </pre>
 
 ### `query(e, 'removed')`
@@ -3258,7 +3264,7 @@ Returns a 3d vector where the entity is looking.
 
 ### `query(e, 'motion')`
 
-Triple of entity's motion vector, `l(motion_x, motion_y, motion_z)`. Motion represents the velocity from all the forces
+Triple of entity's motion vector, `[motion_x, motion_y, motion_z]`. Motion represents the velocity from all the forces
 that exert on the given entity. Things that are not 'forces' like voluntary movement, or reaction from the ground are
 not part of said forces.
 
@@ -3680,11 +3686,11 @@ Removes (not kills) entity from the game.
 
 Kills the entity.
 
-### `modify(e, 'pos', x, y, z), modify(e, 'pos', l(x,y,z) )`
+### `modify(e, 'pos', x, y, z), modify(e, 'pos', [x,y,z] )`
 
 Moves the entity to a specified coords.
 
-### `modify(e, 'location', x, y, z, yaw, pitch), modify(e, 'location', l(x, y, z, yaw, pitch) )`
+### `modify(e, 'location', x, y, z, yaw, pitch), modify(e, 'location', [x, y, z, yaw, pitch] )`
 
 Changes full location vector all at once.
 
@@ -3696,15 +3702,21 @@ Changes entity's location in the specified direction.
 
 Changes entity's pitch or yaw angle.
 
+### `modify(e, 'look', x, y, z), modify(e, 'look', [x,y,z] )`
+
+Sets entity's 3d vector where the entity is looking.
+For cases where the vector has a length of 0, yaw and pitch won't get changed.
+When pointing straight up or down, yaw will stay the same.
+
 ### `modify(e, 'head_yaw', angle)`, `modify(e, 'body_yaw', angle)`
 
 For living entities, controls their head and body yaw angle.
 
-### `modify(e, 'move', x, y, z), modify(e, 'move', l(x,y,z) )`
+### `modify(e, 'move', x, y, z), modify(e, 'move', [x,y,z] )`
 
 Moves the entity by a vector from its current location.
 
-### `modify(e, 'motion', x, y, z), modify(e, 'motion', l(x,y,z) )`
+### `modify(e, 'motion', x, y, z), modify(e, 'motion', [x,y,z] )`
 
 Sets the motion vector (where and how much entity is moving).
 
@@ -3712,7 +3724,7 @@ Sets the motion vector (where and how much entity is moving).
 
 Sets the corresponding component of the motion vector.
 
-### `modify(e, 'accelerate', x, y, z), modify(e, 'accelerate', l(x, y, z) )`
+### `modify(e, 'accelerate', x, y, z), modify(e, 'accelerate', [x, y, z] )`
 
 Adds a vector to the motion vector. Most realistic way to apply a force to an entity.
 
@@ -3763,15 +3775,15 @@ Mounts the entity to the `other`.
 
 Shakes off all passengers.
 
-### `modify(e, 'mount_passengers', passenger, ? ...), modify(e, 'mount_passengers', l(passengers) )`
+### `modify(e, 'mount_passengers', passenger, ? ...), modify(e, 'mount_passengers', [passengers] )`
 
 Mounts on all listed entities on `e`.
 
-### `modify(e, 'tag', tag, ? ...), modify(e, 'tag', l(tags) )`
+### `modify(e, 'tag', tag, ? ...), modify(e, 'tag', [tags] )`
 
 Adds tag(s) to the entity.
 
-### `modify(e, 'clear_tag', tag, ? ...), modify(e, 'clear_tag', l(tags) )`
+### `modify(e, 'clear_tag', tag, ? ...), modify(e, 'clear_tag', [tags] )`
 
 Removes tag(s) from the entity.
 
@@ -3968,7 +3980,7 @@ protect_villager(entity, amount, source, source_entity, healing_player) ->
 (
    if(source_entity && source_entity~'type' != 'player',
       modify(entity, 'health', amount + entity~'health' );
-      particle('end_rod', pos(entity)+l(0,3,0));
+      particle('end_rod', pos(entity)+[0,3,0]);
       print(str('%s healed thanks to %s', entity, healing_player))
    )
 );
@@ -4793,7 +4805,7 @@ Throws `unknown_particle` if particle doesn't exist.
 ## Markers
 
 ### `draw_shape(shape, duration, key?, value?, ... )`, 
-### `draw_shape(shape, duration, l(key?, value?, ... ))`, 
+### `draw_shape(shape, duration, [key?, value?, ... ])`, 
 ### `draw_shape(shape, duration, attribute_map)`
 ### `draw_shape(shape_list)`
 
@@ -4955,7 +4967,7 @@ produce an exception.
 Displays the result of the expression to the chat. Overrides default `scarpet` behaviour of sending everyting to stderr.
 Can optionally define player or list of players to send the message to.
 
-### `format(components, ...)`, `format(l(components, ...))`
+### `format(components, ...)`, `format([components, ...])`
 
 Creates a line of formatted text. Each component is either a string indicating formatting and text it corresponds to
 or a decorator affecting the component preceding it.