Merge in select generics classes from genericsTake2. (#1406)

This cherry-picked merge is phase 1 of merging in support for generics.
By itself, this code does nothing, but some changes to CClassType are
necessarily not dark. Most methods stubbed, but some actually call in to
the dark code, but should not be used yet.

Author: LadyCailin

src/main/java/com/laytonsmith/PureUtilities/Common/StringUtils.java

@@ -303,6 +303,30 @@ public static String Join(List list, String glue) {
 		return Join(list, glue, null, null, null);
 	}
 
+	/**
+	 * Joins a list together, rendering each item with the custom renderer.
+	 * @param <T> The list type
+	 * @param list The list to concatenate
+	 * @param glue The glue to use
+	 * @param renderer The item renderer. If null, toString will be used by default on each item.
+	 * @return The concatenated string
+	 */
+	public static <T> String Join(List<T> list, String glue, Renderer<T> renderer) {
+		return Join(list, glue, null, null, null, renderer);
+	}
+
+	/**
+	 * Joins an array together, rendering each item with the custom renderer.
+	 * @param <T> The array type
+	 * @param list The array to concatenate
+	 * @param glue The glue to use
+	 * @param renderer The item renderer. If null, toString will be used by default on each item.
+	 * @return The concatenated string
+	 */
+	public static <T> String Join(T[] list, String glue, Renderer<T> renderer) {
+		return Join(list, glue, null, null, null, renderer);
+	}
+
 	/**
 	 * Joins a list together (using StringBuilder's {@link StringBuilder#append(Object)} method
 	 * to "toString" the Object) using the specified string for glue.

src/main/java/com/laytonsmith/PureUtilities/Either.java

@@ -0,0 +1,116 @@
+package com.laytonsmith.PureUtilities;
+
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * The {@code Either} class can contain neither of, or one of either the specified types of values.
+ * @param <L> The first possible type.
+ * @param <R> The second possible type.
+ */
+public final class Either<L, R> {
+
+	/**
+	 * Creates a new Either object with the first possible type.
+	 * @param <L> The first possible type, which is the type of the input parameter.
+	 * @param <R> The other possible type, which this value will not contain.
+	 * @param value The value to store.
+	 * @return A new Either object.
+	 */
+	public static <L, R> Either<L, R> left(L value) {
+		return new Either<>(Optional.of(value), Optional.empty());
+	}
+
+	/**
+	 * Creates a new Either object with the second possible type.
+	 * @param <L> The other possible type, which this value will not contain.
+	 * @param <R> The second possible type, which is the type of the input parameter.
+	 * @param value The value to store.
+	 * @return A new Either object.
+	 */
+	public static <L, R> Either<L, R> right(R value) {
+		return new Either<>(Optional.empty(), Optional.of(value));
+	}
+
+	/**
+	 * Creates a new Either object, which does not contain any value.
+	 * @param <L> The first possible type.
+	 * @param <R> The second possible type.
+	 * @return A new, empty, Either object.
+	 */
+	public static <L, R> Either<L, R> neither() {
+		return new Either<>(Optional.empty(), Optional.empty());
+	}
+
+	private final Optional<L> left;
+	private final Optional<R> right;
+
+	private Either(Optional<L> left, Optional<R> right) {
+		this.left = left;
+		this.right = right;
+	}
+
+	/**
+	 * Returns the left value. May be empty, even if the other value is also empty.
+	 * @return
+	 */
+	public Optional<L> getLeft() {
+		return this.left;
+	}
+
+	/**
+	 * Returns the left value. May be empty, even if the other value is also empty.
+	 * @return
+	 */
+	public Optional<R> getRight() {
+		return this.right;
+	}
+
+	/**
+	 * Returns if there was a left side.
+	 * @return
+	 */
+	public boolean hasLeft() {
+		return this.left.isPresent();
+	}
+
+	/**
+	 * Returns if there was a right side.
+	 * @return
+	 */
+	public boolean hasRight() {
+		return this.right.isPresent();
+	}
+
+	@Override
+	public int hashCode() {
+		int hash = 3;
+		hash = 19 * hash + Objects.hashCode(this.left);
+		hash = 19 * hash + Objects.hashCode(this.right);
+		return hash;
+	}
+
+	@Override
+	public boolean equals(Object obj) {
+		if(this == obj) {
+			return true;
+		}
+		if(obj == null) {
+			return false;
+		}
+		if(getClass() != obj.getClass()) {
+			return false;
+		}
+		final Either<?, ?> other = (Either<?, ?>) obj;
+		if(!Objects.equals(this.left, other.left)) {
+			return false;
+		}
+		return Objects.equals(this.right, other.right);
+	}
+
+	@Override
+	public String toString() {
+		return "Either{" + "left=" + left + ", right=" + right + '}';
+	}
+
+}

src/main/java/com/laytonsmith/core/MethodScriptCompiler.java

@@ -21,7 +21,6 @@
 import com.laytonsmith.core.compiler.TokenStream;
 import com.laytonsmith.core.compiler.analysis.StaticAnalysis;
 import com.laytonsmith.core.constructs.CBareString;
-import com.laytonsmith.core.constructs.CClassType;
 import com.laytonsmith.core.constructs.CDecimal;
 import com.laytonsmith.core.constructs.CDouble;
 import com.laytonsmith.core.constructs.CFunction;
@@ -37,6 +36,7 @@
 import com.laytonsmith.core.constructs.CVoid;
 import com.laytonsmith.core.constructs.Construct;
 import com.laytonsmith.core.constructs.IVariable;
+import com.laytonsmith.core.constructs.SourceType;
 import com.laytonsmith.core.constructs.Target;
 import com.laytonsmith.core.constructs.Token;
 import com.laytonsmith.core.constructs.Token.TType;
@@ -1753,11 +1753,11 @@ public static ParseTree compile(TokenStream stream, Environment environment,
 				ParseTree previous = tree.getChildAt(tree.getChildren().size() - 1);
 				// TODO: Add LHSType as well, though this will not work as is with user objects. It may need
 				// to be moved into a node modifier or something.
-				if(!(previous.getData() instanceof CClassType)) {
+				if(!(previous.getData() instanceof SourceType)) {
 					throw new ConfigCompileException("Unexpected varargs token (\"...\"). This can only be used with types.", t.target);
 				}
-				if(previous.getData() instanceof CClassType c) {
-					previous.setData(c.asVarargs());
+				if(previous.getData() instanceof SourceType st) {
+					previous.setData(st.asVariadicType(null));
 				}
 				continue;
 			} else if(t.type == TType.LIT) {

src/main/java/com/laytonsmith/core/Procedure.java

@@ -68,7 +68,7 @@ public Procedure(String name, CClassType returnType, List<IVariable> varList, Sm
 		this.procComment = procComment;
 		for(int i = 0; i < varList.size(); i++) {
 			IVariable var = varList.get(i);
-			if(var.getDefinedType().isVarargs() && i != varList.size() - 1) {
+			if(var.getDefinedType().isVariadicType() && i != varList.size() - 1) {
 				throw new CREFormatException("Varargs can only be added to the last argument.", t);
 			}
 			try {
@@ -77,7 +77,7 @@ public Procedure(String name, CClassType returnType, List<IVariable> varList, Sm
 				this.varList.put(var.getVariableName(), var);
 			}
 			this.varIndex.add(var);
-			if(var.getDefinedType().isVarargs() && var.ival() != CNull.UNDEFINED) {
+			if(var.getDefinedType().isVariadicType() && var.ival() != CNull.UNDEFINED) {
 				throw new CREFormatException("Varargs may not have default values", t);
 			}
 			this.originals.put(var.getVariableName(), var.ival());
@@ -218,10 +218,10 @@ public Mixed execute(List<Mixed> args, Environment oldEnv, Target t) {
 			arguments.push(c, t);
 			if(this.varIndex.size() > varInd
 					|| (!this.varIndex.isEmpty()
-						&& this.varIndex.get(this.varIndex.size() - 1).getDefinedType().isVarargs())) {
+						&& this.varIndex.get(this.varIndex.size() - 1).getDefinedType().isVariadicType())) {
 				IVariable var;
 				if(varInd < this.varIndex.size() - 1
-						|| !this.varIndex.get(this.varIndex.size() - 1).getDefinedType().isVarargs()) {
+						|| !this.varIndex.get(this.varIndex.size() - 1).getDefinedType().isVariadicType()) {
 					var = this.varIndex.get(varInd);
 				} else {
 					var = this.varIndex.get(this.varIndex.size() - 1);
@@ -242,7 +242,7 @@ public Mixed execute(List<Mixed> args, Environment oldEnv, Target t) {
 				}
 
 				// Type check vararg parameter.
-				if(var.getDefinedType().isVarargs()) {
+				if(var.getDefinedType().isVariadicType()) {
 					if(InstanceofUtil.isInstanceof(c.typeof(), var.getDefinedType().getVarargsBaseType(), env)) {
 						vararg.push(c, t);
 						continue;

src/main/java/com/laytonsmith/core/compiler/FileOptions.java

@@ -368,6 +368,10 @@ public static enum SuppressWarning implements Documentation {
 				MSVersion.V3_3_5, SeverityLevel.MEDIUM),
 		UnexpectedStatement("In strict mode, unexpected statements are an error, but in non-strict mode, they are"
 				+ " a warning.", MSVersion.V3_3_5, SeverityLevel.HIGH),
+		GenericTypeOverrides("When using generics, defining a typename which matches an in-scope actual object type"
+				+ " can lead to confusion, since references to the original type will no longer reference the"
+				+ " actual type, but rather the typename. Thus, this should be avoided.", MSVersion.V3_3_5,
+				SeverityLevel.HIGH),
 		PossibleUnexpectedExecution("If the parenthesis following a token is on a different line as the previous"
 				+ " token, and it in general looks like a value that might be executable, this warning is"
 				+ " issued, as it will cause an attempt at executing the previous statement. This"

src/main/java/com/laytonsmith/core/compiler/signature/FunctionSignature.java

@@ -8,6 +8,7 @@
 import com.laytonsmith.PureUtilities.Common.StringUtils;
 import com.laytonsmith.core.constructs.CClassType;
 import com.laytonsmith.core.constructs.InstanceofUtil;
+import com.laytonsmith.core.constructs.generics.GenericDeclaration;
 import com.laytonsmith.core.environments.Environment;
 
 /**
@@ -44,6 +45,13 @@ public FunctionSignature(ReturnType returnType) {
 		this(returnType, new ArrayList<>(), new ArrayList<>(), false);
 	}
 
+	/**
+	 * Stub for generics support — not yet implemented.
+	 */
+	public GenericDeclaration getGenericDeclaration() {
+		throw new UnsupportedOperationException("Not yet implemented");
+	}
+
 	protected void addParam(Param param) {
 		this.params.add(param);
 	}

src/main/java/com/laytonsmith/core/constructs/Auto.java

@@ -8,4 +8,5 @@
 public class Auto {
 
 	public static final CClassType TYPE = CClassType.AUTO;
+	public static final LeftHandSideType LHSTYPE = TYPE.asLeftHandSideType();
 }

src/main/java/com/laytonsmith/core/constructs/CArray.java

@@ -7,6 +7,8 @@
 import com.laytonsmith.core.MSLog;
 import com.laytonsmith.core.MSVersion;
 import com.laytonsmith.core.LogLevel;
+import com.laytonsmith.core.constructs.generics.GenericParameters;
+import com.laytonsmith.core.environments.Environment;
 import com.laytonsmith.core.exceptions.CRE.CRECastException;
 import com.laytonsmith.core.exceptions.CRE.CREFormatException;
 import com.laytonsmith.core.exceptions.CRE.CREIndexOverflowException;
@@ -58,6 +60,27 @@ public CArray(Target t) {
 		this(t, 0, (Mixed[]) null);
 	}
 
+	/**
+	 * Constructor with generic parameters and environment. GenericParameters are ignored for now.
+	 */
+	public CArray(Target t, GenericParameters genericParameters, Environment env) {
+		this(t);
+	}
+
+	/**
+	 * Constructor with initial capacity, generic parameters and environment. GenericParameters are ignored for now.
+	 */
+	public CArray(Target t, int initialCapacity, GenericParameters genericParameters, Environment env) {
+		this(t, initialCapacity);
+	}
+
+	/**
+	 * Constructor with items, generic parameters and environment. GenericParameters are ignored for now.
+	 */
+	public CArray(Target t, GenericParameters genericParameters, Environment env, Mixed... items) {
+		this(t, items);
+	}
+
 	public CArray(Target t, Mixed... items) {
 		this(t, 0, items);
 	}