[vim9script/en] corrections and improvements

[kennypete]

• I solemnly swear that this is all original content of which I am the original author
• Pull request title is prepended with [language/lang-code] - Yes, the title is, though the commit message is only [vim9script] - I hope that is okay.
• 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)

---

I envisaged this PR would be small, addressing only the issues noted in 5376. However, while working through them, I came across several other things, and it snowballed into a much larger update.

Header

• Updates to name, which should be “Vim9 script”. It is the name used consistently in Vim’s documentation (and is corrected by PRs in the Vim repository when not using that form). It is also corrected in the main text where “Vim9script” and “Vim9Script” are also used.)
• Added two contributors omitted from the original work on vim9script.md.

Style Guidelines / Overview

CONTRIBUTING.md says to, “Try to use as few words as possible”, and, “Code examples are preferred over exposition in all cases.” Accordingly, the 400+ word introduction (and explanation at the start of the monolithic code block) is reduced by two thirds in an introduction that does not:

• Dwell/focus on comparisons with legacy Vim script
• Explain syntax, variables, types, etc., because those are explained in the code examples themselves (= duplication), and
• Adds a sub-heading and explanation regarding how to source the scripts.

The Overview, and the numbered sections/sub-sections, separate the code into logical blocks. This follows the approach of a few other learnxinyminutes topics, e.g., Smalltalk`. Doing this makes more sense in the Vim9 script context:

1. It is more readable, especially as syntax highlighting is not possible for Vim9 script in this tutorial.
2. Copying and using individual components is much easier from a structure where each smaller code block is a distinct, sourcable example.
3. If the “Get the code:” link at the top of the page is followed, the code components of the page are isolated and produced as a whole. With the revised design, those should now display nicely, and make it easy for readers to find the block(s) they seek because they should present like this:

vim9script
# BUILTIN VARIABLES AND SETTINGS

...

# ----------------------------------------------------------------------------

vim9script
# CONDITIONALS AND LOOPS

...

# ----------------------------------------------------------------------------

vim9script
# EXCEPTIONS

...

# ----------------------------------------------------------------------------

Although the capitalised heading after each vim9script command may appear a bit repetitive when looking at the main document online (when the “Get the code:” link is used) the purpose of doing this is revealed. It makes it easy to see what each block is about, and facilitates copy-and-put of the desired code into Vim to source the example(s).

Plenty of the content of the big code block in the current vim9script.md remains unchanged, though there are some general improvements. Examples:

• Inline comments are aligned within code blocks, where practicable. This makes them easier to follow, for example:

  echo typename(1)           # number
  echo typename(1.1)         # float
  echo typename(true)        # bool
  

• Most code blocks will now echo to an extent that does not involve more than a “page” of output.
• A small number of the current examples would error, particularly if used in Windows rather than Linux/WSL.

1. Types, Operators, Expressions, and Regular Expressions

The section is divided into six sub-topics:

• Primitive and Collection Types
• Operators and Expressions
• Logical and Comparison Operators
• Numbers
• Strings
• Regular Expressions

The section is a bit longer than currently, with more examples in the Strings and Regular Expressions especially, covering points like POSIX bracket expressions and PCRE-style assertions.

It also addresses the “passage of time” matter of tuples, which are no longer a “recent addition”. In the current file, that was a design choice to lessen the likelihood that sourcing the monolithic script would error. With the code now in separate scripts, that is less of a concern.

2. Variables

There are few changes to this section, which is divided into five sub-sections:

• Declarations
• Manipulating Container Variables
• Variables’ Scopes
• Registers
• Builtin Variables and Settings

3. Control Flow

There are few changes to this section, which is divided into two sub-sections:

• Conditionals and Loops
• Exceptions

4. Functions, Lambdas, and Closures

This section has a few more changes, in the sub-sections:

• Function Basics
• Generic Functions
• Lambdas
• Closures

Improvements:

• _ argument usage for ignoring unused callback parameters is documented.
• The Generic Functions sub-section is added.
• The Lambdas sub-section is more detailed.
• The closure example shows capturing and modifying the state more clearly than current example, so is more revealing, and additional commentary makes it easier to follow.

5. Classes and Enums

Aside from providing two sub-sections, the examples are largely unchanged, though the enum one removes some redundancy.

6. Sourcing Scripts, Modules, and Importing

There are not too many changes to this section, though the division into sub-sections helps particularly as the exporting and importing “files” are more obvious.

7. Vim Idioms

This section is easier to navigate now with sub-sections addressing distinct topics.

• Plugin Development
• Command and Mapping Definitions
• Event Handling
• Executing Normal Mode Commands
• Feature Detection and Utility Functions

8. External Commands

This section is significantly improved. It progresses from simple to more complicated, with all examples now working cross-platform, using commands like whoami instead of Unix-specific, like ls. The [now working] job example is completely rewritten to be functional, using proper callbacks with &shell and &shellcmdflag for portability. The simplified outputs are also less distracting (e.g., avoiding potentially long directory listings).

Sub-sections are now:

• Direct Shell Command Execution
• Capturing shell command output with system()
• Processing Command Output as Lines with systemlist()
• Asynchronous Command Execution with Jobs
• A More Advanced Example: Git Integration

9. Testing, Debugging, and Inspecting Bytecode

The separation into subsections makes sourcing and working interactively with this content meaningful.

Sub-sections now are:

• Assertions
• Breakpoints
• Listing Instructions / Bytecode of a Function

Additional Resources

This is updated and to indicate what is at the destinations for some of the links. It has links relocated from the introduction/in the main text, removing what is currently duplication (e.g., the Python Developers link is prominent in the introduction currently, which is not ideal for a resource aimed at briefly covering off Vim9 script).

[Konfekt]

Had a gander. Fantastic, a work of love. Also potentially useful at vim/vim#18576; LLMs follow Vim9 script initially, but eventually fall back to legacy syntax, say for comments.

[vendethiel]

Thanks for the PR! I hope to get some time this weekend to take a look at it, if I don't, feel free to ping me again.

[kennypete]

Thanks @Konfekt and @vendethiel - if there are any fixes or improvements needed, I'll look at it again in a week's time. (As for a labour of love, the vim9.txt help has been that - only one section left to go now!)