Update runtime files
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 6d13536..ba3cd2e 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -17,8 +17,10 @@
|41.6| Using functions
|41.7| Defining a function
|41.8| Lists and Dictionaries
-|41.9| Exceptions
-|41.10| Various remarks
+|41.9| White space
+|41.10| Line continuation
+|41.11| Comments
+|41.12| Fileformat
Next chapter: |usr_42.txt| Add new menus
Previous chapter: |usr_40.txt| Make new commands
@@ -112,7 +114,7 @@
TRYING OUT EXAMPLES
You can easily try out most examples in these help files without saving the
-commands in a file. For example, to try out the "for" loop above do this:
+commands to a file. For example, to try out the "for" loop above do this:
1. position the cursor on the "for"
2. start Visual mode with "v"
3. move down to the "endfor"
@@ -195,7 +197,7 @@
CamelCaseName
LENGTH
-Invalid names are "foo+bar" and "6var".
+Invalid names are "foo.bar" and "6var".
Some variables are global. To see a list of currently defined global
variables type this command: >
@@ -684,8 +686,8 @@
one as flags. The "W" flag means the search doesn't wrap around the end of
the file.
-Using the `call` command is optional in |Vim9| script. This works the same
-way and also works in legacy script and on the command line: >
+Using the `call` command is optional in |Vim9| script. It is required in
+legacy script and on the command line: >
call search("Date: ", "W")
@@ -711,7 +713,7 @@
:substitute/\a/*/g
-Using the functions becomes more interesting when you do more work before and
+Using the functions becomes interesting when you do more work before and
after the substitute() call.
@@ -1402,8 +1404,9 @@
smaller = num2
endif
-The variable "smaller" is a local variable. Variables used inside a function
-are local unless prefixed by something like "g:", "w:", or "s:".
+The variable "smaller" is a local variable. It is declared to be a number,
+that way Vim can warn you for any mistakes. Variables used inside a function
+are local unless prefixed by something like "g:", "w:", or "b:".
Note:
To access a global variable from inside a function you must prepend
@@ -1469,6 +1472,10 @@
echo text
enddef
+If you want to return any kind of value, you can use the "any" return type: >
+ def GetValue(): any
+This disables type checking for the return value, use only when needed.
+
It is also possible to define a legacy function with `function` and
`endfunction`. These do not have types and are not compiled. Therefore they
execute much slower.
@@ -1485,47 +1492,12 @@
If you call this function with: >
- :10,15call Number()
+ :10,15Number()
The function will be called six times, starting on line 10 and ending on line
15.
-VARIABLE NUMBER OF ARGUMENTS
-
-Vim enables you to define functions that have a variable number of arguments.
-The following command, for instance, defines a function that must have 1
-argument (start) and can have up to 20 additional arguments: >
-
- def Show(start: string, ...items: list<string>)
-
-The variable "items" will be a list in the function containing the extra
-arguments. You can use it like any list, for example: >
-
- def Show(start: string, ...items: list<string>)
- echohl Title
- echo "start is " .. start
- echohl None
- for index in range(len(items))
- echon $" Arg {index} is {items[index]}"
- endfor
- echo
- enddef
-
-You can call it like this: >
-
- Show('Title', 'one', 'two', 'three')
-< start is Title Arg 0 is one Arg 1 is two Arg 2 is three ~
-
-This uses the `echohl` command to specify the highlighting used for the
-following `echo` command. `echohl None` stops it again. The `echon` command
-works like `echo`, but doesn't output a line break.
-
-If you call it with one argument the "items" list will be empty.
-`range(len(items))` returns a list with the indexes, what `for` loops over,
-we'll explain that further down.
-
-
LISTING FUNCTIONS
The `function` command lists the names and arguments of all user-defined
@@ -1606,6 +1578,11 @@
with a capital. Otherwise it could be confused with the name of a builtin
function.
+
+FURTHER READING
+
+Using a variable number of arguments is introduced in section |50.2|.
+
More information about defining your own functions here: |user-functions|.
==============================================================================
@@ -1766,95 +1743,16 @@
For further reading see |Dictionaries|.
==============================================================================
-*41.9* Exceptions
-
-Let's start with an example: >
-
- try
- read ~/templates/pascal.tmpl
- catch /E484:/
- echo "Sorry, the Pascal template file cannot be found."
- endtry
-
-The `read` command will fail if the file does not exist. Instead of
-generating an error message, this code catches the error and gives the user a
-message with more information.
-
-For the commands in between `try` and `endtry` errors are turned into
-exceptions. An exception is a string. In the case of an error the string
-contains the error message. And every error message has a number. In this
-case, the error we catch contains "E484:". This number is guaranteed to stay
-the same (the text may change, e.g., it may be translated).
-
-Besides being able to give a nice error message, Vim will also continue
-executing commands after the `:endtry`. Otherwise, once an uncaught error is
-encountered, execution of the script/function/mapping will be aborted.
-
-When the `read` command causes another error, the pattern "E484:" will not
-match in it. Thus this exception will not be caught and result in the usual
-error message and execution is aborted.
-
-You might be tempted to do this: >
-
- try
- read ~/templates/pascal.tmpl
- catch
- echo "Sorry, the Pascal template file cannot be found."
- endtry
-
-This means all errors are caught. But then you will not see an error that
-would indicate a completely different problem, such as "E21: Cannot make
-changes, 'modifiable' is off". Think twice before you catch any error!
-
-Another useful mechanism is the `finally` command: >
-
- var tmp = tempname()
- try
- exe ":.,$write " .. tmp
- exe "!filter " .. tmp
- :.,$delete
- exe ":$read " .. tmp
- finally
- delete(tmp)
- endtry
-
-This filters the lines from the cursor until the end of the file through the
-"filter" command, which takes a file name argument. No matter if the
-filtering works, if something goes wrong in between `try` and `finally` or the
-user cancels the filtering by pressing CTRL-C, the `delete(tmp)` call is
-always executed. This makes sure you don't leave the temporary file behind.
-
-The `finally` does not catch the exception, the error will still abort
-further execution.
-
-More information about exception handling can be found in the reference
-manual: |exception-handling|.
-
-==============================================================================
-*41.10* Various remarks
-
-Here are a few items that are useful to know when writing Vim scripts.
-
-
-FILEFORMAT
-
-The end-of-line character depends on the system. For Vim scripts it is
-recommended to always use the Unix fileformat. This also works on any other
-system. That way you can copy your Vim scripts from MS-Windows to Unix and
-they still work. See |:source_crnl|. To be sure it is set right, do this
-before writing the file: >
-
- :setlocal fileformat=unix
-
-
-WHITE SPACE
+*41.9* White space
Blank lines are allowed and ignored.
Leading whitespace characters (blanks and TABs) are always ignored.
Trailing whitespace is often ignored, but not always. One command that
-includes it is `map`.
+includes it is `map`. You have to watch out for that, it can cause hard to
+understand mistakes. A generic solution is to never use trailing white space,
+unless you really need it.
To include a whitespace character in the value of an option, it must be
escaped by a "\" (backslash) as in the following example: >
@@ -1876,8 +1774,39 @@
If you use white space sensibly it will just work. When not you will get an
error message telling you where white space is missing or should be removed.
+==============================================================================
+*41.10* Line continuation
-COMMENTS
+In legacy Vim script line continuation is done by preceding a continuation
+line with a backslash: >
+ let mylist = [
+ \ 'one',
+ \ 'two',
+ \ ]
+
+This requires the 'cpo' option to exclude the "C" flag. Normally this is done
+by putting this at the start of the script: >
+ let s:save_cpo = &cpo
+ set cpo&vim
+
+And restore the option at the end of the script: >
+ let &cpo = s:save_cpo
+ unlet s:save_cpo
+
+A few more details can be found here: |line-continuation|.
+
+In |Vim9| script the backslash can still be used, but in most places it is not
+needed: >
+ var mylist = [
+ 'one',
+ 'two',
+ ]
+
+Also, the 'cpo' option does not need to be changed. See
+|vim9-line-continuation| for details.
+
+==============================================================================
+*41.11* Comments
In |Vim9| script the character # starts a comment. That character and
everything after it until the end-of-line is considered a comment and
@@ -1933,11 +1862,21 @@
echo "this is a Vim script"
quit
+==============================================================================
+*41.12* Fileformat
-Advance information about writing Vim script is in |usr_50.txt|.
+The end-of-line character depends on the system. For Vim scripts it is
+recommended to always use the Unix fileformat. This also works on any other
+system. That way you can copy your Vim scripts from MS-Windows to Unix and
+they still work. See |:source_crnl|. To be sure it is set right, do this
+before writing the file: >
+
+ :setlocal fileformat=unix
==============================================================================
+Advance information about writing Vim script is in |usr_50.txt|.
+
Next chapter: |usr_42.txt| Add new menus
Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: