Class: Loofah::Scrubber

Inherits:
Object
  • Object
show all
Defined in:
lib/loofah/scrubber.rb

Overview

A Scrubber wraps up a block (or method) that is run on an HTML node (element):

# change all <span> tags to <div> tags
span2div = Loofah::Scrubber.new do |node|
 node.name = "div" if node.name == "span"
end

Alternatively, this scrubber could have been implemented as:

class Span2Div < Loofah::Scrubber
 def scrub(node)
   node.name = "div" if node.name == "span"
 end
end
span2div = Span2Div.new

This can then be run on a document:

Loofah.html5_fragment("<span>foo</span><p>bar</p>").scrub!(span2div).to_s
# => "<div>foo</div><p>bar</p>"

Scrubbers can be run on a document in either a top-down traversal (the default) or bottom-up. Top-down scrubbers can optionally return Scrubber::STOP to terminate the traversal of a subtree.

Constant Summary collapse

CONTINUE =

Top-down Scrubbers may return CONTINUE to indicate that the subtree should be traversed.

Object.new.freeze
STOP =

Top-down Scrubbers may return STOP to indicate that the subtree should not be traversed.

Object.new.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}, &block) ⇒ Scrubber

Options may include :direction => :top_down (the default) or :direction => :bottom_up

For top_down traversals, if the block returns Loofah::Scrubber::STOP, then the traversal will be terminated for the current node's subtree.

Alternatively, a Scrubber may inherit from Loofah::Scrubber, and implement scrub, which is slightly faster than using a block.



65
66
67
68
69
70
71
72
73
 
# File 'lib/loofah/scrubber.rb', line 65

def initialize(options = {}, &block)
  direction = options[:direction] || :top_down
  unless [:top_down, :bottom_up].include?(direction)
    raise ArgumentError, "direction #{direction} must be one of :top_down or :bottom_up"
  end

  @direction = direction
  @block = block
end

Instance Attribute Details

#block ⇒ Object (readonly)

When a scrubber is initialized, the optional block is saved as :block. Note that, if no block is passed, then the scrub method is assumed to have been implemented.



49
50
51
 
# File 'lib/loofah/scrubber.rb', line 49

def block
  @block
end

#direction ⇒ Object (readonly)

When a scrubber is initialized, the :direction may be specified as :top_down (the default) or :bottom_up.



44
45
46
 
# File 'lib/loofah/scrubber.rb', line 44

def direction
  @direction
end

Instance Method Details

#append_attribute(node, attribute, value) ⇒ Object

If the attribute is not set, add it If the attribute is set, don't overwrite the existing value



96
97
98
99
100
101
 
# File 'lib/loofah/scrubber.rb', line 96

def append_attribute(node, attribute, value)
  current_value = node.get_attribute(attribute) || ""
  current_values = current_value.split(/\s+/)
  updated_value = current_values | [value]
  node.set_attribute(attribute, updated_value.join(" "))
end

#scrub(node) ⇒ Object

When new is not passed a block, the class may implement scrub, which will be called for each document node.

Raises:



88
89
90
 
# File 'lib/loofah/scrubber.rb', line 88

def scrub(node)
  raise ScrubberNotFound, "No scrub method has been defined on #{self.class}"
end

#traverse(node) ⇒ Object

Calling traverse will cause the document to be traversed by either the lambda passed to the initializer or the scrub method, in the direction specified at new time.



80
81
82
 
# File 'lib/loofah/scrubber.rb', line 80

def traverse(node)
  direction == :bottom_up ? traverse_conditionally_bottom_up(node) : traverse_conditionally_top_down(node)
end