PHP HTML CSS
Switch branches/tags
Clone or download
Permalink
Failed to load latest commit information.
Directives Adding raw directive Sep 7, 2017
HTML Adding raw directive Sep 7, 2017
LaTeX Add missing visibility on PHP methods Feb 18, 2017
Nodes Adding raw directive Sep 7, 2017
References Adding ref, alias for doc Oct 14, 2014
test Auto-detecting title levels Oct 14, 2014
tests Adding an option to enable/disable relative URLs (see #39) Oct 5, 2017
.gitignore Ignore the vendor directory. Feb 14, 2015
.travis.yml Removing PHP 5.3.3 from Travis (openssl issue) May 25, 2016
Builder.php Adding an option to enable/disable relative URLs (see #39) Oct 5, 2017
Directive.php Fixing quote blocks following directives Sep 10, 2013
Document.php Adding redirection-title:: directive May 13, 2014
Environment.php Adding an option to enable/disable relative URLs (see #39) Oct 5, 2017
ErrorManager.php Fixes on errorManager Sep 30, 2013
Kernel.php Adding raw directive Sep 7, 2017
LICENSE Adding LICENSE & improving README Jun 21, 2013
Metas.php Adding TOCs & parents in meta Jul 8, 2013
Parser.php Allow file inclusion to be jailed within a directory or disabled outr… Oct 31, 2016
README.md abort on error (see #36) Dec 20, 2016
Reference.php Comments Sep 11, 2013
Span.php Adding an option to enable/disable relative URLs (see #39) Oct 5, 2017
SubDirective.php Ensure title state isn't remembered between parses. May 13, 2016
autoload.php First version Jun 18, 2013
composer.json Adding composer Jul 4, 2013
phpunit.xml Adding builder test Jul 5, 2013

README.md

RST

Build status paypal

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

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

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