Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork5.2k
[WIP] Add docs for ExpressionLanguage component#3044
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Changes fromall commits
File filter
Filter by extension
Conversations
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. I prefer ExpressionLanguage (that's also the name used in the README) | ||
| ================================= | ||
| 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. was introduced in | ||
| Installation | ||
| ------------ | ||
| You can install the component in 2 different ways: | ||
| * Use the official Git repository (https://github.com/symfony/expression-language); | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. preach it and practice 👶 | ||
| * :doc:`Install it via Composer </components/using_components>` (``symfony/expression-language`` on `Packagist`_). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. I think we should document Composer first as it is the recommended way There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. syntax used with | ||
| 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. 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) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. contains | ||
| * ``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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. is this also true in twig, interesting, never knew elvis operator had another version There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. shouldn't it be null on evaluation and '' on compilation maybe? just saying There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. 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 | ||