darkroom 0.0.8 → 0.0.10

data/lib/darkroom/delegate.rb

@@ -1,237 +1,280 @@
+# frozen_string_literal: true
+
 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)
+    IMPORT_REGEX_CAPTURES = %w[path].freeze
+    REFERENCE_REGEX_CAPTURES = %w[quote path quoted entity format].freeze
+    LIB_REQUIRES = [:compile, :finalize, :minify].freeze
+
+    @content_type = nil
+    @parsers = nil
+    @compile_lib = nil
+    @compile_delegate = nil
+    @compile_handler = nil
+    @finalize_lib = nil
+    @finalize_handler = nil
+    @minify_lib = nil
+    @minify_handler = nil
+
+    # Public: Set and/or get the HTTP MIME type string, falling back to that of the parent class.
+    #
+    # Returns the String content type.
+    def self.content_type(content_type = (get = true; nil))
+      if get
+        defined?(@content_type) ? @content_type : superclass.content_type
+      else
+        @content_type = content_type
       end
     end
 
-    class << self; alias :get_content_type :content_type end
+    # Public: Get parsers, falling back to those of the parent class.
+    #
+    # Returns the Array of Proc parsers.
+    def self.parsers
+      defined?(@parsers) ? @parsers : superclass.parsers
+    end
 
-    ##
-    # Sets or returns HTTP MIME type string.
+    # Public: Iterate over each parser.
     #
-    def self.content_type(content_type = (get = true; nil))
-      get ? get_content_type : (@content_type = content_type)
+    # Yields each parser's Symbol kind, Regexp regex, and Proc handler.
+    #
+    # Returns nothing.
+    def self.each_parser
+      parsers&.each do |kind, (regex, handler)|
+        yield(kind, regex, handler)
+      end
     end
 
-    ##
-    # Configures how imports are handled.
+    # Public: Get the name of the compile library to require, falling back to that of the parent class.
     #
-    # [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.
+    # Returns the String library name if present or nil otherwise.
+    def self.compile_lib
+      defined?(@compile_lib) ? @compile_lib : superclass.compile_lib
+    end
+
+    # Public: Get the Delegate class used once an asset is compiled, falling back to that of the parent
+    # class.
+    #
+    # Returns the Delegate class if present or nil otherwise.
+    def self.compile_delegate
+      defined?(@compile_delegate) ? @compile_delegate : superclass.compile_delegate
+    end
+
+    # Public: Get the compile handler, falling back to that of the parent class.
+    #
+    # Returns the Proc handler if present or nil otherwise.
+    def self.compile_handler
+      defined?(@compile_handler) ? @compile_handler : superclass.compile_handler
+    end
+
+    # Public: Get the name of the finalize library to require, falling back to that of the parent class.
+    #
+    # Returns the String library name if present or nil otherwise.
+    def self.finalize_lib
+      defined?(@finalize_lib) ? @finalize_lib : superclass.finalize_lib
+    end
+
+    # Public: Get the finalize handler, falling back to that of the parent class.
+    #
+    # Returns the Proc handler if present or nil otherwise.
+    def self.finalize_handler
+      defined?(@finalize_handler) ? @finalize_handler : superclass.finalize_handler
+    end
+
+    # Public: Get the name of the minify library to require, falling back to that of the parent class.
+    #
+    # Returns the String library name if present or nil otherwise.
+    def self.minify_lib
+      defined?(@minify_lib) ? @minify_lib : superclass.minify_lib
+    end
+
+    # Public: Get the minify handler, falling back to that of the parent class.
+    #
+    # Returns the Proc handler if present or nil otherwise.
+    def self.minify_handler
+      defined?(@minify_handler) ? @minify_handler : superclass.minify_handler
+    end
+
+    # Internal: Configure import handling.
     #
+    # regex   - Regexp for finding import statements. Must contain a named components :quote (' or ") and
+    #           :path (the path of the asset being imported).
+    # handler - Proc for special handling of import statements (optional), which is passed three keyword
+    #           arguments:
+    #
+    #           parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+    #           match:      - MatchData object from the match against the regex.
+    #           asset:      - Asset object of the asset being imported.
+    #
+    #           Returns nil for default behavior, or a String which is used as the substitution for the text
+    #             matched by the regex. The portion of the matched text that is replaced can optionally be
+    #             changed by returning second and third Integer values specifying start and end indexes
+    #             within the regex match (e.g. ['my substitution', match.begin(:path) + 1,
+    #             match.end(:path) - 1]).
+    #           Throws :error with a String message when an error is encountered.
+    #
+    # Returns nothing.
+    # Raises RuntimeError if the regex does not have the required named captures.
     def self.import(regex, &handler)
