Created API-Flag (markdown)

API-Flag.md

@@ -0,0 +1,98 @@
+# The Flag API
+
+A plot flag is any property that can be assigned to a plot, that will
+alter its functionality in some way. Most of these are user assignable in-game,
+or via configuration files (for plot areas).
+
+To create a new flag, simply extend PlotFlag, or one of the default types:
+- BlockTypeListFlag: Holds WorldEdit BlockTypes
+- BooleanFlag
+- DoubleFlag
+- IntegerFlag
+- ListFlag
+- LongFlag
+- NonNegativeIntegerFlag
+- NumberFlag
+- TimedFlag
+
+Flags are essentially immutable value containers. The flag values must be able to be parsed from a string, and later on serialized into a string.
+
+## Creating a flag
+
+Each flag contains one immutable value. The type of this value is supplied as a generic
+parameter to the PlotFlag class, like such:
+```java
+import com.github.intellectualsites.plotsquared.plot.flags.FlagParseException;
+import com.github.intellectualsites.plotsquared.plot.flags.PlotFlag;
+
+public class YourFlag extends PlotFlag<YourValueType, YourFlag> {
+...
+}
+```
+
+The PlotFlag constructor requires three parameters:
+- The (non-null) immutable flag value
+- A flag category
+- A flag description
+
+The category and description should be a Caption (`com.github.intellectualsites.plotsquared.plot.config.Caption`).
+An instance of Caption can be created by using `com.github.intellectualsites.plotsquared.plot.config.StaticCaption`,
+or by using an existing value in the enum `com.github.intellectualsites.plotsquared.plot.config.Captions`.
+
+It is preferred if one of the values prefixed with `FLAG_CATEGORY_` in the Captions enum is used as the flag
+category, although this is not a requirement. 
+
+Your flag constructor should look something like this:
+
+```java
+public YourFlag(final YourValueType value) {
+  super(value, Captions.SOME_CATEGORY, Captions.SOME_DESCRIPTION);
+}
+```
+
+Your flag class needs to override the following methods:
+- `YourFlag parse(@NotNull String input) throws FlagParseException`,
+- `YourFlag merge(@NotNull YourValueType newValue)`,
+- `String toString()`: Returns the string serialization of the current value.
+- `String getExample()`: Returns an example argument.
+- `YourFlag flagOf(@NotNull YourValueType value)`: Returns a new instance of your flag.
+
+The `parse(String input)` method parses a string input, and returns a new flag instance.
+If the input is not valid, `FlagParseException` is thrown. It should look something like:
+
+```java
+@Override
+public YourFlag parse(@NotNull final String input) throws FlagParseException {
+  if (isValid(input)) {
+    YourValueType type = convertSomehow(input);
+    return flagOf(type);
+  }
+  throw new FlagParseException(this, input, someCaption);
+}
+```
+The caption is created in the same way as for the constructor. There are some pre-made
+error captions in the Captions enum, prefixed with `FLAG_ERROR_`. The FlagParseException takes
+in parameters that will replace the placeholder values in the caption (`%s`).  
+
+This method should **NEVER** return null. If the value cannot be parsed, thrown an 
+exception.
+
+The merge method allows you to merge two different flag instances, which allows users
+to use the `/plot flag add <flag> <value>` command on the flag. If merging isn't supported,
+simply return `flagOf(newValue)`.
+
+As the values are immutable, it is possible (and encouraged) to re-use flag instances. 
+
+For examples, see: https://github.com/IntellectualSites/PlotSquared/tree/flags_remake/Core/src/main/java/com/github/intellectualsites/plotsquared/plot/flags/implementations
+
+## Registering a flag
+
+All flags must be registered in the `GlobalFlagContainer`, or else they will not be usable in-game.
+Each flag will be applied to every plot, so it is necessary to pick appropriate default flag values.
+
+To register a flag, use:
+`com.github.intellectualsites.plotsquared.plot.flags.GlobalFlagContainer().getInstance().addFlag(flagInstance)`
+
+## Adding a flag to a plot
+
+To add a flag to a plot, use `plot.addFlag(flagInstance)`. If you need a new flag instance, and only have the flag type, it is possible to add a flag using `plot.addFlag(GlobalFlagContainer.getInstance().getFlag(flagInstance).createFlagInstance(flagValue))`