Skip to content

Commit 799b2c6

Browse files
weaverryanweaverryan
committed
Merge pull request #3044 from WouterJ/document_expressionlanguage
[WIP] Add docs for ExpressionLanguage component
2 parents 2e91170 + 8fe9fd6 commit 799b2c6

File tree

5 files changed

+167
-0
lines changed

5 files changed

+167
-0
lines changed

‎components/expression_language/index.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Expression Language
2+
===================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
introduction
8+
syntax

‎components/expression_language/introduction.rst

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
.. index::
2+
single: Expressions
3+
Single: Components; Expression Language
4+
5+
The ExpressionLanguage Component
6+
=================================
7+
8+
The ExpressionLanguage component provides an engine that can compile and
9+
evaluate expressions. An expression is a one-liner that returns a value
10+
(mostly, but not limited to, Booleans).
11+
12+
.. versionadded:: 2.4
13+
The ExpressionLanguage component was new in Symfony 2.4.
14+
15+
Installation
16+
------------
17+
18+
You can install the component in 2 different ways:
19+
20+
* Use the official Git repository (https://github.com/symfony/expression-language);
21+
* :doc:`Install it via Composer </components/using_components>` (``symfony/expression-language`` on `Packagist`_).
22+
23+
Usage
24+
-----
25+
26+
The ExpressionLanguage component can compile and evaluate expressions.
27+
Expressions are one-liners which most of the time return a boolean, you can
28+
compare them to the expression in an ``if`` statement. A simple example of an
29+
expression is ``1 + 2``. You can also use more complicated expressions, such
30+
as ``someArray[3].someMethod('bar')``.
31+
32+
The component provides 2 ways to work with expressions:
33+
34+
* **compile**: the expression is compiled to PHP, so it can be cached and
35+
evaluated;
36+
* **evaluation**: the expression is evaluated without being compiled to PHP.
37+
38+
The main class of the component is
39+
:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage`::
40+
41+
use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
42+
43+
$language = new ExpressionLanguage();
44+
45+
echo $language->evaluate('1 + 2'); // displays 3
46+
47+
echo $language->compile('1 + 2'); // displays (1 + 2)
48+
49+
Expression Syntax
50+
-----------------
51+
52+
See ":doc:`/components/expression_language/syntax`" to learn the syntax of the
53+
ExpressionLanguage component.
54+
55+
.. _Packagist: https://packagist.org/packages/symfony/expression-language

‎components/expression_language/syntax.rst

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
.. index::
2+
single: Syntax; ExpressionLanguage
3+
4+
The Expression Syntax
5+
=====================
6+
7+
The ExpressionLanguage component uses a specific syntax which is based on the
8+
expression syntax of Twig. In this document, you can find all supported
9+
syntaxes.
10+
11+
Supported Literals
12+
~~~~~~~~~~~~~~~~~~
13+
14+
The component supports:
15+
16+
* **strings** - single and double quotes (e.g. ``'hello'``)
17+
* **numbers** - e.g. ``103``
18+
* **arrays** - using twig notation (e.g. ``[1, 2]``)
19+
* **hashes** - using twig notation (e.g. ``{ foo: 'bar' }``)
20+
* **booleans** - ``true`` and ``false``
21+
* **null** - ``null``
22+
23+
Supported Operators
24+
~~~~~~~~~~~~~~~~~~~
25+
26+
The component comes with a lot of operators:
27+
28+
Arithmetic Operators
29+
....................
30+
31+
* ``+`` (addition)
32+
* ``-`` (subtraction)
33+
* ``*`` (multiplication)
34+
* ``/`` (division)
35+
* ``%`` (modulus)
36+
* ``**`` (pow)
37+
38+
Assignment Operators
39+
....................
40+
41+
* ``=``
42+
43+
Bitwise Operators
44+
.................
45+
46+
* ``&`` (and)
47+
* ``|`` (or)
48+
* ``^`` (xor)
49+
50+
Comparison Operators
51+
....................
52+
53+
* ``==`` (equal)
54+
* ``===`` (identical)
55+
* ``!=`` (not equal)
56+
* ``!==`` (not identical)
57+
* ``<`` (less than)
58+
* ``>`` (greater than)
59+
* ``<=`` (less than or equal to)
60+
* ``>=`` (greater than or equal to)
61+
* ``matches`` (regex match)
62+
63+
.. tip::
64+
65+
To test if a string does *not* match a regex, use the logical ``not``
66+
operator in combination with the ``matches`` operator::
67+
68+
$language->evaluate('not "foo" matches "/bar/"'); // returns true
69+
70+
Logical Operators
71+
.................
72+
73+
* ``not`` or ``!``
74+
* ``and`` or ``&&``
75+
* ``or`` or ``||``
76+
77+
String Operators
78+
................
79+
80+
* ``~`` (concatenation)
81+
82+
Array Operators
83+
...............
84+
85+
* ``in`` (contain)
86+
* ``not in`` (does not contain)
87+
88+
Numeric Operators
89+
.................
90+
91+
* ``..`` (range)
92+
93+
Ternary Operators
94+
.................
95+
96+
* ``foo ? 'yes' : 'no'``
97+
* ``foo ?: 'no'`` (equal to ``foo ? foo : 'no'``)
98+
* ``foo ? 'yes'`` (equal to ``foo ? 'yes' : ''``)

‎components/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ The Components
1313
dependency_injection/index
1414
dom_crawler
1515
event_dispatcher/index
16+
expression_language/index
1617
filesystem
1718
finder
1819
form/index

‎components/map.rst.inc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,11 @@
5757
* :doc:`/components/event_dispatcher/generic_event`
5858
* :doc:`/components/event_dispatcher/immutable_dispatcher`
5959

60+
* :doc:`/components/expression_language/index`
61+
62+
* :doc:`/components/expression_language/introduction`
63+
* :doc:`/components/expression_language/syntax`
64+
6065
* **Filesystem**
6166

6267
* :doc:`/components/filesystem`

0 commit comments

Comments
 (0)