Merge remote-tracking branch 'origin/master'

BREAKING CHANGES: Now we override "onReload()" method to define ConfigurationProvider how to reload the configs.

Fix the problem that when the configuration file is read, the "reload()" method not working.

README.md

@@ -9,7 +9,7 @@
 # EasyConfiguration
 
 [![version](https://img.shields.io/github/v/release/CarmJos/EasyConfiguration)](https://github.com/CarmJos/EasyConfiguration/releases)
-[![License](https://img.shields.io/github/license/CarmJos/EasyConfiguration)](https://opensource.org/licenses/MIT)
+[![License](https://img.shields.io/github/license/CarmJos/EasyConfiguration)](https://www.gnu.org/licenses/lgpl-3.0.html)
 [![workflow](https://github.com/CarmJos/EasyConfiguration/actions/workflows/maven.yml/badge.svg?branch=master)](https://github.com/CarmJos/EasyConfiguration/actions/workflows/maven.yml)
 [![CodeFactor](https://www.codefactor.io/repository/github/carmjos/easyconfiguration/badge)](https://www.codefactor.io/repository/github/carmjos/easyconfiguration)
 ![CodeSize](https://img.shields.io/github/languages/code-size/CarmJos/EasyConfiguration)
@@ -20,6 +20,9 @@
 ## 优势
 
 - 基于类的配置文件初始化、加载、获取与更新机制，方便快捷。
+- 支持复杂配置的手动序列化、反序列化。
+- 提供多种builder形式，快速构建 `ConfigValue<?>` 对象。
+- 支持通过注解规定配置对应的路径、注释等信息。
 
 ## 开发
 
@@ -91,6 +94,15 @@
             <scope>compile</scope>
         </dependency>
 
+        <!--基于JSON文件的实现版本，可用于全部Java环境。-->
+        <!--需要注意的是，JSON不支持文件注释。-->
+        <dependency>
+            <groupId>cc.carm.lib</groupId>
+            <artifactId>easyconfiguration-json</artifactId>
+            <version>[LATEST RELEASE]</version>
+            <scope>compile</scope>
+        </dependency>
+
     </dependencies>
 </project>
 ```
@@ -131,6 +143,10 @@ dependencies {
     //基于YAML文件的实现版本，可用于全部Java环境。
     api "cc.carm.lib:easyconfiguration-yaml:[LATEST RELEASE]"
 
+     //基于JSON文件的实现版本，可用于全部Java环境。
+    //需要注意的是，JSON不支持文件注释。
+    api "cc.carm.lib:easyconfiguration-json:[LATEST RELEASE]"
+
 }
 ```
 
@@ -155,23 +171,4 @@ EasyConfiguration for MineCraft!
 
 ## 开源协议
 
-本项目源码采用 [The MIT License](https://opensource.org/licenses/MIT) 开源协议。
-
-<details>
-<summary>关于 MIT 协议</summary>
-
-> MIT 协议可能是几大开源协议中最宽松的一个，核心条款是：
->
-> 该软件及其相关文档对所有人免费，可以任意处置，包括使用，复制，修改，合并，发表，分发，再授权，或者销售。唯一的限制是，软件中必须包含上述版 权和许可提示。
->
-> 这意味着：
->
-> - 你可以自由使用，复制，修改，可以用于自己的项目。
-> - 可以免费分发或用来盈利。
-> - 唯一的限制是必须包含许可声明。
->
-> MIT 协议是所有开源许可中最宽松的一个，除了必须包含许可声明外，再无任何限制。
->
-> *以上文字来自 [五种开源协议GPL,LGPL,BSD,MIT,Apache](https://www.oschina.net/question/54100_9455) 。*
-
-</details>
+本项目源码采用 [GNU LESSER GENERAL PUBLIC LICENSE](https://www.gnu.org/licenses/lgpl-3.0.html) 开源协议。

core/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyconfiguration-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>2.2.0</version>
+        <version>3.1.0</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <properties>

core/src/main/java/cc/carm/lib/configuration/core/ConfigInitializer.java

@@ -1,13 +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.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;
 
 /**
  * 配置文件类初始化方法
@@ -44,7 +47,7 @@ public class ConfigInitializer<T extends ConfigurationProvider<?>> {
     public void initialize(@NotNull Class<? extends ConfigurationRoot> clazz,
                            boolean saveDefaults, boolean loadSubClasses) {
         initializeClass(
-                clazz, null,
+                clazz, null, null,
                 null, null, null,
                 saveDefaults, loadSubClasses
         );
@@ -59,49 +62,47 @@ public class ConfigInitializer<T extends ConfigurationProvider<?>> {
 
     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);
-        if (path != null) setComments(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,
-                                   @NotNull String[] 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 {
             field.setAccessible(true);
             Object object = field.get(source);
             if (object instanceof ConfigValue<?>) {
-                String path = getFieldPath(field, parent);
-                String[] comments = readComments(field.getAnnotation(ConfigComment.class));
-                initializeValue((ConfigValue<?>) object, path, comments, saveDefaults);
-                setComments(path, comments);
+                initializeValue(
+                        (ConfigValue<?>) object, getFieldPath(field, parent),
+                        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
                 );
             }
@@ -109,26 +110,36 @@ public class ConfigInitializer<T extends ConfigurationProvider<?>> {
         }
     }
 
-    protected void setComments(@NotNull String path, @Nullable ConfigComment filedComments) {
-        setComments(path, readComments(filedComments));
+    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 void setComments(@NotNull String path, @NotNull String[] comments) {
-        if (comments.length <= 0) return;
-        this.provider.setComments(path, comments);
+    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;
+        else return readHeaderComments(fieldAnnotation);
     }
 
-    protected static @NotNull String[] readComments(@Nullable ConfigComment filedComments) {
-        if (filedComments == null) return new String[0];
-        if (String.join("", filedComments.value()).length() <= 0) return new String[0];
-        return filedComments.value();
+
+    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 @NotNull String[] getClassComments(@NotNull Class<?> clazz,
-                                                        @Nullable ConfigComment fieldAnnotation) {
-        String[] clazzComments = readComments(clazz.getAnnotation(ConfigComment.class));
-        if (clazzComments.length > 0) return clazzComments;
-        else return readComments(fieldAnnotation);
+
+    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,

core/src/main/java/cc/carm/lib/configuration/core/annotation/ConfigComment.java

@@ -1,17 +0,0 @@
-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;
-
-@Target({ElementType.TYPE, ElementType.FIELD})
-@Retention(RetentionPolicy.RUNTIME)
-public @interface ConfigComment {
-
-    @NotNull
-    String[] value() default "";
-
-}

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 "";
+
+}

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 "";
+
+}

core/src/main/java/cc/carm/lib/configuration/core/builder/AbstractConfigBuilder.java

@@ -5,6 +5,9 @@ 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;
@@ -12,7 +15,9 @@ public abstract class AbstractConfigBuilder<T, B extends AbstractConfigBuilder<T
     protected @Nullable P provider;
     protected @Nullable String path;
 
-    protected @NotNull String[] comments = new String[0];
+    protected @Nullable List<String> headerComments;
+    protected @Nullable String inlineComment;
+
     protected @Nullable T defaultValue;
 
     public AbstractConfigBuilder(Class<? super P> providerClass) {
@@ -34,7 +39,20 @@ public abstract class AbstractConfigBuilder<T, B extends AbstractConfigBuilder<T
     }
 
     public @NotNull B comments(@NotNull String... comments) {
-        this.comments = comments;
+        return headerComments(comments);
+    }
+
+    public @NotNull B headerComments(@NotNull String... comments) {
+        return headerComments(Arrays.asList(comments));
+    }
+
+    public @NotNull B headerComments(@NotNull List<String> comments) {
+        this.headerComments = comments;
+        return getThis();
+    }
+
+    public @NotNull B inlineComment(@NotNull String comment) {
+        this.inlineComment = comment;
         return getThis();
     }
 
@@ -43,5 +61,4 @@ public abstract class AbstractConfigBuilder<T, B extends AbstractConfigBuilder<T
         return getThis();
     }
 
-
 }

core/src/main/java/cc/carm/lib/configuration/core/builder/CommonConfigBuilder.java

@@ -1,46 +1,12 @@
 package cc.carm.lib.configuration.core.builder;
 
 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;
 
 public abstract class CommonConfigBuilder<T, B extends CommonConfigBuilder<T, B>>
         extends AbstractConfigBuilder<T, B, ConfigurationProvider<?>> {
 
-    protected @Nullable ConfigurationProvider<?> provider;
-    protected @Nullable String path;
-
-    protected @NotNull String[] comments = new String[0];
-    protected @Nullable T defaultValue;
-
     public CommonConfigBuilder() {
         super(ConfigurationProvider.class);
     }
 
-    protected abstract @NotNull B getThis();
-
-    public abstract @NotNull ConfigValue<?> build();
-
-    public @NotNull B from(@Nullable ConfigurationProvider<?> provider) {
-        this.provider = provider;
-        return getThis();
-    }
-
-    public @NotNull B path(@Nullable String path) {
-        this.path = path;
-        return getThis();
-    }
-
-    public @NotNull B comments(@NotNull String... comments) {
-        this.comments = comments;
-        return getThis();
-    }
-
-    public @NotNull B defaults(@Nullable T defaultValue) {
-        this.defaultValue = defaultValue;
-        return getThis();
-    }
-
-
 }

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;

core/src/main/java/cc/carm/lib/configuration/core/builder/list/SourceListBuilder.java

@@ -65,7 +65,8 @@ public class SourceListBuilder<S, V> extends CommonConfigBuilder<List<V>, Source
     @Override
     public @NotNull ConfiguredList<V> build() {
         return new ConfiguredList<>(
-                this.provider, this.path, this.comments,
+                this.provider, this.path,
+                this.headerComments, this.inlineComment,
                 this.valueClass, this.defaultValue,
                 this.sourceParser.andThen(this.valueParser),
                 this.valueSerializer.andThen(sourceSerializer)

core/src/main/java/cc/carm/lib/configuration/core/builder/map/SourceMapBuilder.java

@@ -89,7 +89,8 @@ public class SourceMapBuilder<M extends Map<K, V>, S, K, V> extends CommonConfig
     @Override
     public @NotNull ConfiguredMap<K, V> build() {
         return new ConfiguredMap<>(
-                this.provider, this.path, this.comments,
+                this.provider, this.path,
+                this.headerComments, this.inlineComment,
                 this.defaultValue, this.supplier,
                 this.keyClass, this.keyParser,
                 this.valueClass, this.sourceParser.andThen(this.valueParser),

core/src/main/java/cc/carm/lib/configuration/core/builder/value/SectionValueBuilder.java

@@ -45,7 +45,8 @@ public class SectionValueBuilder<V>
     @Override
     public @NotNull ConfiguredSection<V> build() {
         return new ConfiguredSection<>(
-                this.provider, this.path, this.comments,
+                this.provider, this.path,
+                this.headerComments, this.inlineComment,
                 this.valueClass, this.defaultValue,
                 this.parser, this.serializer
         );

core/src/main/java/cc/carm/lib/configuration/core/builder/value/SourceValueBuilder.java

@@ -57,7 +57,8 @@ public class SourceValueBuilder<S, V> extends CommonConfigBuilder<V, SourceValue
     @Override
     public @NotNull ConfiguredValue<V> build() {
         return new ConfiguredValue<>(
-                this.provider, this.path, this.comments,
+                this.provider, this.path,
+                this.headerComments, this.inlineComment,
                 this.valueClass, this.defaultValue,
                 this.valueParser.compose(this.sourceParser),
                 this.valueSerializer.andThen(sourceSerializer)

core/src/main/java/cc/carm/lib/configuration/core/source/ConfigurationProvider.java

@@ -4,6 +4,9 @@ import cc.carm.lib.configuration.core.ConfigInitializer;
 import cc.carm.lib.configuration.core.ConfigurationRoot;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.util.List;
 
 public abstract class ConfigurationProvider<W extends ConfigurationWrapper> {
 
@@ -23,13 +26,24 @@ public abstract class ConfigurationProvider<W extends ConfigurationWrapper> {
 
     public abstract @NotNull W getConfiguration();
 
-    public abstract void reload() throws Exception;
+    public void reload() throws Exception {
+        onReload(); // 调用重写的Reload方法
+        this.updateTime = System.currentTimeMillis();
+    }
 
     public abstract void save() throws Exception;
 
-    public abstract void setComments(@NotNull String path, @NotNull String... comments);
+    protected abstract void onReload() throws Exception;
 
-    public abstract @Nullable String[] getComments(@NotNull String path);
+    public abstract void setHeaderComment(@Nullable String path, @Nullable List<String> comments);
+
+    public abstract void setInlineComment(@NotNull String path, @Nullable String comment);
+
+    @Nullable
+    @Unmodifiable
+    public abstract List<String> getHeaderComment(@Nullable String path);
+
+    public abstract @Nullable String getInlineComment(@NotNull String path);
 
     public abstract @NotNull ConfigInitializer<? extends ConfigurationProvider<W>> getInitializer();
 

core/src/main/java/cc/carm/lib/configuration/core/source/ConfigurationReader.java

@@ -4,6 +4,11 @@ import cc.carm.lib.configuration.core.function.ConfigValueParser;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
 
 interface ConfigurationReader {
 
@@ -26,7 +31,6 @@ interface ConfigurationReader {
         return getWrapper().isType(path, Byte.class);
     }
 
-
     default @Nullable Byte getByte(@NotNull String path) {
         return getByte(path, (byte) 0);
     }
@@ -36,12 +40,10 @@ interface ConfigurationReader {
         return getWrapper().get(path, def, ConfigValueParser.byteValue());
     }
 
-
     default boolean isShort(@NotNull String path) {
         return getWrapper().isType(path, Short.class);
     }
 
-
     default @Nullable Short getShort(@NotNull String path) {
         return getShort(path, (short) 0);
     }
@@ -56,7 +58,6 @@ interface ConfigurationReader {
         return getWrapper().isType(path, Integer.class);
     }
 
-
     default @Nullable Integer getInt(@NotNull String path) {
         return getInt(path, 0);
     }
@@ -71,7 +72,6 @@ interface ConfigurationReader {
         return getWrapper().isType(path, Long.class);
     }
 
-
     default @Nullable Long getLong(@NotNull String path) {
         return getLong(path, 0L);
     }
@@ -86,7 +86,6 @@ interface ConfigurationReader {
         return getWrapper().isType(path, Float.class);
     }
 
-
     default @Nullable Float getFloat(@NotNull String path) {
         return getFloat(path, 0.0F);
     }
@@ -101,7 +100,6 @@ interface ConfigurationReader {
         return getWrapper().isType(path, Double.class);
     }
 
-
     default @Nullable Double getDouble(@NotNull String path) {
         return getDouble(path, 0.0D);
     }
@@ -116,7 +114,6 @@ interface ConfigurationReader {
         return getWrapper().isType(path, Boolean.class);
     }
 
-
     default @Nullable Character getChar(@NotNull String path) {
         return getChar(path, null);
     }
@@ -140,5 +137,54 @@ interface ConfigurationReader {
         return getWrapper().get(path, def, String.class);
     }
 
+    @Unmodifiable
+    default @NotNull List<String> getStringList(@NotNull String path) {
+        return parseList(getWrapper().getList(path), ConfigValueParser.castToString());
+    }
+
+    @Unmodifiable
+    default @NotNull List<Integer> getIntegerList(@NotNull String path) {
+        return parseList(getWrapper().getList(path), ConfigValueParser.intValue());
+    }
+
+    @Unmodifiable
+    default @NotNull List<Long> getLongList(@NotNull String path) {
+        return parseList(getWrapper().getList(path), ConfigValueParser.longValue());
+    }
+
+    @Unmodifiable
+    default @NotNull List<Double> getDoubleList(@NotNull String path) {
+        return parseList(getWrapper().getList(path), ConfigValueParser.doubleValue());
+    }
+
+    @Unmodifiable
+    default @NotNull List<Float> getFloatList(@NotNull String path) {
+        return parseList(getWrapper().getList(path), ConfigValueParser.floatValue());
+    }
+
+    @Unmodifiable
+    default @NotNull List<Byte> getByteList(@NotNull String path) {
+        return parseList(getWrapper().getList(path), ConfigValueParser.byteValue());
+    }
+
+    @Unmodifiable
+    default @NotNull List<Character> getCharList(@NotNull String path) {
+        return parseList(getWrapper().getList(path), ConfigValueParser.castObject(Character.class));
+    }
+
+    @Unmodifiable
+    static <T> @NotNull List<T> parseList(@Nullable List<?> list, ConfigValueParser<Object, T> parser) {
+        if (list == null) return Collections.emptyList();
+        List<T> values = new ArrayList<>();
+        for (Object o : list) {
+            try {
+                T parsed = parser.parse(o, null);
+                if (parsed != null) values.add(parsed);
+            } catch (Exception ignored) {
+            }
+        }
+        return values;
+    }
+
 
 }

core/src/main/java/cc/carm/lib/configuration/core/value/ConfigValue.java

@@ -5,7 +5,9 @@ import cc.carm.lib.configuration.core.source.ConfigurationProvider;
 import cc.carm.lib.configuration.core.source.ConfigurationWrapper;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
+import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
 
@@ -17,24 +19,37 @@ public abstract class ConfigValue<T> {
 
     protected @Nullable ConfigurationProvider<?> provider;
     protected @Nullable String configPath;
-    protected @NotNull String[] comments;
+
+    protected @Nullable List<String> headerComments;
+    protected @Nullable String inlineComments;
 
     protected @Nullable T defaultValue;
 
-    public ConfigValue(@Nullable ConfigurationProvider<?> provider,
-                       @Nullable String configPath, @NotNull String[] comments, @Nullable T defaultValue) {
+    public ConfigValue(@Nullable ConfigurationProvider<?> provider, @Nullable String configPath,
+                       @Nullable List<String> headerComments, @Nullable String inlineComments,
+                       @Nullable T defaultValue) {
         this.provider = provider;
         this.configPath = configPath;
-        this.comments = comments;
+        this.headerComments = headerComments;
+        this.inlineComments = inlineComments;
         this.defaultValue = defaultValue;
     }
 
-    public void initialize(@NotNull ConfigurationProvider<?> provider, boolean saveDefault,
-                           @NotNull String configPath, @NotNull String... comments) {
+    public void initialize(@NotNull ConfigurationProvider<?> provider, boolean saveDefault, @NotNull String configPath,
+                           @Nullable List<String> headerComments, @Nullable String inlineComments) {
         if (this.provider == null) this.provider = provider;
         if (this.configPath == null) this.configPath = configPath;
-        if (this.comments.length == 0) this.comments = comments;
+        if (this.headerComments == null) this.headerComments = headerComments;
+        if (this.inlineComments == null) this.inlineComments = inlineComments;
         if (saveDefault) setDefault();
+
+        if (getHeaderComments() != null) {
+            this.provider.setHeaderComment(getConfigPath(), getHeaderComments());
+        }
+        if (getInlineComments() != null) {
+            this.provider.setInlineComment(getConfigPath(), getInlineComments());
+        }
+
     }
 
     public @Nullable T getDefaultValue() {
@@ -103,6 +118,11 @@ public abstract class ConfigValue<T> {
         Optional.ofNullable(getDefaultValue()).ifPresent(this::set);
     }
 
+    /**
+     * 判断加载的配置是否与默认值相同。
+     *
+     * @return 获取当前值是否为默认值。
+     */
     public boolean isDefault() {
         T defaultValue = getDefaultValue();
         T value = get();
@@ -137,12 +157,13 @@ public abstract class ConfigValue<T> {
         getConfiguration().set(getConfigPath(), value);
     }
 
-    public String[] getComments() {
-        return comments;
+    public @Nullable String getInlineComments() {
+        return inlineComments;
     }
 
-    public void setComments(String[] comments) {
-        this.comments = comments;
+    @Unmodifiable
+    public @Nullable List<String> getHeaderComments() {
+        return headerComments;
     }
 
 }

core/src/main/java/cc/carm/lib/configuration/core/value/impl/CachedConfigValue.java

@@ -2,9 +2,10 @@ package cc.carm.lib.configuration.core.value.impl;
 
 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.List;
+
 public abstract class CachedConfigValue<T> extends ConfigValue<T> {
 
 
@@ -12,8 +13,9 @@ public abstract class CachedConfigValue<T> extends ConfigValue<T> {
     protected long parsedTime = -1;
 
     public CachedConfigValue(@Nullable ConfigurationProvider<?> provider, @Nullable String sectionPath,
-                             @NotNull String[] comments, @Nullable T defaultValue) {
-        super(provider, sectionPath, comments, defaultValue);
+                             @Nullable List<String> headerComments, @Nullable String inlineComments,
+                             @Nullable T defaultValue) {
+        super(provider, sectionPath, headerComments, inlineComments, defaultValue);
     }
 
     protected T updateCache(T value) {

core/src/main/java/cc/carm/lib/configuration/core/value/type/ConfiguredList.java

@@ -1,5 +1,6 @@
 package cc.carm.lib.configuration.core.value.type;
 
+import cc.carm.lib.configuration.core.annotation.HeaderComment;
 import cc.carm.lib.configuration.core.builder.list.ConfigListBuilder;
 import cc.carm.lib.configuration.core.function.ConfigDataFunction;
 import cc.carm.lib.configuration.core.source.ConfigurationProvider;
@@ -16,17 +17,18 @@ public class ConfiguredList<V> extends CachedConfigValue<List<V>> {
         return builder().asList(valueClass);
     }
 
+    @HeaderComment
     protected final @NotNull Class<V> valueClass;
 
     protected final @NotNull ConfigDataFunction<Object, V> parser;
     protected final @NotNull ConfigDataFunction<V, Object> serializer;
 
-    public ConfiguredList(@Nullable ConfigurationProvider<?> provider,
-                          @Nullable String sectionPath, @NotNull String[] comments,
+    public ConfiguredList(@Nullable ConfigurationProvider<?> provider, @Nullable String sectionPath,
+                          @Nullable List<String> headerComments, @Nullable String inlineComments,
                           @NotNull Class<V> valueClass, @Nullable List<V> defaultValue,
                           @NotNull ConfigDataFunction<Object, V> parser,
                           @NotNull ConfigDataFunction<V, Object> serializer) {
-        super(provider, sectionPath, comments, defaultValue);
+        super(provider, sectionPath, headerComments, inlineComments, defaultValue);
         this.valueClass = valueClass;
         this.parser = parser;
         this.serializer = serializer;
@@ -34,15 +36,10 @@ public class ConfiguredList<V> extends CachedConfigValue<List<V>> {
 
     @Override
     public @NotNull List<V> get() {
-
-
-
         if (isExpired()) { // 已过时的数据，需要重新解析一次。
             List<V> list = new ArrayList<>();
-
             List<?> data = getConfiguration().getList(getConfigPath());
             if (data == null || data.isEmpty()) return useOrDefault(list);
-
             for (Object dataVal : data) {
                 if (dataVal == null) continue;
                 try {
@@ -51,7 +48,6 @@ public class ConfiguredList<V> extends CachedConfigValue<List<V>> {
                     e.printStackTrace();
                 }
             }
-
             return updateCache(list);
         } else if (getCachedValue() != null) return getCachedValue();
         else if (getDefaultValue() != null) return getDefaultValue();

core/src/main/java/cc/carm/lib/configuration/core/value/type/ConfiguredMap.java

@@ -9,6 +9,7 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.function.Supplier;
@@ -31,14 +32,14 @@ public class ConfiguredMap<K, V> extends CachedConfigValue<Map<K, V>> {
     protected final @NotNull ConfigDataFunction<K, String> keySerializer;
     protected final @NotNull ConfigDataFunction<V, Object> valueSerializer;
 
-    public ConfiguredMap(@Nullable ConfigurationProvider<?> provider,
-                         @Nullable String sectionPath, @NotNull String[] comments,
+    public ConfiguredMap(@Nullable ConfigurationProvider<?> provider, @Nullable String sectionPath,
+                         @Nullable List<String> headerComments, @Nullable String inlineComments,
                          @Nullable Map<K, V> defaultValue, @NotNull Supplier<? extends Map<K, V>> supplier,
                          @NotNull Class<K> keyClass, @NotNull ConfigDataFunction<String, K> keyParser,
                          @NotNull Class<V> valueClass, @NotNull ConfigDataFunction<Object, V> valueParser,
                          @NotNull ConfigDataFunction<K, String> keySerializer,
                          @NotNull ConfigDataFunction<V, Object> valueSerializer) {
-        super(provider, sectionPath, comments, defaultValue);
+        super(provider, sectionPath, headerComments, inlineComments, defaultValue);
         this.supplier = supplier;
         this.keyClass = keyClass;
         this.valueClass = valueClass;
@@ -109,9 +110,10 @@ public class ConfiguredMap<K, V> extends CachedConfigValue<Map<K, V>> {
             Map<String, Object> data = new LinkedHashMap<>();
             for (Map.Entry<K, V> entry : value.entrySet()) {
                 try {
-                    String key = keySerializer.parse(entry.getKey());
-                    Object val = valueSerializer.parse(entry.getValue());
-                    data.put(key, val);
+                    data.put(
+                            keySerializer.parse(entry.getKey()),
+                            valueSerializer.parse(entry.getValue())
+                    );
                 } catch (Exception e) {
                     e.printStackTrace();
                 }

core/src/main/java/cc/carm/lib/configuration/core/value/type/ConfiguredSection.java

@@ -9,6 +9,7 @@ import cc.carm.lib.configuration.core.value.impl.CachedConfigValue;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 
@@ -23,12 +24,12 @@ public class ConfiguredSection<V> extends CachedConfigValue<V> {
     protected final @NotNull ConfigValueParser<ConfigurationWrapper, V> parser;
     protected final @NotNull ConfigDataFunction<V, ? extends Map<String, Object>> serializer;
 
-    public ConfiguredSection(@Nullable ConfigurationProvider<?> provider,
-                             @Nullable String sectionPath, @NotNull String[] comments,
+    public ConfiguredSection(@Nullable ConfigurationProvider<?> provider, @Nullable String sectionPath,
+                             @Nullable List<String> headerComments, @Nullable String inlineComments,
                              @NotNull Class<V> valueClass, @Nullable V defaultValue,
                              @NotNull ConfigValueParser<ConfigurationWrapper, V> parser,
                              @NotNull ConfigDataFunction<V, ? extends Map<String, Object>> serializer) {
-        super(provider, sectionPath, comments, defaultValue);
+        super(provider, sectionPath, headerComments, inlineComments, defaultValue);
         this.valueClass = valueClass;
         this.parser = parser;
         this.serializer = serializer;
@@ -69,7 +70,6 @@ public class ConfiguredSection<V> extends CachedConfigValue<V> {
         else {
             try {
                 setValue(serializer.parse(value));
-//                getConfiguration().createSection(getSectionPath(), serializer.parse(value));
             } catch (Exception e) {
                 e.printStackTrace();
             }

core/src/main/java/cc/carm/lib/configuration/core/value/type/ConfiguredValue.java

@@ -8,6 +8,7 @@ import cc.carm.lib.configuration.core.value.impl.CachedConfigValue;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.List;
 import java.util.Optional;
 
 public class ConfiguredValue<V> extends CachedConfigValue<V> {
@@ -29,13 +30,13 @@ public class ConfiguredValue<V> extends CachedConfigValue<V> {
     protected final @NotNull ConfigValueParser<Object, V> parser;
     protected final @NotNull ConfigDataFunction<V, Object> serializer;
 
-    public ConfiguredValue(@Nullable ConfigurationProvider<?> provider,
-                           @Nullable String sectionPath, @NotNull String[] comments,
+    public ConfiguredValue(@Nullable ConfigurationProvider<?> provider, @Nullable String sectionPath,
+                           @Nullable List<String> headerComments, @Nullable String inlineComments,
                            @NotNull Class<V> valueClass, @Nullable V defaultValue,
                            @NotNull ConfigValueParser<Object, V> parser,
                            @NotNull ConfigDataFunction<V, Object> serializer) {
 
-        super(provider, sectionPath, comments, defaultValue);
+        super(provider, sectionPath, headerComments, inlineComments, defaultValue);
         this.valueClass = valueClass;
         this.parser = parser;
         this.serializer = serializer;

impl/json/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyconfiguration-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>2.2.0</version>
+        <version>3.1.0</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

impl/json/src/main/java/cc/carm/lib/configuration/json/JSONConfigProvider.java

@@ -8,10 +8,12 @@ import com.google.gson.GsonBuilder;
 import com.google.gson.JsonSerializer;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.io.*;
 import java.nio.charset.StandardCharsets;
 import java.util.LinkedHashMap;
+import java.util.List;
 
 /**
  * Some code comes from BungeeCord's implementation of the JsonConfiguration.
@@ -47,7 +49,6 @@ public class JSONConfigProvider extends FileConfigProvider<JSONConfigWrapper> {
         if (map == null) map = new LinkedHashMap<>();
 
         this.configuration = new JSONConfigWrapper(map);
-        this.initializer = new ConfigInitializer<>(this);
     }
 
     @Override
@@ -56,7 +57,8 @@ public class JSONConfigProvider extends FileConfigProvider<JSONConfigWrapper> {
     }
 
     @Override
-    public void reload() {
+    protected void onReload() throws Exception {
+        super.reload();
         initializeConfig();
     }
 
@@ -68,13 +70,23 @@ public class JSONConfigProvider extends FileConfigProvider<JSONConfigWrapper> {
     }
 
     @Override
-    public void setComments(@NotNull String path, @NotNull String... comments) {
-        // JSON doesn't support comments.
+    public void setHeaderComment(@Nullable String path, @Nullable List<String> comments) {
+        // JSON doesn't support comments;
     }
 
     @Override
-    public @Nullable String[] getComments(@NotNull String path) {
-        return new String[0];     // JSON doesn't support comments.
+    public void setInlineComment(@NotNull String path, @Nullable String comment) {
+        // JSON doesn't support comments;
+    }
+
+    @Override
+    public @Nullable @Unmodifiable List<String> getHeaderComment(@Nullable String path) {
+        return null;
+    }
+
+    @Override
+    public @Nullable String getInlineComment(@NotNull String path) {
+        return null;
     }
 
     @Override

impl/json/src/main/java/cc/carm/lib/configuration/json/JSONConfigWrapper.java

@@ -4,7 +4,10 @@ import cc.carm.lib.configuration.core.source.ConfigurationWrapper;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-import java.util.*;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
 
 /**
  * Some code comes from BungeeCord's implementation of the JsonConfiguration.
@@ -33,12 +36,16 @@ public class JSONConfigWrapper implements ConfigurationWrapper {
 
     @Override
     public @NotNull Set<String> getKeys(boolean deep) {
-        return new LinkedHashSet<>(this.data.keySet());
+        return getValues(deep).keySet();
     }
 
     @Override
     public @NotNull Map<String, Object> getValues(boolean deep) {
-        return new LinkedHashMap<>(this.data);
+        if (deep) {
+            Map<String, Object> values = new LinkedHashMap<>();
+            mapChildrenValues(values, this, null, true);
+            return values;
+        } else return new LinkedHashMap<>(this.data);
     }
 
     @Override
@@ -111,4 +118,16 @@ public class JSONConfigWrapper implements ConfigurationWrapper {
         return (index == -1) ? path : path.substring(index + 1);
     }
 
+
+    protected void mapChildrenValues(@NotNull Map<String, Object> output, @NotNull JSONConfigWrapper section,
+                                     @Nullable String parent, boolean deep) {
+        for (Map.Entry<String, Object> entry : section.data.entrySet()) {
+            String path = (parent == null ? "" : parent + ".") + entry.getKey();
+            output.remove(path);
+            output.put(path, entry.getValue());
+            if (deep && entry.getValue() instanceof JSONConfigWrapper) {
+                this.mapChildrenValues(output, (JSONConfigWrapper) entry.getValue(), path, true);
+            }
+        }
+    }
 }

impl/json/src/main/java/cc/carm/lib/configuration/json/JSONValue.java

@@ -1,4 +0,0 @@
-package cc.carm.lib.configuration.json;
-
-public abstract class JSONValue {
-}

impl/json/src/test/java/config/JSONConfigTest.java

@@ -23,6 +23,11 @@ public class JSONConfigTest {
         provider.initialize(DemoConfiguration.class);
 
         testDemo();
+        System.out.println("----------------------------------------------------");
+        provider.getConfiguration().getValues(true).forEach((k, v) -> System.out.println(k + ": " + v));
+        System.out.println("----------------------------------------------------");
+        provider.getConfiguration().getValues(false).forEach((k, v) -> System.out.println(k + ": " + v));
+        System.out.println("----------------------------------------------------");
 
         try {
             provider.save();

impl/json/src/test/java/config/source/DatabaseConfiguration.java

@@ -1,12 +1,12 @@
 package config.source;
 
 import cc.carm.lib.configuration.core.ConfigurationRoot;
-import cc.carm.lib.configuration.core.annotation.ConfigComment;
+import cc.carm.lib.configuration.core.annotation.HeaderComment;
 import cc.carm.lib.configuration.core.annotation.ConfigPath;
 import cc.carm.lib.configuration.core.value.ConfigValue;
 import cc.carm.lib.configuration.core.value.type.ConfiguredValue;
 
-@ConfigComment({"数据库配置", "  用于提供数据库连接，进行数据库操作。"})
+@HeaderComment({"数据库配置", "  用于提供数据库连接，进行数据库操作。"})
 public class DatabaseConfiguration extends ConfigurationRoot {
 
     @ConfigPath("driver")

impl/yaml/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyconfiguration-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>2.2.0</version>
+        <version>3.1.0</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>
@@ -27,9 +27,9 @@
         </dependency>
 
         <dependency>
-            <groupId>cc.carm.lib</groupId>
-            <artifactId>yamlconfiguration-commented</artifactId>
-            <version>2.0.2</version>
+            <groupId>org.bspfsystems</groupId>
+            <artifactId>yamlconfiguration</artifactId>
+            <version>1.2.0</version>
             <scope>compile</scope>
         </dependency>
 

impl/yaml/src/main/java/cc/carm/lib/configuration/EasyConfiguration.java

@@ -30,5 +30,4 @@ public class EasyConfiguration {
         return from(new File(fileName), source);
     }
 
-
 }

impl/yaml/src/main/java/cc/carm/lib/configuration/yaml/YAMLComments.java

@@ -1,35 +1,148 @@
 package cc.carm.lib.configuration.yaml;
 
-import org.bspfsystems.yamlconfiguration.commented.CommentsProvider;
+import org.bspfsystems.yamlconfiguration.configuration.ConfigurationSection;
+import org.bspfsystems.yamlconfiguration.file.FileConfiguration;
+import org.bspfsystems.yamlconfiguration.file.YamlConfiguration;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
-import java.util.HashMap;
-import java.util.Map;
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.util.*;
+import java.util.stream.Collectors;
+import java.util.stream.IntStream;
 
-public class YAMLComments implements CommentsProvider {
+import static cc.carm.lib.configuration.yaml.YAMLConfigProvider.SEPARATOR;
 
-    Map<String, String[]> comments = new HashMap<>();
+public class YAMLComments {
 
-    protected Map<String, String[]> getComments() {
-        return comments;
+    protected final @NotNull Map<String, List<String>> headerComments = new HashMap<>();
+    protected final @NotNull Map<String, String> inlineComments = new HashMap<>();
+
+    protected @NotNull Map<String, List<String>> getHeaderComments() {
+        return headerComments;
     }
 
-    public void set(@NotNull String path, @NotNull String... comments) {
-        if (comments.length == 0) {
-            getComments().remove(path);
+    protected @NotNull Map<String, String> getInlineComments() {
+        return inlineComments;
+    }
+
+    public void setHeaderComments(@Nullable String path, @Nullable List<String> comments) {
+
+        if (comments == null) {
+            getHeaderComments().remove(path);
         } else {
-            getComments().put(path, comments);
+            getHeaderComments().put(path, comments);
         }
     }
 
-    public @Nullable String[] get(@NotNull String path) {
-        return getComments().get(path);
+
+    public void setInlineComment(@NotNull String path, @Nullable String comment) {
+        if (comment == null) {
+            getInlineComments().remove(path);
+        } else {
+            getInlineComments().put(path, comment);
+        }
     }
 
-    @Override
-    public String[] apply(String s) {
-        return get(s);
+    @Nullable
+    @Unmodifiable
+    public List<String> getHeaderComment(@Nullable String path) {
+        return Optional.ofNullable(getHeaderComments().get(path)).map(Collections::unmodifiableList).orElse(null);
+    }
+
+    public @Nullable String getInlineComment(@NotNull String path) {
+        return getInlineComments().get(path);
+    }
+
+    public @Nullable String buildHeaderComments(@Nullable String path, @NotNull String indents) {
+        List<String> comments = getHeaderComment(path);
+        if (comments == null || comments.size() == 0) return null;
+
+        StringJoiner joiner = new StringJoiner("\n");
+        for (String comment : comments) {
+            if (comment.length() == 0) joiner.add(" ");
+            else joiner.add(indents + "# " + comment);
+        }
+        return joiner + "\n";
+    }
+
+    /**
+     * 从一个文件读取配置并写入注释到某个写入器中。
+     * 该方法的部分源代码借鉴自 tchristofferson/ConfigUpdater 项目。
+     *
+     * @param source 源配置文件
+     * @param writer 配置写入器
+     * @throws IOException 当写入发生错误时抛出
+     */
+    public void writeComments(@NotNull YamlConfiguration source, @NotNull BufferedWriter writer) throws IOException {
+        FileConfiguration temp = new YamlConfiguration(); // 该对象用于临时记录配置内容
+
+        String configHeader = buildHeaderComments(null, "");
+        if (configHeader != null) writer.write(configHeader);
+
+        for (String fullKey : source.getKeys(true)) {
+            Object currentValue = source.get(fullKey);
+
+            String indents = getIndents(fullKey);
+            String headerComments = buildHeaderComments(fullKey, indents);
+            String inlineComment = getInlineComment(fullKey);
+
+            if (headerComments != null) writer.write(headerComments);
+
+            String[] splitFullKey = fullKey.split("[" + SEPARATOR + "]");
+            String trailingKey = splitFullKey[splitFullKey.length - 1];
+
+            if (currentValue instanceof ConfigurationSection) {
+                ConfigurationSection section = (ConfigurationSection) currentValue;
+                writer.write(indents + trailingKey + ":");
+                if (inlineComment != null && inlineComment.length() > 0) {
+                    writer.write(" # " + inlineComment);
+                }
+                if (!section.getKeys(false).isEmpty()) {
+                    writer.write("\n");
+                } else {
+                    writer.write(" {}\n");
+                    if (indents.length() == 0) writer.write("\n");
+                }
+                continue;
+            }
+
+            temp.set(trailingKey, currentValue);
+            String yaml = temp.saveToString();
+            temp.set(trailingKey, null);
+
+            yaml = yaml.substring(0, yaml.length() - 1);
+
+            if (inlineComment != null && inlineComment.length() > 0) {
+                if (yaml.contains("\n")) {
+                    // section为多行内容，需要 InlineComment 加在首行末尾
+                    String[] splitLine = yaml.split("\n", 2);
+                    yaml = splitLine[0] + " # " + inlineComment + "\n" + splitLine[1];
+                } else {
+                    // 其他情况下就直接加载后面就好。
+                    yaml += " # " + inlineComment;
+                }
+            }
+
+            writer.write(indents + yaml.replace("\n", "\n" + indents) + "\n");
+            if (indents.length() == 0) writer.write("\n");
+        }
+
+        writer.close();
+    }
+
+    /**
+     * 得到一个键的缩进。
+     * 该方法的源代码来自 tchristofferson/ConfigUpdater 项目。
+     *
+     * @param key 键
+     * @return 该键的缩进文本
+     */
+    protected static String getIndents(String key) {
+        String[] splitKey = key.split("[" + YAMLConfigProvider.SEPARATOR + "]");
+        return IntStream.range(1, splitKey.length).mapToObj(i -> "  ").collect(Collectors.joining());
     }
 
 }

impl/yaml/src/main/java/cc/carm/lib/configuration/yaml/YAMLConfigProvider.java

@@ -2,16 +2,25 @@ package cc.carm.lib.configuration.yaml;
 
 import cc.carm.lib.configuration.core.ConfigInitializer;
 import cc.carm.lib.configuration.core.source.impl.FileConfigProvider;
-import org.bspfsystems.yamlconfiguration.commented.CommentedYamlConfiguration;
+import org.bspfsystems.yamlconfiguration.file.YamlConfiguration;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
+import java.io.BufferedWriter;
 import java.io.File;
+import java.io.StringWriter;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
 
 public class YAMLConfigProvider extends FileConfigProvider<YAMLSectionWrapper> {
 
+    protected static final char SEPARATOR = '.';
+
     protected final @NotNull YAMLComments comments = new YAMLComments();
-    protected CommentedYamlConfiguration configuration;
+    protected YamlConfiguration configuration;
     protected ConfigInitializer<YAMLConfigProvider> initializer;
 
     public YAMLConfigProvider(@NotNull File file) {
@@ -19,7 +28,7 @@ public class YAMLConfigProvider extends FileConfigProvider<YAMLSectionWrapper> {
     }
 
     public void initializeConfig() {
-        this.configuration = CommentedYamlConfiguration.loadConfiguration(comments, file);
+        this.configuration = YamlConfiguration.loadConfiguration(file);
         this.initializer = new ConfigInitializer<>(this);
     }
 
@@ -29,23 +38,48 @@ public class YAMLConfigProvider extends FileConfigProvider<YAMLSectionWrapper> {
     }
 
     @Override
-    public void reload() throws Exception {
+    protected void onReload() throws Exception {
         configuration.load(getFile());
     }
 
     @Override
     public void save() throws Exception {
         configuration.save(getFile());
+
+        // tchristofferson/ConfigUpdater start
+        StringWriter writer = new StringWriter();
+        this.comments.writeComments(configuration, new BufferedWriter(writer));
+        String value = writer.toString(); // config contents
+
+        Path toUpdatePath = getFile().toPath();
+        if (!value.equals(new String(Files.readAllBytes(toUpdatePath), StandardCharsets.UTF_8))) {
+            // if updated contents are not the same as current file contents, update
+            Files.write(toUpdatePath, value.getBytes(StandardCharsets.UTF_8));
+        }
+        // tchristofferson/ConfigUpdater end
+
     }
 
     @Override
-    public void setComments(@NotNull String path, @NotNull String... comments) {
-        this.comments.set(path, comments);
+    public void setHeaderComment(@Nullable String path, @Nullable List<String> comments) {
+        this.comments.setHeaderComments(path, comments);
     }
 
     @Override
-    public @Nullable String[] getComments(@NotNull String path) {
-        return this.comments.get(path);
+    public void setInlineComment(@NotNull String path, @Nullable String comment) {
+        this.comments.setInlineComment(path, comment);
+    }
+
+    @Override
+    @Nullable
+    @Unmodifiable
+    public List<String> getHeaderComment(@Nullable String path) {
+        return this.comments.getHeaderComment(path);
+    }
+
+    @Override
+    public @Nullable String getInlineComment(@NotNull String path) {
+        return this.comments.getInlineComment(path);
     }
 
     @Override

impl/yaml/src/main/java/cc/carm/lib/configuration/yaml/YAMLValue.java

@@ -6,15 +6,18 @@ import cc.carm.lib.configuration.yaml.builder.YAMLConfigBuilder;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.List;
+
 public abstract class YAMLValue<T> extends CachedConfigValue<T> {
 
     public static @NotNull YAMLConfigBuilder builder() {
         return new YAMLConfigBuilder();
     }
 
-    public YAMLValue(@Nullable YAMLConfigProvider provider,
-                     @Nullable String configPath, @NotNull String[] comments, @Nullable T defaultValue) {
-        super(provider, configPath, comments, defaultValue);
+    public YAMLValue(@Nullable YAMLConfigProvider provider, @Nullable String configPath,
+                     @Nullable List<String> headerComments, @Nullable String inlineComments,
+                     @Nullable T defaultValue) {
+        super(provider, configPath, headerComments, inlineComments, defaultValue);
     }
 
     public YAMLConfigProvider getYAMLProvider() {

impl/yaml/src/main/java/cc/carm/lib/configuration/yaml/builder/serializable/SerializableBuilder.java

@@ -21,7 +21,7 @@ public class SerializableBuilder<T extends ConfigurationSerializable>
 
     @Override
     public @NotNull ConfiguredSerializable<T> build() {
-        return new ConfiguredSerializable<>(this.provider, this.path, this.comments, this.valueClass, this.defaultValue);
+        return new ConfiguredSerializable<>(this.provider, this.path, this.headerComments, this.inlineComment, this.valueClass, this.defaultValue);
     }
 
 

impl/yaml/src/main/java/cc/carm/lib/configuration/yaml/value/ConfiguredSerializable.java

@@ -1,11 +1,12 @@
 package cc.carm.lib.configuration.yaml.value;
 
-import cc.carm.lib.configuration.yaml.YAMLValue;
 import cc.carm.lib.configuration.yaml.YAMLConfigProvider;
+import cc.carm.lib.configuration.yaml.YAMLValue;
 import org.bspfsystems.yamlconfiguration.serialization.ConfigurationSerializable;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.List;
 import java.util.Optional;
 
 public class ConfiguredSerializable<T extends ConfigurationSerializable> extends YAMLValue<T> {
@@ -15,16 +16,16 @@ public class ConfiguredSerializable<T extends ConfigurationSerializable> extends
     }
 
     public static <V extends ConfigurationSerializable> ConfiguredSerializable<V> of(@NotNull Class<V> valueClass,
-                                                                                             @Nullable V defaultValue) {
+                                                                                     @Nullable V defaultValue) {
         return builder().ofSerializable(valueClass).defaults(defaultValue).build();
     }
 
     protected final @NotNull Class<T> valueClass;
 
-    public ConfiguredSerializable(@Nullable YAMLConfigProvider provider,
-                                  @Nullable String configPath, @NotNull String[] comments,
+    public ConfiguredSerializable(@Nullable YAMLConfigProvider provider, @Nullable String configPath,
+                                  @Nullable List<String> headerComments, @Nullable String inlineComments,
                                   @NotNull Class<T> valueClass, @Nullable T defaultValue) {
-        super(provider, configPath, comments, defaultValue);
+        super(provider, configPath, headerComments, inlineComments, defaultValue);
         this.valueClass = valueClass;
     }
 

impl/yaml/src/test/java/config/source/DatabaseConfiguration.java

@@ -1,16 +1,16 @@
 package config.source;
 
 import cc.carm.lib.configuration.core.ConfigurationRoot;
-import cc.carm.lib.configuration.core.annotation.ConfigComment;
 import cc.carm.lib.configuration.core.annotation.ConfigPath;
+import cc.carm.lib.configuration.core.annotation.HeaderComment;
 import cc.carm.lib.configuration.core.value.ConfigValue;
 import cc.carm.lib.configuration.core.value.type.ConfiguredValue;
 
-@ConfigComment({"数据库配置", "  用于提供数据库连接，进行数据库操作。"})
+@HeaderComment({"", "数据库配置", "  用于提供数据库连接，进行数据库操作。"})
 public class DatabaseConfiguration extends ConfigurationRoot {
 
     @ConfigPath("driver")
-    @ConfigComment({
+    @HeaderComment({
             "数据库驱动配置，请根据数据库类型设置。",
             "- MySQL: com.mysql.cj.jdbc.Driver",
             "- MariaDB(推荐): org.mariadb.jdbc.Driver",
@@ -21,11 +21,9 @@ public class DatabaseConfiguration extends ConfigurationRoot {
 
     protected static final ConfigValue<String> HOST = ConfiguredValue.of(String.class, "127.0.0.1");
     protected static final ConfigValue<Integer> PORT = ConfiguredValue.of(Integer.class, 3306);
-
     protected static final ConfigValue<String> DATABASE = ConfiguredValue.of(String.class, "minecraft");
     protected static final ConfigValue<String> USERNAME = ConfiguredValue.of(String.class, "root");
     protected static final ConfigValue<String> PASSWORD = ConfiguredValue.of(String.class, "password");
-
     protected static final ConfigValue<String> EXTRA = ConfiguredValue.of(String.class, "?useSSL=false");
 
     protected static String buildJDBC() {

impl/yaml/src/test/java/config/source/DemoConfiguration.java

@@ -2,8 +2,9 @@ package config.source;
 
 import cc.carm.lib.configuration.core.ConfigInitializer;
 import cc.carm.lib.configuration.core.ConfigurationRoot;
-import cc.carm.lib.configuration.core.annotation.ConfigComment;
 import cc.carm.lib.configuration.core.annotation.ConfigPath;
+import cc.carm.lib.configuration.core.annotation.HeaderComment;
+import cc.carm.lib.configuration.core.annotation.InlineComment;
 import cc.carm.lib.configuration.core.value.ConfigValue;
 import cc.carm.lib.configuration.core.value.type.ConfiguredList;
 import cc.carm.lib.configuration.core.value.type.ConfiguredMap;
@@ -16,21 +17,21 @@ import java.util.Map;
 import java.util.Objects;
 import java.util.UUID;
 
+
+@HeaderComment({
+        "此处内容将显示在配置文件的最上方",
+        ""/*添加一个空行与其他配置的注释分割*/
+})
 public class DemoConfiguration extends ConfigurationRoot {
 
     @ConfigPath(root = true)
-    @ConfigComment({
-            "有时候，需要在配置文件最上面显示点东西，",
-            "此时就推荐添加一个可以用到但并不重要的参数到最上面",
-            "并给他添加对应的注释。"
-    })
     protected static final ConfigValue<Double> VERSION = ConfiguredValue.of(Double.class, 1.0D);
 
-
     // 支持通过 Class<?> 变量标注子配置，一并注册。
     // 注意： 若对应类也有注解，则优先使用类的注解。
     @ConfigPath("impl-test") //支持通过注解修改子配置的主路径，若不修改则以变量名自动生成。
-    @ConfigComment("Something...") // 支持给子路径直接打注释
+    @HeaderComment({"", "Something..."}) // 支持给子路径直接打注释
+    @InlineComment("InlineComments for class path")
     public static final Class<?> IMPL = ImplConfiguration.class;
 
     // 子配置文件
@@ -38,14 +39,15 @@ public class DemoConfiguration extends ConfigurationRoot {
     public static final Class<?> DB_CONFIG = DatabaseConfiguration.class;
 
     @ConfigPath("user") // 通过注解规定配置文件中的路径，若不进行注解则以变量名自动生成。
-    @ConfigComment({"Section类型数据测试"}) // 通过注解给配置添加注释。
+    @HeaderComment({"", "Section类型数据测试"}) // 通过注解给配置添加注释。
+    @InlineComment("Section数据也支持InlineComment注释")
     public static final ConfigValue<TestModel> MODEL_TEST = ConfiguredSection
             .builder(TestModel.class)
             .defaults(new TestModel("Carm", UUID.randomUUID()))
             .parseValue((section, defaultValue) -> TestModel.deserialize(section))
             .serializeValue(TestModel::serialize).build();
 
-    @ConfigComment({"[ID-UUID] 对照表", "", "用于测试Map类型的解析与序列化保存"})
+    @HeaderComment({"", "[ID - UUID]对照表", "", "用于测试Map类型的解析与序列化保存"})
     public static final ConfigValue<Map<Integer, UUID>> USERS = ConfiguredMap
             .builder(Integer.class, UUID.class).fromString()
             .parseKey(Integer::parseInt)
@@ -60,6 +62,7 @@ public class DemoConfiguration extends ConfigurationRoot {
     public static class Sub extends ConfigurationRoot {
 
         @ConfigPath(value = "uuid-value", root = true)
+        @InlineComment("This is an inline comment")
         public static final ConfigValue<UUID> UUID_CONFIG_VALUE = ConfiguredValue
                 .builder(UUID.class).fromString()
                 .parseValue((data, defaultValue) -> UUID.fromString(data))

impl/yaml/src/test/java/config/source/ImplConfiguration.java

@@ -10,7 +10,9 @@ import config.model.TestModel;
 @ConfigPath(root = true)
 public class ImplConfiguration extends ConfigurationRoot {
 
-    public static final ConfigValue<? extends AbstractModel> TEST = ConfiguredSerializable.of(TestModel.class, TestModel.random());
+    public static final ConfigValue<? extends AbstractModel> TEST = ConfiguredSerializable.of(
+            TestModel.class, TestModel.random()
+    );
 
 
 }

pom.xml

@@ -15,7 +15,7 @@
     <groupId>cc.carm.lib</groupId>
     <artifactId>easyconfiguration-parent</artifactId>
     <packaging>pom</packaging>
-    <version>2.2.0</version>
+    <version>3.1.0</version>
     <modules>
         <module>core</module>
         <module>impl/yaml</module>