Zeta Components - high quality PHP components

Zeta Components Manual :: Docs For Class ezcDocumentRst

Document::ezcDocumentRst

Class ezcDocumentRst

Document handler for RST text documents.

RST (ReStructured Text) is a text based markup language developed inside the docutils project, with a rather complete description of the markup language:

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

The basic RST syntax can be extended with so called directives, which can contain user specific markup blocks handled by external applications or custom scripts. This class does not support all of the directives known from docutils yet, but you may register custom additional ones.

RST can be converted forth and back between Docbook and RST. Additionally you may register cusom visitors for the abstract sysntax tree (AST) the RST parser creates, to directly convert the AST into other languages then Docbook. Two different visitors for XHTML are already implemented in the component:

  • ezcDocumentRstXhtmlVisitor
  • ezcDocumentRstXhtmlBodyVisitor
A basic conversion from a RST document to a Docbook document looks like:

  1.   $document = new ezcDocumentRst();
  2.   $document->loadFile( 'my_rst_doc.txt' );
  3.   $docbook = $document->getAsDocbook();
  4.   echo $docbook->save();

Additional directives, which are implemented by extending from the ezcDocumentRstDirective class, can be registerd before the conversion:

  1.   $document = new ezcDocumentRst();
  2.   $document->registerDirective( 'address', 'myAddressDirective' );
  3.   $document->loadString( <<<EORST
  4.   Address example
  5.   ===============
  6.  
  7.   .. address:: John Doe
  8.       :street: Some Lane 42
  9.   EORST
  10.   );
  11.  
  12.   $docbook = $document->getAsDocbook();
  13.   echo $docbook->save();

This class can also read docbook documents (ezcDocumentDocbook) and convert it back to RST, which then works like:

  1.   $docbook = new ezcDocumentDocbook();
  2.   $docbook->loadFile( 'docbook.xml' );
  3.  
  4.   $rst = new ezcDocumentRst();
  5.   $rst->createFromDocbook( $docbook );
  6.  
  7.   echo $rst->save();

Source for this file: /Document/src/document/rst.php

Implements interfaces:

ezcDocument
   |
   --ezcDocumentRst
Version:   //autogen//

Member Variables

protected ezcDocumentRstDocumentNode $ast
Asbtract syntax tree.

The internal representation of RST documents.
protected string $contents
Plain RST contents as a string
protected array $directives = array(
'include' => 'ezcDocumentRstIncludeDirective',
'contents' => 'ezcDocumentRstContentsDirective',
'image' => 'ezcDocumentRstImageDirective',
'figure' => 'ezcDocumentRstFigureDirective',
'attention' => 'ezcDocumentRstAttentionDirective',
'warning' => 'ezcDocumentRstWarningDirective',
'danger' => 'ezcDocumentRstDangerDirective',
'notice' => 'ezcDocumentRstNoticeDirective',
'note' => 'ezcDocumentRstNoteDirective',
)
Registered directives

Directives are special RST element, which are documented at: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives

Directives are the best entry point for custom rules, and you may register custom directive classes using the class method registerDirective().
protected array $roles = array(
'emphasis' => 'ezcDocumentRstEmphasisTextRole',
'literal' => 'ezcDocumentRstLiteralTextRole',
'strong' => 'ezcDocumentRstStrongTextRole',
'subscript' => 'ezcDocumentRstSubscriptTextRole',
'sub' => 'ezcDocumentRstSubscriptTextRole',
'superscript' => 'ezcDocumentRstSuperscriptTextRole',
'super' => 'ezcDocumentRstSuperscriptTextRole',
'sup' => 'ezcDocumentRstSuperscriptTextRole',
'title_reference' => 'ezcDocumentRstTitleReferenceTextRole',
'title' => 'ezcDocumentRstTitleReferenceTextRole',
't' => 'ezcDocumentRstTitleReferenceTextRole',
)
Registered interpreted text role handlers

Interpreted text roles are special RST element, which are documented at: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#interpreted-text

Interpreted text roles are the best entry point for custom rules for inline markup. You can register custom text role using the class method registerRole().

Inherited Member Variables

From ezcDocument
protected ezcDocument::$errors
protected ezcDocument::$options
protected ezcDocument::$path

Method Summary

