Package org.asciidoctor

Interface Asciidoctor

  • All Superinterfaces:
    java.lang.AutoCloseable
    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 Detail

      • convert

        java.lang.String convert​(java.lang.String content,
                         Options options)
        Parse the AsciiDoc source input into a 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 a 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. The type must match the one generated by Asciidoctor based on the Options used, or the type returned by a Java converter (AbstractConverter) No coercion is applied.
        Returns:
        the rendered output String is returned

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

      • convertFile

        java.lang.String convertFile​(java.io.File file,
                             Options options)
        Parse the AsciiDoc source input into a 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 a 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, Options) is the same.
        Returns:
        returns nothing 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.

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

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

      • 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

        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

        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