### Define Versioning History

Source: https://github.com/dejvokep/boosted-yaml/blob/main/README.md

Example of how version IDs increment across file releases.

```yaml
config-version: 1   # 1st release
config-version: 2   # 2nd release
config-version: 3   # 3rd release
# etc.
```

--------------------------------

### Create a YamlDocument

Source: https://github.com/dejvokep/boosted-yaml/blob/main/README.md

Initializes a configuration file with default settings or custom key formats.

```java
YamlDocument config = YamlDocument.create(new File("config.yml"), getResource("config.yml"));
```

```java
YamlDocument config = YamlDocument.create(new File("config.yml"), getResource("config.yml"), GeneralSettings.builder().setKeyFormat(KeyFormat.OBJECT).build(), LoaderSettings.DEFAULT, DumperSettings.DEFAULT, UpdaterSettings.DEFAULT);
```

--------------------------------

### Create and Load YamlDocument

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Initialize configuration documents from files or input streams with optional custom settings for loading, dumping, and updating.

```java
import dev.dejvokep.boostedyaml.YamlDocument;
import dev.dejvokep.boostedyaml.settings.general.GeneralSettings;
import dev.dejvokep.boostedyaml.settings.loader.LoaderSettings;
import dev.dejvokep.boostedyaml.settings.dumper.DumperSettings;
import dev.dejvokep.boostedyaml.settings.updater.UpdaterSettings;
import java.io.File;
import java.io.IOException;

// Basic creation from file with defaults from resources
YamlDocument config = YamlDocument.create(
    new File("config.yml"),
    getClass().getResourceAsStream("/config.yml")
);

// Creation with custom settings
YamlDocument advancedConfig = YamlDocument.create(
    new File("config.yml"),
    getClass().getResourceAsStream("/config.yml"),
    GeneralSettings.builder()
        .setKeyFormat(GeneralSettings.KeyFormat.STRING)
        .setRouteSeparator('.')
        .build(),
    LoaderSettings.builder()
        .setAutoUpdate(true)
        .setCreateFileIfAbsent(true)
        .build(),
    DumperSettings.DEFAULT,
    UpdaterSettings.DEFAULT
);

// Creation without defaults
YamlDocument simpleConfig = YamlDocument.create(new File("data.yml"));
```

--------------------------------

### Configure General Document Settings

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Defines document behavior such as key formats, route separators, and default value suppliers. Supports both string-based and object-based key formats.

```java
import dev.dejvokep.boostedyaml.settings.general.GeneralSettings;
import dev.dejvokep.boostedyaml.settings.general.GeneralSettings.KeyFormat;

GeneralSettings settings = GeneralSettings.builder()
    // Key format: STRING (Spigot-compatible) or OBJECT (preserves types)
    .setKeyFormat(KeyFormat.STRING)

    // Route separator for string routes
    .setRouteSeparator('.')

    // Enable/disable use of defaults in getters
    .setUseDefaults(true)

    // Default values for getters
    .setDefaultObject(null)
    .setDefaultString(null)
    .setDefaultNumber(0)
    .setDefaultBoolean(false)
    .setDefaultChar(' ')

    // Custom collection suppliers
    .setDefaultList(ArrayList::new)
    .setDefaultSet(LinkedHashSet::new)
    .setDefaultMap(LinkedHashMap::new)

    .build();

// Usage with document creation
YamlDocument config = YamlDocument.create(
    new File("config.yml"),
    getClass().getResourceAsStream("/config.yml"),
    settings
);

// Using Route objects with OBJECT key format (supports non-string keys)
GeneralSettings objectKeySettings = GeneralSettings.builder()
    .setKeyFormat(KeyFormat.OBJECT)
    .build();

YamlDocument objectConfig = YamlDocument.create(
    new File("data.yml"),
    objectKeySettings
);
// Now can use integer keys: objectConfig.set(Route.from(1, "data"), "value");
```

--------------------------------

### Implement Document Versioning and Migrations

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Configures automatic updates for YAML files using versioning patterns and migration rules. Use this to handle relocations, value mapping, and custom logic during version transitions.

