[#376] Help.Ansi.text(String) and Help.Ansi.string(String) help c…

…lient code easily create ANSI messages outside usage help and version help.

Closes #376

RELEASE-NOTES.md

@@ -3,7 +3,9 @@
 # <a name="3.4.0"></a> Picocli 3.4.0 (UNRELEASED)
 The picocli community is pleased to announce picocli 3.4.0.
 
-This release contains bugfixes and enhancements.
+This release contains new features, bugfixes and enhancements.
+The parser can now ignore case when parsing arguments for an Enum option or positional parameter.
+New methods `Help.Ansi.text(String)` and `Help.Ansi.string(String)` assist client code in easily creating ANSI messages outside usage help and version help.
 
 This is the thirty-fifth public release.
 Picocli follows [semantic versioning](http://semver.org/).
@@ -24,6 +26,7 @@ No features have been promoted in this picocli release.
 
 ## <a name="3.4.0-fixes"></a> Fixed issues
 - [#14] New API: Support enum values to be parsed in an case-insensitive way.
+- [#376] New API: `Help.Ansi.text(String)` and `Help.Ansi.string(String)` help client code easily create ANSI messages outside usage help and version help.
 - [#412] Enhancement: Enum constant names are now returned from `ArgSpec::completionCandidates()`. Thanks to [Radovan Panák](https://github.com/rpanak).
 - [#417] Enhancement: Ensure bash scripts have correct line separators. Thanks to [Holger Stenger](https://github.com/stengerh).
 - [#425] Enhancement: Fix autocomplete script errors in zsh. Thanks to [Anthony Keenan](https://github.com/anthonykeenan).

src/main/java/picocli/CommandLine.java

@@ -8175,6 +8175,29 @@ public boolean enabled() {
                 if (this == OFF) { return false; }
                 return (System.getProperty("picocli.ansi") == null ? ansiPossible() : Boolean.getBoolean("picocli.ansi"));
             }
+            /**
+             * Returns a new Text object for this Ansi mode, encapsulating the specified string
+             * which may contain markup like {@code @|bg(red),white,underline some text|@}.
+             * <p>
+             * Calling {@code toString()} on the returned Text will either include ANSI escape codes
+             * (if this Ansi mode is ON), or suppress ANSI escape codes (if this Ansi mode is OFF).
+             * <p>
+             * Equivalent to {@code this.new Text(stringWithMarkup)}.
+             * @since 3.4 */
+            public Text text(String stringWithMarkup) { return this.new Text(stringWithMarkup); }
+
+            /**
+             * Returns a String where any markup like
+             * {@code @|bg(red),white,underline some text|@} is converted to ANSI escape codes
+             * if this Ansi is ON, or suppressed if this Ansi is OFF.
+             * <p>
+             * Equivalent to {@code this.new Text(stringWithMarkup).toString()}.
+             * @since 3.4 */
+            public String string(String stringWithMarkup) { return this.new Text(stringWithMarkup).toString(); }
+
+            /** Returns Ansi.ON if the specified {@code enabled} flag is true, Ansi.OFF otherwise.
+             * @since 3.4 */
+            public static Ansi valueOf(boolean enabled) {return enabled ? ON : OFF; }
 
             /** Defines the interface for an ANSI escape sequence. */
             public interface IStyle {

src/test/java/picocli/CommandLineHelpTest.java

@@ -3570,4 +3570,27 @@ class App {
                 "  -l     use a long listing format%n" +
                 "  -t     sort by modification time%n"), actual);
     }
+
+    @Test
+    public void testAnsiText() {
+        String markup = "@|bg(red),white,underline some text|@";
+        Help.Ansi.Text txt = Help.Ansi.ON.text(markup);
+        Help.Ansi.Text txt2 = Help.Ansi.ON.new Text(markup);
+        assertEquals(txt, txt2);
+    }
+
+    @Test
+    public void testAnsiString() {
+        String msg = "some text";
+        String markup = "@|bg(red),white,underline " + msg + "|@";
+        String ansiTxt = Help.Ansi.ON.string(markup);
+        String ansiTxt2 = Help.Ansi.ON.new Text(markup).toString();
+        assertEquals(ansiTxt, ansiTxt2);
+    }
+
+    @Test
+    public void testAnsiValueOf() {
+        assertEquals("true=ON", Help.Ansi.ON, Help.Ansi.valueOf(true));
+        assertEquals("false=OFF", Help.Ansi.OFF, Help.Ansi.valueOf(false));
+    }
 }