org.asciidoctor

Interface Asciidoctor

All Superinterfaces:

java.lang.AutoCloseable

All Known Subinterfaces:

AsciidoctorJRuby

All Known Implementing Classes:

JRubyAsciidoctor

public interface Asciidoctor
extends java.lang.AutoCloseable

The main application interface (API) for Asciidoctor. This API provides methods to:

• parse (aka. load) AsciiDoc content,
• convert it to various output formats,
• register extensions, custom converter and syntax highlighter.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Asciidoctor.Factory Factory for creating a new instance of Asciidoctor interface.

Method Summary

Modifier and Type	Method and Description
java.lang.String	asciidoctorVersion() Method that gets the asciidoctor version which is being used..
default void	close()
void	convert(java.io.Reader contentReader, java.io.Writer rendererWriter, java.util.Map<java.lang.String,java.lang.Object> options) Deprecated. Use convert(Reader, Writer, Options) instead.
void	convert(java.io.Reader contentReader, java.io.Writer rendererWriter, Options options) Parse the document read from reader sending the converted result to writer.
void	convert(java.io.Reader contentReader, java.io.Writer rendererWriter, OptionsBuilder options) Deprecated. Use convert(Reader, Writer, Options) instead.
java.lang.String	convert(java.lang.String content, java.util.Map<java.lang.String,java.lang.Object> options) Deprecated. User convert(String, Options) instead.
<T> T	convert(java.lang.String content, java.util.Map<java.lang.String,java.lang.Object> options, java.lang.Class<T> expectedResult) Deprecated. Use convert(String, Options, Class) instead.
java.lang.String	convert(java.lang.String content, Options options) Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.
java.lang.String	convert(java.lang.String content, OptionsBuilder options) Deprecated. Use convert(String, Options) instead.
<T> T	convert(java.lang.String content, OptionsBuilder options, java.lang.Class<T> expectedResult) Deprecated. Use convert(String, Options, Class) instead.
<T> T	convert(java.lang.String content, Options options, java.lang.Class<T> expectedResult) Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.
java.lang.String[]	convertDirectory(java.lang.Iterable<java.io.File> directoryWalker, java.util.Map<java.lang.String,java.lang.Object> options) Deprecated. Use convertDirectory(Iterable, Options) instead.
java.lang.String[]	convertDirectory(java.lang.Iterable<java.io.File> directoryWalker, Options options) Convert all AsciiDoc files found in directoryWalker.
java.lang.String[]	convertDirectory(java.lang.Iterable<java.io.File> directoryWalker, OptionsBuilder options) Deprecated. Use convertDirectory(Iterable, Options) instead.
java.lang.String	convertFile(java.io.File file, java.util.Map<java.lang.String,java.lang.Object> options) Deprecated. Use convertFile(File, Options) instead.
<T> T	convertFile(java.io.File file, java.util.Map<java.lang.String,java.lang.Object> options, java.lang.Class<T> expectedResult) Deprecated. User convertFile(File, Options, Class) instead.
java.lang.String	convertFile(java.io.File file, Options options) Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.
java.lang.String	convertFile(java.io.File file, OptionsBuilder options) Deprecated. Use convertFile(File, Options) instead.
<T> T	convertFile(java.io.File file, OptionsBuilder options, java.lang.Class<T> expectedResult) Deprecated. User convertFile(File, Options, Class) instead.
<T> T	convertFile(java.io.File file, Options options, java.lang.Class<T> expectedResult) Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.
java.lang.String[]	convertFiles(java.util.Collection<java.io.File> files, java.util.Map<java.lang.String,java.lang.Object> options) Deprecated. Use convertFiles(Collection, Options) instead.
java.lang.String[]	convertFiles(java.util.Collection<java.io.File> asciidoctorFiles, Options options) Convert all files from a collection.
java.lang.String[]	convertFiles(java.util.Collection<java.io.File> files, OptionsBuilder options) Deprecated. Use convertFiles(Collection, Options) instead.
ExtensionGroup	createGroup() Creates an ExtensionGroup that can be used to register and unregister multiples extensions all at once.
ExtensionGroup	createGroup(java.lang.String groupName) Creates an ExtensionGroup that can be used to register and unregister multiples extensions all at once.
JavaConverterRegistry	javaConverterRegistry() Creates a registry for registering Java converters.
JavaExtensionRegistry	javaExtensionRegistry() Creates an extension registry ready to be used for registering Java extensions.
Document	load(java.lang.String content, java.util.Map<java.lang.String,java.lang.Object> options) Deprecated. Use load(String, Options) instead.
Document	load(java.lang.String content, Options options) Loads AsciiDoc content and returns the Document object.
Document	loadFile(java.io.File file, java.util.Map<java.lang.String,java.lang.Object> options) Deprecated. Use loadFile(File, Options) instead.
Document	loadFile(java.io.File file, Options options) Loads AsciiDoc content from file and returns the Document object.
DocumentHeader	readDocumentHeader(java.io.File file) Deprecated. Use loadFile(File, Map) instead.
DocumentHeader	readDocumentHeader(java.io.Reader contentReader) Deprecated. Use loadFile(File, Map) instead.
DocumentHeader	readDocumentHeader(java.lang.String content) Deprecated. Use load(String, Map) instead.
void	registerLogHandler(LogHandler logHandler) Register a LogHandler to capture Asciidoctor message records.
void	requireLibraries(java.util.Collection<java.lang.String> requiredLibraries) Loads the given Ruby gem in requiredLibraries by name.
void	requireLibrary(java.lang.String... requiredLibraries) Loads the given Ruby gem(s) by name.
RubyExtensionRegistry	rubyExtensionRegistry() Creates an Ruby extension registry ready to be used for registering Ruby extension.
void	shutdown() This method frees all resources consumed by AsciidoctorJ module.
SyntaxHighlighterRegistry	syntaxHighlighterRegistry() Creates a registry for registering Java syntax highlighter.
void	unregisterAllExtensions() Unregister all registered extensions.
void	unregisterLogHandler(LogHandler logHandler) Unregister a LogHandler.
default <T> T	unwrap(java.lang.Class<T> clazz)

