<?php
/**
* Represents an XHTML 1.1 module, with information on elements, tags
* and attributes.
* @note Even though this is technically XHTML 1.1, it is also used for
* regular HTML parsing. We are using modulization as a convenient
* way to represent the internals of HTMLDefinition, and our
* implementation is by no means conforming and does not directly
* use the normative DTDs or XML schemas.
* @note The public variables in a module should almost directly
* correspond to the variables in HTMLPurifier_HTMLDefinition.
* However, the prefix info carries no special meaning in these
* objects (include it anyway if that's the correspondence though).
* @todo Consider making some member functions protected
*/
class HTMLPurifier_HTMLModule
{
// -- Overloadable ----------------------------------------------------
/**
* Short unique string identifier of the module.
* @type string
*/
public $name;
/**
* Informally, a list of elements this module changes.
* Not used in any significant way.
* @type array
*/
public $elements = array();
/**
* Associative array of element names to element definitions.
* Some definitions may be incomplete, to be merged in later
* with the full definition.
* @type array
*/
public $info = array();
/**
* Associative array of content set names to content set additions.
* This is commonly used to, say, add an A element to the Inline
* content set. This corresponds to an internal variable $content_sets
* and NOT info_content_sets member variable of HTMLDefinition.
* @type array
*/
public $content_sets = array();
/**
* Associative array of attribute collection names to attribute
* collection additions. More rarely used for adding attributes to
* the global collections. Example is the StyleAttribute module adding
* the style attribute to the Core. Corresponds to HTMLDefinition's
* attr_collections->info, since the object's data is only info,
* with extra behavior associated with it.
* @type array
*/
public $attr_collections = array();
/**
* Associative array of deprecated tag name to HTMLPurifier_TagTransform.
* @type array
*/
public $info_tag_transform = array();
/**
* List of HTMLPurifier_AttrTransform to be performed before validation.
* @type array
*/
public $info_attr_transform_pre = array();
/**
* List of HTMLPurifier_AttrTransform to be performed after validation.
* @type array
*/
public $info_attr_transform_post = array();
/**
* List of HTMLPurifier_Injector to be performed during well-formedness fixing.
* An injector will only be invoked if all of it's pre-requisites are met;
* if an injector fails setup, there will be no error; it will simply be
* silently disabled.
* @type array
*/
public $info_injector = array();
/**
* Boolean flag that indicates whether or not getChildDef is implemented.
* For optimization reasons: may save a call to a function. Be sure
* to set it if you do implement getChildDef(), otherwise it will have
* no effect!
* @type bool
*/
public $defines_child_def = false;
/**
* Boolean flag whether or not this module is safe. If it is not safe, all
* of its members are unsafe. Modules are safe by default (this might be
* slightly dangerous, but it doesn't make much sense to force HTML Purifier,
* which is based off of safe HTML, to explicitly say, "This is safe," even
* though there are modules which are "unsafe")
*
* @type bool
* @note Previously, safety could be applied at an element level granularity.
* We've removed this ability, so in order to add "unsafe" elements
* or attributes, a dedicated module with this property set to false
* must be used.
*/
public $safe = true;
/**
* Retrieves a proper HTMLPurifier_ChildDef subclass based on
* content_model and content_model_type member variables of
* the HTMLPurifier_ElementDef class. There is a similar function
* in HTMLPurifier_HTMLDefinition.
* @param HTMLPurifier_ElementDef $def
* @return HTMLPurifier_ChildDef subclass
*/
public function getChildDef($def)
{
return false;
}
// -- Convenience -----------------------------------------------------
/**
* Convenience function that sets up a new element
* @param string $element Name of element to add
* @param string|bool $type What content set should element be registered to?
* Set as false to skip this step.
* @param string $contents Allowed children in form of:
* "$content_model_type: $content_model"
* @param array $attr_includes What attribute collections to register to
* element?
* @param array $attr What unique attributes does the element define?
* @see HTMLPurifier_ElementDef:: for in-depth descriptions of these parameters.
* @return HTMLPurifier_ElementDef Created element definition object, so you
* can set advanced parameters
*/
public function addElement($element, $type, $contents, $attr_includes = array(), $attr = array())
{
$this->elements[] = $element;
// parse content_model
list($content_model_type, $content_model) = $this->parseContents($contents);
// merge in attribute inclusions
$this->mergeInAttrIncludes($attr, $attr_includes);
// add element to content sets
if ($type) {
$this->addElementToContentSet($element, $type);
}
// create element
$this->info[$element] = HTMLPurifier_ElementDef::create(
$content_model,
$content_model_type,
$attr
);
// literal object $contents means direct child manipulation
if (!is_string($contents)) {
$this->info[$element]->child = $contents;
}
return $this->info[$element];
}
/**
* Convenience function that creates a totally blank, non-standalone
* element.
* @param string $element Name of element to create
* @return HTMLPurifier_ElementDef Created element
*/
public function addBlankElement($element)
{
if (!isset($this->info[$element])) {
$this->elements[] = $element;
$this->info[$element] = new HTMLPurifier_ElementDef();
$this->info[$element]->standalone = false;
} else {
trigger_error("Definition for $element already exists in module, cannot redefine");
}
return $this->info[$element];
}
/**
* Convenience function that registers an element to a content set
* @param string $element Element to register
* @param string $type Name content set (warning: case sensitive, usually upper-case
* first letter)
*/
public function addElementToContentSet($element, $type)
{
if (!isset($this->content_sets[$type])) {
$this->content_sets[$type] = '';
} else {
$this->content_sets[$type] .= ' | ';
}
$this->content_sets[$type] .= $element;
}
/**
* Convenience function that transforms single-string contents
* into separate content model and content model type
* @param string $contents Allowed children in form of:
* "$content_model_type: $content_model"
* @return array
* @note If contents is an object, an array of two nulls will be
* returned, and the callee needs to take the original $contents
* and use it directly.
*/
public function parseContents($contents)
{
if (!is_string($contents)) {
return array(null, null);
} // defer
switch ($contents) {
// check for shorthand content model forms
case 'Empty':
return array('empty', '');
case 'Inline':
return array('optional', 'Inline | #PCDATA');
case 'Flow':
return array('optional', 'Flow | #PCDATA');
}
list($content_model_type, $content_model) = explode(':', $contents);
$content_model_type = strtolower(trim($content_model_type));
$content_model = trim($content_model);
return array($content_model_type, $content_model);
}
/**
* Convenience function that merges a list of attribute includes into
* an attribute array.
* @param array $attr Reference to attr array to modify
* @param array $attr_includes Array of includes / string include to merge in
*/
public function mergeInAttrIncludes(&$attr, $attr_includes)
{
if (!is_array($attr_includes)) {
if (empty($attr_includes)) {
$attr_includes = array();
} else {
$attr_includes = array($attr_includes);
}
}
$attr[0] = $attr_includes;
}
/**
* Convenience function that generates a lookup table with boolean
* true as value.
* @param string $list List of values to turn into a lookup
* @note You can also pass an arbitrary number of arguments in
* place of the regular argument
* @return array array equivalent of list
*/
public function makeLookup($list)
{
if (is_string($list)) {
$list = func_get_args();
}
$ret = array();
foreach ($list as $value) {
if (is_null($value)) {
continue;
}
$ret[$value] = true;
}
return $ret;
}
/**
* Lazy load construction of the module after determining whether
* or not it's needed, and also when a finalized configuration object
* is available.
* @param HTMLPurifier_Config $config
*/
public function setup($config)
{
}
}
// vim: et sw=4 sts=4
