Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
# Backport This will backport the following commits from `main` to `8.x`: - [[ES|QL] Comment parsing and pretty-printing (#192173)](#192173) <!--- Backport version: 9.4.3 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Vadim Kibana","email":"82822460+vadimkibana@users.noreply.github.com"},"sourceCommit":{"committedDate":"2024-09-26T10:34:38Z","message":"[ES|QL] Comment parsing and pretty-printing (#192173)\n\n## Summary\r\n\r\nTL;DR\r\n\r\n- Adds ability to parse out comments from source to AST.\r\n- Adds ability for every AST node to have *decoration*—comments,\r\nwhich can be attached from left, top, and right from the node.\r\n- Implements routine which attached comments to AST nodes.\r\n- In `BasicPrettyPrinter` adds support only for *left* and *right*\r\ncomment printing, as the basic printer prints only on one line.\r\n- In `WrappingPrettyPrinter` adds support for all comment printing for\r\nall AST nodes.\r\n- Introduces a `Query` object and `query` AST node, which represent\r\nthole query—the root node, list of commands.\r\n- The ES|QL AST example plugin now displays the pretty-printed text\r\nversion.\r\n\r\n\r\n### Comments\r\n\r\nThis PR introduced an optional `formatting` field for all AST nodes. In\r\nthe `formatting` field one can specify comment decorations from\r\ndifferent sides of a node.\r\n\r\nWhen parsing, once can now specify the `{ withComments: true }` option,\r\nwhich will collect all comments from the source while parsing using the\r\n`collectDecorations` routine. It will then also call the\r\n`attachDecorations`, which walks the AST and assigns each comment to\r\nsome AST node.\r\n\r\nFurther, traversal and pretty-print API have been updated to work with\r\ncomments:\r\n\r\n- The `Walker` has been updated to be able to walk all comments from the\r\nAST.\r\n- The `BasicPrettyPrinter` adds support only for *left* and *right*\r\ninline comment printing, as the basic printer prints only on one line.\r\n- The `WrappingPrettyPrinter` adds support for all comment printing for\r\nall AST nodes. It switches to line-break printing mode if it detects\r\nthere are comments with line breaks (those could be multi-line comments,\r\nor single line comments—single line comments are always followed\r\nby a line break). It also correctly inserts punctuation, when an AST\r\nnode is surrounded by comments.\r\n\r\n\r\n### Parsing utils\r\n\r\nAll parsing utils have been moved to the `/parser` sub-folder.\r\n\r\nFiles in the `/parser` folder have been renamed as per Kibana convention\r\nto reflect what is inside the file. For example, the `EsqlErrorListener`\r\nclass is in a file named `esql_error_listener.ts`.\r\n\r\nA `Query` class and `ESQLAstQueryExpression` AST nodes have been\r\nintroduced. They represent the result of a full query parse. (Before\r\nthat, the AST root was just an array of command nodes, now the AST root\r\nis represented by the `ESQLAstQueryExpression` node.)\r\n\r\n\r\n### Builder\r\n\r\nI have started the implementation of the `Builder` static class in the\r\n`/builder` folder. It is simply a collection of stateless AST node\r\nfactories—functions which construct AST nodes.\r\n\r\nSome of the `Builder` methods are already used by the parser, more will\r\nfollow. We will also use the `Builder` in upcoming [*Mutation\r\nAPI*](https://github.com/elastic/kibana/issues/191812).\r\n\r\n\r\n### ES|QL Example Plugin\r\n\r\nThis PR sets up Storybook and implements few Storybook stories for the\r\nES|QL AST example plugin, run it with:\r\n\r\n```\r\nyarn storybook esql_ast_inspector\r\n```\r\n\r\nThis PR updates the *ES|QL AST Explorer* example plugin. Start Kibana\r\nwith example plugins enabled:\r\n\r\n```\r\nyarn start --run-examples\r\n```\r\n\r\nAnd navigate to\r\n[`/app/esql_ast_inspector`](http://localhost:5601/app/esql_ast_inspector)\r\nto see the new example plugin UI.\r\n\r\n\r\n\r\n\r\n\r\n\r\n### Checklist\r\n\r\n- [x] [Unit or functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere updated or added to match the most common scenarios\r\n\r\n\r\n### For maintainers\r\n\r\n- [x] This was checked for breaking API changes and was [labeled\r\nappropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>\r\nCo-authored-by: Stratoula Kalafateli <efstratia.kalafateli@elastic.co>","sha":"2217337c5d91340ba67e0bedaab0762502518993","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["review","release_note:skip","v9.0.0","backport:prev-minor","Feature:ES|QL","Team:ESQL","v8.16.0"],"title":"[ES|QL] Comment parsing and pretty-printing","number":192173,"url":"https://github.com/elastic/kibana/pull/192173","mergeCommit":{"message":"[ES|QL] Comment parsing and pretty-printing (#192173)\n\n## Summary\r\n\r\nTL;DR\r\n\r\n- Adds ability to parse out comments from source to AST.\r\n- Adds ability for every AST node to have *decoration*—comments,\r\nwhich can be attached from left, top, and right from the node.\r\n- Implements routine which attached comments to AST nodes.\r\n- In `BasicPrettyPrinter` adds support only for *left* and *right*\r\ncomment printing, as the basic printer prints only on one line.\r\n- In `WrappingPrettyPrinter` adds support for all comment printing for\r\nall AST nodes.\r\n- Introduces a `Query` object and `query` AST node, which represent\r\nthole query—the root node, list of commands.\r\n- The ES|QL AST example plugin now displays the pretty-printed text\r\nversion.\r\n\r\n\r\n### Comments\r\n\r\nThis PR introduced an optional `formatting` field for all AST nodes. In\r\nthe `formatting` field one can specify comment decorations from\r\ndifferent sides of a node.\r\n\r\nWhen parsing, once can now specify the `{ withComments: true }` option,\r\nwhich will collect all comments from the source while parsing using the\r\n`collectDecorations` routine. It will then also call the\r\n`attachDecorations`, which walks the AST and assigns each comment to\r\nsome AST node.\r\n\r\nFurther, traversal and pretty-print API have been updated to work with\r\ncomments:\r\n\r\n- The `Walker` has been updated to be able to walk all comments from the\r\nAST.\r\n- The `BasicPrettyPrinter` adds support only for *left* and *right*\r\ninline comment printing, as the basic printer prints only on one line.\r\n- The `WrappingPrettyPrinter` adds support for all comment printing for\r\nall AST nodes. It switches to line-break printing mode if it detects\r\nthere are comments with line breaks (those could be multi-line comments,\r\nor single line comments—single line comments are always followed\r\nby a line break). It also correctly inserts punctuation, when an AST\r\nnode is surrounded by comments.\r\n\r\n\r\n### Parsing utils\r\n\r\nAll parsing utils have been moved to the `/parser` sub-folder.\r\n\r\nFiles in the `/parser` folder have been renamed as per Kibana convention\r\nto reflect what is inside the file. For example, the `EsqlErrorListener`\r\nclass is in a file named `esql_error_listener.ts`.\r\n\r\nA `Query` class and `ESQLAstQueryExpression` AST nodes have been\r\nintroduced. They represent the result of a full query parse. (Before\r\nthat, the AST root was just an array of command nodes, now the AST root\r\nis represented by the `ESQLAstQueryExpression` node.)\r\n\r\n\r\n### Builder\r\n\r\nI have started the implementation of the `Builder` static class in the\r\n`/builder` folder. It is simply a collection of stateless AST node\r\nfactories—functions which construct AST nodes.\r\n\r\nSome of the `Builder` methods are already used by the parser, more will\r\nfollow. We will also use the `Builder` in upcoming [*Mutation\r\nAPI*](https://github.com/elastic/kibana/issues/191812).\r\n\r\n\r\n### ES|QL Example Plugin\r\n\r\nThis PR sets up Storybook and implements few Storybook stories for the\r\nES|QL AST example plugin, run it with:\r\n\r\n```\r\nyarn storybook esql_ast_inspector\r\n```\r\n\r\nThis PR updates the *ES|QL AST Explorer* example plugin. Start Kibana\r\nwith example plugins enabled:\r\n\r\n```\r\nyarn start --run-examples\r\n```\r\n\r\nAnd navigate to\r\n[`/app/esql_ast_inspector`](http://localhost:5601/app/esql_ast_inspector)\r\nto see the new example plugin UI.\r\n\r\n\r\n\r\n\r\n\r\n\r\n### Checklist\r\n\r\n- [x] [Unit or functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere updated or added to match the most common scenarios\r\n\r\n\r\n### For maintainers\r\n\r\n- [x] This was checked for breaking API changes and was [labeled\r\nappropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>\r\nCo-authored-by: Stratoula Kalafateli <efstratia.kalafateli@elastic.co>","sha":"2217337c5d91340ba67e0bedaab0762502518993"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/192173","number":192173,"mergeCommit":{"message":"[ES|QL] Comment parsing and pretty-printing (#192173)\n\n## Summary\r\n\r\nTL;DR\r\n\r\n- Adds ability to parse out comments from source to AST.\r\n- Adds ability for every AST node to have *decoration*—comments,\r\nwhich can be attached from left, top, and right from the node.\r\n- Implements routine which attached comments to AST nodes.\r\n- In `BasicPrettyPrinter` adds support only for *left* and *right*\r\ncomment printing, as the basic printer prints only on one line.\r\n- In `WrappingPrettyPrinter` adds support for all comment printing for\r\nall AST nodes.\r\n- Introduces a `Query` object and `query` AST node, which represent\r\nthole query—the root node, list of commands.\r\n- The ES|QL AST example plugin now displays the pretty-printed text\r\nversion.\r\n\r\n\r\n### Comments\r\n\r\nThis PR introduced an optional `formatting` field for all AST nodes. In\r\nthe `formatting` field one can specify comment decorations from\r\ndifferent sides of a node.\r\n\r\nWhen parsing, once can now specify the `{ withComments: true }` option,\r\nwhich will collect all comments from the source while parsing using the\r\n`collectDecorations` routine. It will then also call the\r\n`attachDecorations`, which walks the AST and assigns each comment to\r\nsome AST node.\r\n\r\nFurther, traversal and pretty-print API have been updated to work with\r\ncomments:\r\n\r\n- The `Walker` has been updated to be able to walk all comments from the\r\nAST.\r\n- The `BasicPrettyPrinter` adds support only for *left* and *right*\r\ninline comment printing, as the basic printer prints only on one line.\r\n- The `WrappingPrettyPrinter` adds support for all comment printing for\r\nall AST nodes. It switches to line-break printing mode if it detects\r\nthere are comments with line breaks (those could be multi-line comments,\r\nor single line comments—single line comments are always followed\r\nby a line break). It also correctly inserts punctuation, when an AST\r\nnode is surrounded by comments.\r\n\r\n\r\n### Parsing utils\r\n\r\nAll parsing utils have been moved to the `/parser` sub-folder.\r\n\r\nFiles in the `/parser` folder have been renamed as per Kibana convention\r\nto reflect what is inside the file. For example, the `EsqlErrorListener`\r\nclass is in a file named `esql_error_listener.ts`.\r\n\r\nA `Query` class and `ESQLAstQueryExpression` AST nodes have been\r\nintroduced. They represent the result of a full query parse. (Before\r\nthat, the AST root was just an array of command nodes, now the AST root\r\nis represented by the `ESQLAstQueryExpression` node.)\r\n\r\n\r\n### Builder\r\n\r\nI have started the implementation of the `Builder` static class in the\r\n`/builder` folder. It is simply a collection of stateless AST node\r\nfactories—functions which construct AST nodes.\r\n\r\nSome of the `Builder` methods are already used by the parser, more will\r\nfollow. We will also use the `Builder` in upcoming [*Mutation\r\nAPI*](https://github.com/elastic/kibana/issues/191812).\r\n\r\n\r\n### ES|QL Example Plugin\r\n\r\nThis PR sets up Storybook and implements few Storybook stories for the\r\nES|QL AST example plugin, run it with:\r\n\r\n```\r\nyarn storybook esql_ast_inspector\r\n```\r\n\r\nThis PR updates the *ES|QL AST Explorer* example plugin. Start Kibana\r\nwith example plugins enabled:\r\n\r\n```\r\nyarn start --run-examples\r\n```\r\n\r\nAnd navigate to\r\n[`/app/esql_ast_inspector`](http://localhost:5601/app/esql_ast_inspector)\r\nto see the new example plugin UI.\r\n\r\n\r\n\r\n\r\n\r\n\r\n### Checklist\r\n\r\n- [x] [Unit or functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere updated or added to match the most common scenarios\r\n\r\n\r\n### For maintainers\r\n\r\n- [x] This was checked for breaking API changes and was [labeled\r\nappropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>\r\nCo-authored-by: Stratoula Kalafateli <efstratia.kalafateli@elastic.co>","sha":"2217337c5d91340ba67e0bedaab0762502518993"}},{"branch":"8.x","label":"v8.16.0","branchLabelMappingKey":"^v8.16.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT--> Co-authored-by: Vadim Kibana <82822460+vadimkibana@users.noreply.github.com>
- Loading branch information
1 parent
ba9a67e
commit 2fd6817