asciidoctor 1.5.8 → 2.0.17

data/lib/asciidoctor/helpers.rb

@@ -1,14 +1,17 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 module Asciidoctor
+# Internal: Except where noted, a module that contains internal helper functions.
 module Helpers
-  # Internal: Require the specified library using Kernel#require.
+  module_function
+
+  # Public: Require the specified library using Kernel#require.
   #
   # Attempts to load the library specified in the first argument using the
   # Kernel#require. Rescues the LoadError if the library is not available and
   # passes a message to Kernel#raise if on_failure is :abort or Kernel#warn if
   # on_failure is :warn to communicate to the user that processing is being
   # aborted or functionality is disabled, respectively. If a gem_name is
-  # specified, the message communicates that a required gem is not installed.
+  # specified, the message communicates that a required gem is not available.
   #
   # name       - the String name of the library to require.
   # gem_name   - a Boolean that indicates whether this library is provided by a RubyGem,
@@ -20,108 +23,96 @@ module Helpers
   # Otherwise, if on_failure is :abort, Kernel#raise is called with an appropriate message.
   # Otherwise, if on_failure is :warn, Kernel#warn is called with an appropriate message and nil returned.
   # Otherwise, nil is returned.
-  def self.require_library name, gem_name = true, on_failure = :abort
+  def require_library name, gem_name = true, on_failure = :abort
     require name
-  rescue ::LoadError => e
+  rescue ::LoadError
     include Logging unless include? Logging
     if gem_name
       gem_name = name if gem_name == true
       case on_failure
       when :abort
