sanitize 2.0.0.dev.20101225 → 2.0.0.dev.20110105

data/HISTORY.md

@@ -16,14 +16,17 @@ Version 2.0.0 (git)
     `<br>` and `<p>`) that should be replaced with whitespace when removed in
     order to preserve readability. See the README for the default list of
     elements that will be replaced with whitespace when removed.
+  * Added a `:transformers_breadth` config, which may be used to specify
+    transformers that should traverse nodes in a breadth-first mode rather than
+    the default depth-first mode.
   * Added the `abbr`, `dfn`, `kbd`, `mark`, `s`, `samp`, `time`, and `var`
     elements to the whitelists for the basic and relaxed configs.
   * Added the `bdo`, `del`, `figcaption`, `figure`, `hgroup`, `ins`, `rp`, `rt`,
     `ruby`, and `wbr` elements to the whitelist for the relaxed config.
   * The `dir`, `lang`, and `title` attributes are now whitelisted for all
     elements in the relaxed config.
-  * Bumped minimum Nokogiri version to 1.4.4 to avoid a bug in 1.4.2+ (issue
-    #315) that caused `</body></html>` to be appended to the CDATA inside
+  * Bumped minimum Nokogiri version to 1.4.4 to avoid a bug in 1.4.2+
+    (issue #315) that caused `</body></html>` to be appended to the CDATA inside
     unterminated script and style elements.
 
 

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Ryan Grove <ryan@wonko.com>
+Copyright (c) 2011 Ryan Grove <ryan@wonko.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the 'Software'), to deal in

data/README.rdoc

@@ -15,7 +15,7 @@ or maliciously-formed HTML, and will always output valid HTML or XHTML.
 
 *Author*::    Ryan Grove (mailto:ryan@wonko.com)
 *Version*::   2.0.0 (git)
-*Copyright*:: Copyright (c) 2010 Ryan Grove. All rights reserved.
+*Copyright*:: Copyright (c) 2011 Ryan Grove. All rights reserved.
 *License*::   MIT License (http://opensource.org/licenses/mit-license.php)
 *Website*::   http://github.com/rgrove/sanitize
 
@@ -173,8 +173,13 @@ The default value is <code>false</code>.
 
 ==== :transformers
 
-Custom transformer or array of custom transformers. See the Transformers section
-below for details.
+Custom transformer or array of custom transformers to run using depth-first
+traversal. See the Transformers section below for details.
+
+=== :transformers_breadth
+
+Custom transformer or array of custom transformers to run using breadth-first
+traversal. See the Transformers section below for details.
 
 ==== :whitespace_elements (Array)
 
@@ -230,6 +235,10 @@ receive as an argument an environment Hash that contains the following items:
   whitelisted by previous transformers, if any. It's generally bad form to
   remove a node that a previous transformer has whitelisted.
 
+[<code>:traversal_mode</code>]
+  Current node traversal mode, either <code>:depth</code> for depth-first (the
+  default mode) or <code>:breadth</code> for breadth-first.
+
 ==== Output
 
 A transformer doesn't have to return anything, but may optionally return a Hash,
@@ -252,9 +261,9 @@ reflected instantly in the document and passed on to subsequently-called
 transformers and to Sanitize itself. A transformer may even call Sanitize
 internally to perform custom sanitization if needed.
 
-Nodes are passed into transformers in the order in which they're traversed. It's
-important to note that Nokogiri traverses markup from the deepest node upward,
-not from the first node to the last node:
+Nodes are passed into transformers in the order in which they're traversed. By
+default, depth-first traversal is used, meaning that markup is traversed from
+the deepest node upward (not from the first node to the last node):
 
   html        = '<div><span>foo</span></div>'
   transformer = lambda{|env| puts env[:node_name] }
@@ -262,17 +271,26 @@ not from the first node to the last node:
   # Prints "text", "span", "div", "#document-fragment".
   Sanitize.clean(html, :transformers => transformer)
 
+You may use the <code>:transformers_breadth</code> config to specify one or more
+transformers that should traverse nodes in breadth-first mode:
+
+  html        = '<div><span>foo</span></div>'
+  transformer = lambda{|env| puts env[:node_name] }
+
+  # Prints "#document-fragment", "div", "span", "text".
+  Sanitize.clean(html, :transformers_breadth => transformer)
+
 Transformers have a tremendous amount of power, including the power to
 completely bypass Sanitize's built-in filtering. Be careful! Your safety is in
 your own hands.
 
 ==== Example: Transformer to whitelist YouTube video embeds
 
-The following example demonstrates how to create a Sanitize transformer that
-will safely whitelist valid YouTube video embeds without having to blindly allow
-other kinds of embedded content, which would be the case if you tried to do this
-by just whitelisting all <code><object></code>, <code><embed></code>, and
-<code><param></code> elements:
+The following example demonstrates how to create a depth-first Sanitize
+transformer that will safely whitelist valid YouTube video embeds without having
+to blindly allow other kinds of embedded content, which would be the case if you
+tried to do this by just whitelisting all <code><object></code>,
+<code><embed></code>, and <code><param></code> elements:
 
   lambda do |env|
     node      = env[:node]
@@ -323,7 +341,7 @@ by just whitelisting all <code><object></code>, <code><embed></code>, and
 
 == Contributors
 
-Sanitize was created and is currently maintained by Ryan Grove (ryan@wonko.com).
+Sanitize was created and is maintained by Ryan Grove (ryan@wonko.com).
 
 The following lovely people have also contributed to Sanitize:
 
@@ -341,7 +359,7 @@ The following lovely people have also contributed to Sanitize:
 
 == License
 
-Copyright (c) 2010 Ryan Grove (ryan@wonko.com)
+Copyright (c) 2011 Ryan Grove (ryan@wonko.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the 'Software'), to deal in

data/lib/sanitize.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 #--
-# Copyright (c) 2010 Ryan Grove <ryan@wonko.com>
+# Copyright (c) 2011 Ryan Grove <ryan@wonko.com>
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -70,14 +70,18 @@ class Sanitize
 
   # Returns a new Sanitize object initialized with the settings in _config_.
   def initialize(config = {})
-    @config       = Config::DEFAULT.merge(config)
-    @transformers = Array(@config[:transformers].dup)
+    @config = Config::DEFAULT.merge(config)
 
-    # Default transformers. These always run at the end of the transformer
-    # chain, after any custom transformers.
-    @transformers << Transformers::CleanComment unless @config[:allow_comments]
+    @transformers = {
+      :breadth => Array(@config[:transformers_breadth].dup),
+      :depth   => Array(@config[:transformers]) + Array(@config[:transformers_depth])
+    }
 
-    @transformers <<
+    # Default depth transformers. These always run at the end of the chain,
+    # after any custom transformers.
+    @transformers[:depth] << Transformers::CleanComment unless @config[:allow_comments]
+
+    @transformers[:depth] <<
         Transformers::CleanCDATA <<
         Transformers::CleanElement.new(@config)
   end
@@ -117,34 +121,49 @@ class Sanitize
     raise ArgumentError unless node.is_a?(Nokogiri::XML::Node)
 
     node_whitelist = Set.new
-    node.traverse {|child| transform_node!(child, node_whitelist) }
 
+    unless @transformers[:breadth].empty?
+      traverse_breadth(node) {|n| transform_node!(n, node_whitelist, :breadth) }
+    end
+
+    traverse_depth(node) {|n| transform_node!(n, node_whitelist, :depth) }
     node
   end
 
   private
 
-  def transform_node!(node, node_whitelist)
-    @transformers.each do |transformer|
+  def transform_node!(node, node_whitelist, mode)
+    @transformers[mode].each do |transformer|
       result = transformer.call({
         :config         => @config,
         :is_whitelisted => node_whitelist.include?(node),
         :node           => node,
         :node_name      => node.name.downcase,
-        :node_whitelist => node_whitelist
+        :node_whitelist => node_whitelist,
+        :traversal_mode => mode
       })
 
       if result.is_a?(Hash) && result[:node_whitelist].respond_to?(:each)
         node_whitelist.merge(result[:node_whitelist])
       end
-
-      # If the node has been unlinked or replaced, there's no point running
-      # subsequent transformers.
-      break if node.parent.nil? && !node.fragment?
     end
 
     node
   end
 
+  # Performs breadth-first traversal, operating first on the root node, then
+  # traversing downwards.
+  def traverse_breadth(node, &block)
+    block.call(node)
+    node.children.each {|child| traverse_breadth(child, &block) }
+  end
+
+  # Performs depth-first traversal, operating first on the deepest nodes in the
+  # document, then traversing upwards to the root.
+  def traverse_depth(node, &block)
+    node.children.each {|child| traverse_depth(child, &block) }
+    block.call(node)
+  end
+
   class Error < StandardError; end
 end

data/lib/sanitize/config.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2010 Ryan Grove <ryan@wonko.com>
+# Copyright (c) 2011 Ryan Grove <ryan@wonko.com>
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -66,6 +66,11 @@ class Sanitize
       # README.rdoc for details and examples.
       :transformers => [],
 
+      # By default, transformers perform depth-first traversal (deepest node
+      # upward). This setting allows you to specify transformers that should
+      # perform breadth-first traversal (top node downward).
+      :transformers_breadth => [],
+
       # Elements which, when removed, should have their contents surrounded by
       # space characters to preserve readability. For example,
       # `foo<div>bar</div>baz` will become 'foo bar baz' when the <div> is
@@ -74,6 +79,7 @@ class Sanitize
         address article aside blockquote br dd div dl dt footer h1 h2 h3 h4 h5
         h6 header hgroup hr li nav ol p pre section ul
       ]
+
     }
   end
 end

