[WIP] Add docs for ExpressionLanguage component #3044
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| Expression Language | ||
| =================== | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 2 | ||
|
|
||
| introduction | ||
| syntax |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 </components/using_components>` (``symfony/expression-language`` on `Packagist`_). | ||
|
There was a problem hiding this comment. I think we should document Composer first as it is the recommended way There was a problem hiding this comment. I like it, but this means we should change it in all component docs. I'll open a ticket for it. There was a problem hiding this comment. We changed the order of these recently |
||
|
|
||
| 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 | ||
|
There was a problem hiding this comment. you can compare them, for example, to the expression in 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. | ||
|
There was a problem hiding this comment. i miss a bit some text saying for what purposes or use cases (at least examples of them) is compile used over evaluation and the other way around. And also how ExpressionLanguage component is plugged into Symfony so that enables further use cases. That is something that will make things like this documentation make a lot more sense. |
||
|
|
||
| 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 | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
|
There was a problem hiding this comment. extra comma can be removed |
||
| 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 | ||
|
There was a problem hiding this comment. are we allowed to place also () to group expressions? just curious |
||
|
|
||
| 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' : ''``) | ||
|
There was a problem hiding this comment. is this also true in twig, interesting, never knew elvis operator had another version There was a problem hiding this comment. as of Twig 1.12, it is supported However, in the ExpressionLanguage component, the implicit else value is There was a problem hiding this comment. shouldn't it be null on evaluation and '' on compilation maybe? just saying There was a problem hiding this comment. nope. The compilation and the evaluation are producing the same result (after evaluating the compiled code). Using an empty string i the doc is because it was written before changing it to |
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ExpressionLanguageorExpression Language? For example, I usedClass Loaderand notClassLoader.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I prefer ExpressionLanguage (that's also the name used in the README)