org.asciidoctor.syntaxhighlighter.Highlighter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of asciidoctorj-api Show documentation
API for AsciidoctorJ
There is a newer version: 3.0.0
package org.asciidoctor.syntaxhighlighter;

import org.asciidoctor.ast.Block;

import java.util.Map;

/**
 * A Highlighter transforms the actual raw source text.
 * While a {@link SyntaxHighlighterAdapter} alone might only include the necessary stylesheets and
 * scripts to highlight the sources in the browser, a {@link Highlighter} can actually transform the
 * source to static HTML.
 *
 * If a {@link SyntaxHighlighterAdapter} also implements this interface, the
 * method {@link #highlight(Block, String, String, Map)} will be called for every source block.
 *
 * This API is experimental and might change in an incompatible way in a minor version update!
 */
public interface Highlighter extends SyntaxHighlighterAdapter {

    /**
     * Highlights the source according to the language.
     * @param node The node of the Asciidoctor AST that contains the source to be highlighted.
     * @param source The full content of the source block as one String.
     * @param lang The language that was associated with the source block, e.g. java or
     *             ruby.
     * @param options A map containing options for conversion:
     *                
     *                     callouts
     *                     A map containing all callouts indexed by line number (1-based) (optional).
     *                         That means ((Map)options.get("callouts")).get(1L) will
     *                         return the List of callouts in the first line.
     *                         The value for each callout is a List with 2 elements:
     *                         The optional comment text before the callout, e.g. // ,
     *                         and the callout number, e.g "1".
     *                     
     *
     *                     css_mode
     *                     The CSS mode as a String, "class" or
     *                         "inline"
     *                     
     *
     *                     highlight_lines
     *                     A 1-based Array of Integer line numbers to highlight (aka emphasize) (optional).
     *
     *                     number_lines
     *                     A String 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).
     *
     *                
     * @return A {@link HighlightResult} containing the converted HTML as a String and optionally a
     * line offset.
     */
    HighlightResult highlight(Block node, String source, String lang, Map options);

}