[1.1.0] Lots of improvements, create good documentation

- Broken TextParser tags in an safe and all categories,
- Gradients now work with Unicode Emojis
- Added TextParser.parseSafe(String) for simpler parsing of user input,
- Added multiple new aliases to tags,
- Added `style` and `raw` tags, which allow usage of json style and json text,
- Marked it as library in ModMenu,
- Added logo to mod (and replaced the old one)
- Created a documentation,

Author: Patbox

.github/workflows/docs.yml

@@ -0,0 +1,14 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.github/workflows/release.yml

@@ -41,3 +41,9 @@ jobs:
         with:
           files: 'build/libs/*.jar;!build/libs/*-sources.jar;!build/libs/*-dev.jar'
           repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

README.md

@@ -1,8 +1,9 @@
-# Fabric Placeholder API
+# About Placeholder API
 It's a small, jij-able API that allows creation and parsing placeholders within strings and Minecraft Text Components.
 Placeholders use simple format of `%modid:type%` or `%modid:type/data%`.
+It also includes simple, general usage text format indented for simplifying user input in configs/chats/etc.
 
-For list of currently available placeholders, check [wiki](https://github.com/Patbox/FabricPlaceholderAPI/wiki).
+For list of currently available placeholders, check [wiki](https://github.com/Patbox/TextPlaceholderAPI/wiki).
 
 ## Usage:
 Add it to your dependencies like this:
@@ -26,3 +27,5 @@ PlaceholderAPI.register(new Identifier("server", "name"), (ctx) -> PlaceholderRe
 If you want to parse placeholders, you need to use `PlaceholderAPI.parseString(String, MinecraftServer or ServerPlayerEntity)`
 for strings or `PlaceholderAPI.parseText(Text, MinecraftServer or ServerPlayerEntity)` for Vanilla Text Components.
 These function don't modify original one, instead they just return new String/Text.
+
+

docs/assets/logo.png

@@ -0,0 +1,3 @@
+.md-header__button.md-logo img, .md-header__button.md-logo svg {
+    width: auto;
+}

docs/assets/style.css

@@ -0,0 +1,54 @@
+# Adding placeholders
+Creation of new placeholders is simple. You just need to import `eu.pb4.placeholders.PlaceholderAPI` 
+and call static `register` method. You only need to provide 2 arguments:
+
+- Identifier with your mod id as namespace and path as argument name (with one additional limitation being not allowed to use `/` in it).
+- A function (in form of lambda for example) that takes PlaceholderContext and returns PlaceholderResult,
+
+Example
+```
+PlaceholderAPI.register(
+         new Identifier("example", "placeholder"),
+         (ctx) -> PlaceholderResult.value(new LiteralText("Hello World!"))
+);
+```
+
+## Using the context
+PlaceholderContext object passed to placeholder contains allows getting player (if exist), server and argument value.
+It also includes few methods for checking if they are present. 
+
+Here is example for player only placeholder
+```
+PlaceholderAPI.register(new Identifier("player", "displayname"), (ctx) -> {
+    if (ctx.hasPlayer()) {
+        return PlaceholderResult.value(ctx.getPlayer().getDisplayName());
+    } else {
+        return PlaceholderResult.invalid("No player!");
+    }
+});
+```
+
+And one for usage of argument
+```
+PlaceholderAPI.register(new Identifier("server", "name_from_uuid"), (ctx) -> {
+    if (ctx.hasArgument()) {
+        return PlaceholderResult.value(ctx.getServer().getUserCache().getByUuid(UUID.fromString(ctx.getArgument())).get().getName()));
+    } else {
+        return PlaceholderResult.invalid("No argument!");
+    }
+});
+```
+
+## Returning correct value
+Placeholders need to return instance of PlaceholderResult. It can be created by usage of provided static methods on this class.
+
+If it was successful:
+
+* `PlaceholderResult.value(Text text)` - Creates a value with text
+* `PlaceholderResult.value(String text)` - Creates a value from string, by parsing it with TextParser
+
+If it was invalid (no player or argument for example):
+
+* `PlaceholderResult.invalid()` - Creates simple invalid result
+* `PlaceholderResult.invalid(String reason)` - Creates invalid result with a reason, 
+  which is currently unused, but can be implemented by other parsers

docs/dev/adding-placeholders.md

@@ -0,0 +1,23 @@
+# Getting Started
+
+To begin, you need to add Nucleoid's maven to your build `build.gradle`.
+
+```groovy
+repositories {
+    // There might be other repos there too, just add it at the end
+    maven { url "https://maven.nucleoid.xyz/" }
+}
+```
+
+Then you just declare it as dependency!
+```groovy
+dependencies {
+    // You will have other dependencies here too
+    
+	modImplementation include("eu.pb4:placeholder-api:[VERSION]")
+}
+```
+This will also include it in yours mods, so users won't need to download it separately.
+
+You just need to replace `[VERSION]` with version you want to use (which should be usually the latest available).
+For list of version names, you can check [maven](https://maven.nucleoid.xyz/eu/pb4/placeholder-api/)

docs/dev/getting-started.md

@@ -0,0 +1,82 @@
+# Parsing placeholders
+There are few ways (and types) of placeholders you can parse with PlaceholderAPI. 
+So depending on your use case some of these will be more useful than others.
+
+## Parsing global placeholders
+Parsing global placeholders is really simple, as long as you have access to ServerPlayerEntity
+or MinecraftServer object. You just need to simply import `eu.pb4.placeholders.PlaceholderAPI` and call
+`parseText`. This method will return fully parsed Text, which can be displayed to the user.
+
+Example
+```
+// for ServerPlayerEntity
+Text message = PlaceholderAPI.parseText(textInput, player);
+
+// for Server
+Text message2 = PlaceholderAPI.parseText(textInput, server);
+```
+
+Placeholders itself will use default formatting of `%category:placeholder%`. 
+If you want to use other formatting for them (which is recommended), you can use
+`parseTextAlt(Text, ServerPlayerEntity or MinecraftServer)` for `{category:placeholder}`.
+
+## Parsing own/custom/predefined placeholders
+If you want to parse your own placeholders, you can do this in 2 ways.
+
+### Static placeholders
+To parse static placeholders you need to create a Map with `String` as a key and `Text` as a value.
+You also need a Pattern object (which can be taken from predefined ones). Then it's as simple as calling 
+a `parsePredefinedText` static method on `PlaceholderAPI` class.
+
+Example
+```
+ServerPlayerEntity player = something.getPlayer(); // MinecraftServer server = something.getServer()
+
+Text inputText = new LiteralText("Hello! ${player}");
+Map<String, Text> placeholders = Map.of("player", new LiteralText("You are a player!"));
+Pattern pattern = PlaceholderAPI.PREDEFINED_PLACEHOLDER_PATTERN;
+
+Text output = PlaceholderAPI.parsePredefinedText(inputText, pattern, placeholders);
+```
+
+### Dynamic placeholders
+In case where you want to parse placeholder with a context similar to global one, you need to
+create a Map with `Identifier` (with `/` being disallowed) as a key and `PlaceholderHandler` as a value (same as adding global ones).
+You also will need a pattern object, which is the same as with static ones.
+
+As opposite to global ones, you don't need to define namespace/category as it can default to minecraft one (for simpler user input).
+Then you just parse it with `parseTextCustom(Text, ServerPlayerEntity or MinecraftServer, Map<String, PlaceholderHandler>, Pattern)`.
+
+Example
+```
+ServerPlayerEntity player = something.getPlayer(); // MinecraftServer server = something.getServer()
+
+Text inputText = new LiteralText("Hello! ${player/blue}");
+Map<Identifier, Text> placeholders = Map.of(new Identifier("player"), 
+                                            (ctx) -> {
+                                                if (ctx.hasPlayer()) {
+                                                    return PlaceholderResult.value(new LiteralText("You are a player!")
+                                                                             .setStyle(Style.EMPTY.withColor(TextColor.parse(ctx.getArgument()))));
+                                                } else {
+                                                    return PlaceholderResult.value(new LiteralText("You are a server!")
+                                                                             .setStyle(Style.EMPTY.withColor(TextColor.parse(ctx.getArgument()))));
+                                                }
+                                            });
+Pattern pattern = PlaceholderAPI.PREDEFINED_PLACEHOLDER_PATTERN;
+
+Text output = PlaceholderAPI.parseTextCustom(inputText, player, pattern, placeholders);
+// Text output = PlaceholderAPI.parseTextCustom(inputText, server, pattern, placeholders);
+```
+
+### Preferred Patterns for static
+PlaceholderAPI has few Patterns you can use, which are accessible as static objects on `PlaceholderAPI` class.
+
+* `PREDEFINED_PLACEHOLDER_PATTERN` (`${placeholder}`) - works the best in most cases, doesn't collide with other ones.
+* `ALT_PLACEHOLDER_PATTERN_CUSTOM` (`{placeholder}`) - second best, but have more chance of colliding with user formatting.
+
+There are other ones, which usage is allowed, but they might work worse.
+
+* `PLACEHOLDER_PATTERN_CUSTOM` (`%placeholder%`) - is the same as default one, but doesn't require `:`.
+* `PLACEHOLDER_PATTERN` (`%category:placeholder%`) - used by default global placeholders (requires category).
+* `PLACEHOLDER_PATTERN_ALT` (`{category:placeholder}`) - used as alternative formatting for global ones (requires category).
+

docs/dev/parsing-placeholders.md

@@ -0,0 +1,30 @@
+# Using Simplified Text Format/TextParser
+[*You can read about format here!*](/user/text-format)
+
+Usage of TextParser is simple and really customisable. You just need to import `eu.pb4.placeholders.TextParser`
+and call static `parse` method for admin provided configs or `parseSafe` for player provided ones.
+They both take only one String argument and output a Text object.
+
+Example
+```
+String inputString = "<red>Hello <rb>World</rb>!"
+
+Text output = TextParser.parse(inputString); // Text output = TextParser.parseSafe(inputString);
+```
+
+## Parsing with only selected ones
+If you want to only use selected tags, you can simply get map of all with `TextParser.getRegisteredTags()` 
+or `TextParser.getRegisteredSafeTags()`. Then you can copy these to your own Map with String keys 
+and `TextParser.TextFormatterHandler` values. 
+Then you just use them with `TextParser.parse(String, Map<String, TextFormatterHandler>)`.
+
+Example
+```
+String inputString = "<red>Hello <blue>World</blue>!"
+
+Map<String, TextParser.TextFormatterHandler> tags = Map.of("red", TextParser.getRegisteredTags().get("red"),
+                                                        "blue", TextParser.getRegisteredTags().get("yellow") // renames works too!
+                                                    );
+
+Text output = TextParser.parse(inputString, tags);
+```

docs/dev/text-format.md

@@ -0,0 +1,27 @@
+# About Placeholder API
+It's a small, jij-able API that allows creation and parsing placeholders within strings and Minecraft Text Components.
+Placeholders use simple format of `%modid:type%` or `%modid:type/data%`.
+It also includes simple, general usage text format indented for simplifying user input in configs/chats/etc.
+
+## For users
+It allows users to configure multiple mods in similar way without losing compatibility between mods.
+Placeholders allow changing what and where any information is present within compatible mods.
+
+Additionally, Simplified Text Format allows to style them in readable way without requirement of writing JSON manually or using 
+generators.
+
+* [Using placeholders](user/general)
+* [Default placeholder list](user/default-placeholders)
+* [Mod placeholder list](user/mod-placeholders)
+* [Simplified Text Format](user/text-format)
+
+## For developers
+Usage of Placeholder API is a simple way to achieve good mod compatibility without having to implement
+multiple mod specific apis. Additionally, the placeholder parsing system can be used for replacing
+own static (or dynamic placeholders) in Text created by player or read from config. This with combination
+of Simplified Text Format allows creating great user/admin experience.
+
+* [Getting Started](dev/getting-started)
+* [Adding placeholders](dev/adding-placeholders)
+* [Parsing placeholders](dev/parsing-placeholders)
+* [Using Simplified Text Format/TextParser](dev/text-format)