-        raise ::LoadError, %(asciidoctor: FAILED: required gem '#{gem_name}' is not installed. Processing aborted.)
+        details = $!.path == gem_name ? '' : %[ (reason: #{$!.path ? %(cannot load '#{$!.path}') : $!.message})]
+        raise ::LoadError, %(asciidoctor: FAILED: required gem '#{gem_name}' is not available#{details}. Processing aborted.)
       when :warn
-        logger.warn %(optional gem '#{gem_name}' is not installed. Functionality disabled.)
+        details = $!.path == gem_name ? '' : %[ (reason: #{$!.path ? %(cannot load '#{$!.path}') : $!.message})]
+        logger.warn %(optional gem '#{gem_name}' is not available#{details}. Functionality disabled.)
       end
     else
       case on_failure
       when :abort
-        raise ::LoadError, %(asciidoctor: FAILED: #{e.message.chomp '.'}. Processing aborted.)
+        raise ::LoadError, %(asciidoctor: FAILED: #{$!.message.chomp '.'}. Processing aborted.)
       when :warn
-        logger.warn %(#{e.message.chomp '.'}. Functionality disabled.)
+        logger.warn %(#{$!.message.chomp '.'}. Functionality disabled.)
       end
     end
     nil
   end
 
-  # Public: Normalize the data to prepare for parsing
-  #
-  # Delegates to Helpers#normalize_lines_from_string if data is a String.
-  # Delegates to Helpers#normalize_lines_array if data is a String Array.
-  #
-  # returns a String Array of normalized lines
-  def self.normalize_lines data
-    ::String === data ? (normalize_lines_from_string data) : (normalize_lines_array data)
-  end
-
-  # Public: Normalize the array of lines to prepare them for parsing
-  #
-  # Force encodes the data to UTF-8 and removes trailing whitespace from each line.
-  #
-  # If a BOM is present at the beginning of the data, a best attempt
-  # is made to encode from the specified encoding to UTF-8.
-  #
-  # data - a String Array of lines to normalize
-  #
-  # returns a String Array of normalized lines
-  def self.normalize_lines_array data
-    return data if data.empty?
-
-    leading_bytes = (first_line = data[0]).unpack 'C3'
-    if COERCE_ENCODING
-      utf8 = ::Encoding::UTF_8
-      if (leading_2_bytes = leading_bytes.slice 0, 2) == BOM_BYTES_UTF_16LE
-        # HACK Ruby messes up trailing whitespace on UTF-16LE, so reencode whole document first
-        data = data.join
-        return (((data.force_encoding ::Encoding::UTF_16LE).slice 1, data.length).encode utf8).each_line.map {|line| line.rstrip }
-      elsif leading_2_bytes == BOM_BYTES_UTF_16BE
-        data[0] = (first_line.force_encoding ::Encoding::UTF_16BE).slice 1, first_line.length
-        return data.map {|line| ((line.force_encoding ::Encoding::UTF_16BE).encode utf8).rstrip }
-      elsif leading_bytes == BOM_BYTES_UTF_8
-        data[0] = (first_line.force_encoding utf8).slice 1, first_line.length
-      end
-
-      data.map {|line| line.encoding == utf8 ? line.rstrip : (line.force_encoding utf8).rstrip }
+  # Internal: Prepare the source data Array for parsing.
+  #
+  # Encodes the data to UTF-8, if necessary, and removes any trailing
+  # whitespace from every line.
+  #
+  # If a BOM is found at the beginning of the data, a best attempt is made to
+  # encode it to UTF-8 from the specified source encoding.
+  #
+  # data     - the source data Array to prepare (no nil entries allowed)
+  # trim_end - whether to trim whitespace from the end of each line;
+  #            (true cleans all whitespace; false only removes trailing newline) (default: true)
+  #
+  # returns a String Array of prepared lines
+  def prepare_source_array data, trim_end = true
+    return [] if data.empty?
+    if (leading_2_bytes = (leading_bytes = (first = data[0]).unpack 'C3').slice 0, 2) == BOM_BYTES_UTF_16LE
+      data[0] = first.byteslice 2, first.bytesize
+      # NOTE you can't split a UTF-16LE string using .lines when encoding is UTF-8; doing so will cause this line to fail
+      return trim_end ? data.map {|line| (line.encode UTF_8, ::Encoding::UTF_16LE).rstrip } : data.map {|line| (line.encode UTF_8, ::Encoding::UTF_16LE).chomp }
+    elsif leading_2_bytes == BOM_BYTES_UTF_16BE
+      data[0] = first.byteslice 2, first.bytesize
+      return trim_end ? data.map {|line| (line.encode UTF_8, ::Encoding::UTF_16BE).rstrip } : data.map {|line| (line.encode UTF_8, ::Encoding::UTF_16BE).chomp }
+    elsif leading_bytes == BOM_BYTES_UTF_8
+      data[0] = first.byteslice 3, first.bytesize
+    end
+    if first.encoding == UTF_8
+      trim_end ? data.map {|line| line.rstrip } : data.map {|line| line.chomp }
     else
-      # Ruby 1.8 has no built-in re-encoding, so no point in removing the UTF-16 BOMs
-      data[0] = first_line.slice 3, first_line.length if leading_bytes == BOM_BYTES_UTF_8
-      data.map {|line| line.rstrip }
+      trim_end ? data.map {|line| (line.encode UTF_8).rstrip } : data.map {|line| (line.encode UTF_8).chomp }
     end
   end
 
-  # Public: Normalize the String and split into lines to prepare them for parsing
+  # Internal: Prepare the source data String for parsing.
   #
-  # Force encodes the data to UTF-8 and removes trailing whitespace from each line.
-  # Converts the data to a String Array.
+  # Encodes the data to UTF-8, if necessary, splits it into an array, and
+  # removes any trailing whitespace from every line.
   #
-  # If a BOM is present at the beginning of the data, a best attempt
-  # is made to encode from the specified encoding to UTF-8.
+  # If a BOM is found at the beginning of the data, a best attempt is made to
+  # encode it to UTF-8 from the specified source encoding.
   #
-  # data - a String of lines to normalize
+  # data     - the source data String to prepare
+  # trim_end - whether to trim whitespace from the end of each line;
+  #            (true cleans all whitespace; false only removes trailing newline) (default: true)
   #
-  # returns a String Array of normalized lines
-  def self.normalize_lines_from_string data
+  # returns a String Array of prepared lines
+  def prepare_source_string data, trim_end = true
     return [] if data.nil_or_empty?
-
-    leading_bytes = data.unpack 'C3'
-    if COERCE_ENCODING
-      utf8 = ::Encoding::UTF_8
-      if (leading_2_bytes = leading_bytes.slice 0, 2) == BOM_BYTES_UTF_16LE
-        data = ((data.force_encoding ::Encoding::UTF_16LE).slice 1, data.length).encode utf8
-      elsif leading_2_bytes == BOM_BYTES_UTF_16BE
-        data = ((data.force_encoding ::Encoding::UTF_16BE).slice 1, data.length).encode utf8
-      elsif leading_bytes == BOM_BYTES_UTF_8
-        data = data.encoding == utf8 ? (data.slice 1, data.length) : ((data.force_encoding utf8).slice 1, data.length)
-      else
-        data = data.force_encoding utf8 unless data.encoding == utf8
-      end
+    if (leading_2_bytes = (leading_bytes = data.unpack 'C3').slice 0, 2) == BOM_BYTES_UTF_16LE
+      data = (data.byteslice 2, data.bytesize).encode UTF_8, ::Encoding::UTF_16LE
+    elsif leading_2_bytes == BOM_BYTES_UTF_16BE
+      data = (data.byteslice 2, data.bytesize).encode UTF_8, ::Encoding::UTF_16BE
+    elsif leading_bytes == BOM_BYTES_UTF_8
+      data = data.byteslice 3, data.bytesize
+      data = data.encode UTF_8 unless data.encoding == UTF_8
+    elsif data.encoding != UTF_8
+      data = data.encode UTF_8
+    end
+    if trim_end
+      [].tap {|lines| data.each_line {|line| lines << line.rstrip } }
     else
-      # Ruby 1.8 has no built-in re-encoding, so no point in removing the UTF-16 BOMs
-      data = data.slice 3, data.length if leading_bytes == BOM_BYTES_UTF_8
+      [].tap {|lines| data.each_line {|line| lines << line.chomp } }
     end
-    data.each_line.map {|line| line.rstrip }
   end
 
-  # Public: Efficiently checks whether the specified String resembles a URI
+  # Internal: Efficiently checks whether the specified String resembles a URI
   #
   # Uses the Asciidoctor::UriSniffRx regex to check whether the String begins
   # with a URI prefix (e.g., http://). No validation of the URI is performed.
@@ -129,46 +120,57 @@ module Helpers
   # str - the String to check
   #
   # returns true if the String is a URI, false if it is not
-  def self.uriish? str
+  def uriish? str
     (str.include? ':') && (UriSniffRx.match? str)
   end
 
-  # Public: Efficiently retrieves the URI prefix of the specified String
-  #
-  # Uses the Asciidoctor::UriSniffRx regex to match the URI prefix in the
-  # specified String (e.g., http://), if present.
-  #
-  # str - the String to check
-  #
-  # returns the string URI prefix if the string is a URI, otherwise nil
-  def self.uri_prefix str
-    (str.include? ':') && UriSniffRx =~ str ? $& : nil
+  # Internal: Encode a URI component String for safe inclusion in a URI.
+  #
+  # str - the URI component String to encode
+  #
+  # Returns the String with all reserved URI characters encoded (e.g., /, &, =, space, etc).
+  if RUBY_ENGINE == 'opal'
+    def encode_uri_component str
+      # patch necessary to adhere with RFC-3986 (and thus CGI.escape)
+      # see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent#Description
+      %x(
+        return encodeURIComponent(str).replace(/%20|[!'()*]/g, function (m) {
+          return m === '%20' ? '+' : '%' + m.charCodeAt(0).toString(16)
+        })
+      )
+    end
+  else
+    CGI = ::CGI
+    def encode_uri_component str
+      CGI.escape str
+    end
   end
 
-  # Matches the characters in a URI to encode
-  REGEXP_ENCODE_URI_CHARS = /[^\w\-.!~*';:@=+$,()\[\]]/
-
-  # Public: Encode a String for inclusion in a URI.
+  # Internal: Apply URI path encoding to spaces in the specified string (i.e., convert spaces to %20).
   #
-  # str - the String to URI encode
+  # str - the String to encode
   #
-  # Returns the String with all URI reserved characters encoded.
-  def self.uri_encode str
-    str.gsub(REGEXP_ENCODE_URI_CHARS) { $&.each_byte.map {|c| sprintf '%%%02X', c }.join }
+  # Returns the specified String with all spaces replaced with %20.
+  def encode_spaces_in_uri str
+    (str.include? ' ') ? (str.gsub ' ', '%20') : str
   end
 
   # Public: Removes the file extension from filename and returns the result
   #
-  # filename - The String file name to process
+  # filename - The String file name to process; expected to be a posix path
   #
   # Examples
   #
-  #   Helpers.rootname('part1/chapter1.adoc')
+  #   Helpers.rootname 'part1/chapter1.adoc'
   #   # => "part1/chapter1"
   #
   # Returns the String filename with the file extension removed
-  def self.rootname filename
-    filename.slice 0, ((filename.rindex '.') || filename.length)
+  def rootname filename
+    if (last_dot_idx = filename.rindex '.')
+      (filename.index '/', last_dot_idx) ? filename : (filename.slice 0, last_dot_idx)
+    else
+      filename
+    end
   end
 
   # Public: Retrieves the basename of the filename, optionally removing the extension, if present
@@ -179,22 +181,59 @@ module Helpers
   #
   # Examples
   #
-  #   Helpers.basename('images/tiger.png', true)
+  #   Helpers.basename 'images/tiger.png', true
   #   # => "tiger"
   #
-  #   Helpers.basename('images/tiger.png', '.png')
+  #   Helpers.basename 'images/tiger.png', '.png'
   #   # => "tiger"
   #
   # Returns the String filename with leading directories removed and, if specified, the extension removed
-  def self.basename(filename, drop_ext = nil)
+  def basename filename, drop_ext = nil
     if drop_ext
-      ::File.basename filename, (drop_ext == true ? (::File.extname filename) : drop_ext)
+      ::File.basename filename, (drop_ext == true ? (extname filename) : drop_ext)
     else
       ::File.basename filename
     end
   end
 
-  def self.mkdir_p dir
+  # Public: Returns whether this path has a file extension.
+  #
+  # path - The path String to check; expects a posix path
+  #
+  # Returns true if the path has a file extension, false otherwise
+  def extname? path
+    (last_dot_idx = path.rindex '.') && !(path.index '/', last_dot_idx)
+  end
+
+  # Public: Retrieves the file extension of the specified path. The file extension is the portion of the path in the
+  # last path segment starting from the last period.
+  #
+  # This method differs from File.extname in that it gives us control over the fallback value and is more efficient.
+  #
+  # path     - The path String in which to look for a file extension
+  # fallback - The fallback String to return if no file extension is present (optional, default: '')
+  #
+  # Returns the String file extension (with the leading dot included) or the fallback value if the path has no file extension.
+  if ::File::ALT_SEPARATOR
+    def extname path, fallback = ''
+      if (last_dot_idx = path.rindex '.')
+        (path.index '/', last_dot_idx) || (path.index ::File::ALT_SEPARATOR, last_dot_idx) ? fallback : (path.slice last_dot_idx, path.length)
+      else
+        fallback
+      end
+    end
+  else
+    def extname path, fallback = ''
+      if (last_dot_idx = path.rindex '.')
+        (path.index '/', last_dot_idx) ? fallback : (path.slice last_dot_idx, path.length)
+      else
+        fallback
+      end
+    end
+  end
+
+  # Internal: Make a directory, ensuring all parent directories exist.
+  def mkdir_p dir
     unless ::File.directory? dir
       unless (parent_dir = ::File.dirname dir) == '.'
         mkdir_p parent_dir
@@ -211,17 +250,55 @@ module Helpers
     'M' => 1000, 'CM' => 900, 'D' => 500, 'CD' => 400, 'C' => 100, 'XC' => 90,
     'L' => 50, 'XL' => 40, 'X' => 10, 'IX' => 9, 'V' => 5, 'IV' => 4, 'I' => 1
   }
+  private_constant :ROMAN_NUMERALS
 
-  # Converts an integer to a Roman numeral.
+  # Internal: Converts an integer to a Roman numeral.
   #
   # val - the [Integer] value to convert
   #
   # Returns the [String] roman numeral for this integer
-  def self.int_to_roman val
-    ROMAN_NUMERALS.map {|l, i|
+  def int_to_roman val
+    ROMAN_NUMERALS.map do |l, i|
       repeat, val = val.divmod i
       l * repeat
-    }.join
+    end.join
+  end
+
+  # Internal: Get the next value in the sequence.
+  #
+  # Handles both integer and character sequences.
+  #
+  # current - the value to increment as a String or Integer
+  #
+  # returns the next value in the sequence according to the current value's type
+  def nextval current
+    if ::Integer === current
+      current + 1
+    elsif (intval = current.to_i).to_s == current.to_s
+      intval + 1
+    else
+      current.succ
+    end
+  end
+
+  # Internal: Resolve the specified object as a Class
+  #
+  # object - The Object to resolve as a Class
+  #
+  # Returns a Class if the specified object is a Class (but not a Module) or
+  # a String that resolves to a Class; otherwise, nil
+  def resolve_class object
+    ::Class === object ? object : (::String === object ? (class_for_name object) : nil)
+  end
+
+  # Internal: Resolves a Class object (not a Module) for the qualified name.
+  #
+  # Returns Class
+  def class_for_name qualified_name
+    raise unless ::Class === (resolved = ::Object.const_get qualified_name, false)
+    resolved
+  rescue
+    raise ::NameError, %(Could not resolve class for name: #{qualified_name})
   end
 end
 end

data/lib/asciidoctor/inline.rb

@@ -1,9 +1,9 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 module Asciidoctor
 # Public: Methods for managing inline elements in AsciiDoc block
 class Inline < AbstractNode
   # Public: Get the text of this inline element
-  attr_reader :text
+  attr_accessor :text
 
   # Public: Get the type (qualifier) of this inline element
   attr_reader :type
@@ -12,19 +12,12 @@ class Inline < AbstractNode
   attr_accessor :target
 
   def initialize(parent, context, text = nil, opts = {})
-    super(parent, context)
+    super(parent, context, opts)
     @node_name = %(inline_#{context})
-
     @text = text
-
     @id = opts[:id]
     @type = opts[:type]
     @target = opts[:target]
-
-    # value of attributes option for inline nodes may be nil
-    if (attrs = opts[:attributes])
-      @attributes = attrs.dup
-    end
   end
 
   def block?
@@ -39,21 +32,25 @@ class Inline < AbstractNode
     converter.convert self
   end
 
-  # Alias render to convert to maintain backwards compatibility
+  # Deprecated: Use {Inline#convert} instead.
   alias render convert
 
   # Public: Returns the converted alt text for this inline image.
   #
   # Returns the [String] value of the alt attribute.
   def alt
-    attr 'alt'
+    (attr 'alt') || ''
   end
 
+  # For a reference node (:ref or :bibref), the text is the reftext (and the reftext attribute is not set).
+  #
   # (see AbstractNode#reftext?)
   def reftext?
     @text && (@type == :ref || @type == :bibref)
   end
 
+  # For a reference node (:ref or :bibref), the text is the reftext (and the reftext attribute is not set).
+  #
   # (see AbstractNode#reftext)
   def reftext
     (val = @text) ? (apply_reftext_subs val) : nil

data/lib/asciidoctor/list.rb

@@ -1,4 +1,4 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 module Asciidoctor
 # Public: Methods for managing AsciiDoc lists (ordered, unordered and description lists)
 class List < AbstractBlock
@@ -31,7 +31,7 @@ class List < AbstractBlock
     end
   end
 
-  # Alias render to convert to maintain backwards compatibility
+  # Deprecated: Use {List#convert} instead.
   alias render convert
 
   def to_s
@@ -41,6 +41,9 @@ class List < AbstractBlock
 end
 
 # Public: Methods for managing items for AsciiDoc olists, ulist, and dlists.
+#
+# In a description list (dlist), each item is a tuple that consists of a 2-item Array of ListItem terms and a ListItem
+# description (i.e., [[term, term, ...], desc]. If a description is not set, then the second entry in the tuple is nil.
 class ListItem < AbstractBlock
 
   # A contextual alias for the list parent node; counterpart to the items alias on List
@@ -63,7 +66,7 @@ class ListItem < AbstractBlock
   # Public: A convenience method that checks whether the text of this list item
   # is not blank (i.e., not nil or empty string).
   def text?
-    !@text.nil_or_empty?
+    @text.nil_or_empty? ? false : true
   end
 
   # Public: Get the String text of this ListItem with substitutions applied.
@@ -77,12 +80,8 @@ class ListItem < AbstractBlock
     @text && (apply_subs @text, @subs)
   end
 
-  # Public: Set the String text.
-  #
-  # Returns the new String text assigned to this ListItem
-  def text= val
-    @text = val
-  end
+  # Public: Set the String text assigned to this ListItem
+  attr_writer :text
 
   # Check whether this list item has simple content (no nested blocks aside from a single outline list).
   # Primarily relevant for outline lists.
@@ -100,33 +99,16 @@ class ListItem < AbstractBlock
     !simple?
   end
 
-  # Public: Fold the first paragraph block into the text
-  #
-  # Here are the rules for when a folding occurs:
-  #
-  # Given: this list item has at least one block
-  # When: the first block is a paragraph that's not connected by a list continuation
-  # Or: the first block is an indented paragraph that's adjacent (wrapped line)
-  # Or: the first block is an indented paragraph that's not connected by a list continuation
-  # Then: then drop the first block and fold it's content (buffer) into the list text
+  # Internal: Fold the adjacent paragraph block into the list item text
   #
   # Returns nothing
-  def fold_first(continuation_connects_first_block = false, content_adjacent = false)
-    if (first_block = @blocks[0]) && Block === first_block &&
-        ((first_block.context == :paragraph && !continuation_connects_first_block) ||
-        ((content_adjacent || !continuation_connects_first_block) && first_block.context == :literal &&
-            first_block.option?('listparagraph')))
-
-      block = blocks.shift
-      block.lines.unshift @text unless @text.nil_or_empty?
-      @text = block.source
-    end
+  def fold_first
+    @text = @text.nil_or_empty? ? @blocks.shift.source : %(#{@text}#{LF}#{@blocks.shift.source})
     nil
   end
 
   def to_s
     %(#<#{self.class}@#{object_id} {list_context: #{parent.context.inspect}, text: #{@text.inspect}, blocks: #{(@blocks || []).size}}>)
   end
-
 end
 end

data/lib/asciidoctor/load.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+module Asciidoctor
+  class << self
+    # Public: Parse the AsciiDoc source input into a {Document}
+    #
+    # Accepts input as an IO (or StringIO), String or String Array object. If the
+    # input is a File, the object is expected to be opened for reading and is not
+    # closed afterwards by this method. Information about the file (filename,
+    # directory name, etc) gets assigned to attributes on the Document object.
+    #
+    # input   - the AsciiDoc source as a IO, String or Array.
+    # options - a String, Array or Hash of options to control processing (default: {})
+    #           String and Array values are converted into a Hash.
+    #           See {Document#initialize} for details about these options.
+    #
+    # Returns the Document
+    def load input, options = {}
+      options = options.merge
+
+      if (timings = options[:timings])
+        timings.start :read
+      end
+
+      if (options.key? :logger) && (logger = options[:logger]) != LoggerManager.logger
+        LoggerManager.logger = logger || NullLogger.new
+      end
+
+      if !(attrs = options[:attributes])
+        attrs = {}
+      elsif ::Hash === attrs
+        attrs = attrs.merge
+      elsif (defined? ::Java::JavaUtil::Map) && ::Java::JavaUtil::Map === attrs
+        attrs = attrs.dup
+      elsif ::Array === attrs
+        attrs = {}.tap do |accum|
+          attrs.each do |entry|
+            k, _, v = entry.partition '='
+            accum[k] = v
+          end
+        end
+      elsif ::String === attrs
+        # condense and convert non-escaped spaces to null, unescape escaped spaces, then split on null
+        attrs = {}.tap do |accum|
+          attrs.gsub(SpaceDelimiterRx, '\1' + NULL).gsub(EscapedSpaceRx, '\1').split(NULL).each do |entry|
+            k, _, v = entry.partition '='
+            accum[k] = v
+          end
+        end
+      elsif (attrs.respond_to? :keys) && (attrs.respond_to? :[])
+        # coerce attrs to a real Hash
+        attrs = {}.tap {|accum| attrs.keys.each {|k| accum[k] = attrs[k] } }
+      else
+        raise ::ArgumentError, %(illegal type for attributes option: #{attrs.class.ancestors.join ' < '})
+      end
+
+      if ::File === input
+        # File#mtime on JRuby 9.1 for Windows doesn't honor TZ environment variable; see https://github.com/jruby/jruby/issues/6659
+        options[:input_mtime] = RUBY_ENGINE == 'jruby' ? (::Time.at input.mtime.to_i) : input.mtime
+        # NOTE defer setting infile and indir until we get a better sense of their purpose
+        # TODO cli checks if input path can be read and is file, but might want to add check to API too
+        attrs['docfile'] = input_path = ::File.absolute_path input.path
+        attrs['docdir'] = ::File.dirname input_path
+        attrs['docname'] = Helpers.basename input_path, (attrs['docfilesuffix'] = Helpers.extname input_path)
+        source = input.read
+      elsif input.respond_to? :read
+        # NOTE tty, pipes & sockets can't be rewound, but can't be sniffed easily either
+        # just fail the rewind operation silently to handle all cases
+        input.rewind rescue nil
+        source = input.read
+      elsif ::String === input
+        source = input
+      elsif ::Array === input
+        source = input.drop 0
+      elsif input
+        raise ::ArgumentError, %(unsupported input type: #{input.class})
+      end
+
+      if timings
+        timings.record :read
+        timings.start :parse
+      end
+
+      options[:attributes] = attrs
+      doc = options[:parse] == false ? (Document.new source, options) : (Document.new source, options).parse
+
+      timings.record :parse if timings
+      doc
+    rescue => e
+      begin
+        context = %(asciidoctor: FAILED: #{attrs['docfile'] || '<stdin>'}: Failed to load AsciiDoc document)
+        if e.respond_to? :exception
+          # The original message must be explicitly preserved when wrapping a Ruby exception
+          wrapped_e = e.exception %(#{context} - #{e.message})
+          # JRuby automatically sets backtrace; MRI did not until 2.6
+          wrapped_e.set_backtrace e.backtrace
+        else
+          # Likely a Java exception class
+          wrapped_e = e.class.new context, e
+          wrapped_e.stack_trace = e.stack_trace
+        end
+      rescue
+        wrapped_e = e
+      end
+      raise wrapped_e
+    end
+
+    # Public: Parse the contents of the AsciiDoc source file into an Asciidoctor::Document
+    #
+    # input   - the String AsciiDoc source filename
+    # options - a String, Array or Hash of options to control processing (default: {})
+    #           String and Array values are converted into a Hash.
+    #           See Asciidoctor::Document#initialize for details about options.
+    #
+    # Returns the Asciidoctor::Document
+    def load_file filename, options = {}
+      ::File.open(filename, FILE_READ_MODE) {|file| load file, options }
+    end
+  end
+end