From 8a54678d634dfb8bd1519cca2627d68e61b285f4 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Mon, 24 Apr 2017 10:50:18 +0200
Subject: [PATCH 1/3] Added an article about ExpressionLanguage AST

---
 components/expression_language.rst     |  6 +++++
 components/expression_language/ast.rst | 33 ++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 components/expression_language/ast.rst

diff --git a/components/expression_language.rst b/components/expression_language.rst
index ad7f3f924f6..dd3b0ff57f4 100644
--- a/components/expression_language.rst
+++ b/components/expression_language.rst
@@ -112,6 +112,12 @@ Caching
 The component provides some different caching strategies, read more about them
 in :doc:`/components/expression_language/caching`.
 
+AST Dumping and Editing
+-----------------------
+
+The AST (*Abstract Syntax Tree*) of expressions can be dumped and manipulated
+as explained in :doc:`/components/expression_language/ast`.
+
 Learn More
 ----------
 
diff --git a/components/expression_language/ast.rst b/components/expression_language/ast.rst
new file mode 100644
index 00000000000..4d1a03d1a5b
--- /dev/null
+++ b/components/expression_language/ast.rst
@@ -0,0 +1,33 @@
+.. index::
+    single: AST; ExpressionLanguage
+
+Dumping and Manipulating the AST of Expressions
+===============================================
+
+In computer science, `AST`_ (*Abstract Syntax Trees*) are a tree representation
+of the structure of source code written in a programming language. The
+expressions created with the ExpressionLanguage component are strings, which
+make them difficult to manipulate or inspect.
+
+A better approach is to dump the AST of those expressions using the ``dump()``
+method. This turns the original string expression into a set of PHP classes
+describing the operations of that expression::
+
+    use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
+
+    $language = new ExpressionLanguage();
+    $ast = $language->dump('1 + 2');
+    // $ast = new BinaryNode('+', new ConstantNode(1), new ConstantNode(2));
+
+    $ast = $language->dump('"a" not in ["a", "b"]');
+    // $ast = new BinaryNode('not in', new ConstantNode('a'), new ArrayNode(new ConstantNode('a'), new ConstantNode('b')));
+
+    $ast = $language->dump('foo[0]');
+    // $ast = new GetAttrNode(new NameNode('foo'), new ConstantNode(0));
+
+Manipulating the AST
+--------------------
+
+.. TODO: https://github.com/symfony/symfony/pull/19060
+
+.. _`AST`: https://en.wikipedia.org/wiki/Abstract_syntax_tree

From bc8057f2e8c28c6b18691c61d83f23c7d9aef6a2 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Mon, 24 Apr 2017 11:45:56 +0200
Subject: [PATCH 2/3] Finished the first draft of the article

---
 components/expression_language/ast.rst | 44 +++++++++++++++++---------
 1 file changed, 29 insertions(+), 15 deletions(-)

diff --git a/components/expression_language/ast.rst b/components/expression_language/ast.rst
index 4d1a03d1a5b..7c89ff0ba3e 100644
--- a/components/expression_language/ast.rst
+++ b/components/expression_language/ast.rst
@@ -4,30 +4,44 @@
 Dumping and Manipulating the AST of Expressions
 ===============================================
 
-In computer science, `AST`_ (*Abstract Syntax Trees*) are a tree representation
-of the structure of source code written in a programming language. The
-expressions created with the ExpressionLanguage component are strings, which
-make them difficult to manipulate or inspect.
+In computer science, `AST`_ (*Abstract Syntax Trees*) is *"a tree representation
+of the structure of source code written in a programming language"*.
 
-A better approach is to dump the AST of those expressions using the ``dump()``
-method. This turns the original string expression into a set of PHP classes
-describing the operations of that expression::
+Manipulating or inspecting the expressions created with the ExpressionLanguage
+component is difficult because they are plain strings. A better approach is to
+turn those expressions into an AST, which is a set of nodes that contain PHP
+classes.
+
+Dumping the AST
+---------------
+
+Call the ``getNodes()`` method after parsing any expression to get its AST::
 
     use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
 
-    $language = new ExpressionLanguage();
-    $ast = $language->dump('1 + 2');
-    // $ast = new BinaryNode('+', new ConstantNode(1), new ConstantNode(2));
+    $ast = (new ExpressionLanguage())
+        ->parse('1 + 2')
+        ->getNodes()
+    ;
 
-    $ast = $language->dump('"a" not in ["a", "b"]');
-    // $ast = new BinaryNode('not in', new ConstantNode('a'), new ArrayNode(new ConstantNode('a'), new ConstantNode('b')));
+    // dump the AST nodes for inspection
+    var_dump($ast);
 
-    $ast = $language->dump('foo[0]');
-    // $ast = new GetAttrNode(new NameNode('foo'), new ConstantNode(0));
+    // dump the AST nodes as a string representation
+    $astAsString = $ast->dump();
 
 Manipulating the AST
 --------------------
 
-.. TODO: https://github.com/symfony/symfony/pull/19060
+The nodes of the AST can also be dumped into a PHP array of nodes to allow
+manipulating them. Call the ``toArray()`` method to turn the AST into an array::
+
+    // ...
+
+    $astAsArray = (new ExpressionLanguage())
+        ->parse('1 + 2')
+        ->getNodes()
+        ->toArray()
+    ;
 
 .. _`AST`: https://en.wikipedia.org/wiki/Abstract_syntax_tree

From bfb54e24703eb10359ccec8d46cd380b89da875c Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Wed, 3 May 2017 12:48:43 +0200
Subject: [PATCH 3/3] Fixes and rewords

---
 components/expression_language/ast.rst | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/components/expression_language/ast.rst b/components/expression_language/ast.rst
index 7c89ff0ba3e..02bd0be8c4b 100644
--- a/components/expression_language/ast.rst
+++ b/components/expression_language/ast.rst
@@ -1,21 +1,22 @@
 .. index::
     single: AST; ExpressionLanguage
+    single: AST; Abstract Syntax Tree
 
 Dumping and Manipulating the AST of Expressions
 ===============================================
 
-In computer science, `AST`_ (*Abstract Syntax Trees*) is *"a tree representation
-of the structure of source code written in a programming language"*.
-
 Manipulating or inspecting the expressions created with the ExpressionLanguage
 component is difficult because they are plain strings. A better approach is to
-turn those expressions into an AST, which is a set of nodes that contain PHP
-classes.
+turn those expressions into an AST. In computer science, `AST`_ (*Abstract
+Syntax Tree*) is *"a tree representation of the structure of source code written
+in a programming language"*. In Symfony, a ExpressionLanguage AST is a set of
+nodes that contain PHP classes representing the given expression.
 
 Dumping the AST
 ---------------
 
-Call the ``getNodes()`` method after parsing any expression to get its AST::
+Call the :method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::getNodes`
+method after parsing any expression to get its AST::
 
     use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
 
@@ -34,7 +35,8 @@ Manipulating the AST
 --------------------
 
 The nodes of the AST can also be dumped into a PHP array of nodes to allow
-manipulating them. Call the ``toArray()`` method to turn the AST into an array::
+manipulating them. Call the :method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::toArray`
+method to turn the AST into an array::
 
     // ...