diff --git a/components/expression_language/index.rst b/components/expression_language/index.rst new file mode 100644 index 00000000000..e6eb657b4be --- /dev/null +++ b/components/expression_language/index.rst @@ -0,0 +1,8 @@ +Expression Language +=================== + +.. toctree:: + :maxdepth: 2 + + introduction + syntax diff --git a/components/expression_language/introduction.rst b/components/expression_language/introduction.rst new file mode 100644 index 00000000000..a7f474c732a --- /dev/null +++ b/components/expression_language/introduction.rst @@ -0,0 +1,55 @@ +.. index:: + single: Expressions + Single: Components; Expression Language + +The ExpressionLanguage Component +================================= + + The ExpressionLanguage component provides an engine that can compile and + evaluate expressions. An expression is a one-liner that returns a value + (mostly, but not limited to, Booleans). + +.. versionadded:: 2.4 + The ExpressionLanguage component was new in Symfony 2.4. + +Installation +------------ + +You can install the component in 2 different ways: + +* Use the official Git repository (https://github.com/symfony/expression-language); +* :doc:`Install it via Composer ` (``symfony/expression-language`` on `Packagist`_). + +Usage +----- + +The ExpressionLanguage component can compile and evaluate expressions. +Expressions are one-liners which most of the time return a boolean, you can +compare them to the expression in an ``if`` statement. A simple example of an +expression is ``1 + 2``. You can also use more complicated expressions, such +as ``someArray[3].someMethod('bar')``. + +The component provides 2 ways to work with expressions: + +* **compile**: the expression is compiled to PHP, so it can be cached and + evaluated; +* **evaluation**: the expression is evaluated without being compiled to PHP. + +The main class of the component is +:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage`:: + + use Symfony\Component\ExpressionLanguage\ExpressionLanguage; + + $language = new ExpressionLanguage(); + + echo $language->evaluate('1 + 2'); // displays 3 + + echo $language->compile('1 + 2'); // displays (1 + 2) + +Expression Syntax +----------------- + +See ":doc:`/components/expression_language/syntax`" to learn the syntax of the +ExpressionLanguage component. + +.. _Packagist: https://packagist.org/packages/symfony/expression-language diff --git a/components/expression_language/syntax.rst b/components/expression_language/syntax.rst new file mode 100644 index 00000000000..7c3a59fccb9 --- /dev/null +++ b/components/expression_language/syntax.rst @@ -0,0 +1,98 @@ +.. index:: + single: Syntax; ExpressionLanguage + +The Expression Syntax +===================== + +The ExpressionLanguage component uses a specific syntax which is based on the +expression syntax of Twig. In this document, you can find all supported +syntaxes. + +Supported Literals +~~~~~~~~~~~~~~~~~~ + +The component supports: + +* **strings** - single and double quotes (e.g. ``'hello'``) +* **numbers** - e.g. ``103`` +* **arrays** - using twig notation (e.g. ``[1, 2]``) +* **hashes** - using twig notation (e.g. ``{ foo: 'bar' }``) +* **booleans** - ``true`` and ``false`` +* **null** - ``null`` + +Supported Operators +~~~~~~~~~~~~~~~~~~~ + +The component comes with a lot of operators: + +Arithmetic Operators +.................... + +* ``+`` (addition) +* ``-`` (subtraction) +* ``*`` (multiplication) +* ``/`` (division) +* ``%`` (modulus) +* ``**`` (pow) + +Assignment Operators +.................... + +* ``=`` + +Bitwise Operators +................. + +* ``&`` (and) +* ``|`` (or) +* ``^`` (xor) + +Comparison Operators +.................... + +* ``==`` (equal) +* ``===`` (identical) +* ``!=`` (not equal) +* ``!==`` (not identical) +* ``<`` (less than) +* ``>`` (greater than) +* ``<=`` (less than or equal to) +* ``>=`` (greater than or equal to) +* ``matches`` (regex match) + +.. tip:: + + To test if a string does *not* match a regex, use the logical ``not`` + operator in combination with the ``matches`` operator:: + + $language->evaluate('not "foo" matches "/bar/"'); // returns true + +Logical Operators +................. + +* ``not`` or ``!`` +* ``and`` or ``&&`` +* ``or`` or ``||`` + +String Operators +................ + +* ``~`` (concatenation) + +Array Operators +............... + +* ``in`` (contain) +* ``not in`` (does not contain) + +Numeric Operators +................. + +* ``..`` (range) + +Ternary Operators +................. + +* ``foo ? 'yes' : 'no'`` +* ``foo ?: 'no'`` (equal to ``foo ? foo : 'no'``) +* ``foo ? 'yes'`` (equal to ``foo ? 'yes' : ''``) diff --git a/components/index.rst b/components/index.rst index e5dffc58cd6..3cf769b6282 100644 --- a/components/index.rst +++ b/components/index.rst @@ -13,6 +13,7 @@ The Components dom_crawler dependency_injection/index event_dispatcher/index + expression_language/index filesystem finder form/index diff --git a/components/map.rst.inc b/components/map.rst.inc index a915310cde1..fb1055a6555 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -57,6 +57,11 @@ * :doc:`/components/event_dispatcher/generic_event` * :doc:`/components/event_dispatcher/immutable_dispatcher` +* :doc:`/components/expression_language/index` + + * :doc:`/components/expression_language/introduction` + * :doc:`/components/expression_language/syntax` + * **Filesystem** * :doc:`/components/filesystem`