darkroom 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a77051a57dc9a5b32fe1ea1e96c831884183729058f1336139e15142d55a43f
-  data.tar.gz: 11ee7f486da94bf7c5dadf9af8e14fd9c1ab41a9620cc72c604885d9474d9150
+  metadata.gz: 5c415007207739d2b2309bad3372784ac664278c9e4eb02e7b3568f4b41ac5ce
+  data.tar.gz: 9faf193286ae14cca9e406cf1f4c9639ef7f5eddf0cd919bd3d5b2f9a87175ef
 SHA512:
-  metadata.gz: c4a4bb0e7cb9845154951aa703197be875b7777bba1f824d0bbba6ccfed609cebc9460a3c32db60ca846e819a0ac4b4a9c4024ba2b882a498108ef83230757d8
-  data.tar.gz: 83a14e41099925ae3ea44c23a18a044c1db1b1ca8fc10c15dabecf725270c32ec559165ef6e596852f5c7b22f2354ab92a0cdfadd654c1c8d22a6d9d2f5ae9f1
+  metadata.gz: e0210152f97f5e96acb9f6da9e5999681cf9b7deeb1e8aaa81e4f609e2d97d04d17216d8ee7950ec4343247632dfa87785e8e9477891ad705d5518142e5ac054
+  data.tar.gz: b25709a4b7aab61a1710402a655043792f14f742793744cea3549cc43aa39ab47740456f9bfcad7f65c4fb859faa9366a0e75eec77bb5e563686ba3fe27f407c

data/README.md

@@ -9,19 +9,20 @@ each language's native import statement syntax.
 The following file types are supported out of the box, though support for others can be added (see the
 [Extending](#extending) section):
 
-| Name       | Content Type           | Exension(s) |
-| ---------- |----------------------- |-------------|
-| CSS        | text/css               | .css        |
-| JavaScript | application/javascript | .js         |
-| HTML       | text/html              | .htm, .html |
-| HTX        | application/javascript | .htx        |
-| ICO        | image/x-icon           | .ico        |
-| JPEG       | image/jpeg             | .jpg, .jpeg |
-| PNG        | image/png              | .png        |
-| SVG        | image/svg+xml          | .svg        |
-| Text       | text/plain             | .txt        |
-| WOFF       | font/woff              | .woff       |
-| WOFF2      | font/woff2             | .woff2      |
+| Name       | Content Type     | Extension(s) |
+|------------|------------------|--------------|
+| CSS        | text/css         | .css         |
+| HTML       | text/html        | .htm, .html  |
+| HTX        | text/javascript  | .htx         |
+| ICO        | image/x-icon     | .ico         |
+| JavaScript | text/javascript  | .js          |
+| JPEG       | image/jpeg       | .jpg, .jpeg  |
+| JSON       | application/json | .json        |
+| PNG        | image/png        | .png         |
+| SVG        | image/svg+xml    | .svg         |
+| Text       | text/plain       | .txt         |
+| WOFF       | font/woff        | .woff        |
+| WOFF2      | font/woff2       | .woff2       |
 
 ## Installation
 
@@ -37,6 +38,17 @@ Or install manually on the command line:
 gem install darkroom
 ```
 
+Darkroom depends on a few other gems for compilation and minification of certain asset types, but does not
+explicitly include them as dependencies since need for them varies from project to project. As such, if your
+project includes HTX templates or you wish to minify CSS and/or JavaScript assets, the following will need
+to be added to your Gemfile:
+
+```ruby
+gem('htx')      # HTX compilation
+gem('sassc')    # CSS minification
+gem('uglifier') # JavaScript and HTX minification
+```
+
 ## Usage
 
 To create and start using a Darkroom instance, specify one or more load paths (all other arguments are
@@ -44,50 +56,70 @@ optional):
 
 ```ruby
 darkroom = Darkroom.new('app/assets', 'vendor/assets', '...',
-  hosts: ['https://cdn1.com', '...']   # Hosts to prepend to asset paths (useful in production)
+  hosts: [                             # Hosts to prepend to asset paths (useful in production
+    'https://cname1.cdn.com',          # when assets are served from a CDN with multiple
+    'https://cname2.cdn.com',          # cnames); hosts are chosen round-robin per thread
+    '...',
+  ],
   prefix: '/static',                   # Prefix to add to all asset paths
-  pristine: ['/google-verify.html'],   # Paths with no prefix or versioning (e.g. /favicon.ico)
+  pristine: ['/google-verify.html'],   # Paths with no prefix or versioning (/favicon.ico,
+                                       # /mask-icon.svg, /humans.txt, and /robots.txt are
+                                       # included automatically)
   minify: true,                        # Minify assets that can be minified
-  minified_pattern: /(\.|-)min\.\w+$/, # Files that should not be minified
-  internal_pattern: /^\/components\//, # Files that cannot be accessed directly
+  minified_pattern: /(\.|-)min\.\w+$/, # Files to skip minification on when minify: true
+  internal_pattern: /^\/components\//, # Files to disallow direct external access to (they can
+                                       # still be imported into other assets)
   min_process_interval: 1,             # Minimum time that must elapse between process calls
 )
+```
 
-# Refresh any assets that have been modified (in development, this should be called at the
-# beginning of each web request).
+Note that assets paths across all load path directories must be globally unique (e.g. the existence of both
+`app/assets/app.js` and `vendor/assets/app.js` will result in an error).
+
+Darkroom will never update assets without explicitly being told to do so. The following call should be made
+once when the app is started and additionally at the beginning of each web request in development to refresh
+any modified assets:
+
+```ruby
 darkroom.process
+```
+
+Alternatively, assets can be dumped to disk when deploying to a production environment where assets will be
+uploaded to and served from a CDN or proxy server:
 
-# Dump assets to disk. Useful when deploying to a production environment where assets will be
-# uploaded to and served from a CDN or proxy server.
+```ruby
 darkroom.dump('output/dir',
   clear: true,            # Delete contents of output/dir before dumping
   include_pristine: true, # Include pristine assets (if preparing for CDN upload, files like
 )                         # /favicon.ico or /robots.txt should be left out)
 ```
 
-Note that assets paths across all load path directories must be globally unique (e.g. the existence of both
-`app/assets/app.js` and `vendor/assets/app.js` will result in an error).
-
 To work with assets:
 
 ```ruby
-# Get the external path that will be used by HTTP requests.
-path = darkroom.asset_path('/js/app.js') # => '/static/js/app-<fingerprint>.js'
+# A Darkroom instance has a few convenience helper methods.
+path = darkroom.asset_path('/js/app.js')           # => '/static/js/app-[fingerprint].js'
+integrity = darkroom.asset_integrity('/js/app.js') # => 'sha384-[hash]'
 
 # Retrieve the Asset object associated with a path.
 asset = darkroom.asset(path)
 
-# Getting paths directly from an Asset object will not include any host or prefix.
-assest.path           # => '/js/app.js'
-assest.path_versioned # => '/js/app-<fingerprint>.js'
+# Prefix (if set on the Darkroom instance) is included in the unversioned and versioned paths.
+assest.path                     # => '/js/app.js'
+assest.path_unversioned         # => '/static/js/app.js'
+assest.path_versioned           # => '/static/js/app-[fingerprint].js'
 
-asset.content_type # => 'application/javascript'
-asset.content      # Content of processed /js/app.js file
+asset.content_type              # => 'text/javascript'
+asset.content                   # Content of processed /js/app.js file
 
-asset.headers                   # => {'Content-Type' => 'application/javascript',
+asset.headers                   # => {'Content-Type' => 'text/javascript',
                                 #     'Cache-Control' => 'public, max-age=31536000'}
-asset.headers(versioned: false) # => {'Content-Type' => 'application/javascript',
-                                #     'ETag' => '<fingerprint>'}
+asset.headers(versioned: false) # => {'Content-Type' => 'text/javascript',
+                                #     'ETag' => '[fingerprint]'}
+
+asset.integrity                 # => 'sha384-[hash]'
+asset.integrity(:sha256)        # => 'sha256-[hash]'
+asset.integrity(:sha512)        # => 'sha512-[hash]'
 ```
 
 ## Asset Bundling
@@ -146,19 +178,73 @@ Imports can even be cyclical. If `asset-a.css` imports `asset-b.css` and vice-ve
 contain the content of both of those assets (though order will be different as an asset's own content always
 comes after any imported assets' contents).
 
+## Asset References
+
+Asset paths and content can be inserted into an asset by referencing an asset's path and including a query
+parameter.
+
+| String                           | Result                            |
+|----------------------------------|-----------------------------------|
+| /logo.svg?asset-path             | /prefix/logo-[fingerprint].svg    |
+| /logo.svg?asset-path=versioned   | /prefix/logo-[fingerprint].svg    |
+| /logo.svg?asset-path=unversioned | /prefix/logo.svg                  |
+| /logo.svg?asset-content          | data:image/svg+xml;base64,[data]  |
+| /logo.svg?asset-content=base64   | data:image/svg+xml;base64,[data]  |
+| /logo.svg?asset-content=utf8     | data:image/svg+xml;utf8,\<svg>... |
+
+Where these get recognized is specific to each asset type.
+
+* **CSS** - Within `url(...)`, which may be unquoted or quoted with single or double quotes.
+* **HTML** - Values of `href` and `src` attributes on `a`, `area`, `audio`, `base`, `embed`, `iframe`,
+  `img`, `input`, `link`, `script`, `source`, `track`, and `video` tags.
+* **HTX** - Same behavior as HTML.
+
+HTML assets additionally support the `?asset-content=displace` query parameter for use with `<link>`,
+`<script>`, and `<img>` tags with CSS, JavaScript, and SVG asset references, respectively. The entire tag is
+replaced appropriately.
+
+```html
+<!-- Source -->
+<head>
+  <title>My App</title>
+  <link href='/app.css?asset-content=displace' type='text/css'>
+  <script src='/app.js?asset-content=displace'></script>
+</head>
+
+<body>
+  <img src='/logo.svg?asset-content-displace'>
+</body>
+
+<!-- Result -->
+<head>
+  <title>My App</title>
+  <style>/* Content of /app.css */</style>
+  <script>/* Content of /app.js */</script>
+</head>
+
+<body>
+  <svg><!-- ... --></svg>
+</body>
+```
+
 ## Extending
 
 Darkroom is extensible. Support for arbitrary file types can be added as follows (all named parameters are
 optional):
 
 ```ruby
-Darkroom::Asset.add_spec('.extension1', 'extension2', '...', 'content/type',
-  dependency_regex: /import (?<path>.*)/, # Regex for identifying dependencies for bundling;
-                                          # must include `path` named capture group
-  compile_lib: 'some-compile-lib',        # Name of library required for compilation
-  compile: -> (path, content) { '...' },  # Proc that returns compiled content
-  minify_lib: 'some-minify-lib',          # Name of library required for minification
-  minify: -> (content) { '...' },         # Proc that returns minified content
+# Simple type with no special behavior.
+Darkroom.register('.extension1', 'extension2', '...', 'content/type')
+
+# Complex type with special behavior.
+Darkroom::Asset.register('.extension1', 'extension2', '...',
+  content_type: 'content/type',         # HTTP MIME type string
+  import_regex: /import (?<path>.*)/,   # Regex for identifying imports for bundling
+  reference_regex: /ref=(?<path>.*)/,   # Regex for identifying references to other assets
+  compile_lib: 'some-compile-lib',      # Name of library required for compilation
+  compile: ->(path, content) { '...' }, # Lambda that returns compiled content
+  minify_lib: 'some-minify-lib',        # Name of library required for minification
+  minify: ->(content) { '...' },        # Lambda that returns minified content
 )
 
 ```

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.4

data/lib/darkroom.rb

@@ -4,36 +4,29 @@ require('darkroom/asset')
 require('darkroom/darkroom')
 require('darkroom/version')
 
+require('darkroom/delegates/css')
+require('darkroom/delegates/html')
+require('darkroom/delegates/htx')
+require('darkroom/delegates/javascript')
+
+require('darkroom/errors/asset_error')
 require('darkroom/errors/asset_not_found_error')
+require('darkroom/errors/circular_reference_error')
 require('darkroom/errors/duplicate_asset_error')
+require('darkroom/errors/invalid_path_error')
 require('darkroom/errors/missing_library_error')
 require('darkroom/errors/processing_error')
-require('darkroom/errors/spec_not_defined_error')
-
-Darkroom::Asset.add_spec('.css', 'text/css',
-  dependency_regex: /^ *@import +#{Darkroom::Asset::IMPORT_PATH_REGEX} *; *$/,
-  minify: -> (content) { SassC::Engine.new(content, style: :compressed).render },
-  minify_lib: 'sassc',
-)
-
-Darkroom::Asset.add_spec('.js', 'application/javascript',
-  dependency_regex: /^ *import +#{Darkroom::Asset::IMPORT_PATH_REGEX} *;? *$/,
-  minify: -> (content) { Uglifier.compile(content, harmony: true) },
-  minify_lib: 'uglifier',
-)
-
-Darkroom::Asset.add_spec('.htx', 'application/javascript',
-  compile: -> (path, content) { HTX.compile(path, content) },
-  compile_lib: 'htx',
-  minify: Darkroom::Asset.spec('.js').minify,
-  minify_lib: Darkroom::Asset.spec('.js').minify_lib,
-)
+require('darkroom/errors/unrecognized_extension_error')
 
-Darkroom::Asset.add_spec('.htm', '.html', 'text/html')
-Darkroom::Asset.add_spec('.ico', 'image/x-icon')
-Darkroom::Asset.add_spec('.jpg', '.jpeg', 'image/jpeg')
-Darkroom::Asset.add_spec('.png', 'image/png')
-Darkroom::Asset.add_spec('.svg', 'image/svg+xml')
-Darkroom::Asset.add_spec('.txt', 'text/plain')
-Darkroom::Asset.add_spec('.woff', 'font/woff')
-Darkroom::Asset.add_spec('.woff2', 'font/woff2')
+Darkroom.register('.css', Darkroom::Asset::CSSDelegate)
+Darkroom.register('.htm', '.html', Darkroom::Asset::HTMLDelegate)
+Darkroom.register('.htx', Darkroom::Asset::HTXDelegate)
+Darkroom.register('.ico', 'image/x-icon')
+Darkroom.register('.jpg', '.jpeg', 'image/jpeg')
+Darkroom.register('.js', Darkroom::Asset::JavaScriptDelegate)
+Darkroom.register('.json', 'application/json')
+Darkroom.register('.png', 'image/png')
+Darkroom.register('.svg', 'image/svg+xml')
+Darkroom.register('.txt', 'text/plain')
+Darkroom.register('.woff', 'font/woff')
+Darkroom.register('.woff2', 'font/woff2')

data/lib/darkroom/asset.rb

@@ -2,23 +2,34 @@
 
 require('base64')
 require('digest')
+require('set')
+
+require_relative('darkroom')
 
 class Darkroom
   ##
   # Represents an asset.
   #
   class Asset
-    DEPENDENCY_JOINER = "\n"
     EXTENSION_REGEX = /(?=\.\w+)/.freeze
 
-    OPEN_QUOTE = '(?<quote>[\'"])'
-    BODY = '((?!\k<quote>).|(?<!\\\\)\\\\(\\\\\\\\)*\k<quote>)*'
-    BODY_END = '(?<!\\\\)(\\\\\\\\)*'
-    CLOSE_QUOTE = '\k<quote>'
+    IMPORT_JOINER = "\n"
+    DEFAULT_QUOTE = '\''
 
-    IMPORT_PATH_REGEX = /#{OPEN_QUOTE}(?<path>#{BODY}#{BODY_END})#{CLOSE_QUOTE}/.freeze
+    QUOTED_PATH = /(?<quote>['"])(?<path>[^'"]*)\k<quote>/.freeze
+    REFERENCE_PATH =
+      %r{
+        (?<quote>['"]?)(?<quoted>
+          (?<path>[^#{DISALLOWED_PATH_CHARS}]+)
+          \?asset-(?<entity>path|content)(=(?<format>\w*))?
+        )\k<quote>
+      }x.freeze
 
-    @@specs = {}
+    # First item of each set is used as default, so order is important.
+    REFERENCE_FORMATS = {
+      'path' => Set.new(%w[versioned unversioned]),
+      'content' => Set.new(%w[base64 utf8 displace]),
+    }.freeze
 
     attr_reader(:content, :error, :errors, :path, :path_unversioned, :path_versioned)
 
@@ -26,16 +37,38 @@ class Darkroom
     # Holds information about how to handle a particular asset type.
     #
     # * +content_type+ - HTTP MIME type string.
-    # * +dependency_regex+ - Regex to match lines of the file against to find dependencies. Must contain a
-    #   named component called 'path' (e.g. +/^import (?<path>.*)/+).
-    # * +compile+ - Proc to call that will produce the compiled version of the asset's content.
-    # * +compile_lib+ - Name of a library to +require+ that is needed by the +compile+ proc.
-    # * +minify+ - Proc to call that will produce the minified version of the asset's content.
-    # * +minify_lib+ - Name of a library to +require+ that is needed by the +minify+ proc.
+    # * +import_regex+ - Regex to find import statements. Must contain a named component called 'path'
+    #   (e.g. +/^import (?<path>.*)/+).
+    # * +reference_regex+ - Regex to find references to other assets. Must contain three named components:
+    #   * +path+ - Path of the asset being referenced.
+    #   * +entity+ - Desired entity (path or content).
+    #   * +format+ - Format to use (see REFERENCE_FORMATS).
+    # * +validate_reference+ - Lambda to call to validate a reference. Should return nil if there are no
+    #   errors and a string error message if validation fails. Three arguments are passed when called:
+    #   * +asset+ - Asset object of the asset being referenced.
+    #   * +match+ - MatchData object from the match against +reference_regex+.
+    #   * +format+ - Format of the reference (see REFERENCE_FORMATS).
+    # * +reference_content+ - Lambda to call to get the content for a reference. Should return nil if the
+    #   default behavior is desired or a string for custom content. Three arguments are passed when called:
+    #   * +asset+ - Asset object of the asset being referenced.
+    #   * +match+ - MatchData object from the match against +reference_regex+.
+    #   * +format+ - Format of the reference (see REFERENCE_FORMATS).
+    # * +compile_lib+ - Name of a library to +require+ that is needed by the +compile+ lambda.
+    # * +compile+ - Lambda to call that will return the compiled version of the asset's content. Two
+    #   arguments are passed when called:
+    #   * +path+ - Path of the asset being compiled.
+    #   * +content+ - Content to compile.
+    # * +minify_lib+ - Name of a library to +require+ that is needed by the +minify+ lambda.
+    # * +minify+ - Lambda to call that will return the minified version of the asset's content. One argument
+    #   is passed when called:
+    #   * +content+ - Content to minify.
     #
-    Spec = Struct.new(:content_type, :dependency_regex, :compile, :compile_lib, :minify, :minify_lib)
+    Delegate = Struct.new(:content_type, :import_regex, :reference_regex, :validate_reference,
+      :reference_content, :compile_lib, :compile, :minify_lib, :minify, keyword_init: true)
 
     ##
+    # DEPRECATED. Use Darkroom.register instead.
+    #
     # Defines an asset spec.
     #
     # * +extensions+ - File extensions to associate with this spec.
@@ -43,48 +76,38 @@ class Darkroom
     # * +other+ - Optional components of the spec (see Spec struct).
     #
     def self.add_spec(*extensions, content_type, **other)
-      spec = Spec.new(
-        content_type.freeze,
-        other[:dependency_regex].freeze,
-        other[:compile].freeze,
-        other[:compile_lib].freeze,
-        other[:minify].freeze,
-        other[:minify_lib].freeze,
-      ).freeze
-
-      extensions.each do |extension|
-        @@specs[extension] = spec
-      end
+      warn("#{self}.add_spec is deprecated and will be removed soon (use Darkroom.register instead)")
 
-      spec
+      params = other.dup
+      params[:content_type] = content_type
+      params[:import_regex] = params.delete(:dependency_regex) if params.key?(:dependency_regex)
+
+      Darkroom.register(*extensions, params)
     end
 
     ##
+    # DEPRECATED. Use Darkroom.delegate instead.
+    #
     # Returns the spec associated with a file extension.
     #
     # * +extension+ - File extension of the desired spec.
     #
     def self.spec(extension)
-      @@specs[extension]
-    end
+      warn("#{self}.spec is deprecated and will be removed soon (use Darkroom.delegate instead)")
 
-    ##
-    # Returns an array of file extensions for which specs exist.
-    #
-    def self.extensions
-      @@specs.keys
+      Darkroom.delegate(extension)
     end
 
     ##
     # Creates a new instance.
     #
-    # * +file+ - The path to the file on disk.
-    # * +path+ - The path this asset will be referenced by (e.g. /js/app.js).
+    # * +file+ - Path of file on disk.
+    # * +path+ - Path this asset will be referenced by (e.g. /js/app.js).
     # * +darkroom+ - Darkroom instance that the asset is a member of.
     # * +prefix+ - Prefix to apply to unversioned and versioned paths.
     # * +minify+ - Boolean specifying whether or not the asset should be minified when processed.
-    # * +internal+ - Boolean indicating whether or not the asset is only accessible internally (i.e. as a
-    #   dependency).
+    # * +internal+ - Boolean indicating whether or not the asset is only accessible internally (i.e. as an
+    #   import or reference).
     #
     def initialize(path, file, darkroom, prefix: nil, minify: false, internal: false)
       @path = path
@@ -96,7 +119,7 @@ class Darkroom
 
       @path_unversioned = "#{@prefix}#{@path}"
       @extension = File.extname(@path).downcase
-      @spec = self.class.spec(@extension) or raise(SpecNotDefinedError.new(@extension, @file))
+      @delegate = Darkroom.delegate(@extension) or raise(UnrecognizedExtensionError.new(@path))
 
       require_libs
       clear
@@ -104,9 +127,9 @@ class Darkroom
 
     ##
     # Processes the asset if modified (see #modified? for how modification is determined). File is read from
-    # disk, any dependencies are merged into its content (if spec for the asset type allows for it), the
-    # content is compiled (if the asset type requires compilation), and minified (if specified for this
-    # Asset). Returns true if asset was modified since it was last processed and false otherwise.
+    # disk, references are substituted (if supported), content is compiled (if required), imports are
+    # prefixed to its content (if supported), and content is minified (if supported and enabled). Returns
+    # true if asset was modified since it was last processed and false otherwise.
     #
     def process
       @process_key == @darkroom.process_key ? (return @processed) : (@process_key = @darkroom.process_key)
@@ -114,6 +137,9 @@ class Darkroom
 
       clear
       read
+      build_imports
+      build_references
+      process_dependencies
       compile
       minify
 
@@ -131,7 +157,32 @@ class Darkroom
     # Returns the HTTP MIME type string.
     #
     def content_type
-      @spec.content_type
+      @delegate.content_type
+    end
+
+    ##
+    # Returns boolean indicating whether or not the asset is binary.
+    #
+    def binary?
+      return @is_binary if defined?(@is_binary)
+
+      type, subtype = content_type.split('/')
+
+      @is_binary = type != 'text' && !subtype.include?('json') && !subtype.include?('xml')
+    end
+
+    ##
+    # Returns boolean indicating whether or not the asset is a font.
+    #
+    def font?
+      defined?(@is_font) ? @is_font : (@is_font = content_type.start_with?('font/'))
+    end
+
+    ##
+    # Returns boolean indicating whether or not the asset is an image.
+    #
+    def image?
+      defined?(@is_image) ? @is_image : (@is_image = content_type.start_with?('image/'))
     end
 
     ##
@@ -150,8 +201,8 @@ class Darkroom
     ##
     # Returns subresource integrity string.
     #
-    # * +algorithm+ - The hash algorithm to use to generate the integrity string (one of sha256, sha384, or
-    #   sha512).
+    # * +algorithm+ - Hash algorithm to use to generate the integrity string (one of :sha256, :sha384, or
+    #   :sha512).
     #
     def integrity(algorithm = :sha384)
       @integrity[algorithm] ||= "#{algorithm}-#{Base64.strict_encode64(
@@ -219,23 +270,21 @@ class Darkroom
     ##
     # Returns all dependencies (including dependencies of dependencies).
     #
-    # * +ancestors+ - Ancestor chain followed to get to this asset as a dependency.
+    # * +ignore+ - Assets already accounted for as dependency tree is walked (to prevent infinite loops when
+    #   circular chains are encountered).
     #
-    def dependencies(ancestors = Set.new)
-      @dependencies ||= @own_dependencies.inject([]) do |dependencies, own_dependency|
-        next dependencies if ancestors.include?(self)
-
-        ancestors << self
-        own_dependency.process
-
-        dependencies |= own_dependency.dependencies(ancestors)
-        dependencies |= [own_dependency]
-
-        dependencies.delete(self)
-        ancestors.delete(self)
+    def dependencies(ignore = Set.new)
+      @dependencies ||= accumulate(:dependencies, ignore)
+    end
 
-        dependencies
-      end
+    ##
+    # Returns all imports (including imports of imports).
+    #
+    # * +ignore+ - Assets already accounted for as import tree is walked (to prevent infinite loops when
+    #   circular chains are encountered).
+    #
+    def imports(ignore = Set.new)
+      @imports ||= accumulate(:imports, ignore)
     end
 
     ##
@@ -252,48 +301,124 @@ class Darkroom
     #
     def clear
       @dependencies = nil
+      @imports = nil
       @error = nil
       @fingerprint = nil
       @path_versioned = nil
 
-      (@errors ||= []).clear
       (@own_dependencies ||= []).clear
+      (@own_imports ||= []).clear
+      (@dependency_matches ||= []).clear
+      (@errors ||= []).clear
       (@content ||= +'').clear
       (@own_content ||= +'').clear
       (@integrity ||= {}).clear
     end
 
     ##
-    # Reads the asset file, building dependency array if dependencies are supported for the asset's type.
+    # Reads the asset file into memory.
     #
     def read
-      unless @spec.dependency_regex
-        @own_content = File.read(@file)
-        return
-      end
+      @own_content = File.read(@file)
+    end
 
-      File.new(@file).each.with_index do |line, line_num|
-        if (path = line[@spec.dependency_regex, :path])
-          if (dependency = @darkroom.manifest(path))
-            @own_dependencies << dependency
+    ##
+    # Builds reference info.
+    #
+    def build_references
+      return unless @delegate.reference_regex
+
+      @own_content.scan(@delegate.reference_regex) do
+        match = Regexp.last_match
+        path = match[:path]
+        format = match[:format]
+        format = REFERENCE_FORMATS[match[:entity]].first if format.nil? || format == ''
+
+        if (asset = @darkroom.manifest(path))
+          if !REFERENCE_FORMATS[match[:entity]].include?(format)
+            @errors << AssetError.new("Invalid reference format '#{format}' (must be one of "\
+              "'#{REFERENCE_FORMATS[match[:entity]].join("', '")}')", match[0], @path, line_num(match))
+          elsif match[:entity] == 'content' && format != 'base64' && asset.binary?
+            @errors << AssetError.new('Base64 encoding is required for binary assets', match[0], @path,
+              line_num(match))
+          elsif (error = @delegate.validate_reference&.(asset, match, format))
+            @errors << AssetError.new(error, match[0], @path, line_num(match))
           else
-            @errors << AssetNotFoundError.new(path, @path, line_num + 1)
+            @own_dependencies << asset
+            @dependency_matches << [:reference, asset, match, format]
           end
         else
-          @own_content << line
+          @errors << not_found_error(path, match)
+        end
+      end
+    end
+
+    ##
+    # Builds import info.
+    #
+    def build_imports
+      return unless @delegate.import_regex
+
+      @own_content.scan(@delegate.import_regex) do
+        match = Regexp.last_match
+        path = match[:path]
+
+        if (asset = @darkroom.manifest(path))
+          @own_dependencies << asset
+          @own_imports << asset
+          @dependency_matches << [:import, asset, match]
+        else
+          @errors << not_found_error(path, match)
         end
       end
+    end
 
-      @content << dependencies.map { |d| d.own_content }.join(DEPENDENCY_JOINER)
+    ##
+    # Processes imports and references.
+    #
+    def process_dependencies
+      @dependency_matches.sort_by! { |_, __, match| -match.begin(0) }.each do |kind, asset, match, format|
+        if kind == :import
+          @own_content[match.begin(0)...match.end(0)] = ''
+        elsif asset.dependencies.include?(self)
+          @errors << CircularReferenceError.new(match[0], @path, line_num(match))
+        else
+          value, start, finish = @delegate.reference_content&.(asset, match, format)
+          min_start, max_finish = match.offset(0)
+          start ||= format == 'displace' ? min_start : match.begin(:quoted)
+          finish ||= format == 'displace' ? max_finish : match.end(:quoted)
+          start = [[start, min_start].max, max_finish].min
+          finish = [[finish, max_finish].min, min_start].max
+
+          @own_content[start...finish] =
+            case "#{match[:entity]}-#{format}"
+            when 'path-versioned'
+              value || asset.path_versioned
+            when 'path-unversioned'
+              value || asset.path_unversioned
+            when 'content-base64'
+              quote = DEFAULT_QUOTE if match[:quote] == ''
+              "#{quote}data:#{asset.content_type};base64,#{Base64.strict_encode64(value || asset.content)}#{quote}"
+            when 'content-utf8'
+              quote = DEFAULT_QUOTE if match[:quote] == ''
+              "#{quote}data:#{asset.content_type};utf8,#{value || asset.content}#{quote}"
+            when 'content-displace'
+              value || asset.content
+            end
+        end
+      end
+
+      @content << imports.map { |d| d.own_content }.join(IMPORT_JOINER)
     end
 
     ##
-    # Compiles the asset if compilation is supported for the asset's type.
+    # Compiles the asset if compilation is supported for the asset's type and appends the asset's own
+    # content to the overall content string.
     #
     def compile
-      if @spec.compile
+      if @delegate.compile
         begin
-          @own_content = @spec.compile.call(@path, @own_content)
+          @own_content = @delegate.compile.(@path, @own_content)
         rescue => e
           @errors << e
         end
@@ -307,9 +432,9 @@ class Darkroom
     # (i.e. it's not already minified), and the asset is not marked as internal-only.
     #
     def minify
-      if @spec.minify && @minify && !@internal
+      if @delegate.minify && @minify && !@internal
         begin
-          @content = @spec.minify.call(@content)
+          @content = @delegate.minify.(@content)
         rescue => e
           @errors << e
         end
@@ -329,19 +454,59 @@ class Darkroom
     #
     def require_libs
       begin
-        require(@spec.compile_lib) if @spec.compile_lib
+        require(@delegate.compile_lib) if @delegate.compile_lib
       rescue LoadError
         compile_load_error = true
       end
 
       begin
-        require(@spec.minify_lib) if @spec.minify_lib && @minify
+        require(@delegate.minify_lib) if @delegate.minify_lib && @minify
       rescue LoadError
         minify_load_error = true
       end
 
-      raise(MissingLibraryError.new(@spec.compile_lib, 'compile', @extension)) if compile_load_error
-      raise(MissingLibraryError.new(@spec.minify_lib, 'minify', @extension)) if minify_load_error
+      raise(MissingLibraryError.new(@delegate.compile_lib, 'compile', @extension)) if compile_load_error
+      raise(MissingLibraryError.new(@delegate.minify_lib, 'minify', @extension)) if minify_load_error
+    end
+
+    ##
+    # Utility method used by #dependencies and #imports to recursively build arrays.
+    #
+    # * +name+ - Name of the array to accumulate (:dependencies or :imports).
+    # * +ignore+ - Set of assets already accumulated which can be ignored (used to avoid infinite loops when
+    #   circular references are encountered).
+    #
+    def accumulate(name, ignore)
+      ignore << self
+      process
+
+      instance_variable_get(:"@own_#{name}").each_with_object([]) do |asset, assets|
+        next if ignore.include?(asset)
+
+        assets.push(*asset.send(name, ignore), asset)
+        assets.uniq!
+        assets.delete(self)
+      end
+    end
+
+    ##
+    # Utility method that returns the appropriate error for a dependency that doesn't exist.
+    #
+    # * +path+ - Path of the asset which cannot be found.
+    # * +match+ - MatchData object of the regex for the asset that cannot be found.
+    #
+    def not_found_error(path, match)
+      klass = Darkroom.delegate(File.extname(path)) ? AssetNotFoundError : UnrecognizedExtensionError
+      klass.new(path, @path, line_num(match))
+    end
+
+    ##
+    # Utility method that returns the line number where a regex match was found.
+    #
+    # * +match+ - MatchData object of the regex.
+    #
+    def line_num(match)
+      @own_content[0..match.begin(:path)].count("\n") + 1
     end
   end
 end