Transformations and Visitors

Transformations

There are several types of configuration transformations that currently exist. All are briefly described here, but more detail is available in the javadocs for the ConfigurationTransformation class. Construction and application of transformations are kept as separate phases to allow transformations to be treated like functions.

Single

This is the basis of the transformation system. A transformation is composed of a TransformationAction assigned to a path (that may contain wildcard values). Paths are sorted in natural ordering from shortest path to longest path.

Chained

The chained transformation takes several existing transformations and executes them in order. This can be used for more complex transformations where multiple phases are necessary.

Versioned

The versioned transformer is designed to make it simple to build versioned configurations. It accepts a key to get the current schema version at and a transformation for each version to make the required changes from the previous version.

Example

One of the examples provided with Configurate shows how to use transformations. Given an input file specified as a command-line parameter, this example will perform the written schema versions.

To visualize this, let's start out with our initial version:

serverVersion=1.15-1
section {
    red {
        prefix="happy"
    },
    green {
        prefix="grumpy"
    }
}

After applying the transformation initialTransform, the configuration will look like this:

server {
    version="1.15-1"
}
section {
    red {
        prefix="happy"
        new-value="i'm a default"
    },
    green {
        prefix="grumpy"
        new-value="i'm a default"
    }
}
version=0

Note the added version option. The base transformation of this example uses this key to know which transformations to apply to a configuration. The VersionedTransformation itself also will apply all transformations needed to bring a configuration file up to the latest version in one go, so the above version 0 configuration won't actually be output by the example as-is. What will be output is this final configuration, applying the zero to one transformation:

server {
    version="1.15_1"
}
section {
    red {
        prefix="happy"
        new-value="i'm a default"
    },
    green {
        prefix="grumpy"
        new-value="i'm a default"
    }
}
version=1

This transformation made smaller changes -- note the change in value at ["server", "version"] and the updated version value. This is just the tip of the iceberg -- a more complicated configuration can use these components to completely change the layout of a configuration file. For example, PermissionsEx uses this system to manage its permissions storage files. We hope to see you using these tools to make configuration wipes a thing of the past!

Visitors

While transformations allow precise modifications at specific points in the configuration tree, visitors make it easy to work with an entire configuration tree. Just implement the ConfigurationVisitor interface or any of its sub-interfaces, and with ConfigurationNode.visit(), you're off. This is the same system that the Gson loader uses to write configuration nodes to files, and that Sponge uses to remove any redundant values from its hierarchical configuration system.