dock: add README.md

README.md

@@ -0,0 +1,114 @@
+# RegistryLib
+A small library for a Minecraft Paper Plugins that allows loading and saving data in a datapack-like format.
+
+## Getting Started
+### Installation
+Available releases and installation instructions can be found on the [[https://repo.axolotsh.org/#/releases/io/github/axolotsh/registrylib | repository website]].
+
+#### Maven:
+Add following to your ```pom.xml```:
+```xml
+<repository>
+  <id>axolotsh-repository-releases</id>
+  <name>axolotsh-repository</name>
+  <url>https://repo.axolotsh.org/releases</url>
+</repository>
+
+<dependency>
+  <groupId>io.github.axolotsh</groupId>
+  <artifactId>registrylib</artifactId>
+  <version>VERSION</version>
+</dependency>
+```
+
+#### Gradle Groovy:
+Add following to your ```build.gradle```:
+```groovy
+maven {
+    name "axolotsh-repository"
+    url "https://repo.axolotsh.org/releases"
+}
+
+compileOnly "io.github.axolotsh:registrylib:VERSION"
+```
+
+#### Gradle Kotlin:
+Add following to your ```build.gradle.kts```:
+```kotlin
+maven {
+    name = "axolotsh-repository"
+    url = uri("https://repo.axolotsh.org/releases")
+}
+
+compileOnly("io.github.axolotsh:registrylib:VERSION")
+```
+
+### Creating a registry
+``Registry<>`` requires a class that implements the ``Keyed`` interface. This can be done as shown below:
+```java
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.Keyed;
+
+public class ItemInfo implements Keyed {
+    private transient Key key;
+    public Key key() {
+        return key;
+    }
+
+    private String name;
+    public String name() {
+        return name;
+    }
+
+    public ItemInfo(Key key, String name) {
+        this.key = key;
+        this.name = name;
+    }
+}
+```
+Note that the ``key`` variable is marked as transient. ``RegistryLoader`` sets this variable based on the file path. </p>
+Then you can create the registry as follows:
+```java
+import io.github.axolotsh.registrylib.Registry;
+
+public static final Registry<ItemInfo> ITEM_INFO_REGISTRY = new Registry<>("item", ItemInfo.class);
+```
+The first ``String`` argument, which in this example is ``"item"``, denotes the registry category, which divides the registry into different directories during serialization.
+Thus, an object with the key ``"myplugin:multitool"`` will be written to the file system at the path ``"myplugin/item/multitool.json"``.
+### Using a registry
+Managing objects in the registry is very similar to managing them in the list.
+```java
+var registry = ITEM_INFO_REGISTRY;
+
+var myItemKey = Key.key("multitool");
+var myItem = new ItemInfo(myItemKey, "<bold><red>MultiTool");
+
+registry
+    .clear()            // Clear all registry entries.
+    .add(myItem)        // Add entry to registry.
+    .remove(myItemKey); // Remove entry from registry by key.
+
+if (registry.contains(myItemKey))   // Checks if the registry contains a value with this key.
+    registry.remove(myItem);        // Remove specific item.
+
+// Accessing item form registry by key.
+// If it doesn't exist - create one and add it to registry.
+var item = registry.getOrAdd(myItemKey, () -> {
+    return myItem;
+});
+```
+### Saving and Loading a registry
+You can save and load registry to the file system with ``RegistryLoader``.
+```java
+var registryLoader = RegistryLoader.builder()
+    .logger(getPluginLogger())
+    .rootPath(getDataPath().resolve("data"))
+    .build();
+
+// Save registry
+registryLoader.saveAll(ITEM_INFO_REGISTRY);
+
+// Load registry
+ITEM_INFO_REGISTRY.clear();
+registryLoader.loadAll(ITEM_INFO_REGISTRY);
+```