Module: Asciidoctor::SyntaxHighlighter

Extended by:
DefaultFactory
Included in:
Base
Defined in:
lib/asciidoctor/syntax_highlighter.rb

Overview

prettify. Additional adapters can be registered using SyntaxHighlighter.register or by supplying a custom factory.

Defined Under Namespace

Modules: Config, DefaultFactory, Factory Classes: Base, CodeRayAdapter, CustomFactory, DefaultFactoryProxy, HighlightJsAdapter, HtmlPipelineAdapter, PrettifyAdapter, PygmentsAdapter, RougeAdapter

Constant Summary

Constants included from DefaultFactory

DefaultFactory::PROVIDED

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from DefaultFactory

for, register

Methods included from Factory

#create, #for, #register

Instance Attribute Details

#name ⇒ Object (readonly)

Returns the String name of this syntax highlighter for referencing it in messages and option names.



16
17
18
 
# File 'lib/asciidoctor/syntax_highlighter.rb', line 16

def name
  @name
end

Instance Method Details

#docinfo(location, doc, opts) ⇒ String

Generates docinfo markup for this syntax highlighter to insert at the specified location in the output document. Should be called by converter after main content has been converted.

Parameters:

  • location —

    The Symbol representing the location slot (:head or :footer).

  • doc —

    The Document in which this syntax highlighter is being used.

  • opts —

    A Hash of options that configure the syntax highlighting:

Options Hash (opts):

  • :linkcss (Object) —

    A Boolean indicating whether the stylesheet should be linked instead of embedded (optional).

  • :cdn_base_url (Object) —

    The String base URL for assets loaded from the CDN.

  • :self_closing_tag_slash (Object) —

    The String ‘/’ if the converter calling this method emits self-closing tags.

Returns:

  • (String) —

    Return the String markup to insert.

Raises:

  • (::NotImplementedError) 


41
42
43
 
# File 'lib/asciidoctor/syntax_highlighter.rb', line 41

def docinfo location, doc, opts
  raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method since #docinfo? returns true)
end

#docinfo?(location) ⇒ Boolean

Indicates whether this syntax highlighter has docinfo (i.e., markup) to insert into the output document at the specified location. Should be called by converter after main content has been converted.

Parameters:

  • location —

    The Symbol representing the location slot (:head or :footer).

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether the docinfo method should be called for this location.



28
 
# File 'lib/asciidoctor/syntax_highlighter.rb', line 28

def docinfo? location; end

#format(node, lang, opts) ⇒ String

Format the highlighted source for inclusion in an HTML document.

Parameters:

  • 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:

Options Hash (opts):

  • :nowrap (Object) —

    A Boolean that indicates whether wrapping should be disabled (optional).

Returns:

  • (String) —

    Returns the highlighted source String wrapped in preformatted tags (e.g., pre and code)

Raises:

  • (::NotImplementedError) 


80
81
82
 
# File 'lib/asciidoctor/syntax_highlighter.rb', line 80

def format node, lang, opts
  raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method)
end

#highlight(node, source, lang, opts) ⇒ Object

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.

Parameters:

  • 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:

Options Hash (opts):

  • :callouts (Object) —

    A Hash of callouts extracted from the source, indexed by line number (1-based) (optional).

  • :css_mode (Object) —

    The Symbol CSS mode (:class or :inline).

  • :highlight_lines (Object) —

    A 1-based Array of Integer line numbers to highlight (aka emphasize) (optional).

  • :number_lines (Object) —

    A Symbol indicating whether lines should be numbered (:table or :inline) (optional).

  • :start_line_number (Object) —

    The starting Integer (1-based) line number (optional, default: 1).

  • :style (Object) —

    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.

Raises:

  • (::NotImplementedError) 


68
69
70
 
# File 'lib/asciidoctor/syntax_highlighter.rb', line 68

def highlight node, source, lang, opts
  raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method since #highlight? returns true)
end

#highlight? ⇒ Boolean

Indicates whether highlighting is handled by this syntax highlighter or by the client.

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether the highlight method should be used to handle the :specialchars substitution.



48
 
# File 'lib/asciidoctor/syntax_highlighter.rb', line 48

def highlight?; end

#initialize(name, backend = 'html5', opts = {}) ⇒ Object 



18
19
20
 
# File 'lib/asciidoctor/syntax_highlighter.rb', line 18

def initialize name, backend = 'html5', opts = {}
  @name = @pre_class = name
end

#write_stylesheet(doc, to_dir) ⇒ void

This method returns an undefined value.

Writes the stylesheet to support the highlighted source(s) to disk.

Parameters:

  • doc —

    The Document in which this syntax highlighter is being used.

  • to_dir —

    The absolute String path of the stylesheet output directory.

Raises:

  • (::NotImplementedError) 


98
99
100
 
# File 'lib/asciidoctor/syntax_highlighter.rb', line 98

def write_stylesheet doc, to_dir
  raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method since #write_stylesheet? returns true)
end

#write_stylesheet?(doc) ⇒ Boolean

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.

Parameters:

  • doc —

    The Document in which this syntax highlighter is being used.

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether the write_stylesheet method should be called.



90
 
# File 'lib/asciidoctor/syntax_highlighter.rb', line 90

def write_stylesheet? doc; end