premailer 1.19.0 → 1.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e81cf33d2027d02e79ecb94b7a535a54b45d0f62170195baecc51e150fdc4e8
-  data.tar.gz: ef4b18d2837a8a80565da581d4ad075115c2457ff2087cff1757c099d4a5724d
+  metadata.gz: 9d0463a94da370db30e1e80fa7851c90f9b24743518137a2d04b2c21ed7246cd
+  data.tar.gz: 73bf8f6e3f7cade9389ff65a6fef58112e8cf2a756f0271adc8b3278bd998a5b
 SHA512:
-  metadata.gz: 15a9659bb308546d7617c8bb09d79cf9d140e0773111309f078958f4b27c7964b331c78787bda3abb221d2b0561de0ba31a2eb007c853bd41d14f8ca1f4791a5
-  data.tar.gz: dc8ac1a09294cdbfa440445f5a6558d5d33d20ead9aa5026c4c83fec487d46aa1cab339abd8c8a15ac51871615a6e4ddcec505b5ddf7ba0436bfdff3cfbb5491
+  metadata.gz: 3d98924c3ff4088566f7952d8b56c2ae8747fc99e6ba3f286dcce5e9dd788b3b5c80d1faf60c1a8ff3bb77dc4be136477b1f862cd00b4f1f55b100c9d6ae1289
+  data.tar.gz: aff5c151b261c9f35eb58a9a87407cb5c6ee67804ae2ec9585ad4b59043eb6132e443223ad650565dfda7a9fdfe8c528315b5946c5b2d4ea1281ecb8e65bb373

data/README.md

@@ -4,7 +4,7 @@
 
 For the best HTML e-mail delivery results, CSS should be inline. This is a
 huge pain and a simple newsletter becomes un-managable very quickly. This
-script is my solution.
+gem is a solution.
 
 * CSS styles are converted to inline style attributes
   - Checks `style` and `link[rel=stylesheet]` tags and preserves existing inline attributes
@@ -12,35 +12,26 @@ script is my solution.
   - Checks links in `href`, `src` and CSS `url('')`
 * CSS properties are checked against e-mail client capabilities
   - Based on the Email Standards Project's guides
