Anchors and __toString patch.

Changelog excerpt:
- Added support for __toString and for anchors to the YAML handler.
- Also updated some PHPDocs.

Changelog.txt

@@ -24,6 +24,9 @@ found at:
   values to the YAML handler, plus some additional aliases for true and false.
   Also updated some of the test files.
 
+- [2021.02.20; Maikuolan]: Added support for __toString and for anchors to the
+  YAML handler. Also updated some PHPDocs.
+
 === Version/Release 2.4.0 ===
 MINOR RELEASE.
 

src/ComplexStringHandler.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Complex string handler (last modified: 2020.06.11).
+ * Complex string handler (last modified: 2021.02.20).
  *
  * This file is a part of the "common classes package", utilised by a number of
  * packages and projects, including CIDRAM and phpMussel.
@@ -94,7 +94,11 @@ public function iterateClosure(callable $Closure, bool $Glue = false)
         }
     }
 
-    /** Recompile all data after all work has finished and return it. */
+    /**
+     * Recompile all data after all work has finished and return it.
+     *
+     * @return string
+     */
     public function recompile(): string
     {
         $Output = '';
@@ -109,7 +113,11 @@ public function recompile(): string
         return $Output;
     }
 
-    /** PHP's magic "__toString" method to act as an alias for "recompile". */
+    /**
+     * PHP's magic "__toString" method to act as an alias for "recompile".
+     *
+     * @return string
+     */
     public function __toString(): string
     {
         return $this->recompile();

src/YAML.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * YAML handler (last modified: 2021.02.19).
+ * YAML handler (last modified: 2021.02.20).
  *
  * This file is a part of the "common classes package", utilised by a number of
  * packages and projects, including CIDRAM and phpMussel.
@@ -13,10 +13,8 @@
  * (Maikuolan). Earliest iteration and deployment of "YAML handler" COPYRIGHT
  * 2016 and beyond by Caleb Mazalevskis (Maikuolan).
  *
- * Note: The YAML handler is intended to adequately serve the needs of the
- * packages and projects where it is implemented, but isn't a complete YAML
- * solution, instead supporting the YAML specification only to the bare minimum
- * required by those packages and projects known to implement it.
+ * Note: Some parts of the YAML specification isn't supported by this class.
+ * See the included documentation for more information.
  */
 
 namespace Maikuolan\Common;
@@ -48,6 +46,11 @@ class YAML
      */
     public $FoldedAt = 120;
 
+    /**
+     * @var array Used to cache any anchors found in the document.
+     */
+    public $Anchors = [];
+
     /**
      * Can optionally begin processing data as soon as the object is
      * instantiated, or just instantiate first, and manually make any needed
@@ -71,6 +74,26 @@ public function __construct(string $In = '')
      */
     private function normaliseValue(&$Value, int $ValueLen, $ValueLow)
     {
+        /** Check for anchors and populate if necessary. */
+        $AnchorMatches = [];
+        if (
+            preg_match('~^&([\dA-Za-z]+) +(.*)$~', $Value, $AnchorMatches) &&
+            isset($AnchorMatches[1], $AnchorMatches[2])
+        ) {
+            $Value = $AnchorMatches[2];
+            $this->Anchors[$AnchorMatches[1]] = $Value;
+            $ValueLen = strlen($Value);
+            $ValueLow = strtolower($Value);
+        } elseif (
+            preg_match('~^\*([\dA-Za-z]+)$~', $Value, $AnchorMatches) &&
+            isset($AnchorMatches[1], $this->Anchors[$AnchorMatches[1]])
+        ) {
+            $Value = $this->Anchors[$AnchorMatches[1]];
+            $ValueLen = strlen($Value);
+            $ValueLow = strtolower($Value);
+        }
+
+        /** Check for string quotes. */
         foreach ([
             ['"', '"', 1],
             ["'", "'", 1],
@@ -85,6 +108,7 @@ private function normaliseValue(&$Value, int $ValueLen, $ValueLow)
                 return;
             }
         }
+
         if ($ValueLow === 'true' || $ValueLow === 'y' || $Value === '+') {
             $Value = true;
         } elseif ($ValueLow === 'false' || $ValueLow === 'n' || $Value === '-') {
@@ -201,7 +225,11 @@ public function process(string $In, array &$Arr, int $Depth = 0): bool
      */
     private function processLine(string &$ThisLine, int &$ThisTab, &$Key, &$Value, array &$Arr): bool
     {
-        if (substr($ThisLine, -1) === ':' && strpos($ThisLine, ': ') === false) {
+        if ($ThisLine === '---') {
+            $Key = '---';
+            $Value = false;
+            $Arr[$Key] = $Value;
+        } elseif (substr($ThisLine, -1) === ':' && strpos($ThisLine, ': ') === false) {
             $Key = substr($ThisLine, $ThisTab, -1);
             $KeyLen = strlen($Key);
             $KeyLow = strtolower($Key);
@@ -317,4 +345,14 @@ public function reconstruct(array $Arr): string
         $this->processInner($Arr, $Out);
         return $Out . "\n";
     }
+
+    /**
+     * PHP's magic "__toString" method to act as an alias for "reconstruct".
+     *
+     * @return string
+     */
+    public function __toString(): string
+    {
+        return $this->reconstruct($this->Data);
+    }
 }