Struct ruma::html::SanitizerConfig

pub struct SanitizerConfig { /* private fields */ }

Available on crate feature html only.

Configuration to sanitize HTML elements and attributes.

Implementations

impl SanitizerConfig

pub fn new() -> SanitizerConfig

Constructs an empty SanitizerConfig that will not filter any element or attribute.

The list of allowed and replaced elements can be changed with Self::allow_elements(), Self::replace_elements(), Self::ignore_elements(), Self::remove_elements(), Self::remove_reply_fallback().

The list of allowed and replaced attributes can be changed with Self::allow_attributes(), Self::replace_attributes(), Self::remove_attributes(), Self::allow_schemes(), Self::deny_schemes(), Self::allow_classes(), Self::remove_classes().

pub fn with_mode(mode: HtmlSanitizerMode) -> SanitizerConfig

Constructs a SanitizerConfig with the given mode for filtering elements and attributes.

The mode defines the basic list of allowed and replaced elements and attributes and the maximum nesting level of elements.

The list of allowed and replaced elements can be changed with Self::allow_elements(), Self::replace_elements(), Self::ignore_elements(), Self::remove_elements(), Self::remove_reply_fallback().

The list of allowed and replaced attributes can be changed with Self::allow_attributes(), Self::replace_attributes(), Self::remove_attributes(), Self::allow_schemes(), Self::deny_schemes(), Self::allow_classes(), Self::remove_classes().

pub fn strict() -> SanitizerConfig

Constructs a SanitizerConfig that will filter elements and attributes not suggested in the Matrix specification.

The list of allowed and replaced elements can be changed with Self::allow_elements(), Self::replace_elements(), Self::ignore_elements(), Self::remove_elements(), Self::remove_reply_fallback().

The list of allowed and replaced attributes can be changed with Self::allow_attributes(), Self::replace_attributes(), Self::remove_attributes(), Self::allow_schemes(), Self::deny_schemes(), Self::allow_classes(), Self::remove_classes().

This is the same as calling SanitizerConfig::with_mode(HtmlSanitizerMode::Strict).

pub fn compat() -> SanitizerConfig

Constructs a SanitizerConfig that will filter elements and attributes not [suggested in the Matrix specification], except a few for improved compatibility:

• The matrix scheme is allowed in links.

The list of allowed elements can be changed with Self::allow_elements(), Self::replace_elements(), Self::ignore_elements(), Self::remove_elements(), Self::remove_reply_fallback().

The list of allowed attributes can be changed with Self::allow_attributes(), Self::replace_attributes(), Self::remove_attributes(), Self::allow_schemes(), Self::deny_schemes(), Self::allow_classes(), Self::remove_classes().

This is the same as calling SanitizerConfig::with_mode(HtmlSanitizerMode::Compat).

pub fn replace_elements( self, elements: impl IntoIterator<Item = NameReplacement>, behavior: ListBehavior, ) -> SanitizerConfig

Change the list of replaced HTML elements.

The given list is added to or replaces the list of replacements of the current mode, depending on the ListBehavior.

The replacement occurs before the removal, so the replaced element should not be in the allowed list of elements, but the replacement element should.

Parameters

• elements: The list of element names replacements.

pub fn remove_elements( self, elements: impl IntoIterator<Item = &'static str>, ) -> SanitizerConfig

Remove the given HTML elements.

When an element is removed, the element and its children are dropped. If you want to remove an element but keep its children, use SanitizerConfig::ignore_elements or SanitizerConfig::allow_elements.

Removing elements has a higher priority than ignoring or allowing. So if an element is in this list, it will always be removed.

Parameters

• elements: The list of element names to remove.

pub fn remove_reply_fallback(self) -> SanitizerConfig

Remove the rich reply fallback.

Calling this allows to remove the mx-reply element in addition to the list of elements to remove.

Removing elements has a higher priority than ignoring or allowing. So if this settings is set, mx-reply will always be removed.

pub fn ignore_elements( self, elements: impl IntoIterator<Item = &'static str>, ) -> SanitizerConfig

Ignore the given HTML elements.

When an element is ignored, the element is dropped and replaced by its children. If you want to drop an element and its children, use SanitizerConfig::remove_elements.

Removing elements has a lower priority than removing but a higher priority than allowing.

Parameters

• elements: The list of element names to ignore.

pub fn allow_elements( self, elements: impl IntoIterator<Item = &'static str>, behavior: ListBehavior, ) -> SanitizerConfig

Change the list of allowed HTML elements.

The given list is added to or replaces the list of allowed elements of the current mode, depending on the ListBehavior.

If an element is not allowed, it is ignored. If no mode is set and no elements are explicitly allowed, all elements are allowed.

Parameters

• elements: The list of element names.

pub fn replace_attributes<'a>( self, attrs: impl IntoIterator<Item = ElementAttributesReplacement<'a>>, behavior: ListBehavior, ) -> SanitizerConfig

Change the list of replaced attributes per HTML element.

The given list is added to or replaces the list of replacements of the current mode, depending on the ListBehavior.

The replacement occurs before the removal, so the replaced attribute should not be in the list of allowed attributes, but the replacement attribute should. Attribute replacement occurs before element replacement, so if you want to replace an attribute on an element that is set to be replaced, you must use the replaced element’s name, not the name of its replacement.

Parameters

• attrs: The list of element’s attributes replacements.

pub fn remove_attributes<'a>( self, attrs: impl IntoIterator<Item = PropertiesNames<'a>>, ) -> SanitizerConfig

Remove the given attributes per HTML element.

Removing attributes has a higher priority than allowing. So if an attribute is in this list, it will always be removed.

Parameters

• attrs: The list of attributes per element. The value of parent is the element name, and properties contains attribute names.

pub fn allow_attributes<'a>( self, attrs: impl IntoIterator<Item = PropertiesNames<'a>>, behavior: ListBehavior, ) -> SanitizerConfig

