Implement nested error collection with start() and end() in ErrorCollector.

Signed-off-by: Edward Z. Yang <edwardzyang@thewritingpot.com>

configdoc/usage.xml

@@ -85,7 +85,7 @@
  </directive>
  <directive id="Core.MaintainLineNumbers">
   <file name="HTMLPurifier/ErrorCollector.php">
-   <line>81</line>
+   <line>148</line>
   </file>
   <file name="HTMLPurifier/Lexer.php">
    <line>82</line>

library/HTMLPurifier/ErrorCollector.php

@@ -7,7 +7,18 @@
 class HTMLPurifier_ErrorCollector
 {
     
-    protected $errors = array();
+    /**
+     * Identifiers for the returned error array. These are purposely numeric
+     * so list() can be used.
+     */
+    const LINENO   = 0;
+    const SEVERITY = 1;
+    const MESSAGE  = 2;
+    const CHILDREN = 3;
+    
+    protected $errors;
+    protected $_current;
+    protected $_stacks = array(array());
     protected $locale;
     protected $generator;
     protected $context;
@@ -16,13 +27,16 @@ class HTMLPurifier_ErrorCollector
         $this->locale    =& $context->get('Locale');
         $this->generator =& $context->get('Generator');
         $this->context   = $context;
+        $this->_current  =& $this->_stacks[0];
+        $this->errors   =& $this->_stacks[0];
     }
     
     /**
      * Sends an error message to the collector for later use
-     * @param $line Integer line number, or HTMLPurifier_Token that caused error
      * @param $severity int Error severity, PHP error style (don't use E_USER_)
      * @param $msg string Error message text
+     * @param $subst1 string First substitution for $msg
+     * @param $subst2 string ...
      */
     public function send($severity, $msg) {
         
@@ -55,13 +69,65 @@ class HTMLPurifier_ErrorCollector
         
         if (!empty($subst)) $msg = strtr($msg, $subst);
         
-        $this->errors[] = array($line, $severity, $msg);
+        // (numerically indexed)
+        $this->_current[] = array(
+            self::LINENO   => $line,
+            self::SEVERITY => $severity,
+            self::MESSAGE  => $msg,
+            self::CHILDREN => array()
+        );
+    }
+    
+    /**
+     * Begins the collection of a number of sub-errors. This is useful if you
+     * are entering a function that may generate errors, but you are able
+     * to detect the overall state afterwards.
+     */
+    public function start() {
+        $this->_stacks[] = array();
+        $this->_resetCurrent();
+    }
+    
+    /**
+     * Terminates the collection of sub-errors, interface is otherwise identical
+     * to send(). Any sub-errors will be registered as children (3) to this
+     * error.
+     * 
+     * @param $severity int Error severity
+     * @param $msg string Error message text
+     * @param $subst1 string First substitution for $msg
+     * @param $subst2 string ...
+     * 
+     * @note If end() is called with no parameters, it is quiet unless there
+     *       were sub-errors.
+     */
+    public function end() {
+        $stack = array_pop($this->_stacks);
+        $this->_resetCurrent();
+        $args = func_get_args();
+        if ($args) {
+            call_user_func_array(array($this, 'send'), $args);
+        } elseif ($stack) {
+            $this->send(E_NOTICE, 'ErrorCollector: Incidental errors');
+        }
+        if ($stack) {
+            $this->_current[count($this->_current) - 1][3] = $stack;
+        }
+    }
+    
+    /**
+     * Resets the _current member variable to the top of the stacks; i.e.
+     * the active set of errors being collected.
+     */
+    protected function _resetCurrent() {
+        $this->_current =& $this->_stacks[count($this->_stacks) - 1];
     }
     
     /**
      * Retrieves raw error data for custom formatter to use
-     * @param List of arrays in format of array(Error message text,
+     * @param List of arrays in format of array(line of error,
-     *        token that caused error, tokens surrounding token)
+     *        error severity, error message,
+     *        recursive sub-errors array)
      */
     public function getRaw() {
         return $this->errors;
@@ -70,11 +136,12 @@ class HTMLPurifier_ErrorCollector
     /**
      * Default HTML formatting implementation for error messages
      * @param $config Configuration array, vital for HTML output nature
+     * @param $errors Errors array to display; used for recursion.
      */
-    public function getHTMLFormatted($config) {
+    public function getHTMLFormatted($config, $errors = null) {
         $ret = array();
         
-        $errors = $this->errors;
+        if ($errors === null) $errors = $this->errors;
         
         // sort error array by line
         // line numbers are enabled if they aren't explicitly disabled
@@ -83,15 +150,15 @@ class HTMLPurifier_ErrorCollector
             $lines          = array();
             $original_order = array();
             foreach ($errors as $i => $error) {
-                $has_line[] = (int) (bool) $error[0];
+                $has_line[] = (int) (bool) $error[self::LINENO];
-                $lines[] = $error[0];
+                $lines[] = $error[self::LINENO];
                 $original_order[] = $i;
             }
             array_multisort($has_line, SORT_DESC, $lines, SORT_ASC, $original_order, SORT_ASC, $errors);
         }
         
         foreach ($errors as $error) {
-            list($line, $severity, $msg) = $error;
+            list($line, $severity, $msg, $children) = $error;
             $string = '';
             $string .= '<strong>' . $this->locale->getErrorName($severity) . '</strong>: ';
             $string .= $this->generator->escape($msg); 
@@ -101,6 +168,9 @@ class HTMLPurifier_ErrorCollector
                 $string .= $this->locale->formatMessage(
                     'ErrorCollector: At line', array('line' => $line));
             }
+            if ($children) {
+                $string .= $this->getHTMLFormatted($config, $children);
+            }
             $ret[] = $string;
         }
         

library/HTMLPurifier/Language/messages/en.php

@@ -15,7 +15,8 @@ $messages = array(
 'Item separator last' => ' and ', // non-Harvard style
 
 'ErrorCollector: No errors' => 'No errors detected. However, because error reporting is still incomplete, there may have been errors that the error collector was not notified of; please inspect the output HTML carefully.',
-'ErrorCollector: At line' => ' at line $line',
+'ErrorCollector: At line'   => ' at line $line',
+'ErrorCollector: Incidental errors'  => 'Incidental errors',
 
 'Lexer: Unclosed comment'      => 'Unclosed comment',
 'Lexer: Unescaped lt'          => 'Unescaped less-than sign (<) should be &lt;',
@@ -52,8 +53,8 @@ $messages = array(
 );
 
 $errorNames = array(
-    E_ERROR => 'Error',
+    E_ERROR   => 'Error',
     E_WARNING => 'Warning',
-    E_NOTICE => 'Notice'
+    E_NOTICE  => 'Notice'
 );
 

tests/HTMLPurifier/ErrorCollectorTest.php

@@ -3,130 +3,175 @@
 class HTMLPurifier_ErrorCollectorTest extends HTMLPurifier_Harness
 {
     
+    protected $language, $generator, $line;
+    protected $collector;
+    
     public function setup() {
         generate_mock_once('HTMLPurifier_Language');
         generate_mock_once('HTMLPurifier_Generator');
         parent::setup();
+        $this->language  = new HTMLPurifier_LanguageMock();
+        $this->language->setReturnValue('getErrorName',  'Error',   array(E_ERROR));
+        $this->language->setReturnValue('getErrorName',  'Warning', array(E_WARNING));
+        $this->language->setReturnValue('getErrorName',  'Notice',  array(E_NOTICE));
+        // this might prove to be troublesome if we need to set config
+        $this->generator = new HTMLPurifier_Generator($this->config, $this->context);
+        $this->line = false;
+        $this->context->register('Locale', $this->language);
+        $this->context->register('CurrentLine', $this->line);
+        $this->context->register('Generator', $this->generator);
+        $this->collector = new HTMLPurifier_ErrorCollector($this->context);
     }
     
     function test() {
         
-        $language = new HTMLPurifier_LanguageMock();
+        $language = $this->language;
-        $language->setReturnValue('getErrorName', 'Error', array(E_ERROR));
+        $language->setReturnValue('getMessage',    'Message 1',   array('message-1'));
-        $language->setReturnValue('getErrorName', 'Warning', array(E_WARNING));
+        $language->setReturnValue('formatMessage', 'Message 2',   array('message-2', array(1 => 'param')));
-        $language->setReturnValue('getMessage', 'Message 1', array('message-1'));
-        $language->setReturnValue('formatMessage', 'Message 2', array('message-2', array(1 => 'param')));
         $language->setReturnValue('formatMessage', ' at line 23', array('ErrorCollector: At line', array('line' => 23)));
-        $language->setReturnValue('formatMessage', ' at line 3', array('ErrorCollector: At line', array('line' => 3)));
+        $language->setReturnValue('formatMessage', ' at line 3',  array('ErrorCollector: At line', array('line' => 3)));
         
-        $line = false;
+        $this->line = 23;
+        $this->collector->send(E_ERROR, 'message-1');
         
-        $this->context->register('Locale', $language);
+        $this->line = 3;
-        $this->context->register('CurrentLine', $line);
+        $this->collector->send(E_WARNING, 'message-2', 'param');
-        
-        $generator = new HTMLPurifier_Generator($this->config, $this->context);
-        $this->context->register('Generator', $generator);
-        
-        $collector = new HTMLPurifier_ErrorCollector($this->context);
-        
-        $line = 23;
-        $collector->send(E_ERROR, 'message-1');
-        
-        $line = 3;
-        $collector->send(E_WARNING, 'message-2', 'param');
         
         $result = array(
-            0 => array(23, E_ERROR, 'Message 1'),
+            0 => array(23, E_ERROR, 'Message 1', array()),
-            1 => array(3, E_WARNING, 'Message 2')
+            1 => array(3, E_WARNING, 'Message 2', array())
         );
         
-        $this->assertIdentical($collector->getRaw(), $result);
+        $this->assertIdentical($this->collector->getRaw(), $result);
         
         $formatted_result = 
             '<ul><li><strong>Warning</strong>: Message 2 at line 3</li>'.
             '<li><strong>Error</strong>: Message 1 at line 23</li></ul>';
         
-        $config = HTMLPurifier_Config::create(array('Core.MaintainLineNumbers' => true));
+        $this->assertIdentical($this->collector->getHTMLFormatted($this->config), $formatted_result);
-        
-        $this->assertIdentical($collector->getHTMLFormatted($this->config), $formatted_result);
         
     }
     
     function testNoErrors() {
-        $language = new HTMLPurifier_LanguageMock();
+        $this->language->setReturnValue('getMessage', 'No errors', array('ErrorCollector: No errors'));
-        $language->setReturnValue('getMessage', 'No errors', array('ErrorCollector: No errors'));
-        $this->context->register('Locale', $language);
         
-        $generator = new HTMLPurifier_Generator($this->config, $this->context);
-        $this->context->register('Generator', $generator);
-        
-        $collector = new HTMLPurifier_ErrorCollector($this->context);
         $formatted_result = '<p>No errors</p>';
-        $this->assertIdentical($collector->getHTMLFormatted($this->config), $formatted_result);
+        $this->assertIdentical(
+            $this->collector->getHTMLFormatted($this->config),
+            $formatted_result
+        );
     }
     
     function testNoLineNumbers() {
-        $language = new HTMLPurifier_LanguageMock();
+        $this->language->setReturnValue('getMessage', 'Message 1', array('message-1'));
-        $language->setReturnValue('getMessage', 'Message 1', array('message-1'));
+        $this->language->setReturnValue('getMessage', 'Message 2', array('message-2'));
-        $language->setReturnValue('getMessage', 'Message 2', array('message-2'));
-        $language->setReturnValue('getErrorName', 'Error', array(E_ERROR));
-        $this->context->register('Locale', $language);
         
-        $generator = new HTMLPurifier_Generator($this->config, $this->context);
+        $this->collector->send(E_ERROR, 'message-1');
-        $this->context->register('Generator', $generator);
+        $this->collector->send(E_ERROR, 'message-2');
-        
-        $collector = new HTMLPurifier_ErrorCollector($this->context);
-        $collector->send(E_ERROR, 'message-1');
-        $collector->send(E_ERROR, 'message-2');
         
         $result = array(
-            0 => array(null, E_ERROR, 'Message 1'),
+            0 => array(false, E_ERROR, 'Message 1', array()),
-            1 => array(null, E_ERROR, 'Message 2')
+            1 => array(false, E_ERROR, 'Message 2', array())
         );
-        $this->assertIdentical($collector->getRaw(), $result);
+        $this->assertIdentical($this->collector->getRaw(), $result);
         
         $formatted_result = 
             '<ul><li><strong>Error</strong>: Message 1</li>'.
             '<li><strong>Error</strong>: Message 2</li></ul>';
-        $this->assertIdentical($collector->getHTMLFormatted($this->config), $formatted_result);
+        $this->assertIdentical($this->collector->getHTMLFormatted($this->config), $formatted_result);
     }
     
     function testContextSubstitutions() {
         
-        $language = new HTMLPurifier_LanguageMock();
-        $this->context->register('Locale', $language);
-        
-        $generator = new HTMLPurifier_Generator($this->config, $this->context);
-        $this->context->register('Generator', $generator);
-        
         $current_token = false;
         $this->context->register('CurrentToken', $current_token);
         
-        $collector = new HTMLPurifier_ErrorCollector($this->context);
-        
         // 0
         $current_token = new HTMLPurifier_Token_Start('a', array('href' => 'http://example.com'), 32);
-        $language->setReturnValue('formatMessage', 'Token message',
+        $this->language->setReturnValue('formatMessage', 'Token message',
           array('message-data-token', array('CurrentToken' => $current_token)));
-        $collector->send(E_NOTICE, 'message-data-token');
+        $this->collector->send(E_NOTICE, 'message-data-token');
         
         $current_attr  = 'href';
-        $language->setReturnValue('formatMessage', '$CurrentAttr.Name => $CurrentAttr.Value',
+        $this->language->setReturnValue('formatMessage', '$CurrentAttr.Name => $CurrentAttr.Value',
           array('message-attr', array('CurrentToken' => $current_token)));
         
         // 1
-        $collector->send(E_NOTICE, 'message-attr'); // test when context isn't available
+        $this->collector->send(E_NOTICE, 'message-attr'); // test when context isn't available
         
         // 2
         $this->context->register('CurrentAttr', $current_attr);
-        $collector->send(E_NOTICE, 'message-attr');
+        $this->collector->send(E_NOTICE, 'message-attr');
         
         $result = array(
-            0 => array(32, E_NOTICE, 'Token message'),
+            0 => array(32, E_NOTICE, 'Token message', array()),
-            1 => array(32, E_NOTICE, '$CurrentAttr.Name => $CurrentAttr.Value'),
+            1 => array(32, E_NOTICE, '$CurrentAttr.Name => $CurrentAttr.Value', array()),
-            2 => array(32, E_NOTICE, 'href => http://example.com')
+            2 => array(32, E_NOTICE, 'href => http://example.com', array())
         );
-        $this->assertIdentical($collector->getRaw(), $result);
+        $this->assertIdentical($this->collector->getRaw(), $result);
+        
+    }
+    
+    function testNestedErrors() {
+        $this->language->setReturnValue('getMessage', 'Message 1',   array('message-1'));
+        $this->language->setReturnValue('getMessage', 'Message 2',   array('message-2'));
+        $this->language->setReturnValue('formatMessage', 'End Message', array('end-message', array(1 => 'param')));
+        $this->language->setReturnValue('formatMessage', ' at line 4', array('ErrorCollector: At line', array('line' => 4)));
+        
+        $this->line = 4;
+        $this->collector->start();
+        $this->collector->send(E_WARNING, 'message-1');
+        $this->collector->send(E_NOTICE,  'message-2');
+        $this->collector->end(E_NOTICE, 'end-message', 'param');
+        
+        $expect = array(
+            0 => array(4, E_NOTICE, 'End Message', array(
+                0 => array(4, E_WARNING, 'Message 1', array()),
+                1 => array(4, E_NOTICE,  'Message 2', array()),
+            )),
+        );
+        $result = $this->collector->getRaw();
+        $this->assertIdentical($result, $expect);
+        
+        $formatted_expect =
+            '<ul><li><strong>Notice</strong>: End Message at line 4<ul>'.
+                '<li><strong>Warning</strong>: Message 1 at line 4</li>'.
+                '<li><strong>Notice</strong>: Message 2 at line 4</li></ul>'.
+            '</li></ul>';
+        $formatted_result = $this->collector->getHTMLFormatted($this->config);
+        $this->assertIdentical($formatted_result, $formatted_expect);
+        
+    }
+    
+    function testNestedErrorsQuiet() {
+        
+        $this->language->setReturnValue('getMessage', 'Incidental errors', array('ErrorCollector: Incidental errors'));
+        $this->language->setReturnValue('getMessage', 'Message', array('message'));
+        $this->language->setReturnValue('formatMessage', ' at line 4', array('ErrorCollector: At line', array('line' => 4)));
+        
+        $this->line = 4;
+        $this->collector->start();
+        $this->collector->send(E_WARNING, 'message');
+        $this->collector->end();
+        
+        $expect = array(
+            0 => array(4, E_NOTICE, 'Incidental errors', array(
+                0 => array(4, E_WARNING, 'Message', array()),
+            )),
+        );
+        $result = $this->collector->getRaw();
+        $this->assertIdentical($result, $expect);
+        
+    }
+    
+    function testNestedErrorsReallyQuiet() {
+        
+        $this->collector->start();
+        $this->collector->end();
+        
+        $expect = array();
+        $result = $this->collector->getRaw();
+        $this->assertIdentical($result, $expect);
         
     }