Merge pull request #4 from darvil82/dev

Add true color and `NO_COLOR=1` support.

Author: darvil82

README.md

@@ -1,6 +1,21 @@
 # Terminal Text Formatter
 
-Text formatting utilities to easily format text on the terminal for Java.
+Text formatting utilities to easily format text in the terminal for Java.
+
+
+## Usage Example
+
+```java
+var text = TextFormatter.of("blue text here, ", TrueColor.of(50, 50, 255))
+   .addFormat(FormatOption.BOLD, FormatOption.ITALIC)
+   .concat(TextFormatter.of("now yellow", SimpleColor.BRIGHT_YELLOW))
+   .concat(" and back to blue");
+
+System.out.println(text);
+```
+
+Javadocs for the latest stable version are provided online [here](https://darvil82.github.io/java-terminal-text-formatter/).
+
 
 ## Installation
 
@@ -17,4 +32,4 @@ The package is currently available on Repsy and GitHub Packages.
    ```
 > [!NOTE]
 > The `+` symbol is a wildcard that will automatically use the latest version of the package.
-> You can also specify a specific version (e.g. `0.0.1`).
+> You can also specify a specific version (e.g. `0.0.1`).

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "com.darvil"
-version = "2.0.0b"
+version = "2.1.0"
 description = "Text formatting utilities to easily format text on the terminal for Java."
 
 dependencies {

src/main/java/module-info.java

@@ -3,4 +3,5 @@
 	requires org.jetbrains.annotations;
 
 	exports textFormatter;
+	exports textFormatter.color;
 }

src/main/java/textFormatter/TextFormatter.java

@@ -2,13 +2,15 @@
 
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import textFormatter.color.Color;
+import textFormatter.color.SimpleColor;
 
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 
 /**
- * Allows to easily format text for display in a terminal.
+ * Allows easily formatting of text for it to be displayed in a terminal.
  * <p>
  * Multiple formatters can be concatenated together. This is useful for when you want to
  * format a string that has multiple parts that need to be formatted differently.
@@ -18,14 +20,17 @@ public class TextFormatter {
 	/**
 	 * When set to {@code false}, no formatting will be applied to text. Raw text will be generated without any
 	 * color or formatting.
+	 * <p>
+	 * This will be set to {@code false} if the environment variable {@code NO_COLOR} is set.
+	 * @see #isColorDisabledEnv()
 	 */
-	public static boolean enableSequences = true;
+	public static boolean enableSequences = !TextFormatter.isColorDisabledEnv();
 
 	/**
 	 * The default color that should be used when no foreground color is specified (if {@link #startWithDefaultColorIfNotDefined}
 	 * is set to {@code true}), or when the foreground color is reset.
 	 */
-	public static @NotNull Color defaultColor = Color.BRIGHT_WHITE;
+	public static @NotNull Color defaultColor = SimpleColor.BRIGHT_WHITE;
 
 	/**
 	 * When set to {@code true}, the default color will be used when no foreground color is specified.
@@ -103,7 +108,7 @@ public static TextFormatter create() {
 	 * @return a new {@link TextFormatter} with the specified contents and the error formatting
 	 * */
 	public static @NotNull TextFormatter error(@NotNull String msg) {
-		return TextFormatter.of(msg, Color.BLACK, Color.BRIGHT_RED).addFormat(FormatOption.BOLD);
+		return TextFormatter.of(msg, SimpleColor.BLACK, SimpleColor.BRIGHT_RED).addFormat(FormatOption.BOLD);
 	}
 
 
@@ -287,7 +292,7 @@ else if (TextFormatter.startWithDefaultColorIfNotDefined && this.parent == null)
 
 	/**
 	 * Returns the {@link Color} that should properly reset the foreground color. This is determined by looking at the
-	 * parent formatters. If no parent formatter has a foreground color, then {@link Color#BRIGHT_WHITE} is returned.
+	 * parent formatters. If no parent formatter has a foreground color, then {@link SimpleColor#BRIGHT_WHITE} is returned.
 	 * @return the {@link Color} that should properly reset the foreground color
 	 */
 	private @Nullable Color getResetFgColor() {
@@ -359,19 +364,40 @@ else if (TextFormatter.startWithDefaultColorIfNotDefined && this.parent == null)
 	}
 
 	/**
-	 * Returns a string with a terminal sequence with the specified code.
-	 * (e.g. {@code "ESC[<code here>m"})
+	 * Returns a string with a terminal sequence with the specified values, separated by a semicolon.
+	 * (e.g. {@code "ESC[<values here>m"})
 	 * <p>
 	 * If {@link #debug} is set to {@code true}, then the text "ESC" will be used instead of the actual escape
 	 * character.
 	 * </p>
-	 * @param code The code of the sequence.
-	 * @return a string with a terminal sequence with the specified code
+	 * If {@link #enableSequences} is set to {@code false}, then an empty string will be returned.
+	 * @param values The values to add to the terminal sequence.
+	 * @return a string with a terminal sequence with the specified values
 	 */
-	static @NotNull String getSequence(int code) {
+	public static @NotNull String getSequence(@NotNull Object... values) {
+		if (!TextFormatter.enableSequences)
+			return "";
+
+		var joined = String.join(
+			";",
+			Arrays.stream(values)
+				.map(Object::toString)
+				.toArray(String[]::new)
+		);
+
 		if (TextFormatter.debug)
-			return "ESC[" + code + "]";
-		return "" + ESC + '[' + code + 'm';
+			return "ESC[" + joined + "]";
+		return "" + ESC + '[' + joined + 'm';
+	}
+
+	/**
+	 * Returns whether there is an environment variable that specifies that
+	 * the terminal does not support color.
+	 * <a href="https://no-color.org/">NO_COLOR.org</a>
+	 * @return {@code true} if the terminal supports color
+	 */
+	public static boolean isColorDisabledEnv() {
+		return System.getenv("NO_COLOR") != null;
 	}
 
 	/**

src/main/java/textFormatter/color/Color.java

@@ -0,0 +1,24 @@
+package textFormatter.color;
+
+import org.jetbrains.annotations.NotNull;
+
+public interface Color {
+	/**
+	 * Returns the ANSI escape sequence for this color for the text foreground.
+	 * @return The ANSI escape sequence for this color.
+	 */
+	@NotNull String fg();
+
+	/**
+	 * Returns the ANSI escape sequence for this color for the text background.
+	 * @return The ANSI escape sequence for this color.
+	 */
+	@NotNull String bg();
+
+	/**
+	 * Returns the ANSI escape sequence for this color for the text foreground.
+	 * @return The ANSI escape sequence for this color.
+	 * @see SimpleColor#fg()
+	 */
+	@NotNull String toString();
+}

src/main/java/textFormatter/Color.java renamed to src/main/java/textFormatter/color/SimpleColor.java

@@ -1,11 +1,12 @@
-package textFormatter;
+package textFormatter.color;
 
 import org.jetbrains.annotations.NotNull;
+import textFormatter.TextFormatter;
 
 /**
  * Enumerates the ANSI color codes that a terminal can normally display.
  */
-public enum Color {
+public enum SimpleColor implements Color {
 	BLACK(30),
 	RED(31),
 	GREEN(32),
@@ -25,40 +26,27 @@ public enum Color {
 
 	private final byte value;
 
-	Color(int value) {
+	SimpleColor(int value) {
 		this.value = (byte)value;
 	}
 
-	/**
-	 * Returns the ANSI escape sequence for this color for the text foreground.
-	 * @return The ANSI escape sequence for this color.
-	 */
+	@Override
 	public @NotNull String fg() {
 		return TextFormatter.getSequence(this.value);
 	}
 
-	/**
-	 * Returns the ANSI escape sequence for this color for the text background.
-	 * @return The ANSI escape sequence for this color.
-	 */
+	@Override
 	public @NotNull String bg() {
 		return TextFormatter.getSequence(this.value + 10);
 	}
 
-	/**
-	 * Returns the ANSI escape sequence for this color for the text foreground.
-	 * @return The ANSI escape sequence for this color.
-	 * @see Color#fg()
-	 */
 	@Override
-	public String toString() {
+	public @NotNull String toString() {
 		return this.fg();
 	}
 
-	/**
-	 * Immutable list of all the dark colors.
-	 */
-	public static final @NotNull Color[] BRIGHT_COLORS = {
+	/** Array of all the bright colors. */
+	public static final @NotNull SimpleColor[] BRIGHT_COLORS = {
 		BRIGHT_RED,
 		BRIGHT_GREEN,
 		BRIGHT_YELLOW,
@@ -68,10 +56,8 @@ public String toString() {
 		BRIGHT_WHITE
 	};
 
-	/**
-	 * Immutable list of all the bright colors.
-	 */
-	public static final @NotNull Color[] DARK_COLORS = {
+	/** Array of all the dark colors. */
+	public static final @NotNull SimpleColor[] DARK_COLORS = {
 		RED,
 		GREEN,
 		YELLOW,

src/main/java/textFormatter/color/TrueColor.java

@@ -0,0 +1,105 @@
+package textFormatter.color;
+
+import org.jetbrains.annotations.NotNull;
+import textFormatter.TextFormatter;
+
+/**
+ * Represents a true color in the RGB color space.
+ * <p>
+ * <strong>Note:</strong> Support for true color is not universal. Expect this implementation to work in
+ * most modern terminals, but not all.
+ */
+public class TrueColor implements Color {
+	/** The color black. */
+	public static final TrueColor BLACK = TrueColor.of(0, 0, 0);
+	/** The color red. */
+	public static final TrueColor RED = TrueColor.of(255, 0, 0);
+	/** The color green. */
+	public static final TrueColor GREEN = TrueColor.of(0, 255, 0);
+	/** The color yellow. */
+	public static final TrueColor YELLOW = TrueColor.of(255, 255, 0);
+	/** The color blue. */
+	public static final TrueColor BLUE = TrueColor.of(0, 0, 255);
+	/** The color magenta. */
+	public static final TrueColor MAGENTA = TrueColor.of(255, 0, 255);
+	/** The color cyan. */
+	public static final TrueColor CYAN = TrueColor.of(0, 255, 255);
+	/** The color white. */
+	public static final TrueColor WHITE = TrueColor.of(255, 255, 255);
+
+
+	private final byte r, g, b;
+
+	private TrueColor(byte r, byte g, byte b) {
+		this.r = r;
+		this.g = g;
+		this.b = b;
+	}
+
+	/**
+	 * Creates a new TrueColor object with the given RGB components.
+	 * @param r The red component, in the range 0-255.
+	 * @param g The green component, in the range 0-255.
+	 * @param b The blue component, in the range 0-255.
+	 * @return A new TrueColor object with the given RGB components.
+	 * @throws IllegalArgumentException If any of the color components are not in the range 0-255.
+	 */
+	public static @NotNull TrueColor of(int r, int g, int b) {
+		if (r < 0 || r > 255 || g < 0 || g > 255 || b < 0 || b > 255) {
+			throw new IllegalArgumentException("Color components must be in the range 0-255");
+		}
+		return new TrueColor((byte)r, (byte)g, (byte)b);
+	}
+
+	/**
+	 * Creates a new TrueColor object with the given RGB components packed into a single integer.
+	 * @param rgb The RGB components packed into a single integer.
+	 * @return A new TrueColor object with the given RGB components.
+	 */
+	public static @NotNull TrueColor of(int rgb) {
+		return of((rgb >> 16) & 0xff, (rgb >> 8) & 0xff, rgb & 0xff);
+	}
+
+	/**
+	 * Returns the red component of this color.
+	 * @return The red component of this color.
+	 */
+	public byte r() {
+		return this.r;
+	}
+
+	/**
+	 * Returns the green component of this color.
+	 * @return The green component of this color.
+	 */
+	public byte g() {
+		return this.g;
+	}
+
+	/**
+	 * Returns the blue component of this color.
+	 * @return The blue component of this color.
+	 */
+	public byte b() {
+		return this.b;
+	}
+
+	@Override
+	public @NotNull String fg() {
+		return this.getSequence(true);
+	}
+
+	@Override
+	public @NotNull String bg() {
+		return this.getSequence(false);
+	}
+
+	private @NotNull String getSequence(boolean fg) {
+		return TextFormatter.getSequence(fg ? 38 : 48, 2, (this.r & 0xff), (this.g & 0xff), (this.b & 0xff));
+	}
+
+	@Override
+	public @NotNull String toString() {
+		return this.fg();
+	}
+}