Add documentation about configuration directive types.

Signed-off-by: Edward Z. Yang <ezyang@mit.edu>

NEWS

@@ -14,6 +14,7 @@ NEWS ( CHANGELOG and HISTORY )                                     HTMLPurifier
   <? ... ?> statements.
 ! Added %URI.DisableResources functionality; the directive originally
   did nothing.  Thanks David Rothstein for reporting.
+! Add documentation about configuration directive types.
 - Fix improper handling of Internet Explorer conditional comments
   by parser.  Thanks zmonteca for reporting.
 - Fix missing attributes bug when running on Mac Snow Leopard and APC.

configdoc/styles/plain.xsl

@@ -40,12 +40,26 @@
                             </xsl:apply-templates>
                         </ul>
                     </div>
+                    <div id="typesContainer">
+                        <h2>Types</h2>
+                        <xsl:apply-templates select="$typeLookup" mode="types" />
+                    </div>
                     <xsl:apply-templates />
                 </div>
             </body>
         </html>
     </xsl:template>
 
+    <xsl:template match="type" mode="types">
+        <div class="type-block">
+            <xsl:attribute name="id">type-<xsl:value-of select="@id" /></xsl:attribute>
+            <h3><code><xsl:value-of select="@id" /></code>: <xsl:value-of select="@name" /></h3>
+            <div class="type-description">
+                <xsl:copy-of xmlns:xhtml="http://www.w3.org/1999/xhtml" select="xhtml:div/node()" />
+            </div>
+        </div>
+    </xsl:template>
+
     <xsl:template match="title" mode="toc" />
     <xsl:template match="namespace" mode="toc">
         <xsl:param name="overflowNumber" />
@@ -192,10 +206,13 @@
             <td>
                 <xsl:variable name="type" select="text()" />
                 <xsl:attribute name="class">type type-<xsl:value-of select="$type" /></xsl:attribute>
-                <xsl:value-of select="$typeLookup/type[@id=$type]/text()" />
-                <xsl:if test="@allow-null='yes'">
-                    (or null)
-                </xsl:if>
+                <a>
+                    <xsl:attribute name="href">#type-<xsl:value-of select="$type" /></xsl:attribute>
+                    <xsl:value-of select="$typeLookup/type[@id=$type]/@name" />
+                    <xsl:if test="@allow-null='yes'">
+                        (or null)
+                    </xsl:if>
+                </a>
             </td>
         </tr>
     </xsl:template>

configdoc/types.xml