Method Detail

convert

@Deprecated
java.lang.String convert(java.lang.String content,
                                     java.util.Map<java.lang.String,java.lang.Object> options)

Deprecated. User convert(String, Options) instead.

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as String object.

Parameters:

content - the AsciiDoc source as String.

options - a Map of options to control processing (default: {}).

Returns:

the rendered output String is returned

convert

@Deprecated
<T> T convert(java.lang.String content,
                          java.util.Map<java.lang.String,java.lang.Object> options,
                          java.lang.Class<T> expectedResult)

Deprecated. Use convert(String, Options, Class) instead.

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as String object.

Parameters:

content - the AsciiDoc source as String.

options - a Map of options to control processing (default: {}).

expectedResult - the expected return type. Usually String for HTML based formats. In this case convert(String, Map) is the same.

Returns:

the rendered output String is returned

convert

java.lang.String convert(java.lang.String content,
                         Options options)

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as String object.

Parameters:

content - the AsciiDoc source as String.

options - options to control processing (default: empty).

Returns:

the rendered output String is returned

convert

<T> T convert(java.lang.String content,
              Options options,
              java.lang.Class<T> expectedResult)

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as String object.

Parameters:

content - the AsciiDoc source as String.

options - options to control processing (default: empty).

expectedResult - the expected return type. Usually String for HTML based formats. In this case convert(String, Options) is the same.

Returns:

the rendered output String is returned

convert

@Deprecated
java.lang.String convert(java.lang.String content,
                                     OptionsBuilder options)

Deprecated. Use convert(String, Options) instead.

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as String object.

Parameters:

content - the AsciiDoc source as String.

options - a Map of options to control processing (default: {}).

Returns:

the rendered output String is returned

convert

@Deprecated
<T> T convert(java.lang.String content,
                          OptionsBuilder options,
                          java.lang.Class<T> expectedResult)

Deprecated. Use convert(String, Options, Class) instead.

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as String object.

Parameters:

content - the AsciiDoc source as String.

options - a Map of options to control processing (default: {}).

expectedResult - the expected return type. Usually String for HTML based formats. In this case convert(String, OptionsBuilder) is the same.

Returns:

the rendered output String is returned

convert

@Deprecated
void convert(java.io.Reader contentReader,
                         java.io.Writer rendererWriter,
                         java.util.Map<java.lang.String,java.lang.Object> options)
                  throws java.io.IOException

Deprecated. Use convert(Reader, Writer, Options) instead.

Parse the document read from reader sending the converted result to writer.

Parameters:

contentReader - where asciidoc content is read.

rendererWriter - where rendered content is written. Writer is flushed, but not closed.

options - a Map of options to control processing (default: {}).

Throws:

java.io.IOException - if an error occurs while writing rendered content, this exception is thrown.

convert