public void createFromDocbook( $document )
Create document from docbook document
public ezcDocumentDocbook getAsDocbook( )
Return document compiled to the docbook format
public ezcDocumentXhtml getAsXhtml( )
Return document compiled to the HTML format
public string getDirectiveHandler( $name )
Get directive handler
public string getRoleHandler( $name )
Get text role handler
public void loadString( $string )
Create document from input string
public void registerDirective( $name , $class )
Register directive handler
public void registerRole( $name , $class )
Register text role handler
public string save( )
Return document as string
public mixed validateFile( $file )
Validate the input file
public mixed validateString( $string )
Validate the input string

Inherited Methods

From ezcDocument
public ezcDocument ezcDocument::__construct()
Construct new document
public abstract void ezcDocument::createFromDocbook()
Create document from docbook document
public abstract ezcDocumentDocbook ezcDocument::getAsDocbook()
Return document compiled to the docbook format
public array ezcDocument::getErrors()
Return list of errors occured during visiting the document.
public string ezcDocument::getPath()
Get document base path
public void ezcDocument::loadFile()
Create document from file
public abstract void ezcDocument::loadString()
Create document from input string
public abstract string ezcDocument::save()
Return document as string
public void ezcDocument::setPath()
Set document base path
public void ezcDocument::triggerError()
Trigger visitor error

Methods

createFromDocbook

void createFromDocbook( ezcDocumentDocbook $document )

Create document from docbook document

A document of the docbook format is provided and the internal document structure should be created out of this.

This method is required for all formats to have one central format, so that each format can be compiled into each other format using docbook as an intermediate format.

You may of course just call an existing converter for this conversion.

Parameters:
Name Type Description
$document ezcDocumentDocbook
Redefinition of:
Method Description
ezcDocument::createFromDocbook() Create document from docbook document

getAsDocbook

ezcDocumentDocbook getAsDocbook( )

Return document compiled to the docbook format

The internal document structure is compiled to the docbook format and the resulting docbook document is returned.

This method is required for all formats to have one central format, so that each format can be compiled into each other format using docbook as an intermediate format.

You may of course just call an existing converter for this conversion.

Redefinition of:
Method Description
ezcDocument::getAsDocbook() Return document compiled to the docbook format

getAsXhtml

ezcDocumentXhtml getAsXhtml( )

Return document compiled to the HTML format

The internal document structure is compiled to the HTML format and the resulting HTML document is returned.

This is an optional interface for document markup languages which support a direct transformation to HTML as a shortcut.

Implementation of:
Method Description
ezcDocumentXhtmlConversion::getAsXhtml() Return document compiled to the XHTML format

getDirectiveHandler

string getDirectiveHandler( string $name )

Get directive handler

Get directive handler class name for the specified name.

Parameters:
Name Type Description
$name string

getRoleHandler

string getRoleHandler( string $name )

Get text role handler

Get text role handler class name for the specified name.

Parameters:
Name Type Description
$name string

loadString

void loadString( string $string )

Create document from input string

Create a document of the current type handler class and parse it into a usable internal structure.

Parameters:
Name Type Description
$string string
Redefinition of:
Method Description
ezcDocument::loadString() Create document from input string

registerDirective

void registerDirective( string $name , string $class )

Register directive handler

Register a custom directive handler for special directives or overwrite existing directive handlers. The directives are specified by its (lowercase) name and the class name, which should handle the directive and extend from ezcDocumentRstDirective.

Parameters:
Name Type Description
$name string
$class string

registerRole

void registerRole( string $name , string $class )

Register text role handler

Register a custom text role handler for special text roles or overwrite existing text role handlers. The text roles are specified by its (lowercase) name and the class name, which should handle the text role and extend from ezcDocumentRstTextRole.

Parameters:
Name Type Description
$name string
$class string

save

string save( )

Return document as string

Serialize the document to a string an return it.

Redefinition of:
Method Description
ezcDocument::save() Return document as string

validateFile

mixed validateFile( string $file )

Validate the input file

Validate the input file against the specification of the current document format.

Returns true, if the validation succeded, and an array with ezcDocumentValidationError objects otherwise.

Parameters:
Name Type Description
$file string
Implementation of:
Method Description
ezcDocumentValidation::validateFile() Validate the input file

validateString

mixed validateString( string $string )

Validate the input string

Validate the input string against the specification of the current document format.

Returns true, if the validation succeded, and an array with ezcDocumentValidationError objects otherwise.

Parameters:
Name Type Description
$string string
Implementation of:
Method Description
ezcDocumentValidation::validateString() Validate the input string
Documentation generated by phpDocumentor 1.4.3