+      validate_regex!(:import, regex, IMPORT_REGEX_CAPTURES)
+
       parse(:import, regex, &handler)
     end
 
-    ##
-    # Configures how references are handled.
+    # Internal: Configure reference handling.
     #
-    # [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.
+    # regex -   Regex for finding references. Must contain named components :quote (' or "), :path (the path
+    #           of the asset being referenced), :quoted (everything inside the quotes), :entity ('path' or
+    #           'content'), and :format (see Asset::REFERENCE_FORMATS).
+    # handler - Proc for special handling of references (optional), which is passed four keyword arguments:
     #
+    #           parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+    #           match:      - MatchData object from the match against the regex.
+    #           asset:      - Asset object of the asset being referenced.
+    #           format:     - String format of the reference (see Asset::REFERENCE_FORMATS).
+    #
+    #           Returns nil for default behavior, or a String which is used as the substitution for the text
+    #             matched by the regex. The portion of the matched text that is replaced can optionally be
+    #             changed by returning second and third Integer values specifying start and end indexes
+    #             within the regex match (e.g. ['my substitution', match.begin(:path) + 1,
+    #             match.end(:path) - 1]).
+    #           Throws :error with a String message when an error is encountered.
+    #
+    # Returns nothing.
+    # Raises RuntimeError if the regex does not have the required named captures.
     def self.reference(regex, &handler)
+      validate_regex!(:reference, regex, REFERENCE_REGEX_CAPTURES)
+
       parse(:reference, regex, &handler)
     end
 
-    ##
-    # Configures a parser.
+    # Internal: Configure a parser.
+    #
+    # kind    - Symbol name to describe what is being parsed. Should be unique across all parse calls. When
+    #           subclassing another Delegate, this can be used to override the parent class's regex and
+    #           handler.
+    # regex   - Regexp to match against.
+    # handler - Proc for handling matches of the regex, which is passed two keyword arguments:
     #
-    # [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.
+    #           parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+    #           match:      - MatchData object from the match against the regex.
     #
+    #           Returns a String which is used as the substitution for the text matched by the regex. The
+    #             portion of the matched text that is replaced can optionally be changed by returning second
+    #             and third Integer values specifying start and end indexes within the regex match (e.g.
+    #             ['my substitution', match.begin(:path) + 1, match.end(:path) - 1]).
+    #           Throws :error with a String message when an error is encountered.
+    #
+    # Returns nothing.
     def self.parse(kind, regex, &handler)
-      @parsers = parsers&.dup || {} unless @parsers
+      @parsers ||= parsers&.dup || {}
       @parsers[kind] = [regex, handler]
     end
 
-    ##
-    # Configures compilation.
+    # Internal: Configure compilation.
+    #
+    # lib:      - String name of a library to require that is needed by the handler (optional).
+    # delegate: - Delegate class to be used after the asset is compiled (optional).
+    # handler   - Proc to call that will return the compiled version of the asset's own content, which is
+    #             passed three keyword arguments:
     #
-    # [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.
+    #             parse_data:  - Hash for storing arbitrary data across calls to this and other handlers.
+    #             path:        - String path of the asset.
+    #             own_content: - String own content (without imports) of the asset.
     #
+    #             Returns a String which is used as a replacement for the asset's own content.
+    #             Raises StandardError when an error is encountered.
+    #
+    # Returns nothing.
     def self.compile(lib: nil, delegate: nil, &handler)
       @compile_lib = lib
       @compile_delegate = delegate
       @compile_handler = handler
     end
 
-    ##
-    # Configures finalize behavior.
+    # Internal: Configure finalize behavior.
+    #
+    # lib:    - String name of a library to require that is needed by the handler (optional).
+    # handler - Proc to call that will return the finalized version of the asset's compiled content (with
+    #           imports prepended), which is passed three keyword arguments:
     #
-    # [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.
+    #           parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+    #           path:       - String path of the asset.
+    #           content:    - String content of the compiled asset (with imports prepended).
     #
+    #           Returns a String which is used as a replacement for the asset's content.
+    #           Raises StandardError when an error is encountered.
+    #
+    # Returns nothing.
     def self.finalize(lib: nil, &handler)
       @finalize_lib = lib
       @finalize_handler = handler
     end
 
-    ##
-    # Configures minification.
+    # Internal: Configure minification.
+    #
+    # lib:    - String name of a library to require that is needed by the handler (optional).
+    # handler - Proc to call that will return the minified version of the asset's finalized content, which
+    #           is passed three keyword arguments:
     #
