DOCSEARCHbyAlgolia
Submit Docs

Configurate

repository·trunk·Indexed 19 days ago

https://github.com/spongepowered/configurate

A node-based configuration library for Java applications that provides a generic way to manipulate data across various formats, including JSON, HOCON, YAML, and XML. It features a modular architecture with a core API and specific loader modules, as well as extras for Kotlin, Google Guice, and Mojang's DataFixerUpper. The library includes a CLI tool for inspecting the internal data structures of configuration files.

Tokens
2.2K
Snippets
7
Records
15
Agent score
64%

What's inside Configurate

  1. Use Configurate Extras for library integrations

    trunk
    Configurate Extras provides specialized modules that bridge Configurate with other popular libraries. These modules allow you to leverage existing ecosystems (like dependency injection or specific data formats) while using Configurate's configuration management.

  2. Understand the Configurate module structure

    trunk

    Configurate is split into several modules to separate the core API from specific file format implementations and extra features:

    Core

    • configurate-core: The base library containing the main APIs for manipulating configurations. It is format-agnostic.

    Loaders

    Each loader module provides implementation for a specific format. You must include the module for the format you need:

    • configurate-gson: JSON format using Gson.
    • configurate-jackson: JSON format using Jackson.
    • configurate-hocon: HOCON format using lightbend config.
    • configurate-xml: XML format using JAXP.
    • configurate-yaml: YAML format using SnakeYAML.

    Extras

    Additional modules for specific integration needs:

    • configurate-extra-dfu[2-4]: Integration with Mojang's DataFixerUpper.
    • configurate-extra-kotlin: Kotlin extensions and support for Kotlin data classes in the object mapper.
    • configurate-extra-guice: Uses a Guice Injector to create object instances in the object mapper.

  4. Integrate with Mojang's DataFixerUpper

    trunk

    Configurate provides integration modules for Mojang's DataFixerUpper library to assist with data migration and versioning.

    Note that modules are version-specific:

    • Separate modules exist for DataFixerUpper versions 2, 4, and 7.
    • New features are only added to the module supporting the latest version.
    • Compatibility Note: The module for v4 is expected to be compatible with DataFixerUpper v5. The module for v7 is expected to be compatible with DataFixerUpper v8.

  6. Install Configurate via Gradle or Maven

    trunk

    To use Configurate, ensure your project is configured for Java 8 or higher. Configurate is modular: you must depend on configurate-core (usually pulled in transitively) and a specific loader module for the format you wish to use (e.g., HOCON, JSON, YAML).

    #### Gradle

```groovy
repositories {
    mavenCentral()
}

dependencies {
    // Modify this line to target the loader you wish to use.
    implementation 'org.spongepowered:configurate-hocon:4.2.0'
}

    Maven

    <dependencies>
    <dependency>
        <groupId>org.spongepowered</groupId>
        <!-- Modify this line to target the loader you wish to use. -->
        <artifactId>configurate-hocon</artifactId>
        <version>4.2.0</version>
    </dependency>
</dependencies>

  8. Use the Configurate CLI tool to inspect configuration files

    trunk

    The Configurate CLI tool is a utility designed to display the internal data structures of configuration files. It helps developers visualize how Configurate's nodes (including attributes, comments, and hierarchy) are parsed from various file formats.

    The tool supports several subcommands corresponding to different file formats: xml, yaml, json, and hocon.

    # Example: Inspecting a YAML file
# (Assuming the tool is compiled and available as 'configurate-tool')
./configurate-tool yaml path/to/config.yml

  11. Use ConfigurationNodeSerializer to copy ConfigurationNodes

    trunk

    The ConfigurationNodeSerializer is a specialized TypeSerializer designed to handle ConfigurationNode objects directly. It allows you to bypass the standard ObjectMapper when you need to work with nodes.

    Key Behaviors:

    • Deserialization: When deserializing a ConfigurationNode, it returns a copy of the provided node. Changes made to the resulting node will not affect the original source node.
    • Serialization: When serializing, it sets the provided object into the target node using node.set(obj).
    • Empty Values: If an empty value is required, it returns a new root BasicConfigurationNode using the provided ConfigurationOptions.
    // Note: This class is package-private in the source, but its behavior defines 
// how ConfigurationNodes are handled when used as types in serialization.

// Deserialization behavior:
ConfigurationNode newNode = serializer.deserialize(ConfigurationNode.class, originalNode);
// newNode is a copy; originalNode remains unchanged.

// Serialization behavior:
serializer.serialize(ConfigurationNode.class, myNode, targetNode);
// myNode is now set into targetNode.

  12. Inspect YAML configuration files

    trunk

    Use the yaml subcommand to display the structure of a YAML file. This subcommand treats nodes as CommentedConfigurationNode, allowing it to display comments associated with nodes.

    Arguments:

    • path: The location of the YAML file to read.

    Options:

    • --header-mode, --header-mode <MODE>: How to read a header from this file (uses HeaderMode enum). Defaults to PRESERVE.
    • -i, --indent <INT>: How much to indent when outputting. Defaults to 4.
    • -s, --style <STYLE>: What node style to use (uses NodeStyle enum).
    configurate-tool yaml path/to/file.yml --style BLOCK