### LightningFile Example Structure

Source: https://github.com/simplix-softworks/simplixstorage/wiki/LightningFile

An example demonstrating nested blocks, lists, and comments in LightningFile.

```LightningFile
# This is an example file
here is {
    a nested {
        key = value
        list = [value1, value2]
        another list = [
            - another value1
            - another value2
        ]
    }
}
```

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

### Using Path Prefixes in Yaml

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Demonstrates how to use path prefixes to simplify setting and getting values in nested YAML structures, reducing redundancy. Prefixes can be changed or cleared to access different sections or the root.

```java
import de.leonhard.storage.Yaml;

Yaml yaml = new Yaml("locations", "data");

// Without path prefix (verbose)
yaml.set("spawn.world", "world");
yaml.set("spawn.x", 100.5);
yaml.set("spawn.y", 64.0);
yaml.set("spawn.z", -200.5);
yaml.set("spawn.yaw", 90.0f);
yaml.set("spawn.pitch", 0.0f);

// With path prefix (cleaner)
yaml.setPathPrefix("spawn");
yaml.set("world", "world");
yaml.set("x", 100.5);
yaml.set("y", 64.0);
yaml.set("z", -200.5);
yaml.set("yaw", 90.0f);
yaml.set("pitch", 0.0f);

// Reading with prefix
double x = yaml.getDouble("x");  // Actually reads "spawn.x"
double y = yaml.getDouble("y");  // Actually reads "spawn.y"
double z = yaml.getDouble("z");  // Actually reads "spawn.z"

// Change prefix for different section
yaml.setPathPrefix("warp.home");
yaml.set("world", "world_nether");
yaml.set("x", 50.0);
yaml.set("y", 100.0);
yaml.set("z", 50.0);

// Clear prefix to access root level again
yaml.clearPathPrefix();
String spawnWorld = yaml.getString("spawn.world"); // Full path required again
```

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

### Basic Get and Set Operations in Yaml

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Use intuitive methods for setting and getting values with automatic type conversion. Handles missing keys by returning default values specific to the getter type.

```java
import de.leonhard.storage.Yaml;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;

Yaml yaml = new Yaml("config", "data");

// Set values
yaml.set("server.name", "MyServer");
yaml.set("server.port", 25565);
yaml.set("server.enabled", true);
yaml.set("server.maxPlayers", 100);
yaml.set("server.tickRate", 20.0);

// Get values with automatic defaults
Object raw = yaml.get("server.name");           // Returns Object or null
String name = yaml.getString("server.name");     // Returns "MyServer" or "" if missing
int port = yaml.getInt("server.port");           // Returns 25565 or 0 if missing
boolean enabled = yaml.getBoolean("server.enabled"); // Returns true or false if missing
double tickRate = yaml.getDouble("server.tickRate"); // Returns 20.0 or 0.0 if missing
long maxMem = yaml.getLong("server.maxMemory");  // Returns 0L if missing
float ratio = yaml.getFloat("server.ratio");      // Returns 0.0f if missing
byte level = yaml.getByte("server.level");        // Returns 0 if missing

// Check if key exists
boolean hasName = yaml.contains("server.name");  // Returns true

// Remove keys
yaml.remove("server.deprecated");
yaml.removeAll("old.key1", "old.key2", "old.key3"); // Batch remove (writes once)

// Get all keys
Set<String> allKeys = yaml.keySet();             // All keys including nested
Set<String> topLevelKeys = yaml.singleLayerKeySet(); // Only top-level keys
Set<String> serverKeys = yaml.singleLayerKeySet("server"); // Keys under "server"

// Clear all data
yaml.clear();
```

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

### Get Values from FileType

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Usage

Shows how to retrieve values from a file using different getter methods. These methods provide type-specific retrieval and default values if the key is not found.

```java
Object anObject = yaml.get("Key"); // Default: null
String aString = yaml.getString("Key"); // Default: ""
int anInt = yaml.getInt("Key"); // Default: 0
double aDouble = yaml.getDouble("Key"); // Default: 0.0
float aFloat = yaml.getFloat("Key"); // Default: 0.0
long aLong = yaml.getLong("Key"); // Default: 0.0
List<String> aStringList = yaml.getStringList("Key");// Default: ArrayList<String>()
TimeUnit anEnum = yaml.getEnum("Key", TimeUnit.class);//Throws an LightningValidation / IllegalStateException
```

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

