Make lexer/state stack more understandable

- rename lexer $mode property to avoid two different uses of "mode" variables in the lexer - clarify/improve comments
dokuwiki · May 23, 2018 · 661c1dd · 661c1dd
1 parent d9d27cd
commit 661c1dd
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 12 deletions.
diff --git a/inc/Parsing/Handler/CallWriterInterface.php b/inc/Parsing/Handler/CallWriterInterface.php
@@ -4,7 +4,27 @@
 
 interface CallWriterInterface
 {
+    /**
+     * Add a call to our call list
+     *
+     * @param $call     the call to be added
+     */
     public function writeCall($call);
+
+    /**
+     * Append a list of calls to our call list
+     *
+     * @param $calls     list of calls to be appended
+     */
     public function writeCalls($calls);
+
+    /**
+     * Explicit request to finish up and clean up NOW!
+     * (probably because document end has been reached)
+     *
+     * If part of a CallWriter chain, call finalise on
+     * the original call writer
+     *
+     */
     public function finalise();
 }
diff --git a/inc/Parsing/Handler/Nest.php b/inc/Parsing/Handler/Nest.php
@@ -20,7 +20,7 @@ class Nest implements ReWriterInterface
     /**
      * @inheritdoc
      *
-     * @param  CallWriterInterface $CallWriter     the renderers current call writer
+     * @param  CallWriterInterface $CallWriter     the parser's current call writer, i.e. the one above us in the chain
      * @param  string     $close          closing instruction name, this is required to properly terminate the
      *                                    syntax mode if the document ends without a closing pattern
      */

diff --git a/inc/Parsing/Lexer/Lexer.php b/inc/Parsing/Lexer/Lexer.php
@@ -30,7 +30,7 @@ class Lexer
     /** @var \Doku_Handler */
     protected $handler;
     /** @var StateStack */
-    protected $mode;
+    protected $modeStack;
     /** @var array mode "rewrites" */
     protected $mode_handlers;
     /** @var bool case sensitive? */
@@ -48,7 +48,7 @@ public function __construct($handler, $start = "accept", $case = false)
         $this->case = $case;
         $this->regexes = array();
         $this->handler = $handler;
-        $this->mode = new StateStack($start);
+        $this->modeStack = new StateStack($start);
         $this->mode_handlers = array();
     }
 
@@ -179,7 +179,7 @@ public function parse($raw)
      * @param int $matchPos Current byte index location in raw doc thats being parsed
      * @return boolean             False if there was any error from the parser.
      */
-    protected function dispatchTokens($unmatched, $matched, $mode = false, $initialPos, $matchPos)
+    protected function dispatchTokens($unmatched, $matched, $mode, $initialPos, $matchPos)
     {
         if (! $this->invokeHandler($unmatched, DOKU_LEXER_UNMATCHED, $initialPos)) {
             return false;
@@ -188,17 +188,17 @@ protected function dispatchTokens($unmatched, $matched, $mode = false, $initialP
             if (! $this->invokeHandler($matched, DOKU_LEXER_EXIT, $matchPos)) {
                 return false;
             }
-            return $this->mode->leave();
+            return $this->modeStack->leave();
         }
         if ($this->isSpecialMode($mode)) {
-            $this->mode->enter($this->decodeSpecial($mode));
+            $this->modeStack->enter($this->decodeSpecial($mode));
             if (! $this->invokeHandler($matched, DOKU_LEXER_SPECIAL, $matchPos)) {
                 return false;
             }
-            return $this->mode->leave();
+            return $this->modeStack->leave();
         }
         if (is_string($mode)) {
-            $this->mode->enter($mode);
+            $this->modeStack->enter($mode);
             return $this->invokeHandler($matched, DOKU_LEXER_ENTER, $matchPos);
         }
         return $this->invokeHandler($matched, DOKU_LEXER_MATCHED, $matchPos);
@@ -256,7 +256,7 @@ protected function invokeHandler($content, $is_match, $pos)
         if (($content === "") || ($content === false)) {
             return true;
         }
-        $handler = $this->mode->getCurrent();
+        $handler = $this->modeStack->getCurrent();
         if (isset($this->mode_handlers[$handler])) {
             $handler = $this->mode_handlers[$handler];
         }
@@ -282,13 +282,13 @@ protected function invokeHandler($content, $is_match, $pos)
      */
     protected function reduce(&$raw)
     {
-        if (! isset($this->regexes[$this->mode->getCurrent()])) {
+        if (! isset($this->regexes[$this->modeStack->getCurrent()])) {
             return false;
         }
         if ($raw === "") {
             return true;
         }
-        if ($action = $this->regexes[$this->mode->getCurrent()]->split($raw, $split)) {
+        if ($action = $this->regexes[$this->modeStack->getCurrent()]->split($raw, $split)) {
             list($unparsed, $match, $raw) = $split;
             return array($unparsed, $match, $action);
         }

diff --git a/inc/Parsing/Lexer/StateStack.php b/inc/Parsing/Lexer/StateStack.php
@@ -47,7 +47,7 @@ public function enter($state)
     /**
      * Leaves the current state and reverts
      * to the previous one.
-     * @return boolean    False if we drop off the bottom of the list.
+     * @return boolean    false if we attempt to drop off the bottom of the list.
      */
     public function leave()
     {