Mercurial > vim

comparison runtime/doc/vim9.txt @ 23573:e2e2cc5d0856

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update runtime files. Commit: https://github.com/vim/vim/commit/82be4849eed0b8fbee45bc8da99b685ec89af59a Author: Bram Moolenaar <Bram@vim.org> Date: Mon Jan 11 19:40:15 2021 +0100 Update runtime files.
author Bram Moolenaar <Bram@vim.org>
date Mon, 11 Jan 2021 19:45:05 +0100
parents 2247a2ce3630
children 96206643bd9f
comparison
equal deleted inserted replaced
23572:b35e568d74e6 23573:e2e2cc5d0856
1 *vim9.txt* For Vim version 8.2. Last change: 2021 Jan 03 1 *vim9.txt* For Vim version 8.2. Last change: 2021 Jan 10
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
50 The Vim9 script syntax and semantics are used in: 50 The Vim9 script syntax and semantics are used in:
51 - a function defined with the `:def` command 51 - a function defined with the `:def` command
52 - a script file where the first command is `vim9script` 52 - a script file where the first command is `vim9script`
53 - an autocommand defined in the context of the above 53 - an autocommand defined in the context of the above
54 54
55 When using `:function` in a Vim9 script file the legacy syntax is used. 55 When using `:function` in a Vim9 script file the legacy syntax is used, with
56 However, this can be confusing and is therefore discouraged. 56 the highest |scriptversion|. However, this can be confusing and is therefore
57 discouraged.
57 58
58 Vim9 script and legacy Vim script can be mixed. There is no requirement to 59 Vim9 script and legacy Vim script can be mixed. There is no requirement to
59 rewrite old scripts, they keep working as before. You may want to use a few 60 rewrite old scripts, they keep working as before. You may want to use a few
60 `:def` functions for code that needs to be fast. 61 `:def` functions for code that needs to be fast.
61 62
68 Overview ~ 69 Overview ~
69 70
70 Brief summary of the differences you will most often encounter when using Vim9 71 Brief summary of the differences you will most often encounter when using Vim9
71 script and `:def` functions; details are below: 72 script and `:def` functions; details are below:
72 - Comments start with #, not ": > 73 - Comments start with #, not ": >
73 echo "hello" # comment 74 echo "hello" # comment
74 - Using a backslash for line continuation is hardly ever needed: > 75 - Using a backslash for line continuation is hardly ever needed: >
75 echo "hello " 76 echo "hello "
76 .. yourName 77 .. yourName
77 .. ", how are you?" 78 .. ", how are you?"
78 - White space is required in many places. 79 - White space is required in many places.
79 - Assign values without `:let`, declare variables with `:var`: > 80 - Assign values without `:let`, declare variables with `:var`: >
80 var count = 0 81 var count = 0
81 count += 3 82 count += 3
82 - Constants can be declared with `:final` and `:const`: > 83 - Constants can be declared with `:final` and `:const`: >
83 final matches = [] # add matches 84 final matches = [] # add matches
84 const names = ['Betty', 'Peter'] # cannot be changed 85 const names = ['Betty', 'Peter'] # cannot be changed
85 - `:final` cannot be used as an abbreviation of `:finally`. 86 - `:final` cannot be used as an abbreviation of `:finally`.
86 - Variables and functions are script-local by default. 87 - Variables and functions are script-local by default.
87 - Functions are declared with argument types and return type: > 88 - Functions are declared with argument types and return type: >
88 def CallMe(count: number, message: string): bool 89 def CallMe(count: number, message: string): bool
89 - Call functions without `:call`: > 90 - Call functions without `:call`: >
90 writefile(['done'], 'file.txt') 91 writefile(['done'], 'file.txt')
91 - You cannot use `:xit`, `:t`, `:append`, `:change`, `:insert` or curly-braces 92 - You cannot use `:xit`, `:t`, `:append`, `:change`, `:insert` or curly-braces
92 names. 93 names.
93 - A range before a command must be prefixed with a colon: > 94 - A range before a command must be prefixed with a colon: >
94 :%s/this/that 95 :%s/this/that
96 - Unless mentioned specifically, the highest |scriptversion| is used.
95 97
96 98
97 Comments starting with # ~ 99 Comments starting with # ~
98 100
99 In legacy Vim script comments start with double quote. In Vim9 script 101 In legacy Vim script comments start with double quote. In Vim9 script
313 final females = ["Mary"] 315 final females = ["Mary"]
314 const NAMES = [["John", "Peter"], females] 316 const NAMES = [["John", "Peter"], females]
315 NAMES[0] = ["Jack"] # Error! 317 NAMES[0] = ["Jack"] # Error!
316 NAMES[0][0] = "Jack" # Error! 318 NAMES[0][0] = "Jack" # Error!
317 NAMES[1] = ["Emma"] # Error! 319 NAMES[1] = ["Emma"] # Error!
318 Names[1][0] = "Emma" # OK, now females[0] == "Emma" 320 NAMES[1][0] = "Emma" # OK, now females[0] == "Emma"
319 321
320 < *E1092* 322 < *E1092*
321 Declaring more than one variable at a time, using the unpack notation, is 323 Declaring more than one variable at a time, using the unpack notation, is
322 currently not supported: > 324 currently not supported: >
323 var [v1, v2] = GetValues() # Error! 325 var [v1, v2] = GetValues() # Error!
430 possible just before or after the operator. For example: > 432 possible just before or after the operator. For example: >
431 var text = lead 433 var text = lead
432 .. middle 434 .. middle
433 .. end 435 .. end
434 var total = start + 436 var total = start +
435 end - 437 end -
436 correction 438 correction
437 var result = positive 439 var result = positive
438 ? PosFunc(arg) 440 ? PosFunc(arg)
439 : NegFunc(arg) 441 : NegFunc(arg)
440 442
627 'yes' && 0 Error! 629 'yes' && 0 Error!
628 [] || 99 Error! 630 [] || 99 Error!
629 631
630 When using "!" for inverting, there is no error for using any type and the 632 When using "!" for inverting, there is no error for using any type and the
631 result is a boolean. "!!" can be used to turn any value into boolean: > 633 result is a boolean. "!!" can be used to turn any value into boolean: >
632 !'yes' == false 634 !'yes' == false
633 !![] == false 635 !![] == false
634 !![1, 2, 3] == true 636 !![1, 2, 3] == true
635 637
636 When using "`.."` for string concatenation arguments of simple types are 638 When using "`.."` for string concatenation arguments of simple types are
637 always converted to string: > 639 always converted to string: >
638 'hello ' .. 123 == 'hello 123' 640 'hello ' .. 123 == 'hello 123'
639 'hello ' .. v:true == 'hello true' 641 'hello ' .. v:true == 'hello true'
649 Indexing a string with [idx] or [idx, idx] uses character indexes instead of 651 Indexing a string with [idx] or [idx, idx] uses character indexes instead of
650 byte indexes. Example: > 652 byte indexes. Example: >
651 echo 'bár'[1] 653 echo 'bár'[1]
652 In legacy script this results in the character 0xc3 (an illegal byte), in Vim9 654 In legacy script this results in the character 0xc3 (an illegal byte), in Vim9
653 script this results in the string 'á'. 655 script this results in the string 'á'.
656 A negative index is counting from the end, "[-1]" is the last character.
657 If the index is out of range then an empty string results.
658
659 In legacy script "++var" and "--var" would be silently accepted and have no
660 effect. This is an error in Vim9 script.
661
662 Numbers starting with zero are not considered to be octal, only numbers
663 starting with "0o" are octal: "0o744". |scriptversion-4|
654 664
655 665
656 What to watch out for ~ 666 What to watch out for ~
657 *vim9-gotchas* 667 *vim9-gotchas*
658 Vim9 was designed to be closer to often used programming languages, but at the 668 Vim9 was designed to be closer to often used programming languages, but at the
687 Vim9 functions are compiled as a whole: > 697 Vim9 functions are compiled as a whole: >
688 def Maybe() 698 def Maybe()
689 if !has('feature') 699 if !has('feature')
690 return 700 return
691 endif 701 endif
692 use-feature # May give compilation error 702 use-feature # May give a compilation error
693 enddef 703 enddef
694 For a workaround, split it in two functions: > 704 For a workaround, split it in two functions: >
695 func Maybe() 705 func Maybe()
696 if has('feature') 706 if has('feature')
697 call MaybyInner() 707 call MaybyInner()
707 def Maybe() 717 def Maybe()
708 if has('feature') 718 if has('feature')
709 use-feature 719 use-feature
710 endif 720 endif
711 enddef 721 enddef
722 < *vim9-user-command*
723 Another side effect of compiling a function is that the precense of a user
724 command is checked at compile time. If the user command is defined later an
725 error will result. This works: >
726 command -nargs=1 MyCommand echom <q-args>
727 def Works()
728 MyCommand 123
729 enddef
730 This will give an error for "MyCommand" not being defined: >
731 def Works()
732 command -nargs=1 MyCommand echom <q-args>
733 MyCommand 123
734 enddef
735 A workaround is to invoke the command indirectly with `:execute`: >
736 def Works()
737 command -nargs=1 MyCommand echom <q-args>
738 execute 'MyCommand 123'
739 enddef
740
712 Note that for unrecognized commands there is no check for "|" and a following 741 Note that for unrecognized commands there is no check for "|" and a following
713 command. This will give an error for missing `endif`: > 742 command. This will give an error for missing `endif`: >
714 def Maybe() 743 def Maybe()
715 if has('feature') | use-feature | endif 744 if has('feature') | use-feature | endif
716 enddef 745 enddef
944 an error, thus breaking backwards compatibility. For example: 973 an error, thus breaking backwards compatibility. For example:
945 - Using a number other than 0 or 1 where a boolean is expected. *E1023* 974 - Using a number other than 0 or 1 where a boolean is expected. *E1023*
946 - Using a string value when setting a number options. 975 - Using a string value when setting a number options.
947 - Using a number where a string is expected. *E1024* 976 - Using a number where a string is expected. *E1024*
948 977
978 One consequence is that the item type of a list or dict given to map() must
979 not change. This will give an error in compiled code: >
980 map([1, 2, 3], (i, v) => 'item ' .. i)
981 E1012: Type mismatch; expected list<number> but got list<string>
982 Instead use |mapnew()|.
983
949 ============================================================================== 984 ==============================================================================
950 985
951 5. Namespace, Import and Export 986 5. Namespace, Import and Export
952 *vim9script* *vim9-export* *vim9-import* 987 *vim9script* *vim9-export* *vim9-import*
953 988
1053 For optimal startup speed, loading scripts should be postponed until they are 1088 For optimal startup speed, loading scripts should be postponed until they are
1054 actually needed. A recommended mechanism: 1089 actually needed. A recommended mechanism:
1055 1090
1056 1. In the plugin define user commands, functions and/or mappings that refer to 1091 1. In the plugin define user commands, functions and/or mappings that refer to
1057 an autoload script. > 1092 an autoload script. >
1058 command -nargs=1 SearchForStuff call searchfor#Stuff(<f-args>) 1093 command -nargs=1 SearchForStuff call searchfor#Stuff(<f-args>)
1059 1094
1060 < This goes in .../plugin/anyname.vim. "anyname.vim" can be freely chosen. 1095 < This goes in .../plugin/anyname.vim. "anyname.vim" can be freely chosen.
1061 1096
1062 2. In the autoload script do the actual work. You can import items from 1097 2. In the autoload script do the actual work. You can import items from
1063 other files to split up functionality in appropriate pieces. > 1098 other files to split up functionality in appropriate pieces. >
1064 vim9script 1099 vim9script
1065 import FilterFunc from "../import/someother.vim" 1100 import FilterFunc from "../import/someother.vim"
1066 def searchfor#Stuff(arg: string) 1101 def searchfor#Stuff(arg: string)
1067 var filtered = FilterFunc(arg) 1102 var filtered = FilterFunc(arg)
1068 ... 1103 ...
1069 < This goes in .../autoload/searchfor.vim. "searchfor" in the file name 1104 < This goes in .../autoload/searchfor.vim. "searchfor" in the file name
1070 must be exactly the same as the prefix for the function name, that is how 1105 must be exactly the same as the prefix for the function name, that is how