sanitize 1.2.0 → 1.2.1.dev.20100122

data/HISTORY

@@ -1,6 +1,15 @@
 Sanitize History
 ================================================================================
 
+Version 1.2.1 (git)
+  * Added a :remove_contents config setting. If set to true, Sanitize will
+    remove the contents of filtered nodes in addition to the nodes themselves.
+  * The environment hash passed into transformers now includes a :node_name item
+    containing the lowercase name of the current HTML node (e.g. "div").
+  * Returning anything other than a Hash or nil from a transformer will now
+    raise a meaningful Sanitize::Error exception rather than an unintended
+    NameError.
+
 Version 1.2.0 (2010-01-17)
   * Requires Nokogiri ~> 1.4.1.
   * Added support for transformers, which allow you to filter and alter nodes

data/README.rdoc

@@ -15,7 +15,7 @@ or maliciously-formed HTML. When in doubt, Sanitize always errs on the side of
 caution.
 
 *Author*::    Ryan Grove (mailto:ryan@wonko.com)
-*Version*::   1.2.0 (2010-01-17)
+*Version*::   1.2.1.dev (git)
 *Copyright*:: Copyright (c) 2010 Ryan Grove. All rights reserved.
 *License*::   MIT License (http://opensource.org/licenses/mit-license.php)
 *Website*::   http://github.com/rgrove/sanitize
@@ -33,7 +33,7 @@ Latest stable release:
 
 Latest development version:
 
-  gem install sanitize --prerelease
+  gem install sanitize --pre
 
 == Usage
 
@@ -89,17 +89,17 @@ configuration:
       :attributes => {'a' => ['href', 'title'], 'span' => ['class']},
       :protocols => {'a' => {'href' => ['http', 'https', 'mailto']}})
 
-==== :elements
+==== :add_attributes (Hash)
 
-Array of element names to allow. Specify all names in lowercase.
+Attributes to add to specific elements. If the attribute already exists, it will
+be replaced with the value specified here. Specify all element names and
+attributes in lowercase.
 
-  :elements => [
-    'a', 'b', 'blockquote', 'br', 'cite', 'code', 'dd', 'dl', 'dt', 'em',
-    'i', 'li', 'ol', 'p', 'pre', 'q', 'small', 'strike', 'strong', 'sub',
-    'sup', 'u', 'ul'
-  ]
+  :add_attributes => {
+    'a' => {'rel' => 'nofollow'}
+  }
 
-==== :attributes
+==== :attributes (Hash)
 
 Attributes to allow for specific elements. Specify all element names and
 attributes in lowercase.
@@ -118,17 +118,28 @@ If you'd like to allow certain attributes on all elements, use the symbol
     'a'  => ['href', 'title']
   }
 
-==== :add_attributes
+==== :allow_comments (boolean)
 
-Attributes to add to specific elements. If the attribute already exists, it will
-be replaced with the value specified here. Specify all element names and
-attributes in lowercase.
+Whether or not to allow HTML comments. Allowing comments is strongly
+discouraged, since IE allows script execution within conditional comments. The
+default value is <code>false</code>.
 
-  :add_attributes => {
-    'a' => {'rel' => 'nofollow'}
-  }
+==== :elements (Array)
+
+Array of element names to allow. Specify all names in lowercase.
+
+  :elements => [
+    'a', 'b', 'blockquote', 'br', 'cite', 'code', 'dd', 'dl', 'dt', 'em',
+    'i', 'li', 'ol', 'p', 'pre', 'q', 'small', 'strike', 'strong', 'sub',
+    'sup', 'u', 'ul'
+  ]
+
+==== :output (Symbol)
 
-==== :protocols
+Output format. Supported formats are <code>:html</code> and <code>:xhtml</code>,
+defaulting to <code>:xhtml</code>.
+
+==== :protocols (Hash)
 
 URL protocols to allow in specific attributes. If an attribute is listed here
 and contains a protocol other than those specified (or if it contains no
@@ -146,6 +157,16 @@ include the symbol <code>:relative</code> in the protocol array:
     'a' => {'href' => ['http', 'https', :relative]}
   }
 
+==== :remove_contents (boolean)
+
+If set to <code>true</code>, Sanitize will remove the contents of any filtered
+nodes in addition to the nodes themselves. By default, Sanitize leaves the safe
+parts of a node's contents behind when the node is removed.
+
+==== :transformers
+
+See below.
+
 === Transformers
 
 Transformers allow you to filter and alter nodes using your own custom logic, on
@@ -170,6 +191,9 @@ Hash that contains the following items:
 [<code>:node</code>]
   A Nokogiri::XML::Node object representing an HTML element.
 
+[<code>:node_name</code>]
+  The name of the current HTML node, always lowercase (e.g. "div" or "span").
+
 ==== Processing
 
 Each transformer has full access to the Nokogiri::XML::Node that's passed into
@@ -223,7 +247,7 @@ by just whitelisting all <code><object></code>, <code><embed></code>, and
 
   lambda do |env|
     node      = env[:node]
-    node_name = node.name.to_s.downcase
+    node_name = env[:node_name]
     parent    = node.parent
 
     # Since the transformer receives the deepest nodes first, we look for a

data/lib/sanitize.rb

@@ -144,7 +144,10 @@ class Sanitize
 
     # Delete any element that isn't in the whitelist.
     unless transform[:whitelist] || @config[:elements].include?(name)
-      node.children.each { |n| node.add_previous_sibling(n) }
+      unless @config[:remove_contents]
+        node.children.each { |n| node.add_previous_sibling(n) }
+      end
+
       node.unlink
       return
     end
@@ -200,8 +203,9 @@ class Sanitize
 
     @config[:transformers].inject(node) do |transformer_node, transformer|
       transform = transformer.call({
-        :config => @config,
-        :node   => transformer_node
+        :config    => @config,
+        :node      => transformer_node,
+        :node_name => transformer_node.name.downcase
       })
 
       if transform.nil?
@@ -224,4 +228,6 @@ class Sanitize
 
     return output
   end
+
+  class Error < StandardError; end
 end

data/lib/sanitize/config.rb

@@ -49,6 +49,11 @@ class Sanitize
       # to allow relative URLs sans protocol.
       :protocols => {},
 
+      # If this is true, Sanitize will remove the contents of any filtered nodes
+      # in addition to the nodes themselves. By default, Sanitize leaves the
+      # safe parts of a node's contents behind when the node is removed.
+      :remove_contents => false,
+
       # Transformers allow you to filter or alter nodes using custom logic. See
       # README.rdoc for details and examples.
       :transformers => []

data/lib/sanitize/version.rb

@@ -1,3 +1,3 @@
 class Sanitize
-  VERSION = '1.2.0'
+  VERSION = '1.2.1.dev.20100122'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sanitize
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
+  version: 1.2.1.dev.20100122
 platform: ruby
 authors: 
 - Ryan Grove
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-17 00:00:00 -08:00
+date: 2010-01-22 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -77,9 +77,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
   version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
-      version: "0"
+      version: 1.3.1
   version: 
 requirements: []