ILIAS  eassessment Revision 61809
 All Data Structures Namespaces Files Functions Variables Groups Pages
HTMLPurifier_Config Class Reference

Configuration object that triggers customizable behavior. More...

+ Collaboration diagram for HTMLPurifier_Config:

Public Member Functions

 __construct ($definition, $parent=null)
 get ($key, $a=null)
 Retreives a value from the configuration.
 getBatch ($namespace)
 Retreives an array of directives to values from a given namespace.
 getBatchSerial ($namespace)
 Returns a md5 signature of a segment of the configuration object that uniquely identifies that particular configuration.
 getSerial ()
 Returns a md5 signature for the entire configuration object that uniquely identifies that particular configuration.
 getAll ()
 Retrieves all directives, organized by namespace.
 set ($key, $value, $a=null)
 Sets a value to configuration.
 getHTMLDefinition ($raw=false)
 Retrieves object reference to the HTML definition.
 getCSSDefinition ($raw=false)
 Retrieves object reference to the CSS definition.
 getDefinition ($type, $raw=false)
 Retrieves a definition.
 loadArray ($config_array)
 Loads configuration values from an array with the following structure: Namespace.Directive => Value.
 mergeArrayFromForm ($array, $index=false, $allowed=true, $mq_fix=true)
 Merges in configuration values from $_GET/$_POST to object.
 loadIni ($filename)
 Loads configuration values from an ini file.
 isFinalized ($error=false)
 Checks whether or not the configuration object is finalized.
 autoFinalize ()
 Finalizes configuration only if auto finalize is on and not already finalized.
 finalize ()
 Finalizes a configuration object, prohibiting further change.
 serialize ()
 Returns a serialized form of the configuration object that can be reconstituted.

Static Public Member Functions

static create ($config, $schema=null)
 Convenience constructor that creates a config object based on a mixed var.
static inherit (HTMLPurifier_Config $config)
 Creates a new config object that inherits from a previous one.
static createDefault ()
 Convenience constructor that creates a default configuration object.
static getAllowedDirectivesForForm ($allowed, $schema=null)
 Returns a list of array(namespace, directive) for all directives that are allowed in a web-form context as per an allowed namespaces/directives list.
static loadArrayFromForm ($array, $index=false, $allowed=true, $mq_fix=true, $schema=null)
 Loads configuration values from $_GET/$_POST that were posted via ConfigForm.
static prepareArrayFromForm ($array, $index=false, $allowed=true, $mq_fix=true, $schema=null)
 Prepares an array from a form into something usable for the more strict parts of HTMLPurifier_Config.

Data Fields

 $version = '4.0.0'
 HTML Purifier's version.
 $autoFinalize = true
 Bool indicator whether or not to automatically finalize the object if a read operation is done.
 $def
 Reference HTMLPurifier_ConfigSchema for value checking.
 $chatty = true
 Set to false if you do not want line and file numbers in errors (useful when unit testing)

Protected Member Functions

 triggerError ($msg, $no)
 Produces a nicely formatted error message by supplying the stack frame information from two levels up and OUTSIDE of HTMLPurifier_Config.

Protected Attributes

 $serials = array()
 Namespace indexed array of serials for specific namespaces (see getSerial() for more info).
 $serial
 Serial for entire configuration object.
 $parser
 Parser for variables.
 $definitions
 Indexed array of definitions.
 $finalized = false
 Bool indicator whether or not config is finalized.
 $plist
 Property list containing configuration directives.

Private Member Functions

 _listify ($lookup)
 Convenience function for error reporting.

Private Attributes

 $aliasMode
 Whether or not a set is taking place due to an alias lookup.
 $lock
 Current lock; only gets to this namespace are allowed.

Detailed Description

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 because a configuration object should always be forwarded, otherwise, you run the risk of missing a parameter and then being stumped when a configuration directive doesn't work.
Todo:
Reconsider some of the public member variables

Definition at line 17 of file Config.php.

Constructor & Destructor Documentation

HTMLPurifier_Config::__construct (   $definition,
  $parent = null 
)
Parameters
$definitionHTMLPurifier_ConfigSchema that defines what directives are allowed.

