Add ColorString utility class

src/github/README.md

@@ -40,3 +40,4 @@ If you wish to use [SLF4J](http://slf4j.org) in your Bukkit plugin, or if your p
     + SLF4Bukkit supports only [Bukkit formatting markers](${project.url}/apidocs/info/ronjenkins/slf4bukkit/ColorMarker.html), which format the entire message and associated throwable (if any). All other markers are discarded. Bukkit formatting markers always override the default level-specific formatting defined in the plugin config.
     + In addition to using the Bukkit formatting markers, you can use Bukkit's `ChatColor` values to further format your message.
     + SLF4Bukkit issues `ChatColor.RESET` after every log message, so you don't have to worry about resetting after each message.
+    + You can use the [ColorString](${project.url}/apidocs/info/ronjenkins/slf4bukkit/ColorString.html) class to easily create colored log messages.

src/main/java/info/ronjenkins/slf4bukkit/ColorString.java

@@ -0,0 +1,315 @@
+/*
+ * Copyright (C) 2016 Ronald Jack Jenkins Jr.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package info.ronjenkins.slf4bukkit;
+
+/**
+ * A {@link StringBuilder}-like class with a fluent API for adding content
+ * colored via {@link ColorMarker}s. You may call {@link #toString()} to get the
+ * current value and then continue adding content to this object. This class is
+ * thread-safe.
+ *
+ * @author Ronald Jack Jenkins Jr.
+ */
+public final class ColorString {
+
+  private ColorMarker         currentColor = ColorMarker.NONE;
+  private final StringBuilder value        = new StringBuilder();
+
+  /** Constructor. */
+  public ColorString() {
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#AQUA}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void aqua(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.AQUA);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#BLACK}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void black(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.BLACK);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#BLUE}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void blue(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.BLUE);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#DARK_AQUA}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void darkAqua(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.DARK_AQUA);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#DARK_BLUE}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void darkBlue(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.DARK_BLUE);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#DARK_GRAY}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void darkGray(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.DARK_GRAY);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#DARK_GREEN}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void darkGreen(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.DARK_GREEN);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#DARK_RED}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void darkRed(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.DARK_RED);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#GOLD}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void gold(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.GOLD);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#GRAY}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void gray(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.GRAY);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#GREEN}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void green(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.GREEN);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Resets all formatting at the current position, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void none(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.NONE);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#LIGHT_PURPLE}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void pink(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.LIGHT_PURPLE);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#DARK_PURPLE}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void purple(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.DARK_PURPLE);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#RED}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void red(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.RED);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Resets all formatting at the current position, then returns the string's
+   * value.
+   *
+   * @return never null.
+   */
+  @Override
+  public String toString() {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.NONE);
+      return this.value.toString();
+    }
+  }
+
+  /**
+   * Appends the given color to the string sequence, then returns the string's
+   * value.
+   *
+   * @param color
+   *          the desired color suffix. Null is coerced to
+   *          {@link ColorMarker#NONE}, which resets all formatting at the
+   *          current position.
+   * @return never null. Returns {@link #toString()} if the color is null.
+   */
+  public String toString(final ColorMarker color) {
+    synchronized (this.value) {
+      if (color == null) { return this.toString(); }
+      this.setColor(color);
+      return this.value.toString();
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#WHITE}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void white(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.WHITE);
+      this.value.append(append);
+    }
+  }
+
+  /**
+   * Sets the color to {@link ColorMarker#YELLOW}, then calls
+   * {@link StringBuilder#append(String)}.
+   *
+   * @param append
+   *          the string to append.
+   */
+  public void yellow(final String append) {
+    synchronized (this.value) {
+      this.setColor(ColorMarker.YELLOW);
+      this.value.append(append);
+    }
+  }
+
+  private void setColor(final ColorMarker color) {
+    synchronized (this.value) {
+      if (color != this.currentColor) {
+        this.value.append(color.getValue());
+        this.currentColor = color;
+      }
+    }
+  }
+
+}

src/site/markdown/devs.md

@@ -39,3 +39,4 @@ If you wish to use [SLF4J](http://slf4j.org) in your Bukkit plugin, or if your p
     + SLF4Bukkit supports only [Bukkit formatting markers](${project.url}/apidocs/info/ronjenkins/slf4bukkit/ColorMarker.html), which format the entire message and associated throwable (if any). All other markers are discarded. Bukkit formatting markers always override the default level-specific formatting defined in the plugin config.
     + In addition to using the Bukkit formatting markers, you can use Bukkit's `ChatColor` values to further format your message.
     + SLF4Bukkit issues `ChatColor.RESET` after every log message, so you don't have to worry about resetting after each message.
+    + You can use the [ColorString](${project.url}/apidocs/info/ronjenkins/slf4bukkit/ColorString.html) class to easily create colored log messages.