asciidoctor 1.5.8 → 2.0.0.rc.1

data/lib/asciidoctor/syntax_highlighter.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+module Asciidoctor
+# Public: A pluggable adapter for integrating a syntax (aka code) highlighter into AsciiDoc processing.
+#
+# There are two types of syntax highlighter adapters. The first performs syntax highlighting during the convert phase.
+# This adapter type must define a highlight? method that returns true. The companion highlight method will then be
+# called to handle the :specialcharacters substitution for source blocks. The second assumes syntax highlighting is
+# performed on the client (e.g., when the HTML document is loaded). This adapter type must define a docinfo? method
+# that returns true. The companion docinfo method will then be called to insert markup into the output document. The
+# docinfo functionality is available to both adapter types.
+#
+# Asciidoctor provides several built-in adapters, including coderay, pygments, rouge, highlight.js, html-pipeline, and
+# prettify. Additional adapters can be registered using SyntaxHighlighter.register or by supplying a custom factory.
+module SyntaxHighlighter
+  # Public: Returns the String name of this syntax highlighter for referencing it in messages and option names.
+  attr_reader :name
+
+  def initialize name, backend = 'html5', opts = {}
+    @name = @pre_class = name
+  end
+
+  # Public: Indicates whether this syntax highlighter has docinfo (i.e., markup) to insert into the output document at
+  # the specified location.
+  #
+  # location - The Symbol representing the location slot (:head or :footer).
+  #
+  # Returns a [Boolean] indicating whether the docinfo method should be called for this location.
+  def docinfo? location; end
+
+  # Public: Generates docinfo markup to insert in the output document at the specified location.
+  #
+  # location - The Symbol representing the location slot (:head or :footer).
+  #
+  # Return the [String] markup to insert.
+  def docinfo location
+    raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method since #docinfo? returns true)
+  end
+
+  # Public: Indicates whether highlighting is handled by this syntax highlighter or by the client.
+  #
+  # Returns a [Boolean] indicating whether the highlight method should be used to handle the :specialchars substitution.
+  def highlight?; end
+
+  # Public: Highlights the specified source when this source block is being converted.
+  #
+  # If the source contains callout marks, the caller assumes the source remains on the same lines and no closing tags
+  # are added to the end of each line. If the source gets shifted by one or more lines, this method must return a
+  # tuple containing the highlighted source and the number of lines by which the source was shifted.
+  #
+  # node   - The source Block to syntax highlight.
+  # source - The raw source text String of this source block (after preprocessing).
+  # lang   - The source language String specified on this block (e.g., ruby).
+  # opts   - A Hash of options that configure the syntax highlighting:
+  #          :callouts - A Hash of callouts extracted from the source, indexed by line number (1-based) (optional).
+  #          :css_mode - The Symbol CSS mode (:class or :inline).
+  #          :highlight_lines - A 1-based Array of Integer line numbers to highlight (aka emphasize) (optional).
+  #          :number_lines - A Symbol indicating whether lines should be numbered (:table or :inline) (optional).
+  #          :start_line_number - The starting Integer (1-based) line number (optional, default: 1).
+  #          :style - The String style (aka theme) to use for colorizing the code (optional).
+  #
+  # Returns the highlighted source String or a tuple of the highlighted source String and an Integer line offset.
+  def highlight node, source, lang, opts
+    raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method since #highlight? returns true)
+  end
+
+  # Public: Format the highlighted source for inclusion in an HTML document.
+  #
+  # node   - The source Block being processed.
+  # lang   - The source language String for this Block (e.g., ruby).
+  # opts   - A Hash of options that control syntax highlighting:
+  #          :nowrap - A Boolean that indicates whether wrapping should be disabled (optional).
+  #
+  # Returns the highlighted source [String] wrapped in preformatted tags (e.g., pre and code)
+  def format node, lang, opts
+    raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method)
+  end
+
+  # Public: Indicates whether this syntax highlighter wants to write a stylesheet to disk. Only called if both the
+  # linkcss and copycss attributes are set on the document.
+  #
+  # doc - The Document in which this syntax highlighter is being used.
+  #
+  # Returns a [Boolean] indicating whether the write_stylesheet method should be called.
+  def write_stylesheet? doc; end
+
+  # Public: Writes the stylesheet to support the highlighted source(s) to disk.
+  #
+  # doc    - The Document in which this syntax highlighter is being used.
+  # to_dir - The absolute String path of the stylesheet output directory.
+  #
+  # Returns nothing.
+  def write_stylesheet doc, to_dir
+    raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method since #write_stylesheet? returns true)
+  end
+
+  private_class_method def self.included into
+    into.extend Config
+  end
+
+  module Config
+    # Public: Statically register the current class in the registry for the specified names.
+    #
+    # Returns nothing.
+    private def register_for *names
+      SyntaxHighlighter.register self, *names
+    end
+  end
+
+  module Factory
+    # Public: Associates the syntax highlighter class or object with the specified names.
+    #
+    # Returns nothing.
+    def register syntax_highlighter, *names
+      names.each {|name| registry[name] = syntax_highlighter }
+    end
+
+    # Public: Retrieves the syntax highlighter class or object registered for the specified name.
+    #
+    # name - The String name of the syntax highlighter to retrieve.
+    #
+    # Returns the SyntaxHighlighter Class or Object instance registered for this name.
+    def for name
+      registry[name]
+    end
+
+    # Public: Resolves the name to a syntax highlighter instance, if found in the registry.
+    #
+    # name    - The String name of the syntax highlighter to create.
+    # backend - The String name of the backend for which this syntax highlighter is being used (default: 'html5').
+    # opts    - A Hash of options providing information about the context in which this syntax highlighter is used:
+    #           :doc - The Document for which this syntax highlighter was created.
+    #
+    # Returns a [SyntaxHighlighter] instance for the specified name.
+    def create name, backend = 'html5', opts = {}
+      if (syntax_hl = self.for name)
+        syntax_hl = syntax_hl.new name, backend, opts if ::Class === syntax_hl
+        raise ::NameError, %(#{syntax_hl.class} must specify a value for `name') unless syntax_hl.name
+        syntax_hl
+      end
+    end
+
+    private def registry
+      raise ::NotImplementedError, %(#{Factory} subclass #{self.class} must implement the ##{__method__} method)
+    end
+  end
+
+  class CustomFactory
+    include Factory
+
+    def initialize seed_registry = nil
+      @registry = seed_registry || {}
+    end
+
+    private def registry
+      @registry
+    end
+  end
+
+  module DefaultFactory
+    include Factory
+
+    private
+
+    @@registry = {}
+
+    def registry
+      @@registry
+    end
+
+    unless RUBY_ENGINE == 'opal'
+      public
+
+      def register syntax_highlighter, *names
+        @@mutex.owned? ? names.each {|name| @@registry = @@registry.merge name => syntax_highlighter } :
+            @@mutex.synchronize { register syntax_highlighter, *names }
+      end
+
+      # This method will lazy require and register additional built-in implementations, which include coderay,
+      # pygments, rouge, and prettify. Refer to {Factory#for} for parameters and return value.
+      def for name
+        @@registry.fetch name do
+          @@mutex.synchronize do
+            @@registry.fetch name do
+              if (require_path = PROVIDED[name])
+                require require_path
+                @@registry[name]
+              else
+                @@registry = @@registry.merge name => nil
+                nil
+              end
+            end
+          end
+        end
+      end
+
+      PROVIDED = {
+        'coderay' => %(#{__dir__}/syntax_highlighter/coderay),
+        'prettify' => %(#{__dir__}/syntax_highlighter/prettify),
+        'pygments' => %(#{__dir__}/syntax_highlighter/pygments),
+        'rouge' => %(#{__dir__}/syntax_highlighter/rouge),
+      }
+
+      private
+
+      @@mutex = ::Mutex.new
+    end
+  end
+
+  class DefaultFactoryProxy < CustomFactory
+    include DefaultFactory # inserts module into ancestors immediately after superclass
+
+    def for name
+      @registry.fetch(name) { super }
+    end unless RUBY_ENGINE == 'opal'
+  end
+
+  class Base
+    include SyntaxHighlighter
+
+    def format node, lang, opts
+      class_attr_val = opts[:nowrap] ? %(#{@pre_class} highlight nowrap) : %(#{@pre_class} highlight)
+      if (transform = opts[:transform])
+        pre = { 'class' => class_attr_val }
+        code = lang ? { 'data-lang' => lang } : {}
+        transform[pre, code]
+        %(<pre#{pre.map {|k, v| %[ #{k}="#{v}"] }.join}><code#{code.map {|k, v| %[ #{k}="#{v}"] }.join}>#{node.content}</code></pre>)
+      else
+        %(<pre class="#{class_attr_val}"><code#{lang ? %[ data-lang="#{lang}"] : ''}>#{node.content}</code></pre>)
+      end
+    end
+  end
+
+  extend DefaultFactory # exports static methods
+end
+end
+
+require_relative 'syntax_highlighter/highlightjs'
+require_relative 'syntax_highlighter/html_pipeline' unless RUBY_ENGINE == 'opal'

data/lib/asciidoctor/syntax_highlighter/coderay.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+module Asciidoctor
+class SyntaxHighlighter::CodeRayAdapter < SyntaxHighlighter::Base
+  register_for 'coderay'
+
+  def initialize *args
+    super
+    @pre_class = 'CodeRay'
+    @requires_stylesheet = nil
+  end
+
+  def highlight?
+    library_available?
+  end
+
+  def highlight node, source, lang, opts
+    @requires_stylesheet = true if (css_mode = opts[:css_mode]) == :class
+    # NOTE CodeRay::Duo gracefully falls back to no highlighting if lang isn't recognized
+    highlighted = ::CodeRay::Duo[lang ? lang.to_sym : :text, :html,
+      css: css_mode,
+      line_numbers: (line_numbers = opts[:number_lines]),
+      line_number_start: opts[:start_line_number],
+      line_number_anchors: false,
+      highlight_lines: opts[:highlight_lines],
+      bold_every: false,
+    ].highlight source
+    if line_numbers == :table && opts[:callouts]
+      [highlighted, (idx = highlighted.index CodeCellStartTagCs) ? idx + CodeCellStartTagCs.length : nil]
+    else
+      highlighted
+    end
+  end
+
+  def docinfo? location
+    @requires_stylesheet && location == :footer
+  end
+
+  def docinfo location, doc, opts
+    if opts[:linkcss]
+      %(<link rel="stylesheet" href="#{doc.normalize_web_path stylesheet_basename, (doc.attr 'stylesdir', ''), false}"#{opts[:self_closing_tag_slash]}>)
+    else
+      %(<style>
+#{read_stylesheet}
+</style>)
+    end
+  end
+
+  def write_stylesheet? doc
+    @requires_stylesheet
+  end
+
+  def write_stylesheet doc, to_dir
+    ::File.write (::File.join to_dir, stylesheet_basename), read_stylesheet, mode: FILE_WRITE_MODE
+  end
+
+  module Loader
+    private
+
+    def library_available?
+      (@@library_status ||= load_library) == :loaded ? true : nil
+    end
+
+    def load_library
+      (defined? ::CodeRay::Duo) ? :loaded : (Helpers.require_library 'coderay', true, :warn).nil? ? :unavailable : :loaded
+    end
+  end
+
+  module Styles
+    include Loader
+
+    def read_stylesheet
+      @@stylesheet_cache ||= (::File.read (::File.join Stylesheets::STYLESHEETS_DIR, stylesheet_basename), mode: FILE_READ_MODE).rstrip
+    end
+
+    def stylesheet_basename
+      'coderay-asciidoctor.css'
+    end
+  end
+
+  extend Styles # exports static methods
+  include Loader, Styles # adds methods to instance
+
+  CodeCellStartTagCs = '<td class="code"><pre>'
+
+  private_constant :CodeCellStartTagCs
+end
+end

data/lib/asciidoctor/syntax_highlighter/highlightjs.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+module Asciidoctor
+class SyntaxHighlighter::HighlightJsAdapter < SyntaxHighlighter::Base
+  register_for 'highlightjs', 'highlight.js'
+
+  def initialize *args
+    super
+    @name = @pre_class = 'highlightjs'
+  end
+
+  def format node, lang, opts
+    super node, lang, (opts.merge transform: proc {|_, code| code['class'] = %(language-#{lang || 'none'} hljs) } )
+  end
+
+  def docinfo? location
+    location == :footer
+  end
+
+  def docinfo location, doc, opts
+    base_url = doc.attr 'highlightjsdir', %(#{opts[:cdn_base_url]}/highlight.js/#{HIGHLIGHT_JS_VERSION})
+    %(<link rel="stylesheet" href="#{base_url}/styles/#{doc.attr 'highlightjs-theme', 'github'}.min.css"#{opts[:self_closing_tag_slash]}>
+<script src="#{base_url}/highlight.min.js"></script>
+<script>hljs.initHighlighting()</script>)
+  end
+end
+end

data/lib/asciidoctor/syntax_highlighter/html_pipeline.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+module Asciidoctor
+class SyntaxHighlighter::HtmlPipelineAdapter < SyntaxHighlighter::Base
+  register_for 'html-pipeline'
+
+  def format node, lang, opts
+    %(<pre#{lang ? %[ lang="#{lang}"] : ''}><code>#{node.content}</code></pre>)
+  end
+end
+end

data/lib/asciidoctor/syntax_highlighter/prettify.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+module Asciidoctor
+class SyntaxHighlighter::PrettifyAdapter < SyntaxHighlighter::Base
+  register_for 'prettify'
+
+  def initialize *args
+    super
+    @pre_class = 'prettyprint'
+  end
+
+  def format node, lang, opts
+    opts[:transform] = proc {|pre| pre['class'] += %( #{(start = node.attr 'start') ? %[linenums:#{start}] : 'linenums'}) } if node.attr? 'linenums'
+    super
+  end
+
+  def docinfo? location
+    location == :footer
+  end
+
+  def docinfo location, doc, opts
+    base_url = doc.attr 'prettifydir', %(#{opts[:cdn_base_url]}/prettify/r298)
+    prettify_theme_url = ((prettify_theme = doc.attr 'prettify-theme', 'prettify').start_with? 'http://', 'https://') ? prettify_theme : %(#{base_url}/#{prettify_theme}.min.css)
+    %(<link rel="stylesheet" href="#{prettify_theme_url}"#{opts[:self_closing_tag_slash]}>
+<script src="#{base_url}/run_prettify.min.js"></script>)
+  end
+end
+end

data/lib/asciidoctor/syntax_highlighter/pygments.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+module Asciidoctor
+class SyntaxHighlighter::PygmentsAdapter < SyntaxHighlighter::Base
+  register_for 'pygments'
+
+  def initialize *args
+    super
+    @requires_stylesheet = nil
+    @style = nil
+  end
+
+  def highlight?
+    library_available?
+  end
+
+  def highlight node, source, lang, opts
+    lexer = (::Pygments::Lexer.find_by_alias lang) || (::Pygments::Lexer.find_by_mimetype 'text/plain')
+    @requires_stylesheet = true unless (noclasses = opts[:css_mode] != :class)
+    highlight_opts = {
+      classprefix: TOKEN_CLASS_PREFIX,
+      cssclass: WRAPPER_CLASS,
+      nobackground: true,
+      noclasses: noclasses,
+      startinline: lexer.name == 'PHP' && !(node.option? 'mixed'),
+      stripnl: false,
+      style: (@style ||= (style = opts[:style]) && (style_available? style) || DEFAULT_STYLE),
+    }
+    if (highlight_lines = opts[:highlight_lines])
+      highlight_opts[:hl_lines] = highlight_lines.join ' '
+    end
+    if (linenos = opts[:number_lines]) && (highlight_opts[:linenostart] = opts[:start_line_number]) && (highlight_opts[:linenos] = linenos) == :table
+      if (highlighted = lexer.highlight source, options: highlight_opts)
+        highlighted = highlighted.sub StyledLinenoColumnStartTagsRx, LinenoColumnStartTagsCs if noclasses
+        highlighted = highlighted.sub WrapperTagRx, PreTagCs
+        opts[:callouts] ? [highlighted, (idx = highlighted.index CodeCellStartTagCs) ? idx + CodeCellStartTagCs.length : nil] : highlighted
+      else
+        node.sub_specialchars source # handles nil response from ::Pygments::Lexer#highlight
+      end
+    elsif (highlighted = lexer.highlight source, options: highlight_opts)
+      highlighted = highlighted.gsub StyledLinenoSpanTagRx, LinenoSpanTagCs if linenos && noclasses
+      highlighted.sub WrapperTagRx, '\1'
+    else
+      node.sub_specialchars source # handles nil response from ::Pygments::Lexer#highlight
+    end
+  end
+
+  def format node, lang, opts
+    if opts[:css_mode] != :class && (@style = (style = opts[:style]) && (style_available? style) || DEFAULT_STYLE) &&
+        (pre_style_attr_val = base_style @style)
+      opts[:transform] = proc {|pre| pre['style'] = pre_style_attr_val }
+    end
+    super
+  end
+
+  def docinfo? location
+    @requires_stylesheet && location == :footer
+  end
+
+  def docinfo location, doc, opts
+    if opts[:linkcss]
+      %(<link rel="stylesheet" href="#{doc.normalize_web_path (stylesheet_basename @style), (doc.attr 'stylesdir', ''), false}"#{opts[:self_closing_tag_slash]}>)
+    else
+      %(<style>
+#{read_stylesheet @style}
+</style>)
+    end
+  end
+
+  def write_stylesheet? doc
+    @requires_stylesheet
+  end
+
+  def write_stylesheet doc, to_dir
+    ::File.write (::File.join to_dir, (stylesheet_basename @style)), (read_stylesheet @style), mode: FILE_WRITE_MODE
+  end
+
+  module Loader
+    private
+
+    def library_available?
+      (@@library_status ||= load_library) == :loaded ? true : nil
+    end
+
+    def load_library
+      (defined? ::Pygments::Lexer) ? :loaded : (Helpers.require_library 'pygments', 'pygments.rb', :warn).nil? ? :unavailable : :loaded
+    end
+  end
+
+  module Styles
+    include Loader
+
+    def read_stylesheet style
+      library_available? ? @@stylesheet_cache[style || DEFAULT_STYLE] || '/* Failed to load Pygments CSS. */' : '/* Pygments CSS disabled because Pygments is not available. */'
+    end
+
+    def stylesheet_basename style
+      %(pygments-#{style || DEFAULT_STYLE}.css)
+    end
+
+    private
+
+    def base_style style
+      library_available? ? @@base_style_cache[style || DEFAULT_STYLE] : nil
+    end
+
+    def style_available? style
+      (((@@available_styles ||= ::Pygments.styles.to_set).include? style) rescue nil) && style
+    end
+
+    @@base_style_cache = ::Hash.new do |cache, key|
+      if BaseStyleRx =~ @@stylesheet_cache[key]
+        @@base_style_cache = cache.merge key => (style = $1.strip)
+        style
+      end
+    end
+    @@stylesheet_cache = ::Hash.new do |cache, key|
+      if (stylesheet = ::Pygments.css BASE_SELECTOR, classprefix: TOKEN_CLASS_PREFIX, style: key)
+        @@stylesheet_cache = cache.merge key => stylesheet
+        stylesheet
+      end
+    end
+
+    DEFAULT_STYLE = 'default'
+    BASE_SELECTOR = 'pre.pygments'
+    TOKEN_CLASS_PREFIX = 'tok-'
+
+    BaseStyleRx = /^#{BASE_SELECTOR.gsub '.', '\\.'} +\{([^}]+?)\}/
+
+    private_constant :BASE_SELECTOR, :TOKEN_CLASS_PREFIX, :BaseStyleRx
+  end
+
+  extend Styles # exports static methods
+  include Loader, Styles # adds methods to instance
+
+  CodeCellStartTagCs = '<td class="code">'
+  LinenoColumnStartTagsCs = '<td class="linenos"><div class="linenodiv"><pre>'
+  LinenoSpanTagCs = '<span class="lineno">\1</span>'
+  PreTagCs = '<pre>\1</pre>'
+  StyledLinenoColumnStartTagsRx = /<td><div class="linenodiv" style="[^"]+?"><pre style="[^"]+?">/
+  StyledLinenoSpanTagRx = %r(<span style="background-color: #f0f0f0; padding: 0 5px 0 5px">( *\d+ )</span>)
+  WRAPPER_CLASS = 'lineno' # doesn't appear in output; Pygments appends "table" to this value to make nested table class
+  # NOTE <pre> has style attribute when pygments-css=style
+  # NOTE <div> has trailing newline when pygments-linenums-mode=table
+  # NOTE initial <span></span> preserves leading blank lines
+  WrapperTagRx = %r(<div class="#{WRAPPER_CLASS}"><pre\b[^>]*?>(.*)</pre></div>\n*)m
+
+  private_constant :CodeCellStartTagCs, :LinenoColumnStartTagsCs, :LinenoSpanTagCs, :PreTagCs, :StyledLinenoColumnStartTagsRx, :StyledLinenoSpanTagRx, :WrapperTagRx, :WRAPPER_CLASS
+end
+end