asciidoctor 0.1.4 → 1.5.0

data/lib/asciidoctor/abstract_block.rb

@@ -6,9 +6,6 @@ class AbstractBlock < AbstractNode
   # Public: Substitutions to be applied to content in this block
   attr_reader :subs
 
-  # Public: Get/Set the String name of the render template
-  attr_accessor :template_name
-
   # Public: Get the Array of Asciidoctor::AbstractBlock sub-blocks for this block
   attr_reader :blocks
 
@@ -24,40 +21,72 @@ class AbstractBlock < AbstractNode
   # Public: Get/Set the caption for this block
   attr_accessor :caption
 
-  def initialize(parent, context)
-    super(parent, context)
+  # Public: Gets/Sets the location in the AsciiDoc source where this block begins
+  attr_accessor :source_location
+
+  def initialize parent, context, opts = {}
+    super
     @content_model = :compound
     @subs = []
-    @template_name = "block_#{context}"
+    @default_subs = nil
     @blocks = []
     @id = nil
     @title = nil
     @caption = nil
     @style = nil
-    if context == :document
-      @level = 0
-    elsif !parent.nil? && !self.is_a?(Section)
-      @level = parent.level
-    else
-      @level = nil
+    @level = if context == :document
+      0
+    elsif parent && context != :section
+      parent.level
     end
     @next_section_index = 0
     @next_section_number = 1
+    @source_location = nil
+  end
+
+  def block?
+    true
+  end
+
+  def inline?
+    false
   end
 
-  # Public: Get the rendered String content for this Block.  If the block
+  # Public: Update the context of this block.
+  #
+  # This method changes the context of this block. It also
+  # updates the node name accordingly.
+  def context=(context)
+    @context = context
+    @node_name = context.to_s
+  end
+
+  # Public: Get the converted String content for this Block.  If the block
   # has child blocks, the content method should cause them to be
-  # rendered and returned as content that can be included in the
+  # converted and returned as content that can be included in the
   # parent block's template.
-  def render
+  def convert
     @document.playback_attributes @attributes
-    renderer.render(@template_name, self)
+    converter.convert self
   end
 
-  # Public: Get an rendered version of the block content, rendering the
+  # Alias render to convert to maintain backwards compatibility
+  alias :render :convert
+
+  # Public: Get the converted result of the child blocks by converting the
   # children appropriate to content model that this block supports.
   def content
-    @blocks.map {|b| b.render } * EOL
+    @blocks.map {|b| b.convert } * EOL
+  end
+
+  # Public: Get the source file where this block started
+  def file
+    @source_location ? @source_location.file : nil
+  end
+
+  # Public: Get the source line number where this block started
+  def lineno
+    @source_location ? @source_location.lineno : nil
   end
 
   # Public: A convenience method that checks whether the specified
@@ -74,7 +103,7 @@ class AbstractBlock < AbstractNode
   # Public: A convenience method that indicates whether the title instance
   # variable is blank (nil or empty)
   def title?
-    !@title.to_s.empty?
+    !@title.nil_or_empty?
   end
 
   # Public: Get the String title of this Block with title substitions applied
@@ -161,52 +190,100 @@ class AbstractBlock < AbstractNode
   #   section.sections.size
   #   # => 1
   #
-  # returns an Array of Section objects
+  # Returns an [Array] of Section objects
   def sections
-    @blocks.inject([]) {|collector, block|
-      collector << block if block.is_a?(Section)
-      collector
-    }
+    @blocks.select {|block| block.context == :section }
   end
 
-  # Internal: Lock-in the substitutions for this block
-  #
-  # Looks for an attribute named "subs". If present, resolves the
-  # substitutions and assigns it to the subs property on this block.
-  # Otherwise, assigns a set of default substitutions based on the
-  # content model of the block.
+# stage the Enumerable mixin until we're sure we've got it right
+=begin
+  include ::Enumerable
+
+  # Public: Yield the block on this block node and all its descendant
+  # block node children to satisfy the Enumerable contract.
   #
   # Returns nothing
