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 Description static class
Asciidoctor.Factory
Factory for creating a new instance of Asciidoctor interface.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method 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.Useconvert(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.Useconvert(Reader, Writer, Options)
instead.java.lang.String
convert(java.lang.String content, java.util.Map<java.lang.String,java.lang.Object> options)
Deprecated.Userconvert(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.Useconvert(String, Options, Class)
instead.java.lang.String
convert(java.lang.String content, Options options)
Parse the AsciiDoc source input into an DocumentDocument
and convert it to the specified backend format.java.lang.String
convert(java.lang.String content, OptionsBuilder options)
Deprecated.Useconvert(String, Options)
instead.<T> T
convert(java.lang.String content, OptionsBuilder options, java.lang.Class<T> expectedResult)
Deprecated.Useconvert(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 DocumentDocument
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.UseconvertDirectory(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.UseconvertDirectory(Iterable, Options)
instead.java.lang.String
convertFile(java.io.File file, java.util.Map<java.lang.String,java.lang.Object> options)
Deprecated.UseconvertFile(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.UserconvertFile(File, Options, Class)
instead.java.lang.String
convertFile(java.io.File file, Options options)
Parse the AsciiDoc source input into an DocumentDocument
and convert it to the specified backend format.java.lang.String
convertFile(java.io.File file, OptionsBuilder options)
Deprecated.UseconvertFile(File, Options)
instead.<T> T
convertFile(java.io.File file, OptionsBuilder options, java.lang.Class<T> expectedResult)
Deprecated.UserconvertFile(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 DocumentDocument
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.UseconvertFiles(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.UseconvertFiles(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.Useload(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.UseloadFile(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.UseloadFile(File, Map)
instead.DocumentHeader
readDocumentHeader(java.io.Reader contentReader)
Deprecated.UseloadFile(File, Map)
instead.DocumentHeader
readDocumentHeader(java.lang.String content)
Deprecated.Useload(String, Map)
instead.void
registerLogHandler(LogHandler logHandler)
Register aLogHandler
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 aLogHandler
.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.Userconvert(String, Options)
instead.Parse the AsciiDoc source input into an DocumentDocument
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.Useconvert(String, Options, Class)
instead.Parse the AsciiDoc source input into an DocumentDocument
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. UsuallyString
for HTML based formats. In this caseconvert(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 DocumentDocument
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 DocumentDocument
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. UsuallyString
for HTML based formats. In this caseconvert(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.Useconvert(String, Options)
instead.Parse the AsciiDoc source input into an DocumentDocument
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.Useconvert(String, Options, Class)
instead.Parse the AsciiDoc source input into an DocumentDocument
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. UsuallyString
for HTML based formats. In this caseconvert(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.Useconvert(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.Useconvert(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.UseconvertFile(File, Options)
instead.Parse the AsciiDoc source input into an DocumentDocument
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.UserconvertFile(File, Options, Class)
instead.Parse the AsciiDoc source input into an DocumentDocument
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. UsuallyString
for HTML based formats. In this caseconvertFile(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 DocumentDocument
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 DocumentDocument
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. UsuallyString
for HTML based formats. In this caseconvertFile(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.UseconvertFile(File, Options)
instead.Parse the AsciiDoc source input into an DocumentDocument
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.UserconvertFile(File, Options, Class)
instead.Parse the AsciiDoc source input into an DocumentDocument
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. UsuallyString
for HTML based formats. In this caseconvertFile(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.UseconvertDirectory(Iterable, Options)
instead.Convert all AsciiDoc files found in directoryWalker. SeeAsciiDocDirectoryWalker
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. SeeAsciiDocDirectoryWalker
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.UseconvertDirectory(Iterable, Options)
instead.Convert all AsciiDoc files found in directoryWalker. SeeAsciiDocDirectoryWalker
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.UseconvertFiles(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.UseconvertFiles(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.UseloadFile(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.Useload(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.UseloadFile(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.Useload(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.UseloadFile(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 aLogHandler
to capture Asciidoctor message records.- Parameters:
logHandler
- handler instance.
-
unregisterLogHandler
void unregisterLogHandler(LogHandler logHandler)
Unregister aLogHandler
.- Parameters:
logHandler
- handler instance.
-
unwrap
default <T> T unwrap(java.lang.Class<T> clazz)
-
close
default void close()
- Specified by:
close
in interfacejava.lang.AutoCloseable
-
-