void convert(java.io.Reader contentReader,
             java.io.Writer rendererWriter,
             Options options)
      throws java.io.IOException

Parse the document read from reader sending the converted result to writer.

Parameters:

contentReader - where asciidoc content is read.

rendererWriter - where rendered content is written. Writer is flushed, but not closed.

options - options to control processing (default: empty).

Throws:

java.io.IOException - if an error occurs while writing rendered content, this exception is thrown.

convert

@Deprecated
void convert(java.io.Reader contentReader,
                         java.io.Writer rendererWriter,
                         OptionsBuilder options)
                  throws java.io.IOException

Deprecated. Use convert(Reader, Writer, Options) instead.

Parse the document read from reader sending the converted result to writer.

Parameters:

contentReader - where asciidoc content is read.

rendererWriter - where rendered content is written. Writer is flushed, but not closed.

options - a Map of options to control processing (default: {}).

Throws:

java.io.IOException - if an error occurs while writing rendered content, this exception is thrown.

convertFile

@Deprecated
java.lang.String convertFile(java.io.File file,
                                         java.util.Map<java.lang.String,java.lang.Object> options)

Deprecated. Use convertFile(File, Options) instead.

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as File.

If the :in_place option is true, and the input is a File, the output is written to a file adjacent to the input file, having an extension that corresponds to the backend format. Otherwise, if the :to_file option is specified, the file is written to that file. If :to_file is not an absolute path, it is resolved relative to :to_dir, if given, otherwise the Document#base_dir. If the target directory does not exist, it will not be created unless the :mkdirs option is set to true. If the file cannot be written because the target directory does not exist, or because it falls outside of the Document#base_dir in safe mode, an IOError is raised.

Parameters:

file - an input Asciidoctor file.

options - a Map of options to control processing (default: {}).

Returns:

returns nothing if the rendered output String is written to a file.

convertFile

@Deprecated
<T> T convertFile(java.io.File file,
                              java.util.Map<java.lang.String,java.lang.Object> options,
                              java.lang.Class<T> expectedResult)

Deprecated. User convertFile(File, Options, Class) instead.

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as File.

If the :in_place option is true, and the input is a File, the output is written to a file adjacent to the input file, having an extension that corresponds to the backend format. Otherwise, if the :to_file option is specified, the file is written to that file. If :to_file is not an absolute path, it is resolved relative to :to_dir, if given, otherwise the Document#base_dir. If the target directory does not exist, it will not be created unless the :mkdirs option is set to true. If the file cannot be written because the target directory does not exist, or because it falls outside of the Document#base_dir in safe mode, an IOError is raised.

Parameters:

file - an input Asciidoctor file.

options - a Map of options to control processing (default: {}).

expectedResult - the expected return type. Usually String for HTML based formats. In this case convertFile(File, Map) is the same.

Returns:

returns nothing if the rendered output is written to a file.

convertFile

java.lang.String convertFile(java.io.File file,
                             Options options)

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as File.

If the :in_place option is true, and the input is a File, the output is written to a file adjacent to the input file, having an extension that corresponds to the backend format. Otherwise, if the :to_file option is specified, the file is written to that file. If :to_file is not an absolute path, it is resolved relative to :to_dir, if given, otherwise the Document#base_dir. If the target directory does not exist, it will not be created unless the :mkdirs option is set to true. If the file cannot be written because the target directory does not exist, or because it falls outside of the Document#base_dir in safe mode, an IOError is raised.

Parameters:

file - an input Asciidoctor file.

options - options to control processing (default: empty).

Returns:

returns nothing if the rendered output String is written to a file.

convertFile

<T> T convertFile(java.io.File file,
                  Options options,
                  java.lang.Class<T> expectedResult)

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as File.

If the :in_place option is true, and the input is a File, the output is written to a file adjacent to the input file, having an extension that corresponds to the backend format. Otherwise, if the :to_file option is specified, the file is written to that file. If :to_file is not an absolute path, it is resolved relative to :to_dir, if given, otherwise the Document#base_dir. If the target directory does not exist, it will not be created unless the :mkdirs option is set to true. If the file cannot be written because the target directory does not exist, or because it falls outside of the Document#base_dir in safe mode, an IOError is raised.

Parameters:

file - an input Asciidoctor file.

options - options to control processing (default: empty).

expectedResult - the expected return type. Usually String for HTML based formats. In this case convertFile(File, Map) is the same.

Returns:

returns nothing if the rendered output is written to a file.

convertFile

@Deprecated
java.lang.String convertFile(java.io.File file,
                                         OptionsBuilder options)

Deprecated. Use convertFile(File, Options) instead.

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as File.

If the :in_place option is true, and the input is a File, the output is written to a file adjacent to the input file, having an extension that corresponds to the backend format. Otherwise, if the :to_file option is specified, the file is written to that file. If :to_file is not an absolute path, it is resolved relative to :to_dir, if given, otherwise the Document#base_dir. If the target directory does not exist, it will not be created unless the :mkdirs option is set to true. If the file cannot be written because the target directory does not exist, or because it falls outside of the Document#base_dir in safe mode, an IOError is raised.

Parameters:

file - an input Asciidoctor file.

options - a Map of options to control processing (default: {}).

Returns:

returns nothing if the rendered output String is written to a file.

convertFile

@Deprecated
<T> T convertFile(java.io.File file,
                              OptionsBuilder options,
                              java.lang.Class<T> expectedResult)

Deprecated. User convertFile(File, Options, Class) instead.

Parse the AsciiDoc source input into an Document Document and convert it to the specified backend format.

Accepts input as File.

If the :in_place option is true, and the input is a File, the output is written to a file adjacent to the input file, having an extension that corresponds to the backend format. Otherwise, if the :to_file option is specified, the file is written to that file. If :to_file is not an absolute path, it is resolved relative to :to_dir, if given, otherwise the Document#base_dir. If the target directory does not exist, it will not be created unless the :mkdirs option is set to true. If the file cannot be written because the target directory does not exist, or because it falls outside of the Document#base_dir in safe mode, an IOError is raised.

Parameters:

file - an input Asciidoctor file.

options - a Map of options to control processing (default: {}).

expectedResult - the expected return type. Usually String for HTML based formats. In this case convertFile(File, Map) is the same.

Returns:

returns nothing if the rendered output is written to a file.

convertDirectory

@Deprecated
java.lang.String[] convertDirectory(java.lang.Iterable<java.io.File> directoryWalker,
                                                java.util.Map<java.lang.String,java.lang.Object> options)

Deprecated. Use convertDirectory(Iterable, Options) instead.

Convert all AsciiDoc files found in directoryWalker. See AsciiDocDirectoryWalker for reference strategy.

Parameters:

directoryWalker - strategy used to retrieve all files to be rendered.

options - a Map of options to control processing (default: {}).

Returns:

returns an array of 0 positions if the rendered output is written to a file.

convertDirectory

java.lang.String[] convertDirectory(java.lang.Iterable<java.io.File> directoryWalker,
                                    Options options)

Convert all AsciiDoc files found in directoryWalker. See AsciiDocDirectoryWalker for reference strategy.

Parameters:

directoryWalker - strategy used to retrieve all files to be rendered.

options - options to control processing (default: empty).

Returns:

returns an array of 0 positions if the rendered output is written to a file.

convertDirectory

@Deprecated
java.lang.String[] convertDirectory(java.lang.Iterable<java.io.File> directoryWalker,
                                                OptionsBuilder options)

Deprecated. Use convertDirectory(Iterable, Options) instead.

Convert all AsciiDoc files found in directoryWalker. See AsciiDocDirectoryWalker for reference strategy.

Parameters:

directoryWalker - strategy used to retrieve all files to be rendered.

options - a Map of options to control processing (default: {}).

Returns:

returns an array of 0 positions if the rendered output is written to a file.

convertFiles

@Deprecated
java.lang.String[] convertFiles(java.util.Collection<java.io.File> files,
                                            java.util.Map<java.lang.String,java.lang.Object> options)

Deprecated. Use convertFiles(Collection, Options) instead.

Convert all files from a collection.

Parameters:

files - to be converted.

options - a Map of options to control processing (default: {}).

Returns:

returns an array of 0 positions if the rendered output is written to a file.

convertFiles

java.lang.String[] convertFiles(java.util.Collection<java.io.File> asciidoctorFiles,
                                Options options)

Convert all files from a collection.

Parameters:

asciidoctorFiles - to be converted.

options - options to control processing (default: empty).

Returns:

returns an array of 0 positions if the rendered output is written to a file.

convertFiles

@Deprecated
java.lang.String[] convertFiles(java.util.Collection<java.io.File> files,
                                            OptionsBuilder options)

Deprecated. Use convertFiles(Collection, Options) instead.

Convert all files from a collection.

Parameters:

files - to be converted.