-  def lock_in_subs
-    default_subs = []
-    case @content_model
-    when :simple
-      default_subs = SUBS[:normal]
-    when :verbatim
-      if @context == :listing || (@context == :literal && !(option? 'listparagraph'))
-        default_subs = SUBS[:verbatim]
+  def each &block
+    # yucky, dlist is a special case
+    if @context == :dlist
+      @blocks.flatten.each &block
+    else
+      #yield self.header if @context == :document && header?
+      @blocks.each &block
+    end
+  end
+
+  #--
+  # TODO is there a way to make this lazy?
+  def each_recursive &block
+    block = lambda {|node| node } unless block_given?
+    results = []
+    self.each do |node|
+      results << block.call(node)
+      results.concat(node.each_recursive(&block)) if ::Enumerable === node
+    end
+    block_given? ? results : results.to_enum
+  end
+=end
+
+  # Public: Query for all descendant block nodes in the document tree that
+  # match the specified Symbol filter_context and, optionally, the style and/or
+  # role specified in the options Hash. If a block is provided, it's used as an
+  # additional filter. If no filters are specified, all block nodes in the tree
+  # are returned.
+  #
+  # Examples
+  #
+  #   doc.find_by context: :section 
+  #   #=> Asciidoctor::Section@14459860 { level: 0, title: "Hello, AsciiDoc!", blocks: 0 }
+  #   #=> Asciidoctor::Section@14505460 { level: 1, title: "First Section", blocks: 1 }
+  #
+  #   doc.find_by(context: :section) {|section| section.level == 1 }
+  #   #=> Asciidoctor::Section@14505460 { level: 1, title: "First Section", blocks: 1 }
+  #
+  #   doc.find_by context: :listing, style: 'source'
+  #   #=> Asciidoctor::Block@13136720 { context: :listing, content_model: :verbatim, style: "source", lines: 1 }
+  #
+  # Returns An Array of block nodes that match the given selector or nil if no matches are found
+  #--
+  # TODO support jQuery-style selector (e.g., image.thumb)
+  def find_by selector = {}, &block
+    result = []
+
+    if ((any_context = !(context_selector = selector[:context])) || context_selector == @context) &&
+        (!(style_selector = selector[:style]) || style_selector == @style) &&
+        (!(role_selector = selector[:role]) || has_role?(role_selector)) &&
+        (!(id_selector = selector[:id]) || id_selector == @id)
+      if id_selector
+        return [(block_given? && yield(self) ? self : self)]
       else
-        default_subs = SUBS[:basic]
+        result << (block_given? && yield(self) ? self : self)
       end
-    when :raw
-      default_subs = SUBS[:pass]
-    else
-      return
     end
 
-    if (custom_subs = @attributes['subs'])
-      @subs = resolve_block_subs custom_subs, @context
-    else
-      @subs = default_subs.dup
+    # process document header as a section if present
+    if @context == :document && (any_context || context_selector == :section) && header?
+      result.concat(@header.find_by(selector, &block) || [])
     end
 
-    # QUESION delegate this logic to method?
-    if @context == :listing && @style == 'source' && (@document.basebackend? 'html') &&
-      ((highlighter = @document.attributes['source-highlighter']) == 'coderay' ||
-      highlighter == 'pygments') && (attr? 'language')
-      @subs = @subs.map {|sub| sub == :specialcharacters ? :highlight : sub }
+    # yuck, dlist is a special case
+    unless context_selector == :document # optimization
+      if @context == :dlist
+        if any_context || context_selector != :section # optimization
+          @blocks.flatten.each do |li|
+            result.concat(li.find_by(selector, &block) || [])
+          end
+        end
+      elsif
+        @blocks.each do |b|
+          next if (context_selector == :section && b.context != :section) # optimization
+          result.concat(b.find_by(selector, &block) || [])
+        end
+      end
     end
+    result.empty? ? nil : result
   end
+  alias :query :find_by
 
   # Public: Remove a substitution from this block
   #
@@ -233,28 +310,23 @@ class AbstractBlock < AbstractNode
   #               If not provided, the name of the context for this block
   #               is used. (default: nil).
   #
-  # returns nothing
+  # Returns nothing
   def assign_caption(caption = nil, key = nil)
-    unless title? || @caption.nil?
-      return nil
-    end
+    return unless title? || !@caption
 
-    if caption.nil?
-      if @document.attributes.has_key? 'caption'
-        @caption = @document.attributes['caption']
+    if caption
+      @caption = caption
+    else
+      if (value = @document.attributes['caption'])
+        @caption = value
       elsif title?
         key ||= @context.to_s
         caption_key = "#{key}-caption"
-        if @document.attributes.has_key? caption_key
-          caption_title = @document.attributes["#{key}-caption"]
+        if (caption_title = @document.attributes[caption_key])
           caption_num = @document.counter_increment("#{key}-number", self)
           @caption = "#{caption_title} #{caption_num}. "
         end
-      else
-        @caption = caption
       end
