Better console display, titles for Koans

Author: Julien Letrouit

README.md

@@ -117,19 +117,21 @@ Next, we can see these lines, colored in green:
 
 ```java
     /**
+     * # Displaying some text in the console
+     * 
      * Display 'Hello!' in the console.
      * 
      * ---------   TIPS --------------
      * 
      * All lines of code in Java must end with the ';' character. Ex:
      * 
-     * System.out.println("Apple");
+     *      System.out.println("Apple");
      * 
-     * You can use the method System.out.println([some value]) to write something in the console.
+     * You can use the method System.out.println([some value]) to display a value in the console.
      * 
      * You can tell Java that some value is text by enclosing it between double quotes. Ex:
      * 
-     * "This is text"
+     *      "This is text"
      * 
      * -------------------------------
      * 
@@ -140,7 +142,11 @@ Next, we can see these lines, colored in green:
      */
 ```
 
-These lines are forming what's called a 'comment'. All the text between a `/*` and a `*/` is a comment. A comment is a piece of information that is ignored by Java. It is not code. It is very useful for documenting your code while you are writing Java. The master is putting each Koan's instructions for you in such a comment. You can find the goal of the koan at the top of each such comment: `Display 'Hello!' in the console.`. The console is the simplest way for a Java program to communicate with you by displaying simple text in a terminal. Remember what was displayed when running the Koans? You saw this bit:
+These lines are forming what's called a 'comment'. All the text between a `/*` and a `*/` is a comment. A comment is a piece of information that is ignored by Java. It is not code. It is very useful for documenting your code while you are writing Java. The master is putting each Koan's instructions for you in such a comment.
+
+The first line of the comment tells you the title of the Koan: `# Displaying some text in the console`.
+
+Then comes the goal of the koan at the top of each such comment: `Display 'Hello!' in the console.`. The console is the simplest way for a Java program to communicate with you by displaying simple text in a terminal. Remember what was displayed when running the Koans? You saw this bit:
 
 ```
 Console:
@@ -387,6 +393,8 @@ Ensuite, nous pouvons voir ces lignes, en vert:
 
 ```java
     /**
+     * # Afficher du texte dans la console
+     * 
      * Afficher 'Hello!' dans la console.
      * 
      * ---------   INDICES   --------------
@@ -412,7 +420,9 @@ Ensuite, nous pouvons voir ces lignes, en vert:
 
 Ces lignes forment ce qu'on appelle un 'commentaire'. Tout le texte vert entre `/**` et `*/` est un commentaire. Un commentaire est une information destinée à des humains, et est ignoré par Java. Ce n'est pas du code. C'est très utile pour documenter ton code quand tu écris du Java. Le maître se sert d'un de ces commentaires pour placer les instructions de chacun de ses koans.
 
-Tu peux trouver l'objectif du koan en haut du commentaire: `Afficher 'Hello!' dans la console.`. La console est la façon la plus simple pour un programme Java d'afficher quelque chose dans un terminal. Tu te souviens de ce qui a été affiché lorsque tu as exécuté les koans? Tu as vu ce bout de texte:
+La première ligne du commentaire te donne le titre du Koan: `# Afficher du texte dans la console`.
+
+Ensuite, tu peux trouver l'objectif du koan en haut du commentaire: `Afficher 'Hello!' dans la console.`. La console est la façon la plus simple pour un programme Java d'afficher quelque chose dans un terminal. Tu te souviens de ce qui a été affiché lorsque tu as exécuté les koans? Tu as vu ce bout de texte:
 
 ```
 Console:

src/main/java/engine/Assertions.java

@@ -0,0 +1,104 @@
+package engine;
+
+import java.util.Arrays;
+
+/**
+ * Console text coloring.
+ */
+public final class ConsoleFmt {
+    private static final String NO_FORMAT = "\033[0m";
+
+    private static final String RED = "\033[0;31m";
+    private static final String GREEN = "\033[0;32m";
+    private static final String CYAN = "\033[0;36m";
+    private static final String DODGERBLUE2="\033[38;5;27m";
+
+    private static final String BOLD= "\033[1m";
+    private static final String RED_BOLD= RED + BOLD;
+
+    public static enum Formats {
+        None(NO_FORMAT),
+        Red(RED),
+        Green(GREEN),
+        Cyan(CYAN),
+        Code(DODGERBLUE2),
+        Strong(BOLD),
+        StrongRed(RED_BOLD);
+
+        public final String tags;
+
+        private Formats(String tags) {
+            this.tags = tags;
+        }
+    }
+
+    public record Formatted<T>(T text, Formats fmt) {}
+
+    public static <T> Formatted<T> fmt(T text, Formats fmt) {
+        return new Formatted<T>(text, fmt);
+    }
+
+    public static <T> Formatted<T> code(T text) {
+        return new Formatted<T>(text, Formats.Code);
+    }
+
+    public static <T> Formatted<T> strong(T text) {
+        return new Formatted<T>(text, Formats.Strong);
+    }
+
+    public static <T> Formatted<T> strongRed(T text) {
+        return new Formatted<T>(text, Formats.StrongRed);
+    }
+
+    public static Localizable<String> red(final Localizable<String> text) {
+        return text.map(ConsoleFmt::red);
+    }
+
+    public static Localizable<String> green(final Localizable<String> text) {
+        return text.map(ConsoleFmt::green);
+    }
+
+    public static Localizable<String> cyan(final Localizable<String> text) {
+        return text.map(ConsoleFmt::cyan);
+    }
+
+    public static Localizable<String> strongRed(final Localizable<String> text) {
+        return text.map(ConsoleFmt::strongRed);
+    }
+
+    public static Localizable<String> strong(final Localizable<String> text) {
+        return text.map(ConsoleFmt::strong);
+    }
+
+    public static String red(final String text) {
+        return String.format("%s%s%s", RED, text, NO_FORMAT);
+    }
+
+    public static String green(final String text) {
+        return String.format("%s%s%s", GREEN, text, NO_FORMAT);
+    }
+
+    public static String cyan(final String text) {
+        return String.format("%s%s%s", CYAN, text, NO_FORMAT);
+    }
+
+    public static String strong(final String text) {
+        return String.format("%s%s%s", BOLD, text, NO_FORMAT);
+    }
+
+    public static String strongRed(final String text) {
+        return String.format("%s%s%s", RED_BOLD, text, NO_FORMAT);
+    }
+
+    public static String format(final String template, Formats fmt, final Object... params) {
+        final var formattedParams = Arrays
+            .stream(params)
+            .map(param -> param instanceof Formatted<?> fmted ? String.format("%s%s%s", fmted.fmt.tags, fmted.text, fmt.tags) : param)
+            .toArray(Object[]::new);
+        return String.format("%s%s%s", fmt.tags, String.format(template, formattedParams) , NO_FORMAT);
+    }
+
+    public static Localizable<String> format(final Localizable<String> template, final Formats fmt, final Object... params) {
+        return template.map(txt -> format(txt, fmt, params));
+    }
+}

src/main/java/engine/Color.java

@@ -2,7 +2,6 @@
 
 import static engine.Texts.AND;
 
-import java.lang.reflect.Modifier;
 import java.util.Arrays;
 import java.util.Random;
 import java.util.Scanner;
@@ -57,15 +56,4 @@ static String formatSequence(final Locale locale, final Object[] toFormat) {
 
         return result.toString();
     }
-
-    static boolean isInstantiable(final Class<?> clasz) {
-        final int modifiers = clasz.getModifiers();
-        return
-            Modifier.isPublic(modifiers) &&
-            !clasz.isInterface() &&
-            !Modifier.isAbstract(modifiers) &&
-            !clasz.isArray() &&
-            !clasz.isPrimitive() &&
-            !clasz.equals(void.class);
-    }
 }

src/main/java/engine/ConsoleFmt.java

@@ -6,19 +6,20 @@
 import java.util.function.Function;
 
 import engine.script.Expression;
+import engine.script.Type;
 
 /**
  * Stores all the information required to execute and assess the result of a koan.
  */
 public class Koan {
     final Localizable<Type> koanClass;
-    final String koanName;
+    final Localizable<String> koanName;
     final KoanTest[] tests;
     final boolean usesConsole;
     final boolean showStdInInputs;
     final BeforeTestAssertion[] beforeAssertions;
 
-    public Koan(final Localizable<Class<?>> koanClass, final String koanName) {
+    public Koan(final Localizable<Class<?>> koanClass, final Localizable<String> koanName) {
         this(
             koanClass.map(Type::new),
             koanName,
@@ -31,7 +32,7 @@ public Koan(final Localizable<Class<?>> koanClass, final String koanName) {
 
     private Koan(
         final Localizable<Type> koanClass,
-        final String koanName,
+        final Localizable<String> koanName,
         final KoanTest[] tests,
         final boolean usesConsole,
         final boolean showStdInInputs,

src/main/java/engine/Helpers.java

@@ -4,10 +4,15 @@
 import java.util.List;
 import java.util.concurrent.atomic.AtomicBoolean;
 
+import engine.ConsoleFmt.Formats;
 import engine.script.Expression;
 import engine.script.ScriptExecutionException;
 import engine.script.ScriptRunner;
 
+import static engine.ConsoleFmt.code;
+import static engine.ConsoleFmt.format;
+import static engine.ConsoleFmt.strong;
+import static engine.ConsoleFmt.strongRed;
 import static engine.Texts.*;
 
 /**
@@ -79,24 +84,24 @@ private boolean offerTest(KoanTest test, int successfulCount) {
                 // Special case: since the executeCall() method did not complete, the console conclusion was not displayed.
                 concludeConsole(koan);
                 if (see.getCause() instanceof InvocationTargetException ite && ite.getTargetException() instanceof StackOverflowError) {
-                    p.println(Color.red(THE_METHOD_SEEMS_TO_RECURSE_INFINITELY), see.methodName);
+                    p.println(ConsoleFmt.red(THE_METHOD_SEEMS_TO_RECURSE_INFINITELY), see.methodName);
                 } else if (see.getCause() instanceof InvocationTargetException ite) {
-                    p.println(Color.red(THE_METHOD_APPEARS_TO_PRODUCE_AN_ERROR), see.methodName, ite.getCause().getMessage());
+                    p.println(ConsoleFmt.red(THE_METHOD_APPEARS_TO_PRODUCE_AN_ERROR), see.methodName, ite.getCause().getMessage());
                 } else {
                     throw see; // Serious bug
                 }
             } catch (KoanBugException kbe) {
                 // Special case: since the executeCall() method did not complete, the console conclusion was not displayed.
                 concludeConsole(koan);
-                p.println(Color.red(BUG_FOUND), kbe.getMessage());
+                p.println(ConsoleFmt.red(BUG_FOUND), kbe.getMessage());
             }
         });
 
         thread.setDaemon(true);
         thread.start();
         try {
-            //thread.join(TIMEOUT_INFINITE_LOOPS_MS);
-            thread.join();
+            thread.join(TIMEOUT_INFINITE_LOOPS_MS);
+            //thread.join();
         }
         catch(InterruptedException ie) {
             throw new IllegalStateException(String.format("Something very weird happened. We should not have been interrupted: %s.", ie.getMessage()));
@@ -105,7 +110,7 @@ private boolean offerTest(KoanTest test, int successfulCount) {
         if (thread.isAlive()) {
             StdStreamsInterceptor.reset();
             concludeConsole(koan);
-            p.println(Color.red(THE_CODE_TRIED_BY_THE_SENSEI_SEEMS_TO_NOT_FINISH), Expression.formatSourceCode(test.script, locale));
+            p.println(ConsoleFmt.red(THE_CODE_TRIED_BY_THE_SENSEI_SEEMS_TO_NOT_FINISH), Expression.formatSourceCode(test.script, locale));
         }
 
         offerToMeditate(koan);
@@ -146,9 +151,7 @@ private boolean executeCall(final KoanTest test) {
     }
 
     private void introduceConsole(final KoanTest test) {
-        String testedExpression = test.script[test.script.length - 1].formatSourceCode(locale);
-
-        p.println();
+        final var testedExpression = code(test.script[test.script.length - 1].formatSourceCode(locale));
 
         if (test.script.length > 1 || test.koan.showStdInInputs) {
             p.println(THE_MASTER_SENSED_AN_HARMONY_BREACH_WHEN); // Seulement si code de prep ou stdin input
@@ -158,13 +161,13 @@ private void introduceConsole(final KoanTest test) {
             if (test.script.length > 1) {
                 p.println(WHEN_EXECUTING);
                 p.println();
-                p.println(Expression.formatPreparationSourceCode(test.script, locale, "    "));
-                p.println(AND_FINALLY_LOOKING_THE_RESULT_OF, test.script[test.script.length - 1].formatSourceCode(locale));
+                p.println(format(Expression.formatPreparationSourceCode(test.script, locale, "    "), Formats.Code));
+                p.println(format(AND_FINALLY_LOOKING_THE_RESULT_OF, Formats.None, testedExpression));
             } else {
-                p.println(WHEN_LOOKING_THE_RESULT_OF, testedExpression);
+                p.println(format(WHEN_LOOKING_THE_RESULT_OF, Formats.None, testedExpression));
             }
         } else {
-            p.println(THE_MASTER_SENSED_AN_HARMONY_BREACH_WHEN_LOOKING_AT, testedExpression);
+            p.println(format(THE_MASTER_SENSED_AN_HARMONY_BREACH_WHEN_LOOKING_AT, Formats.None, testedExpression));
         }
 
         p.println();
@@ -187,10 +190,10 @@ private void concludeConsole(final Koan koan) {
     private void encourage(final Koan koan) {
         p.println();
         p.println(THINKING, koan.koanClass.get(locale).simpleClassName);
-        p.println(Color.red(HAS_DAMAGED_YOUR_KARMA), koan.koanName);
+        p.println(format(HAS_DAMAGED_YOUR_KARMA, Formats.Red, strongRed(koan.koanName.get(locale))));
         p.println();
         p.println(THE_MASTER_SAYS);
-        p.println(Color.cyan(YOU_HAVE_NOT_REACHED_ENLIGHTMENT));
+        p.println(ConsoleFmt.cyan(YOU_HAVE_NOT_REACHED_ENLIGHTMENT));
         p.println();
         p.println("---------");
         p.println();
@@ -201,9 +204,12 @@ private void encourage(final Koan koan) {
     private void offerToMeditate(final Koan koan) {
         p.println();
         p.println(
-            PLEASE_MEDITATE_ON, 
-            koan.koanName,
-            koan.koanClass.get(locale).simpleClassName
+            format(
+                PLEASE_MEDITATE_ON, 
+                Formats.None,
+                strong(koan.koanName.get(locale)),
+                koan.koanClass.get(locale).simpleClassName
+            )
         );
         p.println();
     }
@@ -216,9 +222,9 @@ private void showProgress(final int successfulCount) {
 
         final var bar = String.format(
             "%s%s%s",
-            Color.green(repeat(".", successfulCount)),
-            Color.red("X"),
-            Color.cyan(repeat("_", allKoans.size() - successfulCount - 1)));
+            ConsoleFmt.green(repeat(".", successfulCount)),
+            ConsoleFmt.red("X"),
+            ConsoleFmt.cyan(repeat("_", allKoans.size() - successfulCount - 1)));
         p.println(YOUR_PROGRESS_THUS_FAR, bar, successfulCount, allKoans.size());
         p.println();
     }