### Set Path Prefix for Keys

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Time-Saver

Use setPathPrefix to simplify key retrieval by setting a common prefix. Subsequent 'get' calls will use this prefix, reducing typing and improving readability.

```java
storage.setPathPrefix("spawn");
storage.get("x");
```

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

### Get Value or Default if Key Absent

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Time-Saver

Use getOrDefault to retrieve a value from a file, returning a specified default if the key is not found. This cleans up conditional logic.

```java
storage.getOrDefault("key", "default_value");
```

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

### Get, Set Default, or Return Existing Value

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Time-Saver

Use getOrSetDefault to retrieve a value, setting a default if the key is absent and returning the default in that case. If the key exists, its value is returned. This is useful for player data or multilingual messages.

```java
storage.getOrSetDefault("key", "default_value");
```

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

### Get File Information

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Retrieve file-related information such as the File object, file name, and full file path using methods like `getFile()`, `getName()`, and `getFilePath()`.

```java
// Get file information
File file = manual.getFile();
String name = manual.getName();           // "static-config.yml"
String path = manual.getFilePath();       // Full absolute path
```

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

### Advanced Getters for FileType

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Usage

Provides advanced methods for retrieving values, including returning an Optional for potentially missing keys or getting a value with a fallback default.

```java
Optional<String> optionalString = yaml.find("Key", String.class); // If a key is not present an empty optional will be returned
String getOrDefault = yaml.getOrDefault("Key", "Default-Value");
String getOrSetDefault = yaml.getOrSetDefault("Key", "Default-Value-To-Be-Set-If-Not-Yet-Present");
```

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

### Create File Instances with Constructors

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Instantiate YAML, JSON, TOML, or Config files directly using constructors. The library handles file creation if it doesn't exist. Supports creating from existing File objects and copy constructors.

```java
import de.leonhard.storage.Yaml;
import de.leonhard.storage.Json;
import de.leonhard.storage.Toml;
import de.leonhard.storage.Config;
import java.io.File;

// Create YAML file with name and path
Yaml yaml = new Yaml("settings", "data/configs");
// Creates: data/configs/settings.yml

// Create JSON file with name and path
Json json = new Json("playerdata", "data/players");
// Creates: data/players/playerdata.json

// Create TOML file with name and path
Toml toml = new Toml("server", "data/configs");
// Creates: data/configs/server.toml

// Create Config (YAML with comment preservation by default)
Config config = new Config("config", "plugins/myplugin");
// Creates: plugins/myplugin/config.yml

// Create from existing File object
File existingFile = new File("data/existing.yml");
Yaml yamlFromFile = new Yaml(existingFile);

// Copy constructor
Yaml yamlCopy = new Yaml(yaml);
```

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

### Instantiate FileTypes

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Usage

Demonstrates the various ways to instantiate FileTypes using internal constructors or the LightningBuilder. Constructors accept different combinations of file objects, names, paths, and input streams.

```java
new FILETYPE-HERE(FILE)
new FILETYPE-HERE(NAME, PATH)
new FILETYPE-HERE(FILETYPE) //Copy-constructor
new FILETYPE-HERE(NAME, PATH, INPUTSTREAM)
```

```java
Yaml yaml = new Yaml("Name", "Path");
Config config = new Config("Name", "Path"); //Special version of YAML
Json json = new Json("Name", "Path");
Toml toml = new Toml("Name", "Path");
```

```java
Config configUsingBuilder = SimplixBuilder
      .fromFile(FILE-HERE)
      .addInputStreamFromResource() //Optional
      .setDataType()
      .setReloadSettings()
      .createConfig(); // Building
```

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

### LightningFile Key-Value Pair Syntax

Source: https://github.com/simplix-softworks/simplixstorage/wiki/LightningFile

Define settings using a 'key = value' structure.

```LightningFile
key = value
```

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

### Configuring YAML Headers and Comments

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Illustrates how to set and manage YAML file headers, including custom comments and framed headers. It also shows how to control comment preservation for Yaml objects.