Definition at line 92 of file Config.php.

{
$parent = $parent ? $parent : $definition->defaultPlist;
$this->plist = new HTMLPurifier_PropertyList($parent);
$this->def = $definition; // keep a copy around for checking
$this->parser = new HTMLPurifier_VarParser_Flexible();
}

Member Function Documentation

HTMLPurifier_Config::_listify (   $lookup)
private

Convenience function for error reporting.

Definition at line 311 of file Config.php.

References $name.

Referenced by set().

{
$list = array();
foreach ($lookup as $name => $b) $list[] = $name;
return implode(', ', $list);
}

+ Here is the caller graph for this function:

HTMLPurifier_Config::autoFinalize ( )

Finalizes configuration only if auto finalize is on and not already finalized.

Definition at line 534 of file Config.php.

References finalize().

Referenced by get(), getAll(), getBatch(), and getDefinition().

{
if ($this->autoFinalize) {
$this->finalize();
} else {
$this->plist->squash(true);
}
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static HTMLPurifier_Config::create (   $config,
  $schema = null 
)
static

Convenience constructor that creates a config object based on a mixed var.

Parameters
mixed$configVariable that defines the state of the config object. Can be: a HTMLPurifier_Config() object, an array of directives based on loadArray(), or a string filename of an ini file.
HTMLPurifier_ConfigSchemaSchema object
Returns
Configured HTMLPurifier_Config object

Definition at line 108 of file Config.php.

References $config, $ret, and createDefault().

Referenced by HTMLPurifier\__construct(), loadArrayFromForm(), and HTMLPurifier\purify().

{
if ($config instanceof HTMLPurifier_Config) {
// pass-through
return $config;
}
if (!$schema) {
} else {
$ret = new HTMLPurifier_Config($schema);
}
if (is_string($config)) $ret->loadIni($config);
elseif (is_array($config)) $ret->loadArray($config);
return $ret;
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static HTMLPurifier_Config::createDefault ( )
static

Convenience constructor that creates a default configuration object.

Returns
Default HTMLPurifier_Config object.

Definition at line 137 of file Config.php.

References $config, and HTMLPurifier_ConfigSchema\instance().

Referenced by create(), HTMLPurifier_URISchemeRegistry\getScheme(), and kses().

{
$config = new HTMLPurifier_Config($definition);
return $config;
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

HTMLPurifier_Config::finalize ( )

Finalizes a configuration object, prohibiting further change.

Definition at line 545 of file Config.php.

Referenced by autoFinalize().

{
$this->finalized = true;
unset($this->parser);
}

+ Here is the caller graph for this function:

HTMLPurifier_Config::get (   $key,
  $a = null 
)

Retreives a value from the configuration.

Parameters
$keyString key

Definition at line 147 of file Config.php.

References $d, autoFinalize(), and triggerError().

{
if ($a !== null) {
$this->triggerError("Using deprecated API: use \$config->get('$key.$a') instead", E_USER_WARNING);
$key = "$key.$a";
}
if (!$this->finalized) $this->autoFinalize();
if (!isset($this->def->info[$key])) {
// can't add % due to SimpleTest bug
$this->triggerError('Cannot retrieve value of undefined directive ' . htmlspecialchars($key),
E_USER_WARNING);
return;
}
if (isset($this->def->info[$key]->isAlias)) {
$d = $this->def->info[$key];
$this->triggerError('Cannot get value from aliased directive, use real name ' . $d->key,
E_USER_ERROR);
return;
}
if ($this->lock) {
list($ns) = explode('.', $key);
if ($ns !== $this->lock) {
$this->triggerError('Cannot get value of namespace ' . $ns . ' when lock for ' . $this->lock . ' is active, this probably indicates a Definition setup method is accessing directives that are not within its namespace', E_USER_ERROR);
return;
}
}
return $this->plist->get($key);
}

+ Here is the call graph for this function:

HTMLPurifier_Config::getAll ( )

Retrieves all directives, organized by namespace.

Warning
This is a pretty inefficient function, avoid if you can

Definition at line 221 of file Config.php.

References $name, $ret, and autoFinalize().

Referenced by getBatch(), and getSerial().

{
if (!$this->finalized) $this->autoFinalize();
$ret = array();
foreach ($this->plist->squash() as $name => $value) {
list($ns, $key) = explode('.', $name, 2);
$ret[$ns][$key] = $value;
}
return $ret;
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static HTMLPurifier_Config::getAllowedDirectivesForForm (   $allowed,
  $schema = null 
)
static

Returns a list of array(namespace, directive) for all directives that are allowed in a web-form context as per an allowed namespaces/directives list.

Parameters
$allowedList of allowed namespaces/directives

Definition at line 424 of file Config.php.

References $def, $ret, and HTMLPurifier_ConfigSchema\instance().

Referenced by prepareArrayFromForm(), and HTMLPurifier_Printer_ConfigForm\render().

{
if (!$schema) {
}
if ($allowed !== true) {
if (is_string($allowed)) $allowed = array($allowed);
$allowed_ns = array();
$allowed_directives = array();
$blacklisted_directives = array();
foreach ($allowed as $ns_or_directive) {
if (strpos($ns_or_directive, '.') !== false) {
// directive
if ($ns_or_directive[0] == '-') {
$blacklisted_directives[substr($ns_or_directive, 1)] = true;
} else {
$allowed_directives[$ns_or_directive] = true;
}
} else {
// namespace
$allowed_ns[$ns_or_directive] = true;
}
}
}
$ret = array();
foreach ($schema->info as $key => $def) {
list($ns, $directive) = explode('.', $key, 2);
if ($allowed !== true) {
if (isset($blacklisted_directives["$ns.$directive"])) continue;
if (!isset($allowed_directives["$ns.$directive"]) && !isset($allowed_ns[$ns])) continue;
}
if (isset($def->isAlias)) continue;
if ($directive == 'DefinitionID' || $directive == 'DefinitionRev') continue;
$ret[] = array($ns, $directive);
}
return $ret;
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

HTMLPurifier_Config::getBatch (   $namespace)

Retreives an array of directives to values from a given namespace.

Parameters
$namespaceString namespace

Definition at line 179 of file Config.php.

References $namespace, autoFinalize(), getAll(), and triggerError().

Referenced by getBatchSerial().

{
if (!$this->finalized) $this->autoFinalize();
$full = $this->getAll();
if (!isset($full[$namespace])) {
$this->triggerError('Cannot retrieve undefined namespace ' . htmlspecialchars($namespace),
E_USER_WARNING);
return;
}
return $full[$namespace];
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

HTMLPurifier_Config::getBatchSerial (   $namespace)

Returns a md5 signature of a segment of the configuration object that uniquely identifies that particular configuration.

Note
Revision is handled specially and is removed from the batch before processing!
Parameters
$namespaceNamespace to get serial for

Definition at line 197 of file Config.php.

References $namespace, getBatch(), and serialize().

{
if (empty($this->serials[$namespace])) {
$batch = $this->getBatch($namespace);
unset($batch['DefinitionRev']);
$this->serials[$namespace] = md5(serialize($batch));
}
return $this->serials[$namespace];
}

+ Here is the call graph for this function:

HTMLPurifier_Config::getCSSDefinition (   $raw = false)

Retrieves object reference to the CSS definition.

Parameters
$rawReturn a copy that has not been setup yet. Must be called before it's been setup, otherwise won't work.

Definition at line 331 of file Config.php.

References getDefinition().

{
return $this->getDefinition('CSS', $raw);
}

+ Here is the call graph for this function:

HTMLPurifier_Config::getDefinition (   $type,
  $raw = false 
)

Retrieves a definition.

Parameters
$typeType of definition: HTML, CSS, etc
$rawWhether or not definition should be returned raw

Definition at line 340 of file Config.php.

References $lock, $type, autoFinalize(), and HTMLPurifier_DefinitionCacheFactory\instance().

Referenced by getCSSDefinition(), getHTMLDefinition(), and serialize().

{
if (!$this->finalized) $this->autoFinalize();
// temporarily suspend locks, so we can handle recursive definition calls
$this->lock = null;
$cache = $factory->create($type, $this);
$this->lock = $lock;
if (!$raw) {
// see if we can quickly supply a definition
if (!empty($this->definitions[$type])) {
if (!$this->definitions[$type]->setup) {
$this->definitions[$type]->setup($this);
$cache->set($this->definitions[$type], $this);
}
return $this->definitions[$type];
}
// memory check missed, try cache
$this->definitions[$type] = $cache->get($this);
if ($this->definitions[$type]) {
// definition in cache, return it
return $this->definitions[$type];
}
} elseif (
!empty($this->definitions[$type]) &&
!$this->definitions[$type]->setup
) {
// raw requested, raw in memory, quick return
return $this->definitions[$type];
}
// quick checks failed, let's create the object
if ($type == 'HTML') {
$this->definitions[$type] = new HTMLPurifier_HTMLDefinition();
} elseif ($type == 'CSS') {
$this->definitions[$type] = new HTMLPurifier_CSSDefinition();
} elseif ($type == 'URI') {
$this->definitions[$type] = new HTMLPurifier_URIDefinition();
} else {
throw new HTMLPurifier_Exception("Definition of $type type not supported");
}
// quick abort if raw
if ($raw) {
if (is_null($this->get($type . '.DefinitionID'))) {
// fatally error out if definition ID not set
throw new HTMLPurifier_Exception("Cannot retrieve raw version without specifying %$type.DefinitionID");
}
return $this->definitions[$type];
}
// set it up
$this->lock = $type;
$this->definitions[$type]->setup($this);
$this->lock = null;
// save in cache
$cache->set($this->definitions[$type], $this);
return $this->definitions[$type];
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

HTMLPurifier_Config::getHTMLDefinition (   $raw = false)

Retrieves object reference to the HTML definition.

Parameters
$rawReturn a copy that has not been setup yet. Must be called before it's been setup, otherwise won't work.

Definition at line 322 of file Config.php.

References getDefinition().

{
return $this->getDefinition('HTML', $raw);
}

+ Here is the call graph for this function:

HTMLPurifier_Config::getSerial ( )

Returns a md5 signature for the entire configuration object that uniquely identifies that particular configuration.

Definition at line 210 of file Config.php.

References $serial, getAll(), and serialize().

{
if (empty($this->serial)) {
$this->serial = md5(serialize($this->getAll()));
}
return $this->serial;
}

+ Here is the call graph for this function:

static HTMLPurifier_Config::inherit ( HTMLPurifier_Config  $config)
static

Creates a new config object that inherits from a previous one.

Parameters
HTMLPurifier_Config$configConfiguration object to inherit from.
Returns
HTMLPurifier_Config object with $config as its parent.

Definition at line 129 of file Config.php.

{
return new HTMLPurifier_Config($config->def, $config->plist);
}
HTMLPurifier_Config::isFinalized (   $error = false)

Checks whether or not the configuration object is finalized.

Parameters
$errorString error message, or false for no error

Definition at line 523 of file Config.php.

References $error, $finalized, and triggerError().

Referenced by loadArray(), loadIni(), and set().

{
if ($this->finalized && $error) {
$this->triggerError($error, E_USER_ERROR);
}
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

HTMLPurifier_Config::loadArray (   $config_array)

Loads configuration values from an array with the following structure: Namespace.Directive => Value.

Parameters
$config_arrayConfiguration associative array

Definition at line 402 of file Config.php.

References $namespace, and isFinalized().

Referenced by loadIni(), and mergeArrayFromForm().

{
if ($this->isFinalized('Cannot load directives after finalization')) return;
foreach ($config_array as $key => $value) {
$key = str_replace('_', '.', $key);
if (strpos($key, '.') !== false) {
$this->set($key, $value);
} else {
$namespace = $key;
$namespace_values = $value;
foreach ($namespace_values as $directive => $value) {
$this->set($namespace .'.'. $directive, $value);
}
}
}
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static HTMLPurifier_Config::loadArrayFromForm (   $array,
  $index = false,
  $allowed = true,
  $mq_fix = true,
  $schema = null 
)
static

Loads configuration values from $_GET/$_POST that were posted via ConfigForm.

Parameters
$array$_GET or $_POST array to import
$indexIndex/name that the config variables are in
$allowedList of allowed namespaces/directives
$mq_fixBoolean whether or not to enable magic quotes fix
$schemaInstance of HTMLPurifier_ConfigSchema to use, if not global copy

Definition at line 470 of file Config.php.

References $config, $ret, create(), and prepareArrayFromForm().

{
$ret = HTMLPurifier_Config::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $schema);
return $config;
}

+ Here is the call graph for this function:

HTMLPurifier_Config::loadIni (   $filename)

Loads configuration values from an ini file.

Parameters
$filenameName of ini file

Definition at line 513 of file Config.php.

References $filename, isFinalized(), and loadArray().

{
if ($this->isFinalized('Cannot load directives after finalization')) return;
$array = parse_ini_file($filename, true);
$this->loadArray($array);
}

+ Here is the call graph for this function:

HTMLPurifier_Config::mergeArrayFromForm (   $array,
  $index = false,
  $allowed = true,
  $mq_fix = true 
)

Merges in configuration values from $_GET/$_POST to object.

NOT STATIC.

Note
Same parameters as loadArrayFromForm

Definition at line 480 of file Config.php.

References $ret, loadArray(), and prepareArrayFromForm().

{
$ret = HTMLPurifier_Config::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $this->def);
$this->loadArray($ret);
}

+ Here is the call graph for this function:

static HTMLPurifier_Config::prepareArrayFromForm (   $array,
  $index = false,
  $allowed = true,
  $mq_fix = true,
  $schema = null 
)
static

Prepares an array from a form into something usable for the more strict parts of HTMLPurifier_Config.

Definition at line 489 of file Config.php.

References $ret, and getAllowedDirectivesForForm().

Referenced by loadArrayFromForm(), and mergeArrayFromForm().

{
if ($index !== false) $array = (isset($array[$index]) && is_array($array[$index])) ? $array[$index] : array();
$mq = $mq_fix && function_exists('get_magic_quotes_gpc') && get_magic_quotes_gpc();
$allowed = HTMLPurifier_Config::getAllowedDirectivesForForm($allowed, $schema);
$ret = array();
foreach ($allowed as $key) {
list($ns, $directive) = $key;
$skey = "$ns.$directive";
if (!empty($array["Null_$skey"])) {
$ret[$ns][$directive] = null;
continue;
}
if (!isset($array[$skey])) continue;
$value = $mq ? stripslashes($array[$skey]) : $array[$skey];
$ret[$ns][$directive] = $value;
}
return $ret;
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

HTMLPurifier_Config::serialize ( )

Returns a serialized form of the configuration object that can be reconstituted.

Definition at line 571 of file Config.php.

References getDefinition().

Referenced by getBatchSerial(), and getSerial().

{
$this->getDefinition('HTML');
$this->getDefinition('CSS');
$this->getDefinition('URI');
return serialize($this);
}

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

HTMLPurifier_Config::set (   $key,
  $value,
  $a = null 
)

Sets a value to configuration.

Parameters
$keyString key
$valueMixed value

Definition at line 236 of file Config.php.

References $def, $namespace, $type, _listify(), HTMLPurifier_VarParser\getTypeName(), isFinalized(), and triggerError().

{
if (strpos($key, '.') === false) {
$namespace = $key;
$directive = $value;
$value = $a;
$key = "$key.$directive";
$this->triggerError("Using deprecated API: use \$config->set('$key', ...) instead", E_USER_NOTICE);
} else {
list($namespace) = explode('.', $key);
}
if ($this->isFinalized('Cannot set directive after finalization')) return;
if (!isset($this->def->info[$key])) {
$this->triggerError('Cannot set undefined directive ' . htmlspecialchars($key) . ' to value',
E_USER_WARNING);
return;
}
$def = $this->def->info[$key];
if (isset($def->isAlias)) {
if ($this->aliasMode) {
$this->triggerError('Double-aliases not allowed, please fix '.
'ConfigSchema bug with' . $key, E_USER_ERROR);
return;
}
$this->aliasMode = true;
$this->set($def->key, $value);
$this->aliasMode = false;
$this->triggerError("$key is an alias, preferred directive name is {$def->key}", E_USER_NOTICE);
return;
}
// Raw type might be negative when using the fully optimized form
// of stdclass, which indicates allow_null == true
$rtype = is_int($def) ? $def : $def->type;
if ($rtype < 0) {
$type = -$rtype;
$allow_null = true;
} else {
$type = $rtype;
$allow_null = isset($def->allow_null);
}
try {
$value = $this->parser->parse($value, $type, $allow_null);
$this->triggerError('Value for ' . $key . ' is of invalid type, should be ' . HTMLPurifier_VarParser::getTypeName($type), E_USER_WARNING);
return;
}
if (is_string($value) && is_object($def)) {
// resolve value alias if defined
if (isset($def->aliases[$value])) {
$value = $def->aliases[$value];
}
// check to see if the value is allowed
if (isset($def->allowed) && !isset($def->allowed[$value])) {
$this->triggerError('Value not supported, valid values are: ' .
$this->_listify($def->allowed), E_USER_WARNING);
return;
}
}
$this->plist->set($key, $value);
// reset definitions if the directives they depend on changed
// this is a very costly process, so it's discouraged
// with finalization
if ($namespace == 'HTML' || $namespace == 'CSS' || $namespace == 'URI') {
$this->definitions[$namespace] = null;
}
$this->serials[$namespace] = false;
}

+ Here is the call graph for this function:

HTMLPurifier_Config::triggerError (   $msg,
  $no 
)
protected

Produces a nicely formatted error message by supplying the stack frame information from two levels up and OUTSIDE of HTMLPurifier_Config.

Definition at line 555 of file Config.php.

Referenced by get(), getBatch(), isFinalized(), and set().

{
// determine previous stack frame
$backtrace = debug_backtrace();
if ($this->chatty && isset($backtrace[1])) {
$frame = $backtrace[1];
$extra = " on line {$frame['line']} in file {$frame['file']}";
} else {
$extra = '';
}
trigger_error($msg . $extra, $no);
}

+ Here is the caller graph for this function:

Field Documentation

HTMLPurifier_Config::$aliasMode
private

Whether or not a set is taking place due to an alias lookup.

Definition at line 75 of file Config.php.

HTMLPurifier_Config::$autoFinalize = true

Bool indicator whether or not to automatically finalize the object if a read operation is done.

Definition at line 29 of file Config.php.

HTMLPurifier_Config::$chatty = true

Set to false if you do not want line and file numbers in errors (useful when unit testing)

Definition at line 81 of file Config.php.

HTMLPurifier_Config::$def

Reference HTMLPurifier_ConfigSchema for value checking.

Note
This is public for introspective purposes. Please don't abuse!

Definition at line 54 of file Config.php.

Referenced by getAllowedDirectivesForForm(), and set().

HTMLPurifier_Config::$definitions
protected

Indexed array of definitions.

Definition at line 59 of file Config.php.

HTMLPurifier_Config::$finalized = false
protected

Bool indicator whether or not config is finalized.

Definition at line 64 of file Config.php.

Referenced by isFinalized().

HTMLPurifier_Config::$lock
private

Current lock; only gets to this namespace are allowed.

Definition at line 86 of file Config.php.

Referenced by getDefinition().

HTMLPurifier_Config::$parser
protected

Parser for variables.

Definition at line 47 of file Config.php.

HTMLPurifier_Config::$plist
protected

Property list containing configuration directives.

Definition at line 69 of file Config.php.

HTMLPurifier_Config::$serial
protected

Serial for entire configuration object.

Definition at line 42 of file Config.php.

Referenced by getSerial().

HTMLPurifier_Config::$serials = array()
protected

Namespace indexed array of serials for specific namespaces (see getSerial() for more info).

Definition at line 37 of file Config.php.

HTMLPurifier_Config::$version = '4.0.0'

HTML Purifier's version.

Definition at line 23 of file Config.php.


The documentation for this class was generated from the following file: