From bbfc7d7aef2e8309c1b1927efe029dc0bb5ffdea Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Fri, 27 Apr 2012 17:40:57 +0200 Subject: [PATCH] renamed a doc file --- doc/hacking.rst | 140 ----------------------------------------------------- doc/internals.rst | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 140 insertions(+), 140 deletions(-) delete mode 100644 doc/hacking.rst create mode 100644 doc/internals.rst diff --git a/doc/hacking.rst b/doc/hacking.rst deleted file mode 100644 index 79a3c8d..0000000 --- a/doc/hacking.rst +++ /dev/null @@ -1,140 +0,0 @@ -Twig Internals -============== - -Twig is very extensible and you can easily hack it. Keep in mind that you -should probably try to create an extension before hacking the core, as most -features and enhancements can be done with extensions. This chapter is also -useful for people who want to understand how Twig works under the hood. - -How Twig works? ---------------- - -The rendering of a Twig template can be summarized into four key steps: - -* **Load** the template: If the template is already compiled, load it and go - to the *evaluation* step, otherwise: - - * First, the **lexer** tokenizes the template source code into small pieces - for easier processing; - * Then, the **parser** converts the token stream into a meaningful tree - of nodes (the Abstract Syntax Tree); - * Eventually, the *compiler* transforms the AST into PHP code; - -* **Evaluate** the template: It basically means calling the ``display()`` - method of the compiled template and passing it the context. - -The Lexer ---------- - -The lexer tokenizes a template source code into a token stream (each token is -an instance of ``Twig_Token``, and the stream is an instance of -``Twig_TokenStream``). The default lexer recognizes 13 different token types: - -* ``Twig_Token::BLOCK_START_TYPE``, ``Twig_Token::BLOCK_END_TYPE``: Delimiters for blocks (``{% %}``) -* ``Twig_Token::VAR_START_TYPE``, ``Twig_Token::VAR_END_TYPE``: Delimiters for variables (``{{ }}``) -* ``Twig_Token::TEXT_TYPE``: A text outside an expression; -* ``Twig_Token::NAME_TYPE``: A name in an expression; -* ``Twig_Token::NUMBER_TYPE``: A number in an expression; -* ``Twig_Token::STRING_TYPE``: A string in an expression; -* ``Twig_Token::OPERATOR_TYPE``: An operator; -* ``Twig_Token::PUNCTUATION_TYPE``: A punctuation sign; -* ``Twig_Token::INTERPOLATION_START_TYPE``, ``Twig_Token::INTERPOLATION_END_TYPE`` (as of Twig 1.5): Delimiters for string interpolation; -* ``Twig_Token::EOF_TYPE``: Ends of template. - -You can manually convert a source code into a token stream by calling the -``tokenize()`` of an environment:: - - $stream = $twig->tokenize($source, $identifier); - -As the stream has a ``__toString()`` method, you can have a textual -representation of it by echoing the object:: - - echo $stream."\n"; - -Here is the output for the ``Hello {{ name }}`` template: - -.. code-block:: text - - TEXT_TYPE(Hello ) - VAR_START_TYPE() - NAME_TYPE(name) - VAR_END_TYPE() - EOF_TYPE() - -.. note:: - - You can change the default lexer use by Twig (``Twig_Lexer``) by calling - the ``setLexer()`` method:: - - $twig->setLexer($lexer); - -The Parser ----------- - -The parser converts the token stream into an AST (Abstract Syntax Tree), or a -node tree (an instance of ``Twig_Node_Module``). The core extension defines -the basic nodes like: ``for``, ``if``, ... and the expression nodes. - -You can manually convert a token stream into a node tree by calling the -``parse()`` method of an environment:: - - $nodes = $twig->parse($stream); - -Echoing the node object gives you a nice representation of the tree:: - - echo $nodes."\n"; - -Here is the output for the ``Hello {{ name }}`` template: - -.. code-block:: text - - Twig_Node_Module( - Twig_Node_Text(Hello ) - Twig_Node_Print( - Twig_Node_Expression_Name(name) - ) - ) - -.. note:: - - The default parser (``Twig_TokenParser``) can be also changed by calling the - ``setParser()`` method:: - - $twig->setParser($parser); - -The Compiler ------------- - -The last step is done by the compiler. It takes a node tree as an input and -generates PHP code usable for runtime execution of the template. - -You can call the compiler by hand with the ``compile()`` method of an -environment:: - - $php = $twig->compile($nodes); - -The ``compile()`` method returns the PHP source code representing the node. - -The generated template for a ``Hello {{ name }}`` template reads as follows -(the actual output can differ depending on the version of Twig you are -using):: - - /* Hello {{ name }} */ - class __TwigTemplate_1121b6f109fe93ebe8c6e22e3712bceb extends Twig_Template - { - protected function doDisplay(array $context, array $blocks = array()) - { - // line 1 - echo "Hello "; - echo twig_escape_filter($this->env, $this->getContext($context, "name"), "ndex", null, true); - } - - // some more code - } - -.. note:: - - As for the lexer and the parser, the default compiler (``Twig_Compiler``) can - be changed by calling the ``setCompiler()`` method:: - - $twig->setCompiler($compiler); diff --git a/doc/internals.rst b/doc/internals.rst new file mode 100644 index 0000000..79a3c8d --- /dev/null +++ b/doc/internals.rst @@ -0,0 +1,140 @@ +Twig Internals +============== + +Twig is very extensible and you can easily hack it. Keep in mind that you +should probably try to create an extension before hacking the core, as most +features and enhancements can be done with extensions. This chapter is also +useful for people who want to understand how Twig works under the hood. + +How Twig works? +--------------- + +The rendering of a Twig template can be summarized into four key steps: + +* **Load** the template: If the template is already compiled, load it and go + to the *evaluation* step, otherwise: + + * First, the **lexer** tokenizes the template source code into small pieces + for easier processing; + * Then, the **parser** converts the token stream into a meaningful tree + of nodes (the Abstract Syntax Tree); + * Eventually, the *compiler* transforms the AST into PHP code; + +* **Evaluate** the template: It basically means calling the ``display()`` + method of the compiled template and passing it the context. + +The Lexer +--------- + +The lexer tokenizes a template source code into a token stream (each token is +an instance of ``Twig_Token``, and the stream is an instance of +``Twig_TokenStream``). The default lexer recognizes 13 different token types: + +* ``Twig_Token::BLOCK_START_TYPE``, ``Twig_Token::BLOCK_END_TYPE``: Delimiters for blocks (``{% %}``) +* ``Twig_Token::VAR_START_TYPE``, ``Twig_Token::VAR_END_TYPE``: Delimiters for variables (``{{ }}``) +* ``Twig_Token::TEXT_TYPE``: A text outside an expression; +* ``Twig_Token::NAME_TYPE``: A name in an expression; +* ``Twig_Token::NUMBER_TYPE``: A number in an expression; +* ``Twig_Token::STRING_TYPE``: A string in an expression; +* ``Twig_Token::OPERATOR_TYPE``: An operator; +* ``Twig_Token::PUNCTUATION_TYPE``: A punctuation sign; +* ``Twig_Token::INTERPOLATION_START_TYPE``, ``Twig_Token::INTERPOLATION_END_TYPE`` (as of Twig 1.5): Delimiters for string interpolation; +* ``Twig_Token::EOF_TYPE``: Ends of template. + +You can manually convert a source code into a token stream by calling the +``tokenize()`` of an environment:: + + $stream = $twig->tokenize($source, $identifier); + +As the stream has a ``__toString()`` method, you can have a textual +representation of it by echoing the object:: + + echo $stream."\n"; + +Here is the output for the ``Hello {{ name }}`` template: + +.. code-block:: text + + TEXT_TYPE(Hello ) + VAR_START_TYPE() + NAME_TYPE(name) + VAR_END_TYPE() + EOF_TYPE() + +.. note:: + + You can change the default lexer use by Twig (``Twig_Lexer``) by calling + the ``setLexer()`` method:: + + $twig->setLexer($lexer); + +The Parser +---------- + +The parser converts the token stream into an AST (Abstract Syntax Tree), or a +node tree (an instance of ``Twig_Node_Module``). The core extension defines +the basic nodes like: ``for``, ``if``, ... and the expression nodes. + +You can manually convert a token stream into a node tree by calling the +``parse()`` method of an environment:: + + $nodes = $twig->parse($stream); + +Echoing the node object gives you a nice representation of the tree:: + + echo $nodes."\n"; + +Here is the output for the ``Hello {{ name }}`` template: + +.. code-block:: text + + Twig_Node_Module( + Twig_Node_Text(Hello ) + Twig_Node_Print( + Twig_Node_Expression_Name(name) + ) + ) + +.. note:: + + The default parser (``Twig_TokenParser``) can be also changed by calling the + ``setParser()`` method:: + + $twig->setParser($parser); + +The Compiler +------------ + +The last step is done by the compiler. It takes a node tree as an input and +generates PHP code usable for runtime execution of the template. + +You can call the compiler by hand with the ``compile()`` method of an +environment:: + + $php = $twig->compile($nodes); + +The ``compile()`` method returns the PHP source code representing the node. + +The generated template for a ``Hello {{ name }}`` template reads as follows +(the actual output can differ depending on the version of Twig you are +using):: + + /* Hello {{ name }} */ + class __TwigTemplate_1121b6f109fe93ebe8c6e22e3712bceb extends Twig_Template + { + protected function doDisplay(array $context, array $blocks = array()) + { + // line 1 + echo "Hello "; + echo twig_escape_filter($this->env, $this->getContext($context, "name"), "ndex", null, true); + } + + // some more code + } + +.. note:: + + As for the lexer and the parser, the default compiler (``Twig_Compiler``) can + be changed by calling the ``setCompiler()`` method:: + + $twig->setCompiler($compiler); -- 1.7.2.5