```java
import dev.dejvokep.boostedyaml.dvs.versioning.BasicVersioning;
import dev.dejvokep.boostedyaml.dvs.Pattern;
import dev.dejvokep.boostedyaml.dvs.segment.Segment;
import dev.dejvokep.boostedyaml.settings.updater.UpdaterSettings;
import dev.dejvokep.boostedyaml.settings.updater.MergeRule;

// config.yml content:
// config-version: 1
// old-setting: value

// Basic versioning (version ID at a specific route)
YamlDocument config = YamlDocument.create(
    new File("config.yml"),
    getClass().getResourceAsStream("/config.yml"),
    GeneralSettings.DEFAULT,
    LoaderSettings.builder().setAutoUpdate(true).build(),
    DumperSettings.DEFAULT,
    UpdaterSettings.builder()
        .setVersioning(new BasicVersioning("config-version"))
        .build()
);

// Advanced versioning with custom pattern (e.g., "1.2.3")
Pattern semverPattern = new Pattern(
    Segment.range(0, 99),  // Major
    Segment.literal("."),
    Segment.range(0, 99),  // Minor
    Segment.literal("."),
    Segment.range(0, 99)   // Patch
);

UpdaterSettings updaterSettings = UpdaterSettings.builder()
    .setVersioning(semverPattern, "version")
    .setAutoSave(true)
    .setEnableDowngrading(false)
    .setKeepAll(false)
    .setOptionSorting(UpdaterSettings.OptionSorting.SORT_BY_DEFAULTS)
    .setMergeRule(MergeRule.MAPPINGS, true) // Keep user's values
    // Add relocations when settings move between versions
    .addRelocation("2", Route.from("old", "path"), Route.from("new", "path"))
    .addRelocation("3", "legacy.setting", "modern.setting", '.')
    // Ignore routes that users can freely extend
    .addIgnoredRoute("2", Route.from("custom-items"))
    // Add value mappers for type conversions
    .addMapper("2", Route.from("mode"), previousValue -> {
        if (previousValue instanceof Boolean) {
            return (Boolean) previousValue ? "ENABLED" : "DISABLED";
        }
        return previousValue;
    })
    // Custom logic for complex migrations
    .addCustomLogic("3", document -> {
        if (document.contains("deprecated-section")) {
            document.remove("deprecated-section");
        }
    })
    .build();

// Manual update trigger
config.update(); // Updates against associated defaults
config.update(newDefaults); // Updates against provided stream
```

--------------------------------

### Initialize Document with Auto-Update

Source: https://github.com/dejvokep/boosted-yaml/blob/main/README.md

Configures the loader to automatically update the document based on the specified versioning settings.

```java
YamlDocument config = YamlDocument.create(new File("config.yml"), getResource("config.yml"), GeneralSettings.DEFAULT, LoaderSettings.builder().setAutoUpdate(true).build(), DumperSettings.DEFAULT, UpdaterSettings.builder().setVersioning(new BasicVersioning("config-version")).build());
```

--------------------------------

### Manage Configuration Routes

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Use Route objects to address nested configuration content, supporting both string-based and object-based keys.

```java
import dev.dejvokep.boostedyaml.route.Route;
import dev.dejvokep.boostedyaml.route.RouteFactory;

// Create routes from objects
Route serverRoute = Route.from("server", "settings", "name");
Route spawnRoute = Route.from("spawn");

// Create routes from strings (splits by separator)
Route databaseRoute = Route.fromString("database.connection.host");
Route customSeparator = Route.fromString("config/general/debug", '/');

// Using a RouteFactory for consistent separator
RouteFactory factory = new RouteFactory('/');
Route factoryRoute = factory.create("users/admin/permissions");

// Route manipulation
Route parentRoute = serverRoute.parent(); // ["server", "settings"]
Route childRoute = serverRoute.add("port"); // ["server", "settings", "name", "port"]
int length = serverRoute.length(); // 3
Object key = serverRoute.get(1); // "settings"

// Using routes with getters
String host = config.getString(Route.from("database", "host"));
int port = config.getInt(Route.from("database", "port"), 3306);

// Static utility for adding to nullable routes
Route extended = Route.addTo(null, "firstKey"); // Creates single-key route
Route appended = Route.addTo(existing, "newKey"); // Adds key to existing route
```

--------------------------------

### Configure LoaderSettings in Java

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Configure file loading behavior, including auto-update, file creation, and SnakeYAML Engine options. Use this to customize how YAML files are loaded into your application.

```java
import dev.dejvokep.boostedyaml.settings.loader.LoaderSettings;

LoaderSettings loaderSettings = LoaderSettings.builder()
    // Automatically create file if it doesn't exist
    .setCreateFileIfAbsent(true)

    // Automatically update after loading (requires defaults and versioning)
    .setAutoUpdate(true)

    // Error handling
    .setDetailedErrors(true)
    .setErrorLabel("ConfigLoader")

    // Allow duplicate keys (last wins)
    .setAllowDuplicateKeys(true)

    // Security: limit aliases to prevent billion laughs attack
    .setMaxCollectionAliases(50)

    // Document size limits
    .setCodePointLimit(3 * 1024 * 1024) // 3MB
    .setBufferSize(8192)

    .build();

// Usage
YamlDocument config = YamlDocument.create(
    new File("config.yml"),
    getClass().getResourceAsStream("/config.yml"),
    GeneralSettings.DEFAULT,
    loaderSettings,
    DumperSettings.DEFAULT,
    UpdaterSettings.DEFAULT
);
```

--------------------------------

