From f30459bd22818754a2f97ac71d9ed815bf38994f Mon Sep 17 00:00:00 2001 From: gnembon Date: Fri, 8 Nov 2019 04:03:39 -0400 Subject: [PATCH] fixed docs --- .../java/carpet/script/CarpetExpression.java | 18 +++++- src/main/java/carpet/script/Expression.java | 60 +++++++------------ 2 files changed, 39 insertions(+), 39 deletions(-) diff --git a/src/main/java/carpet/script/CarpetExpression.java b/src/main/java/carpet/script/CarpetExpression.java index 05917c94..8083c2d7 100644 --- a/src/main/java/carpet/script/CarpetExpression.java +++ b/src/main/java/carpet/script/CarpetExpression.java @@ -510,15 +510,28 @@ public class CarpetExpression * top('ocean_floor', x, y, z) => 41 * *

loaded(pos)

- *

Boolean function, true if the block is loaded. Normally scarpet doesn't check if operates on + *

Boolean function, true if the block is accessible forthe game mechanics. + * Normally scarpet doesn't check if operates on * loaded area - the game will automatically load missing blocks. We see this as advantage. * Vanilla fill/clone commands only check the specified corners for loadness.

+ *

To check if block is truly loaded, I mean in memory, use generation_status(x) != null, as + * chunks can still be loaded outside of the playable area, just are not used any of the game mechanics processes.

* 
      * loaded(pos(players()))  => 1
      * loaded(100000,100,1000000)  => 0
      *
- *

loaded_ep(pos)

+ *

(Deprecated) loaded_ep(pos)

*

Boolean function, true if the block is loaded and entity processing, as per 1.13.2

+ *

Deprecated as of scarpet 1.6, use loaded_status(x) > 0, or + * just loaded(x) with the same effect

+ *

loaded_status(pos)

+ *

Returns loaded status as per new 1.14 chunk ticket system, 0 for inaccessible, 1 for border chunk, + * 2 for ticking, 3 for entity ticking

+ *

generation_status(pos), generation_status(pos, true)

+ *

Returns generation status as per new 1.14 chunk ticket system. Can return any value from several available + * but chunks can only be valid in a few states: full, features, liquid_carvers, + * and structure_starts. Returns null if the chunk is not in memory unless called with optional + * true.

*

suffocates(pos)

*

Boolean function, true if the block causes suffocation.

*

power(pos)

@@ -788,6 +801,7 @@ public class CarpetExpression return (c_, t_) -> retval; }); + // Deprecated, use loaded_status as more indicative this.expr.addLazyFunction("loaded_ep", -1, (c, t, lv) -> { BlockPos pos = BlockValue.fromParams((CarpetContext)c, lv, 0).block.getPos(); diff --git a/src/main/java/carpet/script/Expression.java b/src/main/java/carpet/script/Expression.java index 1fdbe740..a0019457 100644 --- a/src/main/java/carpet/script/Expression.java +++ b/src/main/java/carpet/script/Expression.java @@ -199,10 +199,9 @@ import static java.lang.Math.min; * by adding them to the function signature wrapped around built-in function outer. What this does is * it borrows the reference to that variable from the outer scope to be used inside the function and any modifications to that outer * variable would result in changes of that value in the outer scope as well. Its like passing the parameters by reference, - * except the calling function itself decides what variables its borrowing and what its name. This can be used to - * return more than one result from a function call, although its a very ugly way of doing it - - * I would still recommend returning a list of values instead. - * Variables from outer scopes have a similar behaviour to, for example, nonlocal variables from python.

+ * except the calling function itself decides what variables its borrowing. Variables are borrowed from the local scope + * when the function is defined, not used, so this can be used to modify static mutable values, without using global + * variables. Check outer(var) for details.

* * *

Code delivery, line indicators

@@ -250,53 +249,53 @@ import static java.lang.Math.min; * /script run * run_program() -> ( * loop( 10, - * foo = floor(rand(10)); + * foo = floor(rand(_)); * check_not_zero(foo); * print(_+' - foo: '+foo); * print(' reciprocal: '+ _/foo ) * ) * ); * check_not_zero(foo) -> ( - * if (foo==0, foo = 1) + * if (foo==0, foo = 1) * ) + * * *

Lets say that the intention was to check if the bar is zero and prevent division by zero in print, * but because the foo is passed as a variable, it never changes the original foo value. * Because of the inevitable division by zero, we get the following message: *