```java
import de.leonhard.storage.Yaml;
import de.leonhard.storage.Config;
import de.leonhard.storage.internal.settings.ConfigSettings;
import java.util.Arrays;
import java.util.List;

// Config preserves comments by default
Config config = new Config("config", "plugins/myplugin");

// Set simple header lines
config.setHeader("MyPlugin Configuration", "Version 1.0.0", "Do not edit manually!");
// Result:
// #MyPlugin Configuration
// #Version 1.0.0
// #Do not edit manually!

// Add additional header lines
config.addHeader("Last updated: 2024");

// Create a framed/boxed header
config.framedHeader("MyPlugin", "Configuration File", "v1.0.0");
// Result:
// # +----------------------------------------------------+ #
// # <                     MyPlugin                      > #
// # <                Configuration File                 > #
// # <                      v1.0.0                       > #
// # +----------------------------------------------------+ #

// Get current header
List<String> currentHeader = config.getHeader();

// For Yaml without comment preservation
Yaml yaml = new Yaml("data", "storage");
yaml.setConfigSettings(ConfigSettings.SKIP_COMMENTS); // Comments will be stripped

// For Yaml with comment preservation
yaml.setConfigSettings(ConfigSettings.PRESERVE_COMMENTS);
```

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

### Set Values in FileType

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Usage

Illustrates how to set or update values within a file. The `set` method unconditionally sets a value, while `setDefault` only sets it if the key does not already exist.

```java
yaml.set("Key", "Value");
yaml.setDefault("Key", "Default-Value"); // Will only be set if key is not yet present in file
```

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

### Advanced Configuration with SimplixBuilder

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Utilize SimplixBuilder for fluent configuration of file instances, including custom reload behavior, comment handling, and input streams. Supports building from paths or existing File objects, and creating various file types (Config, Yaml, Json, Toml).

```java
import de.leonhard.storage.SimplixBuilder;
import de.leonhard.storage.Config;
import de.leonhard.storage.Yaml;
import de.leonhard.storage.Json;
import de.leonhard.storage.Toml;
import de.leonhard.storage.internal.settings.ReloadSettings;
import de.leonhard.storage.internal.settings.ConfigSettings;
import de.leonhard.storage.internal.settings.DataType;
import java.io.File;

// Build a Config with all settings
Config config = SimplixBuilder
    .fromPath("config", "plugins/myplugin")
    .addInputStreamFromResource("default-config.yml")  // Load defaults from resources
    .setReloadSettings(ReloadSettings.INTELLIGENT)     // Reload only when file changes
    .setConfigSettings(ConfigSettings.PRESERVE_COMMENTS) // Keep comments in file
    .setDataType(DataType.SORTED)                      // Maintain key order
    .reloadCallback(flatFile -> {
        System.out.println("Config reloaded: " + flatFile.getName());
    })
    .createConfig();

// Build YAML file from existing File object
File dataFile = new File("data/settings.yml");
Yaml yaml = SimplixBuilder
    .fromFile(dataFile)
    .setReloadSettings(ReloadSettings.AUTOMATICALLY)
    .createYaml();

// Build JSON file with manual reload
Json json = SimplixBuilder
    .fromPath("cache", "data")
    .setReloadSettings(ReloadSettings.MANUALLY)
    .createJson();

// Build TOML file
Toml toml = SimplixBuilder
    .fromPath("server", "config")
    .setReloadSettings(ReloadSettings.INTELLIGENT)
    .createToml();
```

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

### Load Default Configurations from Resources

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Load default configuration values from bundled resource files within your JAR. This can be done using SimplixBuilder, or by adding defaults from an InputStream or another Yaml file.

```java
import de.leonhard.storage.Config;
import de.leonhard.storage.Yaml;
import de.leonhard.storage.SimplixBuilder;
import java.io.InputStream;

// Method 1: Using SimplixBuilder with resource
Config config = SimplixBuilder
    .fromPath("config", "plugins/myplugin")
    .addInputStreamFromResource("default-config.yml")  // Loads from JAR resources
    .createConfig();

// Method 2: Add defaults after creation
Yaml yaml = new Yaml("settings", "data");
yaml.addDefaultsFromInputStream();  // Uses previously set InputStream

// Method 3: Add defaults from specific InputStream
InputStream defaults = getClass().getResourceAsStream("/defaults.yml");
yaml.addDefaultsFromInputStream(defaults);

// Method 4: Add defaults from another file
Yaml defaultYaml = new Yaml("defaults", "resources");
yaml.addDefaultsFromFlatFile(defaultYaml);

// Method 5: Add defaults from a Map
Map<String, Object> defaultValues = new HashMap<>();
defaultValues.put("setting1", "default1");
defaultValues.put("setting2", 100);
defaultValues.put("nested.setting", true);
yaml.addDefaultsFromMap(defaultValues);
```

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

### IO Operations for FileType

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Usage

Demonstrates basic input/output operations for a FileType, such as retrieving the underlying File object, its name, or clearing its contents.

```java
File file = yaml.getFile();
String name = yaml.getName();
yaml.clear();
```

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

### Add JitPack Repository

Source: https://github.com/simplix-softworks/simplixstorage/wiki/How-to-setup

Include this XML snippet in your project's pom.xml to enable the JitPack repository.

```xml
<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>
```

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

### Add JitPack Repository

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Project-setup

Include this XML snippet in your project's repository section to enable the JitPack repository.

```xml
<!-- JitPack-Repo -->
<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>
```

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

### Working with File Sections in Yaml

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Shows how to use FlatFileSection to manage specific parts of a YAML configuration file, allowing for encapsulated access to nested data. Standard methods are available on these sections.

```java
import de.leonhard.storage.Yaml;
import de.leonhard.storage.sections.FlatFileSection;

Yaml config = new Yaml("config", "plugins/myplugin");

// Get a section for database settings
FlatFileSection dbSection = config.getSection("database");
dbSection.set("host", "localhost");
dbSection.set("port", 3306);
dbSection.set("name", "myapp");

String host = dbSection.getString("host");
int port = dbSection.getInt("port");

// Get a section for server settings
FlatFileSection serverSection = config.getSection("server");
serverSection.set("name", "MyServer");
serverSection.set("maxPlayers", 100);
serverSection.setDefault("motd", "Welcome to the server!");

// Nested sections work too
FlatFileSection spawnSection = config.getSection("locations.spawn");
spawnSection.set("x", 0);
spawnSection.set("y", 64);
spawnSection.set("z", 0);

// All standard methods available on sections
boolean hasHost = dbSection.contains("host");
String motd = serverSection.getOrDefault("motd", "Default MOTD");
```

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

### LightningFile List Syntax (Multi-line)

Source: https://github.com/simplix-softworks/simplixstorage/wiki/LightningFile

Define lists with each item prefixed by '-' on a new line, enclosed in square brackets '[]'.

```LightningFile
list = [
    - key1
    - key2
]
```

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

### Configure Maven Shade Plugin

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Project-setup

Configure the Maven Shade Plugin to shade the library into your final JAR. Relocation is recommended to avoid package conflicts. Ensure 'yourpackage.yourname' is replaced with your actual package name.

```xml
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.1.0</version>
  <executions>
    <execution>
    <phase>package</phase>
    <goals>
      <goal>shade</goal>
    </goals>
    </execution>
  </executions>
  <configuration>
    <createDependencyReducedPom>false</createDependencyReducedPom>
    <relocations>
      <relocation>
        <pattern>de.leonhard.storage</pattern>
        <shadedPattern>yourpackage.yourname.storage</shadedPattern>
      </relocation>
    </relocations>
  </configuration>
</plugin>
```

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

### Implement Reload Callback

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Define a callback function that executes whenever a file is reloaded. This is useful for re-applying runtime states or performing actions after a configuration update.

```java
// Reload callback for any file type
Yaml withCallback = SimplixBuilder
    .fromPath("monitored", "data")
    .setReloadSettings(ReloadSettings.INTELLIGENT)
    .reloadCallback(flatFile -> {
        System.out.println("File " + flatFile.getName() + " was reloaded!");
        // Re-apply any runtime state that depends on config
    })
    .createYaml();
```

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

### Annotation-Based Configuration Mapping

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Use annotations to automatically map configuration values to class fields. This simplifies loading configuration into objects, supporting nested paths and section prefixes.