### Read Configuration Values

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Retrieve values using type-safe getters, support for default values, Optional wrappers, and list handling.

```java
// Basic type getters with string routes
String serverName = config.getString("server.name");
int maxPlayers = config.getInt("server.max-players");
double spawnX = config.getDouble("spawn.x");
boolean debugMode = config.getBoolean("debug.enabled");
long timeout = config.getLong("connection.timeout");

// Getters with default values
String motd = config.getString("server.motd", "Welcome to the server!");
int port = config.getInt("server.port", 25565);
boolean pvp = config.getBoolean("game.pvp", true);

// Optional-based getters for null-safe access
Optional<String> optionalName = config.getOptionalString("player.name");
optionalName.ifPresent(name -> System.out.println("Player: " + name));

// Enum support
public enum GameMode { SURVIVAL, CREATIVE, ADVENTURE }
GameMode mode = config.getEnum("game.mode", GameMode.class, GameMode.SURVIVAL);

// List getters
List<String> worlds = config.getStringList("worlds");
List<Integer> allowedPorts = config.getIntList("network.ports");
List<Double> coordinates = config.getDoubleList("spawn.coords");

// Type checking
if (config.isSection("database")) {
    // Handle database configuration
}
if (config.isList("whitelist")) {
    // Handle whitelist
}
```

--------------------------------

### Modify Configuration Values and Structure

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Update, move, or remove configuration entries using string paths or Route objects.

```java
// Set values using string routes
config.set("server.name", "My Server");
config.set("server.port", 25565);
config.set("game.pvp", true);
config.set("spawn.coords", Arrays.asList(100.5, 64.0, -200.5));

// Set values using Route objects
config.set(Route.from("database", "host"), "localhost");
config.set(Route.from("database", "credentials", "username"), "admin");

// Set a map as a section
Map<String, Object> newData = new HashMap<>();
newData.put("enabled", true);
newData.put("interval", 300);
config.set("auto-save", newData);

// Move content from one route to another
config.move("old.path.to.value", "new.path.to.value");
config.move(Route.from("legacy", "setting"), Route.from("modern", "setting"));

// Remove entries
config.remove("deprecated.option");
config.remove(Route.from("temp", "data"));

// Check existence
boolean exists = config.contains("server.name");
boolean hasSection = config.contains(Route.from("database"));

// Clear a section
Section tempSection = config.getSection("temp");
if (tempSection != null) {
    tempSection.clear();
}
```

--------------------------------

### Add BoostedYAML Dependency using Gradle

Source: https://github.com/dejvokep/boosted-yaml/blob/main/README.md

Include this dependency in your Gradle project. Configure the shadowJar plugin for package relocation to avoid class loader conflicts.

```gradle
repositories {
   mavenCentral()
}

dependencies {
   implementation "dev.dejvokep:boosted-yaml:1.3.6"
}
```

```gradle
plugins {
  id 'com.gradleup.shadow' version '8.3.5'
  id 'java'
}
```

```gradle
// Relocating a Package
shadowJar {
   // The second string is where you will locate dev.dejvokep.boostedyaml
   relocate 'dev.dejvokep.boostedyaml', 'me.plugin.libs'
}
```

--------------------------------

### Save and Reload Documents

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Persist configuration changes to files or streams and reload data with optional custom loader settings.

```java
// Save to the associated file
boolean saved = config.save(); // Returns false if no file associated

// Save to a specific file
config.save(new File("backup-config.yml"));

// Save to an output stream
try (OutputStream os = new FileOutputStream("output.yml")) {
    config.save(os, StandardCharsets.UTF_8);
}

// Dump to string without saving
String yamlContent = config.dump();
System.out.println(yamlContent);

// Reload from associated file
boolean reloaded = config.reload(); // Returns false if no file associated

// Reload from input stream
try (InputStream is = new FileInputStream("external-config.yml")) {
    config.reload(is);
}

// Reload with custom loader settings
config.reload(inputStream, LoaderSettings.builder()
    .setAutoUpdate(false)
    .build());
```

--------------------------------

### Configure Updater Versioning

Source: https://github.com/dejvokep/boosted-yaml/blob/main/README.md

Defines the version ID route for the document to enable automatic updates.

```yaml
config-version: 1
```

```java
UpdaterSettings.builder().setVersioning(new BasicVersioning("config-version")).build();
```

--------------------------------

### Retrieve Data with Functional Getters

Source: https://github.com/dejvokep/boosted-yaml/blob/main/README.md

Uses functional method chaining to retrieve and process configuration values.

```java
Mode m = config.getStringOptional("mode").map(mode -> Mode.valueOf(mode.toUpperCase())).orElse(Mode.PERFORMANCE);
```

--------------------------------

### Custom Serialization with Type Adapters in Java

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Register custom type adapters for serializing and deserializing complex objects. This allows BoostedYAML to handle custom Java classes.

