Sync matching-brackets (#736)

exercises/practice/matching-brackets/.docs/instructions.md

@@ -1,5 +1,5 @@
 # Instructions
 
-Given a string containing brackets `[]`, braces `{}`, parentheses `()`,
-or any combination thereof, verify that any and all pairs are matched
-and nested correctly.
+Given a string containing brackets `[]`, braces `{}`, parentheses `()`, or any combination thereof, verify that any and all pairs are matched and nested correctly.
+Any other characters should be ignored.
+For example, `"{what is (42)}?"` is balanced and `"[text}"` is not.

exercises/practice/matching-brackets/.docs/introduction.md

@@ -0,0 +1,8 @@
+# Introduction
+
+You're given the opportunity to write software for the Bracketeer™, an ancient but powerful mainframe.
+The software that runs on it is written in a proprietary language.
+Much of its syntax is familiar, but you notice _lots_ of brackets, braces and parentheses.
+Despite the Bracketeer™ being powerful, it lacks flexibility.
+If the source code has any unbalanced brackets, braces or parentheses, the Bracketeer™ crashes and must be rebooted.
+To avoid such a scenario, you start writing code that can verify that brackets, braces, and parentheses are balanced before attempting to run it on the Bracketeer™.

exercises/practice/matching-brackets/.meta/example.php

@@ -1,27 +1,5 @@
 <?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);
 
 function brackets_match(string $input): bool

exercises/practice/matching-brackets/.meta/tests.toml

@@ -1,6 +1,13 @@
-# This is an auto-generated file. Regular comments will be removed when this
-# file is regenerated. Regenerating will not touch any manually added keys,
-# so comments can be added in a "comment" key.
+# 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.
 
 [81ec11da-38dd-442a-bcf9-3de7754609a5]
 description = "paired square brackets"
@@ -41,12 +48,21 @@ description = "unpaired and nested brackets"
 [a0205e34-c2ac-49e6-a88a-899508d7d68e]
 description = "paired and wrong nested brackets"
 
+[1d5c093f-fc84-41fb-8c2a-e052f9581602]
+description = "paired and wrong nested brackets but innermost are correct"
+
 [ef47c21b-bcfd-4998-844c-7ad5daad90a8]
 description = "paired and incomplete brackets"
 
 [a4675a40-a8be-4fc2-bc47-2a282ce6edbe]
 description = "too many closing brackets"
 
+[a345a753-d889-4b7e-99ae-34ac85910d1a]
+description = "early unexpected brackets"
+
+[21f81d61-1608-465a-b850-baa44c5def83]
+description = "early mismatched brackets"
+
 [99255f93-261b-4435-a352-02bdecc9bdf2]
 description = "math expression"
 

exercises/practice/matching-brackets/MatchingBracketsTest.php

@@ -1,27 +1,5 @@
 <?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 MatchingBracketsTest extends PHPUnit\Framework\TestCase
@@ -31,66 +9,181 @@ public static function setUpBeforeClass(): void
         require_once 'MatchingBrackets.php';
     }
 
+    /**
+     * uuid 81ec11da-38dd-442a-bcf9-3de7754609a5
+     * @testdox Paired square brackets
+     */
     public function testPairedSquareBrackets(): void
     {
         $this->assertTrue(brackets_match('[]'));
     }
 
+    /**
+     * uuid 287f0167-ac60-4b64-8452-a0aa8f4e5238
+     * @testdox Empty string
+     */
     public function testEmptyString(): void
     {
         $this->assertTrue(brackets_match(''));
     }
 
+    /**
+     * uuid 6c3615a3-df01-4130-a731-8ef5f5d78dac
+     * @testdox Unpaired brackets
+     */
     public function testUnpairedBrackets(): void
     {
         $this->assertFalse(brackets_match('[['));
     }
 
+    /**
+     * uuid 9d414171-9b98-4cac-a4e5-941039a97a77
+     * @testdox Wrong ordered brackets
+     */
     public function testWrongOrderedBrackets(): void
     {
         $this->assertFalse(brackets_match('}{'));
     }
 
+    /**
+     * uuid f0f97c94-a149-4736-bc61-f2c5148ffb85
+     * @testdox Wrong closing bracket
+     */
+    public function testWrongClosingBracket(): void
+    {
+        $this->assertFalse(brackets_match('{]'));
+    }
+
+    /**
+     * uuid 754468e0-4696-4582-a30e-534d47d69756
+     * @testdox Paired with whitespace
+     */
     public function testPairedWithWhitespace(): void
     {
         $this->assertTrue(brackets_match('{ }'));
     }
 
+    /**
+     * uuid ba84f6ee-8164-434a-9c3e-b02c7f8e8545
+     * @testdox Partially paired brackets
+     */
+    public function testPartiallyPairedBrackets(): void
+    {
+        $this->assertFalse(brackets_match('{[])'));
+    }
+
+    /**
+     * uuid 3c86c897-5ff3-4a2b-ad9b-47ac3a30651d
+     * @testdox Simple nested brackets
+     */
     public function testSimpleNestedBrackets(): void
     {
         $this->assertTrue(brackets_match('{[]}'));
     }
 
+    /**
+     * uuid 2d137f2c-a19e-4993-9830-83967a2d4726
+     * @testdox Several paired brackets
+     */
     public function testSeveralPairedBrackets(): void
     {
         $this->assertTrue(brackets_match('{}[]'));
     }
 
+    /**
+     * uuid 2e1f7b56-c137-4c92-9781-958638885a44
+     * @testdox Paired and nested brackets
+     */
     public function testPairedAndNestedBrackets(): void
     {
         $this->assertTrue(brackets_match('([{}({}[])])'));
     }
 
+    /**
+     * uuid 84f6233b-e0f7-4077-8966-8085d295c19b
+     * @testdox Unopened closing brackets
+     */
     public function testUnopenedClosingBrackets(): void
     {
         $this->assertFalse(brackets_match('{[)][]}'));
     }
 
+    /**
+     * uuid 9b18c67d-7595-4982-b2c5-4cb949745d49
+     * @testdox Unpaired and nested brackets
+     */
     public function testUnpairedAndNestedBrackets(): void
     {
         $this->assertFalse(brackets_match('([{])'));
     }
 
+    /**
+     * uuid a0205e34-c2ac-49e6-a88a-899508d7d68e
+     * @testdox Paired and wrong nested brackets
+     */
     public function testPairedAndWrongNestedBrackets(): void
     {
         $this->assertFalse(brackets_match('[({]})'));
     }
 
+    /**
+     * uuid 1d5c093f-fc84-41fb-8c2a-e052f9581602
+     * @testdox Paired and wrong nested brackets but innermost are correct
+     */
+    public function testPairedAndWrongNestedBracketsButInnermostAreCorrect(): void
+    {
+        $this->assertFalse(brackets_match('[({}])'));
+    }
+
+    /**
+     * uuid ef47c21b-bcfd-4998-844c-7ad5daad90a8
+     * @testdox Paired and incomplete brackets
+     */
+    public function testPairedAndIncompleteBrackets(): void
+    {
+        $this->assertFalse(brackets_match('{}['));
+    }
+
+    /**
+     * uuid a4675a40-a8be-4fc2-bc47-2a282ce6edbe
+     * @testdox Too many closing brackets
+     */
+    public function testTooManyClosingBrackets(): void
+    {
+        $this->assertFalse(brackets_match('[]]'));
+    }
+
+    /**
+     * uuid a345a753-d889-4b7e-99ae-34ac85910d1a
+     * @testdox Early unexpected brackets
+     */
+    public function testEarlyUnexpectedBrackets(): void
+    {
+        $this->assertFalse(brackets_match(')()'));
+    }
+
+    /**
+     * uuid 21f81d61-1608-465a-b850-baa44c5def83
+     * @testdox Early mismatched brackets
+     */
+    public function testEarlyMismatchedBrackets(): void
+    {
+        $this->assertFalse(brackets_match('{)()'));
+    }
+
+    /**
+     * uuid 99255f93-261b-4435-a352-02bdecc9bdf2
+     * @testdox Math expression
+     */
     public function testMathExpression(): void
     {
         $this->assertTrue(brackets_match('(((185 + 223.85) * 15) - 543)/2'));
     }
 
+    /**
+     * uuid 8e357d79-f302-469a-8515-2561877256a1
+     * @testdox Complex latex expression
+     */
     public function testComplexLatexExpression(): void
     {
         $this->assertTrue(brackets_match(