Update to 0.17.0, new way to define elements

 * @Datapath is no longer necessary and has been removed

 * Ethylene compile dependency is now `latest` (0.24.0)

 * @child annotation is now a path pointing to the child pointer (path), list, or node

 * When constructing lists of children, it is possible to mix paths and nodes, and chain references indefinitely

 * Passing a list in config when the element accepts a non-list child is possible iff the list is non-empty (the first element is used)

 * The @dataobject does not specify paths (or exist at all) if children are used

 * @default annotations can be placed on the element or data class to specify default elements

 * Additional methods added to ElementPath, in line with bringing the functionality closer to that of Java's Path

 * Improvements to error messages: element class information is printed when applicable, element path likewise

Author: Steanky

autodoc/src/main/kotlin/com/github/steanky/element/gradle/plugin/autodoc/AutodocTask.kt

@@ -2,7 +2,6 @@ package com.github.steanky.element.gradle.plugin.autodoc
 
 import com.github.steanky.element.core.ElementFactory
 import com.github.steanky.element.core.annotation.Child
-import com.github.steanky.element.core.annotation.ChildPath
 import com.github.steanky.element.core.annotation.DataObject
 import com.github.steanky.element.core.annotation.FactoryMethod
 import com.github.steanky.element.core.annotation.document.Description
@@ -13,20 +12,19 @@ import com.github.steanky.element.core.key.Constants
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.encodeToJsonElement
 import org.gradle.api.logging.Logger
-import org.gradle.api.tasks.*
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.OutputFile
+import org.gradle.api.tasks.SourceTask
+import org.gradle.api.tasks.TaskAction
 import java.io.File
-
-import java.lang.RuntimeException
 import java.util.regex.Pattern
 import javax.annotation.processing.*
 import javax.lang.model.SourceVersion
-import javax.lang.model.element.*
-import javax.lang.model.type.ArrayType
-import javax.lang.model.type.DeclaredType
-import javax.lang.model.type.TypeKind
-import javax.lang.model.type.TypeMirror
-import javax.lang.model.type.TypeVariable
-import javax.lang.model.type.WildcardType
+import javax.lang.model.element.ElementKind
+import javax.lang.model.element.ExecutableElement
+import javax.lang.model.element.TypeElement
+import javax.lang.model.element.VariableElement
+import javax.lang.model.type.*
 import javax.lang.model.util.Types
 import javax.tools.JavaFileObject
 import javax.tools.ToolProvider
@@ -339,7 +337,7 @@ abstract class AutodocTask : SourceTask() {
         }
 
         private fun processParameters(typeElement: TypeElement): List<Parameter> {
-            typeElement.dataType()?.let { (dataType, mappings) ->
+            typeElement.dataType()?.let { (dataType, _) ->
                 val parameters = dataType
                         .getAnnotationsByType(com.github.steanky.element.core.annotation.document.Parameter::class.java)
                 if (!parameters.isNullOrEmpty()) {
@@ -352,7 +350,7 @@ abstract class AutodocTask : SourceTask() {
                     return dataType.recordComponents.map { component ->
                         val accessor = component.accessor
 
-                        val type = accessor.type() ?: tryLink(accessor, mappings) ?: simpleTypeName(component.asType())
+                        val type = accessor.type() ?: simpleTypeName(component.asType())
                         val name = accessor.name()
                         val behavior = accessor.description()
 
@@ -366,23 +364,6 @@ abstract class AutodocTask : SourceTask() {
             return listOf()
         }
 
-        private fun tryLink(component: ExecutableElement, map: Map<String, VariableElement>): String? {
-            component.getAnnotation(ChildPath::class.java)?.let { childPath ->
-                map[childPath.value]?.let { variableElement ->
-                    processingEnv.typeUtils.asElement(variableElement.asType()).asTypeElement()?.model()?.let { (model, _) ->
-                        return model.value
-                    }
-
-                    return null
-                }
-
-                logger.error("No child dependency named ${childPath.value}")
-                return null
-            }
-
-            return null
-        }
-
         private fun simpleTypeName(componentType: TypeMirror): String {
             val typeUtils = processingEnv.typeUtils
 
@@ -477,8 +458,8 @@ abstract class AutodocTask : SourceTask() {
                 typeUtils.directSupertypes(component).forEach {superMirror ->
                     superMirror as DeclaredType
 
-                    val mirorErasure = typeUtils.erasure(superMirror)
-                    if (typeUtils.isSameType(mapType, mirorErasure)) {
+                    val mirrorErasure = typeUtils.erasure(superMirror)
+                    if (typeUtils.isSameType(mapType, mirrorErasure)) {
                         val typeArguments = superMirror.typeArguments
                         return "map of ${simpleTypeName(typeArguments[0])} -> ${simpleTypeName(typeArguments[1])}"
                     }

buildSrc/src/main/kotlin/element.java-conventions.gradle.kts

@@ -3,7 +3,7 @@ plugins {
 }
 
 group = "com.github.steanky"
-version = "0.16.0"
+version = "0.17.0"
 
 java {
     toolchain.languageVersion.set(JavaLanguageVersion.of(17))

core/src/main/java/com/github/steanky/element/core/BasicElementInspector.java

@@ -37,11 +37,11 @@ public BasicElementInspector(final @NotNull FactoryResolver factoryResolver,
     public @NotNull Information inspect(final @NotNull Class<?> elementClass) {
         final int modifiers = elementClass.getModifiers();
         if (!Modifier.isStatic(elementClass.getModifiers()) && elementClass.getDeclaringClass() != null) {
-            throw elementException(elementClass, "non-static with declaring class");
+            throw elementException(elementClass, "Non-static nested class");
         }
 
         if (!Modifier.isPublic(modifiers)) {
-            throw elementException(elementClass, "not public");
+            throw elementException(elementClass, "Not public");
         }
 
         final Mutable<ConfigProcessor<?>> mutable = new MutableObject<>(

core/src/main/java/com/github/steanky/element/core/BasicElementTypeIdentifier.java

@@ -34,6 +34,6 @@ public BasicElementTypeIdentifier(final @NotNull KeyParser keyParser) {
             return keyParser.parseKey(value);
         }
 
-        throw elementException(elementType, "no ElementModel annotation");
+        throw elementException(elementType, "No @Model annotation");
     }
 }

core/src/main/java/com/github/steanky/element/core/ElementException.java

@@ -1,9 +1,22 @@
 package com.github.steanky.element.core;
 
+import com.github.steanky.element.core.path.ElementPath;
+
 /**
- * Represents a generic exception thrown by various parts of the Element API.
+ * Represents a generic exception thrown by various parts of the Element API. Can have an associated {@link ElementPath}
+ * and {@link Class} which, respectively, define a path and/or class related to this error.
  */
 public class ElementException extends RuntimeException {
+    /**
+     * The element class associated with this error.
+     */
+    private Class<?> elementClass;
+
+    /**
+     * The element path associated with this error.
+     */
+    private ElementPath elementPath;
+
     /**
      * Creates a new ElementException with no detail message or cause.
      */
@@ -38,4 +51,64 @@ public ElementException(String message, Throwable cause) {
     public ElementException(Throwable cause) {
         super(cause);
     }
+
+    /**
+     * Sets the element class associated with this error. This method does nothing if an element class is already set.
+     *
+     * @param elementClass the element class
+     */
+    public void setElementClass(Class<?> elementClass) {
+        if (this.elementClass == null) {
+            this.elementClass = elementClass;
+        }
+    }
+
+    /**
+     * Sets the {@link ElementPath} associated with this error. This method does nothing if an error path is already set.
+     *
+     * @param elementPath the path
+     */
+    public void setElementPath(ElementPath elementPath) {
+        if (this.elementPath == null) {
+            this.elementPath = elementPath;
+        }
+    }
+
+    /**
+     * The element class which had an error.
+     *
+     * @return the element class
+     */
+    public Class<?> elementClass() {
+        return elementClass;
+    }
+
+    /**
+     * The path of the element object which had an error.
+     *
+     * @return the error path
+     */
+    public ElementPath errorPath() {
+        return elementPath;
+    }
+
+    @Override
+    public String getMessage() {
+        final String baseMessage = super.getMessage();
+        final StringBuilder builder = new StringBuilder(baseMessage.length() + 100);
+        final Class<?> elementClass = this.elementClass;
+        final ElementPath elementPath = this.elementPath;
+
+        builder.append("\"").append(baseMessage).append("\"");
+        if (elementClass != null) {
+            builder.append(System.lineSeparator()).append("Relevant class: ").append(elementClass);
+        }
+
+        if (elementPath != null) {
+            builder.append(System.lineSeparator()).append("Data path: '").append(elementPath).append("'");
+        }
+
+
+        return builder.toString();
+    }
 }

core/src/main/java/com/github/steanky/element/core/HashRegistry.java

@@ -3,7 +3,11 @@
 import net.kyori.adventure.key.Key;
 import org.jetbrains.annotations.NotNull;
 
-import java.util.*;
+import java.util.Collection;
+import java.util.Map;
+import java.util.Objects;
+
+import static com.github.steanky.element.core.util.Validate.elementException;
 
 /**
  * A {@link Map}-based Registry implementation. Uses a backing immutable map combined with copy-on-write semantics to
@@ -75,7 +79,7 @@ public void registerBulk(final @NotNull Collection<? extends Map.Entry<? extends
         Objects.requireNonNull(key);
         final TRegistrant registrant = map.get(key);
         if (registrant == null) {
-            throw new NoSuchElementException("no registrant under key " + key);
+            throw elementException("No registrant under key " + key);
         }
 
         return registrant;

core/src/main/java/com/github/steanky/element/core/annotation/Child.java

@@ -2,8 +2,7 @@
 
 import com.github.steanky.element.core.context.ElementContext;
 import com.github.steanky.element.core.dependency.DependencyProvider;
-import com.github.steanky.element.core.key.Constants;
-import com.github.steanky.element.core.key.KeyString;
+import com.github.steanky.element.core.path.ElementPath;
 import org.jetbrains.annotations.NotNull;
 
 import java.lang.annotation.*;
@@ -17,10 +16,10 @@
 @Target(ElementType.PARAMETER)
 public @interface Child {
     /**
-     * The identifier of this child dependency.
+     * The path of the child dependency, relative to the configuration object on which it is defined. Syntax is
+     * interpreted as if by calling {@link ElementPath#of(String)}.
      *
-     * @return the identifier of this child dependency, or {@link Constants#DEFAULT} to indicate that the value of its
-     * Model annotation should be used instead
+     * @return the value of this annotation
      */
-    @NotNull @KeyString String value() default Constants.DEFAULT;
+    @NotNull String value();
 }