RST
, (*1)
PHP library to parse reStructuredText document, (*2)
Usage
The parser can be used this way:, (*3)
<?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>
Hello world
<a id="title.1.1"></a>
What is it?
This is a RST document!, (*4)
<a id="title.1.2"></a>
Where can I get it?
You can get it on the GitHub page, (*5)
*/
For more information, you can have a look at test/document/document.rst and its result
test/document/document.html, (*6)
Using the builder
The builder is another tool that will parses a whole tree of documents and generates
an output directory containing files., (*7)
You can simply use it with:, (*8)
<?php
$builder = new Gregwar\RST\Builder;
$builder->build('input', 'output');
It will parses all the files in the input directory, starting with index.rst and
scanning for dependencies references and generates you target files in the output
directory. Default format is HTML., (*9)
You can use those methods on it to customize the build:, (*10)
-
copy($source, $destination): copy the $source file or directory to the $destination
file or directory of the build
-
mkdir($directory): create the $directory in build directory
-
addHook($function): adds an hook that will be called after each document is parsed, this
hook will be called with the $document as parameter and can then tweak it as you want
-
addBeforeHook($function): adds an hook that will be called before parsing the
document, the parser will be passed as a parameter
Writing directives
Step 1: Extends the Directive class
Write your own class that extends the Gregwar\RST\Directive class, and define the
method getName() that return the directive name., (*11)
You can then redefine one of the following method:, (*12)
-
processAction() if your directive simply tweak the document without modifying the nodes
-
processNode() if your directive is adding a node
-
process() if your directive is tweaking the node that just follows it
See Directive.php for more information, (*13)
Step 2: Register your directive
You can register your directive by directly calling registerDirective() on your
Parser object., (*14)
Else, you will have to also create your own kernel by extending the Kernel class
and adding your own logic to define extra directives, see Kernel.php for more information.
Then, pass the kernel when constructing the Parser or the Builder, (*15)
License
This library is under MIT license, (*16)
Wallogit.com
