Add save the cow exercise

config.json

@@ -1105,6 +1105,14 @@
           "transforming"
         ]
       },
+      {
+        "slug": "save-the-cow",
+        "name": "Save the Cow",
+        "uuid": "ec60632c-c682-4f72-87a7-8601c960165b",
+        "practices": [],
+        "prerequisites": [],
+        "difficulty": 4
+      },
       {
         "slug": "scale-generator",
         "name": "Scale Generator",

exercises/practice/save-the-cow/.docs/instructions.md

@@ -0,0 +1,7 @@
+# Instructions
+
+Implement the logic for a word-guessing game.
+
+A player tries to solve a secret word by guessing individual letters.
+They win if they reveal all the letters in the secret word.
+They lose if they make ten incorrect guesses before revealing the word.

exercises/practice/save-the-cow/.docs/introduction.md

@@ -0,0 +1,4 @@
+# Introduction
+
+Bessie the cow has wandered onto an alien spaceship.
+Guess the secret door code to bring her home before the ship blasts off.

exercises/practice/save-the-cow/.meta/config.json

@@ -0,0 +1,17 @@
+{
+  "authors": [
+    "resu-xuniL"
+  ],
+  "files": {
+    "solution": [
+      "SaveTheCow.php"
+    ],
+    "test": [
+      "SaveTheCowTest.php"
+    ],
+    "example": [
+      ".meta/example.php"
+    ]
+  },
+  "blurb": "Implement a word-guessing game."
+}

exercises/practice/save-the-cow/.meta/example.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+class SaveTheCow
+{
+    public function __construct(
+        private string $word,
+        public string $maskedWord = "",
+        public string $state = "Ongoing",
+        public int $remainingFailures = 9
+    ) {
+        $this->maskedWord = str_repeat("_", strlen($word));
+    }
+
+    public function guess(string $guess): void
+    {
+        if ($this->state === "Win") {
+            throw new Exception("cannot guess after the game is won");
+        } else if ($this->state === "Lose") {
+            throw new Exception("cannot guess after the game is lost");
+        }
+
+        if (str_contains($this->word, $guess) && ! str_contains($this->maskedWord, $guess)) {
+            for ($i = 0; $i < strlen($this->word); $i++) {
+                if ($this->word[$i] === $guess) {
+                    $this->maskedWord[$i] = $guess;
+                }
+            }
+            if (! str_contains($this->maskedWord, "_")) {
+                $this->state = "Win";
+            }
+        } else {
+            if ($this->remainingFailures === 0) {
+                $this->state = "Lose";
+            } else {
+                $this->remainingFailures--;
+            }
+        }
+    }
+}

exercises/practice/save-the-cow/.meta/tests.toml

@@ -0,0 +1,40 @@
+# This is an auto-generated file.
+#
+# Regenerating this file via `configlet sync` will:
+# - Recreate every `description` key/value pair
+# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
+# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
+# - Preserve any other key/value pair
+#
+# As user-added comments (using the # character) will be removed when this file
+# is regenerated, comments can be added via a `comment` key.
+
+[71d340f9-fc29-4826-872e-ad7d0b83dd98]
+description = "Initially 9 failures are allowed and no letters are guessed"
+
+[76759c24-8f1a-4fc8-9ffd-d6a1ff0cf03b]
+description = "After 10 failures the game is over"
+
+[d6f2e202-7857-46fb-b709-43a7f3f3b2de]
+description = "Losing with several correct guesses"
+
+[71bc0cda-2032-4637-80c8-fc8771124c08]
+description = "Feeding a correct letter removes underscores"
+
+[5b568a1c-867d-418f-97a8-7b6f8a7ca0a2]
+description = "Feeding a correct letter twice counts as a failure"
+
+[3d40f15b-0271-4c5d-b1a4-3e1f66ff221f]
+description = "Guessing a repeated letter reveals all instances"
+
+[11a86435-e401-4250-a26e-3b0d8c4049ad]
+description = "Getting all the letters right makes for a win"
+
+[b3d81876-84ee-45bb-b531-baa1b05b4709]
+description = "Winning on the last guess is still a win"
+
+[cf204398-5e9f-402f-8bff-42cb7cbbbda9]
+description = "Guessing after a lose is error"
+
+[c2ec5b3d-4923-4a0e-a485-6aa6e78c7ece]
+description = "Guessing after a win is error"

exercises/practice/save-the-cow/SaveTheCow.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * By adding type hints and enabling strict type checking, code can become
+ * easier to read, self-documenting and reduce the number of potential bugs.
+ * By default, type declarations are non-strict, which means they will attempt
+ * to change the original type to match the type specified by the
+ * type-declaration.
+ *
+ * In other words, if you pass a string to a function requiring a float,
+ * it will attempt to convert the string value to a float.
+ *
+ * To enable strict mode, a single declare directive must be placed at the top
+ * of the file.
+ * This means that the strictness of typing is configured on a per-file basis.
+ * This directive not only affects the type declarations of parameters, but also
+ * a function's return type.
+ *
+ * For more info review the Concept on strict type checking in the PHP track
+ * <link>.
+ *
+ * To disable strict typing, comment out the directive below.
+ */
+
+declare(strict_types=1);
+
+class SaveTheCow
+{
+    /**
+     * In PHP 8.4 and newer you can use Asymmetric Property Visibility to enhance data encapsulation
+     * @see https://www.php.net/manual/en/language.oop5.visibility.php#language.oop5.visibility-members-aviz
+     */
+    public function __construct(string $word)
+    {
+        throw new \BadMethodCallException("Please implement the SaveTheCow class!");
+    }
+}

exercises/practice/save-the-cow/SaveTheCowTest.php

@@ -0,0 +1,182 @@
+<?php
+
+declare(strict_types=1);
+
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+class SaveTheCowTest extends TestCase
+{
+    public static function setUpBeforeClass(): void
+    {
+        require_once 'SaveTheCow.php';
+    }
+
+    /**
+     * uuid: 71d340f9-fc29-4826-872e-ad7d0b83dd98
+     */
+    #[TestDox('Initially 9 failures are allowed and no letters are guessed')]
+    public function testInitiallyNineFailuresAreAllowedAndNoLettersAreGuessed(): void
+    {
+        $guesses = [];
+        $saveTheCow = new SaveTheCow("loot");
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+
+        $this->assertEquals("Ongoing", $saveTheCow->state);
+        $this->assertEquals("____", $saveTheCow->maskedWord);
+        $this->assertEquals(9, $saveTheCow->remainingFailures);
+    }
+
+    /**
+     * uuid: 76759c24-8f1a-4fc8-9ffd-d6a1ff0cf03b
+     */
+    #[TestDox('After 10 failures the game is over')]
+    public function testAfterTenFailuresTheGameIsOver(): void
+    {
+        $guesses = ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"];
+        $saveTheCow = new SaveTheCow("loot");
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+
+        $this->assertEquals("Lose", $saveTheCow->state);
+        $this->assertEquals("____", $saveTheCow->maskedWord);
+        $this->assertEquals(0, $saveTheCow->remainingFailures);
+    }
+
+    /**
+     * uuid: d6f2e202-7857-46fb-b709-43a7f3f3b2de
+     */
+    #[TestDox('Losing with several correct guesses')]
+    public function testLosingWithSeveralCorrectGuesses(): void
+    {
+        $guesses = ["t", "o", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j"];
+        $saveTheCow = new SaveTheCow("loot");
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+
+        $this->assertEquals("Lose", $saveTheCow->state);
+        $this->assertEquals("_oot", $saveTheCow->maskedWord);
+        $this->assertEquals(0, $saveTheCow->remainingFailures);
+    }
+
+    /**
+     * uuid: 71bc0cda-2032-4637-80c8-fc8771124c08
+     */
+    #[TestDox('Feeding a correct letter removes underscores')]
+    public function testFeedingACorrectLetterRemovesUnderscores(): void
+    {
+        $guesses = ["t"];
+        $saveTheCow = new SaveTheCow("loot");
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+
+        $this->assertEquals("Ongoing", $saveTheCow->state);
+        $this->assertEquals("___t", $saveTheCow->maskedWord);
+        $this->assertEquals(9, $saveTheCow->remainingFailures);
+    }
+
+    /**
+     * uuid: 5b568a1c-867d-418f-97a8-7b6f8a7ca0a2
+     */
+    #[TestDox('Feeding a correct letter twice counts as a failure')]
+    public function testFeedingACorrectLetterTwiceCountsAsAFailure(): void
+    {
+        $guesses = ["t", "t"];
+        $saveTheCow = new SaveTheCow("loot");
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+
+        $this->assertEquals("Ongoing", $saveTheCow->state);
+        $this->assertEquals("___t", $saveTheCow->maskedWord);
+        $this->assertEquals(8, $saveTheCow->remainingFailures);
+    }
+
+    /**
+     * uuid: 3d40f15b-0271-4c5d-b1a4-3e1f66ff221f
+     */
+    #[TestDox('Guessing a repeated letter reveals all instances')]
+    public function testGuessingARepeatedLetterRevealsAllInstances(): void
+    {
+        $guesses = ["t", "t", "o"];
+        $saveTheCow = new SaveTheCow("loot");
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+
+        $this->assertEquals("Ongoing", $saveTheCow->state);
+        $this->assertEquals("_oot", $saveTheCow->maskedWord);
+        $this->assertEquals(8, $saveTheCow->remainingFailures);
+    }
+
+    /**
+     * uuid: 11a86435-e401-4250-a26e-3b0d8c4049ad
+     */
+    #[TestDox('Getting all the letters right makes for a win')]
+    public function testGettingAllTheLettersRightMakesForAWin(): void
+    {
+        $guesses = ["t", "t", "o", "l"];
+        $saveTheCow = new SaveTheCow("loot");
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+
+        $this->assertEquals("Win", $saveTheCow->state);
+        $this->assertEquals("loot", $saveTheCow->maskedWord);
+        $this->assertEquals(8, $saveTheCow->remainingFailures);
+    }
+
+    /**
+     * uuid: b3d81876-84ee-45bb-b531-baa1b05b4709
+     */
+    #[TestDox('Winning on the last guess is still a win')]
+    public function testWinningOnTheLastGuessIsStillAWin(): void
+    {
+        $guesses = ["a", "b", "c", "d", "e", "f", "g", "h", "i", "t", "o", "l"];
+        $saveTheCow = new SaveTheCow("loot");
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+
+        $this->assertEquals("Win", $saveTheCow->state);
+        $this->assertEquals("loot", $saveTheCow->maskedWord);
+        $this->assertEquals(0, $saveTheCow->remainingFailures);
+    }
+
+    /**
+     * uuid: cf204398-5e9f-402f-8bff-42cb7cbbbda9
+     */
+    #[TestDox('Guessing after a lose is error')]
+    public function testGuessingAfterALoseIsError(): void
+    {
+        $guesses = ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"];
+        $saveTheCow = new SaveTheCow("loot");
+
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('cannot guess after the game is lost');
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+    }
+
+    /**
+     * uuid: c2ec5b3d-4923-4a0e-a485-6aa6e78c7ece
+     */
+    #[TestDox('Guessing after a win is error')]
+    public function testGuessingAfterAWinIsError(): void
+    {
+        $guesses = ["t", "o", "l", "l"];
+        $saveTheCow = new SaveTheCow("loot");
+
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('cannot guess after the game is won');
+        foreach ($guesses as $guess) {
+            $saveTheCow->guess($guess);
+        }
+    }
+}