@@ -1,16 +1,68 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <types>
-  <type id="string">String</type>
-  <type id="istring">Case-insensitive string</type>
-  <type id="text">Text</type>
-  <type id="itext">Case-insensitive text</type>
-  <type id="int">Integer</type>
-  <type id="float">Float</type>
-  <type id="bool">Boolean</type>
-  <type id="lookup">Lookup array</type>
-  <type id="list">Array list</type>
-  <type id="hash">Associative array</type>
-  <type id="mixed">Mixed</type>
+  <type id="string" name="String"><div xmlns="http://www.w3.org/1999/xhtml">
+    A <a
+    href="http://docs.php.net/manual/en/language.types.string.php">sequence
+    of characters</a>.
+  </div></type>
+  <type id="istring" name="Case-insensitive string"><div xmlns="http://www.w3.org/1999/xhtml">
+    A series of case-insensitive characters.  Internally, upper-case
+    ASCII characters will be converted to lower-case.
+  </div></type>
+  <type id="text" name="Text"><div xmlns="http://www.w3.org/1999/xhtml">
+    A series of characters that may contain newlines.  Text tends to
+    indicate human-oriented text, as opposed to a machine format.
+  </div></type>
+  <type id="itext" name="Case-insensitive text"><div xmlns="http://www.w3.org/1999/xhtml">
+    A series of case-insensitive characters that may contain newlines.
+  </div></type>
+  <type id="int" name="Integer"><div xmlns="http://www.w3.org/1999/xhtml">
+    An <a
+      href="http://docs.php.net/manual/en/language.types.integer.php">
+      integer</a>.  You are alternatively permitted to pass a string of
+    digits instead, which will be cast to an integer using
+    <code>(int)</code>.
+  </div></type>
+  <type id="float" name="Float"><div xmlns="http://www.w3.org/1999/xhtml">
+    A <a href="http://docs.php.net/manual/en/language.types.float.php">
+      floating point number</a>.  You are alternatively permitted to
+    pass a numeric string (as defined by <code>is_numeric()</code>),
+    which will be cast to a float using <code>(float)</code>.
+  </div></type>
+  <type id="bool" name="Boolean"><div xmlns="http://www.w3.org/1999/xhtml">
+    A <a
+      href="http://docs.php.net/manual/en/language.types.boolean.php">boolean</a>.
+    You are alternatively permitted to pass an integer <code>0</code> or
+    <code>1</code> (other integers are not permitted) or a string
+    <code>"on"</code>, <code>"true"</code> or <code>"1"</code> for
+    <code>true</code>, and <code>"off"</code>, <code>"false"</code> or
+    <code>"0"</code> for <code>false</code>.
+  </div></type>
+  <type id="lookup" name="Lookup array"><div xmlns="http://www.w3.org/1999/xhtml">
+    An array whose values are <code>true</code>, e.g. <code>array('key'
+      => true, 'key2' => true)</code>.  You are alternatively permitted
+    to pass an array list of the keys <code>array('key', 'key2')</code>
+    or a comma-separated string of keys <code>"key, key2"</code>.  If
+    you pass an array list of values, ensure that your values are
+    strictly numerically indexed: <code>array('key1', 2 =>
+      'key2')</code> will not do what you expect and emits a warning.
+  </div></type>
+  <type id="list" name="Array list"><div xmlns="http://www.w3.org/1999/xhtml">
+    An array which has consecutive integer indexes, e.g.
+    <code>array('val1', 'val2')</code>.  You are alternatively permitted
+    to pass a comma-separated string of keys <code>"val1, val2"</code>.
+    If your array is not in this form, <code>array_values</code> is run
+    on the array and a warning is emitted.
+  </div></type>
+  <type id="hash" name="Associative array"><div xmlns="http://www.w3.org/1999/xhtml">
+    An array which is a mapping of keys to values, e.g.
+    <code>array('key1' => 'val1', 'key2' => 'val2')</code>.  You are
+    alternatively permitted to pass a comma-separated string of
+    key-colon-value strings, e.g. <code>"key1: val1, key2: val2"</code>.
+  </div></type>
+  <type id="mixed" name="Mixed"><div xmlns="http://www.w3.org/1999/xhtml">
+    An arbitrary PHP value of any type.
+  </div></type>
 </types>
 
 <!-- vim: et sw=4 sts=4

library/HTMLPurifier/VarParser/Flexible.php

@@ -62,7 +62,7 @@ class HTMLPurifier_VarParser_Flexible extends HTMLPurifier_VarParser
                         foreach ($var as $keypair) {
                             $c = explode(':', $keypair, 2);
                             if (!isset($c[1])) continue;
-                            $nvar[$c[0]] = $c[1];
+                            $nvar[trim($c[0])] = trim($c[1]);
                         }
                         $var = $nvar;
                     }
@@ -79,8 +79,15 @@ class HTMLPurifier_VarParser_Flexible extends HTMLPurifier_VarParser
                         return $new;
                     } else break;
                 }
+                if ($type === self::ALIST) {
+                    trigger_error("Array list did not have consecutive integer indexes", E_USER_WARNING);
+                    return array_values($var);
+                }
                 if ($type === self::LOOKUP) {
                     foreach ($var as $key => $value) {
+                        if ($value !== true) {
+                            trigger_error("Lookup array has non-true value at key '$key'; maybe your input array was not indexed numerically", E_USER_WARNING);
+                        }
                         $var[$key] = true;
                     }
                 }