roadie 2.4.3 → 3.0.0

data/Rakefile

@@ -1,29 +1,12 @@
 # encoding: utf-8
 require 'bundler/setup'
-require 'appraisal'
 
 Bundler::GemHelper.install_tasks
 
-begin
-  require 'rspec'
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-
-require 'rspec/core/rake_task'
-
 desc "Run specs"
-RSpec::Core::RakeTask.new('spec') do |t|
-  t.pattern = 'spec/**/*_spec.rb'
-  t.rspec_opts = ["-c"]
+task :spec do
+  sh "bundle exec rspec -f progress"
 end
 
 desc "Default: Run specs"
 task :default => :spec
-
-namespace :spec do
-  desc 'Run specs against all supported versions of Rails'
-  task :all => ["appraisal:install", "appraisal", "spec"]
-end

data/lib/roadie.rb

@@ -1,79 +1,26 @@
 module Roadie
-  class << self
-    # Shortcut for inlining CSS using {Inliner}
-    # @see Inliner
-    def inline_css(*args)
-      Roadie::Inliner.new(*args).execute
-    end
-
-    # Shortcut to Rails.application
-    def app
-      Rails.application
-    end
-
-    # Returns all available providers
-    def providers
-      [AssetPipelineProvider, FilesystemProvider]
-    end
-
-    # Returns the value of +config.roadie.enabled+.
-    #
-    # Roadie will disable all processing if this config is set to +false+. If
-    # you just want to disable CSS inlining without disabling the rest of
-    # Roadie, pass +css: nil+ to the +defaults+ method inside your mailers.
-    def enabled?
-      config.roadie.enabled
-    end
-
-    # Returns the active provider
-    #
-    # If no provider has been configured a new provider will be instantiated
-    # depending on if the asset pipeline is enabled or not.
-    #
-    # If +config.assets.enabled+ is +true+, the {AssetPipelineProvider} will be used
-    # while {FilesystemProvider} will be used if it is set to +false+.
-    #
-    # @see AssetPipelineProvider
-    # @see FilesystemProvider
-    def current_provider
-      return config.roadie.provider if config.roadie.provider
-
-      if assets_enabled?
-        AssetPipelineProvider.new
-      else
-        FilesystemProvider.new
-      end
-    end
-
-    # Returns the value of +config.roadie.after_inlining+
-    #
-    def after_inlining_handler
-      config.roadie.after_inlining
-    end
-
-    private
-      def config
-        Roadie.app.config
-      end
-
-      def assets_enabled?
-        # In Rails 4.0, config.assets.enabled is nil by default, so we need to
-        # explicitly make sure it's not false rather than checking for a
-        # truthy value.
-        config.respond_to?(:assets) and config.assets and config.assets.enabled != false
-      end
-  end
 end
 
 require 'roadie/version'
-require 'roadie/css_file_not_found'
+require 'roadie/errors'
+
+require 'roadie/stylesheet'
 require 'roadie/selector'
-require 'roadie/style_declaration'
+require 'roadie/style_property'
+require 'roadie/style_attribute_builder'
+require 'roadie/style_block'
 
 require 'roadie/asset_provider'
-require 'roadie/asset_pipeline_provider'
+require 'roadie/provider_list'
 require 'roadie/filesystem_provider'
+require 'roadie/null_provider'
 
+require 'roadie/asset_scanner'
+require 'roadie/markup_improver'
+require 'roadie/url_generator'
+require 'roadie/url_rewriter'
+require 'roadie/null_url_rewriter'
 require 'roadie/inliner'
+require 'roadie/document'
 
-require 'roadie/railtie' if defined?(Rails)
+require 'roadie/upgrade_guide'

data/lib/roadie/asset_provider.rb

@@ -1,62 +1,11 @@
 module Roadie
-  # @abstract Subclass to create your own providers
-  class AssetProvider
-    # The prefix is whatever is prepended to your stylesheets when referenced inside markup.
-    #
-    # The prefix is stripped away from any URLs before they are looked up in {#find}:
-    #   find("/assets/posts/comment.css")
-    #   # Same as: (if prefix == "/assets"
-    #   find("posts/comment.css")
-    attr_reader :prefix
-
-    # @param [String] prefix Prefix of assets as seen from the browser
-    # @see #prefix
-    def initialize(prefix = "/assets")
-      @prefix = prefix
-      @quoted_prefix = prepare_prefix(prefix)
+  # This module can be included in your own code to help you implement the
+  # standard behavior for asset providers.
+  #
+  # It helps you by declaring {#find_stylesheet!} in the terms of #find_stylesheet in your own class.
+  module AssetProvider
+    def find_stylesheet!(name)
+      find_stylesheet(name) or raise CssNotFound, name
     end
