From cd77639df5e902a107504ac8eff1571994746ec1 Mon Sep 17 00:00:00 2001 From: carm Date: Mon, 17 Feb 2025 18:37:16 +0800 Subject: [PATCH] docs: Add examples --- README.md | 80 ++++++++++++------- README_CN.md | 75 ++++++++++------- .../src/test/java/sample/SampleConfig.java | 3 + .../yaml/src/test/java/sample/SampleTest.java | 2 +- 4 files changed, 104 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index b705e5e..d6390f5 100644 --- a/README.md +++ b/README.md @@ -49,41 +49,58 @@ Check out all code demonstrations [HERE](demo/src/main/java/cc/carm/lib/configur For more examples, see the [Development Guide](.doc/README.md). ```java -@HeaderComment("Configurations for sample") -interface SampleConfig extends Configuration { +@ConfigPath(root = true) +@HeaderComments("Configurations for sample") +public interface SampleConfig extends Configuration { - @InlineComment("Enabled?") // Inline comment - ConfiguredValue ENABLED = ConfiguredValue.of(true); + @InlineComment("Enabled?") // Inline comment + ConfiguredValue ENABLED = ConfiguredValue.of(true); - ConfiguredList UUIDS = ConfiguredList.builderOf(UUID.class).fromString() - .parseValue(UUID::fromString).serializeValue(UUID::toString) - .defaults( - UUID.fromString("00000000-0000-0000-0000-000000000000"), - UUID.fromString("00000000-0000-0000-0000-000000000001") - ).build(); + @HeaderComments("Server configurations") // Header comment + ConfiguredValue PORT = ConfiguredValue.of(Integer.class); - interface INFO extends Configuration { - - @HeaderComment("Configure your name!") // Header comment - ConfiguredValue NAME = ConfiguredValue.of("Joker"); + @HeaderComments({"[ UUID >-----------------------------------", "A lot of UUIDs"}) + @FooterComments("[ UUID >-----------------------------------") + ConfiguredList UUIDS = ConfiguredList.builderOf(UUID.class).fromString() + .parse(UUID::fromString).serialize(UUID::toString) + .defaults( + UUID.fromString("00000000-0000-0000-0000-000000000000"), + UUID.fromString("00000000-0000-0000-0000-000000000001") + ).build(); + + @ConfigPath("info") // Custom path + interface INFO extends Configuration { + + @HeaderComments("Configure your name!") // Header comment + ConfiguredValue NAME = ConfiguredValue.of("Joker"); + + @ConfigPath("how-old-are-you") // Custom path + ConfiguredValue AGE = ConfiguredValue.of(24); + + } - @ConfigPath("year") // Custom path - ConfiguredValue AGE = ConfiguredValue.of(24); - - } } + ``` ```java public class Sample { public static void main(String[] args) { // 1. Make a configuration provider from a file. - ConfigurationProvider provider = EasyConfiguration.from("config.yml"); + ConfigurationHolder holder = YAMLConfigFactory.from("target/config.yml") + .resourcePath("configs/sample.yml") + .indent(4) // Optional: Set the indentation of the configuration file. + .build(); + // 2. Initialize the configuration classes or instances. - provider.initialize(SampleConfig.class); + holder.initialize(SampleConfig.class); // 3. Enjoy using the configuration! + System.out.println("Enabled? -> " + SampleConfig.ENABLED.resolve()); SampleConfig.ENABLED.set(false); - System.out.println("Your name is " + SampleConfig.INFO.NAME.getNotNull() + " !"); + System.out.println("And now? -> " + SampleConfig.ENABLED.resolve()); + // p.s. Changes not save so enable value will still be true in the next run. + + System.out.println("Your name is " + SampleConfig.INFO.NAME.resolve() + " (age=" + SampleConfig.INFO.AGE.resolve() + ")!"); } } @@ -92,16 +109,22 @@ public class Sample { ```yaml # Configurations for sample -enabled: true # Enabled? +enabled: true #Enabled? +# Server configurations +port: + +# [ UUID >----------------------------------- +# A lot of UUIDs uuids: - 00000000-0000-0000-0000-000000000000 - 00000000-0000-0000-0000-000000000001 +# [ UUID >----------------------------------- info: # Configure your name! name: Joker - year: 24 + how-old-are-you: 24 ``` ### Dependencies @@ -159,10 +182,10 @@ info: compile - + cc.carm.lib - easyconfiguration-json + easyconfiguration-gson [LATEST RELEASE] compile @@ -205,8 +228,8 @@ dependencies { // YAML file-based implementation, compatible with all Java environments. api "cc.carm.lib:easyconfiguration-yaml:[LATEST RELEASE]" - // JSON file-based implementation, compatible with all Java environments. Note: JSON does not support file comments. - api "cc.carm.lib:easyconfiguration-json:[LATEST RELEASE]" + // JSON file-based implementation, compatible with all Java environments. + api "cc.carm.lib:easyconfiguration-gson:[LATEST RELEASE]" } ``` @@ -220,7 +243,8 @@ dependencies { EasyConfiguration for MineCraft! Easily manage configurations on MineCraft-related server platforms. -Currently supports BungeeCord, Bukkit (Spigot) servers, with more platforms to be supported soon. +Currently, it supports BungeeCord, Velocity, Bukkit (Spigot) servers, +with more platforms to be supported soon. ## Support and Donation diff --git a/README_CN.md b/README_CN.md index 75951d0..0ef1c60 100644 --- a/README_CN.md +++ b/README_CN.md @@ -43,42 +43,57 @@ README LANGUAGES [ [English](README.md) | [**中文**](README_CN.md) ] 您可以 [点击这里](demo/src/main/java/cc/carm/lib/configuration/demo) 直接查看现有的代码演示，更多复杂情况演示详见 [开发介绍](.doc/README.md) 。 + ```java -@HeaderComment("Configurations for sample") -interface SampleConfig extends Configuration { +@ConfigPath(root = true) +@HeaderComments("Configurations for sample") +public interface SampleConfig extends Configuration { - @InlineComment("Enabled?") // 行内注释 - ConfiguredValue ENABLED = ConfiguredValue.of(true); + @InlineComment("Enabled?") // 行后注释 + ConfiguredValue ENABLED = ConfiguredValue.of(true); - ConfiguredList UUIDS = ConfiguredList.builderOf(UUID.class).fromString() - .parseValue(UUID::fromString).serializeValue(UUID::toString) - .defaults( - UUID.fromString("00000000-0000-0000-0000-000000000000"), - UUID.fromString("00000000-0000-0000-0000-000000000001") - ).build(); + @HeaderComments("Server configurations") // 头部注释 + ConfiguredValue PORT = ConfiguredValue.of(Integer.class); - interface INFO extends Configuration { - - @HeaderComment("Configure your name!") // 头部注释 - ConfiguredValue NAME = ConfiguredValue.of("Joker"); + @HeaderComments({"[ UUID >-----------------------------------", "A lot of UUIDs"}) + @FooterComments("[ UUID >-----------------------------------") + ConfiguredList UUIDS = ConfiguredList.builderOf(UUID.class).fromString() + .parse(UUID::fromString).serialize(UUID::toString) + .defaults( + UUID.fromString("00000000-0000-0000-0000-000000000000"), + UUID.fromString("00000000-0000-0000-0000-000000000001") + ).build(); + + interface INFO extends Configuration { + + @HeaderComments("Configure your name!") // Header comment + ConfiguredValue NAME = ConfiguredValue.of("Joker"); + + @ConfigPath("how-old-are-you") // 自定义路径 + ConfiguredValue AGE = ConfiguredValue.of(24); + + } - @ConfigPath("year") // 自定义配置路径，若不定义，则按照默认规则生成 - ConfiguredValue AGE = ConfiguredValue.of(24); - - } } + ``` ```java public class Sample { public static void main(String[] args) { - // 1. 生成一个 “Provider” 用于给配置类提供源配置的文件。 - ConfigurationProvider provider = EasyConfiguration.from("config.yml"); - // 2. 通过 “Provider” 初始化配置类或配置实例。 - provider.initialize(SampleConfig.class); + // 1. 生成一个 “holder” 用于给配置类提供源配置的文件。 + ConfigurationHolder holder = YAMLConfigFactory.from("target/config.yml") + .resourcePath("configs/sample.yml") + .indent(4) // Optional: Set the indentation of the configuration file. + .build(); + + // 2. 通过 “holder” 初始化配置类或配置实例。 + holder.initialize(SampleConfig.class); // 3. 现在可以享受快捷方便的配置文件使用方式了~ + System.out.println("Enabled? -> " + SampleConfig.ENABLED.resolve()); SampleConfig.ENABLED.set(false); - System.out.println("Your name is " + SampleConfig.INFO.NAME.getNotNull() + " !"); + System.out.println("And now? -> " + SampleConfig.ENABLED.resolve()); + // p.s. 在本示例里的更改未保存，因此启用值在下次运行中仍将为 true。 } } ``` @@ -86,16 +101,22 @@ public class Sample { ```yaml # Configurations for sample -enabled: true # Enabled? +enabled: true #Enabled? +# Server configurations +port: + +# [ UUID >----------------------------------- +# A lot of UUIDs uuids: - 00000000-0000-0000-0000-000000000000 - 00000000-0000-0000-0000-000000000001 +# [ UUID >----------------------------------- info: # Configure your name! name: Joker - year: 24 + how-old-are-you: 24 ``` ### 依赖方式 @@ -164,7 +185,7 @@ info: cc.carm.lib - easyconfiguration-json + easyconfiguration-gson [LATEST RELEASE] compile @@ -225,7 +246,7 @@ dependencies { //基于JSON文件的实现版本，可用于全部Java环境。 //需要注意的是，JSON不支持文件注释。 - api "cc.carm.lib:easyconfiguration-json:[LATEST RELEASE]" + api "cc.carm.lib:easyconfiguration-gson:[LATEST RELEASE]" api "cc.carm.lib:easyconfiguration-hocon:[LATEST RELEASE]" diff --git a/providers/yaml/src/test/java/sample/SampleConfig.java b/providers/yaml/src/test/java/sample/SampleConfig.java index 3cb9254..f1f4fde 100644 --- a/providers/yaml/src/test/java/sample/SampleConfig.java +++ b/providers/yaml/src/test/java/sample/SampleConfig.java @@ -2,6 +2,7 @@ package sample; import cc.carm.lib.configuration.Configuration; import cc.carm.lib.configuration.annotation.ConfigPath; +import cc.carm.lib.configuration.annotation.FooterComments; import cc.carm.lib.configuration.annotation.HeaderComments; import cc.carm.lib.configuration.annotation.InlineComment; import cc.carm.lib.configuration.value.standard.ConfiguredList; @@ -19,6 +20,8 @@ public interface SampleConfig extends Configuration { @HeaderComments("Server configurations") // Header comment ConfiguredValue PORT = ConfiguredValue.of(Integer.class); + @HeaderComments({"[ UUID >-----------------------------------", "A lot of UUIDs"}) + @FooterComments("[ UUID >-----------------------------------") ConfiguredList UUIDS = ConfiguredList.builderOf(UUID.class).fromString() .parse(UUID::fromString).serialize(UUID::toString) .defaults( diff --git a/providers/yaml/src/test/java/sample/SampleTest.java b/providers/yaml/src/test/java/sample/SampleTest.java index 2ddaaeb..259734a 100644 --- a/providers/yaml/src/test/java/sample/SampleTest.java +++ b/providers/yaml/src/test/java/sample/SampleTest.java @@ -11,7 +11,7 @@ public class SampleTest { // 1. Make a configuration provider from a file. ConfigurationHolder holder = YAMLConfigFactory.from("target/config.yml") .resourcePath("configs/sample.yml") - .indent(4) // Optional: Set the indentation of the configuration file. + .indent(2) // Optional: Set the indentation of the configuration file. .build(); // 2. Initialize the configuration classes or instances.