gregwar / rst
PHP library to parse reStructuredText documents
Installs: 167 641
Dependents: 16
Suggesters: 4
Security: 1
Stars: 94
Watchers: 11
Forks: 22
Open Issues: 13
Requires
- php: >=5.3.0
- symfony/polyfill-mbstring: ^1.12
Requires (Dev)
- phpunit/phpunit: ^6.4
README
PHP library to parse reStructuredText document
Usage
The parser can be used this way:
<?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> */
For more information, you can have a look at test/document/document.rst
and its result
test/document/document.html
Using the builder
The builder is another tool that will parses a whole tree of documents and generates an output directory containing files.
You can simply use it with:
<?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.
You can use those methods on it to customize the build:
copy($source, $destination)
: copy the$source
file or directory to the$destination
file or directory of the buildmkdir($directory)
: create the$directory
in build directoryaddHook($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 wantaddBeforeHook($function)
: adds an hook that will be called before parsing the document, the parser will be passed as a parameter
Abort on error
In some situation you want the build to continue even if there is some errors, like missing references:
<?php // Using parser $parser->getEnvironment()->getErrorManager()->abortOnError(false); // Using builder $builder->getErrorManager()->abortOnError(false);
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.
You can then redefine one of the following method:
processAction()
if your directive simply tweak the document without modifying the nodesprocessNode()
if your directive is adding a nodeprocess()
if your directive is tweaking the node that just follows it
See Directive.php
for more information
Step 2: Register your directive
You can register your directive by directly calling registerDirective()
on your
Parser
object.
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
License
This library is under MIT license