-    # [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.
+    #           parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+    #           path:       - String oath of the asset being minified.
+    #           content:    - string content of the finalized asset.
+    #
+    #           Returns a String which is used as the minified version of the asset's content.
+    #           Raises StandardError when an error is encountered.
     #
     def self.minify(lib: nil, &handler)
       @minify_lib = lib
       @minify_handler = handler
     end
 
-    ##
-    # Throws +:error+ with a message.
+    # Internal: Throw :error with a message.
     #
-    # [message] Message to include with the throw.
+    # message - String message to include with the throw.
     #
+    # Returns nothing.
     def self.error(message)
       throw(:error, message)
     end
 
-    ##
-    # Returns regex for a parser.
+    # Internal: Get a parser's regex.
     #
-    # [kind] Name of the parser.
+    # kind - Symbol name of the parser.
     #
+    # Returns the Regexp.
     def self.regex(kind)
       parsers[kind]&.first
     end
 
-    ##
-    # Returns handler for a parser.
+    # Internal: Get a parser's handler.
     #
-    # [kind] Name of the parser.
+    # kind - Symbol name of the parser.
     #
+    # Returns the Proc handler.
     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.
+    # Internal: Raise an exception if a regex does not have the required named captures.
     #
-    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.
+    # name              - Symbol name of the regex (used in the exception message).
+    # regex             - Regexp to validate.
+    # required_captures - Array of String required named captures.
     #
-    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
+    # Returns nothing.
+    # Raises RuntimeError if the regex does not have the required named captures.
+    def self.validate_regex!(name, regex, required_captures)
+      missing = (required_captures - regex.named_captures.keys)
 
-          self.reference(reference_regex) do |parse_data:, match:, asset:, format:|
-            error_message = validate_reference&.call(asset, match, format)
-            error(error_message) if error_message
+      return if missing.empty?
 
-            reference_content&.call(asset, match, format)
-          end
-        elsif reference_regex
-          self.reference(reference_regex)
-        end
+      name = name.to_s.capitalize
+      plural = missing.size != 1
+      missing_str = missing.join(', ')
 
-        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
+      raise("#{name} regex is missing required named capture#{'s' if plural}: #{missing_str}")
     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 → css_delegate.rb}

@@ -4,6 +4,7 @@ require_relative('../asset')
 require_relative('../delegate')
 
 class Darkroom
+  # Delegate for handling CSS-specific asset processing.
   class CSSDelegate < Delegate
     IMPORT_REGEX = /
       (?<=^|;)[^\S\n]*

data/lib/darkroom/delegates/{html.rb → html_delegate.rb}

@@ -4,6 +4,7 @@ require_relative('../asset')
 require_relative('../delegate')
 
 class Darkroom
+  # Delegate for handling HTML-specific asset processing.
   class HTMLDelegate < Delegate
     REFERENCE_REGEX = /
       <(?<tag>a|area|audio|base|embed|iframe|img|input|link|script|source|track|video)\s+[^>]*
@@ -26,8 +27,8 @@ class Darkroom
           if asset.content_type == 'text/javascript'
             offset = match.begin(0)
 
-            "#{match[0][0..(match.begin(:attr) - 2 - offset)]}"\
-            "#{match[0][(match.end(:quoted) + match[:quote].size - offset)..(match.end(0) - offset)]}"\
+            "#{match[0][0..(match.begin(:attr) - 2 - offset)]}" \
+            "#{match[0][(match.end(:quoted) + match[:quote].size - offset)..(match.end(0) - offset)]}" \
             "#{asset.content}"
           else
             error('Asset content type must be text/javascript')
@@ -46,7 +47,7 @@ class Darkroom
 
         content = asset.content.dup
         content.gsub!('#', '%23')
-        content.gsub!(quote, quote == '"' ? "&#34;" : '&#39;')
+        content.gsub!(quote, quote == '"' ? '&#34;' : '&#39;')
 
         content
       end

data/lib/darkroom/delegates/{htx.rb → htx_delegate.rb}

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
-require_relative('html')
-require_relative('javascript')
+require_relative('html_delegate')
+require_relative('javascript_delegate')
 
 class Darkroom
+  # Delegate for handling HTX-specific asset processing.
   class HTXDelegate < HTMLDelegate
     compile(lib: 'htx', delegate: JavaScriptDelegate) do |parse_data:, path:, own_content:|
       module_supported = false

data/lib/darkroom/delegates/{javascript.rb → javascript_delegate.rb}

@@ -5,13 +5,14 @@ require_relative('../asset')
 require_relative('../delegate')
 
 class Darkroom
