selma 0.0.4-x86_64-linux → 0.0.6-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3b9b090cd0f742bd24d8bd1d065b45d0b142b690141cce378258c8bd231501d
-  data.tar.gz: '08eaf21b2ab2161bb5daadf451175cb3e37a4c4ab9212c294450a73291f06460'
+  metadata.gz: be9face4692cbc6653b2085a056679aab5eca490517f3fa17e4f53ac5c9b4028
+  data.tar.gz: 47fa7091498f304b8aba324637218b7ca0af09e8370084337f1e588be677ac3e
 SHA512:
-  metadata.gz: 8be8197fb86053ae0aa6e957a2694812be266a5d3903d15c59ede3768811b11639002d92f21217428fb89e023022544cfcd930191dec20b3d7d12934d6337a0f
-  data.tar.gz: 9e059e1e25bc52ad38ea64dd0d8b9654caaf4ce67aaa33bd6e1d1187ac534d92dc4c9631bff7457d76f7d685100d93b69e18e335dc4f6b69d8dcc053c36e0179
+  metadata.gz: 9e57f2b3f8a82aa92cbc68c17a465226631af6bc1c89150a65e58a0b87d37698418799f812083de22590fdf11a18e1991d847f6273c7d9d03c66fd4139c10cc7
+  data.tar.gz: 66f079b74f387266446c5293b17dd1a534de422c1b7a7149ff562a4a9a05fefd7857216d2e6a782d92eecb7595ec5e1ba7b2e94c2a56350caef63c2d768a3901

data/README.md

@@ -24,23 +24,27 @@ Or install it yourself as:
 
 ## Usage
 
