0
0
mirror of https://github.com/ezyang/htmlpurifier.git synced 2025-03-11 17:18:44 +00:00

Document core classes up to EntityLookup.php

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@304 48356398-32a2-884e-a903-53898d9a118a
This commit is contained in:
Edward Z. Yang 2006-08-19 23:06:59 +00:00
parent 973cc43b64
commit 37cbdc25b1
5 changed files with 180 additions and 12 deletions

View File

@ -9,11 +9,24 @@ require_once 'HTMLPurifier/AttrDef/Multiple.php';
require_once 'HTMLPurifier/AttrDef/TextDecoration.php';
require_once 'HTMLPurifier/AttrDef/FontFamily.php';
/**
* Defines allowed CSS attributes and what their values are.
* @see HTMLPurifier_HTMLDefinition
*/
class HTMLPurifier_CSSDefinition
{
/**
* Assoc array of attribute name to definition object.
*/
var $info = array();
/**
* Returns sole instance of this definition.
* @param $prototype Optional prototype you may pass in to overload
* the sole instance. Good for replacing an instance of
* the object with your own, custom object.
*/
function &instance($prototype = null) {
static $instance = null;
if ($prototype) {
@ -25,8 +38,9 @@ class HTMLPurifier_CSSDefinition
return $instance;
}
function HTMLPurifier_CSSDefinition() {}
/**
* Constructs the info array. The meat of this class.
*/
function setup() {
$this->info['text-align'] = new HTMLPurifier_AttrDef_Enum(

View File

@ -22,27 +22,73 @@ HTMLPurifier_ConfigDef::define(
);
/**
* Class that defines allowed child nodes and validates tokens against this.
* Defines allowed child nodes and validates tokens against it.
*/
class HTMLPurifier_ChildDef
{
/**
* Type of child definition, usually right-most part of class name lowercase
*
* Used occasionally in terms of context. Possible values include
* custom, required, optional and empty.
*/
var $type;
/**
* Bool that indicates whether or not an empty array of children is okay
*
* This is necessary for redundant checking when changes affecting
* a child node may cause a parent node to now be disallowed.
*/
var $allow_empty;
function validateChildren($tokens_of_children) {
/**
* Validates nodes according to definition and returns modification.
*
* @warning $context is NOT HTMLPurifier_AttrContext
* @param $tokens_of_children Array of HTMLPurifier_Token
* @param $config HTMLPurifier_Config object
* @param $context String context indicating inline, block or unknown
* @return bool true to leave nodes as is
* @return bool false to remove parent node
* @return array of replacement child tokens
*/
function validateChildren($tokens_of_children, $config, $context) {
trigger_error('Call to abstract function', E_USER_ERROR);
}
}
/**
* Custom validation class, accepts DTD child definitions
*
* @warning Currently this class is an all or nothing proposition, that is,
* it will only give a bool return value. Table is the only
* child definition that uses this class, and we ought to give
* it a dedicated one.
*/
class HTMLPurifier_ChildDef_Custom extends HTMLPurifier_ChildDef
{
var $type = 'custom';
var $allow_empty = false;
/**
* Allowed child pattern as defined by the DTD
*/
var $dtd_regex;
/**
* PCRE regex derived from $dtd_regex
* @private
*/
var $_pcre_regex;
/**
* @param $dtd_regex Allowed child pattern from the DTD
*/
function HTMLPurifier_ChildDef_Custom($dtd_regex) {
$this->dtd_regex = $dtd_regex;
$this->_compileRegex();
}
/**
* Compiles the PCRE regex from a DTD regex ($dtd_regex to $_pcre_regex)
*/
function _compileRegex() {
$raw = str_replace(' ', '', $this->dtd_regex);
if ($raw{0} != '(') {
@ -82,9 +128,18 @@ class HTMLPurifier_ChildDef_Custom extends HTMLPurifier_ChildDef
}
}
/**
* Definition that allows a set of elements, but disallows empty children.
*/
class HTMLPurifier_ChildDef_Required extends HTMLPurifier_ChildDef
{
/**
* Lookup table of allowed elements.
*/
var $elements = array();
/**
* @param $elements List of allowed element names (lowercase).
*/
function HTMLPurifier_ChildDef_Required($elements) {
if (is_string($elements)) {
$elements = str_replace(' ', '', $elements);
@ -168,8 +223,13 @@ class HTMLPurifier_ChildDef_Required extends HTMLPurifier_ChildDef
}
}
// only altered behavior is that it returns an empty array
// instead of a false (to delete the node)
/**
* Definition that allows a set of elements, and allows no children.
* @note This is a hack to reuse code from HTMLPurifier_ChildDef_Required,
* really, one shouldn't inherit from the other. Only altered behavior
* is to overload a returned false with an array. Thus, it will never
* return false.
*/
class HTMLPurifier_ChildDef_Optional extends HTMLPurifier_ChildDef_Required
{
var $allow_empty = true;
@ -181,23 +241,48 @@ class HTMLPurifier_ChildDef_Optional extends HTMLPurifier_ChildDef_Required
}
}
// placeholder
/**
* Definition that disallows all elements.
* @warning validateChildren() in this class is actually never called, because
* empty elements are corrected in HTMLPurifier_Strategy_MakeWellFormed
* before child definitions are parsed in earnest by
* HTMLPurifier_Strategy_FixNesting.
*/
class HTMLPurifier_ChildDef_Empty extends HTMLPurifier_ChildDef
{
var $allow_empty = true;
var $type = 'empty';
function HTMLPurifier_ChildDef_Empty() {}
function validateChildren($tokens_of_children, $config, $context) {
return false;
return array();
}
}
/**
* Definition that uses different definitions depending on context.
*
* The del and ins tags are notable because they allow different types of
* elements depending on whether or not they're in a block or inline context.
* Chameleon allows this behavior to happen by using two different
* definitions depending on context. While this somewhat generalized,
* it is specifically intended for those two tags.
*/
class HTMLPurifier_ChildDef_Chameleon extends HTMLPurifier_ChildDef
{
/**
* Instance of the definition object to use when inline. Usually stricter.
*/
var $inline;
/**
* Instance of the definition object to use when block.
*/
var $block;
/**
* @param $inline List of elements to allow when inline.
* @param $block List of elements to allow when block.
*/
function HTMLPurifier_ChildDef_Chameleon($inline, $block) {
$this->inline = new HTMLPurifier_ChildDef_Optional($inline);
$this->block = new HTMLPurifier_ChildDef_Optional($block);

View File

@ -1,7 +1,10 @@
<?php
/**
*
* Configuration object that triggers customizable behavior.
*
* @warning This class is strongly defined: that means that the class
* will fail if an undefined directive is retrieved or set.
*
* @note Many classes that could (although many times don't) use the
* configuration object make it a mandatory parameter. This is
@ -12,18 +15,34 @@
class HTMLPurifier_Config
{
/**
* Two-level associative array of configuration directives
*/
var $conf;
/**
* @param $definition HTMLPurifier_ConfigDef that defines what directives
* are allowed.
*/
function HTMLPurifier_Config(&$definition) {
$this->conf = $definition->info; // set up the defaults
}
/**
* Convenience constructor that creates a default configuration object.
* @return Default HTMLPurifier_Config object.
*/
function createDefault() {
$definition =& HTMLPurifier_ConfigDef::instance();
$config = new HTMLPurifier_Config($definition);
return $config;
}
/**
* Retreives a value from the configuration.
* @param $namespace String namespace
* @param $key String key
*/
function get($namespace, $key) {
if (!isset($this->conf[$namespace][$key])) {
trigger_error('Cannot retrieve value of undefined directive',
@ -33,6 +52,12 @@ class HTMLPurifier_Config
return $this->conf[$namespace][$key];
}
/**
* Sets a value to configuration.
* @param $namespace String namespace
* @param $key String key
* @param $value Mixed value
*/
function set($namespace, $key, $value) {
if (!isset($this->conf[$namespace][$key])) {
trigger_error('Cannot set undefined directive to value',

View File

@ -1,15 +1,29 @@
<?php
/**
* Configuration definition, defines directives and their defaults.
* @todo Build documentation generation capabilities.
*/
class HTMLPurifier_ConfigDef {
/**
* Currently defined directives (and namespaces).
* @note This shares the exact same structure as HTMLPurifier_Config::$conf
*/
var $info = array();
/**
* Initializes the default namespaces.
*/
function initialize() {
$this->defineNamespace('Core', 'Core features that are always available.');
$this->defineNamespace('Attr', 'Features regarding attribute validation.');
$this->defineNamespace('URI', 'Features regarding Uniform Resource Identifiers.');
}
/**
* Retrieves an instance of the application-wide configuration definition.
*/
function &instance($prototype = null) {
static $instance;
if ($prototype !== null) {
@ -21,6 +35,17 @@ class HTMLPurifier_ConfigDef {
return $instance;
}
/**
* Defines a directive for configuration
* @warning Will fail of directive's namespace is defined
* @todo Collect information on description and allow redefinition
* so that multiple files can register a dependency on a
* configuration directive.
* @param $namespace Namespace the directive is in
* @param $name Key of directive
* @param $default Default value of directive
* @param $description Description of directive for documentation
*/
function define($namespace, $name, $default, $description) {
$def =& HTMLPurifier_ConfigDef::instance();
if (!isset($def->info[$namespace])) {
@ -36,6 +61,11 @@ class HTMLPurifier_ConfigDef {
$def->info[$namespace][$name] = $default;
}
/**
* Defines a namespace for directives to be put into.
* @param $namespace Namespace's name
* @param $description Description of the namespace
*/
function defineNamespace($namespace, $description) {
$def =& HTMLPurifier_ConfigDef::instance();
if (isset($def->info[$namespace])) {

View File

@ -1,12 +1,22 @@
<?php
/**
* Object that provides entity lookup table from entity name to character
*/
class HTMLPurifier_EntityLookup {
/**
* Assoc array of entity name to character represented.
* @public
*/
var $table;
function HTMLPurifier_EntityLookup() {}
// to enforce Singleton-ness
/**
* Sets up the entity lookup table from the serialized file contents.
* @note The serialized contents are versioned, but were generated
* using the maintenance script generate_entity_file.php
* @warning This is not in constructor to help enforce the Singleton
*/
function setup($file = false) {
if (!$file) {
$file = dirname(__FILE__) . '/EntityLookup/data.txt';
@ -14,6 +24,10 @@ class HTMLPurifier_EntityLookup {
$this->table = unserialize(file_get_contents($file));
}
/**
* Retrieves sole instance of the object.
* @param Optional prototype of custom lookup table to overload with.
*/
function instance($prototype = false) {
// no references, since PHP doesn't copy unless modified
static $instance = null;