From ddfb23b874376805f72c226c323be8cbbedd5cd0 Mon Sep 17 00:00:00 2001 From: Auca Coyan Date: Sat, 23 Mar 2024 18:09:07 -0300 Subject: [PATCH 1/5] :sparkles: add the page and test if it works --- .vuepress/configs/sidebar/en.ts | 1 + contributor-book/parser_and_other_editor_tools.md | 13 +++++++++++++ 2 files changed, 14 insertions(+) create mode 100644 contributor-book/parser_and_other_editor_tools.md diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts index 62efe3d3135..d326e5617d4 100644 --- a/.vuepress/configs/sidebar/en.ts +++ b/.vuepress/configs/sidebar/en.ts @@ -124,6 +124,7 @@ export const sidebarEn: SidebarConfig = { 'commands', 'plugins', 'plugin_protocol_reference', + 'parser_and_other_editor_tools.md', ], }, ], diff --git a/contributor-book/parser_and_other_editor_tools.md b/contributor-book/parser_and_other_editor_tools.md new file mode 100644 index 00000000000..66527352fcc --- /dev/null +++ b/contributor-book/parser_and_other_editor_tools.md @@ -0,0 +1,13 @@ +--- +title: Parser and other editor tools +--- + +# Parser + +# Tree-sitter + +# FAQ + +- Do we have a formatter? + +Yes, we have [`nufmt`](https://github.com/nushell/nufmt) but it is still a work in progress and not ready to use. From 2e7869909ef1c598c9b83a25e6f1123d8dd4c2fb Mon Sep 17 00:00:00 2001 From: Auca Coyan Date: Sun, 24 Mar 2024 15:32:47 -0300 Subject: [PATCH 2/5] :sparkles: add contributing guide to parser and editor related topics --- .../parser_and_other_editor_tools.md | 74 +++++++++++++++++-- i18n-meta.json | 24 +++++- 2 files changed, 92 insertions(+), 6 deletions(-) diff --git a/contributor-book/parser_and_other_editor_tools.md b/contributor-book/parser_and_other_editor_tools.md index 66527352fcc..0409f5849ab 100644 --- a/contributor-book/parser_and_other_editor_tools.md +++ b/contributor-book/parser_and_other_editor_tools.md @@ -2,12 +2,76 @@ title: Parser and other editor tools --- -# Parser +# Parser and other editor tools -# Tree-sitter +Hi! There is a lot of space to grow in this area, and the development is +somewhat spaced in time, so I (@AucaCoyan) decided to make a document explaning +the framework, conventions and other required knowledge to help others and +myself with this section. -# FAQ +## Parser -- Do we have a formatter? +The most important piece of this chapter is the parser. The parser is the bridge +between the `*.nu` text files and the internal representation of object in +nushell. Almost everything in this chapter interacts or is affected by the +parser. -Yes, we have [`nufmt`](https://github.com/nushell/nufmt) but it is still a work in progress and not ready to use. +### Current status + +The current production parser is not bad at all, but it has certain areas that +some improvement that could be greately appreciated. Sophia [started a new parser](https://github.com/sophiajt/new-nu-parser/) +and it's still on the works. The central idea of this new parser is that it +will have multiple passes over the text, improving the typing structures by +a lot. + +## Formatter + +We have [`nufmt`](https://github.com/nushell/nufmt), but is a little stagnated +because it will probably need some rework after the new parser is landed. The +current issue is a bug reading stdin from the cmdline. Ask @AucaCoyan anything! + +## LSPs + +LSP stands for Language Server Protocol, a [Microsoft document](https://microsoft.github.io/language-server-protocol/) +to establish communication between text editors and parsers and other tools. + +We currently have 2 of them, one for VS Code and one for other terminal editors + +### VSCode + +This has [it's own extension](https://github.com/nushell/vscode-nushell-lang/) +and it's the most advanced LSP. It was the first to appear it is bootstraped +from a prototype of Microsoft. It's written in Typescript and interacts with +`nu` in the command line to have: + +- hover +- go to definition +- auto-completions + +### nu-lsp + +This is a newer LSP that we would like to have as the long term for every editor +. It's written in rust and it's on the `nushell/nushell` repo, in the +[`crates/nu-lsp`](https://github.com/nushell/nushell/tree/main/crates/nu-lsp) +folder. Interacts via stdin and stdout and it is useful for vim, +neovim, helix and other text editors. Sadly, it doesn't have the same level of +features of VSCode-nushell-lang, that's why we still can't replace it. + +## Tree-sitter + +For syntax highligting we can use [nushell tre-sitter grammar](https://github.com/nushell/tree-sitter-nu) +this is useful for terminal text editors (nvim, helix, etc), VS Code [has +its own grammar](https://github.com/nushell/vscode-nushell-lang/blob/main/syntaxes/nushell.tmLanguage.json) + +## I dont know a thing about all this, can you give me a hint where to learn? + +Sure! + +- Adrian Hesketh gives an excellent talk about [how LSP works](https://youtu.be/EkK8Jxjj95s?si=KT3YdfV5LebbTzXp) +- TeeJ explains [tree-sitter in a 15 min video](https://www.youtube.com/watch?v=09-9LltqWLY) +- about the formatter: + - Bob Nystrom worked with the dart formatter and [wrote a precious blog post](https://journal.stuffwithstuff.com/2015/09/08/the-hardest-program-ive-ever-written/) about his journey. The hackernews + [post is also useful](https://news.ycombinator.com/item?id=22706242) for the + comments! + - and a [short overall view](https://blog.vjeux.com/2017/javascript/anatomy-of-a-javascript-pretty-printer.html) + of how `prettier` works diff --git a/i18n-meta.json b/i18n-meta.json index 87c32feb829..d68b76e9ed1 100644 --- a/i18n-meta.json +++ b/i18n-meta.json @@ -54,6 +54,17 @@ "pt-BR": "-", "ru": "-" }, + { + "name": "cheat_sheet.md", + "en": "In progress", + "zh-CN": "-", + "de": "-", + "tr": "-", + "ja": "-", + "es": "-", + "pt-BR": "-", + "ru": "-" + }, { "name": "coloring_and_theming.md", "en": "Completed", @@ -549,6 +560,17 @@ "pt-BR": "-", "ru": "-" }, + { + "name": "style_guide.md", + "en": "In progress", + "zh-CN": "-", + "de": "-", + "tr": "-", + "ja": "-", + "es": "-", + "pt-BR": "-", + "ru": "-" + }, { "name": "table_of_contents.md", "en": "Completed", @@ -637,4 +659,4 @@ "pt-BR": "-", "ru": "-" } -] +] \ No newline at end of file From bc66a93b511b33a8ca77190610fa363dece3464d Mon Sep 17 00:00:00 2001 From: Auca Coyan Date: Sun, 24 Mar 2024 22:39:52 -0300 Subject: [PATCH 3/5] :memo: update section on tree-sitter --- contributor-book/parser_and_other_editor_tools.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/contributor-book/parser_and_other_editor_tools.md b/contributor-book/parser_and_other_editor_tools.md index 0409f5849ab..8dcd526fa21 100644 --- a/contributor-book/parser_and_other_editor_tools.md +++ b/contributor-book/parser_and_other_editor_tools.md @@ -59,9 +59,14 @@ features of VSCode-nushell-lang, that's why we still can't replace it. ## Tree-sitter -For syntax highligting we can use [nushell tre-sitter grammar](https://github.com/nushell/tree-sitter-nu) -this is useful for terminal text editors (nvim, helix, etc), VS Code [has -its own grammar](https://github.com/nushell/vscode-nushell-lang/blob/main/syntaxes/nushell.tmLanguage.json) +We have another grammar: [tree-sitter nushell](https://github.com/nushell/tree-sitter-nu) this is useful for terminal text editors (nvim, helix, etc). VS Code doesn't have support for tree-sitter and its grammar [is written in tmLanguage](https://github.com/nushell/vscode-nushell-lang/blob/main/syntaxes/nushell.tmLanguage.json) +It has the following goals: + +- Ability to serve as a parser for a repl +- Ability to work in editors that support tree-sitter (hx, nvim, others) +- Ability to work in rust +- Fast +- Ability to be utilized for syntax highlighting ## I dont know a thing about all this, can you give me a hint where to learn? From 535f9cc78ba897678ea59879a1044c3248c2799a Mon Sep 17 00:00:00 2001 From: Auca Coyan Date: Sun, 24 Mar 2024 22:42:51 -0300 Subject: [PATCH 4/5] :pencil2: typo --- contributor-book/parser_and_other_editor_tools.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributor-book/parser_and_other_editor_tools.md b/contributor-book/parser_and_other_editor_tools.md index 8dcd526fa21..acfbe3e316b 100644 --- a/contributor-book/parser_and_other_editor_tools.md +++ b/contributor-book/parser_and_other_editor_tools.md @@ -68,9 +68,9 @@ It has the following goals: - Fast - Ability to be utilized for syntax highlighting -## I dont know a thing about all this, can you give me a hint where to learn? +## I dont know a thing about all this, can you give me a hint on where to start? -Sure! +Sure! you can begin with these resources: - Adrian Hesketh gives an excellent talk about [how LSP works](https://youtu.be/EkK8Jxjj95s?si=KT3YdfV5LebbTzXp) - TeeJ explains [tree-sitter in a 15 min video](https://www.youtube.com/watch?v=09-9LltqWLY) From 12f1c215c080174abbbc08ea83613f85aff5e0d0 Mon Sep 17 00:00:00 2001 From: Auca Coyan Date: Sun, 21 Apr 2024 07:55:00 -0300 Subject: [PATCH 5/5] :pencil2: fix typo and red ci --- contributor-book/parser_and_other_editor_tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributor-book/parser_and_other_editor_tools.md b/contributor-book/parser_and_other_editor_tools.md index acfbe3e316b..9ad0634d41a 100644 --- a/contributor-book/parser_and_other_editor_tools.md +++ b/contributor-book/parser_and_other_editor_tools.md @@ -5,7 +5,7 @@ title: Parser and other editor tools # Parser and other editor tools Hi! There is a lot of space to grow in this area, and the development is -somewhat spaced in time, so I (@AucaCoyan) decided to make a document explaning +somewhat spaced in time, so I (@AucaCoyan) decided to make a document explaining the framework, conventions and other required knowledge to help others and myself with this section.