+  # Delegate for handling JavaScript-specific asset processing.
   class JavaScriptDelegate < Delegate
     IDENTIFIER_REGEX = /[_$a-zA-Z][_$a-zA-Z0-9]*/.freeze
     COMMA_REGEX = /,/.freeze
     QUOTED_REGEX = /
       (?<quoted>
-        (?<quote>['"])(
-          (?<=[^\\])\\(\\\\)*\k<quote> |
+        (?<quote>['"])(?:
+          (?<=[^\\])\\(?:\\\\)*\k<quote> |
           (?!\k<quote>).
         )*\k<quote>
       )
@@ -131,14 +132,14 @@ class Darkroom
         end while items.any? { |i| i.first == mod }
 
         own_content.prepend(
-          "let #{items.map(&:first).join(', ')}; "\
-          "$import('#{import_path}', "\
+          "let #{items.map(&:first).join(', ')}; " \
+          "$import('#{import_path}', " \
           "#{mod} => #{prefix}#{items.map { |(i, e)| "#{i} = #{mod}#{e}" }.join(', ')}#{suffix})\n"
         )
       end
 
       own_content.prepend("['#{path}', $import => {\n\n")
-      own_content << <<~EOS
+      own_content << <<~JS
 
         return Object.seal({#{
           if parse_data[:exports] && !parse_data[:exports].empty?
@@ -147,7 +148,7 @@ class Darkroom
         }})
 
         }],
-      EOS
+      JS
     end
 
     ########################################################################################################
@@ -158,7 +159,7 @@ class Darkroom
       next unless Darkroom.javascript_iife
 
       (content.frozen? ? content.dup : content).prepend(
-        <<~EOS
+        <<~JS
           ((...bundle) => {
             const modules = {}
             const setters = []
@@ -172,7 +173,7 @@ class Darkroom
               setter(modules[name])
           })(
 
-        EOS
+        JS
       ) << "\n)\n"
     end
 

data/lib/darkroom/errors/asset_error.rb

@@ -1,33 +1,22 @@
 # frozen_string_literal: true
 
 class Darkroom
-  ##
   # General error class used for errors encountered while processing an asset.
-  #
   class AssetError < StandardError
     attr_reader(:detail, :source_path, :source_line_num)
 
-    ##
-    # Creates a new instance.
-    #
-    # [message] Description of the error.
-    # [detail] Additional detail about the error.
-    # [source_path] Path of the asset that contains the error.
-    # [source_line_num] Line number in the asset where the error is located.
+    # Public: Create a new instance.
     #
+    # message         - String description of the error.
+    # detail          - String additional error detail.
+    # source_path     - String path of the asset that contains the error.
+    # source_line_num - Integer line number in the asset file where the error was located.
     def initialize(message, detail, source_path = nil, source_line_num = nil)
-      super(message)
+      super("#{"#{source_path}:#{source_line_num || '?'}: " if source_path}#{message}: #{detail}")
 
       @detail = detail
       @source_path = source_path
       @source_line_num = source_line_num
     end
-
-    ##
-    # Returns a string representation of the error.
-    #
-    def to_s
-      "#{"#{@source_path}:#{@source_line_num || '?'}: " if @source_path}#{super}: #{@detail}"
-    end
   end
 end

data/lib/darkroom/errors/asset_not_found_error.rb

@@ -3,18 +3,14 @@
 require_relative('asset_error')
 
 class Darkroom
-  ##
   # Error class used when an asset requested explicitly or specified as a dependency of another doesn't
   # exist.
-  #
   class AssetNotFoundError < AssetError
-    ##
-    # Creates a new instance.
-    #
-    # [path] Path of asset that doesn't exist.
-    # [source_path] Path of the asset that contains the error.
-    # [source_line_num] Line number in the asset where the error is located.
+    # Public: Create a new instance.
     #
+    # path            - String path of asset that doesn't exist.
+    # source_path     - String path of the asset that contains the error.
+    # source_line_num - Integer line number in the asset file where the error is located.
     def initialize(path, source_path = nil, source_line_num = nil)
       super('Asset not found', path, source_path, source_line_num)
     end

data/lib/darkroom/errors/circular_reference_error.rb

@@ -3,17 +3,13 @@
 require_relative('asset_error')
 
 class Darkroom
-  ##
   # Error class used when an asset reference results in a circular reference chain.
-  #
   class CircularReferenceError < AssetError
-    ##
-    # Creates a new instance.
-    #
-    # [snippet] Snippet showing the reference.
-    # [source_path] Path of the asset that contains the error.
-    # [source_line_num] Line number in the asset where the error is located.
+    # Public: Create a new instance.
     #
+    # snippet         - String snippet showing the reference.
+    # source_path     - String path of the asset that contains the error.
+    # source_line_num - Integer line number in the asset file where the error is located.
     def initialize(snippet, source_path, source_line_num)
       super('Reference would result in a circular reference chain', snippet, source_path, source_line_num)
     end