darkroom 0.0.6 → 0.0.7

data/lib/darkroom/darkroom.rb

@@ -12,32 +12,41 @@ require_relative('errors/processing_error')
 # Main class providing fast, lightweight, and straightforward web asset management.
 #
 class Darkroom
-  DEFAULT_INTERNAL_PATTERN = nil
-  DEFAULT_MINIFIED_PATTERN = /(\.|-)min\.\w+$/.freeze
+  DEFAULT_MINIFIED = /(\.|-)min\.\w+$/.freeze
+  TRAILING_SLASHES = /\/+$/.freeze
   PRISTINE = Set.new(%w[/favicon.ico /mask-icon.svg /humans.txt /robots.txt]).freeze
   MIN_PROCESS_INTERVAL = 0.5
 
-  DISALLOWED_PATH_CHARS = '\'"`=<>? '
-  INVALID_PATH = /[#{DISALLOWED_PATH_CHARS}]/.freeze
-  TRAILING_SLASHES = /\/+$/.freeze
-
   @@delegates = {}
   @@glob = ''
 
   attr_reader(:error, :errors, :process_key)
 
+  class << self; attr_accessor(:javascript_iife) end
+
   ##
   # Registers an asset delegate.
   #
-  # * +delegate+ - An HTTP MIME type string, a Hash of Delegate parameters, or a Delegate instance.
-  # * +extensions+ - File extension(s) to associate with this delegate.
+  # [*extensions] One or more file extension(s) to associate with this delegate.
+  # [delegate] An HTTP MIME type string or a Delegate subclass.
   #
-  def self.register(*extensions, delegate)
-    case delegate
-    when String
-      delegate = Asset::Delegate.new(content_type: delegate.freeze)
-    when Hash
-      delegate = Asset::Delegate.new(**delegate)
+  def self.register(*extensions, delegate, &block)
+    if delegate.kind_of?(String)
+      content_type = delegate
+
+      if delegate[0] == '.'
+        extensions << delegate
+        content_type = nil
+      end
+
+      delegate = Class.new(Delegate, &block)
+      delegate.content_type(content_type) if content_type && !delegate.content_type
+    elsif delegate.kind_of?(Hash)
+      deprecated("#{self.name}.register with a Hash is deprecated: use the Delegate DSL inside a block "\
+        'instead')
+      delegate = Delegate.deprecated_from_hash(**delegate)
+    elsif delegate && delegate < Delegate
+      delegate = block ? Class.new(delegate, &block) : delegate
     end
 
     extensions.each do |extension|
@@ -52,38 +61,63 @@ class Darkroom
   ##
   # Returns the delegate associated with a file extension.
   #
-  # * +extension+ - File extension of the desired delegate.
+  # [extension] File extension of the desired delegate.
   #
   def self.delegate(extension)
     @@delegates[extension]
   end
 
+  ##
+  # Utility method that prints a warning with file and line number of a deprecated call.
+  #
+  def self.deprecated(message)
+    location = caller_locations(2, 1).first
+
+    warn("#{location.path}:#{location.lineno}: #{message}")
+  end
+
   ##
   # Creates a new instance.
   #
-  # * +load_paths+ - Path(s) where assets are located on disk.
-  # * +host+ - Host(s) to prepend to paths (useful when serving from a CDN in production). If multiple hosts
-  #   are specified, they will be round-robined within each thread for each call to +#asset_path+.
-  # * +hosts+ - Alias of +host+ parameter.
-  # * +prefix+ - Prefix to prepend to asset paths (e.g. +/assets+).
-  # * +pristine+ - Path(s) that should not include prefix and for which unversioned form should be provided
-  #   by default (e.g. +/favicon.ico+).
-  # * +minify+ - Boolean specifying whether or not to minify assets.
-  # * +minified_pattern+ - Regex used against asset paths to determine if they are already minified and
-  #   should therefore be skipped over for minification.
-  # * +internal_pattern+ - Regex used against asset paths to determine if they should be marked as internal
-  #   and therefore made inaccessible externally.
-  # * +min_process_interval+ - Minimum time required between one run of asset processing and another.
+  # [*load_paths] One or more paths where assets are located on disk.
+  # [host:] Host(s) to prepend to paths (useful when serving from a CDN in production). If multiple hosts
+  #         are specified, they will be round-robined within each thread for each call to +#asset_path+.
+  # [hosts:] Alias of +host:+.
+  # [prefix:] Prefix to prepend to asset paths (e.g. +/assets+).
+  # [pristine:] Path(s) that should not include prefix and for which unversioned form should be provided by
+  #             default (e.g. +/favicon.ico+).
+  # [entries:] String, regex, or array of strings and regexes specifying entry point paths / path patterns.
+  # [minify:] Boolean specifying whether or not to minify assets.
+  # [minified:] String, regex, or array of strings and regexes specifying paths of assets that are already
+  #             minified and thus should be skipped for minification.
+  # [minified_pattern:] DEPRECATED: use +minified:+ instead. Regex used against asset paths to determine if
+  #                     they are already minified and should therefore be skipped over for minification.
+  # [internal_pattern:] DEPRECATED: use +entries:+ instead. Regex used against asset paths to determine if
+  #                     they should be marked as internal and therefore made inaccessible externally.
+  # [min_process_interval:] Minimum time required between one run of asset processing and another.
   #
-  def initialize(*load_paths, host: nil, hosts: nil, prefix: nil, pristine: nil, minify: false,
-      minified_pattern: DEFAULT_MINIFIED_PATTERN, internal_pattern: DEFAULT_INTERNAL_PATTERN,
+  def initialize(*load_paths, host: nil, hosts: nil, prefix: nil, pristine: nil, entries: nil,
+      minify: false, minified: DEFAULT_MINIFIED, minified_pattern: nil, internal_pattern: nil,
       min_process_interval: MIN_PROCESS_INTERVAL)
     @load_paths = load_paths.map { |load_path| File.expand_path(load_path) }
 
     @hosts = (Array(host) + Array(hosts)).map! { |host| host.sub(TRAILING_SLASHES, '') }
+    @entries = Array(entries)
     @minify = minify
+    @minified = Array(minified)
     @internal_pattern = internal_pattern
-    @minified_pattern = minified_pattern
+
+    if minified_pattern
+      self.class.deprecated("#{self.class.name} :minified_pattern is deprecated: use :minified instead "\
+        'and pass a string, regex, or array of strings and regexes')
+      @minified = [minified_pattern]
+    end
+
+    if @internal_pattern
+      self.class.deprecated("#{self.class.name} :internal_pattern is deprecated: use :entries to instead "\
+        'specify which assets are entry points (i.e. available externally) and pass a string, regex, or '\
+        'array of strings and regexes')
+    end
 
     @prefix = prefix&.sub(TRAILING_SLASHES, '')
     @prefix = nil if @prefix && @prefix.empty?
@@ -106,14 +140,15 @@ class Darkroom
 
   ##
   # Walks all load paths and refreshes any assets that have been modified on disk since the last call to
-  # this method.
+  # this method. Returns false if processing was skipped due to previous call happening less than
+  # min_process_interval ago or because another thread was already processing; returns true otherwise.
   #
   def process
-    return if Time.now.to_f - @last_processed_at < @min_process_interval
+    return false if Time.now.to_f - @last_processed_at < @min_process_interval
 
     if @mutex.locked?
       @mutex.synchronize {}
-      return
+      return false
     end
 
     @mutex.synchronize do
@@ -125,18 +160,22 @@ class Darkroom
         Dir.glob(File.join(load_path, @@glob)).sort.each do |file|
           path = file.sub(load_path, '')
 
-          if index = (path =~ INVALID_PATH)
+          if index = (path =~ Asset::INVALID_PATH_REGEX)
             @errors << InvalidPathError.new(path, index)
           elsif found.key?(path)
             @errors << DuplicateAssetError.new(path, found[path], load_path)
           else
             found[path] = load_path
 
-            @manifest[path] ||= Asset.new(path, file, self,
-              prefix: (@prefix unless @pristine.include?(path)),
-              internal: @internal_pattern && path =~ @internal_pattern,
-              minify: @minify && path !~ @minified_pattern,
-            )
+            unless @manifest.key?(path)
+              entry = entry?(path)
+
+              @manifest[path] = Asset.new(path, file, self,
+                prefix: (@prefix unless @pristine.include?(path)),
+                entry: entry,
+                minify: entry && @minify && !minified?(path),
+              )
+            end
           end
         end
       end
@@ -148,13 +187,15 @@ class Darkroom
       @manifest.each do |path, asset|
         asset.process
 
-        unless asset.internal?
+        if asset.entry?
           @manifest_unversioned[asset.path_unversioned] = asset
           @manifest_versioned[asset.path_versioned] = asset
         end
 
-        @errors += asset.errors
+        @errors.concat(asset.errors)
       end
+
+      true
     ensure
       @last_processed_at = Time.now.to_f
       @error = @errors.empty? ? nil : ProcessingError.new(@errors)
@@ -162,12 +203,13 @@ class Darkroom
   end
 
   ##
-  # Does the same thing as #process, but raises an exception if any errors were encountered.
+  # Calls #process. If processing was skipped, returns false. If processing was performed, raises an
+  # exception if any errors were encountered and returns true otherwise.
   #
   def process!
-    process
+    result = process
 
-    raise(@error) if @error
+    (result && @error) ? raise(@error) : result
   end
 
   ##
@@ -186,7 +228,7 @@ class Darkroom
   #   darkroom.asset('/assets/js/app.<hash>.js')
   #   darkroom.asset('/assets/js/app.js')
   #
-  # * +path+ - External path of the asset.
+  # [path] External path of the asset.
   #
   def asset(path)
     @manifest_versioned[path] || @manifest_unversioned[path]
@@ -203,8 +245,8 @@ class Darkroom
   #
   # Raises an AssetNotFoundError if the asset doesn't exist.
   #
-  # * +path+ - Internal path of the asset.
-  # * +versioned+ - Boolean indicating whether the versioned or unversioned path should be returned.
+  # [path] Internal path of the asset.
+  # [versioned:] Boolean indicating whether the versioned or unversioned path should be returned.
   #
   def asset_path(path, versioned: !@pristine.include?(path))
     asset = @manifest[path] or raise(AssetNotFoundError.new(path))
@@ -219,8 +261,8 @@ class Darkroom
   # Returns an asset's subresource integrity string. Raises an AssetNotFoundError if the asset doesn't
   # exist.
   #
-  # * +path+ - Internal path of the asset.
-  # * +algorithm+ - Hash algorithm to use to generate the integrity string (see Asset#integrity).
+  # [path] Internal path of the asset.
+  # [algorithm] Hash algorithm to use to generate the integrity string (see Asset#integrity).
   #
   def asset_integrity(path, algorithm = nil)
     asset = @manifest[path] or raise(AssetNotFoundError.new(path))
@@ -231,7 +273,7 @@ class Darkroom
   ##
   # Returns the asset from the manifest hash associated with the given path.
   #
-  # * +path+ - Internal path of the asset.
+  # [path] Internal path of the asset.
   #
   def manifest(path)
     @manifest[path]
@@ -241,14 +283,16 @@ class Darkroom
   # Writes assets to disk. This is useful when deploying to a production environment where assets will be
   # uploaded to and served from a CDN or proxy server.
   #
-  # * +dir+ - Directory to write the assets to.
-  # * +clear+ - Boolean indicating whether or not the existing contents of the directory should be deleted
-  #   before performing the dump.
-  # * +include_pristine+ - Boolean indicating whether or not to include pristine assets (when dumping for
-  #   the purpose of uploading to a CDN, assets such as /robots.txt and /favicon.ico don't need to be
-  #   included).
+  # [dir] Directory to write the assets to.
+  # [clear:] Boolean indicating whether or not the existing contents of the directory should be deleted
+  #          before performing the dump.
+  # [include_pristine:] Boolean indicating whether or not to include pristine assets (when dumping for the
+  #                     purpose of uploading to a CDN, assets such as /robots.txt and /favicon.ico don't
+  #                     need to be included).
   #
   def dump(dir, clear: false, include_pristine: true)
+    raise(@error) if @error
+
     require('fileutils')
 
     dir = File.expand_path(dir)
@@ -257,7 +301,6 @@ class Darkroom
     Dir.each_child(dir) { |child| FileUtils.rm_rf(File.join(dir, child)) } if clear
 
     @manifest_versioned.each do |path, asset|
-      next if asset.internal?
       next if @pristine.include?(asset.path) && !include_pristine
 
       file_path = File.join(dir,
@@ -274,17 +317,50 @@ class Darkroom
   #
   def inspect
     "#<#{self.class}: "\
+      "@entries=#{@entries.inspect}, "\
       "@errors=#{@errors.inspect}, "\
       "@hosts=#{@hosts.inspect}, "\
       "@internal_pattern=#{@internal_pattern.inspect}, "\
       "@last_processed_at=#{@last_processed_at.inspect}, "\
       "@load_paths=#{@load_paths.inspect}, "\
       "@min_process_interval=#{@min_process_interval.inspect}, "\
-      "@minified_pattern=#{@minified_pattern.inspect}, "\
+      "@minified=#{@minified.inspect}, "\
       "@minify=#{@minify.inspect}, "\
       "@prefix=#{@prefix.inspect}, "\
       "@pristine=#{@pristine.inspect}, "\
       "@process_key=#{@process_key.inspect}"\
     '>'
   end
+
+  private
+
+  ##
+  # Returns boolean indicating whether or not the provided path is an entry point.
+  #
+  # [path] Path to check.
+  #
+  def entry?(path)
+    if @pristine.include?(path)
+      true
+    elsif @internal_pattern && @entries.empty?
+      !path.match?(@internal_pattern)
+    elsif @entries.empty?
+      true
+    else
+      @entries.any? do |entry|
+        path == entry || (entry.kind_of?(Regexp) && path.match?(entry))
+      end
+    end
+  end
+
+  ##
+  # Returns boolean indicating whether or not the asset with the provided path is already minified.
+  #
+  # [path] Path to check.
+  #
+  def minified?(path)
+    @minified.any? do |minified|
+      path == minified || (minified.kind_of?(Regexp) && path.match?(minified))
+    end
+  end
 end

data/lib/darkroom/delegate.rb

@@ -0,0 +1,237 @@
+class Darkroom
+  ##
+  # Holds asset type-specific information and functionality.
+  #
+  # [minify_lib:] Name of a library to +require+ that is needed by the +minify+ lambda (optional).
+  # [minify:] Lambda to call that will return the minified version of the asset's content (optional). One
+  #           argument is passed when called:
+  #           * +content+ - Content to minify.
+  #
+  class Delegate
+    [
+      :content_type, :parsers, :compile_lib, :compile_delegate, :compile_handler, :finalize_lib,
+      :finalize_handler, :minify_lib, :minify_handler
+    ].each do |name|
+      var = :"@#{name}"
+      instance_variable_set(var, nil)
+
+      define_singleton_method(name) do
+        instance_variable_defined?(var) ? instance_variable_get(var) : superclass.send(name)
+      end
+    end
+
+    class << self; alias :get_content_type :content_type end
+
+    ##
+    # Sets or returns HTTP MIME type string.
+    #
+    def self.content_type(content_type = (get = true; nil))
+      get ? get_content_type : (@content_type = content_type)
+    end
+
+    ##
+    # Configures how imports are handled.
+    #
+    # [regex] Regex for finding import statements. Must contain a named component called +path+ (e.g.
+    #         <tt>/^import (?<path>.*)/</tt>).
+    # [&handler] Block for special handling of import statements (optional). Should
+    #            <tt>throw(:error, '...')</tt> on error. Passed three arguments:
+    #            * +parse_data:+ - Hash for storing data across calls to this and other parsing handlers.
+    #            * +match:+ - MatchData object from the match against +regex+.
+    #            * +asset:+ - Asset object of the asset being imported.
+    #            Return value is used as the substitution for the import statement, with optional second and
+    #            third values as integers representing the start and end indexes of the match to replace.
+    #
+    def self.import(regex, &handler)
+      parse(:import, regex, &handler)
+    end
+
+    ##
+    # Configures how references are handled.
+    #
+    # [regex] Regex for finding references. Must contain three named components:
+    #         * +path+ - Path of the asset being referenced.
+    #         * +entity+ - Desired entity ('path' or 'content').
+    #         * +format+ - Format to use (see Asset::REFERENCE_FORMATS).
+    # [&handler] Block for special handling of references (optional). Should <tt>throw(:error, '...')</tt>
+    #            on error. Passed four arguments:
+    #            * +parse_data:+ - Hash for storing data across calls to this and other parsing handlers.
+    #            * +match:+ - MatchData object from the match against +regex+.
+    #            * +asset:+ - Asset object of the asset being imported.
+    #            * +format:+ - Format of the reference (see Asset::REFERENCE_FORMATS).
+    #            Return value is used as the substitution for the reference, with optional second and third
+    #            values as integers representing the start and end indexes of the match to replace.
+    #
+    def self.reference(regex, &handler)
+      parse(:reference, regex, &handler)
+    end
+
+    ##
+    # Configures a parser.
+    #
+    # [kind] A name to describe what is being parsed. Should be unique across all +parse+ calls. When
+    #        subclassing another Delegate, can be used to override the parent class's regex and handler.
+    # [regex] Regex to match against.
+    # [&handler] Block for handling matches of the regex. Should <tt>throw(:error, '...')</tt>
+    #            on error. Passed two arguments:
+    #            * +parse_data:+ - Hash for storing data across calls to this and other parsing handlers.
+    #            * +match:+ - MatchData object from the match against +regex+.
+    #            Return value is used as the substitution for the reference, with optional second and third
+    #            values as integers representing the start and end indexes of the match to replace.
+    #
+    def self.parse(kind, regex, &handler)
+      @parsers = parsers&.dup || {} unless @parsers
+      @parsers[kind] = [regex, handler]
+    end
+
+    ##
+    # Configures compilation.
+    #
+    # [lib:] Name of a library to +require+ that is needed by the handler (optional).
+    # [delegate:] Another Delegate to be used after the asset is compiled (optional).
+    # [&handler] Block to call that will return the compiled version of the asset's own content. Passed
+    #            three arguments when called:
+    #.           * +parse_data:+ - Hash of data collected during parsing.
+    #            * +path+ - Path of the asset being compiled.
+    #            * +own_content+ - Asset's own content.
+    #            Asset's own content is set to the value returned.
+    #
+    def self.compile(lib: nil, delegate: nil, &handler)
+      @compile_lib = lib
+      @compile_delegate = delegate
+      @compile_handler = handler
+    end
+
+    ##
+    # Configures finalize behavior.
+    #
+    # [lib:] Name of a library to +require+ that is needed by the handler (optional).
+    # [&handler] Block to call that will return the completed version of the asset's overall content. Passed
+    #            three arguments when called:
+    #.           * +parse_data:+ - Hash of data collected during parsing.
+    #            * +path+ - Path of the asset being finalized.
+    #            * +content+ - Asset's content (with imports prepended).
+    #            Asset's content is set to the value returned.
+    #
+    def self.finalize(lib: nil, &handler)
+      @finalize_lib = lib
+      @finalize_handler = handler
+    end
+
+    ##
+    # Configures minification.
+    #
+    # [lib:] Name of a library to +require+ that is needed by the handler (optional).
+    # [&handler] Block to call that will return the minified version of the asset's overall content. Passed
+    #            three arguments when called:
+    #.           * +parse_data:+ - Hash of data collected during parsing.
+    #            * +path+ - Path of the asset being finalized.
+    #            * +content+ - Finalized asset's content.
+    #            Asset's minified content is set to the value returned.
+    #
+    def self.minify(lib: nil, &handler)
+      @minify_lib = lib
+      @minify_handler = handler
+    end
+
+    ##
+    # Throws +:error+ with a message.
+    #
+    # [message] Message to include with the throw.
+    #
+    def self.error(message)
+      throw(:error, message)
+    end
+
+    ##
+    # Returns regex for a parser.
+    #
+    # [kind] Name of the parser.
+    #
+    def self.regex(kind)
+      parsers[kind]&.first
+    end
+
+    ##
+    # Returns handler for a parser.
+    #
+    # [kind] Name of the parser.
+    #
+    def self.handler(kind)
+      parsers[kind]&.last
+    end
+
+    ##
+    # Iterates over each parser and yields its kind, regex, and handler.
+    #
+    def self.each_parser
+      parsers&.each do |kind, (regex, handler)|
+        yield(kind, regex, handler)
+      end
+    end
+
+    ##
+    # DEPRECATED: subclass Delegate and use its DSL instead. Returns a subclass of Delegate configured using
+    # the supplied Hash.
+    #
+    def self.new(**params)
+      Darkroom.deprecated("#{self.name}::new is deprecated: use the DSL inside a child class or a block "\
+        'passed to Darkroom.register')
+
+      deprecated_from_hash(**params)
+    end
+
+    ##
+    # DEPRECATED: subclass Delegate and use its DSL instead. Returns a subclass of Delegate configured using
+    # the supplied Hash.
+    #
+    def self.deprecated_from_hash(content_type:, import_regex: nil, reference_regex: nil,
+        validate_reference: nil, reference_content: nil, compile_lib: nil, compile: nil, compiled: nil,
+        minify_lib: nil, minify: nil)
+      Class.new(Delegate) do
+        self.content_type(content_type)
+
+        @import_regex = import_regex
+        @reference_regex = reference_regex
+
+        self.import(import_regex) if import_regex
+
+        if validate_reference || reference_content
+          @validate_reference = validate_reference
+          @reference_content = reference_content
+
+          self.reference(reference_regex) do |parse_data:, match:, asset:, format:|
+            error_message = validate_reference&.call(asset, match, format)
+            error(error_message) if error_message
+
+            reference_content&.call(asset, match, format)
+          end
+        elsif reference_regex
+          self.reference(reference_regex)
+        end
+
+        if compile
+          self.compile(lib: compile_lib, delegate: compiled) do |parse_data:, path:, own_content:|
+            compile.call(path, own_content)
+          end
+        elsif compile_lib || compiled
+          self.compile(lib: compile_lib, delegate: compiled)
+        end
+
+        if minify
+          self.minify(lib: minify_lib) do |parse_data:, path:, content:|
+            minify.call(content)
+          end
+        end
+      end
+    end
+
+    ##
+    # DEPRECATED: subclass Delegate and use its DSL instead.
+    #
+    def self.import_regex() @import_regex end
+    def self.reference_regex() @reference_regex end
+    def self.validate_reference() @validate_reference end
+    def self.reference_content() @reference_content end
+  end
+end

data/lib/darkroom/delegates/css.rb

@@ -1,39 +1,41 @@
 # frozen_string_literal: true
 
 require_relative('../asset')
+require_relative('../delegate')
 
 class Darkroom
-  class Asset
-    ##
-    # Delegate for CSS assets.
-    #
-    CSSDelegate = Delegate.new(
-      content_type: 'text/css',
-      import_regex: /^ *@import +#{QUOTED_PATH.source} *; *(\n|$)/.freeze,
-      reference_regex: /url\(\s*#{REFERENCE_PATH.source}\s*\)/x.freeze,
-
-      validate_reference: ->(asset, match, format) do
-        if format == 'displace'
-          'Cannot displace in CSS files'
-        elsif !asset.image? && !asset.font?
-          'Referenced asset must be an image or font type'
-        end
-      end,
-
-      reference_content: ->(asset, match, format) do
-        if format == 'utf8'
-          content = asset.content.gsub('#', '%23')
-          content.gsub!(/(['"])/, '\\\\\1')
-          content.gsub!("\n", "\\\n")
-
-          content
-        end
-      end,
-
-      minify_lib: 'sassc',
-      minify: ->(content) do
-        SassC::Engine.new(content, style: :compressed).render
-      end,
-    )
+  class CSSDelegate < Delegate
+    IMPORT_REGEX = /
+      (?<=^|;)[^\S\n]*
+      @import\s+#{Asset::QUOTED_PATH_REGEX.source}
+      [^\S\n]*;[^\S\n]*(\n|\Z)
+    /x.freeze
+
+    REFERENCE_REGEX = /url\(\s*#{Asset::REFERENCE_REGEX.source}\s*\)/x.freeze
+
+    content_type('text/css')
+
+    import(IMPORT_REGEX)
+
+    reference(REFERENCE_REGEX) do |parse_data:, match:, asset:, format:|
+      if format == 'displace'
+        error('Cannot displace in CSS files')
+      elsif !asset.image? && !asset.font?
+        error('Referenced asset must be an image or font type')
+      elsif format == 'utf8'
+        content = asset.content.dup
+
+        content.gsub!('#', '%23')
+        content.gsub!('\'', '\\\\\'')
+        content.gsub!('"', '\\"')
+        content.gsub!("\n", "\\\n")
+
+        content
+      end
+    end
+
+    minify(lib: 'sassc') do |parse_data:, path:, content:|
+      SassC::Engine.new(content, style: :compressed).render
+    end
   end
 end