通过 API 处理 AsciiDoc

Asciidoctor 提供了一个名为 Asciidoctor 的 Ruby API，用于解析、分析和转换 AsciiDoc 内容。此 API 旨在用于应用程序、脚本、与其他 Ruby 软件（如 Rails、GitHub 和 GitLab）的集成，以及供其他语言使用，例如 Java（通过 AsciidoctorJ）和 JavaScript（通过 Asciidoctor.js）。

本页将探讨 API 的用途及其用法，展示如何开始使用它，介绍其主要入口点，并提供链接，您可以从中找到更多信息来开始实践。

何时使用 API

如果您只需要将 AsciiDoc 文件转换为可发布格式（如 HTML），那么 asciidoctor CLI 应该能满足您的需求。以下是一个示例，展示了如何使用 CLI 将 AsciiDoc 文档转换为 HTML。

$ asciidoctor -d book -n -a toc=left -a source-highlighter=highlight.js document.adoc

以下是使用 API 将文档转换为 HTML 的相同示例。

require 'asciidoctor'

Asciidoctor.convert_file 'document.adoc', doctype: :book, safe: :unsafe,
  attributes: { 'toc' => 'left', 'sectnums' => '', 'source-highlighter' => 'highlight.js' }
使用 Hash 格式传递属性时，属性名称必须指定为 String，而不是 Symbol。换句话说，toc: 'left' 不会被识别为属性条目（因为 toc: 创建了一个 Symbol 键）。它必须指定为 'toc' => 'left'，如前一个示例所示。

可以通过声明属性的简写形式来缩短此 API 调用。

require 'asciidoctor'

Asciidoctor.convert_file 'document.adoc', doctype: :book, safe: :unsafe,
  attributes: 'toc=left sectnums source-highlighter=highlight.js'

与 CLI 相比，API 使您能够将处理分解为更小的步骤。通过这样做，您可以捕获单个步骤的结果，分析已解析的文档，在扩展中与文档模型进行交互，或者仅仅获得对处理的总体控制。

使用 API 时，我们讨论两个主要步骤。

加载 (load)

在此步骤中，AsciiDoc 内容会被解析成一个文档对象模型。该模型将 AsciiDoc 内容表示为一个 Ruby 对象树的内存层次结构。这些对象表示 AsciiDoc 文档中的元素，直至块级别，以及任何元数据，例如文档和块属性。

转换 (convert)

在此步骤中，使用转换器将先前准备好的文档对象模型转换为指定的输出格式。与转换器协调，处理器将文档对象模型中的每个节点传递给转换器进行转换。然后将结果组合起来，并根据传递给 API 的选项进行返回或写入文件。

您可以使用 API 将这两个步骤一起执行（类似于 CLI），使用 convert 和 convert_file，或者分别使用 load 和 load_file，然后调用文档对象上的 #convert。API 可以加载和转换 AsciiDoc 文件（load_file 和 convert_file）或字符串（load 和 convert）。API 入口点部分更详细地介绍了这些方法。

API 是在应用程序或集成库中与 Asciidoctor 交互的主要方式。通过使用 API，您可以避免通过子进程调用 Asciidoctor。您会发现它还为您提供了比 CLI 所提供的更多的处理控制。API 也是脚本中有用的工具，在脚本中，您可能需要深入研究扩展允许您访问的文档模型之外的内容。它在开发扩展方面也起着至关重要的作用。

让我们通过要求 Asciidoctor 库来学习如何开始使用 API。

从 require 开始

要开始使用 Asciidoctor API，您首先需要安装 gem。该 gem 同时提供了 CLI 和 API。事实上，CLI 使用 API 来处理 AsciiDoc 转换。

虽然使用 CLI 时，您使用 asciidoctor 命令与 Asciidoctor 交互，但在使用 API 时，您使用 Asciidoctor 模块上的方法与 Asciidoctor 交互。

为了使 Asciidoctor 模块在 Ruby 脚本或应用程序中可用，您必须使用 Ruby 的 require 函数要求 asciidoctor gem。

require 'asciidoctor'

此语句即可将 Asciidoctor 中的所有公共 API 提供给您的 Ruby 代码。例如，我们可以使用以下语句检查 Ruby 请求的是哪个版本的 Asciidoctor。

puts Asciidoctor::VERSION
# => 2.0.26

如果 require 语句失败，请检查以确保您已安装 gem（并在 GEM_PATH 上可用）。

API 入口点

CLI 主要用于转换 AsciiDoc。虽然 API 也可以做到这一点，但它还可以做更多。API 不仅仅是转换 AsciiDoc，它还允许您将 AsciiDoc 加载到文档模型中。然后，您可以将文档模型转换为输出格式，或者暂停以分析或修改其结构。

Asciidoctor API 中有四个主要入口点。

Asciidoctor.load

将 AsciiDoc 源（直至块级别）解析为 Asciidoctor::Document 对象。

Asciidoctor.load_file

将 AsciiDoc 源文件的内容（直至块级别）解析为 Asciidoctor::Document 对象。

Asciidoctor.convert

解析 AsciiDoc 源并将其转换为由指定后端确定的输出格式。

Asciidoctor.convert_file

解析 AsciiDoc 源文件内容并将其转换为由指定后端确定的输出格式。

如果您正在处理文件，通常会使用以 _file 结尾的方法。否则，您将使用其补充方法，该方法接受 String、String 数组或 IO 对象。

默认情况下，转换方法的输出遵循输入。如果您转换字符串，该方法将输出字符串。如果您转换文件，该方法将输出到文件。但是，这些默认值可以使用选项（例如 :to_file）进行更改。

调用 Asciidoctor 时，您可以使用 API 访问 控制处理的附加选项，这些选项在使用 CLI 时不可用。例如，您可以传入扩展、仅解析标题、启用源映射或编目资源。

除了主要入口点之外，API 还提供了一种注册和开发扩展的机制。要了解有关扩展的更多信息，请参阅扩展。

下一步