More internal docs

Small docs update
Code reformat

Author: TPGamesNL

build.gradle

@@ -25,14 +25,14 @@ repositories {
 }
 
 processResources {
-  inputs.files 'build.gradle'
-  from sourceSets.main.resources.srcDirs
-  filter(ReplaceTokens, tokens: [version: version])
+  from ('src/main/resources') {
+    filter(ReplaceTokens, tokens: ["version": version])
+  }
 }
 
 dependencies {
   implementation 'org.spigotmc:spigot-api:1.13-R0.1-SNAPSHOT'
-  implementation 'com.github.SkriptLang:Skript:master-SNAPSHOT'
+  implementation 'com.github.SkriptLang:Skript:2.5.3'
 }
 
 compileJava.options.encoding = "UTF-8"

docs/advanced/experiments.md

@@ -23,7 +23,7 @@ Individual features may be enabled by adding the codename of the feature on new
 Deferred parsing allows you to prefix any line with `(parse[d] later)` to defer parsing until the first execution of the line. This allows you to circumvent issues where custom syntaxes are used before they are defined.
 
 {% hint style="danger" %}
-This should only be used when two custom syntaxes refer to each other. Other issues should be resolved by reordering custom syntax definitions and ensuring that libraries containing custom syntax load before other scripts.
+This should only be used when two custom syntaxes refer to each other. Other issues should be resolved by reordering custom syntax definitions and ensuring that libraries containing custom syntax load before other scripts, or by using the [preloading feature](#preloading).
 {% endhint %}
 
 

src/main/java/com/btk5h/skriptmirror/Null.java

@@ -1,7 +1,7 @@
 package com.btk5h.skriptmirror;
 
 public class Null {
-  private static Null instance = new Null();
+  private static final Null instance = new Null();
 
   private Null() {
   }

src/main/java/com/btk5h/skriptmirror/ParseOrderWorkarounds.java

@@ -2,7 +2,6 @@
 
 import ch.njol.skript.Skript;
 import ch.njol.skript.effects.EffReturn;
-import ch.njol.skript.lang.*;
 import ch.njol.util.Checker;
 import com.btk5h.skriptmirror.skript.EffExpressionStatement;
 import com.btk5h.skriptmirror.skript.custom.ExprMatchedPattern;
@@ -11,9 +10,7 @@
 import com.btk5h.skriptmirror.skript.custom.expression.CustomExpression;
 import com.btk5h.skriptmirror.util.SkriptReflection;
 
-import java.util.Arrays;
 import java.util.Collection;
-import java.util.List;
 import java.util.Optional;
 
 /**

src/main/java/com/btk5h/skriptmirror/skript/CondParseLater.java

@@ -20,9 +20,8 @@ public class CondParseLater extends Condition {
   public boolean check(Event e) {
     Condition parsedCondition = getParsedCondition();
 
-    if (parsedCondition == null) {
+    if (parsedCondition == null)
       return false;
-    }
 
     return parsedCondition.check(e);
   }
@@ -31,13 +30,7 @@ public boolean check(Event e) {
   protected TriggerItem walk(Event e) {
     Statement parsedStatement = getParsedStatement();
 
-    if (parsedStatement == null) {
-      return null;
-    }
-
-    TriggerItem.walk(parsedStatement, e);
-
-    return null;
+    return parsedStatement == null ? getNext() : parsedStatement;
   }
 
   @Override
@@ -70,12 +63,10 @@ private Statement getParsedStatement() {
         + statement);
       previousState.applyToCurrentState();
 
-      if (parsedStatement == null) {
-        return null;
+      if (parsedStatement != null) {
+        parsedStatement.setNext(getNext());
+        parsedStatement.setParent(getParent());
       }
-
-      parsedStatement.setNext(getNext());
-      parsedStatement.setParent(getParent());
     }
 
     return parsedStatement;
@@ -84,22 +75,18 @@ private Statement getParsedStatement() {
   private Condition getParsedCondition() {
     if (parsedStatement == null) {
       scriptLoaderState.applyToCurrentState();
-      parsedStatement = Condition.parse(statement,
-          String.format("Could not parse condition at runtime: %s", statement));
+      parsedStatement = Condition.parse(statement, "Could not parse condition at runtime: " + statement);
 
-      if (parsedStatement == null) {
-        return null;
+      if (parsedStatement != null) {
+        parsedStatement.setNext(getNext());
+        parsedStatement.setParent(getParent());
       }
-
-      parsedStatement.setNext(getNext());
-      parsedStatement.setParent(getParent());
     }
 
-    if (!(parsedStatement instanceof Condition)) {
-      throw new IllegalStateException(
-          String.format("%s was used as a condition but was parsed as a statement", statement));
+    if (parsedStatement != null && !(parsedStatement instanceof Condition)) {
+      throw new IllegalStateException(statement + " was used as a condition but was parsed as a statement");
     }
 
-    return ((Condition) parsedStatement);
+    return (Condition) parsedStatement;
   }
 }

src/main/java/com/btk5h/skriptmirror/skript/Consent.java

@@ -1,6 +1,5 @@
 package com.btk5h.skriptmirror.skript;
 
-import ch.njol.skript.ScriptLoader;
 import ch.njol.skript.Skript;
 import ch.njol.skript.config.Node;
 import ch.njol.skript.config.SectionNode;
@@ -78,8 +77,8 @@ public void unregisterAll() {
 
   @Override
   public boolean init(Literal<?>[] args, int matchedPattern, SkriptParser.ParseResult parseResult) {
-    File currentScript = ScriptLoader.currentScript.getFile();
-    SectionNode node = ((SectionNode) SkriptLogger.getNode());
+    File currentScript = SkriptUtil.getCurrentScript();
+    SectionNode node = (SectionNode) SkriptLogger.getNode();
 
     if (node.getKey().toLowerCase().startsWith("on ")) {
       return false;

src/main/java/com/btk5h/skriptmirror/util/JavaUtil.java

@@ -41,24 +41,40 @@ public final class JavaUtil {
     PRIMITIVE_CLASS_NAMES.put("short", short.class);
   }
 
+  /**
+   * @return a {@link Stream} of {@link Field}s, with the fields declared in the given class,
+   * and the public fields of the given class, without duplicates.
+   */
   public static Stream<Field> fields(Class<?> cls) {
     return Stream.concat(
       Arrays.stream(cls.getFields()),
       Arrays.stream(cls.getDeclaredFields())
     ).distinct();
   }
 
+  /**
+   * @return a {@link Stream} of {@link Method}s, with the methods declared in the given class
+   * and the public methods of the given class, without duplicates.
+   */
   public static Stream<Method> methods(Class<?> cls) {
     return Stream.concat(
       Arrays.stream(cls.getMethods()),
       Arrays.stream(cls.getDeclaredMethods())
     ).distinct();
   }
 
+  /**
+   * @return a {@link Stream} of the {@link Constructor}s declared in the given class.
+   */
   public static Stream<Constructor> constructors(Class<?> cls) {
     return Arrays.stream(cls.getDeclaredConstructors());
   }
 
+  /**
+   * Calls {@code toGenericString} on the given {@link Member},
+   * returning {@code null} if the given {@link Member} is not
+   * a {@link Field}, a {@link Method} or a {@link Constructor}.
+   */
   public static String toGenericString(Member o) {
     if (o instanceof Field) {
       return ((Field) o).toGenericString();
@@ -70,6 +86,10 @@ public static String toGenericString(Member o) {
     return null;
   }
 
+  /**
+   * @return an array of the wrapper type of the component type of the given array (e.g. {@code int[] -> Integer[]}).
+   * The contents of the array are copied over.
+   */
   public static Object boxPrimitiveArray(Object obj) {
     Class<?> componentType = obj.getClass().getComponentType();
     if (componentType != null && componentType.isPrimitive()) {
@@ -85,6 +105,9 @@ public static Object boxPrimitiveArray(Object obj) {
     return obj;
   }
 
+  /**
+   * Converts a numeric array to a different numeric class. Also supports arrays with depths higher than {@code 1}.
+   */
   public static Object convertNumericArray(Object array, Class<?> to) {
     Class<?> componentType = array.getClass().getComponentType();
     int length = Array.getLength(array);
@@ -131,6 +154,11 @@ public static Object convertNumericArray(Object array, Class<?> to) {
     return newArray;
   }
 
+  /**
+   * Gets the array depth of a given class, for example:<br>
+   *   Object[] -> 1<br>
+   *   Object[][][] -> 3
+   */
   public static int getArrayDepth(Class<?> cls) {
     int depth = 0;
 
@@ -142,6 +170,9 @@ public static int getArrayDepth(Class<?> cls) {
     return depth;
   }
 
+  /**
+   * @return the component type of the given array class, independent of the depth of the array.
+   */
   public static Class<?> getBaseComponent(Class<?> obj) {
     Class<?> componentType = obj.getComponentType();
 
@@ -152,11 +183,21 @@ public static Class<?> getBaseComponent(Class<?> obj) {
     return componentType;
   }
 
+  /**
+   * An functional interface with an input and output that may throw an {@link Exception}.
+   * @param <T> the input of the function.
+   * @param <R> the return value of the function.
+   */
   @FunctionalInterface
   public interface ExceptionalFunction<T, R> {
     R apply(T t) throws Exception;
   }
 
+  /**
+   * Converts a {@link ExceptionalFunction} to a normal {@link Function}, by catching the exception
+   * and logging a warning with the simple class name and message of the exception.
+   * If Skript's verbosity is set to 'very high' or above, this will also print the stack trace.
+   */
   public static <T, R> Function<T, R> propagateErrors(ExceptionalFunction<T, R> function) {
     return t -> {
       try {
@@ -177,19 +218,31 @@ public static <T, R> Function<T, R> propagateErrors(ExceptionalFunction<T, R> fu
     };
   }
 
+  /**
+   * @return whether the given class is a numeric class, albeit primitive or a wrapper of a primitive numeric class.
+   */
   public static boolean isNumericClass(Class<?> cls) {
     return Number.class.isAssignableFrom(cls) || JavaUtil.NUMERIC_CLASSES.contains(cls);
   }
 
+  /**
+   * {@return} a new array with the given class as base component type, and the given length as the array length.
+   */
   @SuppressWarnings("unchecked")
   public static <T> T[] newArray(Class<? extends T> type, int length) {
     return (T[]) Array.newInstance(type, length);
   }
 
+  /**
+   * {@return} the array class of the given class.
+   */
   public static <T> Class<?> getArrayClass(Class<T> type) {
     return Array.newInstance(type, 0).getClass();
   }
 
+  /**
+   * @return the array class with the given depth of the given type, using {@link #getArrayClass(Class)}.
+   */
   public static Class<?> getArrayClass(Class<?> type, int layers) {
     for (int i = 0; i < layers; i++) {
       type = getArrayClass(type);

src/main/java/com/btk5h/skriptmirror/util/SkriptMirrorUtil.java

@@ -22,6 +22,10 @@ public class SkriptMirrorUtil {
 
   private static final Pattern TYPE_PREFIXES = Pattern.compile("^[-*~]*");
 
+  /**
+   * @return the {@link Class} of this {@link JavaType}, if it is a {@link JavaType},
+   * otherwise it returns {@link #getClass(Object)} of this object.
+   */
   public static Class<?> toClassUnwrapJavaTypes(Object o) {
     if (o instanceof JavaType) {
       return ((JavaType) o).getJavaClass();
@@ -34,6 +38,10 @@ public static String getDebugName(Class<?> cls) {
     return Skript.logVeryHigh() ? cls.getName() : cls.getSimpleName();
   }
 
+  /**
+   * The given object is first possibly unwrapped using {@link ObjectWrapper#unwrapIfNecessary(Object)}.
+   * Then returns the class of the object, or {@code Object.class}, if the object is {@code null}.
+   */
   public static Class<?> getClass(Object o) {
     o = ObjectWrapper.unwrapIfNecessary(o);
 
@@ -44,6 +52,10 @@ public static Class<?> getClass(Object o) {
     return o.getClass();
   }
 
+  /**
+   * Returns the given pattern, with all types starting with an underscore
+   * replaced with {@code javaobject(s)}, as those types are just context indicators.
+   */
   public static String preprocessPattern(String pattern) {
     StringBuilder newPattern = new StringBuilder(pattern.length());
     String[] parts = pattern.split("%");
@@ -68,6 +80,10 @@ public static String preprocessPattern(String pattern) {
     return newPattern.toString();
   }
 
+  /**
+   * Returns the given type string, using {@link SkriptUtil#replaceUserInputPatterns(String)}
+   * on each type in the given string.
+   */
   public static String processTypes(String part) {
     if (part.length() > 0) {
       // copy all prefixes
@@ -88,14 +104,18 @@ public static String processTypes(String part) {
 
       // replace user input patterns
       String types = Arrays.stream(part.split("/"))
-          .map(SkriptUtil::replaceUserInputPatterns)
-          .collect(Collectors.joining("/"));
+        .map(SkriptUtil::replaceUserInputPatterns)
+        .collect(Collectors.joining("/"));
 
       return prefixes + types + suffixes;
     }
     return part;
   }
 
+  /**
+   * @return {@link Null#getInstance()} if the given object is {@code null},
+   * otherwise returns the given object itself.
+   */
   public static Object reifyIfNull(Object o) {
     return o == null ? Null.getInstance() : o;
   }

src/main/java/com/btk5h/skriptmirror/util/SkriptReflection.java

@@ -187,6 +187,10 @@ public static Parameter<?>[] getParameters(Function<?> function) {
     }
   }
 
+  /**
+   * Prints the log stored in the given {@link RetainingLogHandler} after closing
+   * all active {@link LogHandler}s, except the {@link ParseLogHandler}s.
+   */
   public static void printLog(RetainingLogHandler logger) {
     logger.stop();
     HandlerList handler;
@@ -214,6 +218,9 @@ public static void printLog(RetainingLogHandler logger) {
     SkriptLogger.logAll(logger.getLog());
   }
 
+  /**
+   * @return a {@link Map} of the options currently being loaded by {@link ScriptLoader}.
+   */
   @SuppressWarnings("unchecked")
   public static Map<String, String> getCurrentOptions() {
     try {
@@ -364,6 +371,9 @@ public static void disableAndOrWarnings() {
     }
   }
 
+  /**
+   * Executes {@link SkriptParser}'s {@code parse_i} method with the given arguments.
+   */
   public static SkriptParser.ParseResult parse_i(SkriptParser skriptParser, String pattern, int i, int j) {
     if (PARSE_I == null)
       return null;
@@ -376,6 +386,9 @@ public static SkriptParser.ParseResult parse_i(SkriptParser skriptParser, String
     return null;
   }
 
+  /**
+   * {@return} a list of all of Skript's registered {@link ch.njol.skript.lang.Expression}s.
+   */
   public static List<ExpressionInfo<?, ?>> getExpressions() {
     try {
       return (List<ExpressionInfo<?, ?>>) EXPRESSIONS.get(null);