{"id":28395125,"url":"https://github.com/townyadvanced/commentedconfiguration","last_synced_at":"2025-10-07T11:07:57.895Z","repository":{"id":88055008,"uuid":"600108057","full_name":"TownyAdvanced/CommentedConfiguration","owner":"TownyAdvanced","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-15T18:06:26.000Z","size":47,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-01T06:52:19.133Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TownyAdvanced.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-10T15:49:43.000Z","updated_at":"2024-10-15T18:05:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"df6be3f7-e8c5-4559-a13e-6cfcf162e603","html_url":"https://github.com/TownyAdvanced/CommentedConfiguration","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/TownyAdvanced/CommentedConfiguration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TownyAdvanced%2FCommentedConfiguration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TownyAdvanced%2FCommentedConfiguration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TownyAdvanced%2FCommentedConfiguration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TownyAdvanced%2FCommentedConfiguration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TownyAdvanced","download_url":"https://codeload.github.com/TownyAdvanced/CommentedConfiguration/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TownyAdvanced%2FCommentedConfiguration/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262172563,"owners_count":23270044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-31T19:39:12.246Z","updated_at":"2025-10-07T11:07:57.889Z","avatar_url":"https://github.com/TownyAdvanced.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CommentedConfiguration\n\nA yaml configuration system that supports comments, automatic editing of existing config comments, automatic adding of new config nodes.\n\n## Importing CommentedConfiguration into your project\n\nMaven:\n```\n  \u003crepositories\u003e\n    \u003crepository\u003e\n      \u003cid\u003eglaremasters repo\u003c/id\u003e\n      \u003curl\u003ehttps://repo.glaremasters.me/repository/towny/\u003c/url\u003e\n    \u003c/repository\u003e\n  \u003c/repositories\u003e\n```\n\n```\n  \u003cdependency\u003e\n    \u003cgroupId\u003eio.github.townyadvanced.commentedconfiguration\u003c/groupId\u003e\n    \u003cartifactId\u003eCommentedConfiguration\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.2\u003c/version\u003e\n  \u003c/dependency\u003e\n```\n\nGradle:\n\n```\nrepositories {\n    maven {\n        name = 'glaremasters repo'\n        url = 'https://repo.glaremasters.me/repository/towny/'\n    }\n\ndependencies {\n    compileOnly 'io.github.townyadvanced.commentedconfiguration:CommentedConfiguration:1.0.2'\n}\n```\n\n\n## Usage\n\nCommentedConfiguration can be used via the included Settings class, or using your own settings-replacement similar to what Towny uses: [settings](https://github.com/TownyAdvanced/Towny/blob/master/src/com/palmergames/bukkit/towny/TownySettings.java), [enum](https://github.com/TownyAdvanced/Towny/blob/master/src/com/palmergames/bukkit/config/ConfigNodes.java).\n\nTo use the Settings you need to provide three things:\n- A path where your file will be saved.\n- A Logger or Plugin instance for CommentedConfiguration to use when it needs to log information. \n- A List of CommentedNodes which will be used to create your config.\n\nExample [Nodes Class](https://github.com/TownyAdvanced/CommentedConfiguration/blob/main/src/test/java/io/github/townyadvanced/commentedconfiguration/TestNodes.java) from which the Settings examples below grabs the CommentedNodes list using #getAllNodes.\n\nThe included Settings class comes with the following constructors:\nhttps://github.com/TownyAdvanced/CommentedConfiguration/blob/7c1122ae3e9edcd4bd61b4e1b4f9d21a3268917e/src/main/java/io/github/townyadvanced/commentedconfiguration/setting/Settings.java#L22-L46\n\nExample initialization in your plugin Settings class:\n```java\nprivate final File configFile = new File(\"path/to/config.yml\"); // The destination you want your config.yml saved to.\nprivate Settings settings;\n\n// Settings initialized with a supplied logger \u0026 a list of CommentedNodes.\nsettings = new Settings(configFile.toPath(), Logger.getLogger(\"YourLoggerNameHere\"), TestNodes.getAllNodes());\n\n// Settings initialized with a supplied plugin \u0026 a list of CommentedNodes.\nsettings = new Settings(configFile.toPath(), yourPluginInstance, TestNodes.getAllNodes());\n```\n\nAfter which, you can load and then save your file to the server using:\n```java\nsettings.load();\nsettings.save();\n```\n\nFrom that point you can get your config file's values using the following methods, opting to use generic or typed lookups:\nhttps://github.com/TownyAdvanced/CommentedConfiguration/blob/7c1122ae3e9edcd4bd61b4e1b4f9d21a3268917e/src/main/java/io/github/townyadvanced/commentedconfiguration/setting/Settings.java#L108-L139\n\nYou can also save settings back to the config using the following methods, just remember to save your settings field afterwards using settings.save();\nhttps://github.com/TownyAdvanced/CommentedConfiguration/blob/7c1122ae3e9edcd4bd61b4e1b4f9d21a3268917e/src/main/java/io/github/townyadvanced/commentedconfiguration/setting/Settings.java#L141-L160\n\n### Further example\n\n\u003cdetails\u003e\u003csummary\u003eClick to view\u003c/summary\u003e\n\nMain\n```java\npackage org.example;\n\nimport java.nio.file.Path;\nimport java.util.Arrays;\nimport java.util.logging.Logger;\n\nimport io.github.townyadvanced.commentedconfiguration.setting.Settings;\n\npublic class Main {\n    public static void main(String[] args) {\n        final Path file = Path.of(\"/home/ben10/Desktop/config.yml\");\n        final Settings settings = new Settings(file, Logger.getLogger(\"TEST\"), TestNodes.getAllNodes());\n        if (!settings.load()) {\n            System.out.println(\"Failed to load config\");\n            return;\n        }\n        System.out.println(\"Loaded config\");\n        System.out.println(settings.get(TestNodes.BOOLEAN_NODE));\n        System.out.println(settings.get(TestNodes.STRING_NODE));\n        System.out.println(settings.get(TestNodes.LOCATION_NODE));\n        settings.save();\n        System.out.println(\"Saved config\");\n\n        final Path enumFile = Path.of(\"/home/ben10/Desktop/enumconfig.yml\");\n        final Settings enumSettings = new Settings(enumFile, Logger.getLogger(\"ENUMTEST\"), Arrays.asList(TestEnumNodes.values()));\n        if (!enumSettings.load()) {\n            System.out.println(\"Failed to load enumconfig\");\n            return;\n        }\n        System.out.println(\"Loaded enumconfig\");\n        System.out.println(enumSettings.get(TestEnumNodes.TEST_BOOLEAN));\n        System.out.println(enumSettings.get(TestEnumNodes.TEST_STRING));\n        System.out.println(enumSettings.get(TestEnumNodes.TEST_LOCATION));\n        enumSettings.save();\n        System.out.println(\"Saved enumconfig\");\n    }\n}\n```\n\nTestEnumNodes\n```java\npackage org.example;\n\nimport io.github.townyadvanced.commentedconfiguration.setting.ValueNode;\nimport org.bukkit.Location;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\npublic enum TestEnumNodes implements ValueNode {\n    TEST_BOOLEAN(\n            \"test.boolean\",\n            true,\n            new String[] {\"# This is a test boolean.\", \"# It is true by default.\"}\n    ),\n    TEST_STRING(\n            \"test.string\",\n            \"Hello, world!\",\n            new String[] {\"# This is a test string.\", \"# It is \\\"Hello, world!\\\" by default.\"}\n    ),\n    TEST_LOCATION(\n            \"test.location\",\n            new Location(null, 0, 0, 0),\n            new String[] {\"# This is a test location.\", \"# It is (0, 0, 0) by default.\"}\n    ),\n    ;\n\n    private final String path;\n    private final Object defaultValue;\n    private final String[] comments;\n\n    TestEnumNodes(String path, Object defaultValue, String[] comments) {\n        this.path = path;\n        this.defaultValue = defaultValue;\n        this.comments = comments;\n    }\n\n    @Override\n    public @NotNull String getPath() {\n        return path;\n    }\n\n    @Override\n    public @Nullable Object getDefaultValue() {\n        return defaultValue;\n    }\n\n    @Override\n    public @NotNull String[] getComments() {\n        return comments;\n    }\n}\n```\n\nTestNodes\n```java\npackage org.example;\n\nimport java.util.ArrayList;\nimport java.util.List;\n\nimport io.github.townyadvanced.commentedconfiguration.setting.CommentedNode;\nimport io.github.townyadvanced.commentedconfiguration.setting.SimpleNode;\nimport io.github.townyadvanced.commentedconfiguration.setting.TypedValueNode;\nimport org.bukkit.Location;\n\npublic class TestNodes {\n    private static final List\u003cCommentedNode\u003e nodes = new ArrayList\u003c\u003e();\n\n    private static \u003cT\u003e TypedValueNode\u003cT\u003e node(TypedValueNode\u003cT\u003e node) {\n        nodes.add(node);\n        return node;\n    }\n\n    public static final TypedValueNode\u003cBoolean\u003e BOOLEAN_NODE = node(SimpleNode.builder(\"test.boolean\", Boolean.class)\n            .defaultValue(true)\n            .comment(\"This is a boolean\")\n            .build());\n\n    public static final TypedValueNode\u003cString\u003e STRING_NODE = node(SimpleNode.builder(\"test.string\", String.class)\n            .defaultValue(\"default\")\n            .comment(\"This is a string\")\n            .build());\n\n    public static final TypedValueNode\u003cLocation\u003e LOCATION_NODE = node(SimpleNode.builder(\"test.location\", Location.class)\n            .defaultValue(new Location(null, 0, 0, 0))\n            .comment(\"This is a location\")\n            .build());\n\n    public static List\u003cCommentedNode\u003e getAllNodes() {\n        return nodes;\n    }\n}\n```\n\n\n\u003c/details\u003e\n\n## Converting Existing Configs To CommentedConfiguration\n\n@ipiepiepie has created a python script that will convert configuration files into CommentedConfigurations.\n\nIt is available on their [CommentedConfigurationMigrator repo](https://github.com/ipiepiepie/CommentedConfigurationMigrator), make sure you check it out if you aren't starting from scratch.\n  \n## History\n\nCommentedConfiguration goes *waaay back* to the original days of Bukkit plugins. Originally devised by [dumptruckman](https://github.com/dumptruckman) who used it in his [PluginBase](https://github.com/dumptruckman/PluginBase), it was [added into Towny](https://github.com/TownyAdvanced/Towny/commit/9de37765a69c92d9fe8ffe94cb62c5c7f250c6c5) in August of 2011. It was maintained over the years in the Towny codebase, receiving a number of updates that kept it working as Bukkit developed. Even after Bukkit's native yaml configuration [received the ability to handle comments in late 2021](https://hub.spigotmc.org/stash/projects/SPIGOT/repos/bukkit/commits/3e2dd2bc120754ea4db193e878050d0eb31a6894#src/main/java/org/bukkit/configuration/file/YamlConfiguration.java), the CommentedConfiguration system is still superior for its ability to update the config's existing comments as your plugin updates.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftownyadvanced%2Fcommentedconfiguration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftownyadvanced%2Fcommentedconfiguration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftownyadvanced%2Fcommentedconfiguration/lists"}