Fully unit tested Expression

Author: Julien Letrouit

CONTRIBUTING.md

@@ -64,7 +64,7 @@ We expressed above a concern for saving student's attention / motivation / time.
 ### Design goals
 
 - Strive to work on a bare WPILib installation: on VSCode with no need for a plugin.
-- Simple start: no dependency other than the Java standard library, so as to avoid a build step with a dependency management tool.
+- Simple start: no dependency other than the Java standard library, so as to avoid a build step with a dependency management tool. This has consequences: the project has to includes a mini test framework for example.
 - Java 17, because as of 2024, this is the version used by default in WPILib's VSCode.
 
 ### Compromises and limitations

src/main/java/bonuses/english/AboutInterfaces.java

@@ -35,10 +35,10 @@ public class AboutInterfaces {
      * 
      * It doesn't matter whether you get a baseball bat or a hammer - as long as it implements your three conditions, you're good.
      * 
-     * In Java, you sometimes need an object that implements "conditions": one or more specific methods. But you don't care about its class. The interface is what will describe those methods.
-     * We can see the interface as a kind of contract that an object would respect.
+     * In Java, you sometimes need an object of a class you do not care, but which implements "conditions": one or more specific methods.
+     * We can see the interface as a kind of contract that an object would respect, by the object having implemented the methods listed in the contract.
      * 
-     * For example, in a game where the situation above would happen, you could create the following interface in a game:
+     * For example, in a game where the situation above would happen, you could create the following interface:
      * 
      *     public interface Weapon {
      *         void hit(Monster monster);
@@ -54,22 +54,21 @@ public class AboutInterfaces {
      *     public class Sword implements Weapon {
      * 
      *         // Since Sword implements Weapon, it must implement the hit method.
-     *         @Override // This special annotation means the method is defined elsewhere (our interface in this case)
+     *         @Override // This strange annotation means the method is defined elsewhere (in our interface)
      *         public void hit(Monster monster) {
      *             // Some code computing and applying damage to the monster, applying some tear and wear on the weapon, etc...
      *         }
      * 
      *     }
      * 
-     * 
      * Now, the code in hit() maybe complicated but it does not matter: it follows the contract of the interface, and you can call it.
      * For example, you could create an object allowing you to hit a zombie with the following code:
      * 
      *     Monster zombie = ...;               // Code getting the object for the zombie in the middle of the room
      *     Weapon tossedWeapon = new Sword();  // or new Hammer() or new Axe() or new WhateverImplementsWeapon()
      *     tossedWeapon.hit(zombie);           // use the Weapon interface
      * 
-     * Notice the type of the variable 'tossedWeapon': it is a Weapon, not a Sword. Interfaces, like classes, are types you can use for variables, fields, and parameters.
+     * Notice the type of the variable 'tossedWeapon': it is a Weapon, not a Sword. Interfaces, like classes, are types you can use for declaring variables, fields, and parameters.
      * Because Sword implements Weapon, Java considers that a Sword object _is_ a Weapon. Having variables and parameters using the interface type allows you to work with any object implementing that interface.
      * 
      * Take a look at the bonuses.teachingmaterial.Combining interface. It defines a method which can be implemented in various ways.
@@ -93,7 +92,7 @@ public class AboutInterfaces {
      * 
      */
 
-     
+
     /**
      * # Anonymous interface implementation
      * 

src/main/java/bonuses/french/AboutInterfaces.java

@@ -8,71 +8,252 @@
 
 public class AboutInterfaces {
     /**
-     * # For loops
+     * # First interface implementations
      * 
-     * Write a method named 'displayNumbers' with an integer parameter 'n', which displays numbers between 1 and n.
-     * Use a 'for' loop instead of a 'while' loop. Use the shortest form of incrementation / decrementation.
+     * Write a class 'numbers.AddNumbers' which implements interface 'bonuses.teachingmaterial.Combining'.
+     * The implementation of the combine() method should return the 2 numbers added together.
+     * Write a class 'numbers.MultiplyNumbers' which also implements interface 'bonuses.teachingmaterial.Combining'.
+     * This implementation of the combine() method should return the 2 numbers multiplied together.
      * 
      * ---------   TIPS   --------------
      * 
-     * To do things multiple times in Java, you already know the 'while' loop.
-     * Most of the time, a 'while' loop has very similar code structure:
+     * Consider the following situation:
      * 
-     *     [Initialize a counter];
-     *     while ([Condition on the counter variable]) {
-     *         // Do stuff repetedly
-     *         [Modify the counter at the end of the loop];
+     * You are in the middle of a large, empty room, when a zombie suddenly attacks you.
+     * You have no weapon.
+     * Luckily, a fellow living human is standing in the doorway of the room.
+     * "Quick!" you shout at him. "Throw me something I can hit the zombie with!"
+     * 
+     * Now consider:
+     * You didn't specify (nor do you care) exactly what your friend will choose to toss; ...But it doesn't matter, as long as:
+     * 
+     * 1) It's something that can be tossed (He can't toss you the sofa)
+     * 2) It's something that you can grab hold of (Not a wet soap)
+     * 3) It's something you can use to bash the zombie's brains out (That rules out pillows and such)
+     * 
+     * It doesn't matter whether you get a baseball bat or a hammer - as long as it implements your three conditions, you're good.
+     * 
+     * In Java, you sometimes need an object of a class you do not care, but which implements "conditions": one or more specific methods.
+     * We can see the interface as a kind of contract that an object would respect, by the object having implemented the methods listed in the contract.
+     * 
+     * For example, in a game where the situation above would happen, you could create the following interface:
+     * 
+     *     public interface Weapon {
+     *         void hit(Monster monster);
      *     }
      * 
-     * Ex:
+     * Now, whether your weapon is a sword inflicting 10 damage points, or a knife inflicting only 4 damage points to the monster, the player will be able to hit a monster with it.
+     * 
+     * Respecting the contract of a Java interface is called 'implementing the interface'. A class can implement an interface this way:
+     * 
+     *         you declare that this class will implement the Weapon interface
+     *                        vvvvvvvvvvvvvvvvv
+     * 
+     *     public class Sword implements Weapon {
+     * 
+     *         // Since Sword implements Weapon, it must implement the hit method.
+     *         @Override // This strange annotation means the method is defined elsewhere (in our interface)
+     *         public void hit(Monster monster) {
+     *             // Some code computing and applying damage to the monster, applying some tear and wear on the weapon, etc...
+     *         }
      * 
-     *     int times = 3; // Initialize a counter
-     *     while (times > 0) { // Condition on the counter variable
-     *         System.out.println("Still executing"); // Do stuff repetedly
-     *         times = times -1; // Modify the counter at the end of the loop
      *     }
      * 
-     * Since this pattern is used again and again, there is a shortcut in Java to make it terser. It's called a 'for' loop, where all 3 parts seen above are grouped on a single line:
+     * Now, the code in hit() maybe complicated but it does not matter: it follows the contract of the interface, and you can call it.
+     * For example, you could create an object allowing you to hit a zombie with the following code:
+     * 
+     *     Monster zombie = ...;               // Code getting the object for the zombie in the middle of the room
+     *     Weapon tossedWeapon = new Sword();  // or new Hammer() or new Axe() or new WhateverImplementsWeapon()
+     *     tossedWeapon.hit(zombie);           // use the Weapon interface
+     * 
+     * Notice the type of the variable 'tossedWeapon': it is a Weapon, not a Sword. Interfaces, like classes, are types you can use for declaring variables, fields, and parameters.
+     * Because Sword implements Weapon, Java considers that a Sword object _is_ a Weapon. Having variables and parameters using the interface type allows you to work with any object implementing that interface.
      * 
-     *     for([Initialize a counter]; [Condition on the counter variable]; [Modify the counter at the end of the loop]) {
-     *         // do stuff repetedly
+     * Take a look at the bonuses.teachingmaterial.Combining interface. It defines a method which can be implemented in various ways.
+     * This exercise is about implementing that interface in 2 ways.
+     * 
+     * -------------------------------
+     * 
+     * Expected result:
+     * 
+     * The following code:
+     * 
+     *     Combining combining = new AddNumbers();
+     *     System.out.println(combining.combine(3, 4));
+     *     combining = new MultiplyNumbers();
+     *     System.out.println(combining.combine(3, 4));
+     * 
+     * Should display:
+     * 
+     * 7
+     * 12
+     * 
+     */
+
+     
+    /**
+     * # Anonymous interface implementation
+     * 
+     * Write a method 'getAnonymousCombining' which returns an anonymous implementation of 'bonuses.teachingmaterial.Combining'.
+     * The implementation of the combine() method should return the second number subtracted from the first.
+     * 
+     * ---------   TIPS   --------------
+     * 
+     * Sometimes, it is tedious to create a class file to implement an interface just for one occasion.
+     * In these situation, you can implement the interface in an anonymous class. It is anonymous, because it does not have a name.
+     * That class is instantiated immediately where it is created. For example:
+     * 
+     *     public Weapon toss() {
+     *         return new Weapon() {
+     *             @Override
+     *             public void hit(Monster monster) {
+     *                 // Some code computing and applying damage to the monster, applying some tear and wear on the weapon, etc...
+     *             }
+     *         }
      *     }
      * 
-     * Ex:
-     *     
-     *     for(int times = 3; times > 0; times = times -1) {
-     *         System.out.println("Still executing"); // Do stuff repetedly
+     * When looking at this code, you could be tempted to believe there is a constructor for the interface Weapon, but there is not.
+     * We are really creating a class, for which there exists a single object.
+     * The constructor with empty parameters is the one of this nameless class.
+     * We can now get and use the tossed weapon this way:
+     * 
+     *     Weapon tossedWeapon = toss();
+     *     tossedWeapon.hit(zombie);
+     * 
+     * -------------------------------
+     * 
+     * Expected result:
+     * 
+     * getAnonymousCombining().combine(3, 4) should return -1
+     * 
+     */
+
+    
+    /**
+     * # Lambda methods
+     * 
+     * Write a method 'getLambdaCombining' which returns an lambda method implementing 'bonuses.teachingmaterial.Combining'.
+     * The implementation of the combine() method should return the first number subtracted from the second.
+     * 
+     * ---------   TIPS   --------------
+     * 
+     * When an interface have only one method, there is an even shorter form to implement it. You can use what is called a 'lambda method'.
+     * A 'lambda method' is a stripped down version of a method. Since our example interface 'Weapon' has only a single method 'hit()', we can use this shortcut:
+     * 
+     * For example:
+     * 
+     *     public Weapon toss() {
+     *         return (monster) -> { 
+     *             // Some code computing and applying damage to the monster, applying some tear and wear on the weapon, etc.. 
+     *         };
      *     }
      * 
-     * There is even another shortcut: since incrementing or decrementing a number is something that happens very often, there is a short form:
+     * We can now get and use the tossed weapon this way:
      * 
-     *     a = a - 2; // Long form
-     *     a -= 2;    // Short form
-     *     b = b + 2; // Long form
-     *     b += 2;    // Short form
+     *     Weapon tossedWeapon = toss();
+     *     tossedWeapon.hit(zombie);
      * 
-     * When we increment / decrement by one, there is an even shorter form:
+     * The general syntax for lambda method returning void, or having a body with multiple lines:
      * 
-     *     a -= 1; // Short form
-     *     a--;    // Shortest form
-     *     b += 1; // Short form
-     *     b++;    // Shortest form
+     *     ([param1Name], [param2Name], ...) -> {
+     *         // Lambda method body here
+     *     }
+     * 
+     * If your lambda is having a single expression, you can even skip the parentheses and the 'return':
+     * 
+     *     ([param1Name], [param2Name], ...) -> // expression here
+     * 
+     * Here are some example of methods and their lambda equivalent (assuming the interface has only one method in it):
+     * 
+     * This interface implementation:
+     * 
+     *     public void sayHello() {
+     *         System.out.println("hello");
+     *     }
+     * 
+     * Can be replaced by this lambda:
+     * 
+     *     () -> {
+     *         System.out.println("hello");
+     *     }
+     * 
+     * This interface implementation:
      * 
-     * Using this, our for loop can become even terser:
+     *     public int square(int x) {
+     *         return x * x;
+     *     }
+     * 
+     * Can be replaced by this lambda:
+     * 
+     *     (x) -> x * x
      * 
-     *     for(int times = 3; times > 0; times--) {
-     *         System.out.println("Still executing"); // Do stuff repetedly
+     * This interface implementation:
+     * 
+     *     public int min(int x, int y) {
+     *         if (x < y) {
+     *             return x;
+     *         }
+     *         return y;
+     *     }
+     * 
+     * Can be replaced by this lambda:
+     * 
+     *     (x, y) -> {
+     *         if (x < y) {
+     *             return x;
+     *         }
+     *         return y;
      *     }
      * 
      * -------------------------------
      * 
      * Expected result:
      * 
-     * displayNumbers(3) should display:
+     * getLambdaCombining().combine(3, 4) should return 1
+     * 
+     */
+
+
+    /**
+     * # Common lambda interfaces
+     * 
+     * Write a method 'getIsEven' which returns a lambda method testing if an integer is even.
+     * 
+     * ---------   TIPS   --------------
+     * 
+     * Since lambda methods are so useful, a lot of interfaces already exist in the Java standard library, and we don't have to create them ourselves.
+     * 
+     * For example:
+     * 
+     * For a lambda taking no parameter, and returning nothing, {@link java.lang.Runnable}:
+     * 
+     *     Runnable sayHello = () -> { System.out.println("Hello"); };
+     * 
+     * For a lambda taking a int parameter, and returning nothing, {@link java.util.function.IntConsumer}:
+     * 
+     *     IntConsumer displayInt = (anInt) -> { System.out.println(anInt); };
+     * 
+     * The same exist for other type. For example {@link java.util.function.DoubleConsumer}:
+     * 
+     *     DoubleConsumer displayDouble = (aDouble) -> { System.out.println(aDouble); };
+     * 
+     * The reverse functions, taking nothing as a parameter, but returning something exist as well: {@link java.util.function.IntSupplier}, {@link java.util.function.DoubleSupplier}. etc...
+     * 
+     *     DoubleSupplier giveMePiPleeeaaase = () -> 3.14159;
+     * 
+     * There is also a lot of case where you would need to test a number somehow. This is where interfaces like {@link java.util.function.IntPredicate} shine:
+     * 
+     *     IntPredicate isPositive = (number) -> number >= 0;
+     * 
+     * For the exercise, you can use the modulo operator, %, which computes the remainder of an integer division:
+     * 
+     *     int remainder = 17 % 5; // remainder equals 2
+     * 
+     * -------------------------------
+     * 
+     * Expected result:
      * 
-     * 1
-     * 2
-     * 3
+     * getIsEven().test(4) should return true
      * 
      */
 

src/main/java/engine/Printer.java

@@ -4,7 +4,7 @@
 import java.util.Arrays;
 import java.util.List;
 
-import engine.test.Line;
+import engine.test.runner.Line;
 
 /**
  * A Printer allows to print feedback to the student.

src/main/java/engine/TestSensei.java

@@ -4,8 +4,11 @@
 import java.util.stream.IntStream;
 
 import engine.script.ScriptRunner;
-import engine.test.Line;
+import engine.test.runner.Line;
 
+/**
+ * A sensei used to run unit tests for the FRC Java Koans, for contributors.
+ */
 public class TestSensei {
     public static final Locale TEST_LOCALE = Locale.en;
 

src/main/java/engine/Texts.java

@@ -217,14 +217,14 @@ public class Texts {
         local("Expected %s to return %d from random number %f but returned %d instead!")
         .fr("Attendu à ce que %s retourne %d à partir du nombre aléatoire %f mais a retourné %d à la place!");
     public static Localizable<String> OK_RETURNED_INT_FROM_RANDOM =
-        local("Ok: %s returned %d from random number %f.")
-        .fr("Ok: %s a retourné %d à partir du nombre aléatoire %f.");
+        local("Ok: %s returned %s from random number %f.")
+        .fr("Ok: %s a retourné %s à partir du nombre aléatoire %f.");
     public static Localizable<String> EXPECTED_TO_RETURN_INT_FROM_RANDOMS_BUT_RETURNED =
-        local("Expected %s to return %d from random numbers %s but returned %d instead!")
-        .fr("Attendu à ce que %s retourne %d à partir des nombres aléatoires %s mais a retourné %d à la place!");
+        local("Expected %s to return %s from random numbers %s but returned %d instead!")
+        .fr("Attendu à ce que %s retourne %s à partir des nombres aléatoires %s mais a retourné %d à la place!");
     public static Localizable<String> OK_RETURNED_INT_FROM_RANDOMS =
-        local("Ok: %s returned %d from random numbers %s.")
-        .fr("Ok: %s a retourné %d à partir du nombre aléatoire %s.");        
+        local("Ok: %s returned %s from random numbers %s.")
+        .fr("Ok: %s a retourné %s à partir du nombre aléatoire %s.");        
     public static Localizable<String> EXPECTED_FIELD_TO_BE_PRIVATE =
         local("Expected '%s' field in class %s to be private, but it is not.")
         .fr("Attendu à ce que le champ '%s' dans la classe %s soit privé, mais il ne l'est pas.");