mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 17:59:23 -04:00
2217337c5d
## Summary
TL;DR
- Adds ability to parse out comments from source to AST.
- Adds ability for every AST node to have *decoration*—comments,
which can be attached from left, top, and right from the node.
- Implements routine which attached comments to AST nodes.
- In `BasicPrettyPrinter` adds support only for *left* and *right*
comment printing, as the basic printer prints only on one line.
- In `WrappingPrettyPrinter` adds support for all comment printing for
all AST nodes.
- Introduces a `Query` object and `query` AST node, which represent
thole query—the root node, list of commands.
- The ES|QL AST example plugin now displays the pretty-printed text
version.
### Comments
This PR introduced an optional `formatting` field for all AST nodes. In
the `formatting` field one can specify comment decorations from
different sides of a node.
When parsing, once can now specify the `{ withComments: true }` option,
which will collect all comments from the source while parsing using the
`collectDecorations` routine. It will then also call the
`attachDecorations`, which walks the AST and assigns each comment to
some AST node.
Further, traversal and pretty-print API have been updated to work with
comments:
- The `Walker` has been updated to be able to walk all comments from the
AST.
- The `BasicPrettyPrinter` adds support only for *left* and *right*
inline comment printing, as the basic printer prints only on one line.
- The `WrappingPrettyPrinter` adds support for all comment printing for
all AST nodes. It switches to line-break printing mode if it detects
there are comments with line breaks (those could be multi-line comments,
or single line comments—single line comments are always followed
by a line break). It also correctly inserts punctuation, when an AST
node is surrounded by comments.
### Parsing utils
All parsing utils have been moved to the `/parser` sub-folder.
Files in the `/parser` folder have been renamed as per Kibana convention
to reflect what is inside the file. For example, the `EsqlErrorListener`
class is in a file named `esql_error_listener.ts`.
A `Query` class and `ESQLAstQueryExpression` AST nodes have been
introduced. They represent the result of a full query parse. (Before
that, the AST root was just an array of command nodes, now the AST root
is represented by the `ESQLAstQueryExpression` node.)
### Builder
I have started the implementation of the `Builder` static class in the
`/builder` folder. It is simply a collection of stateless AST node
factories—functions which construct AST nodes.
Some of the `Builder` methods are already used by the parser, more will
follow. We will also use the `Builder` in upcoming [*Mutation
API*](https://github.com/elastic/kibana/issues/191812).
### ES|QL Example Plugin
This PR sets up Storybook and implements few Storybook stories for the
ES|QL AST example plugin, run it with:
```
yarn storybook esql_ast_inspector
```
This PR updates the *ES|QL AST Explorer* example plugin. Start Kibana
with example plugins enabled:
```
yarn start --run-examples
```
And navigate to
[`/app/esql_ast_inspector`](http://localhost:5601/app/esql_ast_inspector)
to see the new example plugin UI.
### Checklist
- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios
### For maintainers
- [x] This was checked for breaking API changes and was [labeled
appropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
Co-authored-by: Stratoula Kalafateli <efstratia.kalafateli@elastic.co>
|
||
|---|---|---|
| .. | ||
| bfetch_explorer | ||
| content_management_examples | ||
| controls_example | ||
| data_view_field_editor_example | ||
| developer_examples | ||
| discover_customization_examples | ||
| embeddable_examples | ||
| error_boundary | ||
| eso_model_version_example | ||
| esql_ast_inspector | ||
| esql_validation_example | ||
| expressions_explorer | ||
| feature_control_examples | ||
| feature_flags_example | ||
| field_formats_example | ||
| files_example | ||
| grid_example | ||
| guided_onboarding_example | ||
| hello_world | ||
| locator_examples | ||
| locator_explorer | ||
| partial_results_example | ||
| portable_dashboards_example | ||
| preboot_example | ||
| resizable_layout_examples | ||
| response_stream | ||
| routing_example | ||
| screenshot_mode_example | ||
| search_examples | ||
| share_examples | ||
| state_containers_examples | ||
| ui_action_examples | ||
| ui_actions_explorer | ||
| unified_doc_viewer | ||
| unified_field_list_examples | ||
| user_profile_examples | ||
| v8_profiler_examples | ||
| README.asciidoc | ||
[[example-plugins]] == Example plugins This folder contains example plugins. To run the plugins in this folder, use the `--run-examples` flag (without a basepath), via [source,bash] ---- yarn start --run-examples ----