SimpleMin Dokumentation

SimpleMin ist eine globale, modulare Konfigurationsbibliothek, die mit Erweiterbarkeit, Stabilität und Flexibilität entwickelt wurde. Mit SimpleMin kannst du Konfigurationsdateien mit einer eigenen, menschenlesbaren Syntax erstellen, laden und speichern.

Die Bibliothek bietet fortschrittliche Features wie benutzerdefinierte Type Handler, detaillierte Fehlerdiagnose, Schema-Validierung, immutable Konfigurationsobjekte, einen erweiterten Ausdrucksparser, Hot Reloading und eine Fluent API für den bequemen Code-basierten Aufbau von Konfigurationen.

Installation

Füge folgendes Repository zu deiner pom.xml hinzu:

/* === DOC START ===
Repository Definition für Maven. Dieses Repository liefert die beta-Version von SimpleMin.
=== DOC END === */
<repository>
  <id>syntaxjason-repo</id>
  <url>https://repo.syntaxjason.de/beta/</url>
</repository>

Und dann die folgende Dependency:

/* === DOC START ===
Dependency Definition für SimpleMin. Diese Version ist beta.1.
=== DOC END === */
<dependency>
  <groupId>de.syntaxjason</groupId>
  <artifactId>simplemin</artifactId>
  <version>beta.1</version>
</dependency>

Füge folgendes Repository zu deiner build.gradle hinzu:

/* === DOC START ===
Repository Definition für Gradle. Dieses Repository liefert die beta-Version von SimpleMin.
=== DOC END === */
repositories {
    maven {
        url "https://repo.syntaxjason.de/beta/"
    }
}

Und dann die folgende Dependency:

/* === DOC START ===
Dependency Definition für SimpleMin in Gradle.
=== DOC END === */
dependencies {
    implementation 'de.syntaxjason:simplemin:beta.1'
}

Features

Beispiele

SimpleMinDocument Beispiel

/* === DOC START ===
Dieses Beispiel zeigt, wie man ein SimpleMinDocument erstellt und konfiguriert.
Die onLoad() Methode wird überschrieben, um das root-Objekt zu setzen.
Die onSave() Methode ruft die Standard-Implementierung auf.
=== DOC END === */
SimpleMinDocument doc = new SimpleMinDocument("config.spm") {
    @Override
    protected void onLoad() throws IOException {
        // Setzt das root-Objekt auf ein leeres SimpleMinObject
        setRoot(new SimpleMinObject());
    }
    @Override
    protected void onSave() throws IOException {
        // Nutzt die Standardimplementierung zum atomaren Speichern
        super.onSave();
    }
};
doc.load();
doc.setVariable("global_var", new SimpleMinPrimitive("Hello World"));
doc.startHotReloading();
doc.save();

SimpleMinObject Beispiel

/* === DOC START ===
Erstellt ein SimpleMinObject und fügt einige Schlüssel-Wert-Paare hinzu.
=== DOC END === */
SimpleMinObject config = new SimpleMinObject();
config.put("server", new SimpleMinPrimitive("MyMinecraftServer"));
config.put("max_players", new SimpleMinPrimitive(100));

SimpleMinArray Beispiel

/* === DOC START ===
Erstellt ein SimpleMinArray und fügt zwei Elemente (Spielernamen) hinzu.
=== DOC END === */
SimpleMinArray players = new SimpleMinArray();
players.add(new SimpleMinPrimitive("Steve"));
players.add(new SimpleMinPrimitive("Alex"));

SimpleMinPrimitive Beispiel

/* === DOC START ===
Erstellt ein SimpleMinPrimitive mit einem numerischen Wert und gibt diesen aus.
=== DOC END === */
SimpleMinPrimitive coins = new SimpleMinPrimitive(100);
System.out.println(coins.getValue());

Fluent API Beispiel