```java
import de.leonhard.storage.Yaml;
import de.leonhard.storage.annotation.ConfigPath;

// Define a configuration class with annotated fields
public class ServerConfig {
    @ConfigPath("server.name")
    public String serverName;

    @ConfigPath("server.port")
    public int port;

    @ConfigPath("server.maxPlayers")
    public int maxPlayers;

    @ConfigPath("debug.enabled")
    public boolean debugEnabled;
}

// Usage
Yaml yaml = new Yaml("config", "data");
yaml.set("server.name", "MyServer");
yaml.set("server.port", 25565);
yaml.set("server.maxPlayers", 100);
yaml.set("debug.enabled", false);

// Populate fields automatically
ServerConfig config = new ServerConfig();
yaml.annotateClass(config);

System.out.println(config.serverName);  // "MyServer"
System.out.println(config.port);         // 25565

// With a section prefix
public class DatabaseConfig {
    @ConfigPath("host")
    public String host;

    @ConfigPath("port")
    public int port;

    @ConfigPath("name")
    public String database;
}

yaml.set("database.host", "localhost");
yaml.set("database.port", 3306);
yaml.set("database.name", "myapp");

DatabaseConfig dbConfig = new DatabaseConfig();
yaml.annotateClass(dbConfig, "database");  // Prefixes all paths with "database."

System.out.println(dbConfig.host);  // "localhost"
```

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

### Configure Maven Shade Plugin for Relocation

Source: https://github.com/simplix-softworks/simplixstorage/wiki/How-to-setup

Configure the Maven shade plugin in your pom.xml to shade the library into your final JAR. Relocation is recommended to avoid package conflicts.

```xml
<plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-shade-plugin</artifactId>
     <version>3.2.1</version>
     <executions>
       <execution>
         <phase>package</phase>
         <goals>
           <goal>shade</goal>
         </goals>
       </execution>
   </executions>
     <configuration>
       <relocations>
         <relocation>
           <pattern>de.leonhard</pattern>
           <shadedPattern>yourpackage.yourname.storage</shadedPattern>
         </relocation>
       </relocations>
     <createDependencyReducedPom>false</createDependencyReducedPom>
   </configuration>
</plugin>
```

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

### Add LightningStorage Dependency

Source: https://github.com/simplix-softworks/simplixstorage/wiki/How-to-setup

Add this dependency to your pom.xml to include the LightningStorage library. Ensure you are using a compatible version.

```xml
<!-- LightningStorage by JavaFactoryDev and Zeanon-->
<dependency>
    <groupId>com.github.JavaFactoryDev</groupId>
    <artifactId>LightningStorage</artifactId>
    <version>3.0-Beta-1</version>
</dependency>
```

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

### LightningFile Comment Syntax

Source: https://github.com/simplix-softworks/simplixstorage/wiki/LightningFile

Use '#' to denote a comment. Comments must be on their own line.

```LightningFile
#This is a comment
```

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

### LightningFile List Syntax (Inline)

Source: https://github.com/simplix-softworks/simplixstorage/wiki/LightningFile

Define lists using square brackets '[]' with comma-separated values.

```LightningFile
list = [value1, value2, value3]
```

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

### Optimize Write Operations with Batching

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Batch multiple set, remove, or default operations before a single write to improve performance. Use FileData for bulk inserts and removeAll for batch removals. Efficiently retrieve multiple values using getAll.

```java
import de.leonhard.storage.Yaml;
import de.leonhard.storage.internal.FileData;

Yaml yaml = new Yaml("performance", "data");

// BAD: Multiple writes (file written 3 times)
yaml.set("key1", "value1");
yaml.set("key2", "value2");
yaml.set("key3", "value3");

// GOOD: Batch inserts with single write
FileData fileData = yaml.getFileData();
fileData.insert("key1", "value1");
fileData.insert("key2", "value2");
fileData.insert("key3", "value3");
yaml.write();  // Single write operation

// BAD: Multiple removes (file written 3 times)
yaml.remove("old1");
yaml.remove("old2");
yaml.remove("old3");

// GOOD: Batch remove (file written once)
yaml.removeAll("old1", "old2", "old3");

// GOOD: Get multiple values efficiently
List<Object> values = yaml.getAll("key1", "key2", "key3");

// Add defaults from another file (writes once)
yaml.addDefaultsFromFlatFile(anotherYaml);

// Add defaults from a map (writes once)
Map<String, Object> defaults = new HashMap<>();
defaults.put("default1", "value1");
defaults.put("default2", "value2");
yaml.addDefaultsFromMap(defaults);
```

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

### Optimizing YAML Insert Operations

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Performance-Saver

Use `getFileData().insert()` for multiple insertions to ensure the file is written to only once, improving efficiency compared to individual `set()` calls.

```java
Yaml yaml = new Yaml("Name", "Path");

// Bad
yaml.set("Key-1", "Value-1");
yaml.set("Key-2", "Value-2");
yaml.set("Key-3", "Value-3");
// Good
yaml.getFileData().insert("Key-1", "Value-1");
yaml.getFileData().insert("Key-2", "Value-2");
yaml.set("Key-3", "Value-3");
// Benefit: File will only be written to once.
```

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

### Configure Automatic Reload Settings

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Configure the reload strategy to AUTOMATICALLY, which reloads the file on every access. This ensures the data is always up-to-date but may incur a performance overhead.

```java
// AUTOMATICALLY reload - reloads on every access (slower but always fresh)
Yaml automatic = SimplixBuilder
    .fromPath("live-data", "data")
    .setReloadSettings(ReloadSettings.AUTOMATICALLY)
    .createYaml();
```

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

### Configure Intelligent Reload Settings

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Set the reload strategy to INTELLIGENT, which only reloads the file from disk when it has been modified. This is the default behavior and offers a balance between performance and data freshness.

```java
import de.leonhard.storage.Yaml;
import de.leonhard.storage.SimplixBuilder;
import de.leonhard.storage.internal.settings.ReloadSettings;
import java.io.File;

// INTELLIGENT reload - only reloads when file has changed (default)
Yaml intelligent = SimplixBuilder
    .fromPath("config", "data")
    .setReloadSettings(ReloadSettings.INTELLIGENT)
    .createYaml();
```

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

### Optimizing YAML Remove Operations

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Performance-Saver

Utilize `removeAll()` to remove multiple keys efficiently, as it writes to the file only once, unlike sequential `remove()` calls.

```java
// Bad
yaml.remove("Key-1");
yaml.remove("Key-2");
yaml.remove("Key-3");
// Good
yaml.removeAll("Key-1", "Key-2", "Key-3");
// Benefit: File will only be written to once.
```

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

### Configure Manual Reload Settings

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Set the reload strategy to MANUALLY, meaning the file is only reloaded when the `forceReload()` method is explicitly called. This is suitable for configuration files that rarely change.

```java
// MANUALLY reload - only reloads when you call forceReload()
Yaml manual = SimplixBuilder
    .fromPath("static-config", "data")
    .setReloadSettings(ReloadSettings.MANUALLY)
    .createYaml();
```

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

### Set Default Value if Key Absent

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Time-Saver

Use setDefault to set a value only if the file does not already contain the key. This can significantly reduce the amount of code needed for checks.

```java
storage.setDefault("key", "value");
```

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

### Add Gradle Dependency

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Project-setup

Add this Gradle dependency to your project's dependencies block. Replace 'VERSION' with the current version.

```groovy
dependencies {
    compile 'com.github.simplix-softworks:simplixstorage:VERSION'/* Replace me with the current version */
}
```

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

### Add Maven Dependency

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Project-setup

Add this Maven dependency to your project's dependency section. Remember to replace 'VERSION' with the current version.

```xml
<dependency>
  <groupId>com.github.simplix-softworks</groupId>
  <artifactId>simplixstorage</artifactId>
  <version>VERSION <!-- Replace me with the current version --></version>
</dependency>
```

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

### Registering a Serializable Class

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Serializables

Register a custom class as serializable with LightningSerializer. Ensure all methods within the anonymous class are implemented according to your serialization needs.

