https://github.com/gregwar/rst
PHP library to parse reStructuredText documents
https://github.com/gregwar/rst
library parser php restructuredtext restructuredtext-parser rst
Last synced: 9 months ago
JSON representation
PHP library to parse reStructuredText documents
- Host: GitHub
- URL: https://github.com/gregwar/rst
- Owner: Gregwar
- License: mit
- Created: 2013-06-18T21:09:20.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2024-10-03T15:18:03.000Z (over 1 year ago)
- Last Synced: 2025-04-08T14:09:36.562Z (9 months ago)
- Topics: library, parser, php, restructuredtext, restructuredtext-parser, rst
- Language: PHP
- Homepage:
- Size: 287 KB
- Stars: 95
- Watchers: 10
- Forks: 22
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# RST
[](https://travis-ci.org/Gregwar/RST)
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=YUXRLWHQSWS6L)
PHP library to parse reStructuredText document
## Usage
The parser can be used this way:
```php
`_
';
// Parse it
$document = $parser->parse($rst);
// Render it
echo $document;
/* Will output, in HTML mode:
Hello world
What is it?
This is a RST document!
Where can I get it?
You can get it on the GitHub page
*/
```
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
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
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