[vim9script/en] add vim9script

[Konfekt]

• All original content is due to the listed sources and contributors
• Pull request title is prepended with [language/lang-code] (example [python/fr] or [java/en])
• Pull request touches only one file (or a set of logically related files with similar changes made)
• Content changes are aimed at intermediate to experienced programmers (this is a poor format for explaining fundamental programming concepts)
• If you've changed any part of the YAML Frontmatter, make sure it is formatted according to CONTRIBUTING.md which does not exist, so rather yes?
• Yes, I have double-checked quotes and field names!

[Konfekt]

Could the failing csv.md containing an invalid key named language be disregarded for this pull request not touching it?

[Konfekt]

@yegappan, thank you for the guide for Python coders that now served as principal input.

[Konfekt]

@ubaldot as author of https://github.com/ubaldot/vim9-conversion-aid may also want to have a glimpse

[HiPhish]

Can you please remove the @ from my name in the commit message? GitHub keeps spamming me with updates about this PR because you mentioned me and this issue has nothing to do with my text. I don't mind that you are naming me in the commit message, that's fine, it's just the @ character that's the problem.

[Konfekt]

I beg your pardon; I that should have been the last amendment

[HiPhish]

It's not big deal, just something to keep in mind for the next time :) It's cool that you are continuing my old work.

[Konfekt]

Thanks a million @kennypete , taken almost wholesale, though keeping the Vim idioms section for plug-in developers

[Konfekt]

In a bit more detail: I merged the former try catch examples into the new one and kept the idioms and external commands sections as common use cases

[girishji]

Inviting other Vim9 experts to have a glimpse at this Vim9script syntax sheet: @saccarosium, @girishji , @habamax , @bfrg, @kennypete

It's funny that this popped up because I have been doing a slow re-write/enhancement of the vim9.txt help file with loads of working examples, which I hope will get the tick once it's finally done. I may do a similar invite to check it out when it's ready.
vim9script-xiny.vim.txt

:echo is not vim9script. It is Ex command. A section on debugging, compiling single functions, listing bytecode, will help. Also, a separate section on data structures will help. A section on lambda functions and how it can be used with map()/filter()/etc idioms of functional programming will also help. A brief section on regex (and various 'match' examples) may also help.

[Konfekt]

Thank you!

:echo is not vim9script

is there a natural vim9 alternative? The question is to which extent vim9script can replace vimscript (for example, the handling of shell commands pretty much stayed as is).

A section on debugging, compiling single functions, listing bytecode, will help.

I added some simple examples.

Also, a separate section on data structures will help. A section on lambda functions and how it can be used with map()/filter()/etc idioms of functional programming will also help. A brief section on regex (and various 'match' examples) may also help.

These have more or less been merged into the first sections in the last commits. Have they become hard to find?

Do you have a suggestion on how to reorganize and which data structures (currently enums, tuples, classes, ...)

[girishji]

Nothing wrong with including Ex commands. Just mention it, so new users can distinguish them from vim9 constructs.

[kennypete]

Nothing wrong with including Ex commands. Just mention it, so new users can distinguish them from vim9 constructs.

I did consider that, though a comment up front could qualify it, noting that to provide visual aid to the reader, it's used so that the script may be run in full.

Vim9 script options could be used instead, I guess, but probably would be clunky and not obvious to new-to-Vim9 users. You could create a new buffer and append(..., or appendbufline(..., but it'd be ugly.

The better idea may be repurposing the vimscript intro. I'd not read it until now, but here are the applicable paragraphs:

" Vim script (also called VimL) is the subset of Vim's ex-commands which
" supplies a number of features one would expect from a scripting language,
" such as values, variables, functions or loops. Always keep in the back of
" your mind that a Vim script file is just a sequence of ex-commands. It is
" very common for a script to mix programming-language features and raw
" ex-commands.
"
" You can run Vim script directly by entering the commands in command-line mode
" (press : to enter command-line mode), or you can write them to a file
" (without the leading :) and source it in a running Vim instance (:source " path/to/file). Some files are sourced automatically as part of your
" configuration (see |startup|). This guide assumes that you are familiar
" with ex-commands and will only cover the scripting. Help topics to the
" relevant manual sections are included.

[girishji]

" Vim script (also called VimL) is the subset of Vim's ex-commands which " supplies a number of features one would expect from a scripting language, " such as values, variables, functions or loops. Always keep in the back of " your mind that ...

I don't think vim9script can be considered a subset of ex-commands. Legacy Vimscript is interpreted line by line, requiring backslashes to continue lines, and commands like let and call are used to make them resemble ex-commands. In contrast, vim9script supports multiline syntax natively, without needing line continuation. This makes it less suited for command-line usage, unlike traditional ex-commands. Ultimately, while both ex-commands and vim9script are important to learn, they should be approached as distinct but complementary parts of the Vim ecosystem.

[ubaldot]

Ex commands are just commands that are part of the legacy Ex editor. They are one liner and they return no values. They just execute an action. On the other had, functions are functions like in other programming languages. Ex commands can be used inside functions and, on the opposite route, you can call a function through an Ex command with :call in legacy script or with vim9cmd in Vim9 when used from the command line. Nevertheless, User can also define his own commands that call functions. Vim9 is a very nice language and it is way better than Lua in the Vim context.

[kennypete]

I don't think vim9script can be considered a subset of ex-commands. Legacy Vimscript ...

Sorry, what I was meaning was to include aspects of that introduction to qualify the point about using echo, not to use it as-is bar substituting VimL with Vim9.

There are other aspects of that introduction that would require changes too. So, here's a first crack at that - perhaps others can make it much better than this (don't use it verbatim - again, it's only a starter):

# Vim9 script, which is exclusive to Vim version 9+, has a lot in common with
# its predecessor, vimscript, though it is a distinct language, which is
# closer in syntax to more modern programming languages and provides key
# improvements such as compiled functions.

# You can run this Vim9 script directly in Vim.  After pasting the content
# into a Vim buffer, enter the command `so` in command-line mode (press `:`
# first to enter command-line mode).  Alternatively, you can write the content
# to a file and source it in a running Vim instance (`:source path/to/file`).

# This guide utilises a small number of Vim ex-commands.  Those are explained
# in Vim's help (e.g., `:h :echo`) which is used extensively to demonstrate
# results/outputs.
# [Maybe list the other small number of ex-commands used in the final script here?]

[Konfekt]

Thank you @NameNoQuality, with the CSV issue being fixed the checks now pass and this could be considered for merging, as there have been no comments from the participants for two weeks

[Konfekt]

@vendethiel, please let us know what tasks are still remaining for this to be included (and kindly excuse my impatience)

[vendethiel]

Sorry, I didn't realize this was ready to merge :). Thank you for your work!