```java
LightningSerializer.registerSerializable(new LightningSerializable<TypeHere>() {
      @Override
      // The object can for example be a map or a String. 
      public TypeHere deserialize(@NonNull Object obj) throws ClassCastException {
        // TODO: Implement this method for your needs
      }

      @Override
      public TypeHere serialize(@NonNull Object o) throws ClassCastException {
        // TODO: Implement this method for your needs
      }

      @Override
      public Class<TypeHere> getClazz() {
        // TODO: Implement this method for your needs
      }
    });
  }
```

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

### Working with Lists and Maps in Yaml

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Store and retrieve complex data structures like lists and maps. Supports parameterized getters for type-safe retrieval of lists and maps.

```java
import de.leonhard.storage.Yaml;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.HashMap;
import java.util.ArrayList;

Yaml yaml = new Yaml("data", "storage");

// Set lists
yaml.set("whitelist", Arrays.asList("player1", "player2", "player3"));
yaml.set("levels", Arrays.asList(1, 5, 10, 25, 50));
yaml.set("multipliers", Arrays.asList(1.0, 1.5, 2.0, 2.5));

// Get lists
List<String> whitelist = yaml.getStringList("whitelist");
List<Integer> levels = yaml.getIntegerList("levels");
List<Long> bigNumbers = yaml.getLongList("bigNumbers");
List<Byte> bytes = yaml.getByteList("bytes");
List<?> genericList = yaml.getList("whitelist");

// Parameterized list getter
List<String> players = yaml.getListParameterized("whitelist");

// Set nested maps
Map<String, Object> playerData = new HashMap<>();
playerData.put("name", "Steve");
playerData.put("level", 42);
playerData.put("balance", 1500.50);
playerData.put("achievements", Arrays.asList("first_kill", "explorer", "builder"));
yaml.set("players.steve", playerData);

// Get maps
Map<?, ?> retrieved = yaml.getMap("players.steve");
Map<String, Object> typedMap = yaml.getMapParameterized("players.steve");

// Add multiple values at once
Map<String, Object> defaults = new HashMap<>();
defaults.put("setting1", "value1");
defaults.put("setting2", 100);
defaults.put("setting3", true);
yaml.putAll(defaults);

// Get all data as map
Map<String, Object> allData = yaml.getData();

// Get multiple values at once
List<Object> values = yaml.getAll("setting1", "setting2", "setting3");
```

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

### Register Custom Serializer for PlayerStats

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Register a custom serializer for a custom class like PlayerStats to enable its storage and retrieval in data files. Ensure the serializer correctly handles deserialization from a Map and serialization to a Map.

```java
import de.leonhard.storage.Yaml;
import de.leonhard.storage.internal.serialize.SimplixSerializer;
import de.leonhard.storage.internal.serialize.SimplixSerializable;
import lombok.NonNull;
import java.util.HashMap;
import java.util.Map;
import java.util.List;

// Define a custom class
public class PlayerStats {
    public String name;
    public int level;
    public double balance;

    public PlayerStats(String name, int level, double balance) {
        this.name = name;
        this.level = level;
        this.balance = balance;
    }
}

// Register serializer for PlayerStats
SimplixSerializer.registerSerializable(new SimplixSerializable<PlayerStats>() {
    @Override
    public PlayerStats deserialize(@NonNull Object obj) throws ClassCastException {
        Map<String, Object> map = (Map<String, Object>) obj;
        return new PlayerStats(
            (String) map.get("name"),
            ((Number) map.get("level")).intValue(),
            ((Number) map.get("balance")).doubleValue()
        );
    }

    @Override
    public Object serialize(@NonNull PlayerStats stats) throws ClassCastException {
        Map<String, Object> map = new HashMap<>();
        map.put("name", stats.name);
        map.put("level", stats.level);
        map.put("balance", stats.balance);
        return map;
    }

    @Override
    public Class<PlayerStats> getClazz() {
        return PlayerStats.class;
    }
});
```

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

### LightningFile Block Syntax

Source: https://github.com/simplix-softworks/simplixstorage/wiki/LightningFile

Group related settings within curly braces '{}'. Indentation does not affect block structure.

```LightningFile
block {
    key = value
}
```

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

### Save and Load Custom Serializable Objects

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Use the registered custom serializer to save and load individual serializable objects and lists of objects to and from Yaml files. The `getSerializable` and `setSerializable` methods handle the conversion.