/* === DOC START ===
Dieses Beispiel demonstriert die Verwendung der Fluent API, um ein verschachteltes Konfigurationsobjekt zu erstellen.
=== DOC END === */
SimpleMinObject config = SimpleMinBuilder.create()
    .add("host", "example.com")
    .add("port", 8080)
    .addObject("database", db -> db
        .add("username", "dbuser")
        .add("password", "secret")
        .add("timeout", 5000)
    )
    .addArray("servers", arr -> arr
        .add("server1")
        .add("server2")
        .addObject(obj -> obj
            .add("name", "server3")
            .add("ip", "192.168.1.3")
        )
    )
    .build();
System.out.println(config.serialize(0));

Erweiterung & Entwickler

Entwickler können SimpleMin einfach erweitern – ohne den Kerncode zu verändern. Nachfolgend sind Beispiele aufgeführt, die zeigen, wie zusätzliche Funktionalitäten integriert werden können.

Custom Type Handler / Converter Registry

/* === DOC START ===
Registriere einen benutzerdefinierten Converter für die Klasse Beispiel.
Mit diesem Converter kann ein Objekt der Klasse Beispiel aus einem SimpleMinValue erzeugt werden.
=== DOC END === */
SimpleMinConverterRegistry.registerConverter(Beispiel.class, new BeispielConverter());

/* === DOC START ===
Rufe den Converter ab und konvertiere ein SimpleMinValue in ein Beispiel-Objekt.
=== DOC END === */
SimpleMinConverter<Beispiel> converter = SimpleMinConverterRegistry.getConverter(Beispiel.class);
Beispiel obj = converter.fromSimpleMin(simpleMinValue);

Schema-Validierung & Merge


/* === DOC START ===
Dieses Beispiel demonstriert, wie ein Schema zur Validierung einer Konfiguration eingesetzt wird.
- SimpleMinSchema definiert erwartete Felder und deren Default-Werte.
- SimpleMinValidator.validate() prüft die Konfiguration.
- schema.toSimpleMinObject() erstellt ein Default-Objekt, welches per merge() mit der Benutzereingabe kombiniert wird.
=== DOC END === */
SimpleMinSchema schema = new SimpleMinSchema();
schema.addField(new SimpleMinField("host", String.class, true, new SimpleMinPrimitive("localhost")));
schema.addField(new SimpleMinField("port", Integer.class, true, new SimpleMinPrimitive(8080)));

// 'configObject' ist das vom Benutzer geladene SimpleMinObject
List errors = SimpleMinValidator.validate(configObject, schema);
if (!errors.isEmpty()) {
    errors.forEach(System.out::println);
} else {
    // Erstelle ein Default-Objekt basierend auf dem Schema
    SimpleMinObject defaults = schema.toSimpleMinObject();
    // Merge die Benutzereingabe in das Default-Objekt
    defaults.merge(configObject);
    // Das Ergebnis ist ein vollständiges, validiertes Konfigurationsobjekt
    configObject = defaults;
}

Immutable Objekte & Thread-Sicherheit

/* === DOC START ===
Konvertiert ein SimpleMinObject in ein unveränderliches, thread-sicheres Objekt.
=== DOC END === */
ImmutableSimpleMinObject immutableConfig = configObject.toImmutable();

Erweiterter Ausdrucksparser

/* === DOC START ===
Evaluiert einen komplexen arithmetischen Ausdruck mit Klammern und Operatoren.
=== DOC END === */
ExtendedExpressionEvaluator evaluator = new ExtendedExpressionEvaluator();
double result = evaluator.evaluate("10 + (5 * 2) - 3");

Fluent API / Builder Pattern

/* === DOC START ===
Erstellt ein verschachteltes Konfigurationsobjekt mithilfe der Fluent API.
=== DOC END === */
SimpleMinObject config = SimpleMinBuilder.create()
    .add("host", "example.com")
    .add("port", 8080)
    .addObject("database", db -> db
        .add("username", "dbuser")
        .add("password", "secret")
    )
    .addArray("servers", arr -> arr
        .add("server1")
        .add("server2")
    )
    .build();
System.out.println(config.serialize(0));

Weitere Anpassungen können durch das Überschreiben der onLoad() und onSave() Methoden in der SimpleMinDocument Klasse vorgenommen werden.

API Dokumentation

Interaktiver Playground

Experimentiere mit SimpleMin direkt im Browser: