From 0e89a81a3036209fa90fd187bd59e104367ce5e5 Mon Sep 17 00:00:00 2001
From: Matt Farina <matt@mattfarina.com>
Date: Mon, 27 May 2013 21:42:05 -0400
Subject: Added an interface for Output Rules to document how they work.

---
 src/HTML5/Exception.php                 |  5 ++
 src/HTML5/Serializer/OutputRules.php    |  2 +-
 src/HTML5/Serializer/RulesInterface.php | 90 +++++++++++++++++++++++++++++++++
 src/HTML5/Serializer/Traverser.php      |  3 ++
 4 files changed, 99 insertions(+), 1 deletion(-)
 create mode 100644 src/HTML5/Exception.php
 create mode 100644 src/HTML5/Serializer/RulesInterface.php

(limited to 'src/HTML5')

diff --git a/src/HTML5/Exception.php b/src/HTML5/Exception.php
new file mode 100644
index 0000000..fab97d0
--- /dev/null
+++ b/src/HTML5/Exception.php
@@ -0,0 +1,5 @@
+<?php
+namespace HTML5;
+
+class Exception extends \Exception {
+}
diff --git a/src/HTML5/Serializer/OutputRules.php b/src/HTML5/Serializer/OutputRules.php
index 6226fdf..65742e5 100644
--- a/src/HTML5/Serializer/OutputRules.php
+++ b/src/HTML5/Serializer/OutputRules.php
@@ -10,7 +10,7 @@ namespace HTML5\Serializer;
 
 use \HTML5\Elements;
 
-class OutputRules {
+class OutputRules implements \HTML5\Serializer\RulesInterface {
 
   protected $traverser;
   protected $encode = FALSE;
diff --git a/src/HTML5/Serializer/RulesInterface.php b/src/HTML5/Serializer/RulesInterface.php
new file mode 100644
index 0000000..2853822
--- /dev/null
+++ b/src/HTML5/Serializer/RulesInterface.php
@@ -0,0 +1,90 @@
+<?php
+/**
+ * @file
+ * The interface definition for Rules to generate output.
+ */
+namespace HTML5\Serializer;
+
+/**
+ * To create a new rule set for writing output the RulesInterface needs to be
+ * implemented. The resulting class can be specified in the options with the
+ * key of rules.
+ *
+ * For an example implementation see \HTML5\Serializer\OutputRules.
+ */
+interface RulesInterface {
+
+  /**
+   * The class constructor.
+   *
+   * @param \HTML5\Serializer\Traverser $traverser
+   *   The traverser walking through the html.
+   * @param mixed $output
+   *   The output stream to write output to.
+   * @param array $options
+   *   An array of options.
+   */
+  public function __construct($traverser, $output, $options = array());
+
+  /**
+   * Write a document element (\DOMDocument).
+   *
+   * Instead of returning the result write it to the output stream ($output)
+   * that was passed into the constructor.
+   * 
+   * @param \DOMDocument $dom
+   */
+  public function document($dom);
+
+  /**
+   * Write an element.
+   *
+   * Instead of returning the result write it to the output stream ($output)
+   * that was passed into the constructor.
+   * 
+   * @param mixed $ele
+   */
+  public function element($ele);
+
+  /**
+   * Write a text node.
+   *
+   * Instead of returning the result write it to the output stream ($output)
+   * that was passed into the constructor.
+   * 
+   * @param mixed $ele
+   */
+  public function text($ele);
+
+  /**
+   * Write a CDATA node.
+   *
+   * Instead of returning the result write it to the output stream ($output)
+   * that was passed into the constructor.
+   * 
+   * @param mixed $ele
+   */
+  public function cdata($ele);
+
+  /**
+   * Write a comment node.
+   *
+   * Instead of returning the result write it to the output stream ($output)
+   * that was passed into the constructor.
+   * 
+   * @param mixed $ele
+   */
+  public function comment($ele);
+
+  /**
+   * Write a processor instruction.
+   *
+   * To learn about processor instructions see \HTML5\InstructionProcessor
+   *
+   * Instead of returning the result write it to the output stream ($output)
+   * that was passed into the constructor.
+   * 
+   * @param mixed $ele
+   */
+  public function processorInstruction($ele);
+}
\ No newline at end of file
diff --git a/src/HTML5/Serializer/Traverser.php b/src/HTML5/Serializer/Traverser.php
index bd9d1ce..27a52ff 100644
--- a/src/HTML5/Serializer/Traverser.php
+++ b/src/HTML5/Serializer/Traverser.php
@@ -44,6 +44,9 @@ class Traverser {
     $this->out = $out;
     $this->options = $options;
 
+    if (!isset($this->options['rules'])) {
+      throw new \HTML5\Exception('No Rules specified for output generation.');
+    }
     $rulesClass = $this->options['rules'];
     $this->rules = new $rulesClass($this, $out, $this->options);
   }
-- 
cgit v1.2.3