```java
// Use the serializer
Yaml yaml = new Yaml("players", "data");

// Save a PlayerStats object
PlayerStats steve = new PlayerStats("Steve", 42, 1500.50);
yaml.setSerializable("players.steve", steve);

// Load a PlayerStats object
PlayerStats loaded = yaml.getSerializable("players.steve", PlayerStats.class);
System.out.println(loaded.name + " - Level " + loaded.level);

// Save a list of serializable objects
yaml.set("topPlayers", Arrays.asList(
    new PlayerStats("Alex", 50, 5000.0),
    new PlayerStats("Steve", 42, 1500.0)
));

// Load a list of serializable objects
List<PlayerStats> topPlayers = yaml.getSerializableList("topPlayers", PlayerStats.class);
```

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

### Advanced Getters with Defaults in Json

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Handle missing values gracefully using default values or Optional returns. Use getOrSetDefault to set a value if it's missing and then return it.

```java
import de.leonhard.storage.Json;
import java.util.Optional;
import java.util.concurrent.TimeUnit;

Json json = new Json("settings", "data");

// Get with default value (doesn't modify file)
String host = json.getOrDefault("database.host", "localhost");
int timeout = json.getOrDefault("database.timeout", 5000);
boolean ssl = json.getOrDefault("database.ssl", true);

// Get or set default (sets value in file if missing, then returns it)
String dbName = json.getOrSetDefault("database.name", "myapp_db");
int poolSize = json.getOrSetDefault("database.pool.size", 10);
// If "database.name" didn't exist, it's now set to "myapp_db" in the file

// Set default only if key doesn't exist (doesn't return value)
json.setDefault("database.maxConnections", 100);
json.setDefault("database.minConnections", 5);

// Optional-based retrieval (returns empty Optional if key missing)
Optional<String> maybeUser = json.find("database.user", String.class);
Optional<Integer> maybePort = json.find("database.port", Integer.class);

maybeUser.ifPresent(user -> System.out.println("User: " + user));
int port = maybePort.orElse(3306);

// Get with explicit type
String value = json.get("some.key", "default");  // Type inferred from default

// Get enum values
json.set("timeUnit", "SECONDS");
TimeUnit unit = json.getEnum("timeUnit", TimeUnit.class); // Returns TimeUnit.SECONDS
```

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

### Retrieving a Serializable Object

Source: https://github.com/simplix-softworks/simplixstorage/wiki/Serializables

Retrieve a serializable object using its key and class type. This method is used after a class has been registered with the LightningSerializer.

```Java
getSerializable(KEY, CLASS)
```

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

### Force Reload and Check File Changes

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Manually trigger a file reload using `forceReload()` and check if the file has been modified since the last load using `hasChanged()`. This is typically used with the MANUALLY reload strategy.

```java
// Force reload the file data
manual.forceReload();

// Check if file has changed since last load
boolean changed = manual.hasChanged();
if (changed) {
    manual.forceReload();
}
```

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

### File Content Replacement

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Perform text replacement operations directly on file contents using the replace method. After replacement, force a reload to update the in-memory values.

```java
import de.leonhard.storage.Yaml;
import java.io.IOException;

Yaml yaml = new Yaml("template", "data");

// Set up template values
yaml.set("message", "Hello, {PLAYER}! Welcome to {SERVER}!");
yaml.set("broadcast", "Player {PLAYER} joined the game.");

// Replace placeholders in the entire file
try {
    yaml.replace("{PLAYER}", "Steve");
    yaml.replace("{SERVER}", "MyAwesomeServer");
} catch (IOException e) {
    e.printStackTrace();
}

// After replacement, file contains:
// message: "Hello, Steve! Welcome to MyAwesomeServer!"
// broadcast: "Player Steve joined the game."

// Force reload to get updated values in memory
yaml.forceReload();
String message = yaml.getString("message");
```

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

### Check if a Class is Serializable

Source: https://context7.com/simplix-softworks/simplixstorage/llms.txt

Verify if a specific class has a custom serializer registered with SimplixSerializer using the `isSerializable` method.

```java
// Check if a class has registered serializer
boolean canSerialize = SimplixSerializer.isSerializable(PlayerStats.class);
```

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