data/lib/sanitize/config/basic.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2010 Ryan Grove <ryan@wonko.com>
+# Copyright (c) 2011 Ryan Grove <ryan@wonko.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal

data/lib/sanitize/config/relaxed.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2010 Ryan Grove <ryan@wonko.com>
+# Copyright (c) 2011 Ryan Grove <ryan@wonko.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal

data/lib/sanitize/config/restricted.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2010 Ryan Grove <ryan@wonko.com>
+# Copyright (c) 2011 Ryan Grove <ryan@wonko.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal

data/lib/sanitize/transformers/clean_element.rb

@@ -6,18 +6,15 @@ class Sanitize; module Transformers
 
       # For faster lookups.
       @add_attributes          = config[:add_attributes]
-      @allowed_elements        = {}
+      @allowed_elements        = Set.new(config[:elements])
       @attributes              = config[:attributes]
       @protocols               = config[:protocols]
       @remove_all_contents     = false
-      @remove_element_contents = {}
-      @whitespace_elements     = {}
-
-      config[:elements].each {|el| @allowed_elements[el] = true }
-      config[:whitespace_elements].each {|el| @whitespace_elements[el] = true }
+      @remove_element_contents = Set.new
+      @whitespace_elements     = Set.new(config[:whitespace_elements])
 
       if config[:remove_contents].is_a?(Array)
