org.asciidoctor.syntaxhighlighter.SyntaxHighlighterAdapter 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.Document;
import org.asciidoctor.extension.LocationType;

import java.util.Map;

/**
 * This interface has to be implemented by all syntax highlighter adapters, regardless if they
 * update the resulting HTML document to highlight sources on the client or on the server.
 *
 * Depending on how the syntax highlighter works in detail one or more of these interfaces
 * should be implemented as well:
 * 

 *     {@link Formatter}
 *     If the highlighter requires certain classes on the
 *     <pre><code></code></pre>
 *     elements that enclose the source text.
 *
 *     {@link StylesheetWriter}
 *     If the highlighter can write stylesheets to external files in case the document
 *     is rendered with the attributes :linkcss and :copycss.
 *
 *     {@link Highlighter}
 *     If the highlighter actually highlights the source text while rendering the asciidoc
 *     document to html.
 *
 *     {@link org.asciidoctor.log.Logging}
 *     If the highlighter wants to log to the common Asciidoctor logger.
 * 
 *
 * SyntaxHighlighterAdapters have to be registered as classes at the
 * {@link SyntaxHighlighterRegistry}:
 * 

 *     Asciidoctor asciidoctor;
 *     asciidoctor.syntaxHighlighterRegistry().register(MySyntaxHighligher.class, "mysyntaxhighighter");
 *     asciidoctor.convert(doc,
 *         OptionsBuilder.options()
 *             .attributes(AttributesBuilder.attributes()
 *                 .sourceHighlighter("mysyntaxhighlighter")));
 * 
 * A SyntaxHighlighterAdapter is expected to have a constructor with 3 parameters:
 * 

 *     name
 *     A String containing the name of the highlighter.
 *
 *     backend
 *     A String containing the backend used for rendering, e.g. "html5".
 *
 *     options
 *     A Map<String, Object> that contains options for rendering.
 *     One key that is always present is document that contains the current
 *     {@link Document} that is rendered.
 * 
 * All parameters are optional, that means if there is only a constructor that takes two
 * String parameters, then this will be used to construct an instance.
 * This includes using the default constructor if the class defines no constructor at all.
 * 
 * The lifecycle of a SyntaxHighlighter is that one instance is created for every document that
 * is converted.
 *
 * This API is experimental and might change in an incompatible way in a minor version update!
 */
public interface SyntaxHighlighterAdapter {

  boolean hasDocInfo(LocationType location);

  String getDocinfo(LocationType location, Document document, Map options);

}