options - a Map of options to control processing (default: {}).

Returns:

returns an array of 0 positions if the rendered output is written to a file.

requireLibrary

void requireLibrary(java.lang.String... requiredLibraries)

Loads the given Ruby gem(s) by name.

Parameters:

requiredLibraries -

requireLibraries

void requireLibraries(java.util.Collection<java.lang.String> requiredLibraries)

Loads the given Ruby gem in requiredLibraries by name.

Parameters:

requiredLibraries -

readDocumentHeader

@Deprecated
DocumentHeader readDocumentHeader(java.io.File file)

Deprecated. Use loadFile(File, Map) instead.

Reads only header parameters instead of all document.

Parameters:

file - to read the attributes.

Returns:

header.

readDocumentHeader

@Deprecated
DocumentHeader readDocumentHeader(java.lang.String content)

Deprecated. Use load(String, Map) instead.

Reads only header parameters instead of all document.

Parameters:

content - where converted content is written. Writer is flushed, but not closed.

Returns:

header.

readDocumentHeader

@Deprecated
DocumentHeader readDocumentHeader(java.io.Reader contentReader)

Deprecated. Use loadFile(File, Map) instead.

Reads only header parameters instead of all document.

Parameters:

contentReader - where asciidoc content is read.

Returns:

header.

javaExtensionRegistry

JavaExtensionRegistry javaExtensionRegistry()

Creates an extension registry ready to be used for registering Java extensions.

Returns:

Extension Registry object.

rubyExtensionRegistry

RubyExtensionRegistry rubyExtensionRegistry()

Creates an Ruby extension registry ready to be used for registering Ruby extension.

Returns:

Extension Registry object.

javaConverterRegistry

JavaConverterRegistry javaConverterRegistry()

Creates a registry for registering Java converters.

Returns:

Converter Registry object.

syntaxHighlighterRegistry

SyntaxHighlighterRegistry syntaxHighlighterRegistry()

Creates a registry for registering Java syntax highlighter.

This API is experimental and might change in an incompatible way in a minor version update!

Returns:

Converter Registry object.

createGroup

ExtensionGroup createGroup()

Creates an ExtensionGroup that can be used to register and unregister multiples extensions all at once.

Returns:

Extension Group instance.

createGroup

ExtensionGroup createGroup(java.lang.String groupName)

Creates an ExtensionGroup that can be used to register and unregister multiples extensions all at once.

Parameters:

groupName - to assign to the ExtensionGroup.

Returns:

Extension Group instance.

unregisterAllExtensions

void unregisterAllExtensions()

Unregister all registered extensions.

shutdown

void shutdown()

This method frees all resources consumed by AsciidoctorJ module. Keep in mind that if this method is called, instance becomes unusable and you should create another instance.

asciidoctorVersion

java.lang.String asciidoctorVersion()

Method that gets the asciidoctor version which is being used..

Returns:

Version number.

load

@Deprecated
Document load(java.lang.String content,
                          java.util.Map<java.lang.String,java.lang.Object> options)

Deprecated. Use load(String, Options) instead.

Loads AsciiDoc content and returns the Document object.

Parameters:

content - to be parsed.

options - a Map of options to control processing (default: {}).

Returns:

Document of given content.

load

Document load(java.lang.String content,
              Options options)

Loads AsciiDoc content and returns the Document object.

Parameters:

content - to be parsed.

options - options to control processing (default: empty).

Returns:

Document of given content.

loadFile

@Deprecated
Document loadFile(java.io.File file,
                              java.util.Map<java.lang.String,java.lang.Object> options)

Deprecated. Use loadFile(File, Options) instead.

Loads AsciiDoc content from file and returns the Document object.

Parameters:

file - to be parsed.

options - a Map of options to control processing (default: {}).

Returns:

Document of given content.

loadFile

Document loadFile(java.io.File file,
                  Options options)

Loads AsciiDoc content from file and returns the Document object.

Parameters:

file - to be parsed.

options - options to control processing (default: empty).

Returns:

Document of given content.

registerLogHandler

void registerLogHandler(LogHandler logHandler)

Register a LogHandler to capture Asciidoctor message records.

Parameters:

logHandler - handler instance.

unregisterLogHandler

void unregisterLogHandler(LogHandler logHandler)

Unregister a LogHandler.

Parameters:

logHandler - handler instance.

unwrap

default <T> T unwrap(java.lang.Class<T> clazz)

close

default void close()

Specified by:

close in interface java.lang.AutoCloseable