Merge branch 'dev/EntityDataFix' of https://github.com/TheAbsolutioni…

…sm/SkriptTest into dev/EntityDataFix

build.gradle

@@ -27,14 +27,14 @@ allprojects {
 
 dependencies {
 	shadow group: 'io.papermc', name: 'paperlib', version: '1.0.8'
-	shadow group: 'org.bstats', name: 'bstats-bukkit', version: '3.0.2'
-	shadow group: 'net.kyori', name: 'adventure-text-serializer-bungeecord', version: '4.3.2'
+	shadow group: 'org.bstats', name: 'bstats-bukkit', version: '3.1.0'
+	shadow group: 'net.kyori', name: 'adventure-text-serializer-bungeecord', version: '4.3.4'
 
 	implementation group: 'io.papermc.paper', name: 'paper-api', version: '1.21.4-R0.1-SNAPSHOT'
 	implementation group: 'com.google.code.findbugs', name: 'findbugs', version: '3.0.1'
 
 	// bundled with Minecraft 1.19.4+ for display entity transforms
-	implementation group: 'org.joml', name: 'joml', version: '1.10.5'
+	implementation group: 'org.joml', name: 'joml', version: '1.10.8'
 
 	// Plugin hook libraries
 	implementation group: 'com.sk89q.worldguard', name: 'worldguard-legacy', version: '7.0.0-SNAPSHOT', {
@@ -48,7 +48,7 @@ dependencies {
 	implementation fileTree(dir: 'lib', include: '*.jar')
 
 	testShadow group: 'junit', name: 'junit', version: '4.13.2'
-	testShadow group: 'org.easymock', name: 'easymock', version: '5.4.0'
+	testShadow group: 'org.easymock', name: 'easymock', version: '5.5.0'
 }
 
 checkstyle {

src/main/java/ch/njol/skript/Skript.java

@@ -44,9 +44,9 @@
 import ch.njol.util.StringUtils;
 import ch.njol.util.coll.iterator.CheckedIterator;
 import ch.njol.util.coll.iterator.EnumerationIterable;
-import com.google.common.collect.Lists;
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
+import io.papermc.lib.PaperLib;
 import org.bstats.bukkit.Metrics;
 import org.bukkit.*;
 import org.bukkit.command.CommandSender;
@@ -683,7 +683,7 @@ protected void afterErrors() {
 					if (TestMode.DEV_MODE) {
 						runTests(); // Dev mode doesn't need a delay
 					} else {
-						Bukkit.getWorlds().get(0).getChunkAtAsync(100, 100).thenRun(() -> runTests());
+						PaperLib.getChunkAtAsync(Bukkit.getWorlds().get(0), 100, 100).thenRun(() -> runTests());
 					}
 				}
 

src/main/java/ch/njol/skript/classes/data/BukkitClasses.java

@@ -6,8 +6,8 @@
 import ch.njol.skript.aliases.ItemType;
 import ch.njol.skript.bukkitutil.BukkitUtils;
 import ch.njol.skript.bukkitutil.EntityUtils;
-import ch.njol.skript.bukkitutil.SkriptTeleportFlag;
 import ch.njol.skript.bukkitutil.ItemUtils;
+import ch.njol.skript.bukkitutil.SkriptTeleportFlag;
 import ch.njol.skript.classes.*;
 import ch.njol.skript.classes.registry.RegistryClassInfo;
 import ch.njol.skript.entity.EntityData;
@@ -21,7 +21,6 @@
 import ch.njol.skript.util.BlockUtils;
 import ch.njol.skript.util.PotionEffectUtils;
 import ch.njol.skript.util.StringMode;
-import ch.njol.util.StringUtils;
 import ch.njol.yggdrasil.Fields;
 import io.papermc.paper.world.MoonPhase;
 import org.bukkit.*;
@@ -1536,6 +1535,15 @@ public String toVariableNameString(EntitySnapshot snapshot) {
 					.description("Teleport Flags are settings to retain during a teleport.")
 					.requiredPlugins("Paper 1.19+")
 					.since("2.10"));
+
+		Classes.registerClass(new ClassInfo<>(Vehicle.class, "vehicle")
+			.user("vehicles?")
+			.name("Vehicle")
+			.description("Represents a vehicle.")
+			.since("INSERT VERSION")
+			.changer(DefaultChangers.entityChanger)
+		);
+
 	}
 
 }

src/main/java/ch/njol/skript/classes/data/DefaultOperations.java

@@ -99,21 +99,24 @@ public class DefaultOperations {
 		// Timespan - Number
 		// Number - Timespan
 		Arithmetics.registerOperation(Operator.MULTIPLICATION, Timespan.class, Number.class, (left, right) -> {
-			long scalar = right.longValue();
-			if (scalar < 0)
+			double scalar = right.doubleValue();
+			if (scalar < 0 || !Double.isFinite(scalar))
 				return null;
-			return new Timespan(Math2.multiplyClamped(left.getAs(TimePeriod.MILLISECOND), scalar));
+			double value = left.getAs(TimePeriod.MILLISECOND) * scalar;
+			return new Timespan((long) Math.min(value, Long.MAX_VALUE));
 		}, (left, right) -> {
-			long scalar = left.longValue();
-			if (scalar < 0)
+			double scalar = left.doubleValue();
+			if (scalar < 0 || !Double.isFinite(scalar))
 				return null;
-			return new Timespan(scalar * right.getAs(TimePeriod.MILLISECOND));
+			double value = right.getAs(TimePeriod.MILLISECOND) * scalar;
+			return new Timespan((long) Math.min(value, Long.MAX_VALUE));
 		});
 		Arithmetics.registerOperation(Operator.DIVISION, Timespan.class, Number.class, (left, right) -> {
-			long scalar = right.longValue();
-			if (scalar <= 0)
+			double scalar = right.doubleValue();
+			if (scalar <= 0 || !Double.isFinite(scalar))
 				return null;
-			return new Timespan(left.getAs(TimePeriod.MILLISECOND) / scalar);
+			double value = left.getAs(TimePeriod.MILLISECOND) / scalar;
+			return new Timespan((long) Math.min(value, Long.MAX_VALUE));
 		});
 
 		// Timespan / Timespan = Number

src/main/java/ch/njol/skript/doc/Documentation.java

@@ -286,7 +286,12 @@ private static void insertSyntaxElement(final PrintWriter pw, final SyntaxElemen
 		Class<?> elementClass = info.getElementClass();
 		if (elementClass.getAnnotation(NoDoc.class) != null)
 			return;
-		if (elementClass.getAnnotation(Name.class) == null || elementClass.getAnnotation(Description.class) == null || elementClass.getAnnotation(Examples.class) == null || elementClass.getAnnotation(Since.class) == null) {
+		if (elementClass.getAnnotation(Name.class) == null
+			|| elementClass.getAnnotation(Description.class) == null
+			|| (!elementClass.isAnnotationPresent(Examples.class)
+			&& !elementClass.isAnnotationPresent(Example.class)
+			&& !elementClass.isAnnotationPresent(Example.Examples.class))
+			|| elementClass.getAnnotation(Since.class) == null) {
 			Skript.warning("" + elementClass.getSimpleName() + " is missing information");
 			return;
 		}

src/main/java/ch/njol/skript/doc/Example.java

@@ -0,0 +1,50 @@
+package ch.njol.skript.doc;
+
+import java.lang.annotation.*;
+
+/**
+ * An example to be used in documentation for the annotated element.
+ * Multiple example annotations can be stacked on a single syntax element.
+ * <p>
+ * Each annotation should include a single example.
+ * This can be used instead of the existing {@link ch.njol.skript.doc.Examples} annotation.
+ * <p>
+ * <b>Multi-line examples</b> should use multi-line strings.
+ * Note that whitespace and quotes do not need to be escaped in this mode.
+ * The indentation will start from the least-indented line (and most IDEs provide a guideline to show this).
+ * <pre>{@code
+ * @Example("set player's health to 1")
+ * @Example("""
+ * 		if player's health is greater than 10:
+ * 			send "Wow you're really healthy!"
+ * 		""")
+ * @Example("""
+ * 		# sets the player's health to 1
+ * 		set player's health to 1""")
+ * public class MyExpression extends ... {
+ * }
+ * }</pre>
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Repeatable(Example.Examples.class)
+@Documented
+public @interface Example {
+
+	String value();
+
+	boolean inTrigger() default true; // todo needed?
+
+	/**
+	 * The internal container annotation for multiple examples.
+	 */
+	@Target(ElementType.TYPE)
+	@Retention(RetentionPolicy.RUNTIME)
+	@Documented
+	@interface Examples {
+
+		Example[] value();
+
+	}
+
+}

src/main/java/ch/njol/skript/doc/HTMLGenerator.java

@@ -20,6 +20,7 @@
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.block.BlockCanBuildEvent;
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.skriptlang.skript.lang.entry.EntryData;
 import org.skriptlang.skript.lang.entry.EntryValidator;
@@ -29,12 +30,7 @@
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.text.SimpleDateFormat;
-import java.util.ArrayList;
-import java.util.Comparator;
-import java.util.Date;
-import java.util.Iterator;
-import java.util.List;
-import java.util.Locale;
+import java.util.*;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
@@ -387,21 +383,30 @@ private static String minifyHtml(String page) {
 		return sb.toString();
 	}
 
-	private static String handleIf(String desc, String start, boolean value) {
+	/**
+	 * Handles an optional part in an HTML description.
+	 * @param desc The existing description.
+	 * @param condition The condition string to check.
+	 * @param value Whether
+	 * @return The modified description.
+	 */
+	private static String handleIf(String desc, String condition, boolean value) {
 		assert desc != null;
-		int ifStart = desc.indexOf(start);
+		int ifStart = desc.indexOf(condition);
+
 		while (ifStart != -1) {
 			int ifEnd = desc.indexOf("${end}", ifStart);
-			String data = desc.substring(ifStart + start.length() + 1, ifEnd);
+			String data = desc.substring(ifStart + condition.length() + 1, ifEnd);
 
 			String before = desc.substring(0, ifStart);
 			String after = desc.substring(ifEnd + 6);
+
 			if (value)
-				desc = before + data + after;
+				desc = before + data + after; // include if condition is met
 			else
-				desc = before + after;
+				desc = before + after; // skip if condition is not met
 
-			ifStart = desc.indexOf(start, ifEnd);
+			ifStart = desc.indexOf(condition, ifEnd);
 		}
 
 		return desc;
@@ -438,10 +443,7 @@ private String generateAnnotated(String descTemp, SyntaxElementInfo<?> info, @Nu
 			.replace("\\", "\\\\").replace("\"", "\\\"").replace("\t", "    "));
 
 		// Examples
-		Examples examples = c.getAnnotation(Examples.class);
-		desc = desc.replace("${element.examples}", Joiner.on("<br>").join(getDefaultIfNullOrEmpty((examples != null ? Documentation.escapeHTML(examples.value()) : null), "Missing examples.")));
-		desc = desc.replace("${element.examples-safe}", Joiner.on("<br>").join(getDefaultIfNullOrEmpty((examples != null ? Documentation.escapeHTML(examples.value()) : null), "Missing examples."))
-			.replace("\\", "\\\\").replace("\"", "\\\"").replace("\t", "    "));
+		desc = extractExamples(desc, c);
 
 		// Documentation ID
 		desc = desc.replace("${element.id}", DocumentationIdProvider.getId(info));
@@ -542,6 +544,29 @@ private String generateAnnotated(String descTemp, SyntaxElementInfo<?> info, @Nu
 		return desc;
 	}
 
+	private @NotNull String extractExamples(String desc, Class<?> syntax) {
+		if (syntax.isAnnotationPresent(Example.class)) {
+			Example examples = syntax.getAnnotation(Example.class);
+			return this.addExamples(desc, examples.value());
+		} else if (syntax.isAnnotationPresent(Example.Examples.class)) {
+			Example.Examples examples = syntax.getAnnotation(Example.Examples.class);
+			return this.addExamples(desc, Arrays.stream(examples.value())
+				.map(Example::value).toArray(String[]::new));
+		} else if (syntax.isAnnotationPresent(Examples.class)) {
+			Examples examples = syntax.getAnnotation(Examples.class);
+			return this.addExamples(desc, examples.value());
+		} else {
+			return this.addExamples(desc, (String[]) null);
+		}
+	}
+
+	private @NotNull String addExamples(String desc, String @Nullable ... examples) {
+		desc = desc.replace("${element.examples}", Joiner.on("<br>").join(getDefaultIfNullOrEmpty((examples != null ? Documentation.escapeHTML(examples) : null), "Missing examples.")));
+		desc = desc.replace("${element.examples-safe}", Joiner.on("<br>").join(getDefaultIfNullOrEmpty((examples != null ? Documentation.escapeHTML(examples) : null), "Missing examples."))
+			.replace("\\", "\\\\").replace("\"", "\\\"").replace("\t", "    "));
+		return desc;
+	}
+
 	private String generateEvent(String descTemp, SkriptEventInfo<?> info, @Nullable String page) {
 		Class<?> c = info.getElementClass();
 		String desc;
@@ -605,10 +630,14 @@ private String generateEvent(String descTemp, SkriptEventInfo<?> info, @Nullable
 		}
 		desc = desc.replace("${element.events-safe}", events == null ? "" : Joiner.on(", ").join((events != null ? events.value() : null)));
 
-		// Required Plugins
-		String[] requiredPlugins = info.getRequiredPlugins();
-		desc = handleIf(desc, "${if required-plugins}", requiredPlugins != null);
-		desc = desc.replace("${element.required-plugins}", Joiner.on(", ").join(requiredPlugins == null ? new String[0] : requiredPlugins));
+		// RequiredPlugins
+		String[] plugins = info.getRequiredPlugins();
+		desc = handleIf(desc, "${if required-plugins}", plugins != null && plugins.length > 0);
+		if (plugins == null) {
+			desc = desc.replace("${element.required-plugins}", "");
+		} else {
+			desc = desc.replace("${element.required-plugins}", Joiner.on(", ").join(plugins));
+		}
 
 		// New Elements
 		desc = handleIf(desc, "${if new-element}", NEW_TAG_PATTERN.matcher(since).find());

src/main/java/ch/njol/skript/doc/JSONGenerator.java

@@ -13,6 +13,7 @@
 import com.google.gson.JsonArray;
 import com.google.gson.JsonObject;
 import com.google.gson.JsonPrimitive;
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.skriptlang.skript.lang.structure.Structure;
 import org.skriptlang.skript.lang.structure.StructureInfo;
@@ -21,6 +22,7 @@
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.Arrays;
 import java.util.Iterator;
 import java.util.Objects;
 import java.util.stream.Stream;
@@ -39,7 +41,7 @@ public JSONGenerator(File templateDir, File outputDir) {
 	 * @param strings the String array to convert
 	 * @return the JsonArray containing the Strings
 	 */
-	private static @Nullable JsonArray convertToJsonArray(String @Nullable [] strings) {
+	private static @Nullable JsonArray convertToJsonArray(String @Nullable ... strings) {
 		if (strings == null)
 			return null;
 		JsonArray jsonArray = new JsonArray();
@@ -73,9 +75,18 @@ public JSONGenerator(File templateDir, File outputDir) {
 			syntaxJsonObject.add("description", new JsonArray());
 		}
 
-		Examples examplesAnnotation = syntaxClass.getAnnotation(Examples.class);
-		if (examplesAnnotation != null) {
+		if (syntaxClass.isAnnotationPresent(Examples.class)) {
+			@NotNull Examples examplesAnnotation = syntaxClass.getAnnotation(Examples.class);
 			syntaxJsonObject.add("examples", convertToJsonArray(examplesAnnotation.value()));
+		} else if (syntaxClass.isAnnotationPresent(Example.Examples.class)) {
+			// If there are multiple examples, they get containerised
+			@NotNull Example.Examples examplesAnnotation = syntaxClass.getAnnotation(Example.Examples.class);
+			syntaxJsonObject.add("examples", convertToJsonArray(Arrays.stream(examplesAnnotation.value())
+				.map(Example::value).toArray(String[]::new)));
+		} else if (syntaxClass.isAnnotationPresent(Example.class)) {
+			// If the user adds just one example, it isn't containerised
+			@NotNull Example example = syntaxClass.getAnnotation(Example.class);
+			syntaxJsonObject.add("examples", convertToJsonArray(example.value()));
 		} else {
 			syntaxJsonObject.add("examples", new JsonArray());
 		}

src/main/java/ch/njol/skript/lang/SkriptEventInfo.java

@@ -27,8 +27,14 @@ public sealed class SkriptEventInfo<E extends SkriptEvent> extends StructureInfo
 	public final String name;
 
 	private ListeningBehavior listeningBehavior;
-	private String @Nullable [] description, examples, keywords, requiredPlugins;
-	private @Nullable String since, documentationID;
+
+	private String @Nullable [] description = null;
+	private String @Nullable [] examples = null;
+	private String @Nullable [] keywords = null;
+	private String @Nullable [] requiredPlugins = null;
+
+	private @Nullable String since = null;
+	private @Nullable String documentationID = null;
 
 	private final String id;
 

src/main/resources/lang/default.lang

@@ -2653,6 +2653,7 @@ types:
 	lootcontext: loot context¦s @a
 	bannerpatterntype: banner pattern type¦s @a
 	bannerpattern: banner pattern¦s @a
+	vehicle: vehicle¦s @a
 
 	# Skript
 	weathertype: weather type¦s @a