Change the list of allowed attributes per HTML element.

The given list is added to or replaces the list of allowed attributes of the current mode, depending on the ListBehavior.

If an attribute is not allowed, it is removed. If no mode is set and no attributes are explicitly allowed, all attributes are allowed.

Parameters

• attrs: The list of attributes per element. The value of parent is the element name, and properties contains attribute names.

pub fn deny_schemes<'a>( self, schemes: impl IntoIterator<Item = ElementAttributesSchemes<'a>>, ) -> SanitizerConfig

Deny the given URI schemes per attribute per HTML element.

Denying schemes has a higher priority than allowing. So if a scheme is in this list, it will always be denied.

If a scheme is denied, its element is removed, because it is deemed that the element will not be usable without it URI.

Parameters

• schemes: The list of schemes per attribute per element.

pub fn allow_schemes<'a>( self, schemes: impl IntoIterator<Item = ElementAttributesSchemes<'a>>, behavior: ListBehavior, ) -> SanitizerConfig

Change the list of allowed schemes per attribute per HTML element.

The given list is added to or replaces the list of allowed schemes of the current mode, depending on the ListBehavior.

If a scheme is not allowed, it is denied. If a scheme is denied, its element is ignored, because it is deemed that the element will not be usable without it URI. If no mode is set and no schemes are explicitly allowed, all schemes are allowed.

Parameters

• schemes: The list of schemes per attribute per element.

pub fn remove_classes<'a>( self, classes: impl IntoIterator<Item = PropertiesNames<'a>>, ) -> SanitizerConfig

Deny the given classes per HTML element.

Removing classes has a higher priority than allowing. So if a class is in this list, it will always be removed.

If all the classes of a class attribute are removed, the whole attribute is removed.

In the list of classes, the names must match the full class name. * can be used as a wildcard for any number of characters. So language will only match a class named language, and language-* will match any class name starting with language-.

Parameters

• attrs: The list of classes per element. The value of parent is the element name, and properties contains classes.

pub fn allow_classes<'a>( self, classes: impl IntoIterator<Item = PropertiesNames<'a>>, behavior: ListBehavior, ) -> SanitizerConfig

Change the list of allowed classes per HTML element.

The given list is added, removed or replaces the list of allowed classes of the current mode, depending on the ListBehavior.

If a class is not allowed, it is removed. If all the classes of a class attribute are removed, the whole attribute is removed. If no mode is set and no classes are explicitly allowed, all classes are allowed.

In the list of classes, the names must match the full class name. * can be used as a wildcard for any number of characters. So language will only match a class named language, and language-* will match any class name starting with language-.

Parameters

• attrs: The list of classes per element. The value of parent is the element name, and properties contains classes.

pub fn max_depth(self, depth: u32) -> SanitizerConfig

The maximum nesting level of HTML elements.

This overrides the maximum depth set by the mode, if one is set.

All elements that are deeper than the maximum depth will be removed. If no mode is set and no maximum depth is explicitly set, elements are not filtered by their nesting level.

Parameters

• depth: The maximum nesting level allowed.

Trait Implementations

impl Clone for SanitizerConfig

fn clone(&self) -> SanitizerConfig

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SanitizerConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for SanitizerConfig

fn default() -> SanitizerConfig

Returns the “default value” for a type.