-Selma can perform two different actions:
+Selma can perform two different actions, either independently or together:
 
 - Sanitize HTML, through a [Sanitize](https://github.com/rgrove/sanitize)-like allowlist syntax; and
-- Select HTML using CSS rules, and manipulate elements and text
+- Select HTML using CSS rules, and manipulate elements and text nodes along the way.
 
-The basic API for Selma looks like this:
+It does this through two kwargsL `sanitizer` and `handlers`. The basic API for Selma looks like this:
 
 ```ruby
-rewriter = Selma::Rewriter.new(sanitizer: sanitizer_config, handlers: [MatchAttribute.new, TextRewrite.new])
+sanitizer_config = {
+   elements: ["b", "em", "i", "strong", "u"],
+}
+sanitizer = Selma::Sanitizer.new(sanitizer_config)
+rewriter = Selma::Rewriter.new(sanitizer: sanitizer, handlers: [MatchElementRewrite.new, MatchTextRewrite.new])
 rewriter(html)
 ```
 
-Let's take a look at each part individually.
+Here's a look at each individual part.
 
 ### Sanitization config
 
-Selma sanitizes by default. That is, even if the `sanitizer` kwarg is not passed in, sanitization occurs. If you want to disable HTML sanitization (for some reason), pass `nil`:
+Selma sanitizes by default. That is, even if the `sanitizer` kwarg is not passed in, sanitization occurs. If you truly want to disable HTML sanitization (for some reason), pass `nil`:
 
 ```ruby
 Selma::Rewriter.new(sanitizer: nil) # dangerous and ill-advised
@@ -87,22 +91,22 @@ whitespace_elements: ["blockquote", "h1", "h2", "h3", "h4", "h5", "h6", ]
 
 ### Defining handlers
 
-The real power in Selma comes in its use of handlers. A handler is simply an object with various methods:
+The real power in Selma comes in its use of handlers. A handler is simply an object with various methods defined:
 
 - `selector`, a method which MUST return instance of `Selma::Selector` which defines the CSS classes to match
 - `handle_element`, a method that's call on each matched element
-- `handle_text_chunk`, a method that's called on each matched text node; this MUST return a string
+- `handle_text_chunk`, a method that's called on each matched text node
 
 Here's an example which rewrites the `href` attribute on `a` and the `src` attribute on `img` to be `https` rather than `http`.
 
 ```ruby
 class MatchAttribute
-  SELECTOR = Selma::Selector(match_element: "a, img")
+  SELECTOR = Selma::Selector(match_element: %(a[href^="http:"], img[src^="http:"]"))
 
   def handle_element(element)
-    if element.tag_name == "a" && element["href"] =~ /^http:/
+    if element.tag_name == "a"
       element["href"] = rename_http(element["href"])
-    elsif element.tag_name == "img" && element["src"] =~ /^http:/
+    elsif element.tag_name == "img"
       element["src"] = rename_http(element["src"])
     end
   end
@@ -118,10 +122,10 @@ rewriter = Selma::Rewriter.new(handlers: [MatchAttribute.new])
 The `Selma::Selector` object has three possible kwargs:
 
 - `match_element`: any element which matches this CSS rule will be passed on to `handle_element`
-- `match_text_within`: any element which matches this CSS rule will be passed on to `handle_text_chunk`
+- `match_text_within`: any text_chunk which matches this CSS rule will be passed on to `handle_text_chunk`
 - `ignore_text_within`: this is an array of element names whose text contents will be ignored
 
-You've seen an example of `match_element`; here's one for `match_text` which changes strings in various elements which are _not_ `pre` or `code`:
+Here's an example for `handle_text_chunk` which changes strings in various elements which are _not_ `pre` or `code`:
 
 ```ruby
 
@@ -144,20 +148,63 @@ rewriter = Selma::Rewriter.new(handlers: [MatchText.new])
 
 The `element` argument in `handle_element` has the following methods:
 
-- `tag_name`: The element's name
-- `[]`: get an attribute
-- `[]=`: set an attribute
-- `remove_attribute`: remove an attribute
-- `attributes`: list all the attributes
-- `ancestors`: list all the ancestors
-- `append(content, as: content_type)`: appends `content` to the element's inner content, i.e. inserts content right before the element's end tag. `content_type` is either `:text` or `:html` and determines how the content will be applied.
+- `tag_name`: Gets the element's name
+- `tag_name=`: Sets the element's name
+- `self_closing?`: A bool which identifies whether or not the element is self-closing
+- `[]`: Get an attribute
+- `[]=`: Set an attribute
+- `remove_attribute`: Remove an attribute
+- `has_attribute?`: A bool which identifies whether or not the element has an attribute
+- `attributes`: List all the attributes
+- `ancestors`: List all of an element's ancestors as an array of strings
 - `before(content, as: content_type)`: Inserts `content` before the element. `content_type` is either `:text` or `:html` and determines how the content will be applied.
 - `after(content, as: content_type)`: Inserts `content` after the element. `content_type` is either `:text` or `:html` and determines how the content will be applied.
-- `set_inner_content`: replaces inner content of the element with `content`. `content_type` is either `:text` or `:html` and determines how the content will be applied.
+- `prepend(content, as: content_type)`: prepends `content` to the element's inner content, i.e. inserts content right after the element's start tag. `content_type` is either `:text` or `:html` and determines how the content will be applied.
+- `append(content, as: content_type)`: appends `content` to the element's inner content, i.e. inserts content right before the element's end tag. `content_type` is either `:text` or `:html` and determines how the content will be applied.
+- `set_inner_content`: Replaces inner content of the element with `content`. `content_type` is either `:text` or `:html` and determines how the content will be applied.
+
+#### `text_chunk` methods
+
+- `to_s` / `.content`: Gets the text node's content
+- `text_type`: identifies the type of text in the text node
+- `before(content, as: content_type)`: Inserts `content` before the text. `content_type` is either `:text` or `:html` and determines how the content will be applied.
+- `after(content, as: content_type)`: Inserts `content` after the text. `content_type` is either `:text` or `:html` and determines how the content will be applied.
+- `replace(content, as: content_type)`: Replaces the text node with `content`. `content_type` is either `:text` or `:html` and determines how the content will be applied.
 
 ## Benchmarks
 
-TBD
+<details>
+<pre>
+ruby test/benchmark.rb
+ruby test/benchmark.rb
+Warming up --------------------------------------
+sanitize-document-huge
+                         1.000  i/100ms
+ selma-document-huge     1.000  i/100ms
+Calculating -------------------------------------
+sanitize-document-huge
+                          0.257  (± 0.0%) i/s -      2.000  in   7.783398s
+ selma-document-huge      4.602  (± 0.0%) i/s -     23.000  in   5.002870s
+Warming up --------------------------------------
+sanitize-document-medium
+                         2.000  i/100ms
+selma-document-medium
+                        22.000  i/100ms
+Calculating -------------------------------------
+sanitize-document-medium
+                         28.676  (± 3.5%) i/s -    144.000  in   5.024669s
+selma-document-medium
+                        121.500  (±22.2%) i/s -    594.000  in   5.135410s
+Warming up --------------------------------------
+sanitize-document-small
+                        10.000  i/100ms
+selma-document-small    20.000  i/100ms
+Calculating -------------------------------------
+sanitize-document-small
+                        107.280  (± 0.9%) i/s -    540.000  in   5.033850s
+selma-document-small    118.867  (±31.1%) i/s -    540.000  in   5.080726s
+</pre>
+</details>
 
 ## Contributing
 

data/ext/selma/src/html/element.rs

@@ -36,6 +36,48 @@ impl SelmaHTMLElement {
         }
     }
 
+    fn set_tag_name(&self, name: String) -> Result<(), Error> {
+        let mut binding = self.0.borrow_mut();
+
+        if let Ok(element) = binding.element.get_mut() {
+            match element.set_tag_name(&name) {
+                Ok(_) => Ok(()),
+                Err(err) => Err(Error::new(exception::runtime_error(), format!("{err:?}"))),
+            }
+        } else {
+            Err(Error::new(
+                exception::runtime_error(),
+                "`set_tag_name` is not available",
+            ))
+        }
+    }
+
+    fn is_self_closing(&self) -> Result<bool, Error> {
+        let binding = self.0.borrow();
+
+        if let Ok(e) = binding.element.get() {
+            Ok(e.is_self_closing())
+        } else {
+            Err(Error::new(
+                exception::runtime_error(),
+                "`is_self_closing` is not available",
+            ))
+        }
+    }
+
+    fn has_attribute(&self, attr: String) -> Result<bool, Error> {
+        let binding = self.0.borrow();
+
+        if let Ok(e) = binding.element.get() {
+            Ok(e.has_attribute(&attr))
+        } else {
+            Err(Error::new(
+                exception::runtime_error(),
+                "`is_self_closing` is not available",
+            ))
+        }
+    }
+
     fn get_attribute(&self, attr: String) -> Option<String> {
         let binding = self.0.borrow();
         let element = binding.element.get();
@@ -132,6 +174,20 @@ impl SelmaHTMLElement {
         Ok(())
     }
 
+    fn prepend(&self, args: &[Value]) -> Result<(), Error> {
+        let mut binding = self.0.borrow_mut();
+        let element = binding.element.get_mut().unwrap();
+
+        let (text_str, content_type) = match crate::scan_text_args(args) {
+            Ok((text_str, content_type)) => (text_str, content_type),
+            Err(err) => return Err(err),
+        };
+
+        element.prepend(&text_str, content_type);
+
+        Ok(())
+    }
+
     fn append(&self, args: &[Value]) -> Result<(), Error> {
         let mut binding = self.0.borrow_mut();
         let element = binding.element.get_mut().unwrap();
@@ -167,17 +223,27 @@ pub fn init(c_html: RClass) -> Result<(), Error> {
         .expect("cannot find class Selma::HTML::Element");
 
     c_element.define_method("tag_name", method!(SelmaHTMLElement::tag_name, 0))?;
+    c_element.define_method("tag_name=", method!(SelmaHTMLElement::set_tag_name, 1))?;
+    c_element.define_method(
+        "self_closing?",
+        method!(SelmaHTMLElement::is_self_closing, 0),
+    )?;
     c_element.define_method("[]", method!(SelmaHTMLElement::get_attribute, 1))?;
     c_element.define_method("[]=", method!(SelmaHTMLElement::set_attribute, 2))?;
     c_element.define_method(
         "remove_attribute",
         method!(SelmaHTMLElement::remove_attribute, 1),
     )?;
+    c_element.define_method(
+        "has_attribute?",
+        method!(SelmaHTMLElement::has_attribute, 1),
+    )?;
     c_element.define_method("attributes", method!(SelmaHTMLElement::get_attributes, 0))?;
     c_element.define_method("ancestors", method!(SelmaHTMLElement::get_ancestors, 0))?;
 
     c_element.define_method("before", method!(SelmaHTMLElement::before, -1))?;
     c_element.define_method("after", method!(SelmaHTMLElement::after, -1))?;
+    c_element.define_method("prepend", method!(SelmaHTMLElement::prepend, -1))?;
     c_element.define_method("append", method!(SelmaHTMLElement::append, -1))?;
     c_element.define_method(
         "set_inner_content",

data/ext/selma/src/html/text_chunk.rs

@@ -54,6 +54,34 @@ impl SelmaHTMLTextChunk {
         }
     }
 
+    fn before(&self, args: &[Value]) -> Result<(), Error> {
+        let mut binding = self.0.borrow_mut();
+        let text_chunk = binding.text_chunk.get_mut().unwrap();
+
+        let (text_str, content_type) = match crate::scan_text_args(args) {
+            Ok((text_str, content_type)) => (text_str, content_type),
+            Err(err) => return Err(err),
+        };
+
+        text_chunk.before(&text_str, content_type);
+
+        Ok(())
+    }
+
+    fn after(&self, args: &[Value]) -> Result<(), Error> {
+        let mut binding = self.0.borrow_mut();
+        let text_chunk = binding.text_chunk.get_mut().unwrap();
+
+        let (text_str, content_type) = match crate::scan_text_args(args) {
+            Ok((text_str, content_type)) => (text_str, content_type),
+            Err(err) => return Err(err),
+        };
+
+        text_chunk.after(&text_str, content_type);
+
+        Ok(())
+    }
+
     fn replace(&self, args: &[Value]) -> Result<(), Error> {
         let mut binding = self.0.borrow_mut();
         let text_chunk = binding.text_chunk.get_mut().unwrap();
@@ -77,6 +105,8 @@ pub fn init(c_html: RClass) -> Result<(), Error> {
     c_text_chunk.define_method("to_s", method!(SelmaHTMLTextChunk::to_s, 0))?;
     c_text_chunk.define_method("content", method!(SelmaHTMLTextChunk::to_s, 0))?;
     c_text_chunk.define_method("text_type", method!(SelmaHTMLTextChunk::text_type, 0))?;
+    c_text_chunk.define_method("before", method!(SelmaHTMLTextChunk::before, -1))?;
+    c_text_chunk.define_method("after", method!(SelmaHTMLTextChunk::after, -1))?;
     c_text_chunk.define_method("replace", method!(SelmaHTMLTextChunk::replace, -1))?;
 
     Ok(())

data/ext/selma/src/sanitizer.rs

@@ -1,4 +1,4 @@
-use std::{borrow::BorrowMut, cell::RefMut, collections::HashMap};
+use std::{borrow::BorrowMut, collections::HashMap};
 
 use lol_html::{
     errors::AttributeNameError,
@@ -14,6 +14,18 @@ struct ElementSanitizer {
     protocol_sanitizers: HashMap<String, Vec<String>>,
 }
 
+impl Default for ElementSanitizer {
+    fn default() -> Self {
+        ElementSanitizer {
+            allowed_attrs: vec![],
+            allowed_classes: vec![],
+            required_attrs: vec![],
+
+            protocol_sanitizers: HashMap::new(),
+        }
+    }
+}
+
 #[derive(Clone, Debug)]
 pub struct Sanitizer {
     flags: [u8; crate::tags::Tag::TAG_COUNT],
@@ -49,13 +61,7 @@ impl SelmaSanitizer {
 
         let mut element_sanitizers = HashMap::new();
         crate::tags::Tag::html_tags().iter().for_each(|html_tag| {
-            let es = ElementSanitizer {
-                allowed_attrs: vec![],
-                allowed_classes: vec![],
-                required_attrs: vec![],
-
-                protocol_sanitizers: HashMap::new(),
-            };
+            let es = ElementSanitizer::default();
             element_sanitizers.insert(
                 crate::tags::Tag::element_name_from_enum(html_tag).to_string(),
                 es,
@@ -169,7 +175,8 @@ impl SelmaSanitizer {
             let allowed_attrs = &mut binding.allowed_attrs;
             Self::set_allowed(allowed_attrs, &attr_name, allow);
         } else {
-            let element_sanitizer = Self::get_mut_element_sanitizer(&mut binding, &element_name);
+            let element_sanitizers = &mut binding.element_sanitizers;
+            let element_sanitizer = Self::get_element_sanitizer(element_sanitizers, &element_name);
 
             element_sanitizer.allowed_attrs.push(attr_name);
         }
@@ -183,7 +190,8 @@ impl SelmaSanitizer {
             let allowed_classes = &mut binding.allowed_classes;
             Self::set_allowed(allowed_classes, &class_name, allow);
         } else {
-            let element_sanitizer = Self::get_mut_element_sanitizer(&mut binding, &element_name);
+            let element_sanitizers = &mut binding.element_sanitizers;
+            let element_sanitizer = Self::get_element_sanitizer(element_sanitizers, &element_name);
 
             let allowed_classes = element_sanitizer.allowed_classes.borrow_mut();
             Self::set_allowed(allowed_classes, &class_name, allow)
@@ -194,9 +202,10 @@ impl SelmaSanitizer {
     fn set_allowed_protocols(&self, element_name: String, attr_name: String, allow_list: RArray) {
         let mut binding = self.0.borrow_mut();
 
-        let element_sanitizer = Self::get_mut_element_sanitizer(&mut binding, &element_name);
+        let element_sanitizers = &mut binding.element_sanitizers;
+        let element_sanitizer = Self::get_element_sanitizer(element_sanitizers, &element_name);
 
-        let protocol_sanitizers = element_sanitizer.protocol_sanitizers.borrow_mut();
+        let protocol_sanitizers = &mut element_sanitizer.protocol_sanitizers.borrow_mut();
 
         for opt_allowed_protocol in allow_list.each() {
             let allowed_protocol = opt_allowed_protocol.unwrap();
@@ -237,9 +246,15 @@ impl SelmaSanitizer {
     }
 
     pub fn sanitize_attributes(&self, element: &mut Element) -> Result<(), AttributeNameError> {
-        let binding = self.0.borrow_mut();
         let tag = crate::tags::Tag::tag_from_element(element);
-        let element_sanitizer = Self::get_element_sanitizer(&binding, &element.tag_name());
+        let tag_name = &element.tag_name();
+        let element_sanitizer = {
+            let mut binding = self.0.borrow_mut();
+            let element_sanitizers = &mut binding.element_sanitizers;
+            Self::get_element_sanitizer(element_sanitizers, tag_name).clone()
+        };
+
+        let binding = self.0.borrow();
 
         // FIXME: This is a hack to get around the fact that we can't borrow
         let attribute_map: HashMap<String, String> = element
@@ -265,7 +280,7 @@ impl SelmaSanitizer {
             let should_keep_attrubute = match Self::should_keep_attribute(
                 &binding,
                 element,
-                element_sanitizer,
+                &element_sanitizer,
                 attr_name,
                 &unescaped_attr_val,
             ) {
@@ -323,7 +338,7 @@ impl SelmaSanitizer {
     }
 
     fn should_keep_attribute(
-        binding: &RefMut<Sanitizer>,
+        binding: &Sanitizer,
         element: &mut Element,
         element_sanitizer: &ElementSanitizer,
         attr_name: &String,
@@ -410,7 +425,7 @@ impl SelmaSanitizer {
     }
 
     fn sanitize_class_attribute(
-        binding: &RefMut<Sanitizer>,
+        binding: &Sanitizer,
         element: &mut Element,
         element_sanitizer: &ElementSanitizer,
         attr_name: &str,
@@ -528,17 +543,12 @@ impl SelmaSanitizer {
     }
 
     fn get_element_sanitizer<'a>(
-        binding: &'a RefMut<Sanitizer>,
-        element_name: &str,
-    ) -> &'a ElementSanitizer {
-        binding.element_sanitizers.get(element_name).unwrap()
-    }
-
-    fn get_mut_element_sanitizer<'a>(
-        binding: &'a mut Sanitizer,
+        element_sanitizers: &'a mut HashMap<String, ElementSanitizer>,
         element_name: &str,
     ) -> &'a mut ElementSanitizer {
-        binding.element_sanitizers.get_mut(element_name).unwrap()
+        element_sanitizers
+            .entry(element_name.to_string())
+            .or_insert_with(ElementSanitizer::default)
     }
 }
 

data/lib/selma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Selma
-  VERSION = "0.0.4"
+  VERSION = "0.0.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: selma
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.6
 platform: x86_64-linux
 authors:
 - Garen J. Torikian
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-26 00:00:00.000000000 Z
+date: 2022-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys