README

用于解析 reStructuredText 文档的 PHP 库

用法

解析器可以这样使用

<?php

$parser = new Gregwar\RST\Parser;

// RST document
$rst = ' 
Hello world
===========

What is it?
----------
This is a **RST** document!

Where can I get it?
-------------------
You can get it on the `GitHub page <https://github.com/Gregwar/RST>`_
';

// Parse it
$document = $parser->parse($rst);

// Render it
echo $document;
/* Will output, in HTML mode:
<a id="title.1"></a><h1>Hello world</h1>
<a id="title.1.1"></a><h2>What is it?</h2>
<p>This is a <b>RST</b> document!</p>
<a id="title.1.2"></a><h2>Where can I get it?</h2>
<p>You can get it on the <a href="https://github.com/Gregwar/RST">GitHub page</a></p>
*/

更多信息，请查看 test/document/document.rst 及其结果 test/document/document.html

使用构建器

构建器是另一个工具，它将解析整个文档树并生成包含文件的输出目录。

您可以使用以下方式简单使用它

<?php

$builder = new Gregwar\RST\Builder;
$builder->build('input', 'output');

它将解析 input 目录中的所有文件，从 index.rst 开始，扫描依赖项引用，并在 output 目录中生成目标文件。默认格式是 HTML。

您可以使用以下方法来定制构建

• copy($source, $destination): 将 $source 文件或目录复制到构建的 $destination 文件或目录
• mkdir($directory): 在构建目录中创建 $directory
• addHook($function): 添加一个钩子，在解析每个文档之后调用，此钩子将以 $document 作为参数，然后您可以按需修改它
• addBeforeHook($function): 添加一个钩子，在解析文档之前调用，解析器将作为参数传递

错误时终止

在某些情况下，您可能希望即使有错误（例如缺少引用）也要继续构建

<?php

// Using parser
$parser->getEnvironment()->getErrorManager()->abortOnError(false);

// Using builder
$builder->getErrorManager()->abortOnError(false);

编写指令

步骤 1: 扩展指令类

编写一个扩展 Gregwar\RST\Directive 类的自定义类，并定义返回指令名称的 getName() 方法。

然后您可以重新定义以下方法之一

• processAction() 如果您的指令仅调整文档而不修改节点
• processNode() 如果您的指令是添加节点
• process() 如果您的指令是调整紧随其后的节点

有关更多信息，请参阅 Directive.php

步骤 2: 注册您的指令

您可以直接在您的 Parser 对象上调用 registerDirective() 来注册您的指令。

否则，您还必须创建自己的内核，通过扩展 Kernel 类并添加自己的逻辑来定义额外的指令，有关更多信息，请参阅 Kernel.php。然后，在构造 Parser 或 Builder 时传递内核

许可协议

此库受 MIT 许可协议的约束