* 
- * Your math is wrong, Incorrect number format for Infinity at pos 112
- * run_program() -> (  loop( 10,    foo = floor(rand(10));    check_not_zero(foo);
- * print(_+' - foo: '+foo);     HERE>> print('  reciprocal: '+  _/foo )  ));
- * check_not_zero(foo) -> (  if (foo==0, foo = 1))
+ * Your math is wrong, Incorrect number format for NaN at pos 98
+ * run_program() -> ( loop( 10, foo = floor(rand(_)); check_not_zero(foo); print(_+' - foo: '+foo);
+ * HERE>> print(' reciprocal: '+ _/foo ) ));check_not_zero(foo) -> ( if (foo==0, foo = 1))
  *
* - * As we can see, we got our problem where the result of the mathematical operation was not a number (Infinity, so not a number), + * As we can see, we got our problem where the result of the mathematical operation was not a number (infinity, so not a number), * however by pasting our program * into the command made it squish the newlines so while it is clear where the error happened and we still can track the error down, - * the position of the error (112) is not very helpful and wouldn't be useful if the program gets significantly longer. + * the position of the error (98) is not very helpful and wouldn't be useful if the program gets significantly longer. * To combat this issue we can precede every line of the script with dollar signs $: * 
  * /script run
  * $run_program() -> (
  * $  loop( 10,
- * $    foo = floor(rand(10));
+ * $    foo = floor(rand(_));
  * $    check_not_zero(foo);
  * $    print(_+' - foo: '+foo);
  * $    print('  reciprocal: '+  _/foo )
  * $  )
  * $);
  * $check_not_zero(foo) -> (
- * $  if (foo==0, foo = 1)
+ * $   if (foo==0, foo = 1)
  * $)
  *
* *

Then we get the following error message

* * 
- * Your math is wrong, Incorrect number format for Infinity at line 7, pos 5
- *     print(_+' - foo: '+foo);
- *      HERE>> print('  reciprocal: '+  _/foo )
+ * Your math is wrong, Incorrect number format for NaN at line 7, pos 2
+ *   print(_+' - foo: '+foo);
+ *    HERE>> print(' reciprocal: '+ _/foo )
  *   )
  *
* @@ -319,20 +318,6 @@ import static java.lang.Math.min; * ... * check_foo_not_zero() -> if(global_foo == 0, global_foo = 1) * - *

.. or scope foo from the outer function - in this case the inner function has to determine what it is accessing

- * 
- *     foo = floor(rand(10));
- *     check_foo_not_zero();
- *     ...
- *     check_foo_not_zero(outer(foo)) -> if(foo == 0, foo = 1)
- *
- *

outer scope can only be used in - * function signatures to indicate outer variables. They are not arguments, but still you would want to use - * locally without affecting other uses of foo in your program. - *

- *

For the most part - passing arguments as values, and using returned values . - * The main usecase of Scarpet would rather be simpler scripts, default scope for all variables is global, unless variable - * is declared with local scope explicitly. *

*/ @@ -716,8 +701,7 @@ public class Expression implements Cloneable LazyValue lv = context.getVariable(global); if (lv == null) { - Value zero = Value.ZERO.reboundedTo(global); - contextValues.put(global, (cc, tt) -> zero); + throw new InternalExpressionException("Variable "+global+" needs to be defined in outer scope to be used as outer parameter"); } else { @@ -888,11 +872,11 @@ public class Expression implements Cloneable *

outer(arg)

*

outer function can only be used in the function signature, and it will * cause an error everywhere else. It borrows the reference to that variable from the outer scope and allows - * its modification in the inner scope. Any modification of outer variable will result in change of them in - * the outer function. In case the variable was not set yet in the outer scope - it will be created. This construct - * is similar to nonlocal scoping from python

+ * its modification in the inner scope. This is a similar behaviour to using local variables in lambda function definitions + * from Java, except here you have to specify 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

* 
-     * a(outer(list)) -> list+=1; list = l(1,2,3); a(); a(); list  // => [1,2,3,1,1]
+     * list = l(1,2,3); a(outer(list)) -> list+=1;  a(); a(); list  // => [1,2,3,1,1]
      *
*

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

@@ -2586,6 +2570,8 @@ public class Expression implements Cloneable *

System functions

*
*

Type conversion functions

+ *

copy(expr)

+ *

Returns the deep copy of the expression. Can be used to copy mutable objects, like maps and lists

*

type(expr)

*

Returns the string value indicating type of the expression. Possible outcomes are * null, number, string, list, iterator, as well as minecraft related concepts like