```java
import dev.dejvokep.boostedyaml.serialization.standard.StandardSerializer;
import dev.dejvokep.boostedyaml.serialization.standard.TypeAdapter;

// Define a custom class
public class Location {
    public final double x, y, z;
    public Location(double x, double y, double z) {
        this.x = x;
        this.y = y;
        this.z = z;
    }
}

// Create a type adapter
TypeAdapter<Location> locationAdapter = new TypeAdapter<Location>() {
    @Override
    public Map<Object, Object> serialize(Location location) {
        Map<Object, Object> map = new LinkedHashMap<>();
        map.put("x", location.x);
        map.put("y", location.y);
        map.put("z", location.z);
        return map;
    }

    @Override
    public Location deserialize(Map<Object, Object> map) {
        return new Location(
            ((Number) map.get("x")).doubleValue(),
            ((Number) map.get("y")).doubleValue(),
            ((Number) map.get("z")).doubleValue()
        );
    }

    @Override
    public Class<Location> getType() {
        return Location.class;
    }
};

// Register with a custom serializer
StandardSerializer serializer = StandardSerializer.builder()
    .add(locationAdapter)
    .build();

// Use in GeneralSettings
GeneralSettings settings = GeneralSettings.builder()
    .setSerializer(serializer)
    .build();

YamlDocument config = YamlDocument.create(
    new File("config.yml"),
    settings
);

// Now you can use custom objects
Location spawn = new Location(100.5, 64.0, -200.5);
config.set("spawn", serializer.serialize(spawn));
```

--------------------------------

### Access and Manipulate YAML Sections

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

Use Section objects to navigate hierarchical configuration data and iterate over keys or routes.

```java
import dev.dejvokep.boostedyaml.block.implementation.Section;

// Get a section
Section serverSection = config.getSection("server");
Section databaseSection = config.getSection("database.connection");

// Section properties
String name = serverSection.getNameAsString(); // "server"
Route route = serverSection.getRoute(); // Route to this section from root
Section parent = serverSection.getParent(); // Parent section or null if root
boolean isRoot = serverSection.isRoot(); // false

// Iterate over section keys
Set<Object> keys = serverSection.getKeys();
for (Object key : keys) {
    System.out.println("Key: " + key);
}

// Get all routes (deep iteration)
Set<Route> allRoutes = config.getRoutes(true); // true = deep
Set<String> allStringRoutes = config.getRoutesAsStrings(true);

// Get all values mapped to routes
Map<Route, Object> values = config.getRouteMappedValues(true);
Map<String, Object> stringValues = config.getStringRouteMappedValues(true);

// Create nested sections
Section newSection = config.createSection("new.nested.section");
newSection.set("option1", "value1");
newSection.set("option2", 42);

// Check if section is empty
boolean isEmpty = serverSection.isEmpty(true); // true = deep check
```

--------------------------------

### Reload and Save Document

Source: https://github.com/dejvokep/boosted-yaml/blob/main/README.md

Synchronizes the document state with the underlying file.

```java
config.reload();
config.save();
```

--------------------------------

### Add BoostedYAML Dependency using Maven

Source: https://github.com/dejvokep/boosted-yaml/blob/main/README.md

Add this dependency to your Maven project to include BoostedYAML. Ensure to configure the shade plugin for class loader conflict prevention.

```xml
<dependency>
  <groupId>dev.dejvokep</groupId>
  <artifactId>boosted-yaml</artifactId>
  <version>1.3.6</version>
</dependency>
```

```xml
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-shade-plugin</artifactId>
      <version>3.3.0</version>
      <configuration>
        <relocations>
          <relocation>
            <pattern>dev.dejvokep.boostedyaml</pattern>
            <!-- Replace this -->
            <shadedPattern>me.plugin.libs</shadedPattern>
          </relocation>
        </relocations>
      </configuration>
      <executions>
        <execution>
          <phase>package</phase>
          <goals>
            <goal>shade</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
```

--------------------------------

### Working with Comments in Java

Source: https://context7.com/dejvokep/boosted-yaml/llms.txt

BoostedYAML preserves YAML comments. Access and modify comments through the Block API. Comments are automatically preserved during loading and saving operations.

```java
import dev.dejvokep.boostedyaml.block.Block;
import dev.dejvokep.boostedyaml.block.Comments;

// Get block at a route
Block<?> block = config.getBlock("server.name");

// Access comments
Comments comments = block.getComments();

// Comments are automatically preserved when loading/saving
// The YAML structure including comments is maintained through the document lifecycle

// Example YAML with comments:
// # Server configuration
// server:
//   # The display name of the server
//   name: "My Server"  // inline comment
//   port: 25565

// After modifications and save, comments are preserved
config.set("server.name", "New Server Name");
config.save(); // Comments remain intact
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.