premailer 1.12.0 → 1.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d3e8552d269ddef67b722b192f58c2afe242f6a824a07e4e7fd4e5bbc3f57f2
-  data.tar.gz: 6c6b611237ffe68b655654c75c21c7a8f17bc73ca9502e06891f26ab5b1bb583
+  metadata.gz: fa4f38aaadca592e45c38537b54ad6e88bd15c0c43c07efed0beb25af8194766
+  data.tar.gz: cde54fad4ac9397bd09b88509aa2b5a22daaa1721172a7c98e0e78c94e8707ad
 SHA512:
-  metadata.gz: 1c963172a6abcb9e71824c07e54a80ea89c58fda395349d68ea0567a5fa06cf160663bd1e8a169a81532f5ad3b7c97d8ed0ad2c09a4182c3d281982a878348da
-  data.tar.gz: 758dae24fbd064a1ee44fe4ab6f0537c191826474dc045a8af5354f28a17e4d20e8a56e93d2ea3ebab83ab4c9c9b2376aa0b53467ff50338773e78e815b8ccbe
+  metadata.gz: bc0358601f237a6ec2cf74764dfb28e5d800cf1ca486d88ca44a7e4d3913ade8ff00b76b98017fa6f565f5812bd6f9c3e66be819708a2764a70fca051458f09f
+  data.tar.gz: 9ea81979f54bd5fd9d8edb2e390e5900d53b7462064bc1465999dba639218db5a479c74e93e6e179d6d6a51abbf066685a21b033d5003899ab037a021db385f7

data/README.md

@@ -1,10 +1,10 @@
-# Premailer README [![Build Status](https://travis-ci.org/premailer/premailer.png?branch=master)](https://travis-ci.org/premailer/premailer) [![Gem Version](https://badge.fury.io/rb/premailer.svg)](https://badge.fury.io/rb/premailer)
+# Premailer README [![CI](https://github.com/premailer/premailer/actions/workflows/actions.yml/badge.svg)](https://github.com/premailer/premailer/actions/workflows/actions.yml) [![Gem Version](https://badge.fury.io/rb/premailer.svg)](https://badge.fury.io/rb/premailer)
 
 ## What is this?
 
 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
@@ -68,7 +55,7 @@ Premailer::Adapter.use = :nokogiri_fast
 
 ## Ruby Compatibility
 
-Premailer is tested on Ruby 2.1 and above. JRuby support is close; contributors are welcome.  Checkout the latest build status on the [Travis CI dashboard](https://travis-ci.org/#!/premailer/premailer).
+See .github/workflows/actions.yml for which ruby versions are tested. JRuby support is close, contributors are welcome.
 
 ## Premailer-specific CSS
 
@@ -97,9 +84,125 @@ will result in
 <table cellspacing='5' width='500'>
 ```
 
+## 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.
+
+```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 -->
+```
+
+## Configuration options
+
+For example:
+```ruby
+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"
+}
+```
+
+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:
 
@@ -116,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.
@@ -21,19 +23,19 @@ class Premailer
         # 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
@@ -41,52 +43,71 @@ class Premailer
               selector.gsub!(/\A\#([\w_\-]+)\Z/, '*[@id=\1]')
 
               doc.search(selector).each do |el|
-                if el.elem? and (el.name != 'head' and el.parent.name != 'head')
+                if el.elem? && ((el.name != 'head') && (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
                 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
         end
 
         # Remove script tags
-        if @options[:remove_scripts]
-          doc.search("script").remove
-        end
+        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|
-            rs = CssParser::RuleSet.new(nil, declaration[1].to_s, declaration[0].to_i)
-            declarations << rs
+          declarations = style.scan(/\[SPEC=([\d]+)\[(.[^\]]*)\]\]/m).filter_map do |declaration|
+            rs = Premailer::CachedRuleSet.new(block: declaration[1].to_s, specificity: declaration[0].to_i)
+            rs.expand_shorthand!
+            rs
+          rescue ArgumentError => e
+            raise e if @options[:rule_set_exceptions]
           end
 
           # Perform style folding
           merged = CssParser.merge(declarations)
-          merged.expand_shorthand!
+          begin
+            merged.expand_shorthand!
+          rescue ArgumentError => e
+            raise e if @options[:rule_set_exceptions]
+          end
 
           # 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_att, html_att|
-              if el[html_att].nil? and not merged[css_att].empty?
-                new_html_att = merged[css_att].gsub(/url\(['"](.*)['"]\)/, '\1').gsub(/;$|\s*!important/, '').strip
-                el[html_att] = css_att.end_with?('color') && @options[:rgb_to_hex_attributes] ? ensure_hex(new_html_att) : new_html_att
+          if Premailer::RELATED_ATTRIBUTES.key?(el.name) && @options[:css_to_attributes]
+            Premailer::RELATED_ATTRIBUTES[el.name].each do |css_attr, html_attr|
+              if el[html_attr].nil? && !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]
+
+                el[html_attr] = new_val
               end
+
               unless @options[:preserve_style_attribute]
-                merged.instance_variable_get("@declarations").tap do |declarations|
-                    declarations.delete(css_att)
+                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]
 
@@ -96,9 +117,9 @@ class Premailer
 
         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]
@@ -110,15 +131,15 @@ 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::MD5.hexdigest(target))
+            el.set_attribute('href', "#" + Digest::SHA256.hexdigest(target))
           end
           # hash ids that are links target, delete others
           doc.search("*[@id]").each do |el|
             id = el.get_attribute('id')
             if targets.include?(id)
-              el.set_attribute('id', Digest::MD5.hexdigest(id))
+              el.set_attribute('id', Digest::SHA256.hexdigest(id))
             else
               el.remove_attribute('id')
             end
@@ -132,7 +153,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
@@ -154,17 +175,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.
@@ -174,17 +194,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)
@@ -198,13 +218,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 = open(input)
+          thing = URI.parse(input).open
         end
 
         if thing.respond_to?(:read)
@@ -215,37 +235,30 @@ 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
         end
-        # Default encoding is ASCII-8BIT (binary) per http://groups.google.com/group/nokogiri-talk/msg/0b81ef0dc180dc74
-        # However, we really don't want to hardcode this. ASCII-8BIT should be the default, but not the only option.
-        encoding = if thing.is_a?(String) and RUBY_VERSION =~ /1.9/
-          thing = thing.force_encoding(@options[:input_encoding]).encode!
-          @options[:input_encoding]
-        else
-          @options[:input_encoding] || (RUBY_PLATFORM == 'java' ? nil : 'BINARY')
-        end
+        encoding = @options[:input_encoding] || (RUBY_PLATFORM == 'java' ? nil : 'BINARY')
         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