Add MazeGenerator exercise and related tests

exercises/practice/mazy-mice/.docs/hints.md

@@ -0,0 +1,23 @@
+# placeholder
+
+## Maze generation
+
+You can use any algorithm to generate a perfect maze. The [recursive backtracker][recursive-backtracker] is a good choice.
+
+## Box drawing characters
+
+| Character | Name                                  | Unicode |
+|:---------:|:--------------------------------------|:--------|
+|     ┌     | box drawings light down and right     |  U+250C |
+|     ─     | box drawings light horizontal         |  U+2500 |
+|     ┬     | box drawings light down and horizontal|  U+252C |
+|     ┐     | box drawings light down and left      |  U+2510 |
+|     │     | box drawings light vertical           |  U+2502 |
+|     └     | box drawings light up and right       |  U+2514 |
+|     ┴     | box drawings light up and horizontal  |  U+2534 |
+|     ┘     | box drawings light up and left        |  U+2518 |
+|     ├     | box drawings light vertical and right |  U+2520 |
+|     ⇨     | rightwards white arrow                |  U+21E8 |
+
+
+[recursive-backtracker]: https://en.wikipedia.org/wiki/Maze_generation_algorithm

exercises/practice/mazy-mice/.docs/instructions.md

@@ -0,0 +1,48 @@
+## Instructions
+
+Your task is to generate the perfect mazes for Mickey and Minerva — those with only one solution and no isolated sections.
+Here's what you need to know:
+
+- The maze has a rectangular shape with an opening at the start and end.
+- The maze has rooms and passages, which intersect at right angles.
+- The program should accept two parameters: rows and columns. The maze should be between 5 and 100 cells in size.
+- A maze which is `x` columns wide and `y` rows high should be `2x + 1` characters wide and `2y + 1` characters high.
+- If no seed is provided, generate a random maze. If the same seed is provided multiple times, the resulting maze should be the same each time.
+- Use [box-drawing][Box-drawing] characters to draw walls, and an arrow symbol (⇨) for the entrance on the left and exit on the right.
+
+It's time to create some perfect mazes for these adventurous mice!
+
+### Examples
+
+1. The small square maze 5x5 cells (or 11x11 characters)
+```text
+	┌───────┬─┐
+	│       │ │
+	│ ┌─┬── │ │
+	│ │ │   │ ⇨
+	│ │ │ ──┤ │
+	⇨ │ │   │ │
+	┌─┤ └── │ │
+	│ │     │ │
+	│ │ ────┘ │
+	│         │
+	└─────────┘
+```
+2. The rectangular maze 6x18 cells
+```text
+	┌───────────┬─────────┬───────────┬─┐
+	│           │         │           │ │
+	│ ┌───────┐ │ ┌─┐ ──┐ └───┐ ┌───┐ │ │
+	│ │       │ │ │ │   │     │ │   │   ⇨
+	│ └─┐ ┌─┐ │ │ │ ├── ├───┐ │ │ ──┼── │
+	│   │ │ │   │   │   │   │ │ │   │   │
+	└── │ │ ├───┴───┤ ┌─┘ ┌─┘ │ ├── │ ──┤
+	⇨   │   │       │ │   │   │ │   │   │
+	┌─┬─┴─┐ └─┐ ┌─┐ │ └─┐ │ ┌─┘ │ ──┴─┐ │
+	│ │   │   │ │ │ │   │   │   │     │ │
+	│ │ │ └── │ │ │ └── │ ──┘ ┌─┘ ──┐ │ │
+	│   │       │       │     │     │   │
+	└───┴───────┴───────┴─────┴─────┴───┘
+```
+
+[Box-drawing]: https://en.wikipedia.org/wiki/Box-drawing_character

exercises/practice/mazy-mice/.docs/introduction.md

@@ -0,0 +1,3 @@
+# Introduction
+
+Meet Mickey and Minerva, two clever mice who love to navigate their way through a maze to find cheese. They enjoy a good challenge, but with only their tiny mouse brains, they prefer if there is only one correct path to the cheese.

exercises/practice/mazy-mice/.meta/config.json

@@ -0,0 +1,19 @@
+{
+  "authors": [
+    "rabestro"
+  ],
+  "files": {
+    "solution": [
+      "src/main/java/MazeGenerator.java"
+    ],
+    "test": [
+      "src/test/java/MazeGeneratorTest.java"
+    ],
+    "example": [
+      ".meta/src/reference/java/MazeGenerator.java"
+    ]
+  },
+  "blurb": "Meet Mickey and Minerva, two clever mice who love to navigate their way through a maze to find cheese. They enjoy a good challenge, but with only their tiny mouse brains, they prefer if there is only one correct path to the cheese.",
+  "source": "Inspired by the 'Maze Generator' created by Jan Boström at Alance AB.",
+  "source_url": "https://mazegenerator.net/"
+}

exercises/practice/mazy-mice/.meta/src/reference/java/Dimensions.java

@@ -0,0 +1,25 @@
+/**
+ * Represents the dimensions of a maze.
+ * <p>
+ * Dimensions of a grid can be represented in cells or characters.
+ * Rows and columns are used for cells, while width and height are used for characters.
+ */
+public record Dimensions(int rows, int columns) {
+    /**
+     * Returns the width of the maze in characters.
+     *
+     * @return the width of the maze
+     */
+    int width() {
+        return 2 * columns + 1;
+    }
+
+    /**
+     * Returns the height of the maze in characters.
+     *
+     * @return the height of the maze
+     */
+    int height() {
+        return 2 * rows + 1;
+    }
+}

exercises/practice/mazy-mice/.meta/src/reference/java/MazeGenerator.java

@@ -0,0 +1,177 @@
+import java.util.Random;
+import java.util.random.RandomGenerator;
+import java.util.BitSet;
+import java.util.EnumSet;
+import java.util.Set;
+
+import static java.util.stream.IntStream.range;
+
+public class MazeGenerator {
+
+    public char[][] generatePerfectMaze(Dimensions dimensions) {
+        return new Grid(dimensions, RandomGenerator.getDefault())
+                .generateMaze()
+                .placeDoors()
+                .print();
+    }
+
+    public char[][] generatePerfectMaze(Dimensions dimensions, int seed) {
+        return new Grid(dimensions, new Random(seed))
+                .generateMaze()
+                .placeDoors()
+                .print();
+    }
+}
+
+enum Direction {
+    NORTH(0, 1),
+    EAST(1, 0),
+    SOUTH(0, -1),
+    WEST(-1, 0);
+    private final int dx;
+    private final int dy;
+
+    Direction(int dx, int dy) {
+        this.dx = dx;
+        this.dy = dy;
+    }
+
+    public int dx() {
+        return dx;
+    }
+
+    public int dy() {
+        return dy;
+    }
+}
+
+final class Grid {
+    private final Dimensions dimensions;
+    private final BitSet grid;
+    private final RandomGenerator randomGenerator;
+
+    Grid(Dimensions dimensions, RandomGenerator randomGenerator) {
+        this.dimensions = dimensions;
+        this.grid = new BitSet(dimensions.width() * dimensions.height());
+        this.randomGenerator = randomGenerator;
+    }
+
+    Grid generateMaze() {
+        generate(new Cell(1, 1));
+        return this;
+    }
+
+    private int random(int bound) {
+        return randomGenerator.nextInt(bound);
+    }
+
+    private Direction pickRandomDirection(Set<Direction> directions) {
+        int size = directions.size();
+        int itemIndex = random(size);
+        var direction = directions.toArray(new Direction[size])[itemIndex];
+        directions.remove(direction);
+        return direction;
+    }
+
+    Grid placeDoors() {
+        new Cell(1 + 2 * random(dimensions.rows()), 0).erase();
+        new Cell(1 + 2 * random(dimensions.rows()), dimensions.width() - 1).erase();
+        return this;
+    }
+
+    private void generate(Cell cell) {
+        cell.erase();
+
+        var directions = EnumSet.allOf(Direction.class);
+        do {
+            var direction = pickRandomDirection(directions);
+            var wall = cell.move(direction);
+            var next = wall.move(direction);
+            if (next.isValid() && next.isNotEmpty()) {
+                wall.erase();
+                generate(next);
+            }
+        } while (!directions.isEmpty());
+    }
+
+    char[][] print() {
+        return range(0, dimensions.height())
+                .mapToObj(this::line)
+                .toArray(char[][]::new);
+    }
+
+    private char[] line(int x) {
+        return range(0, dimensions.width())
+                .map(y -> new Cell(x, y).symbol())
+                .collect(StringBuilder::new, StringBuilder::appendCodePoint, StringBuilder::append)
+                .toString()
+                .toCharArray();
+    }
+
+    private final class Cell {
+        final int x;
+        final int y;
+
+        private Cell(int x, int y) {
+            this.x = x;
+            this.y = y;
+        }
+
+        boolean isValid() {
+            return x > 0 && x < dimensions.height() && y > 0 && y < dimensions.width();
+        }
+
+        void erase() {
+            grid.set(index());
+        }
+
+        boolean isNotEmpty() {
+            return !isEmpty();
+        }
+
+        boolean isEmpty() {
+            return grid.get(index());
+        }
+
+        int index() {
+            return x * dimensions.width() + y;
+        }
+
+        boolean isDoor() {
+            return isEmpty() && (y == 0 || y == dimensions.width() - 1);
+        }
+
+        Cell move(Direction direction) {
+            return new Cell(x + direction.dx(), y + direction.dy());
+        }
+
+        char symbol() {
+            if (isDoor()) {
+                return '⇨';
+            }
+            if (isEmpty()) {
+                return ' ';
+            }
+            var n = x > 0 && new Cell(x - 1, y).isNotEmpty() ? 1 : 0;
+            var e = y < dimensions.width() - 1 && new Cell(x, y + 1).isNotEmpty() ? 1 : 0;
+            var s = x < dimensions.height() - 1 && new Cell(x + 1, y).isNotEmpty() ? 1 : 0;
+            var w = y > 0 && new Cell(x, y - 1).isNotEmpty() ? 1 : 0;
+            var i = n + 2 * e + 4 * s + 8 * w;
+            return switch (i) {
+                case 0 -> ' ';
+                case 1, 5, 4 -> '│';
+                case 2, 8, 10 -> '─';
+                case 3 -> '└';
+                case 6 -> '┌';
+                case 7 -> '├';
+                case 9 -> '┘';
+                case 11 -> '┴';
+                case 12 -> '┐';
+                case 13 -> '┤';
+                case 14 -> '┬';
+                case 15 -> '┼';
+                default -> throw new IllegalStateException("Unexpected value: " + i);
+            };
+        }
+    }
+}

exercises/practice/mazy-mice/.meta/version

@@ -0,0 +1 @@
+1.0.0

exercises/practice/mazy-mice/build.gradle

@@ -0,0 +1,24 @@
+apply plugin: "java"
+apply plugin: "eclipse"
+apply plugin: "idea"
+
+// set default encoding to UTF-8
+compileJava.options.encoding = "UTF-8"
+compileTestJava.options.encoding = "UTF-8"
+
+repositories {
+  mavenCentral()
+}
+
+dependencies {
+  testImplementation "junit:junit:4.13"
+  testImplementation "org.assertj:assertj-core:3.15.0"
+}
+
+test {
+  testLogging {
+    exceptionFormat = 'full'
+    showStandardStreams = true
+    events = ["passed", "failed", "skipped"]
+  }
+}

exercises/practice/mazy-mice/src/main/java/Dimensions.java

@@ -0,0 +1,25 @@
+/**
+ * Represents the dimensions of a maze.
+ * <p>
+ * Dimensions of a grid can be represented in cells or characters.
+ * Rows and columns are used for cells, while width and height are used for characters.
+ */
+public record Dimensions(int rows, int columns) {
+    /**
+     * Returns the width of the maze in characters.
+     *
+     * @return the width of the maze
+     */
+    int width() {
+        return 2 * columns + 1;
+    }
+
+    /**
+     * Returns the height of the maze in characters.
+     *
+     * @return the height of the maze
+     */
+    int height() {
+        return 2 * rows + 1;
+    }
+}

exercises/practice/mazy-mice/src/main/java/MazeGenerator.java

@@ -0,0 +1,10 @@
+public class MazeGenerator {
+
+    public char[][] generatePerfectMaze(Dimensions dimensions) {
+        return null;
+    }
+
+    public char[][] generatePerfectMaze(Dimensions dimensions, int seed) {
+        return null;
+    }
+}