-* A [plain text version](https://premailer.github.io/premailer/HtmlToPlainText.html) is created (optional)
+* A [plain text version](#plain-text-version) is created (optional)
 
 ## Installation
 
-Install the Premailer gem from RubyGems.
-
 ```bash
 gem install premailer
 ```
 
-or add it to your `Gemfile` and run `bundle`.
-
 ## Example
 
 ```ruby
 require 'premailer'
 
-premailer = Premailer.new('http://example.com/myfile.html', :warn_level => Premailer::Warnings::SAFE)
+premailer = Premailer.new('http://example.com/myfile.html', warn_level: Premailer::Warnings::SAFE)
 
-# Write the plain-text output
-# This must come before to_inline_css (https://github.com/premailer/premailer/issues/201)
-File.open("output.txt", "w") do |fout|
-  fout.puts premailer.to_plain_text
-end
+# Write the plain-text output (must come before to_inline_css)
+File.write "output.txt", premailer.to_plain_text
 
 # Write the HTML output
-File.open("output.html", "w") do |fout|
-  fout.puts premailer.to_inline_css
-end
+File.write "output.html", premailer.to_inline_css
 
 # Output any CSS warnings
 premailer.warnings.each do |w|
@@ -50,17 +41,13 @@ end
 
 ## Adapters
 
-Premailer's default adapter is nokogiri if both nokogiri and nokogumbo are included in the Gemfile list. However, if you want to use a different adapter, you can choose to.
-
-There are three adapters in total (as of premailer 1.10.0)
-
 1. nokogiri (default)
-2. nokogiri_fast
+2. nokogiri_fast (20x speed, more memory)
 3. nokogumbo
 
-hpricot adapter removed due to its EOL, please use `~>1.9.0` version if You still need it..
+(hpricot adapter removed, use `~>1.9.0` version if you need it)
 
-`NokogiriFast` adapter improves the Algorithmic complexity of the running time by 20x with a slight compensation on memory. To switch to any of these adapters, add the following line. For example, if you want to include the `NokogiriFast` adapter,
+Picking an adapter:
 
 ```ruby
 Premailer::Adapter.use = :nokogiri_fast
@@ -97,22 +84,125 @@ will result in
 <table cellspacing='5' width='500'>
 ```
 
-## Configuration options
+## Plain text version
+
+Premailer can generate a plain text version of your HTML. Links and images will be inlined.
+
+For example
+
+```html
+<a href="https://example.com" >
+  <img src="https://github.com/premailer.png" alt="Premailer Logo" />
+</a>
+```
+
+will become
+
+```text
+Premailer Logo ( https://example.com )
+```
+
+To ignore/omit a section of HTML content from the plain text version, wrap it with the following comments.
 
-The behavior of Premailer can be configured by passing options in the initializer.
+```html
+<!-- start text/html -->
+<p>This will be omitted from the plain text version.</p>
+<p>
+  This is extremely helpful for <strong>removing email headers and footers</strong>
+  that aren't needed in the text version.
+</p>
+<!-- end text/html -->
+```
 
-For example, the following will accept HTML from a string and will exclude unmergeable css from being added to the `<head>` of the output document.
+## Configuration options
 
+For example:
 ```ruby
-premailer = Premailer.new(html_string, with_html_string: true, drop_unmergeable_css_rules: true)
+Premailer.new(
+  html, # html as string
+  with_html_string: true,
+  drop_unmergeable_css_rules: true
+)
+```
+
+[available options](https://premailer.github.io/premailer/Premailer.html#initialize-instance_method)
+
+## Support for CSS variables
+
+The gem does not automatically replace CSS variables with their static values.
+
+For example, if a variable is used to set the `font-weight` of an `h1` element, the result will be
+```html
+<h1 style="
+  font-size:3rem;
+  font-weight:var(--bulma-content-heading-weight);">
+  Title</h1>
+```
+
+This causes the `font-weight` value to be the CSS variable call `var(--bulma-content-heading-weight);` instead of its static value.
+
+### Replace CSS variable calls with their static values
+
+The following section instructs how to replace CSS variables with their static value in the context of a Ruby on Rails application.
+
+Install the `postcss-css-variables` plugin for PostCSS to process the CSS variables.
+
+```shell
+yarn add postcss postcss-cli postcss-css-variables
+```
+
+To configure the plugin, create the file `postcss.config.js` in the root directory with the content:
+
+```javascript
+module.exports = {
+    plugins: [
+        // https://github.com/MadLittleMods/postcss-css-variables to transform the css
+      require("postcss-css-variables")({
+        preserve: false, // Set to false to replace variables with static values
+      }),
+    ],
+  };
+```
+
+In the `package.json` file, add the new "build:emails" to the scripts.<br>Replace `./app/assets/stylesheets/emails.css` with your file path:
+```json
+"scripts": {
+  "build:emails": "postcss ./app/assets/stylesheets/emails.css -o ./app/assets/builds/emails.css"
+}
 ```
 
-[See here for a full list of the available options](https://premailer.github.io/premailer/Premailer.html#initialize-instance_method).
+The previous script processes and overwrites the file at `./app/assets/stylesheets/emails.css` with PostCSS using its `postcss-css-variables` plugin, replacing the CSS variables with their static value.
 
+If the file to be processed is not `.css`, but `.scss`, it needs to be converted first to `.css`, then have its variables replaced. The script would then be
+
+```json
+"scripts": {
+  "build:emails": "sass ./app/assets/stylesheets/emails.scss:./app/assets/builds/emails.css --no-source-map --load-path=node_modules && postcss ./app/assets/builds/emails.css -o ./app/assets/builds/emails.css"
+}
+```
+
+Next, to execute the script when running `bin/dev`, add the following line in the file `Procfile.dev`
+
+```
+emails_css: yarn build:emails --watch
+```
+
+The srcipt can also be executed separately with the command
+
+```shell
+yarn build:emails
+```
+
+### Caveat
+
+The variables must be declared before use. Otherwise, their values when called will be set to `undefined`.
 
 ## Contributions
 
-Contributions are most welcome.  Premailer was rotting away in a private SVN repository for too long and could use some TLC.  Fork and patch to your heart's content.  Please don't increment the version numbers, though.
+Contributions are most welcome.
+Premailer was rotting away in a private SVN repository for too long and could use some TLC.
+Fork and patch to your heart's content.
+Please don't increment the version numbers.
 
 A few areas that are particularly in need of love:
 
@@ -129,4 +219,3 @@ and to [Campaign Monitor](https://www.campaignmonitor.com/) for supporting the w
 The source code can be found on [GitHub](https://github.com/premailer/premailer).
 
 Copyright by Alex Dunae (dunae.ca, e-mail 'code' at the same domain), 2007-2017.  See [LICENSE.md](https://github.com/premailer/premailer/blob/master/LICENSE.md) for license details.
-

data/bin/premailer

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 # This binary used in rubygems environment only as part of installed gem
 
 require 'premailer/executor'
-

data/lib/premailer/adapter/nokogiri.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
 require 'nokogiri'
 
 class Premailer
   module Adapter
     # Nokogiri adapter
     module Nokogiri
+      WIDTH_AND_HIGHT = ['width', 'height'].freeze
 
       include AdapterHelper::RgbToHex
       # Merge CSS into the HTML document.
@@ -13,42 +15,67 @@ class Premailer
         doc = @processed_doc
         @unmergable_rules = CssParser::Parser.new
 
+        # Accumulate matched rule sets per node in memory instead of
+        # round-tripping them through style attributes as [SPEC=n[...]]
+        # string markers (which costs two libxml2 attribute round-trips per
+        # element plus a regex re-scan, and dominates allocation churn).
+        rules_by_node = {}
+
         # Give all styles already in style attributes a specificity of 1000
         # per http://www.w3.org/TR/CSS21/cascade.html#specificity
+        # Identical style strings (repeated components) share one rule set so
+        # the fold cache below can hit on them.
+        rule_set_cache = {}
         doc.search("*[@style]").each do |el|
-          el['style'] = '[SPEC=1000[' + el.attributes['style'] + ']]'
+          style = el.attributes['style'].to_s
+          rs = rule_set_cache.fetch(style) { rule_set_cache[style] = build_rule_set(style, 1000) }
+          rules_by_node[el] = rs ? [rs] : []
         end
         # Iterate through the rules and merge them into the HTML
         @css_parser.each_selector(:all) do |selector, declaration, specificity, media_types|
           # Save un-mergable rules separately
-          selector.gsub!(/:link([\s]*)+/i) { |m| $1 }
+          selector.gsub!(/:link([\s]*)+/i) { |_m| $1 }
 
           # Convert element names to lower case
-          selector.gsub!(/([\s]|^)([\w]+)/) { |m| $1.to_s + $2.to_s.downcase }
+          selector.gsub!(/([\s]|^)([\w]+)/) { |_m| $1.to_s + $2.to_s.downcase }
 
-          if Premailer.is_media_query?(media_types) || selector =~ Premailer::RE_UNMERGABLE_SELECTORS
-            @unmergable_rules.add_rule_set!(CssParser::RuleSet.new(selector, declaration), media_types) unless @options[:preserve_styles]
+          if Premailer.media_query?(media_types) || selector =~ Premailer::RE_UNMERGABLE_SELECTORS
+            @unmergable_rules.add_rule_set!(CssParser::RuleSet.new(selectors: selector, block: declaration), media_types) unless @options[:preserve_styles]
           else
             begin
-              if selector =~ Premailer::RE_RESET_SELECTORS
+              if Premailer::RE_RESET_SELECTORS.match?(selector) && !!@options[:preserve_reset]
                 # this is in place to preserve the MailChimp CSS reset: http://github.com/mailchimp/Email-Blueprints/
                 # however, this doesn't mean for testing pur
-                @unmergable_rules.add_rule_set!(CssParser::RuleSet.new(selector, declaration)) unless !@options[:preserve_reset]
+                @unmergable_rules.add_rule_set!(CssParser::RuleSet.new(selectors: selector, block: declaration))
               end
 
               # Change single ID CSS selectors into xpath so that we can match more
               # than one element.  Added to work around dodgy generated code.
               selector.gsub!(/\A\#([\w_\-]+)\Z/, '*[@id=\1]')
 
+              rule_set = nil
+              rule_set_missing = false
               doc.search(selector).each do |el|
-                if el.elem? and (el.name != 'head' and el.parent.name != 'head')
-                  # Add a style attribute or append to the existing one
-                  block = "[SPEC=#{specificity}[#{declaration}]]"
-                  el['style'] = (el.attributes['style'].to_s ||= '') + ' ' + block
+                if el.elem? && ((el.name != 'head') && (el.parent.name != 'head'))
+                  # Enroll the element even when the rule below fails to build:
+                  # the marker implementation wrote the style attribute before
+                  # parsing, so matched elements end up with style="" when
+                  # their only rule is invalid and exceptions are disabled.
+                  rules = (rules_by_node[el] ||= [])
+                  next if rule_set_missing
+
+                  # One shared rule set per CSS rule; merge never mutates inputs
+                  # (CachedRuleSet#expand_shorthand! is idempotent by design).
+                  rule_set ||= build_rule_set(declaration, specificity)
+                  if rule_set.nil?
+                    rule_set_missing = true
+                    next
+                  end
+                  rules << rule_set
                 end
               end
             rescue ::Nokogiri::SyntaxError, RuntimeError, ArgumentError
-              $stderr.puts "CSS syntax error with selector: #{selector}" if @options[:verbose]
+              warn "CSS syntax error with selector: #{selector}" if @options[:verbose]
               next
             end
           end
@@ -57,65 +84,35 @@ class Premailer
         # Remove script tags
         doc.search("script").remove if @options[:remove_scripts]
 
-        # Read STYLE attributes and perform folding
-        doc.search("*[@style]").each do |el|
-          style = el.attributes['style'].to_s
-
-          declarations = []
-          style.scan(/\[SPEC\=([\d]+)\[(.[^\]\]]*)\]\]/).each do |declaration|
-            begin
-              rs = CssParser::RuleSet.new(nil, declaration[1].to_s, declaration[0].to_i)
-              declarations << rs
-            rescue ArgumentError => e
-              raise e if @options[:rule_set_exceptions]
-            end
-          end
-
-          # Perform style folding
-          merged = CssParser.merge(declarations)
-          merged.expand_shorthand!
-
-          # Duplicate CSS attributes as HTML attributes
-          if Premailer::RELATED_ATTRIBUTES.has_key?(el.name) && @options[:css_to_attributes]
-            Premailer::RELATED_ATTRIBUTES[el.name].each do |css_attr, html_attr|
-              if el[html_attr].nil? and not merged[css_attr].empty?
-                new_val = merged[css_attr].dup
-
-                # Remove url() function wrapper
-                new_val.gsub!(/url\((['"])(.*?)\1\)/, '\2')
-
-                # Remove !important, trailing semi-colon, and leading/trailing whitespace
-                new_val.gsub!(/;$|\s*!important/, '').strip!
-
-                # For width and height tags, remove px units
-                new_val.gsub!(/(\d+)px/, '\1') if %w[width height].include?(html_attr)
-
-                # For color-related tags, convert RGB to hex if specified by options
-                new_val = ensure_hex(new_val) if css_attr.end_with?('color') && @options[:rgb_to_hex_attributes]
-
-                el[html_attr] = new_val
-              end
-
-              unless @options[:preserve_style_attribute]
-                merged.instance_variable_get("@declarations").tap do |declarations|
-                  declarations.delete(css_attr)
-                end
-              end
-            end
+        # Perform style folding. Elements sharing the same matched rule sets
+        # (ubiquitous in table-based email markup) fold to the same result, so
+        # the merge/expand/collapse/serialize pipeline runs once per unique
+        # (element name, rule list) pair instead of once per element.
+        fold_cache = {}
+        rules_by_node.each do |el, declarations|
+          related = Premailer::RELATED_ATTRIBUTES.key?(el.name) && @options[:css_to_attributes]
+          # Rule sets are interned above, so default identity hashing makes
+          # them usable directly as cache key elements.
+          cache_key = [related ? el.name : nil, *declarations]
+
+          folded = fold_cache[cache_key] ||= fold_declarations(declarations, related ? el.name : nil)
+          style, attributes = folded
+
+          # Write the inline STYLE attribute first so the attribute order for
+          # elements that had no style attribute matches the marker-based
+          # implementation (style attr was created during selector matching).
+          el['style'] = style
+
+          attributes&.each do |html_attr, value|
+            el[html_attr] = value if el[html_attr].nil?
           end
-
-          # Collapse multiple rules into one as much as possible.
-          merged.create_shorthand! if @options[:create_shorthands]
-
-          # write the inline STYLE attribute
-          el['style'] = merged.declarations_to_s
         end
 
         doc = write_unmergable_css_rules(doc, @unmergable_rules) unless @options[:drop_unmergeable_css_rules]
 
-        if @options[:remove_classes] or @options[:remove_comments]
+        if @options[:remove_classes] || @options[:remove_comments]
           doc.traverse do |el|
-            if el.comment? and @options[:remove_comments]
+            if el.comment? && @options[:remove_comments]
               el.remove
             elsif el.element?
               el.remove_attribute('class') if @options[:remove_classes]
@@ -127,7 +124,7 @@ class Premailer
           # find all anchor's targets and hash them
           targets = []
           doc.search("a[@href^='#']").each do |el|
-            target = el.get_attribute('href')[1..-1]
+            target = el.get_attribute('href')[1..]
             targets << target
             el.set_attribute('href', "#" + Digest::SHA256.hexdigest(target))
           end
@@ -149,7 +146,7 @@ class Premailer
         end
 
         @processed_doc = doc
-        if is_xhtml?
+        if xhtml?
           # we don't want to encode carriage returns
           @processed_doc.to_xhtml(:encoding => @options[:output_encoding]).gsub(/&\#(xD|13);/i, "\r")
         else
@@ -157,6 +154,72 @@ class Premailer
         end
       end
 
+      # Merge a list of rule sets into a final style string plus the HTML
+      # attribute duplications (bgcolor/align/...) for RELATED_ATTRIBUTES
+      # elements. Element-independent: the per-element "attribute already
+      # set" guard stays with the caller.
+      def fold_declarations(declarations, related_el_name) # :nodoc:
+        merged = CssParser.merge(declarations)
+        if merged.equal?(declarations[0])
+          # CssParser.merge returns its input untouched when given a single
+          # rule set; copy it before the destructive fold pipeline below so
+          # rule sets shared across elements are not corrupted.
+          merged = CssParser::RuleSet.new(block: merged.declarations_to_s, specificity: merged.specificity)
+        end
+        begin
+          merged.expand_shorthand!
+        rescue ArgumentError => e
+          raise e if @options[:rule_set_exceptions]
+        end
+
+        attributes = nil
+        # Duplicate CSS attributes as HTML attributes
+        if related_el_name
+          Premailer::RELATED_ATTRIBUTES[related_el_name].each do |css_attr, html_attr|
+            unless merged[css_attr].empty?
+              new_val = merged[css_attr].dup
+
+              # Remove url() function wrapper
+              new_val.gsub!(/url\((['"])(.*?)\1\)/, '\2')
+
+              # Remove !important, trailing semi-colon, and leading/trailing whitespace
+              new_val.gsub!(/;$|\s*!important/, '').strip!
+
+              # For width and height tags, remove px units
+              new_val.gsub!(/(\d+)px/, '\1') if WIDTH_AND_HIGHT.include?(html_attr)
+
+              # For color-related tags, convert RGB to hex if specified by options
+              new_val = ensure_hex(new_val) if css_attr.end_with?('color') && @options[:rgb_to_hex_attributes]
+
+              (attributes ||= []) << [html_attr, new_val]
+            end
+
+            unless @options[:preserve_style_attribute]
+              merged.instance_variable_get(:@declarations).tap do |declarations|
+                declarations.delete(css_attr)
+              end
+            end
+          end
+        end
+
+        # Collapse multiple rules into one as much as possible.
+        merged.create_shorthand! if @options[:create_shorthands]
+
+        # write the inline STYLE attribute
+        [merged.declarations_to_s, attributes]
+      end
+
+      # Build an expanded rule set for folding. Returns nil (and optionally
+      # swallows the error, mirroring the old fold-time rescue) on bad CSS.
+      def build_rule_set(block, specificity) # :nodoc:
+        rs = Premailer::CachedRuleSet.new(block: block, specificity: specificity)
+        rs.expand_shorthand!
+        rs
+      rescue ArgumentError => e
+        raise e if @options[:rule_set_exceptions]
+        nil
+      end
+
       # Create a <tt>style</tt> element with un-mergable rules (e.g. <tt>:hover</tt>)
       # and write it into the <tt>head</tt>.
       #
@@ -171,17 +234,16 @@ class Premailer
             style_tag.content = styles
             doc.add_child(style_tag)
           else
-            style_tag = doc.create_element "style", "#{styles}"
+            style_tag = doc.create_element "style", styles.to_s
             head = doc.at_css('head')
-            head ||=  doc.root.first_element_child.add_previous_sibling(doc.create_element "head")  if doc.root && doc.root.first_element_child
-            head ||=  doc.add_child(doc.create_element "head")
+            head ||=  doc.root.first_element_child.add_previous_sibling(doc.create_element("head")) if doc.root&.first_element_child
+            head ||=  doc.add_child(doc.create_element("head"))
             head << style_tag
           end
         end
         doc
       end
 
-
       # Converts the HTML document to a format suitable for plain-text e-mail.
       #
       # If present, uses the <body> element as its base; otherwise uses the whole document.
@@ -191,17 +253,17 @@ class Premailer
         html_src = ''
         begin
           html_src = @doc.at("body").inner_html
-        rescue;
+        rescue StandardError
         end
 
-        html_src = @doc.to_html unless html_src and not html_src.empty?
+        html_src = @doc.to_html unless html_src && !html_src.empty?
         convert_to_text(html_src, @options[:line_length], @html_encoding)
       end
 
       # Gets the original HTML as a string.
       # @return [String] HTML.
       def to_s
-        if is_xhtml?
+        if xhtml?
           @doc.to_xhtml(:encoding => nil)
         else
           @doc.to_html(:encoding => nil)
@@ -215,13 +277,13 @@ class Premailer
         thing = nil
 
         # TODO: duplicate options
-        if @options[:with_html_string] or @options[:inline] or input.respond_to?(:read)
+        if @options[:with_html_string] || @options[:inline] || input.respond_to?(:read)
           thing = input
         elsif @is_local_file
           @base_dir = File.dirname(input)
           thing = File.open(input, 'r')
         else
-          thing = URI.open(input)
+          thing = URI.parse(input).open
         end
 
         if thing.respond_to?(:read)
@@ -232,7 +294,8 @@ class Premailer
         doc = nil
 
         # Handle HTML entities
-        if @options[:replace_html_entities] == true and thing.is_a?(String)
+        if (@options[:replace_html_entities] == true) && thing.is_a?(String)
+          thing = +thing
           HTML_ENTITIES.map do |entity, replacement|
             thing.gsub! entity, replacement
           end
@@ -241,21 +304,20 @@ class Premailer
         doc = if @options[:html_fragment]
           ::Nokogiri::HTML.fragment(thing, encoding)
         else
-          ::Nokogiri::HTML(thing, nil, encoding) { |c| c.recover }
+          ::Nokogiri::HTML(thing, nil, encoding, &:recover)
         end
 
         # Fix for removing any CDATA tags from both style and script tags inserted per
         # https://github.com/sparklemotion/nokogiri/issues/311 and
         # https://github.com/premailer/premailer/issues/199
-        %w(style script).each do |tag|
+        ['style', 'script'].each do |tag|
           doc.search(tag).children.each do |child|
-            child.swap(child.text()) if child.cdata?
+            child.swap(child.text) if child.cdata?
           end
         end
 
         doc
       end
-
     end
   end
 end