Merge remote-tracking branch 'quiltmc/master' into quiltmc-master

CHANGELOG.md

@@ -1,4 +1,42 @@
+# 1.3.0
+Quilt Config 1.3.0 brings a veritable treasure trove of new annotations, bringing a whopping 5 new metadata options! It also brings improvements to processors, fixes for the old `WrappedConfig` API, and some brand-new API to top it all off. With the new features added in this update, it should finally be viable to build the automatic config screen generator we've been dreaming of!
+
+- add `@SerializedNameConvention` annotation
+    - can be applied to classes, fields, and sections
+    - similar to `@SerializedName`, allows you to define a different name to be used for your config
+    - contrary to `@SerializedName`, you do not manually define the names: instead, the annotation will automatically convert your fields' names to match your chosen convention. for example, if you choose `snake_case`, as is the recommendation for TOML, `veryCuteField` becomes `very_cute_field` when serialized. `@SerializedName` will always take priority over converted names!
+    - the ideal way to use this is to apply it to your entire class via just one annotation!
+- add `@Alias` annotation
+    - can be applied to fields and sections 
+    - defines a previous name for the field or section, allowing you to migrate old configs. for example, if you now want a config section to be named `GeorgeSection` after you remove `Joe` and add `George`, you can use `@Alias("JoeSection")` to automatically migrate old `Joe` configs to the new `George` name
+- add `@DisplayName` annotation
+    - can be applied to configs, sections, and fields
+    - does not have any functionality in the base quilt config API. instead, this metadata is intended to be used by *metadata processors*, other programs making use of quilt config's information. an example metadata processor, and one we're planning to build, is an automatic config screen generator that works on all mods using quilt config!
+    - defines the user-facing name of the config field, for metadata processors implementing visual config editors. allows translatability!
+- add `@DisplayNameConvention` annotation
+    - can be applied to configs, sections, and fields
+    - similar to `@DisplayName`, has no functionality in base quilt config.
+    - defines a convention for transforming field names into display names, pulling from the same convention options as `@SerializedNameConvention`. for example, use `Space Separated Uppercase` to turn `superAdorableField` into `Super Adorable Field`. `@DisplayName` will always take priority over transformed names!
+- add `@ChangeWarning` annotation
+    - can be applied to configs, sections, and fields
+    - has no functionality in base quilt config
+    - used to tell visual config editors that they should show a warning before applying changes to config fields. contains lots of options for warnings: `RequiresRestart`, `Unsafe`, `Experimental`, `CustomTranslatable`, or `Custom`.
+- add an overload for `setValue` with the `serialize` parameter defaulted to `true` to allow for more concise code
+- allow using the `@Processor` annotation on sections
+- add extensive javadoc for `@Processor` (on top of the [tutorial](https://wiki.quiltmc.org/en/configuration/advanced-configuring#using-processors) on the developer wiki!)
+- allow using non-final values as config fields in `WrappedConfig`
+    - the previous system would simply not work for a few types, notably `String`: due to the field being final, the JVM would inline some references to it, making them unmodifiable for us
+    - now, a warning will be shown for anyone using `final` modifiers in their `WrappedConfig` classes. we recommend moving to `ReflectiveConfig`, but you can also simply remove the modifier!
+- add a new API for inheriting metadata in the `ConfigBuilder`: this allows adding metadata via processors to work the same way as adding it via annotations
+    - when the new `inherited` parameter of `MetadataType` is set to true, that metadata will be propagated to all children of the section or class you apply the metadata to
+- fix useless default comments being added for custom serializable values that do not override `toString`
+    - `# default: MySerializableClass@fe34g6` is not exactly helpful to the user
+- fix documentation mentioning primitive types (`int`, `double`, etc) when the `ReflectiveConfig` API calls for the usage of classes (`Integer`, `Double`)
+- add checkstyle to clean up code a bit
+
 # 1.2.0
+`1.2.0` marks the grand return of Quilt Config, after a long drought of updates. It introduces much better support for using QConf outside of [Quilt Loader](https://github.com/QuiltMC/quilt-loader), a new annotation for customising your automatically generated config files, a couple new API methods, and fixes some important bugs!
+
 -  published default serializers for **TOML** and **JSON5**, which you can use in your projects with [these instructions](<https://github.com/QuiltMC/quilt-config#usage>). these have a few benefits:
    - the user no longer has to implement their own serializers in a project using qconf. brilliant!
    - the builtin serializers will always support the latest annotations and features, instead of making you puzzle out how to add them to yours. neat!

build.gradle

@@ -9,7 +9,7 @@ sourceCompatibility = JavaVersion.VERSION_1_8
 targetCompatibility = JavaVersion.VERSION_1_8
 
 group 'org.quiltmc'
-version '1.2.0'
+version '1.3.0'
 
 java {
 	withSourcesJar()

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

@@ -0,0 +1,81 @@
+/*
+ * 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 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 config screen libraries that a warning should be displayed before applying changes. Can be applied to configs, sections and fields.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.TYPE})
+public @interface ChangeWarning {
+	/**
+	 * A {@link MetadataType} to supply to {@link Config.Builder#metadata}
+	 */
+	MetadataType<org.quiltmc.config.api.metadata.ChangeWarning, ChangeWarning.Builder> TYPE = MetadataType.create(Optional::empty, ChangeWarning.Builder::new, true);
+
+	/**
+	 * The {@link org.quiltmc.config.api.metadata.ChangeWarning.Type ChangeWarning.Type} of the change warning
+	 */
+	org.quiltmc.config.api.metadata.ChangeWarning.Type value();
+
+	/**
+	 * The message to display if the type is {@link org.quiltmc.config.api.metadata.ChangeWarning.Type#Custom ChangeWarning.Type.Custom}. In that case, Metadata processors (like config screens) may define translation keys that take precedence, else the translation key if it is {@link org.quiltmc.config.api.metadata.ChangeWarning.Type#CustomTranslatable ChangeWarning.Type.CustomTranslatable}.
+	 */
+	String customMessage() default "";
+
+	final class Builder implements MetadataType.Builder<org.quiltmc.config.api.metadata.ChangeWarning> {
+		private String message;
+		private org.quiltmc.config.api.metadata.ChangeWarning.Type type;
+
+		public Builder() {
+		}
+
+		/**
+		 * Utility for updating the type and the message
+		 */
+		public void setMessage(String message) {
+			this.setType(org.quiltmc.config.api.metadata.ChangeWarning.Type.Custom);
+			this.message = message;
+		}
+
+		public void setType(org.quiltmc.config.api.metadata.ChangeWarning.Type type) {
+			this.type = type;
+		}
+
+		/**
+		 * Utility for updating the type and the message
+		 */
+		public void setTranslatableMessage(String translationKey) {
+			this.setType(org.quiltmc.config.api.metadata.ChangeWarning.Type.CustomTranslatable);
+			this.setMessage(translationKey);
+		}
+
+		@Override
+		public org.quiltmc.config.api.metadata.ChangeWarning build() {
+			return new org.quiltmc.config.api.metadata.ChangeWarning(this.message, this.type);
+		}
+	}
+}

src/main/java/org/quiltmc/config/api/annotations/DisplayName.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 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 config screen libraries what name should be used for the annotated element when displaying it. Can be applied to configs, sections and fields.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.TYPE})
+public @interface DisplayName {
+	/**
+	 * A {@link MetadataType} to supply to {@link Config.Builder#metadata}
+	 */
+	MetadataType<org.quiltmc.config.api.metadata.DisplayName, DisplayName.Builder> TYPE = MetadataType.create(
+			Optional::empty,
+			DisplayName.Builder::new
+	);
+
+	/**
+	 * The name for the config screen to use if {@link #translatable} is false. A translation key pointing to the name to be used otherwise. Metadata processors (like config screens) may define generated translation keys taking precedence if it isn't translatable.
+	 */
+	String value();
+
+	/**
+	 * If true, {@link #value()} contains a translation key
+	 */
+	boolean translatable() default false;
+
+	final class Builder implements MetadataType.Builder<org.quiltmc.config.api.metadata.DisplayName> {
+		private String name;
+		private boolean translatable;
+
+		public Builder() {
+		}
+
+		public void setName(String name) {
+			this.name = name;
+		}
+
+		public void setTranslatable(boolean translatable) {
+			this.translatable = translatable;
+		}
+
+		@Override
+		public org.quiltmc.config.api.metadata.DisplayName build() {
+			return new org.quiltmc.config.api.metadata.DisplayName(this.name, this.translatable);
+		}
+	}
+}

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

@@ -0,0 +1,69 @@
+/*
+ * 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 config screen libraries how properties should be formatted when displaying them. Metadata processors (like config screens) may define generated translation keys taking precedence. Can be applied to configs, sections and properties. {@link DisplayName} must always take priority.
+ * @see org.quiltmc.config.api.annotations.DisplayName
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.TYPE})
+public @interface DisplayNameConvention {
+	/**
+	 * A {@link MetadataType} to supply to {@link Config.Builder#metadata}
+	 */
+	MetadataType<NamingScheme, DisplayNameConvention.Builder> TYPE = MetadataType.create(Optional::empty, DisplayNameConvention.Builder::new, true);
+
+	/**
+	 * One of the included {@link NamingSchemes}. {@link DisplayNameConvention#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 DisplayNameConvention#value()} otherwise.
+	 */
+	String custom() default "";
+
+	final class Builder implements MetadataType.Builder<NamingScheme> {
+		private NamingScheme scheme;
+
+		public Builder() {
+			this.scheme = NamingSchemes.PASSTHROUGH;
+		}
+
+		public void set(NamingScheme scheme) {
+			this.scheme = scheme;
+		}
+
+		@Override
+		public NamingScheme build() {
+			return this.scheme;
+		}
+	}
+}

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

@@ -0,0 +1,79 @@
+/*
+ * 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;
+
+import java.util.Objects;
+
+public class ChangeWarning {
+	private final String customMessage;
+	private final Type type;
+
+	public ChangeWarning(String customMessage, Type type) {
+		this.customMessage = customMessage;
+		this.type = type;
+	}
+
+	public String getCustomMessage() {
+		return this.customMessage;
+	}
+
+	public Type getType() {
+		return this.type;
+	}
+
+	@Override
+	public boolean equals(Object o) {
+		if (this == o) {
+			return true;
+		}
+
+		if (o == null || getClass() != o.getClass()) {
+			return false;
+		}
+
+		ChangeWarning that = (ChangeWarning) o;
+		return Objects.equals(this.customMessage, that.customMessage) && this.type == that.type;
+	}
+
+	@Override
+	public int hashCode() {
+		return Objects.hash(this.customMessage, this.type);
+	}
+
+	public enum Type {
+		/**
+		 * indicates that the changed setting requires a restart to apply
+		 */
+		RequiresRestart,
+		/**
+		 * indicates that stuff may or will go wrong, and that that is intentional
+		 */
+		Unsafe,
+		/**
+		 * indicates that stuff may or will go wrong, because the setting is not mature enough
+		 */
+		Experimental,
+		/**
+		 * the message parameter contains the raw message to be displayed
+		 */
+		CustomTranslatable,
+		/**
+		 * the message parameter contains the translation key to be displayed
+		 */
+		Custom
+	}
+}