Merge branch 'quiltmc-master' into alias

# Conflicts:
#	serializers-json5/src/main/java/org/quiltmc/config/api/serializers/Json5Serializer.java

README.md

@@ -7,6 +7,8 @@ management of config files.
 
 ## Usage
 
+### Importing via Gradle
+
 Quilt Config can be imported from the [Quilt maven](https://maven.quiltmc.org/repository/release/) using the following code in your `build.gradle`:
 
 ```groovy
@@ -25,3 +27,7 @@ dependencies {
     implementation("org.quiltmc.quilt-config.serializers:<serializer>:<version>")
 }
 ```
+
+### Documentation
+
+Quilt Config has extensive javadoc, as well as tutorials on the [Quilt Wiki](https://wiki.quiltmc.org/en). We recommend going to the [Getting Started tutorial](https://wiki.quiltmc.org/en/configuration/getting-started) to begin using out Quilt Config.

src/main/java/org/quiltmc/config/api/annotations/SerializedNameConvention.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2024 QuiltMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.quiltmc.config.api.annotations;
+
+import org.quiltmc.config.api.Config;
+import org.quiltmc.config.api.metadata.MetadataType;
+import org.quiltmc.config.api.metadata.NamingScheme;
+import org.quiltmc.config.api.metadata.NamingSchemes;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.Optional;
+
+/**
+ * Used to tell the serializer how properties should be formatted when saving to disk. Can be applied to configs, sections and properties. {@link SerializedName} must always take priority.
+ * @see SerializedName
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.TYPE})
+public @interface SerializedNameConvention {
+	/**
+	 * A {@link MetadataType} to supply to {@link Config.Builder#metadata}
+	 */
+	MetadataType<NamingScheme, SerializedNameConvention.Builder> TYPE = MetadataType.create(Optional::empty, SerializedNameConvention.Builder::new, true);
+
+	/**
+	 * One of the included {@link NamingSchemes}. The naming schemes must not generate spaces. {@link SerializedNameConvention#custom()} takes priority when not empty
+	 * @see NamingSchemes
+	 */
+	NamingSchemes value() default NamingSchemes.PASSTHROUGH;
+
+	/**
+	 * A fully qualified name of a class implementing the {@link NamingScheme}. Ignored when empty, takes precedence over {@link SerializedNameConvention#value()} otherwise.
+	 */
+	String custom() default "";
+
+	final class Builder implements MetadataType.Builder<NamingScheme> {
+		private NamingScheme scheme;
+
+		public Builder() {
+			scheme = NamingSchemes.PASSTHROUGH;
+		}
+
+		public void set(NamingScheme scheme) {
+			if (scheme == NamingSchemes.SPACE_SEPARATED_LOWER_CASE || scheme == NamingSchemes.SPACE_SEPARATED_LOWER_CASE_INITIAL_UPPER_CASE || scheme == NamingSchemes.TITLE_CASE) {
+				throw new IllegalArgumentException("Scheme with spaces unsupported for serialized names");
+			}
+			this.scheme = scheme;
+		}
+
+		@Override
+		public NamingScheme build() {
+			return scheme;
+		}
+	}
+}

src/main/java/org/quiltmc/config/api/metadata/MetadataType.java

@@ -33,11 +33,13 @@ public final class MetadataType<T, B extends MetadataType.Builder<T>> {
 	private final Supplier<Optional<T>> defaultValueSupplier;
 	private final Function<Type, Optional<T>> trackedValueDefaultValueSupplier;
 	private final Supplier<B> builderSupplier;
+	private final boolean inherited;
 
-	private MetadataType(Supplier<Optional<T>> defaultValueSupplier, Function<Type, Optional<T>> trackedValueDefaultValueSupplier, Supplier<B> builderSupplier) {
+	private MetadataType(Supplier<Optional<T>> defaultValueSupplier, Function<Type, Optional<T>> trackedValueDefaultValueSupplier, Supplier<B> builderSupplier, boolean inherited) {
 		this.defaultValueSupplier = defaultValueSupplier;
 		this.trackedValueDefaultValueSupplier = trackedValueDefaultValueSupplier;
 		this.builderSupplier = builderSupplier;
+		this.inherited = inherited;
 	}
 
 	/**
@@ -61,6 +63,10 @@ public B newBuilder() {
 		return this.builderSupplier.get();
 	}
 
+	public boolean isInherited() {
+		return inherited;
+	}
+
 	/**
 	 * Creates a new {@link MetadataType} with the given parameters.
 	 *
@@ -76,7 +82,7 @@ public B newBuilder() {
 	 * @return a new {@link MetadataType}
 	 */
 	public static <T, B extends Builder<T>> MetadataType<T, B> create(Supplier<Optional<T>> defaultSupplier, Function<Type, Optional<T>> trackedValueDefaultFunction, Supplier<B> builderSupplier) {
-		return new MetadataType<>(defaultSupplier, trackedValueDefaultFunction, builderSupplier);
+		return new MetadataType<>(defaultSupplier, trackedValueDefaultFunction, builderSupplier, false);
 	}
 
 	/**
@@ -85,15 +91,52 @@ public static <T, B extends Builder<T>> MetadataType<T, B> create(Supplier<Optio
 	 * @return a new {@link MetadataType}
 	 */
 	public static <T, B extends Builder<T>> MetadataType<T, B> create(Supplier<Optional<T>> defaultSupplier, Supplier<B> builderSupplier) {
-		return new MetadataType<>(defaultSupplier, t -> defaultSupplier.get(), builderSupplier);
+		return create(defaultSupplier, builderSupplier, false);
 	}
 
 	/**
 	 * @param builderSupplier supplies a new instance of the {@link MetadataType}'s builder class
 	 * @return a new {@link MetadataType}
 	 */
 	public static <T, B extends Builder<T>> MetadataType<T, B> create(Supplier<B> builderSupplier) {
-		return create(Optional::empty, builderSupplier);
+		return create(builderSupplier, false);
+	}
+	/**
+	 * Creates a new {@link MetadataType} with the given parameters.
+	 *
+	 * The {@link Type} passed to trackedValueDefaultFunction will always be one of the following:
+	 * <ul>
+	 *     <li>A basic type ({@link Integer}, {@link Long}, {@link Float}, {@link Double}, {@link Boolean}, {@link String}, or enum)</li>
+	 *     <li>{@link ValueList} or {@link ValueMap}</li>
+	 * </ul>
+	 *
+	 * @param defaultSupplier should provide the default value for the metadata for non-values
+	 * @param trackedValueDefaultFunction can infer the default metadata based on the type of a {@link TrackedValue}
+	 * @param builderSupplier supplies a new instance of the {@link MetadataType}'s builder class
+	 * @param inherited true if the metadata should be inherited to containers when using the builder or reflective config
+	 * @return a new {@link MetadataType}
+	 */
+	public static <T, B extends Builder<T>> MetadataType<T, B> create(Supplier<Optional<T>> defaultSupplier, Function<Type, Optional<T>> trackedValueDefaultFunction, Supplier<B> builderSupplier, boolean inherited) {
+		return new MetadataType<>(defaultSupplier, trackedValueDefaultFunction, builderSupplier, inherited);
+	}
+
+	/**
+	 * @param defaultSupplier should provide the default value for the metadata for non-values
+	 * @param builderSupplier supplies a new instance of the {@link MetadataType}'s builder class
+	 * @param inherited true if the metadata should be inherited when using the builder or reflective config
+	 * @return a new {@link MetadataType}
+	 */
+	public static <T, B extends Builder<T>> MetadataType<T, B> create(Supplier<Optional<T>> defaultSupplier, Supplier<B> builderSupplier, boolean inherited) {
+		return new MetadataType<>(defaultSupplier, t -> defaultSupplier.get(), builderSupplier, inherited);
+	}
+
+	/**
+	 * @param builderSupplier supplies a new instance of the {@link MetadataType}'s builder class
+	 * @param inherited true if the metadata should be inherited when using the builder or reflective config
+	 * @return a new {@link MetadataType}
+	 */
+	public static <T, B extends Builder<T>> MetadataType<T, B> create(Supplier<B> builderSupplier, boolean inherited) {
+		return create(Optional::empty, builderSupplier, inherited);
 	}
 
 	public interface Builder<T> {

src/main/java/org/quiltmc/config/api/metadata/NamingScheme.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 QuiltMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.quiltmc.config.api.metadata;
+
+/**
+ * A naming scheme to indicate how a string should be formatted.
+ * <p>
+ * Common formats are exposed in {@link NamingSchemes}.
+ * </p>
+ * @see org.quiltmc.config.api.annotations.SerializedNameConvention
+ */
+@FunctionalInterface
+public interface NamingScheme {
+	String coerce(String input);
+}