From ef757aec1d9c752420602793b919996d4442a5e2 Mon Sep 17 00:00:00 2001 From: gnembon Date: Tue, 8 Oct 2019 01:52:53 -0300 Subject: [PATCH] docs contd --- .../java/carpet/script/CarpetExpression.java | 6 +- src/main/java/carpet/script/Expression.java | 130 +++++++++++++++--- .../java/carpet/script/value/MapValue.java | 10 +- .../script/value/NBTSerializableValue.java | 4 + src/main/resources/carpet.mixins.json | 1 + 5 files changed, 128 insertions(+), 23 deletions(-) diff --git a/src/main/java/carpet/script/CarpetExpression.java b/src/main/java/carpet/script/CarpetExpression.java index db6a5a70..84e27f33 100644 --- a/src/main/java/carpet/script/CarpetExpression.java +++ b/src/main/java/carpet/script/CarpetExpression.java @@ -99,7 +99,7 @@ import static java.lang.Math.sqrt; /** *

Minecraft specific API and scarpet language add-ons and commands

*

Here is the gist of the Minecraft related functions. Otherwise the CarpetScript could live without Minecraft.

- *

Dimension issues

+ *

Dimension warning

*

One note, which is important is that most of the calls for entities and blocks * would refer to the current dimension of the caller, meaning, that if we for example * list all the players using player('all') function, if a player is in the @@ -108,7 +108,8 @@ import static java.lang.Math.sqrt; * refer to the overworld blocks and entities. * In case you would want to run commands across all dimensions, just run three of them, using * /execute in overworld/the_nether/the_end run script run ... and query - * players using player('*'), which only returns players in current dimension.

+ * players using player('*'), which only returns players in current dimension, or use + * in_dimension(expr) function.

*/ public class CarpetExpression { @@ -2361,6 +2362,7 @@ public class CarpetExpression *

nbt(expr)

*

Treats the argument as a nbt serializable string and returns its nbt value. * In case nbt is not in a correct nbt compound tag format, it will return null value.

+ *

Consult section about container operations in Expression to learn about possible operations on nbt values.

*

print(expr)

*

Displays the result of the expression to the chat. Overrides default scarpet behaviour of * sending everyting to stderr.

diff --git a/src/main/java/carpet/script/Expression.java b/src/main/java/carpet/script/Expression.java index 06bec169..7ffaabe8 100644 --- a/src/main/java/carpet/script/Expression.java +++ b/src/main/java/carpet/script/Expression.java @@ -50,7 +50,7 @@ import static java.lang.Math.min; /** - *

Fundamental components of scarpet programming language.

+ *

Fundamental components of scarpet programming language (towards upcoming version 1.5).

* *

Scarpet (a.k.a. Carpet Script, or Script for Carpet) is a programming language designed to provide * the ability to write custom programs to run within Minecraft and @@ -74,7 +74,7 @@ import static java.lang.Math.min; * 

  * script run print('Hello World!')
  *
- *

or an overly complex example:

+ *

or an OVERLY complex example:

* 
  * /script run
  *     block_check(x1, y1, z1, x2, y2, z2, block_to_check) ->
@@ -83,7 +83,7 @@ import static java.lang.Math.min;
  *         l(miny, maxy) = sort(l(y1, y2));
  *         l(minz, maxz) = sort(l(z1, z2));
  *         'Need to compute the size of the area of course';
- *         'Cause this language doesn\'t support comments';
+ *         'Cause this language doesn\'t support comments in the command mode';
  *         xsize = maxx - minx + 1;
  *         ysize = maxy - miny + 1;
  *         zsize = maxz - minz + 1;
@@ -202,11 +202,36 @@ import static java.lang.Math.min;
  * Variables from outer scopes have a similar behaviour to, for example, nonlocal variables from python. 

  *
  *
- * 
Line indicators

+ * 
Code delivery, line indicators

  * 
Note that this should only apply to pasting your code to execute with commandblock. Scarpet recommends placing your
  * code in packages (files with .sc extension that can be placed inside "/scripts" folder in the world files
  * and loaded as a module with command /script load [package_name]. Scarpet modules loaded from disk should only
  * contain code, no need to start with "/script run" prefix

+ * 
The following is the code that could be provided in a foo.sc file located in world /scripts folder

+ *
+ * 
+ * run_program() -> (
+ *   loop( 10,
+ *     // looping 10 times
+ *     // comments are allowed in scripts located in world files
+ *     // since we can tell where that line ends
+ *     foo = floor(rand(10));
+ *     check_not_zero(foo);
+ *     print(_+' - foo: '+foo);
+ *     print('  reciprocal: '+  _/foo )
+ *   )
+ * );
+ * check_not_zero(foo) -> (
+ *   if (foo==0, foo = 1)
+ * )
+ * 

+ * 
Which we then call in-game with:

+ * 
+ *     /script load foo
+ *     /script in foo invoke run_program
+ * 

+ * 
However the following code can also be input as a command, or in a command block.

+ *
  * 
Since the maximum command that can be input to the chat is limited in length, you will be probably inserting your
  * programs by pasting them to command blocks or reading from world files, however pasting to command blocks will remove some whitespaces and squish
  * your newlines making the code not readable. If you are pasting a program that is perfect and will never cause an error,
@@ -833,7 +858,8 @@ public class Expression implements Cloneable
      * Names in the signature don't need to be used anywhere else, other occurrences of these names
      * will be masked in this function scope.
      * Function call creates new scope for variables inside expr, so all non-global variables are not
-     * visible from the caller scope. All parameters are passed by value to the new scope, including lists

+     * visible from the caller scope. All parameters are passed by value to the new scope, including lists and other
+     * containers, however their copy will be shallow.

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

@@ -1045,7 +1071,7 @@ public class Expression implements Cloneable
      * even if they look like them:
      * 

      *