-        config[:remove_contents].each {|el| @remove_element_contents[el] = true }
+        @remove_element_contents.merge(config[:remove_contents])
       else
         @remove_all_contents = !!config[:remove_contents]
       end
@@ -30,10 +27,10 @@ class Sanitize; module Transformers
       return if env[:is_whitelisted] || !node.element?
 
       # Delete any element that isn't in the config whitelist.
-      unless @allowed_elements[name]
+      unless @allowed_elements.include?(name)
         # Elements like br, div, p, etc. need to be replaced with whitespace in
         # order to preserve readability.
-        if @whitespace_elements[name]
+        if @whitespace_elements.include?(name)
           node.add_previous_sibling(Nokogiri::XML::Text.new(' ', node.document))
 
           unless node.children.empty?
@@ -41,7 +38,7 @@ class Sanitize; module Transformers
           end
         end
 
-        unless @remove_all_contents || @remove_element_contents[name]
+        unless @remove_all_contents || @remove_element_contents.include?(name)
           node.children.each {|n| node.add_previous_sibling(n) }
         end
 

data/lib/sanitize/version.rb

@@ -1,3 +1,3 @@
 class Sanitize
-  VERSION = '2.0.0.dev.20101225'
+  VERSION = '2.0.0.dev.20110105'
 end

metadata

@@ -7,8 +7,8 @@ version: !ruby/object:Gem::Version
   - 0
   - 0
   - dev
-  - 20101225
-  version: 2.0.0.dev.20101225
+  - 20110105
+  version: 2.0.0.dev.20110105
 platform: ruby
 authors: 
 - Ryan Grove
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-25 00:00:00 -08:00
+date: 2011-01-05 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency