fix(text): 令 AbstractText#parse 返回值不得为null，避免在List类型循环parse时出现异常。

项目结构修改，避免使用上的误解。同时为 Bungee(YAML) 支持了注释功能。

BREAKING CHANGE: 包名与入口类变更
  1. 项目结构与包名修改
  mineconfiguration-bukkit-general -> mineconfiguration-bukkit
  mineconfiguration-bukkit-native -> mineconfiguration-spigot
  2. MineConfiguration入口类变更，现移动到各自平台的包下。

.documentation/javadoc/JAVADOC-README.md

@@ -0,0 +1,9 @@
+# MineConfiguration Javadoc
+
+基于 [Github Pages](https://pages.github.com/) 搭建，请访问 [JavaDoc](https://carmjos.github.io/MineConfiguration) 。
+
+## 如何实现？
+
+若您也想通过 [Github Actions](https://docs.github.com/en/actions/learn-github-actions) 
+自动部署项目的Javadoc到 [Github Pages](https://pages.github.com/) ，
+可以参考我的文章 [《自动部署Javadoc到Github Pages》](https://pages.carm.cc/doc/javadoc-in-github.html) 。

.github/workflows/deploy.yml

@@ -12,7 +12,7 @@ on:
 
 jobs:
   gh-deploy:
-    name: "Publish Project (GitHub)"
+    name: "Deploy Project (GitHub)"
     runs-on: ubuntu-latest
 
     steps:
@@ -37,7 +37,7 @@ jobs:
           MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
 
   central-deploy:
-    name: "Deploy Project (Central Repository)"
+    name: "Deploy Project (Central)"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
@@ -58,4 +58,4 @@ jobs:
         env:
           MAVEN_USERNAME: ${{ secrets.OSSRH_USER }}
           MAVEN_PASSWORD: ${{ secrets.OSSRH_PASS }}
-          MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
+          MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}

.github/workflows/javadoc.yml

@@ -0,0 +1,74 @@
+name: "Publish Javadoc"
+
+on:
+  # 支持手动触发构建
+  workflow_dispatch:
+  release:
+    # 创建release的时候触发
+    types: [ published ]
+
+
+jobs:
+
+  javadoc-deploy:
+    name: "Deploy Javadoc (Github Pages)"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: "Set up JDK"
+        uses: actions/setup-java@v2
+        with:
+          java-version: '8'
+          distribution: 'adopt'
+          cache: maven
+
+      - name: "Generate Javadoc"
+        run: mvn -B javadoc:aggregate --file pom.xml -DskipTests
+
+      - name: "Copy Javadoc"
+        run: |
+          rm -rf docs
+          mkdir -vp docs
+          cp -vrf target/site/apidocs/* docs/
+          cp -vrf .documentation/javadoc/JAVADOC-README.md docs/README.md
+
+      - name: "Generate Sitemap"
+        id: sitemap
+        uses: cicirello/generate-sitemap@v1
+        with:
+          base-url-path: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
+          path-to-root: docs
+
+      - name: Output stats
+        run: |
+          echo "sitemap-path = ${{ steps.sitemap.outputs.sitemap-path }}"
+          echo "url-count = ${{ steps.sitemap.outputs.url-count }}"
+          echo "excluded-count = ${{ steps.sitemap.outputs.excluded-count }}"
+          ls -l docs
+
+      - name: Configure Git
+        env:
+          DEPLOY_PRI: ${{secrets.DEPLOY_PRI}}
+        run: |
+          sudo timedatectl set-timezone "Asia/Shanghai"
+          mkdir -p ~/.ssh/
+          echo "$DEPLOY_PRI" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+          git config --global user.name '${{ github.repository_owner }}'
+          git config --global user.email '${{ github.repository_owner }}@users.noreply.github.com'
+
+      - name: Commit documentation changes
+        run: |
+          echo "Committing changes to git@github.com:${{ github.repository_owner }}/${{ github.event.repository.name }}.git ..."
+          cd docs
+          git init
+          git remote add origin git@github.com:${{ github.repository_owner }}/${{ github.event.repository.name }}.git
+          git checkout -b gh-pages
+          git add -A
+          git commit -m "API Document generated."
+
+      - name: Javadoc Website Push
+        run: |
+          cd docs
+          git push origin HEAD:gh-pages --force

README.md

@@ -43,19 +43,17 @@ Bukkit系通用依赖，不包含实现部分，请使用 **MineConfiguration-Bu
 
 以上类型可以通过 `CraftConfigValue.builder()` 来创建，部分类型提供了 `of(...);` 方法来快速创建。
 
-#### **MineConfiguration-Bukkit-General** _(推荐)_
+#### **MineConfiguration-Bukkit** _(推荐)_
 
 适用于Bukkit的版本，包含以Bukkit为基础的其他服务端 *(如Spigot、Paper、CatServer)* 。
 
-#### **MineConfiguration-Bukkit-Native**
+#### **MineConfiguration-Spigot**
 
 适用于 Spigot(1.18+) 的版本，适配了1.18及以后版本Spigot原生自带的配置文件注释功能，随Spigot更新而优化，安全稳定。
 
 ### **MineConfiguration-Bungee**
 
-适用于BungeeCord的版本，可用JSON与YAML格式，但**不支持配置文件注释**。
-
-如需使用配置文件注释，建议使用 [EasyConfiguration-YAML](https://github.com/CarmJos/EasyConfiguration) 。
+适用于BungeeCord的版本，可用JSON与YAML格式。其中JSON格式**不支持配置文件注释**。
 
 ## 开发
 
@@ -111,14 +109,14 @@ Bukkit系通用依赖，不包含实现部分，请使用 **MineConfiguration-Bu
 
         <dependency>
             <groupId>cc.carm.lib</groupId>
-            <artifactId>mineconfiguration-bukkit-general</artifactId>
+            <artifactId>mineconfiguration-bukkit</artifactId>
             <version>[LATEST RELEASE]</version>
             <scope>compile</scope>
         </dependency>
         
         <dependency>
             <groupId>cc.carm.lib</groupId>
-            <artifactId>mineconfiguration-bukkit-native</artifactId>
+            <artifactId>mineconfiguration-spigot</artifactId>
             <version>[LATEST RELEASE]</version>
             <scope>compile</scope>
         </dependency>
@@ -164,9 +162,9 @@ repositories {
 
 dependencies {
 
-    api "cc.carm.lib:mineconfiguration-bukkit-general:[LATEST RELEASE]"
+    api "cc.carm.lib:mineconfiguration-bukkit:[LATEST RELEASE]"
 
-    api "cc.carm.lib:mineconfiguration-bukkit-native:[LATEST RELEASE]"
+    api "cc.carm.lib:mineconfiguration-spigot:[LATEST RELEASE]"
 
     api "cc.carm.lib:mineconfiguration-bungee:[LATEST RELEASE]"
 

common/pom.xml

@@ -5,12 +5,12 @@
     <parent>
         <artifactId>mineconfiguration-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.4.2</version>
+        <version>2.0.2</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <properties>
-        <maven.compiler.source>${java.version}</maven.compiler.source>
-        <maven.compiler.target>${java.version}</maven.compiler.target>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
     </properties>
     <artifactId>mineconfiguration-common</artifactId>
 
@@ -23,14 +23,6 @@
             <scope>compile</scope>
         </dependency>
 
-        <dependency>
-            <groupId>de.themoep</groupId>
-            <artifactId>minedown</artifactId>
-            <version>1.7.1-SNAPSHOT</version>
-            <scope>compile</scope>
-            <optional>true</optional>
-        </dependency>
-
         <dependency>
             <groupId>net.md-5</groupId>
             <artifactId>bungeecord-chat</artifactId>
@@ -43,18 +35,6 @@
 
     <build>
         <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-jar-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-source-plugin</artifactId>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>

common/src/main/java/cc/carm/lib/mineconfiguration/common/data/AbstractText.java

@@ -28,16 +28,14 @@ public abstract class AbstractText<R> {
         return this.message;
     }
 
-    public <M> @Nullable M parse(@NotNull BiFunction<@Nullable R, @NotNull String, @NotNull M> parser,
-                                 @Nullable R receiver, @Nullable String[] params, @Nullable Object[] values) {
+    public <M> @NotNull M parse(@NotNull BiFunction<@Nullable R, @NotNull String, @NotNull M> parser,
+                                @Nullable R receiver, @Nullable String[] params, @Nullable Object[] values) {
         return parse(parser, receiver, ParamsUtils.buildParams(params, values));
     }
 
-    public <M> @Nullable M parse(@NotNull BiFunction<@Nullable R, @NotNull String, @NotNull M> parser,
-                                 @Nullable R receiver, @NotNull Map<String, Object> placeholders) {
-        String message = getMessage();
-        if (message.isEmpty()) return null; // No further processing
-        else return parser.apply(receiver, ParamsUtils.setPlaceholders(message, placeholders));
+    public <M> @NotNull M parse(@NotNull BiFunction<@Nullable R, @NotNull String, @NotNull M> parser,
+                                @Nullable R receiver, @NotNull Map<String, Object> placeholders) {
+        return parser.apply(receiver, ParamsUtils.setPlaceholders(message, placeholders));
     }
 
 

common/src/main/java/cc/carm/lib/mineconfiguration/common/value/ConfigMessageList.java

@@ -1,10 +1,10 @@
 package cc.carm.lib.mineconfiguration.common.value;
 
-import cc.carm.lib.mineconfiguration.common.utils.ParamsUtils;
-import cc.carm.lib.mineconfiguration.common.data.AbstractText;
 import cc.carm.lib.configuration.core.function.ConfigDataFunction;
 import cc.carm.lib.configuration.core.source.ConfigurationProvider;
 import cc.carm.lib.configuration.core.value.type.ConfiguredList;
+import cc.carm.lib.mineconfiguration.common.data.AbstractText;
+import cc.carm.lib.mineconfiguration.common.utils.ParamsUtils;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 

platform/bukkit/base/pom.xml

@@ -3,50 +3,31 @@
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <parent>
-        <artifactId>mineconfiguration-bukkit</artifactId>
+        <artifactId>mineconfiguration-bukkit-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.4.2</version>
+        <version>2.0.2</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <properties>
-        <maven.compiler.source>${java.version}</maven.compiler.source>
-        <maven.compiler.target>${java.version}</maven.compiler.target>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
     </properties>
     <artifactId>mineconfiguration-bukkit-base</artifactId>
     <packaging>jar</packaging>
 
     <dependencies>
 
-        <dependency>
-            <groupId>${project.parent.groupId}</groupId>
-            <artifactId>easyconfiguration-core</artifactId>
-            <version>${easyconfiguration.version}</version>
-            <scope>compile</scope>
-        </dependency>
-
         <dependency>
             <groupId>${project.parent.groupId}</groupId>
             <artifactId>mineconfiguration-common</artifactId>
             <version>${project.parent.version}</version>
             <scope>compile</scope>
         </dependency>
-        
+
     </dependencies>
 
     <build>
         <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-jar-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-source-plugin</artifactId>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>

platform/bukkit/base/src/main/java/cc/carm/lib/mineconfiguration/bukkit/builder/item/ItemConfigBuilder.java

@@ -5,13 +5,12 @@ import cc.carm.lib.mineconfiguration.bukkit.data.ItemConfig;
 import cc.carm.lib.mineconfiguration.bukkit.value.ConfiguredItem;
 import cc.carm.lib.mineconfiguration.common.utils.ParamsUtils;
 import org.bukkit.Material;
+import org.bukkit.enchantments.Enchantment;
+import org.bukkit.inventory.ItemFlag;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.List;
-import java.util.Optional;
+import java.util.*;
 import java.util.function.Function;
 
 public class ItemConfigBuilder extends AbstractCraftBuilder<ItemConfig, ItemConfigBuilder> {
@@ -21,6 +20,9 @@ public class ItemConfigBuilder extends AbstractCraftBuilder<ItemConfig, ItemConf
     protected String name = null;
     protected List<String> lore = new ArrayList<>();
 
+    protected Map<Enchantment, Integer> enchants = new LinkedHashMap<>();
+    protected Set<ItemFlag> flags = new LinkedHashSet<>();
+
     protected @NotNull String[] params = new String[0];
     protected @NotNull Function<@NotNull String, @NotNull String> paramFormatter = ParamsUtils.DEFAULT_PARAM_FORMATTER;
 
@@ -63,6 +65,24 @@ public class ItemConfigBuilder extends AbstractCraftBuilder<ItemConfig, ItemConf
         return this;
     }
 
+    public ItemConfigBuilder defaultEnchants(@NotNull Map<Enchantment, Integer> enchants) {
+        this.enchants = new LinkedHashMap<>(enchants);
+        return this;
+    }
+
+    public ItemConfigBuilder defaultEnchant(@NotNull Enchantment enchant, int level) {
+        return defaultEnchants(Collections.singletonMap(enchant, level));
+    }
+
+    public ItemConfigBuilder defaultFlags(@NotNull Set<ItemFlag> flags) {
+        this.flags = new LinkedHashSet<>(flags);
+        return this;
+    }
+
+    public ItemConfigBuilder defaultFlags(@NotNull ItemFlag... flags) {
+        return defaultFlags(new LinkedHashSet<>(Arrays.asList(flags)));
+    }
+
     public ItemConfigBuilder formatParam(@NotNull Function<@NotNull String, @NotNull String> paramFormatter) {
         this.paramFormatter = paramFormatter;
         return getThis();
@@ -85,7 +105,7 @@ public class ItemConfigBuilder extends AbstractCraftBuilder<ItemConfig, ItemConf
 
     protected @Nullable ItemConfig buildDefault() {
         if (this.type == null) return null;
-        else return new ItemConfig(type, data, name, lore);
+        else return new ItemConfig(type, data, name, lore, enchants, flags);
     }
 
     @Override

platform/bukkit/base/src/main/java/cc/carm/lib/mineconfiguration/bukkit/builder/title/TitleConfigBuilder.java

@@ -28,7 +28,7 @@ public class TitleConfigBuilder extends AbstractCraftBuilder<TitleConfig, TitleC
         }
     };
 
-    protected @NotNull String[] params;
+    protected @NotNull String[] params = new String[0];
 
     protected @Range(from = 0L, to = Integer.MAX_VALUE) int fadeIn = 10;
     protected @Range(from = 0L, to = Integer.MAX_VALUE) int stay = 60;

platform/bukkit/base/src/main/java/cc/carm/lib/mineconfiguration/bukkit/data/ItemConfig.java

@@ -3,13 +3,16 @@ package cc.carm.lib.mineconfiguration.bukkit.data;
 import cc.carm.lib.configuration.core.source.ConfigurationWrapper;
 import cc.carm.lib.mineconfiguration.bukkit.utils.TextParser;
 import org.bukkit.Material;
+import org.bukkit.enchantments.Enchantment;
 import org.bukkit.entity.Player;
+import org.bukkit.inventory.ItemFlag;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.meta.ItemMeta;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.*;
+import java.util.stream.Collectors;
 
 public class ItemConfig {
 
@@ -18,12 +21,32 @@ public class ItemConfig {
     protected @Nullable String name;
     protected @NotNull List<String> lore;
 
+    protected @NotNull Map<Enchantment, Integer> enchants;
+    protected @NotNull Set<ItemFlag> flags;
+
+    public ItemConfig(@NotNull Material type, @Nullable String name) {
+        this(type, name, Collections.emptyList());
+    }
+
+    public ItemConfig(@NotNull Material type, @Nullable String name, @NotNull List<String> lore) {
+        this(type, (short) 0, name, lore);
+    }
+
     public ItemConfig(@NotNull Material type, short damage,
                       @Nullable String name, @NotNull List<String> lore) {
+        this(type, damage, name, lore, Collections.emptyMap(), Collections.emptySet());
+    }
+
+    public ItemConfig(@NotNull Material type, short damage,
+                      @Nullable String name, @NotNull List<String> lore,
+                      @NotNull Map<Enchantment, Integer> enchants,
+                      @NotNull Set<ItemFlag> flags) {
         this.type = type;
         this.data = damage;
         this.name = name;
         this.lore = lore;
+        this.enchants = enchants;
+        this.flags = flags;
     }
 
     public @NotNull Material getType() {
@@ -75,6 +98,8 @@ public class ItemConfig {
         if (meta == null) return item;
         Optional.ofNullable(getName(player, placeholders)).ifPresent(meta::setDisplayName);
         Optional.ofNullable(getLore(player, placeholders)).ifPresent(meta::setLore);
+        enchants.forEach((enchant, level) -> meta.addEnchant(enchant, level, true));
+        flags.forEach(meta::addItemFlags);
         item.setItemMeta(meta);
         return item;
     }
@@ -86,6 +111,18 @@ public class ItemConfig {
         if (name != null) map.put("name", name);
         if (!lore.isEmpty()) map.put("lore", lore);
 
+        Map<String, Integer> enchantments = new LinkedHashMap<>();
+        enchants.forEach((enchant, level) -> {
+            if (level > 0) enchantments.put(enchant.getName(), level);
+        });
+
+        if (!enchantments.isEmpty()) {
+            map.put("enchants", enchantments);
+        }
+
+        if (!flags.isEmpty()) {
+            map.put("flags", flags.stream().map(ItemFlag::name).collect(Collectors.toList()));
+        }
         return map;
     }
 
@@ -95,11 +132,41 @@ public class ItemConfig {
 
         Material type = Material.matchMaterial(typeName);
         if (type == null) throw new Exception("Invalid material name: " + typeName);
-        else return new ItemConfig(
-                type, section.getShort("data", (short) 0),
-                section.getString("name"),
-                section.getStringList("lore")
-        );
+
+        short data = section.getShort("data", (short) 0);
+        String name = section.getString("name");
+        List<String> lore = section.getStringList("lore");
+
+        Map<Enchantment, Integer> enchantments = readEnchantments(section.getConfigurationSection("enchants"));
+        Set<ItemFlag> flags = readFlags(section.getStringList("flags"));
+
+        return new ItemConfig(type, data, name, lore, enchantments, flags);
+    }
+
+    private static ItemFlag parseFlag(String flagName) {
+        return Arrays.stream(ItemFlag.values()).filter(flag -> flag.name().equalsIgnoreCase(flagName)).findFirst().orElse(null);
+    }
+
+    private static Set<ItemFlag> readFlags(List<String> flagConfig) {
+        Set<ItemFlag> flags = new LinkedHashSet<>();
+        for (String flagName : flagConfig) {
+            ItemFlag flag = parseFlag(flagName);
+            if (flag != null) flags.add(flag);
+        }
+        return flags;
+    }
+
+    private static Map<Enchantment, Integer> readEnchantments(ConfigurationWrapper section) {
+        Map<Enchantment, Integer> enchantments = new LinkedHashMap<>();
+        if (section == null) return enchantments;
+        section.getKeys(false).forEach(key -> {
+            Enchantment enchantment = Enchantment.getByName(key);
+            int level = section.getInt(key, 0);
+            if (enchantment != null && level > 0) {
+                enchantments.put(enchantment, level);
+            }
+        });
+        return enchantments;
     }
 
 }

platform/bukkit/base/src/main/java/cc/carm/lib/mineconfiguration/bukkit/data/SoundConfig.java

@@ -85,7 +85,7 @@ public class SoundConfig {
 
     @Contract("null -> null")
     public static @Nullable SoundConfig deserialize(@Nullable String string) throws Exception {
-        if (string == null) return null;
+        if (string == null || string.isEmpty()) return null;
 
         String[] args = string.contains(":") ? string.split(":") : new String[]{string};
         if (args.length < 1) return null;

platform/bukkit/general/pom.xml

@@ -3,17 +3,17 @@
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <parent>
-        <artifactId>mineconfiguration-bukkit</artifactId>
+        <artifactId>mineconfiguration-bukkit-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.4.2</version>
+        <version>2.0.2</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <properties>
-        <maven.compiler.source>${java.version}</maven.compiler.source>
-        <maven.compiler.target>${java.version}</maven.compiler.target>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
     </properties>
 
-    <artifactId>mineconfiguration-bukkit-general</artifactId>
+    <artifactId>mineconfiguration-bukkit</artifactId>
     <packaging>jar</packaging>
 
     <dependencies>
@@ -29,18 +29,6 @@
 
     <build>
         <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-jar-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-source-plugin</artifactId>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>

platform/bukkit/general/src/main/java/cc/carm/lib/mineconfiguration/bukkit/MineConfiguration.java

@@ -1,4 +1,4 @@
-package cc.carm.lib.mineconfiguration;
+package cc.carm.lib.mineconfiguration.bukkit;
 
 import cc.carm.lib.mineconfiguration.bukkit.source.BukkitConfigProvider;
 import org.bukkit.plugin.Plugin;

platform/bukkit/pom.xml

@@ -5,24 +5,22 @@
     <parent>
         <artifactId>mineconfiguration-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.4.2</version>
+        <version>2.0.2</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <properties>
-        <maven.compiler.source>${java.version}</maven.compiler.source>
-        <maven.compiler.target>${java.version}</maven.compiler.target>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
     </properties>
-    <artifactId>mineconfiguration-bukkit</artifactId>
+    <artifactId>mineconfiguration-bukkit-parent</artifactId>
     <packaging>pom</packaging>
     <modules>
         <module>base</module>
-
         <module>general</module>
-        <module>native</module>
     </modules>
 
-    <name>MineConfiguration-Bukkit</name>
+    <name>MineConfiguration-Bukkit-Parent</name>
 
     <dependencies>
 

platform/bungee/pom.xml

@@ -5,13 +5,13 @@
     <parent>
         <artifactId>mineconfiguration-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.4.2</version>
+        <version>2.0.2</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <properties>
-        <maven.compiler.source>${java.version}</maven.compiler.source>
-        <maven.compiler.target>${java.version}</maven.compiler.target>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
     </properties>
     <artifactId>mineconfiguration-bungee</artifactId>
     <packaging>jar</packaging>
@@ -54,18 +54,6 @@
 
     <build>
         <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-jar-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-source-plugin</artifactId>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>

platform/bungee/src/main/java/cc/carm/lib/mineconfiguration/bungee/MineConfiguration.java

@@ -1,4 +1,4 @@
-package cc.carm.lib.mineconfiguration;
+package cc.carm.lib.mineconfiguration.bungee;
 
 import cc.carm.lib.mineconfiguration.bungee.source.BungeeConfigProvider;
 import net.md_5.bungee.api.plugin.Plugin;

platform/bungee/src/main/java/cc/carm/lib/mineconfiguration/bungee/source/BungeeConfigProvider.java

@@ -4,25 +4,39 @@ import cc.carm.lib.configuration.core.ConfigInitializer;
 import cc.carm.lib.configuration.core.source.impl.FileConfigProvider;
 import net.md_5.bungee.config.Configuration;
 import net.md_5.bungee.config.ConfigurationProvider;
+import net.md_5.bungee.config.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.IOException;
+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 BungeeConfigProvider extends FileConfigProvider<BungeeSectionWrapper> {
 
+    protected static final char SEPARATOR = '.';
+
     protected ConfigurationProvider loader;
     protected Configuration configuration;
     protected ConfigInitializer<BungeeConfigProvider> initializer;
 
-    public BungeeConfigProvider(@NotNull File file, ConfigurationProvider loader) {
+    protected BungeeYAMLComments comments = new BungeeYAMLComments();
+
+    public BungeeConfigProvider(@NotNull File file, @NotNull ConfigurationProvider loader) {
         super(file);
         this.loader = loader;
     }
 
+    public BungeeConfigProvider(@NotNull File file, @NotNull Class<? extends ConfigurationProvider> providerClass) {
+        this(file, ConfigurationProvider.getProvider(providerClass));
+    }
+
     public void initializeConfig() throws IOException {
         this.configuration = getLoader().load(file);
         this.initializer = new ConfigInitializer<>(this);
@@ -41,26 +55,36 @@ public class BungeeConfigProvider extends FileConfigProvider<BungeeSectionWrappe
     @Override
     public void save() throws Exception {
         getLoader().save(configuration, file);
+        if (getLoader() instanceof YamlConfiguration) {
+            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))) {
+                Files.write(toUpdatePath, value.getBytes(StandardCharsets.UTF_8));
+            }
+        }
     }
 
     @Override
     public void setHeaderComment(@Nullable String path, @Nullable List<String> comments) {
-
+        this.comments.setHeaderComments(path, comments);
     }
 
     @Override
     public void setInlineComment(@NotNull String path, @Nullable String comment) {
-
+        this.comments.setInlineComment(path, comment);
     }
 
     @Override
     public @Nullable @Unmodifiable List<String> getHeaderComment(@Nullable String path) {
-        return null;
+        return this.comments.getHeaderComment(path);
     }
 
     @Override
     public @Nullable String getInlineComment(@NotNull String path) {
-        return null;
+        return this.comments.getInlineComment(path);
     }
 
     @Override

platform/bungee/src/main/java/cc/carm/lib/mineconfiguration/bungee/source/BungeeSectionWrapper.java

@@ -9,6 +9,8 @@ import org.jetbrains.annotations.Nullable;
 import java.util.*;
 import java.util.stream.Collectors;
 
+import static cc.carm.lib.mineconfiguration.bungee.source.BungeeConfigProvider.SEPARATOR;
+
 public class BungeeSectionWrapper implements ConfigurationWrapper {
 
     private final Configuration section;
@@ -22,14 +24,31 @@ public class BungeeSectionWrapper implements ConfigurationWrapper {
         return section == null ? null : new BungeeSectionWrapper(section);
     }
 
+    protected static Set<String> getAllKeys(@NotNull Configuration config) {
+        Set<String> keys = new LinkedHashSet<>();
+        for (String key : config.getKeys()) {
+            keys.add(key);
+            Object value = config.get(key);
+            if (value instanceof Configuration) {
+                getAllKeys((Configuration) value).stream()
+                        .map(subKey -> key + SEPARATOR + subKey).forEach(keys::add);
+            }
+        }
+        return keys;
+    }
+
     @Override
     public @NotNull Set<String> getKeys(boolean deep) {
-        return new LinkedHashSet<>(section.getKeys());
+        if (deep) {
+            return new LinkedHashSet<>(getAllKeys(section));
+        } else {
+            return new LinkedHashSet<>(section.getKeys());
+        }
     }
 
     @Override
     public @NotNull Map<String, Object> getValues(boolean deep) {
-        return section.getKeys().stream()
+        return getKeys(deep).stream()
                 .collect(Collectors.toMap(key -> key, section::get, (a, b) -> b, LinkedHashMap::new));
     }
 

platform/bungee/src/main/java/cc/carm/lib/mineconfiguration/bungee/source/BungeeYAMLComments.java

@@ -0,0 +1,152 @@
+package cc.carm.lib.mineconfiguration.bungee.source;
+
+import net.md_5.bungee.config.Configuration;
+import net.md_5.bungee.config.ConfigurationProvider;
+import net.md_5.bungee.config.YamlConfiguration;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.io.StringWriter;
+import java.util.*;
+import java.util.stream.Collectors;
+import java.util.stream.IntStream;
+
+import static cc.carm.lib.mineconfiguration.bungee.source.BungeeConfigProvider.SEPARATOR;
+
+public class BungeeYAMLComments {
+
+    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;
+    }
+
+    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 {
+            getHeaderComments().put(path, comments);
+        }
+    }
+
+
+    public void setInlineComment(@NotNull String path, @Nullable String comment) {
+        if (comment == null) {
+            getInlineComments().remove(path);
+        } else {
+            getInlineComments().put(path, comment);
+        }
+    }
+
+    @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 Configuration source, @NotNull BufferedWriter writer) throws IOException {
+        ConfigurationProvider provider = ConfigurationProvider.getProvider(YamlConfiguration.class);
+        Configuration tmp = new Configuration();// 该对象用于临时记录配置内容
+
+        String configHeader = buildHeaderComments(null, "");
+        if (configHeader != null) writer.write(configHeader);
+
+        for (String fullKey : BungeeSectionWrapper.getAllKeys(source)) {
+            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 Configuration) {
+                Configuration section = (Configuration) currentValue;
+                writer.write(indents + trailingKey + ":");
+                if (inlineComment != null && inlineComment.length() > 0) {
+                    writer.write(" # " + inlineComment);
+                }
+                if (!section.getKeys().isEmpty()) {
+                    writer.write("\n");
+                } else {
+                    writer.write(" {}\n");
+                    if (indents.length() == 0) writer.write("\n");
+                }
+                continue;
+            }
+
+            tmp.set(trailingKey, currentValue);
+            StringWriter tmpStr = new StringWriter();
+            provider.save(tmp, tmpStr);
+            String yaml = tmpStr.toString();
+            tmpStr.close();
+            tmp.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("[" + SEPARATOR + "]");
+        return IntStream.range(1, splitKey.length).mapToObj(i -> "  ").collect(Collectors.joining());
+    }
+
+}

platform/bungee/src/test/java/ConfigTest.java

@@ -0,0 +1,62 @@
+import cc.carm.lib.configuration.core.ConfigurationRoot;
+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 cc.carm.lib.configuration.core.value.type.ConfiguredList;
+import cc.carm.lib.configuration.core.value.type.ConfiguredValue;
+import cc.carm.lib.mineconfiguration.bungee.MineConfiguration;
+import org.junit.Test;
+
+import java.io.File;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.util.List;
+
+public class ConfigTest {
+
+
+    @Test
+    public void test() {
+        File file = new File("target/config.yml");
+        ConfigurationProvider<?> config = MineConfiguration.from(file);
+        config.initialize(Configuration.class);
+
+        try {
+            System.out.println("--------------------------------------------");
+            System.out.println(new String(Files.readAllBytes(file.toPath()), StandardCharsets.UTF_8));
+            System.out.println("--------------------------------------------");
+        } catch (Exception exception) {
+            exception.printStackTrace();
+        }
+    }
+
+
+    @HeaderComment({
+            "MineConfiguration for BungeeCord",
+            "测试实例配置文件", ""
+    })
+    public static class Configuration extends ConfigurationRoot {
+
+        @InlineComment("是否显示DEBUG消息")
+        public static final ConfigValue<Boolean> DEBUG = ConfiguredValue.of(Boolean.class, false);
+
+        @HeaderComment("启动时执行的命令")
+        public static final class START_UP {
+
+            @HeaderComment("延迟执行的时间(单位:秒)")
+            public static final ConfigValue<Integer> DELAY = ConfiguredValue.of(Integer.class, 30);
+
+            @HeaderComment("循环执行的间隔(单位:秒)")
+            public static final ConfigValue<Integer> PERIOD = ConfiguredValue.of(Integer.class, 10);
+
+            @HeaderComment("执行的指令列表")
+            @InlineComment("建议以\"\"包裹")
+            public static final ConfigValue<List<String>> COMMANDS = ConfiguredList.builder(String.class)
+                    .fromString().defaults("alert Commands here!").build();
+        }
+
+    }
+
+
+}

platform/spigot/pom.xml

@@ -3,17 +3,18 @@
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <parent>
-        <artifactId>mineconfiguration-bukkit</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.4.2</version>
+        <artifactId>mineconfiguration-parent</artifactId>
+        <version>2.0.2</version>
+        <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <properties>
-        <maven.compiler.source>${java.version}</maven.compiler.source>
-        <maven.compiler.target>${java.version}</maven.compiler.target>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
     </properties>
 
-    <artifactId>mineconfiguration-bukkit-native</artifactId>
+    <artifactId>mineconfiguration-spigot</artifactId>
     <packaging>jar</packaging>
 
     <dependencies>
@@ -32,22 +33,27 @@
             <scope>provided</scope>
         </dependency>
 
+
+        <!--PlaceholderAPI for general placeholder's support-->
+        <dependency>
+            <groupId>me.clip</groupId>
+            <artifactId>placeholderapi</artifactId>
+            <version>2.11.1</version>
+            <scope>provided</scope>
+        </dependency>
+
+        <!--ProtocolLib for general packet's function support-->
+        <dependency>
+            <groupId>com.comphenix.protocol</groupId>
+            <artifactId>ProtocolLib</artifactId>
+            <version>4.8.0</version>
+            <scope>provided</scope>
+        </dependency>
+
     </dependencies>
 
     <build>
         <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-jar-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-source-plugin</artifactId>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>

platform/spigot/src/main/java/cc/carm/lib/mineconfiguration/spigot/MineConfiguration.java

@@ -1,6 +1,6 @@
-package cc.carm.lib.mineconfiguration;
+package cc.carm.lib.mineconfiguration.spigot;
 
-import cc.carm.lib.mineconfiguration.bukkit.source.SpigotConfigProvider;
+import cc.carm.lib.mineconfiguration.spigot.source.SpigotConfigProvider;
 import org.bukkit.plugin.Plugin;
 
 import java.io.File;

platform/spigot/src/main/java/cc/carm/lib/mineconfiguration/spigot/source/SpigotConfigProvider.java

@@ -1,6 +1,7 @@
-package cc.carm.lib.mineconfiguration.bukkit.source;
+package cc.carm.lib.mineconfiguration.spigot.source;
 
 import cc.carm.lib.configuration.core.ConfigInitializer;
+import cc.carm.lib.mineconfiguration.bukkit.source.CraftConfigProvider;
 import org.bukkit.configuration.file.YamlConfiguration;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;

pom.xml

@@ -4,9 +4,9 @@
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <properties>
-        <java.version>1.8</java.version>
-        <maven.compiler.source>${java.version}</maven.compiler.source>
-        <maven.compiler.target>${java.version}</maven.compiler.target>
+        <project.jdk.version>8</project.jdk.version>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
 
@@ -14,13 +14,14 @@
     </properties>
     <groupId>cc.carm.lib</groupId>
     <artifactId>mineconfiguration-parent</artifactId>
-    <version>1.4.2</version>
+    <version>2.0.2</version>
     <packaging>pom</packaging>
     <modules>
         <module>common</module>
 
         <module>platform/bungee</module>
         <module>platform/bukkit</module>
+        <module>platform/spigot</module>
     </modules>
 
     <name>MineConfiguration</name>
@@ -151,6 +152,36 @@
                     <goals>deploy</goals>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.10.1</version>
+                <configuration>
+                    <source>${project.jdk.version}</source>
+                    <target>${project.jdk.version}</target>
+                    <encoding>UTF-8</encoding>
+                    <compilerArgument>-parameters</compilerArgument>
+                </configuration>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <version>3.2.2</version>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <version>3.2.1</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>jar-no-fork</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
 
         <pluginManagement>
@@ -185,38 +216,6 @@
                     </executions>
                 </plugin>
 
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-compiler-plugin</artifactId>
-                    <version>3.10.1</version>
-                    <configuration>
-                        <source>${java.version}</source>
-                        <target>${java.version}</target>
-                        <encoding>UTF-8</encoding>
-                        <compilerArgument>-parameters</compilerArgument>
-                    </configuration>
-                </plugin>
-
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-jar-plugin</artifactId>
-                    <version>3.2.2</version>
-                </plugin>
-
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-source-plugin</artifactId>
-                    <version>3.2.1</version>
-                    <executions>
-                        <execution>
-                            <phase>package</phase>
-                            <goals>
-                                <goal>jar-no-fork</goal>
-                            </goals>
-                        </execution>
-                    </executions>
-                </plugin>
-
                 <plugin>
                     <groupId>org.apache.maven.plugins</groupId>
                     <artifactId>maven-shade-plugin</artifactId>