premailer 1.23.0 → 1.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea6e9ef14eeb9cdffd7e718f976d9e71e50fb1f154c947c9ee9b97399f1aceeb
-  data.tar.gz: 02d8f609acce2abb421f607e1937e35e4d36f12c609386bef808378f56e9753c
+  metadata.gz: fa4f38aaadca592e45c38537b54ad6e88bd15c0c43c07efed0beb25af8194766
+  data.tar.gz: cde54fad4ac9397bd09b88509aa2b5a22daaa1721172a7c98e0e78c94e8707ad
 SHA512:
-  metadata.gz: d1e580add5528f240e2170bb2aed29171227d35ce8acc31d5c8ceed7ea3f211072f8db8257f9665bef5838c606c9f77a56a792482c3d5f730025a6448374a4bb
-  data.tar.gz: 3afd5c1330b5b1ddff158e77260c0fc87876779e839f5f1beb641ea4c00d424db97c0b5410a566f08ac97a3615cd125c8d9198a77d5edf3ee5959abcc2058440
+  metadata.gz: bc0358601f237a6ec2cf74764dfb28e5d800cf1ca486d88ca44a7e4d3913ade8ff00b76b98017fa6f565f5812bd6f9c3e66be819708a2764a70fca051458f09f
+  data.tar.gz: 9ea81979f54bd5fd9d8edb2e390e5900d53b7462064bc1465999dba639218db5a479c74e93e6e179d6d6a51abbf066685a21b033d5003899ab037a021db385f7

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.
@@ -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,14 +43,14 @@ 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
@@ -61,8 +63,8 @@ class Premailer
         doc.search("*[@style]").each do |el|
           style = el.attributes['style'].to_s
 
-          declarations = style.scan(/\[SPEC\=([\d]+)\[(.[^\]\]]*)\]\]/).filter_map do |declaration|
-            rs = Premailer::CachedRuleSet.new(nil, declaration[1].to_s, declaration[0].to_i)
+          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
@@ -78,9 +80,9 @@ class Premailer
           end
 
           # Duplicate CSS attributes as HTML attributes
-          if Premailer::RELATED_ATTRIBUTES.has_key?(el.name) && @options[:css_to_attributes]
+          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? and not merged[css_attr].empty?
+              if el[html_attr].nil? && !merged[css_attr].empty?
                 new_val = merged[css_attr].dup
 
                 # Remove url() function wrapper
@@ -90,7 +92,7 @@ class Premailer
                 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)
+                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]
@@ -99,7 +101,7 @@ class Premailer
               end
 
               unless @options[:preserve_style_attribute]
-                merged.instance_variable_get("@declarations").tap do |declarations|
+                merged.instance_variable_get(:@declarations).tap do |declarations|
                   declarations.delete(css_attr)
                 end
               end
@@ -115,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]
@@ -129,7 +131,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
@@ -151,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
@@ -173,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.
@@ -193,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)
@@ -217,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 = URI.open(input)
+          thing = URI.parse(input).open
         end
 
         if thing.respond_to?(:read)
@@ -234,7 +235,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
@@ -243,21 +245,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