Merge branch 'exercism:main' into sync-secret-handshake

.github/workflows/exercise-lint-phpcs-psr-12.yml

@@ -20,7 +20,7 @@ jobs:
     steps:
       - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
 
-      - uses: shivammathur/setup-php@fc14643b0a99ee9db10a3c025a33d76544fa3761
+      - uses: shivammathur/setup-php@2e947f1f6932d141d076ca441d0e1e881775e95b
         with:
           php-version: ${{ matrix.php-version }}
           extensions: gmp

.github/workflows/exercise-tests-phpunit-10.yml

@@ -26,7 +26,7 @@ jobs:
 
       - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
 
-      - uses: shivammathur/setup-php@fc14643b0a99ee9db10a3c025a33d76544fa3761
+      - uses: shivammathur/setup-php@2e947f1f6932d141d076ca441d0e1e881775e95b
         with:
           php-version: ${{ matrix.php-version }}
           extensions: gmp

exercises/practice/acronym/.docs/instructions.md

@@ -4,5 +4,14 @@ Convert a phrase to its acronym.
 
 Techies love their TLA (Three Letter Acronyms)!
 
-Help generate some jargon by writing a program that converts a long name
-like Portable Network Graphics to its acronym (PNG).
+Help generate some jargon by writing a program that converts a long name like Portable Network Graphics to its acronym (PNG).
+
+Punctuation is handled as follows: hyphens are word separators (like whitespace); all other punctuation can be removed from the input.
+
+For example:
+
+| Input                     | Output |
+| ------------------------- | ------ |
+| As Soon As Possible       | ASAP   |
+| Liquid-crystal display    | LCD    |
+| Thank George It's Friday! | TGIF   |

exercises/practice/acronym/.meta/config.json

@@ -20,7 +20,7 @@
       ".meta/example.php"
     ]
   },
-  "blurb": "Convert a long phrase to its acronym",
+  "blurb": "Convert a long phrase to its acronym.",
   "source": "Julien Vanier",
   "source_url": "https://github.com/monkbroc"
 }

exercises/practice/acronym/.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);
 
 /**

exercises/practice/acronym/.meta/tests.toml

@@ -25,6 +25,11 @@ description = "consecutive delimiters"
 
 [5118b4b1-4572-434c-8d57-5b762e57973e]
 description = "apostrophes"
+included = false
+comment = "This invalidates existing solutions that rely on RegExp word boundary detection"
 
 [adc12eab-ec2d-414f-b48c-66a4fc06cdef]
 description = "underscore emphasis"
+included = false
+comment = "This also invalidates existing solutions that rely on RegExp word boundary detection"
+

exercises/practice/acronym/AcronymTest.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 AcronymTest extends PHPUnit\Framework\TestCase
@@ -31,41 +9,66 @@ public static function setUpBeforeClass(): void
         require_once 'Acronym.php';
     }
 
+    /**
+     * @testdox Basic
+     * uuid: 1e22cceb-c5e4-4562-9afe-aef07ad1eaf4
+     */
     public function testBasicTitleCase(): void
     {
         $this->assertEquals('PNG', acronym('Portable Network Graphics'));
     }
 
+    /**
+     * @testdox Lowercase words
+     * uuid: 79ae3889-a5c0-4b01-baf0-232d31180c08
+     */
     public function testLowerCaseWord(): void
     {
         $this->assertEquals('ROR', acronym('Ruby on Rails'));
     }
 
-    public function testCamelCase(): void
+    /**
+     * @testdox Punctuation
+     * uuid: ec7000a7-3931-4a17-890e-33ca2073a548
+     */
+    public function testPunctuation(): void
     {
-        $this->assertEquals('HTML', acronym('HyperText Markup Language'));
+        $this->assertEquals('FIFO', acronym('First In, First Out'));
     }
 
+    /**
+     * @testdox All caps word
+     * uuid: 32dd261c-0c92-469a-9c5c-b192e94a63b0
+     */
     public function testAllCapsWords(): void
     {
-        $this->assertEquals('PHP', acronym('PHP: Hypertext Preprocessor'));
+        $this->assertEquals('GIMP', acronym('GNU Image Manipulation Program'));
     }
 
+    /**
+     * @testdox Punctuation without whitespace
+     * uuid: ae2ac9fa-a606-4d05-8244-3bcc4659c1d4
+     */
     public function testHyphenated(): void
     {
         $this->assertEquals('CMOS', acronym('Complementary metal-oxide semiconductor'));
     }
 
-    // Additional points for making the following tests pass
-
-    public function testOneWordIsNotAbbreviated(): void
+    /**
+     * @testdox Very long abbreviation
+     * uuid: 0e4b1e7c-1a6d-48fb-81a7-bf65eb9e69f9
+     */
+    public function testVeryLongAbbreviation(): void
     {
-        $this->assertEmpty(acronym('Word'));
+        $this->assertEquals('ROTFLSHTMDCOALM', acronym('Rolling On The Floor Laughing So Hard That My Dogs Came Over And Licked Me'));
     }
 
-    public function testUnicode(): void
+    /**
+     * @testdox Consecutive delimiters
+     * uuid: 6a078f49-c68d-4b7b-89af-33a1a98c28cc
+     */
+    public function testConsecutiveDelimiters(): void
     {
-        $phrase = 'Специализированная процессорная часть';
-        $this->assertEquals('СПЧ', acronym($phrase));
+        $this->assertEquals('SIMUFTA', acronym('Something - I made up from thin air'));
     }
 }

exercises/practice/circular-buffer/.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);
 
 class BufferFullError extends Exception

exercises/practice/circular-buffer/CircularBufferTest.php

@@ -9,6 +9,7 @@
 class CircularBufferTest extends TestCase
 {
     /**
+     * @testdox reading empty buffer should fail
      * uuid: 28268ed4-4ff3-45f3-820e-895b44d53dfa
      */
     public function testReadingEmptyBufferShouldFail(): void
@@ -19,6 +20,7 @@ public function testReadingEmptyBufferShouldFail(): void
     }
 
     /**
+     * @testdox can read an item just written
      * uuid: 2e6db04a-58a1-425d-ade8-ac30b5f318f3
      */
     public function testCanReadAnItemJustWritten(): void
@@ -29,6 +31,7 @@ public function testCanReadAnItemJustWritten(): void
     }
 
     /**
+     * @testdox each item may only be read once
      * uuid: 90741fe8-a448-45ce-be2b-de009a24c144
      */
     public function testEachItemMayOnlyBeReadOnce(): void
@@ -41,6 +44,7 @@ public function testEachItemMayOnlyBeReadOnce(): void
     }
 
     /**
+     * @testdox items are read in the order they are written
      * uuid: be0e62d5-da9c-47a8-b037-5db21827baa7
      */
     public function testItemsAreReadInTheOrderTheyAreWritten(): void
@@ -53,6 +57,7 @@ public function testItemsAreReadInTheOrderTheyAreWritten(): void
     }
 
     /**
+     * @testdox full buffer can't be written to
      * uuid: 2af22046-3e44-4235-bfe6-05ba60439d38
      */
     public function testFullBufferCantBeWrittenTo(): void
@@ -64,6 +69,7 @@ public function testFullBufferCantBeWrittenTo(): void
     }
 
     /**
+     * @testdox a read frees up capacity for another write
      * uuid: 547d192c-bbf0-4369-b8fa-fc37e71f2393
      */
     public function testAReadFreesUpCapacityForAnotherWrite(): void
@@ -76,6 +82,7 @@ public function testAReadFreesUpCapacityForAnotherWrite(): void
     }
 
     /**
+     * @testdox read position is maintained even across multiple writes
      * uuid: 04a56659-3a81-4113-816b-6ecb659b4471
      */
     public function testReadPositionIsMaintainedEvenAcrossMultipleWrites(): void
@@ -90,6 +97,7 @@ public function testReadPositionIsMaintainedEvenAcrossMultipleWrites(): void
     }
 
     /**
+     * @testdox items cleared out of buffer can't be read
      * uuid: 60c3a19a-81a7-43d7-bb0a-f07242b1111f
      */
     public function testItemsClearedOutOfBufferCantBeRead(): void
@@ -102,6 +110,7 @@ public function testItemsClearedOutOfBufferCantBeRead(): void
     }
 
     /**
+     * @testdox clear frees up capacity for another write
      * uuid: 45f3ae89-3470-49f3-b50e-362e4b330a59
      */
     public function testClearFreesUpCapacityForAnotherWrite(): void
@@ -114,6 +123,7 @@ public function testClearFreesUpCapacityForAnotherWrite(): void
     }
 
     /**
+     * @testdox clear does nothing on empty buffer
      * uuid: e1ac5170-a026-4725-bfbe-0cf332eddecd
      */
     public function testClearDoesNothingOnEmptyBuffer(): void
@@ -125,9 +135,10 @@ public function testClearDoesNothingOnEmptyBuffer(): void
     }
 
     /**
+     * @testdox overwrite acts like write on non-full buffer
      * uuid: 9c2d4f26-3ec7-453f-a895-7e7ff8ae7b5b
      */
-    public function testForceWriteActsLikeWriteOnNonFullBuffer(): void
+    public function testOverwriteActsLikeWriteOnNonFullBuffer(): void
     {
         $buffer = new CircularBuffer(2);
         $buffer->write('1');
@@ -137,9 +148,10 @@ public function testForceWriteActsLikeWriteOnNonFullBuffer(): void
     }
 
     /**
+     * @testdox overwrite replaces the oldest item on full buffer
      * uuid: 880f916b-5039-475c-bd5c-83463c36a147
      */
-    public function testForceWriteReplacesTheOldestItemOnFullBuffer(): void
+    public function testOverwriteReplacesTheOldestItemOnFullBuffer(): void
     {
         $buffer = new CircularBuffer(2);
         $buffer->write('1');
@@ -150,9 +162,10 @@ public function testForceWriteReplacesTheOldestItemOnFullBuffer(): void
     }
 
     /**
+     * @testdox overwrite replaces the oldest item remaining in buffer following a read
      * uuid: bfecab5b-aca1-4fab-a2b0-cd4af2b053c3
      */
-    public function testForceWriteReplacesTheOldestItemRemainingInBufferFollowingARead(): void
+    public function testOverwriteReplacesTheOldestItemRemainingInBufferFollowingARead(): void
     {
         $buffer = new CircularBuffer(3);
         $buffer->write('1');
@@ -167,6 +180,7 @@ public function testForceWriteReplacesTheOldestItemRemainingInBufferFollowingARe
     }
 
     /**
+     * @testdox initial clear does not affect wrapping around
      * uuid: 9cebe63a-c405-437b-8b62-e3fdc1ecec5a
      */
     public function testInitialClearDoesNotAffectWrappingAround(): void

exercises/practice/spiral-matrix/.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);
 
 class SpiralMatrix