[3.0.0] (breaking-update) update comments usage.

CarmJos · May 18, 2022 · 6b3a353 · 6b3a353
1 parent e9a0f0f
commit 6b3a353
Show file tree

Hide file tree

Showing 35 changed files with 395 additions and 310 deletions.
diff --git a/core/pom.xml b/core/pom.xml
@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyconfiguration-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>2.3.0</version>
+        <version>3.0.0</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <properties>

diff --git a/core/src/main/java/cc/carm/lib/configuration/core/ConfigInitializer.java b/core/src/main/java/cc/carm/lib/configuration/core/ConfigInitializer.java
@@ -1,14 +1,16 @@
 package cc.carm.lib.configuration.core;
 
-import cc.carm.lib.configuration.core.annotation.ConfigComment;
 import cc.carm.lib.configuration.core.annotation.ConfigPath;
-import cc.carm.lib.configuration.core.source.ConfigCommentInfo;
+import cc.carm.lib.configuration.core.annotation.HeaderComment;
+import cc.carm.lib.configuration.core.annotation.InlineComment;
 import cc.carm.lib.configuration.core.source.ConfigurationProvider;
 import cc.carm.lib.configuration.core.value.ConfigValue;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.lang.reflect.Field;
+import java.util.Arrays;
+import java.util.List;
 
 /**
  * 配置文件类初始化方法
@@ -45,7 +47,7 @@ public void initialize(@NotNull Class<? extends ConfigurationRoot> clazz, boolea
     public void initialize(@NotNull Class<? extends ConfigurationRoot> clazz,
                            boolean saveDefaults, boolean loadSubClasses) {
         initializeClass(
-                clazz, null,
+                clazz, null, null,
                 null, null, null,
                 saveDefaults, loadSubClasses
         );
@@ -60,33 +62,29 @@ public void initialize(@NotNull Class<? extends ConfigurationRoot> clazz,
 
     protected void initializeClass(@NotNull Class<?> clazz,
                                    @Nullable String parentPath, @Nullable String fieldName,
-                                   @Nullable ConfigPath fieldPath, @Nullable ConfigComment filedComments,
+                                   @Nullable ConfigPath fieldPath,
+                                   @Nullable HeaderComment fieldHeaderComments,
+                                   @Nullable InlineComment fieldInlineComments,
                                    boolean saveDefaults, boolean loadSubClasses) {
         String path = getClassPath(clazz, parentPath, fieldName, fieldPath);
-        this.provider.setComment(path, getClassComments(clazz, filedComments));
+        this.provider.setHeaderComment(path, getClassHeaderComments(clazz, fieldHeaderComments));
+        if (path != null) this.provider.setInlineComment(path, readInlineComments(fieldInlineComments));
+
         for (Field field : clazz.getDeclaredFields()) {
             initializeField(clazz, field, path, saveDefaults, loadSubClasses);
         }
 
+        if (!loadSubClasses) return;
         Class<?>[] classes = clazz.getDeclaredClasses();
-        if (loadSubClasses && classes.length > 0) {
-            // 逆向加载，保持顺序。
-            for (int i = classes.length - 1; i >= 0; i--) {
-                initializeClass(
-                        classes[i], path, classes[i].getSimpleName(),
-                        null, null,
-                        saveDefaults, true
-                );
-            }
+        for (int i = classes.length - 1; i >= 0; i--) {   // 逆向加载，保持顺序。
+            initializeClass(
+                    classes[i], path, classes[i].getSimpleName(),
+                    null, null, null,
+                    saveDefaults, true
+            );
         }
     }
 
-
-    protected void initializeValue(@NotNull ConfigValue<?> value, @NotNull String path,
-                                   @Nullable ConfigCommentInfo comments, boolean saveDefaults) {
-        value.initialize(provider, saveDefaults, path, comments);
-    }
-
     private void initializeField(@NotNull Class<?> source, @NotNull Field field, @Nullable String parent,
                                  boolean saveDefaults, boolean loadSubClasses) {
         try {
@@ -95,30 +93,53 @@ private void initializeField(@NotNull Class<?> source, @NotNull Field field, @Nu
             if (object instanceof ConfigValue<?>) {
                 initializeValue(
                         (ConfigValue<?>) object, getFieldPath(field, parent),
-                        ConfigCommentInfo.fromAnnotation(field.getAnnotation(ConfigComment.class)),
+                        field.getAnnotation(HeaderComment.class),
+                        field.getAnnotation(InlineComment.class),
                         saveDefaults
                 );
             } else if (object instanceof Class<?>) {
                 initializeClass(
                         (Class<?>) object, parent, field.getName(),
                         field.getAnnotation(ConfigPath.class),
-                        field.getAnnotation(ConfigComment.class),
+                        field.getAnnotation(HeaderComment.class),
+                        field.getAnnotation(InlineComment.class),
                         saveDefaults, loadSubClasses
                 );
             }
         } catch (IllegalAccessException ignored) {
         }
     }
 
-    protected void setComments(@Nullable String path, @Nullable ConfigCommentInfo comments) {
-        if (comments != null) this.provider.setComment(path, comments);
+    protected void initializeValue(@NotNull ConfigValue<?> value, @NotNull String path,
+                                   @Nullable HeaderComment fieldHeaderComment,
+                                   @Nullable InlineComment fieldInlineComment,
+                                   boolean saveDefaults) {
+        value.initialize(
+                provider, saveDefaults, path,
+                readHeaderComments(fieldHeaderComment),
+                readInlineComments(fieldInlineComment)
+        );
     }
 
-    protected static @Nullable ConfigCommentInfo getClassComments(@NotNull Class<?> clazz,
-                                                                  @Nullable ConfigComment fieldAnnotation) {
-        ConfigCommentInfo classComments = ConfigCommentInfo.fromAnnotation(clazz.getAnnotation(ConfigComment.class));
+    protected static @Nullable List<String> getClassHeaderComments(@NotNull Class<?> clazz,
+                                                                   @Nullable HeaderComment fieldAnnotation) {
+        List<String> classComments = readHeaderComments(clazz.getAnnotation(HeaderComment.class));
         if (classComments != null) return classComments;
-        return ConfigCommentInfo.fromAnnotation(fieldAnnotation);
+        else return readHeaderComments(fieldAnnotation);
+    }
+
+
+    protected static List<String> readHeaderComments(@Nullable HeaderComment annotation) {
+        if (annotation == null) return null;
+        String[] value = annotation.value();
+        return value.length > 0 ? Arrays.asList(value) : null;
+    }
+
+
+    protected static @Nullable String readInlineComments(@Nullable InlineComment annotation) {
+        if (annotation == null) return null;
+        String value = annotation.value();
+        return value.length() > 0 ? value : null;
     }
 
     protected static @Nullable String getClassPath(@NotNull Class<?> clazz,

diff --git a/core/src/main/java/cc/carm/lib/configuration/core/annotation/ConfigComment.java b/core/src/main/java/cc/carm/lib/configuration/core/annotation/ConfigComment.java
diff --git a/core/src/main/java/cc/carm/lib/configuration/core/annotation/HeaderComment.java b/core/src/main/java/cc/carm/lib/configuration/core/annotation/HeaderComment.java
@@ -0,0 +1,39 @@
+package cc.carm.lib.configuration.core.annotation;
+
+import org.jetbrains.annotations.NotNull;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * 顶部注释，用于给对应配置的顶部添加注释，便于使用者阅读查看。
+ * <p>如：
+ * <blockquote><pre>
+ * # 注释第一行
+ * # 注释第二行
+ * foo: "bar"
+ * </pre></blockquote>
+ */
+@Target({ElementType.TYPE, ElementType.FIELD})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface HeaderComment {
+
+    /**
+     * 注释内容，若内容长度为0则会视为一个空行。
+     * <p> 如 <b>{"foo","","bar"}</b>
+     * 会被添加为
+     * <blockquote><pre>
+     * # foo
+     *
+     * # bar
+     * foo: "bar"
+     * </pre></blockquote>
+     *
+     * @return 注释内容
+     */
+    @NotNull
+    String[] value() default "";
+
+}
diff --git a/core/src/main/java/cc/carm/lib/configuration/core/annotation/InlineComment.java b/core/src/main/java/cc/carm/lib/configuration/core/annotation/InlineComment.java
@@ -0,0 +1,33 @@
+package cc.carm.lib.configuration.core.annotation;
+
+import org.jetbrains.annotations.NotNull;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * 行内注释，用于给对应配置的所在行添加注释，便于使用者阅读查看。
+ * 如：
+ * <blockquote><pre>
+ * foo: "bar" # 注释内容
+ * </pre></blockquote>
+ */
+@Target({ElementType.FIELD})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface InlineComment {
+
+    /**
+     * 注释内容，若内容长度为0则不会添加注释
+     * <p> 如 <b>"foobar"</b> 将被设定为
+     * <blockquote><pre>
+     * foo: "bar" # foobar
+     * </pre></blockquote>
+     *
+     * @return 注释内容
+     */
+    @NotNull
+    String value() default "";
+
+}
diff --git a/core/src/main/java/cc/carm/lib/configuration/core/builder/AbstractConfigBuilder.java b/core/src/main/java/cc/carm/lib/configuration/core/builder/AbstractConfigBuilder.java
@@ -1,21 +1,22 @@
 package cc.carm.lib.configuration.core.builder;
 
-import cc.carm.lib.configuration.core.source.ConfigCommentInfo;
 import cc.carm.lib.configuration.core.source.ConfigurationProvider;
 import cc.carm.lib.configuration.core.value.ConfigValue;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.Arrays;
+import java.util.List;
+
 public abstract class AbstractConfigBuilder<T, B extends AbstractConfigBuilder<T, B, P>, P extends ConfigurationProvider<?>> {
 
     protected final Class<? super P> providerClass;
 
     protected @Nullable P provider;
     protected @Nullable String path;
 
-    protected @NotNull String[] comments = new String[0];
-    protected boolean startWrap = true;
-    protected boolean endWrap = false;
+    protected @Nullable List<String> headerComments;
+    protected @Nullable String inlineComment;
 
     protected @Nullable T defaultValue;
 
@@ -38,38 +39,26 @@ public AbstractConfigBuilder(Class<? super P> providerClass) {
     }
 
     public @NotNull B comments(@NotNull String... comments) {
-        this.comments = comments;
-        return getThis();
-    }
-
-    public @NotNull B setStartWarp(boolean enable) {
-        this.startWrap = enable;
-        return getThis();
+        return headerComments(comments);
     }
 
-    public @NotNull B startWarp() {
-        return setStartWarp(true);
+    public @NotNull B headerComments(@NotNull String... comments) {
+        return headerComments(Arrays.asList(comments));
     }
 
-    public @NotNull B setEndWarp(boolean enable) {
-        this.endWrap = enable;
+    public @NotNull B headerComments(@NotNull List<String> comments) {
+        this.headerComments = comments;
         return getThis();
     }
 
-    public @NotNull B endWarp() {
-        return setEndWarp(true);
+    public @NotNull B inlineComment(@NotNull String comment) {
+        this.inlineComment = comment;
+        return getThis();
     }
 
     public @NotNull B defaults(@Nullable T defaultValue) {
         this.defaultValue = defaultValue;
         return getThis();
     }
 
-    protected @Nullable ConfigCommentInfo buildComments() {
-        ConfigCommentInfo info = ConfigCommentInfo.of(this.comments, this.startWrap, this.endWrap);
-        if (info.equals(ConfigCommentInfo.defaults())) return null;
-        else return info;
-    }
-
-
 }
diff --git a/core/src/main/java/cc/carm/lib/configuration/core/builder/list/ConfigListBuilder.java b/core/src/main/java/cc/carm/lib/configuration/core/builder/list/ConfigListBuilder.java
@@ -1,8 +1,10 @@
 package cc.carm.lib.configuration.core.builder.list;
 
+import cc.carm.lib.configuration.core.annotation.InlineComment;
 import cc.carm.lib.configuration.core.function.ConfigDataFunction;
 import org.jetbrains.annotations.NotNull;
 
+
 public class ConfigListBuilder<V> {
 
     protected final @NotNull Class<V> valueClass;

diff --git a/core/src/main/java/cc/carm/lib/configuration/core/builder/list/SourceListBuilder.java b/core/src/main/java/cc/carm/lib/configuration/core/builder/list/SourceListBuilder.java
@@ -65,7 +65,8 @@ public SourceListBuilder(@NotNull Class<S> sourceClass, @NotNull ConfigDataFunct
     @Override
     public @NotNull ConfiguredList<V> build() {
         return new ConfiguredList<>(
-                this.provider, this.path, this.buildComments(),
+                this.provider, this.path,
+                this.headerComments, this.inlineComment,
                 this.valueClass, this.defaultValue,
                 this.sourceParser.andThen(this.valueParser),
                 this.valueSerializer.andThen(sourceSerializer)

diff --git a/core/src/main/java/cc/carm/lib/configuration/core/builder/map/SourceMapBuilder.java b/core/src/main/java/cc/carm/lib/configuration/core/builder/map/SourceMapBuilder.java
@@ -89,7 +89,8 @@ public <MAP extends Map<K, V>> SourceMapBuilder<MAP, S, K, V> supplier(@NotNull
     @Override
     public @NotNull ConfiguredMap<K, V> build() {
         return new ConfiguredMap<>(
-                this.provider, this.path,this.buildComments(),
+                this.provider, this.path,
+                this.headerComments, this.inlineComment,
                 this.defaultValue, this.supplier,
                 this.keyClass, this.keyParser,
                 this.valueClass, this.sourceParser.andThen(this.valueParser),

diff --git a/core/src/main/java/cc/carm/lib/configuration/core/builder/value/SectionValueBuilder.java b/core/src/main/java/cc/carm/lib/configuration/core/builder/value/SectionValueBuilder.java
@@ -45,7 +45,8 @@ public SectionValueBuilder(@NotNull Class<V> valueClass,
     @Override
     public @NotNull ConfiguredSection<V> build() {
         return new ConfiguredSection<>(
-                this.provider, this.path,this.buildComments(),
+                this.provider, this.path,
+                this.headerComments, this.inlineComment,
                 this.valueClass, this.defaultValue,
                 this.parser, this.serializer
         );

diff --git a/core/src/main/java/cc/carm/lib/configuration/core/builder/value/SourceValueBuilder.java b/core/src/main/java/cc/carm/lib/configuration/core/builder/value/SourceValueBuilder.java
@@ -3,7 +3,6 @@
 import cc.carm.lib.configuration.core.builder.CommonConfigBuilder;
 import cc.carm.lib.configuration.core.function.ConfigDataFunction;
 import cc.carm.lib.configuration.core.function.ConfigValueParser;
-import cc.carm.lib.configuration.core.source.ConfigCommentInfo;
 import cc.carm.lib.configuration.core.value.type.ConfiguredValue;
 import org.jetbrains.annotations.NotNull;
 
@@ -58,7 +57,8 @@ public SourceValueBuilder(@NotNull Class<S> sourceClass, @NotNull ConfigDataFunc
     @Override
     public @NotNull ConfiguredValue<V> build() {
         return new ConfiguredValue<>(
-                this.provider, this.path, this.buildComments(),
+                this.provider, this.path,
+                this.headerComments, this.inlineComment,
                 this.valueClass, this.defaultValue,
                 this.valueParser.compose(this.sourceParser),
                 this.valueSerializer.andThen(sourceSerializer)