asciidoctor 1.5.8 → 2.0.0.rc.1

data/lib/asciidoctor/extensions.rb

@@ -1,7 +1,6 @@
-# NOTE .to_s hides require from Opal
-require 'asciidoctor'.to_s unless defined? Asciidoctor
+# frozen_string_literal: true
+(require 'asciidoctor' unless defined? Asciidoctor.load) unless RUBY_ENGINE == 'opal'
 
-# encoding: UTF-8
 module Asciidoctor
 # Extensions provide a way to participate in the parsing and converting
 # phases of the AsciiDoc processor or extend the AsciiDoc syntax.
@@ -57,27 +56,23 @@ module Extensions
         config[key] = default_value
       end
 
-      # Include the DSL class for this processor into this processor class or instance.
+      # Mixes the DSL class for this processor into this processor class or instance.
       #
-      # This method automatically detects whether to use the include or extend keyword
-      # based on what is appropriate.
+      # This method automatically detects whether to use the include or extend keyword to mix in the module.
       #
       # NOTE Inspiration for this DSL design comes from https://corcoran.io/2013/09/04/simple-pattern-ruby-dsl/
       #
-      # Returns nothing
-      def use_dsl
-        if self.name.nil_or_empty?
-          # NOTE contants(false) doesn't exist in Ruby 1.8.7
-          #include const_get :DSL if constants(false).grep :DSL
-          include const_get :DSL if constants.grep :DSL
-        else
-          # NOTE contants(false) doesn't exist in Ruby 1.8.7
-          #extend const_get :DSL if constants(false).grep :DSL
-          extend const_get :DSL if constants.grep :DSL
+      # Returns self
+      def enable_dsl
+        if const_defined? :DSL
+          if singleton_class?
+            include const_get :DSL
+          else
+            extend const_get :DSL
+          end
         end
       end
-      alias extend_dsl use_dsl
-      alias include_dsl use_dsl
+      alias use_dsl enable_dsl
     end
 
     # Public: Get the configuration Hash for this processor instance.
@@ -92,7 +87,7 @@ module Extensions
     end
 
     def process *args