-    else
-      @caption = caption
     end
     nil
   end
@@ -264,13 +336,27 @@ class AbstractBlock < AbstractNode
   # Assign the next index of this section within the parent
   # Block (in document order)
   #
-  # returns nothing
+  # Returns nothing
   def assign_index(section)
     section.index = @next_section_index
     @next_section_index += 1
-    if section.numbered
-      section.number = @next_section_number
-      @next_section_number += 1
+
+    if section.sectname == 'appendix'
+      appendix_number = @document.counter 'appendix-number', 'A'
+      section.number = appendix_number if section.numbered
+      if (caption = @document.attr 'appendix-caption', '') != ''
+        section.caption = %(#{caption} #{appendix_number}: )
+      else
+        section.caption = %(#{appendix_number}. )
+      end
+    elsif section.numbered
+      # chapters in a book doctype should be sequential even when divided into parts
+      if (section.level == 1 || (section.level == 0 && section.special)) && @document.doctype == 'book'
+        section.number = @document.counter('chapter-number', 1)
+      else
+        section.number = @next_section_number
+        @next_section_number += 1
+      end
     end
   end
 
@@ -280,12 +366,12 @@ class AbstractBlock < AbstractNode
   # and reassign the section 0-based index value to each Section
   # as it appears in document order.
   # 
-  # returns nothing
+  # Returns nothing
   def reindex_sections
     @next_section_index = 0
     @next_section_number = 0
     @blocks.each {|block|
-      if block.is_a?(Section)
+      if block.context == :section
         assign_index(block)
         block.reindex_sections
       end

data/lib/asciidoctor/abstract_node.rb

@@ -4,7 +4,7 @@ module Asciidoctor
 # all content segments in an AsciiDoc document.
 class AbstractNode
 
-  include Substituters
+  include Substitutors
 
   # Public: Get the element which is the parent of this node
   attr_reader :parent
@@ -15,24 +15,32 @@ class AbstractNode
   # Public: Get the Symbol context for this node
   attr_reader :context
 
-  # Public: Get the id of this node
+  # Public: Get the String name of this node
+  attr_reader :node_name
+
+  # Public: Get/Set the id of this node
   attr_accessor :id
 
   # Public: Get the Hash of attributes for this node
   attr_reader :attributes
 
-  def initialize(parent, context)
+  def initialize parent, context, opts = {}
     # document is a special case, should refer to itself
     if context == :document
       @parent = nil
       @document = parent
     else
-      @parent = parent
-      @document = (parent.nil? ? nil : parent.document)
+      if (@parent = parent)
+        @document = parent.document
+      else
+        @document = nil
+      end
     end
     @context = context
-    @attributes = {}
-    @passthroughs = []
+    @node_name = context.to_s
+    # QUESTION are we correct in duplicating the attributes (seems to be just as fast)
+    @attributes = opts.key?(:attributes) ? (opts[:attributes] || {}).dup : {}
+    @passthroughs = {}
   end
 
   # Public: Associate this Block with a new parent Block
@@ -46,6 +54,20 @@ class AbstractNode
     nil
   end
 
+  # Public: Returns whether this {AbstractNode} is an instance of {Inline}
+  #
+  # Returns [Boolean]
+  def inline?
+    raise ::NotImplementedError
+  end
+
+  # Public: Returns whether this {AbstractNode} is an instance of {Block}
+  #
+  # Returns [Boolean]
+  def block?
+    raise ::NotImplementedError
+  end
+
   # Public: Get the value of the specified attribute
   #
   # Get the value for the specified attribute. First look in the attributes on
@@ -54,20 +76,20 @@ class AbstractNode
   # Document node and return the value of the attribute if found. Otherwise,
   # return the default value, which defaults to nil.
   #
-  # name    - the String or Symbol name of the attribute to lookup
-  # default - the Object value to return if the attribute is not found (default: nil)
-  # inherit - a Boolean indicating whether to check for the attribute on the
-  #           AsciiDoctor::Document if not found on this node (default: false)
+  # name          - the String or Symbol name of the attribute to lookup
+  # default_value - the Object value to return if the attribute is not found (default: nil)
+  # inherit       - a Boolean indicating whether to check for the attribute on the
+  #                 AsciiDoctor::Document if not found on this node (default: false)
   #
   # return the value of the attribute or the default value if the attribute
   # is not found in the attributes of this node or the document node
-  def attr(name, default = nil, inherit = true)
-    name = name.to_s if name.is_a?(Symbol)
+  def attr(name, default_value = nil, inherit = true)
+    name = name.to_s if name.is_a?(::Symbol)
     inherit = false if self == @document
     if inherit
-      @attributes[name] || @document.attributes[name] || default
+      @attributes[name] || @document.attributes[name] || default_value
     else
-      @attributes[name] || default
+      @attributes[name] || default_value
     end
   end
 
@@ -89,7 +111,7 @@ class AbstractNode
   # comparison value is specified, whether the value of the attribute matches
   # the comparison value
   def attr?(name, expect = nil, inherit = true)
-    name = name.to_s if name.is_a?(Symbol)
+    name = name.to_s if name.is_a?(::Symbol)
     inherit = false if self == @document
     if expect.nil?
       @attributes.has_key?(name) || (inherit && @document.attributes.has_key?(name))
@@ -100,20 +122,21 @@ class AbstractNode
     end
   end
 
-  # Public: Assign the value to the specified key in this
-  # block's attributes hash.
+  # Public: Assign the value to the attribute name for the current node.
   #
-  # key - The attribute key (or name)
-  # val - The value to assign to the key
+  # name      - The String attribute name
+  # value     - The Object value to assign to the attribute name
+  # overwrite - A Boolean indicating whether to assign the attribute
+  #             if currently present in the attributes Hash
   #
-  # returns a flag indicating whether the assignment was performed
-  def set_attr(key, val, overwrite = nil)
+  # Returns a [Boolean] indicating whether the assignment was performed
+  def set_attr name, value, overwrite = nil
     if overwrite.nil?
-      @attributes[key] = val
+      @attributes[name] = value
       true
     else
-      if overwrite || @attributes.has_key?(key)
-        @attributes[key] = val
+      if overwrite || !(@attributes.key? name)
+        @attributes[name] = value
         true
       else
         false
@@ -135,33 +158,13 @@ class AbstractNode
   # enabled on the current node.
   #
   # Check if the option is enabled. This method simply checks to see if the
-  # {name}-option attribute is defined on the current node.
+  # %name%-option attribute is defined on the current node.
   #
   # name    - the String or Symbol name of the option
   #
   # return a Boolean indicating whether the option has been specified
   def option?(name)
-    @attributes.has_key? "#{name}-option"
-  end
-
-  # Public: Get the execution context of this object (via Kernel#binding).
-  #
-  # This method is used to set the 'self' reference as well as local variables
-  # that map to this method's arguments during the evaluation of a backend
-  # template.
-  #
-  # Each object in Ruby has a binding context that can be used to set the 'self'
-  # reference in an evaluation context. Any arguments passed to this
-  # method are also available in the execution environment.
-  #
-  # template -  The BaseTemplate instance in which this binding will be active.
-  #             Bound to the local variable of the same name, template.
-  #
-  # returns the execution context for this object so it can be be transferred to
-  # the backend template and binds the method arguments as local variables in
-  # that same environment.
-  def get_binding template
-    binding
+    @attributes.has_key? %(#{name}-option)
   end
 
   # Public: Update the attributes of this node with the new values in
@@ -172,16 +175,16 @@ class AbstractNode
   #
   # attributes - A Hash of attributes to assign to this node.
   #
-  # returns nothing
+  # Returns nothing
   def update_attributes(attributes)
     @attributes.update(attributes)
     nil
   end
 
-  # Public: Get the Asciidoctor::Renderer instance being used for the
-  # Asciidoctor::Document to which this node belongs
-  def renderer
-    @document.renderer
+  # Public: Get the Asciidoctor::Converter instance being used to convert the
+  # current Asciidoctor::Document.
+  def converter
+    @document.converter
   end
 
   # Public: A convenience method that checks if the role attribute is specified
@@ -249,7 +252,7 @@ class AbstractNode
     if attr? 'icon'
       image_uri(attr('icon'), nil)
     else
-      image_uri("#{name}.#{@document.attr('icontype', 'png')}", 'iconsdir')
+      image_uri(%(#{name}.#{@document.attr('icontype', 'png')}), 'iconsdir')
     end
   end
 
@@ -268,12 +271,10 @@ class AbstractNode
   #
   # Returns A String reference for the target media
   def media_uri(target, asset_dir_key = 'imagesdir')
-    if target.include?(':') && target.match(Asciidoctor::REGEXP[:uri_sniff])
+    if is_uri? target
       target
-    elsif asset_dir_key && attr?(asset_dir_key)
-      normalize_web_path(target, @document.attr(asset_dir_key))
     else
-      normalize_web_path(target)
+      normalize_web_path target, (asset_dir_key ? @document.attr(asset_dir_key) : nil)
     end
   end
 
@@ -297,14 +298,22 @@ class AbstractNode
   #
   # Returns A String reference or data URI for the target image
   def image_uri(target_image, asset_dir_key = 'imagesdir')
-    if target_image.include?(':') && target_image.match(Asciidoctor::REGEXP[:uri_sniff])
+    if (doc = @document).safe < SafeMode::SECURE && doc.attr?('data-uri')
+      if is_uri?(target_image) ||
+          (asset_dir_key && (images_base = doc.attr(asset_dir_key)) &&
+          is_uri?(images_base) && (target_image = normalize_web_path target_image, images_base))
+        if doc.attr? 'allow-uri-read'
+          generate_data_uri_from_uri target_image, doc.attr?('cache-uri')
+        else
+          target_image
+        end
+      else
+        generate_data_uri target_image, asset_dir_key
+      end
+    elsif is_uri? target_image
       target_image
-    elsif @document.safe < Asciidoctor::SafeMode::SECURE && @document.attr?('data-uri')
-      generate_data_uri(target_image, asset_dir_key)
-    elsif asset_dir_key && attr?(asset_dir_key)
-      normalize_web_path(target_image, @document.attr(asset_dir_key))
     else
-      normalize_web_path(target_image)
+      normalize_web_path target_image, (asset_dir_key ? doc.attr(asset_dir_key) : nil)
     end
   end
 
@@ -321,32 +330,69 @@ class AbstractNode
   #
   # Returns A String data URI containing the content of the target image
   def generate_data_uri(target_image, asset_dir_key = nil)
-    Helpers.require_library 'base64'
-
-    ext = File.extname(target_image)[1..-1]
-    mimetype = 'image/' + ext
-    mimetype = "#{mimetype}+xml" if ext == 'svg'
+    ext = ::File.extname(target_image)[1..-1]
+    mimetype = (ext == 'svg' ? 'image/svg+xml' : %(image/#{ext}))
     if asset_dir_key
-      #asset_dir_path = normalize_system_path(@document.attr(asset_dir_key), nil, nil, :target_name => asset_dir_key)
-      #image_path = normalize_system_path(target_image, asset_dir_path, nil, :target_name => 'image')
       image_path = normalize_system_path(target_image, @document.attr(asset_dir_key), nil, :target_name => 'image')
     else
       image_path = normalize_system_path(target_image)
     end
 
-    if !File.readable? image_path
-      warn "asciidoctor: WARNING: image to embed not found or not readable: #{image_path}"
+    unless ::File.readable? image_path
+      warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path})
+      # must enclose string following return in " for Opal
       return "data:#{mimetype}:base64,"
+      # uncomment to return 1 pixel white dot instead
       #return 'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=='
     end
 
     bindata = nil
-    if IO.respond_to? :binread
-      bindata = IO.binread(image_path)
+    if ::IO.respond_to? :binread
+      bindata = ::IO.binread(image_path)
     else
-      bindata = File.open(image_path, 'rb') {|file| file.read }
+      bindata = ::File.open(image_path, 'rb') {|file| file.read }
+    end
+    %(data:#{mimetype};base64,#{::Base64.encode64(bindata).delete EOL})
+  end
+ 
+  # Public: Read the image data from the specified URI and generate a data URI
+  #
+  # The image data is read from the URI and converted to Base64. A data URI is
+  # constructed from the content_type header and Base64 data and returned,
+  # which can then be used in an image tag.
+  #
+  # image_uri  - The URI from which to read the image data. Can be http://, https:// or ftp://
+  # cache_uri  - A Boolean to control caching. When true, the open-uri-cached library
+  #              is used to cache the image for subsequent reads. (default: false)
+  #
+  # Returns A data URI string built from Base64 encoded data read from the URI
+  # and the mime type specified in the Content Type header.
+  def generate_data_uri_from_uri image_uri, cache_uri = false
+    Helpers.require_library 'base64'
+    if cache_uri
+      # caching requires the open-uri-cached gem to be installed
+      # processing will be automatically aborted if these libraries can't be opened
+      Helpers.require_library 'open-uri/cached', 'open-uri-cached'
+    elsif !::RUBY_ENGINE_OPAL
+      # autoload open-uri
+      ::OpenURI
+    end
+
+    begin
+      mimetype = nil
+      bindata = open(image_uri, 'rb') {|file|
+        mimetype = file.content_type 
+        file.read
+      }
+      %(data:#{mimetype};base64,#{Base64.encode64(bindata).delete EOL})
+    rescue
+      warn %(asciidoctor: WARNING: could not retrieve image data from URI: #{image_uri})
+      image_uri
+      # uncomment to return empty data (however, mimetype needs to be resolved)
+      #%(data:#{mimetype}:base64,)
+      # uncomment to return 1 pixel white dot instead
+      #'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=='
     end
-    "data:#{mimetype};base64,#{Base64.encode64(bindata).delete("\n")}"
   end
 
   # Public: Read the contents of the file at the specified path.
@@ -357,11 +403,12 @@ class AbstractNode
   # warn_on_failure - a Boolean that controls whether a warning is issued if
   #                   the file cannot be read
   #
-  # returns the contents of the file at the specified path, or nil
+  # Returns the [String] content of the file at the specified path, or nil
   # if the file does not exist.
   def read_asset(path, warn_on_failure = false)
-    if File.readable? path
-      File.read(path).chomp
+    if ::File.readable? path
+      # QUESTION should we use strip or rstrip instead of chomp here?
+      ::File.read(path).chomp
     else
       warn "asciidoctor: WARNING: file does not exist or cannot be read: #{path}" if warn_on_failure
       nil
@@ -370,20 +417,20 @@ class AbstractNode
 
   # Public: Normalize the web page using the PathResolver.
   #
-  # See PathResolver::web_path(target, start) for details.
+  # See {PathResolver#web_path} for details.
   #
   # target - the String target path
   # start  - the String start (i.e, parent) path (optional, default: nil)
   #
-  # returns the resolved String path 
+  # Returns the resolved [String] path 
   def normalize_web_path(target, start = nil)
-    PathResolver.new.web_path(target, start)
+    (@path_resolver ||= PathResolver.new).web_path(target, start)
   end
 
   # Public: Resolve and normalize a secure path from the target and start paths
   # using the PathResolver.
   #
-  # See PathResolver::system_path(target, start, jail, opts) for details.
+  # See {PathResolver#system_path} for details.
   #
   # The most important functionality in this method is to prevent resolving a
   # path outside of the jail (which defaults to the directory of the source
@@ -402,17 +449,21 @@ class AbstractNode
   # raises a SecurityError if a jail is specified and the resolved path is
   # outside the jail.
   #
-  # returns a String path resolved from the start and target paths, with any
+  # Returns the [String] path resolved from the start and target paths, with any
   # parent references resolved and self references removed. If a jail is provided,
   # this path will be guaranteed to be contained within the jail.
-  def normalize_system_path(target, start = nil, jail = nil, opts = {})
-    if start.nil?
-      start = @document.base_dir
-    end
-    if jail.nil? && @document.safe >= SafeMode::SAFE
-      jail = @document.base_dir
+  def normalize_system_path target, start = nil, jail = nil, opts = {}
+    if (doc = @document).safe < SafeMode::SAFE
+      if start
+        start = ::File.join doc.base_dir, start unless (@path_resolver ||= PathResolver.new).is_root? start
+      else
+        start = doc.base_dir
+      end
+    else
+      start = doc.base_dir unless start
+      jail = doc.base_dir unless jail
     end
-    PathResolver.new.system_path(target, start, jail, opts)
+    (@path_resolver ||= PathResolver.new).system_path target, start, jail, opts
   end
 
   # Public: Normalize the asset file or directory to a concrete and rinsed path
@@ -426,7 +477,13 @@ class AbstractNode
 
   # Public: Calculate the relative path to this absolute filename from the Document#base_dir
   def relative_path(filename)
-    PathResolver.new.relative_path filename, @document.base_dir
+    (@path_resolver ||= PathResolver.new).relative_path filename, @document.base_dir
+  end
+
+  # Public: Check whether the specified String is a URI by
+  # matching it against the Asciidoctor::UriSniffRx regex.
+  def is_uri? str
+    str.include?(':') && UriSniffRx =~ str
   end
 
   # Public: Retrieve the list marker keyword for the specified list type.
@@ -435,7 +492,7 @@ class AbstractNode
   #
   # list_type - the type of list; default to the @style if not specified
   #
-  # returns the single-character String keyword that represents the marker for the specified list type
+  # Returns the single-character [String] keyword that represents the marker for the specified list type
   def list_marker_keyword(list_type = nil)
     ORDERED_LIST_KEYWORDS[list_type || @style]
   end