asciidoctor 2.0.6 → 2.0.11

data/lib/asciidoctor/converter/template.rb

@@ -34,8 +34,8 @@ class Converter::TemplateConverter < Converter::Base
   }
 
   begin
-    require 'concurrent/hash' unless defined? ::Concurrent::Hash
-    @caches = { scans: ::Concurrent::Hash.new, templates: ::Concurrent::Hash.new }
+    require 'concurrent/map' unless defined? ::Concurrent::Map
+    @caches = { scans: ::Concurrent::Map.new, templates: ::Concurrent::Map.new }
   rescue ::LoadError
     @caches = { scans: {}, templates: {} }
   end
@@ -71,7 +71,7 @@ class Converter::TemplateConverter < Converter::Base
     end
     case opts[:template_cache]
     when true
-      logger.warn 'optional gem \'concurrent-ruby\' is not available. This gem is recommended when using the default template cache.' unless defined? ::Concurrent::Hash
+      logger.warn 'optional gem \'concurrent-ruby\' is not available. This gem is recommended when using the default template cache.' unless defined? ::Concurrent::Map
       @caches = self.class.caches
     when ::Hash
       @caches = opts[:template_cache]
@@ -257,6 +257,9 @@ class Converter::TemplateConverter < Converter::Base
     if !name || name == 'erb'
       require 'erb' unless defined? ::ERB.version
       [::Tilt::ERBTemplate, {}]
+    elsif name == 'erubi'
+      Helpers.require_library 'erubi' unless defined? ::Erubis::Engine
+      [::Tilt::ErubiTemplate, {}]
     elsif name == 'erubis'
       Helpers.require_library 'erubis' unless defined? ::Erubis::FastEruby
       [::Tilt::ErubisTemplate, { engine_class: ::Erubis::FastEruby }]

data/lib/asciidoctor/document.rb

@@ -326,13 +326,12 @@ class Document < AbstractBlock
       @sourcemap = options[:sourcemap]
       @timings = options.delete :timings
       @path_resolver = PathResolver.new
-      initialize_extensions = (defined? ::Asciidoctor::Extensions) ? true : nil
+      initialize_extensions = (defined? ::Asciidoctor::Extensions) || (options.key? :extensions) ? ::Asciidoctor::Extensions : nil
       @extensions = nil # initialize furthur down if initialize_extensions is true
       options[:standalone] = options[:header_footer] if (options.key? :header_footer) && !(options.key? :standalone)
     end
 
-    @parsed = false
-    @header = @header_attributes = nil
+    @parsed = @reftexts = @header = @header_attributes = nil
     @counters = {}
     @attributes_modified = ::Set.new
     @docinfo_processor_extensions = {}
@@ -340,51 +339,36 @@ class Document < AbstractBlock
     (@options = options).freeze
 
     attrs = @attributes
-    #attrs['encoding'] = 'UTF-8'
-    attrs['sectids'] = ''
-    attrs['toc-placement'] = 'auto'
+    attrs['attribute-undefined'] = Compliance.attribute_undefined
+    attrs['attribute-missing'] = Compliance.attribute_missing
+    attrs.update DEFAULT_ATTRIBUTES
+    # TODO if lang attribute is set, @safe mode < SafeMode::SERVER, and !parent_doc,
+    # load attributes from data/locale/attributes-<lang>.adoc
+
     if standalone
-      attrs['copycss'] = ''
       # sync embedded attribute with :standalone option value
       attr_overrides['embedded'] = nil
+      attrs['copycss'] = ''
+      attrs['iconfont-remote'] = ''
+      attrs['stylesheet'] = ''
+      attrs['webfonts'] = ''
     else
-      attrs['notitle'] = ''
       # sync embedded attribute with :standalone option value
       attr_overrides['embedded'] = ''
+      if (attr_overrides.key? 'showtitle') && (attr_overrides.keys & %w(notitle showtitle))[-1] == 'showtitle'
+        attr_overrides['notitle'] = { nil => '', false => '@', '@' => false}[attr_overrides['showtitle']]
+      elsif attr_overrides.key? 'notitle'
+        attr_overrides['showtitle'] = { nil => '', false => '@', '@' => false}[attr_overrides['notitle']]
+      else
+        attrs['notitle'] = ''
+      end
     end
-    attrs['stylesheet'] = ''
-    attrs['webfonts'] = ''
-    attrs['prewrap'] = ''
-    attrs['attribute-undefined'] = Compliance.attribute_undefined
-    attrs['attribute-missing'] = Compliance.attribute_missing
-    attrs['iconfont-remote'] = ''
-
-    # language strings
-    # TODO load these based on language settings
-    attrs['caution-caption'] = 'Caution'
-    attrs['important-caption'] = 'Important'
-    attrs['note-caption'] = 'Note'
-    attrs['tip-caption'] = 'Tip'
-    attrs['warning-caption'] = 'Warning'
-    attrs['example-caption'] = 'Example'
-    attrs['figure-caption'] = 'Figure'
-    #attrs['listing-caption'] = 'Listing'
-    attrs['table-caption'] = 'Table'
-    attrs['toc-title'] = 'Table of Contents'
-    #attrs['preface-title'] = 'Preface'
-    attrs['section-refsig'] = 'Section'
-    attrs['part-refsig'] = 'Part'
-    attrs['chapter-refsig'] = 'Chapter'
-    attrs['appendix-caption'] = attrs['appendix-refsig'] = 'Appendix'
-    attrs['untitled-label'] = 'Untitled'
-    attrs['version-label'] = 'Version'
-    attrs['last-update-label'] = 'Last updated'
 
     attr_overrides['asciidoctor'] = ''
     attr_overrides['asciidoctor-version'] = ::Asciidoctor::VERSION
 
     attr_overrides['safe-mode-name'] = (safe_mode_name = SafeMode.name_for_value @safe)
-    attr_overrides["safe-mode-#{safe_mode_name}"] = ''
+    attr_overrides[%(safe-mode-#{safe_mode_name})] = ''
     attr_overrides['safe-mode-level'] = @safe
 
     # the only way to set the max-include-depth attribute is via the API; default to 64 like AsciiDoc Python
@@ -506,10 +490,10 @@ class Document < AbstractBlock
               ::AsciidoctorJ::Extensions::ExtensionRegistry === ext_registry)
             @extensions = ext_registry.activate self
           end
-        elsif ::Proc === (ext_block = options[:extensions])
+        elsif (ext_block = options[:extensions]).nil?
+          @extensions = Extensions::Registry.new.activate self unless Extensions.groups.empty?
+        elsif ::Proc === ext_block
           @extensions = Extensions.create(&ext_block).activate self
-        elsif !Extensions.groups.empty?
-          @extensions = Extensions::Registry.new.activate self
         end
       end
 
@@ -607,24 +591,32 @@ class Document < AbstractBlock
     when :refs
       @catalog[:refs][value[0]] ||= (ref = value[1])
       ref
-    #when :footnotes, :indexterms
     when :footnotes
       @catalog[type] << value
     else
-      @catalog[type] << (type == :images ? (ImageReference.new value[0], value[1]) : value) if @options[:catalog_assets]
+      @catalog[type] << (type == :images ? (ImageReference.new value, @attributes['imagesdir']) : value) if @options[:catalog_assets]
     end
   end
 
-  # Public: Scan all registered references and return the ID of the reference that matches the specified reference text.
-  #
-  # If multiple references in the document have the same reference text, the first match in document order is used.
+  # Public: Scan registered references and return the ID of the first reference that matches the specified reference text.
   #
   # text - The String reference text to compare to the converted reference text of each registered reference.
   #
   # Returns the String ID of the first reference with matching reference text or nothing if no reference is found.
   def resolve_id text
-    ((@reftexts ||= @parsed ? {}.tap {|accum| @catalog[:refs].each {|id, ref| accum[ref.xreftext] = id } } : nil) ||
-      {}.tap {|accum| @catalog[:refs].find {|id, ref| ref.xreftext == text ? accum[text] = id : nil } })[text]
+    if @reftexts
+      @reftexts[text]
+    elsif @parsed
+      # @reftexts is set eagerly to prevent nested lazy init
+      (@reftexts = {}).tap {|accum| @catalog[:refs].each {|id, ref| accum[ref.xreftext] ||= id } }[text]
+    else
+      # @reftexts is set eagerly to prevent nested lazy init
+      resolved_id = nil
+      # NOTE short-circuit early since we're throwing away this table
+      (@reftexts = {}).tap {|accum| @catalog[:refs].each {|id, ref| (xreftext = ref.xreftext) == text ? (break (resolved_id = id)) : (accum[xreftext] ||= id) } }
+      @reftexts = nil
+      resolved_id
+    end
   end
 
   def footnotes?
@@ -765,7 +757,7 @@ class Document < AbstractBlock
   end
 
   def notitle
-    !@attributes.key?('showtitle') && @attributes.key?('notitle')
+    @attributes.key? 'notitle'
   end
 
   def noheader
@@ -1210,7 +1202,7 @@ class Document < AbstractBlock
       when '', 'font'
       else
         attrs['icons'] = ''
-        attrs['icontype'] = icons_val
+        attrs['icontype'] = icons_val unless icons_val == 'image'
       end
     end
 

data/lib/asciidoctor/extensions.rb

@@ -425,7 +425,7 @@ module Extensions
   # TIP: Postprocessors can also be used to relocate assets needed by the published
   # document.
   #
-  # Postprocessor implementations must Postprocessor.
+  # Postprocessor implementations must extend Postprocessor.
   class Postprocessor < Processor
     def process document, output
       raise ::NotImplementedError, %(#{Postprocessor} subclass #{self.class} must implement the ##{__method__} method)
@@ -610,7 +610,7 @@ module Extensions
   #--
   # TODO break this out into different pattern types
   # for example, FullInlineMacro, ShortInlineMacro (no target) and other patterns
-  # FIXME for inline passthrough, we need to have some way to specify the text as a passthrough
+  # FIXME for inline macro, we need to have some way to specify the text as a passthrough
   class InlineMacroProcessor < MacroProcessor
     @@rx_cache = {}
 
@@ -622,7 +622,7 @@ module Extensions
 
     def resolve_regexp name, format
       raise ::ArgumentError, %(invalid name for inline macro: #{name}) unless MacroNameRx.match? name
-      @@rx_cache[[name, format]] ||= /\\?#{name}:#{format == :short ? '(){0}' : '(\S+?)'}\[(|.*?[^\\])\]/
+      @@rx_cache[[name, format]] ||= /\\?#{name}:#{format == :short ? '(){0}' : '(\S+?)'}\[(|#{CC_ANY}*?[^\\])\]/
     end
   end
 

data/lib/asciidoctor/helpers.rb

@@ -2,7 +2,9 @@
 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
@@ -21,7 +23,7 @@ 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
     include Logging unless include? Logging
@@ -54,25 +56,27 @@ module Helpers
   # 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)
+  # 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 self.prepare_source_array data
+  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 data.map {|line| (line.encode UTF_8, ::Encoding::UTF_16LE).rstrip }
+      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 data.map {|line| (line.encode UTF_8, ::Encoding::UTF_16BE).rstrip }
+      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
-      data.map {|line| line.rstrip }
+      trim_end ? data.map {|line| line.rstrip } : data.map {|line| line.chomp }
     else
-      data.map {|line| (line.encode UTF_8).rstrip }
+      trim_end ? data.map {|line| (line.encode UTF_8).rstrip } : data.map {|line| (line.encode UTF_8).chomp }
     end
   end
 
@@ -84,10 +88,12 @@ module Helpers
   # 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 String to prepare
+  # 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 prepared lines
-  def self.prepare_source_string data
+  def prepare_source_string data, trim_end = true
     return [] if data.nil_or_empty?
     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
@@ -99,7 +105,11 @@ module Helpers
     elsif data.encoding != UTF_8
       data = data.encode UTF_8
     end
-    [].tap {|lines| data.each_line {|line| lines << line.rstrip } }
+    if trim_end
+      [].tap {|lines| data.each_line {|line| lines << line.rstrip } }
+    else
+      [].tap {|lines| data.each_line {|line| lines << line.chomp } }
+    end
   end
 
   # Internal: Efficiently checks whether the specified String resembles a URI
@@ -110,29 +120,17 @@ 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
 
-  # Internal: 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
-  end
-
   # 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 self.encode_uri_component str
+    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(
@@ -143,17 +141,17 @@ module Helpers
     end
   else
     CGI = ::CGI
-    def self.encode_uri_component str
+    def encode_uri_component str
       CGI.escape str
     end
   end
 
-  # Internal: Encode a URI String (namely the path portion).
+  # Internal: Apply URI path encoding to spaces in the specified string (i.e., convert spaces to %20).
   #
   # str - the String to encode
   #
-  # Returns the String with all spaces replaced with %20.
-  def self.encode_uri str
+  # Returns the specified String with all spaces replaced with %20.
+  def encode_spaces_in_uri str
     (str.include? ' ') ? (str.gsub ' ', '%20') : str
   end
 
@@ -167,7 +165,7 @@ module Helpers
   #   # => "part1/chapter1"
   #
   # Returns the String filename with the file extension removed
-  def self.rootname filename
+  def rootname filename
     if (last_dot_idx = filename.rindex '.')
       (filename.index '/', last_dot_idx) ? filename : (filename.slice 0, last_dot_idx)
     else
@@ -190,7 +188,7 @@ module Helpers
   #   # => "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 ? (extname filename) : drop_ext)
     else
@@ -203,7 +201,7 @@ module Helpers
   # path - The path String to check; expects a posix path
   #
   # Returns true if the path has a file extension, false otherwise
-  def self.extname? path
+  def extname? path
     (last_dot_idx = path.rindex '.') && !(path.index '/', last_dot_idx)
   end
 
@@ -217,7 +215,7 @@ module Helpers
   #
   # 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 self.extname path, fallback = ''
+    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
@@ -225,7 +223,7 @@ module Helpers
       end
     end
   else
-    def self.extname path, fallback = ''
+    def extname path, fallback = ''
       if (last_dot_idx = path.rindex '.')
         (path.index '/', last_dot_idx) ? fallback : (path.slice last_dot_idx, path.length)
       else
@@ -235,7 +233,7 @@ module Helpers
   end
 
   # Internal: Make a directory, ensuring all parent directories exist.
-  def self.mkdir_p dir
+  def mkdir_p dir
     unless ::File.directory? dir
       unless (parent_dir = ::File.dirname dir) == '.'
         mkdir_p parent_dir
@@ -252,13 +250,14 @@ 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
 
   # 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
+  def int_to_roman val
     ROMAN_NUMERALS.map do |l, i|
       repeat, val = val.divmod i
       l * repeat
@@ -272,7 +271,7 @@ module Helpers
   # 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 self.nextval current
+  def nextval current
     if ::Integer === current
       current + 1
     else
@@ -291,14 +290,14 @@ module Helpers
   #
   # 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 self.resolve_class object
+  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 self.class_for_name qualified_name
+  def class_for_name qualified_name
     raise unless ::Class === (resolved = ::Object.const_get qualified_name, false)
     resolved
   rescue

data/lib/asciidoctor/inline.rb

@@ -39,7 +39,7 @@ class Inline < AbstractNode
   #
   # 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).

data/lib/asciidoctor/load.rb

@@ -0,0 +1,117 @@
+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 (logger = options[:logger]) && logger != LoggerManager.logger
+        LoggerManager.logger = logger
+      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
+        options[:input_mtime] = 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 => ex
+      begin
+        context = %(asciidoctor: FAILED: #{attrs['docfile'] || '<stdin>'}: Failed to load AsciiDoc document)
+        if ex.respond_to? :exception
+          # The original message must be explicitly preserved when wrapping a Ruby exception
+          wrapped_ex = ex.exception %(#{context} - #{ex.message})
+          # JRuby automatically sets backtrace; MRI did not until 2.6
+          wrapped_ex.set_backtrace ex.backtrace
+        else
+          # Likely a Java exception class
+          wrapped_ex = ex.class.new context, ex
+          wrapped_ex.stack_trace = ex.stack_trace
+        end
+      rescue
+        wrapped_ex = ex
+      end
+      raise wrapped_ex
+    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