class Sanitize
Constants
- REGEX_HTML_CONTROL_CHARACTERS
Matches one or more control characters that should be removed from HTML before parsing, as defined by the HTML living standard.
- REGEX_HTML_NON_CHARACTERS
Matches one or more non-characters that should be removed from HTML before parsing, as defined by the HTML living standard.
- REGEX_PROTOCOL
Matches an attribute value that could be treated by a browser as a URL with a protocol prefix, such as “http:” or “javascript:”. Any string of zero or more characters followed by a colon is considered a match, even if the colon is encoded as an entity and even if it's an incomplete entity (which IE6 and Opera will still parse).
- REGEX_UNSUITABLE_CHARS
Matches one or more characters that should be stripped from HTML before parsing. This is a combination of `REGEX_HTML_CONTROL_CHARACTERS` and `REGEX_HTML_NON_CHARACTERS`.
html.spec.whatwg.org/multipage/parsing.html#preprocessing-the-input-stream
- VERSION
Attributes
Public Class Methods
Returns a sanitized copy of the given full html document, using the settings in config if specified.
When sanitizing a document, the `<html>` element must be whitelisted or an error will be raised. If this is undesirable, you should probably use {#fragment} instead.
# File lib/sanitize.rb, line 59 def self.document(html, config = {}) Sanitize.new(config).document(html) end
Returns a sanitized copy of the given html fragment, using the settings in config if specified.
# File lib/sanitize.rb, line 65 def self.fragment(html, config = {}) Sanitize.new(config).fragment(html) end
Returns a new Sanitize object initialized with the settings in config.
# File lib/sanitize.rb, line 91 def initialize(config = {}) @config = Config.merge(Config::DEFAULT, config) @transformers = Array(@config[:transformers]).dup # Default transformers always run at the end of the chain, after any custom # transformers. @transformers << Transformers::CleanElement.new(@config) @transformers << Transformers::CleanComment unless @config[:allow_comments] if @config[:elements].include?('style') scss = Sanitize::CSS.new(config) @transformers << Transformers::CSS::CleanElement.new(scss) end if @config[:attributes].values.any? {|attr| attr.include?('style') } scss ||= Sanitize::CSS.new(config) @transformers << Transformers::CSS::CleanAttribute.new(scss) end @transformers << Transformers::CleanDoctype @transformers << Transformers::CleanCDATA @transformer_config = { config: @config } end
Sanitizes the given `Nokogiri::XML::Node` instance and all its children.
# File lib/sanitize.rb, line 70 def self.node!(node, config = {}) Sanitize.new(config).node!(node) end
Public Instance Methods
Returns a sanitized copy of the given html document.
When sanitizing a document, the `<html>` element must be whitelisted or an error will be raised. If this is undesirable, you should probably use {#fragment} instead.
# File lib/sanitize.rb, line 122 def document(html) return '' unless html doc = Nokogiri::HTML5.parse(preprocess(html), **@config[:parser_options]) node!(doc) to_html(doc) end
Returns a sanitized copy of the given html fragment.
# File lib/sanitize.rb, line 134 def fragment(html) return '' unless html frag = Nokogiri::HTML5.fragment(preprocess(html), **@config[:parser_options]) node!(frag) to_html(frag) end
Sanitizes the given `Nokogiri::XML::Node` and all its children, modifying it in place.
If node is a `Nokogiri::XML::Document`, the `<html>` element must be whitelisted or an error will be raised.
# File lib/sanitize.rb, line 150 def node!(node) raise ArgumentError unless node.is_a?(Nokogiri::XML::Node) if node.is_a?(Nokogiri::XML::Document) unless @config[:elements].include?('html') raise Error, 'When sanitizing a document, "<html>" must be whitelisted.' end end node_whitelist = Set.new traverse(node) do |n| transform_node!(n, node_whitelist) end node end
Private Instance Methods
Preprocesses HTML before parsing to remove undesirable Unicode chars.
# File lib/sanitize.rb, line 174 def preprocess(html) html = html.to_s.dup unless html.encoding.name == 'UTF-8' html.encode!('UTF-8', :invalid => :replace, :undef => :replace) end html.gsub!(REGEX_UNSUITABLE_CHARS, '') html end
# File lib/sanitize.rb, line 187 def to_html(node) node.to_html(preserve_newline: true) end
# File lib/sanitize.rb, line 191 def transform_node!(node, node_whitelist) @transformers.each do |transformer| # Since transform_node! may be called in a tight loop to process thousands # of items, we can optimize both memory and CPU performance by: # # 1. Reusing the same config hash for each transformer # 2. Directly assigning values to hash instead of using merge!. Not only # does merge! create a new hash, it is also 2.6x slower: # https://github.com/JuanitoFatas/fast-ruby#hashmerge-vs-hashmerge-code config = @transformer_config config[:is_whitelisted] = node_whitelist.include?(node) config[:node] = node config[:node_name] = node.name.downcase config[:node_whitelist] = node_whitelist result = transformer.call(config) if result.is_a?(Hash) && result[:node_whitelist].respond_to?(:each) node_whitelist.merge(result[:node_whitelist]) end end node end
Performs top-down traversal of the given node, operating first on the node itself, then traversing each child (if any) in order.
# File lib/sanitize.rb, line 218 def traverse(node, &block) yield node child = node.child while child do prev = child.previous_sibling traverse(child, &block) if child.parent == node child = child.next_sibling else # The child was unlinked or reparented, so traverse the previous node's # next sibling, or the parent's first child if there is no previous # node. child = prev ? prev.next_sibling : node.child end end end