First koan in AboutInterfaces

Author: Julien Letrouit

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

@@ -0,0 +1,98 @@
+package bonuses.english;
+
+import java.util.List;
+
+import engine.Locale;
+import engine.Sensei;
+import sensei.AboutInterfacesKoans;
+
+public class AboutInterfaces {
+    /**
+     * # First interface implementations
+     * 
+     * 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   --------------
+     * 
+     * Consider the following situation:
+     * 
+     * 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 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.
+     * 
+     * For example, in a game where the situation above would happen, you could create the following interface in a game:
+     * 
+     *     public interface Weapon {
+     *         void hit(Monster monster);
+     *     }
+     * 
+     * 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 special annotation means the method is defined elsewhere (our interface in this case)
+     *         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.
+     * 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.
+     * 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
+     * 
+     */
+
+
+     public static void main(String[] args) {
+        new Sensei(Locale.en, List.of(AboutInterfacesKoans.koans)).offerKoans();
+    }
+}

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

@@ -0,0 +1,83 @@
+package bonuses.french;
+
+import java.util.List;
+
+import engine.Locale;
+import engine.Sensei;
+import sensei.AboutInterfacesKoans;
+
+public class AboutInterfaces {
+    /**
+     * # For loops
+     * 
+     * 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.
+     * 
+     * ---------   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:
+     * 
+     *     [Initialize a counter];
+     *     while ([Condition on the counter variable]) {
+     *         // Do stuff repetedly
+     *         [Modify the counter at the end of the loop];
+     *     }
+     * 
+     * Ex:
+     * 
+     *     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:
+     * 
+     *     for([Initialize a counter]; [Condition on the counter variable]; [Modify the counter at the end of the loop]) {
+     *         // do stuff repetedly
+     *     }
+     * 
+     * Ex:
+     *     
+     *     for(int times = 3; times > 0; times = times -1) {
+     *         System.out.println("Still executing"); // Do stuff repetedly
+     *     }
+     * 
+     * There is even another shortcut: since incrementing or decrementing a number is something that happens very often, there is a short form:
+     * 
+     *     a = a - 2; // Long form
+     *     a -= 2;    // Short form
+     *     b = b + 2; // Long form
+     *     b += 2;    // Short form
+     * 
+     * When we increment / decrement by one, there is an even shorter form:
+     * 
+     *     a -= 1; // Short form
+     *     a--;    // Shortest form
+     *     b += 1; // Short form
+     *     b++;    // Shortest form
+     * 
+     * Using this, our for loop can become even terser:
+     * 
+     *     for(int times = 3; times > 0; times--) {
+     *         System.out.println("Still executing"); // Do stuff repetedly
+     *     }
+     * 
+     * -------------------------------
+     * 
+     * Expected result:
+     * 
+     * displayNumbers(3) should display:
+     * 
+     * 1
+     * 2
+     * 3
+     * 
+     */
+
+
+     public static void main(String[] args) {
+        new Sensei(Locale.fr, List.of(AboutInterfacesKoans.koans)).offerKoans();
+    }
+}

src/main/java/bonuses/teachingmaterial/Combining.java

@@ -0,0 +1,11 @@
+package bonuses.teachingmaterial;
+
+/**
+ * This file is used by the AboutInterfaces koans.
+ */
+public interface Combining {
+    /**
+     * somehow combines 2 integers a and b, and returns the result of this combination.
+     */
+    int combine(int a, int b);
+}

src/main/java/engine/Assertions.java

@@ -438,4 +438,20 @@ public static BeforeTestAssertion assertField(final String className, final Stri
             return true;
         };
     } 
+
+    public static BeforeTestAssertion assertImplementsInterface(final String className, final Class<?> interfaceClass) {
+        return (p, locale, koan) -> {
+            final var type = new Type(className);
+            final var clasz = type.unsafeResolve();
+            final var success = Arrays
+                .stream(clasz.getInterfaces())
+                .anyMatch(implemented -> implemented == interfaceClass);
+
+            if (!success) {
+                    p.println(format(EXPECTED_CLASS_TO_IMPLEMENT, Formats.Red, code(className), code(interfaceClass.getName())));
+            }
+
+            return success;
+        };
+    } 
 }

src/main/java/engine/Texts.java

@@ -204,5 +204,8 @@ public class Texts {
     public static Localizable<String> EXPECTED_FIELD_TO_BE_OF_TYPE =
         local("Expected '%s' field in class %s to be a '%s', but it is a '%s'.")
         .fr("Attendu à ce que le champ '%s' dans la classe %s soit un '%s', mais il est un '%s'.");
+    public static Localizable<String> EXPECTED_CLASS_TO_IMPLEMENT =
+        local("Expected class %s to implement %s, but it does not.")
+        .fr("Attendu à ce la classe %s implémente %s, mais elle ne l'implémente pas.");
 
 }

src/main/java/engine/test/ReflectionAssertionsUnitTests.java

@@ -0,0 +1,41 @@
+package engine.test;
+
+import static engine.Assertions.assertImplementsInterface;
+import static engine.ConsoleFmt.code;
+import static engine.ConsoleFmt.format;
+import static engine.Localizable.global;
+
+import java.util.List;
+import java.util.function.IntConsumer;
+
+import engine.Koan;
+import engine.Localizable;
+import engine.ConsoleFmt.Formats;
+import engine.test.simulation.SomeInterface;
+import engine.test.simulation.StudentSolutions;
+
+import static engine.script.Expression.callKoanMethod;
+import static engine.Texts.*;
+import static engine.test.UnitTestExpectation.assertSuccess;
+import static engine.test.UnitTestExpectation.assertFailure;
+
+public class ReflectionAssertionsUnitTests {
+    private static Localizable<Class<?>> CLASS = global(StudentSolutions.class);
+    
+    public static final List<UnitTest> items = List.of(
+        new UnitTest(
+            new Koan(CLASS, global("implements interface"))
+                .beforeFirstTest(assertImplementsInterface("engine.test.simulation.SomeImplementation", SomeInterface.class))
+                .when(callKoanMethod("simpleConsoleOutput")),
+            assertSuccess()
+        ),
+        new UnitTest(
+            new Koan(CLASS, global("does not implement interface"))
+                .beforeFirstTest(assertImplementsInterface("engine.test.simulation.SomeImplementation", IntConsumer.class))
+                .when(callKoanMethod("simpleConsoleOutput")),
+            assertFailure(
+                new Line.Localized(format(EXPECTED_CLASS_TO_IMPLEMENT, Formats.Red, code("engine.test.simulation.SomeImplementation"), code("java.util.function.IntConsumer")))
+            )
+        )
+    );
+}

src/main/java/engine/test/TestRunner.java

@@ -10,7 +10,8 @@
 public class TestRunner {
     private static final List<List<UnitTest>> TO_RUN = List.of(
         ConsoleAssertionsUnitTests.items,
-        EqualityAssertionsUnitTests.items
+        EqualityAssertionsUnitTests.items,
+        ReflectionAssertionsUnitTests.items
     );
     private static final Map<Boolean, String> SUCCESS_WORDING = Map.of(
         true, "success",

src/main/java/engine/test/simulation/SomeImplementation.java

@@ -0,0 +1,8 @@
+package engine.test.simulation;
+
+public class SomeImplementation implements SomeInterface {
+    @Override
+    public int op(int a, int b) {
+        return a + b;
+    }
+}

src/main/java/engine/test/simulation/SomeInterface.java

@@ -0,0 +1,5 @@
+package engine.test.simulation;
+
+public interface SomeInterface {
+    int op(int a, int b);
+}

src/main/java/sensei/AboutInterfacesKoans.java

@@ -0,0 +1,55 @@
+package sensei;
+
+import static engine.Assertions.assertReturnValueEquals;
+import static engine.Assertions.assertConstructorIsInvokable;
+import static engine.Assertions.assertImplementsInterface;
+import static engine.Localizable.localClass;
+import static engine.script.Expression.newObject;
+import static sensei.Texts.*;
+
+import java.util.List;
+
+import bonuses.teachingmaterial.Combining;
+import engine.Koan;
+import engine.Localizable;
+
+
+public class AboutInterfacesKoans {
+    private static final Localizable<Class<?>> CLASS =
+        localClass(bonuses.english.AboutInterfaces.class)
+        .fr(bonuses.french.AboutInterfaces.class);
+
+    public static final List<Koan> koans = List.of(
+        new Koan(CLASS, FIRST_INTERFACE_IMPLEMENTATIONS)
+            .beforeFirstTest(
+                assertConstructorIsInvokable("numbers.AddNumbers"),
+                assertConstructorIsInvokable("numbers.MultiplyNumbers"),
+                assertImplementsInterface("numbers.AddNumbers", Combining.class),
+                assertImplementsInterface("numbers.MultiplyNumbers", Combining.class)
+            )
+            .when(
+                newObject("numbers.AddNumbers").call("combine", 5, 7)
+            )
+            .then(
+                assertReturnValueEquals(12)
+            )
+            .when(
+                newObject("numbers.AddNumbers").call("combine", 0, -1)
+            )
+            .then(
+                assertReturnValueEquals(-1)
+            )
+            .when(
+                newObject("numbers.MultiplyNumbers").call("combine", 5, 7)
+            )
+            .then(
+                assertReturnValueEquals(35)
+            )
+            .when(
+                newObject("numbers.MultiplyNumbers").call("combine", 0, -1)
+            )
+            .then(
+                assertReturnValueEquals(0)
+            )
+    );
+}