-      raise ::NotImplementedError, %(Asciidoctor::Extensions::Processor subclass must implement ##{__method__} method)
+      raise ::NotImplementedError, %(#{Processor} subclass #{self.class} must implement the ##{__method__} method)
     end
 
     # QUESTION should attributes be an option instead of a parameter?
@@ -156,7 +151,7 @@ module Extensions
     end
 
     def create_block parent, context, source, attrs, opts = {}
-      Block.new parent, context, { :source => source, :attributes => attrs }.merge(opts)
+      Block.new parent, context, { source: source, attributes: attrs }.merge(opts)
     end
 
     # Public: Creates a list node and links it to the specified parent.
@@ -250,20 +245,20 @@ module Extensions
     def process *args, &block
       if block_given?
         raise ::ArgumentError, %(wrong number of arguments (given #{args.size}, expected 0)) unless args.empty?
+        unless block.binding && self == block.binding.receiver
+          # NOTE remap self in process method to processor instance
+          context = self
+          block.define_singleton_method(:call) {|*m_args| context.instance_exec(*m_args, &block) }
+        end
         @process_block = block
       # TODO enable if we want to support passing proc or lambda as argument instead of block
       #elsif ::Proc === args[0]
-      #  block = args.shift
-      #  raise ::ArgumentError, %(wrong number of arguments (given #{args.size}, expected 0)) unless args.empty?
-      #  @process_block = block
+      #  raise ::ArgumentError, %(wrong number of arguments (given #{args.size - 1}, expected 0)) unless args.size == 1
+      #  @process_block = args.shift
       elsif defined? @process_block
-        # NOTE Proc automatically expands a single array argument
-        # ...but lambda doesn't (and we want to accept lambdas too)
-        # TODO need a test for this!
         @process_block.call(*args)
       else
-        # TODO add exception message here
-        raise ::NotImplementedError
+        raise ::NotImplementedError, %(#{self.class} ##{__method__} method called before being registered)
       end
     end
 
@@ -291,28 +286,25 @@ module Extensions
         option :name, value
       end
     end
-    # NOTE match_name may get deprecated
-    alias match_name named
 
     def content_model value
       option :content_model, value
     end
     alias parse_content_as content_model
-    alias parses_content_as content_model
-    #alias parse_as content_model
-    #alias parsed_as content_model
 
-    def positional_attrs *value
+    def positional_attributes *value
       option :pos_attrs, value.flatten
     end
-    alias name_attributes positional_attrs
-    alias name_positional_attributes positional_attrs
+    alias name_positional_attributes positional_attributes
+    # NOTE positional_attrs alias is deprecated
+    alias positional_attrs positional_attributes
 
     def default_attrs value
       option :default_attrs, value
     end
+    alias default_attributes default_attrs
 
-    def resolves_attributes *args
+    def resolve_attributes *args
       # NOTE assume true as default value; rewrap single-argument string or symbol
       if (args = args.fetch 0, true).respond_to? :to_sym
         args = [args]
@@ -325,15 +317,15 @@ module Extensions
         names, defaults = [], {}
         args.each do |arg|
           if (arg = arg.to_s).include? '='
-            name, value = arg.split '=', 2
+            name, _, value = arg.partition '='
             if name.include? ':'
-              idx, name = name.split ':', 2
+              idx, _, name = name.partition ':'
               idx = idx == '@' ? names.size : idx.to_i
               names[idx] = name
             end
             defaults[name] = value
           elsif arg.include? ':'
-            idx, name = arg.split ':', 2
+            idx, _, name = arg.partition ':'
             idx = idx == '@' ? names.size : idx.to_i
             names[idx] = name
           else
@@ -346,7 +338,7 @@ module Extensions
         names, defaults = [], {}
         args.each do |key, val|
           if (name = key.to_s).include? ':'
-            idx, name = name.split ':', 2
+            idx, _, name = name.partition ':'
             idx = idx == '@' ? names.size : idx.to_i
             names[idx] = name
           end
@@ -358,8 +350,8 @@ module Extensions
         raise ::ArgumentError, %(unsupported attributes specification for macro: #{args.inspect})
       end
     end
-    # NOTE we may decide to drop this alias
-    alias resolve_attributes resolves_attributes
+    # NOTE resolves_attributes alias is deprecated
+    alias resolves_attributes resolve_attributes
   end
 
   # Public: Preprocessors are run after the source text is split into lines and
@@ -377,7 +369,7 @@ module Extensions
   # Preprocessor implementations must extend the Preprocessor class.
   class Preprocessor < Processor
     def process document, reader
-      raise ::NotImplementedError, %(Asciidoctor::Extensions::Preprocessor subclass must implement ##{__method__} method)
+      raise ::NotImplementedError, %(#{Preprocessor} subclass #{self.class} must implement the ##{__method__} method)
     end
   end
   Preprocessor::DSL = DocumentProcessorDsl
@@ -394,7 +386,7 @@ module Extensions
   # QUESTION should the tree processor get invoked after parse header too?
   class TreeProcessor < Processor
     def process document
-      raise ::NotImplementedError, %(Asciidoctor::Extensions::TreeProcessor subclass must implement ##{__method__} method)
+      raise ::NotImplementedError, %(#{TreeProcessor} subclass #{self.class} must implement the ##{__method__} method)
     end
   end
   TreeProcessor::DSL = DocumentProcessorDsl
@@ -419,7 +411,7 @@ module Extensions
   # Postprocessor implementations must Postprocessor.
   class Postprocessor < Processor
     def process document, output
-      raise ::NotImplementedError, %(Asciidoctor::Extensions::Postprocessor subclass must implement ##{__method__} method)
+      raise ::NotImplementedError, %(#{Postprocessor} subclass #{self.class} must implement the ##{__method__} method)
     end
   end
   Postprocessor::DSL = DocumentProcessorDsl
@@ -437,7 +429,7 @@ module Extensions
   # TODO add file extension or regexp as shortcut for handles? method
   class IncludeProcessor < Processor
     def process document, reader, target, attributes
-      raise ::NotImplementedError, %(Asciidoctor::Extensions::IncludeProcessor subclass must implement ##{__method__} method)
+      raise ::NotImplementedError, %(#{IncludeProcessor} subclass #{self.class} must implement the ##{__method__} method)
     end
 
     def handles? target
@@ -483,7 +475,7 @@ module Extensions
     end
 
     def process document
-      raise ::NotImplementedError, %(Asciidoctor::Extensions::DocinfoProcessor subclass must implement ##{__method__} method)
+      raise ::NotImplementedError, %(#{DocinfoProcessor} subclass #{self.class} must implement the ##{__method__} method)
     end
   end
 
@@ -539,7 +531,7 @@ module Extensions
     end
 
     def process parent, reader, attributes
-      raise ::NotImplementedError, %(Asciidoctor::Extensions::BlockProcessor subclass must implement ##{__method__} method)
+      raise ::NotImplementedError, %(#{BlockProcessor} subclass #{self.class} must implement the ##{__method__} method)
     end
   end
 
@@ -551,7 +543,7 @@ module Extensions
     end
     alias on_contexts contexts
     alias on_context contexts
-    alias bound_to contexts
+    alias bind_to contexts
   end
   BlockProcessor::DSL = BlockProcessorDsl
 
@@ -565,14 +557,14 @@ module Extensions
     end
 
     def process parent, target, attributes
-      raise ::NotImplementedError, %(Asciidoctor::Extensions::MacroProcessor subclass must implement ##{__method__} method)
+      raise ::NotImplementedError, %(#{MacroProcessor} subclass #{self.class} must implement the ##{__method__} method)
     end
   end
 
   module MacroProcessorDsl
     include SyntaxProcessorDsl
 
-    def resolves_attributes *args
+    def resolve_attributes *args
       if args.size == 1 && !args[0]
         option :content_model, :text
         return
@@ -580,8 +572,8 @@ module Extensions
       super
       option :content_model, :attributes
     end
-    # NOTE we may decide to drop this alias
-    alias resolve_attributes resolves_attributes
+    # NOTE resolves_attributes alias is deprecated
+    alias resolves_attributes resolve_attributes
   end
 
   # Public: BlockMacroProcessors are used to handle block macros that have a
@@ -622,16 +614,16 @@ module Extensions
   module InlineMacroProcessorDsl
     include MacroProcessorDsl
 
-    def with_format value
+    def format value
       option :format, value
     end
-    alias using_format with_format
+    alias match_format format
+    # NOTE using_format alias is deprecated
+    alias using_format format
 
-    def matches value
+    def match value
       option :regexp, value
     end
-    alias match matches
-    alias matching matches
   end
   InlineMacroProcessor::DSL = InlineMacroProcessorDsl
 
@@ -965,7 +957,7 @@ module Extensions
     #   docinfo_processor MetaRobotsDocinfoProcessor
     #
     #   # as an instance of a DocinfoProcessor subclass with an explicit location
-    #   docinfo_processor JQueryDocinfoProcessor.new, :location => :footer
+    #   docinfo_processor JQueryDocinfoProcessor.new, location: :footer
     #
     #   # as a name of a DocinfoProcessor subclass
     #   docinfo_processor 'MetaRobotsDocinfoProcessor'
@@ -1319,30 +1311,27 @@ module Extensions
     def add_document_processor kind, args, &block
       kind_name = kind.to_s.tr '_', ' '
       kind_class_symbol = kind_name.split.map {|it| it.capitalize }.join.to_sym
-      kind_class = Extensions.const_get kind_class_symbol
-      kind_java_class = (defined? ::AsciidoctorJ) ? (::AsciidoctorJ::Extensions.const_get kind_class_symbol) : nil
+      kind_class = Extensions.const_get kind_class_symbol, false
+      kind_java_class = (defined? ::AsciidoctorJ) ? (::AsciidoctorJ::Extensions.const_get kind_class_symbol, false) : nil
       kind_store = instance_variable_get(%(@#{kind}_extensions).to_sym) || instance_variable_set(%(@#{kind}_extensions).to_sym, [])
       # style 1: specified as block
       extension = if block_given?
         config = resolve_args args, 1
-        # TODO if block arity is 0, assume block is process method
-        processor = kind_class.new config
-        # NOTE class << processor idiom doesn't work in Opal
-        #class << processor
-        #  include_dsl
-        #end
-        # NOTE kind_class.contants(false) doesn't exist in Ruby 1.8.7
-        processor.extend kind_class.const_get :DSL if kind_class.constants.grep :DSL
-        processor.instance_exec(&block)
-        processor.freeze
+        (processor = kind_class.new config).singleton_class.enable_dsl
+        if block.arity == 0
+          processor.instance_exec(&block)
+        else
+          yield processor
+        end
         unless processor.process_block_given?
           raise ::ArgumentError, %(No block specified to process #{kind_name} extension at #{block.source_location})
         end
+        processor.freeze
         ProcessorExtension.new kind, processor
       else
         processor, config = resolve_args args, 2
         # style 2: specified as Class or String class name
-        if (processor_class = Extensions.resolve_class processor)
+        if (processor_class = Helpers.resolve_class processor)
           unless processor_class < kind_class || (kind_java_class && processor_class < kind_java_class)
             raise ::ArgumentError, %(Invalid type for #{kind_name} extension: #{processor})
           end
@@ -1365,24 +1354,18 @@ module Extensions
 
     def add_syntax_processor kind, args, &block
       kind_name = kind.to_s.tr '_', ' '
-      kind_class_symbol = (kind_name.split.map {|it| it.capitalize }.push 'Processor').join.to_sym
-      kind_class = Extensions.const_get kind_class_symbol
-      kind_java_class = (defined? ::AsciidoctorJ) ? (::AsciidoctorJ::Extensions.const_get kind_class_symbol) : nil
+      kind_class_symbol = (kind_name.split.map {|it| it.capitalize } << 'Processor').join.to_sym
+      kind_class = Extensions.const_get kind_class_symbol, false
+      kind_java_class = (defined? ::AsciidoctorJ) ? (::AsciidoctorJ::Extensions.const_get kind_class_symbol, false) : nil
       kind_store = instance_variable_get(%(@#{kind}_extensions).to_sym) || instance_variable_set(%(@#{kind}_extensions).to_sym, {})
       # style 1: specified as block
       if block_given?
         name, config = resolve_args args, 2
-        processor = kind_class.new as_symbol(name), config
-        # NOTE class << processor idiom doesn't work in Opal
-        #class << processor
-        #  include_dsl
-        #end
-        # NOTE kind_class.contants(false) doesn't exist in Ruby 1.8.7
-        processor.extend kind_class.const_get :DSL if kind_class.constants.grep :DSL
-        if block.arity == 1
-          yield processor
-        else
+        (processor = kind_class.new (as_symbol name), config).singleton_class.enable_dsl
+        if block.arity == 0
           processor.instance_exec(&block)
+        else
+          yield processor
         end
         unless (name = as_symbol processor.name)
           raise ::ArgumentError, %(No name specified for #{kind_name} extension at #{block.source_location})
@@ -1395,7 +1378,7 @@ module Extensions
       else
         processor, name, config = resolve_args args, 3
         # style 2: specified as Class or String class name
-        if (processor_class = Extensions.resolve_class processor)
+        if (processor_class = Helpers.resolve_class processor)
           unless processor_class < kind_class || (kind_java_class && processor_class < kind_java_class)
             raise ::ArgumentError, %(Class specified for #{kind_name} extension does not inherit from #{kind_class}: #{processor})
           end
@@ -1453,13 +1436,11 @@ module Extensions
 
     def create name = nil, &block
       if block_given?
-        Registry.new({ (name || generate_name) => block })
+        Registry.new (name || generate_name) => block
       else
         Registry.new
       end
     end
-    # Deprecated: Use create instead of build_registry
-    alias build_registry create
 
     # Public: Registers an extension Group that subsequently registers a
     # collection of extensions.
@@ -1501,7 +1482,7 @@ module Extensions
         resolved_group = block
       elsif (group = args.pop)
         # QUESTION should we instantiate the group class here or defer until activation??
-        resolved_group = (resolve_class group) || group
+        resolved_group = (Helpers.resolve_class group) || group
       else
         raise ::ArgumentError, %(Extension group to register not specified)
       end
@@ -1529,55 +1510,6 @@ module Extensions
       names.each {|group| @groups.delete group.to_sym }
       nil
     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
-      case object
-      when ::Class
-        object
-      when ::String
-        class_for_name object
-      end
-    end
-
-    # Public: Resolves the Class object for the qualified name.
-    #
-    # Returns Class
-    if ::RUBY_MIN_VERSION_2
-      def class_for_name qualified_name
-        resolved = ::Object.const_get qualified_name, false
-        raise unless ::Class === resolved
-        resolved
-      rescue
-        raise ::NameError, %(Could not resolve class for name: #{qualified_name})
-      end
-    elsif ::RUBY_MIN_VERSION_1_9
-      def class_for_name qualified_name
-        resolved = (qualified_name.split '::').reduce ::Object do |current, name|
-          name.empty? ? current : (current.const_get name, false)
-        end
-        raise unless ::Class === resolved
-        resolved
-      rescue
-        raise ::NameError, %(Could not resolve class for name: #{qualified_name})
-      end
-    else
-      def class_for_name qualified_name
-        resolved = (qualified_name.split '::').reduce ::Object do |current, name|
-          # NOTE on Ruby 1.8, const_defined? only checks for constant in current scope
-          name.empty? ? current : ((current.const_defined? name) ? (current.const_get name) : raise)
-        end
-        raise unless ::Class === resolved
-        resolved
-      rescue
-        raise ::NameError, %(Could not resolve class for name: #{qualified_name})
-      end
-    end
   end
 end
 end

data/lib/asciidoctor/helpers.rb

@@ -1,5 +1,6 @@
-# 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.
   #
@@ -43,85 +44,63 @@ module Helpers
     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 }
-    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
+  # 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)
+  #
+  # returns a String Array of prepared lines
+  def self.prepare_source_array data
+    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 }
+    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 }
+    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 }
+    else
+      data.map {|line| (line.encode UTF_8).rstrip }
     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
   #
-  # returns a String Array of normalized lines
-  def self.normalize_lines_from_string data
+  # returns a String Array of prepared lines
+  def self.prepare_source_string data
     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
-    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
+    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
-    data.each_line.map {|line| line.rstrip }
+    [].tap {|lines| data.each_line {|line| lines << 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.
@@ -133,7 +112,7 @@ module Helpers
     (str.include? ':') && (UriSniffRx.match? str)
   end
 
-  # Public: Efficiently retrieves the URI prefix of the specified String
+  # 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.
@@ -145,16 +124,35 @@ module Helpers
     (str.include? ':') && UriSniffRx =~ str ? $& : nil
   end
 
-  # Matches the characters in a URI to encode
-  REGEXP_ENCODE_URI_CHARS = /[^\w\-.!~*';:@=+$,()\[\]]/
+  # 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
+      # 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 self.encode_uri_component str
+      CGI.escape str
+    end
+  end
 
-  # Public: Encode a String for inclusion in a URI.
+  # Internal: Encode a URI String (namely the path portion).
   #
-  # 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 String with all spaces replaced with %20.
+  def self.encode_uri str
+    (str.include? ' ') ? (str.gsub ' ', '%20') : str
   end
 
   # Public: Removes the file extension from filename and returns the result
@@ -163,7 +161,7 @@ module Helpers
   #
   # Examples
   #
-  #   Helpers.rootname('part1/chapter1.adoc')
+  #   Helpers.rootname 'part1/chapter1.adoc'
   #   # => "part1/chapter1"
   #
   # Returns the String filename with the file extension removed
@@ -179,14 +177,14 @@ 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 self.basename filename, drop_ext = nil
     if drop_ext
       ::File.basename filename, (drop_ext == true ? (::File.extname filename) : drop_ext)
     else
@@ -194,6 +192,7 @@ module Helpers
     end
   end
 
+  # Internal: Make a directory, ensuring all parent directories exist.
   def self.mkdir_p dir
     unless ::File.directory? dir
       unless (parent_dir = ::File.dirname dir) == '.'
@@ -212,16 +211,56 @@ module Helpers
     'L' => 50, 'XL' => 40, 'X' => 10, 'IX' => 9, 'V' => 5, 'IV' => 4, 'I' => 1
   }
 
-  # 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|
+    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 self.nextval current
+    if ::Integer === current
+      current + 1
+    else
+      intval = current.to_i
+      if intval.to_s != current.to_s
+        (current[0].ord + 1).chr
+      else
+        intval + 1
+      end
+    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 self.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
+    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