-
-    # Iterates all the passed elements and calls {#find} on them, joining the results with a newline.
-    #
-    # @example
-    #   MyProvider.all("first", "second.css", :third)
-    #
-    # @param [Array] files The target files to be loaded together
-    # @raise [CSSFileNotFound] In case any of the elements is not found
-    # @see #find
-    def all(files)
-      files.map { |file| find(file) }.join("\n")
-    end
-
-    # @abstract Implement in your own subclass
-    #
-    # Return the CSS contents of the file specified. A provider should not care about
-    # the +.css+ extension; it can, however, behave differently if it's passed or not.
-    #
-    # If the asset cannot be found, the method should raise {CSSFileNotFound}.
-    #
-    # @example
-    #   MyProvider.find("mystyle")
-    #   MyProvider.find("mystyle.css")
-    #   MyProvider.find(:mystyle)
-    #
-    # @param [String] name Name of the file requested
-    # @raise [CSSFileNotFound] In case any of the elements is not found
-    def find(name)
-      raise "Not implemented"
-    end
-
-    private
-      def prepare_prefix(prefix)
-        if prefix =~ /^\//
-          "/?#{Regexp.quote(prefix[1, prefix.size])}"
-        else
-          Regexp.quote(prefix)
-        end
-      end
-
-      def remove_prefix(name)
-        name.sub(/^#{@quoted_prefix}\/?/, '').sub(%r{^/}, '').gsub(%r{//+}, '/')
-      end
   end
 end

data/lib/roadie/asset_scanner.rb

@@ -0,0 +1,92 @@
+module Roadie
+  # @api private
+  #
+  # The asset scanner's main usage is finding and/or extracting styles from a
+  # DOM tree. Referenced styles will be found using the provided asset
+  # provider.
+  #
+  # Any style declaration tagged with +data-roadie-ignore+ will be ignored.
+  class AssetScanner
+    attr_reader :dom, :asset_provider
+
+    # @param [Nokogiri::HTML::Document] dom
+    # @param [#find_stylesheet!] asset_provider
+    def initialize(dom, asset_provider)
+      @dom = dom
+      @asset_provider = asset_provider
+    end
+
+    # Looks for all non-ignored stylesheets and returns them.
+    #
+    # This method will *not* mutate the DOM and is safe to call multiple times.
+    #
+    # The order of the array corresponds with the document order in the DOM.
+    #
+    # @see #extract_css
+    # @return [Enumerable<Stylesheet>] every found stylesheet
+    def find_css
+      @dom.css(STYLE_ELEMENT_QUERY).map { |element| read_stylesheet(element) }.compact
+    end
+
+    # Looks for all non-ignored stylesheets, removes their references from the
+    # DOM and then returns them.
+    #
+    # This will mutate the DOM tree.
+    #
+    # The order of the array corresponds with the document order in the DOM.
+    #
+    # @see #find_css
+    # @return [Enumerable<Stylesheet>] every extracted stylesheet
+    def extract_css
+      @dom.css(STYLE_ELEMENT_QUERY).map { |element|
+        stylesheet = read_stylesheet(element)
+        element.remove if stylesheet
+        stylesheet
+      }.compact
+    end
+
+    private
+
+    STYLE_ELEMENT_QUERY = (
+      "style:not([data-roadie-ignore]), " +
+      # TODO: When using Nokogiri 1.6.1 and later; we may use a double :not here
+      #       instead of the extra code inside #read_stylesheet, and the #compact
+      #       call in #find_css.
+      "link[rel=stylesheet][href]:not([data-roadie-ignore])"
+    ).freeze
+
+    # Cleans out stupid CDATA and/or HTML comments from the style text
+    # TinyMCE causes this, allegedly
+    CLEANING_MATCHER = /
+      (^\s*             # Beginning-of-lines matches
+        (<!\[CDATA\[)|
+        (<!--+)
+      )|(               # End-of-line matches
+        (--+>)|
+        (\]\]>)
+      $)
+    /x.freeze
+
+    def read_stylesheet(element)
+      if element.name == "style"
+        read_style_element element
+      else
+        read_link_element element
+      end
+    end
+
+    def read_style_element(element)
+      Stylesheet.new "(inline)", clean_css(element.text.strip)
+    end
+
+    def read_link_element(element)
+      if element['media'] != "print" && element["href"]
+        asset_provider.find_stylesheet! element['href']
+      end
+    end
+
+    def clean_css(css)
+      css.gsub(CLEANING_MATCHER, '')
+    end
+  end
+end

data/lib/roadie/document.rb

@@ -0,0 +1,103 @@
+module Roadie
+  # The main entry point for Roadie. A document represents a working unit and
+  # is built with the input HTML and the configuration options you need.
+  #
+  # A Document must never be used from two threads at the same time. Reusing
+  # Documents is discouraged.
+  #
+  # Stylesheets are added to the HTML from three different sources:
+  # 1. Stylesheets inside the document ( +<style>+ elements)
+  # 2. Stylesheets referenced by the DOM ( +<link>+ elements)
+  # 3. The internal stylesheet (see {#add_css})
+  #
+  # The internal stylesheet is used last and gets the highest priority. The
+  # rest is used in the same order as browsers are supposed to use them.
+  #
+  # @attr [#call] before_transformation Callback to call just before {#transform}ation is begun. Will be called with the parsed DOM tree.
+  # @attr [#call] after_transformation Callback to call just before {#transform}ation is completed. Will be called with the current DOM tree.
+  class Document
+    attr_reader :html, :asset_providers
+
+    # URL options. If none are given no URL rewriting will take place.
+    # @see UrlGenerator#initialize
+    attr_accessor :url_options
+
+    attr_accessor :before_transformation, :after_transformation
+
+    # @param [String] html the input HTML
+    def initialize(html)
+      @html = html
+      @asset_providers = ProviderList.wrap(FilesystemProvider.new)
+      @css = ""
+    end
+
+    # Append additional CSS to the document's internal stylesheet.
+    # @param [String] new_css
+    def add_css(new_css)
+      @css << "\n\n" << new_css
+    end
+
+    # Transform the input HTML and returns the processed HTML.
+    #
+    # Before the transformation begins, the {#before_transformation} callback will be
+    # called with the parsed HTML tree, and after all work is complete the
+    # {#after_transformation} callback will be invoked.
+    #
+    # Most of the work is delegated to other classes. A list of them can be seen below.
+    #
+    # @see MarkupImprover MarkupImprover (improves the markup of the DOM)
+    # @see Inliner Inliner (inlines the stylesheets)
+    # @see UrlRewriter UrlRewriter (rewrites URLs and makes them absolute)
+    #
+    # @return [String] the transformed HTML
+    def transform
+      dom = Nokogiri::HTML.parse html
+
+      callback before_transformation, dom
+
+      improve dom
+      inline dom
+      rewrite_urls dom
+
+      callback after_transformation, dom
+
+      # #dup is called since it fixed a few segfaults in certain versions of Nokogiri
+      dom.dup.to_html
+    end
+
+    # Assign new asset providers. The supplied list will be wrapped in a {ProviderList} using {ProviderList.wrap}.
+    def asset_providers=(list)
+      @asset_providers = ProviderList.wrap(list)
+    end
+
+    private
+    def stylesheet
+      Stylesheet.new "(Document styles)", @css
+    end
+
+    def improve(dom)
+      MarkupImprover.new(dom, html).improve
+    end
+
+    def inline(dom)
+      dom_stylesheets = AssetScanner.new(dom, asset_providers).extract_css
+      Inliner.new(dom_stylesheets + [stylesheet]).inline(dom)
+    end
+
+    def rewrite_urls(dom)
+      make_url_rewriter.transform_dom(dom)
+    end
+
+    def make_url_rewriter
+      if url_options
+        UrlRewriter.new(UrlGenerator.new(url_options))
+      else
+        NullUrlRewriter.new
+      end
+    end
+
+    def callback(callable, dom)
+      callable.(dom) if callable.respond_to?(:call)
+    end
+  end
+end

data/lib/roadie/errors.rb

@@ -0,0 +1,57 @@
+module Roadie
+  # Base class for all Roadie errors. Rescue this if you want to catch errors
+  # from Roadie.
+  #
+  # If Roadie raises an error that does not inherit this class, please report
+  # it as a bug.
+  class Error < RuntimeError; end
+
+  # Raised when a declaration which cannot be parsed is encountered.
+  #
+  # A declaration is something like "font-size: 12pt;".
+  class UnparseableDeclaration < Error; end
+
+  # Raised when Roadie encounters an invalid URL which cannot be parsed by
+  # Ruby's +URI+ class.
+  #
+  # This could be a hint that something in your HTML or CSS is broken.
+  class InvalidUrlPath < Error
+    # The original error, raised from +URI+.
+    attr_reader :cause
+
+    def initialize(given_path, cause = nil)
+      @cause = cause
+      if cause
+        cause_message = " Caused by: #{cause}"
+      else
+        cause_message = ""
+      end
+      super "Cannot use path \"#{given_path}\" in URL generation.#{cause_message}"
+    end
+  end
+
+  # Raised when an asset provider cannot find a stylesheet.
+  #
+  # If you are writing your own asset provider, make sure to raise this in the
+  # +#find_stylesheet!+ method.
+  #
+  # @see AssetProvider
+  class CssNotFound < Error
+    # The name of the stylesheet that cannot be found
+    attr_reader :css_name
+
+    def initialize(css_name, extra_message = nil)
+      @css_name = css_name
+      super build_message(extra_message)
+    end
+
+    private
+    def build_message(extra_message)
+      if extra_message
+        %(Could not find stylesheet "#{css_name}": #{extra_message})
+      else
+        %(Could not find stylesheet "#{css_name}")
+      end
+    end
+  end
+end