Mercurial > vim

comparison runtime/doc/vim9.txt @ 20856:83cfa1ef1bf2

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/65e0d77a66b7e50beb562ad554ace46c32ef8f0f Author: Bram Moolenaar <Bram@vim.org> Date: Sun Jun 14 17:29:55 2020 +0200 Update runtime files
author Bram Moolenaar <Bram@vim.org>
date Sun, 14 Jun 2020 17:45:04 +0200
parents 74e3316c1d5a
children 59f93c2d2551
comparison
equal deleted inserted replaced
20855:6390b8b611fb 20856:83cfa1ef1bf2
1 *vim9.txt* For Vim version 8.2. Last change: 2020 May 25 1 *vim9.txt* For Vim version 8.2. Last change: 2020 Jun 14
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
104 for item in itemlist 104 for item in itemlist
105 ... 105 ...
106 106
107 107
108 Functions and variables are script-local by default ~ 108 Functions and variables are script-local by default ~
109 109 *vim9-scopes*
110 When using `:function` or `:def` to specify a new function at the script level 110 When using `:function` or `:def` to specify a new function at the script level
111 in a Vim9 script, the function is local to the script, as if "s:" was 111 in a Vim9 script, the function is local to the script, as if "s:" was
112 prefixed. Using the "s:" prefix is optional. 112 prefixed. Using the "s:" prefix is optional.
113 113
114 To define or use a global function or variable the "g:" prefix must be used. 114 To define or use a global function or variable the "g:" prefix must be used.
134 Vim9 script script-local functions are defined once when the script is sourced 134 Vim9 script script-local functions are defined once when the script is sourced
135 and cannot be deleted or replaced. 135 and cannot be deleted or replaced.
136 136
137 137
138 Variable declarations with :let and :const ~ 138 Variable declarations with :let and :const ~
139 139 *vim9-declaration*
140 Local variables need to be declared with `:let`. Local constants need to be 140 Local variables need to be declared with `:let`. Local constants need to be
141 declared with `:const`. We refer to both as "variables". 141 declared with `:const`. We refer to both as "variables".
142 142
143 Variables can be local to a script, function or code block: > 143 Variables can be local to a script, function or code block: >
144 vim9script 144 vim9script
386 The first form is a mandatory argument, the caller 386 The first form is a mandatory argument, the caller
387 must always provide them. 387 must always provide them.
388 The second and third form are optional arguments. 388 The second and third form are optional arguments.
389 When the caller omits an argument the {value} is used. 389 When the caller omits an argument the {value} is used.
390 390
391 The function will be compiled into instructions when
392 called, or when `:defcompile` is used. Syntax and
393 type errors will be produced at that time.
394
391 NOTE: It is possible to nest `:def` inside another 395 NOTE: It is possible to nest `:def` inside another
392 `:def`, but it is not possible to nest `:def` inside 396 `:def`, but it is not possible to nest `:def` inside
393 `:function`, for backwards compatibility. 397 `:function`, for backwards compatibility.
394 398
395 [!] is used as with `:function`. Note that in Vim9 399 [!] is used as with `:function`. Note that in Vim9
396 script script-local functions cannot be deleted or 400 script script-local functions cannot be deleted or
397 redefined. 401 redefined later in the same script.
398 402
399 *:enddef* 403 *:enddef*
400 :enddef End of a function defined with `:def`. 404 :enddef End of a function defined with `:def`.
401 405
402 406
403 If the script the function is defined in is Vim9 script, then script-local 407 If the script the function is defined in is Vim9 script, then script-local
404 variables can be accessed without the "s:" prefix. They must be defined 408 variables can be accessed without the "s:" prefix. They must be defined
405 before the function. If the script the function is defined in is legacy 409 before the function is compiled. If the script the function is defined in is
406 script, then script-local variables must be accessed with the "s:" prefix. 410 legacy script, then script-local variables must be accessed with the "s:"
411 prefix.
407 412
408 *:defc* *:defcompile* 413 *:defc* *:defcompile*
409 :defc[ompile] Compile functions defined in the current script that 414 :defc[ompile] Compile functions defined in the current script that
410 were not compiled yet. 415 were not compiled yet.
411 This will report errors found during the compilation. 416 This will report errors found during the compilation.
553 be exported. 558 be exported.
554 559
555 Alternatively, an export statement can be used to export several already 560 Alternatively, an export statement can be used to export several already
556 defined (otherwise script-local) items: > 561 defined (otherwise script-local) items: >
557 export {EXPORTED_CONST, someValue, MyFunc, MyClass} 562 export {EXPORTED_CONST, someValue, MyFunc, MyClass}
563 <
564 *E1042*
565 `:export` can only be used in Vim9 script, at the script level.
558 566
559 567
560 Import ~ 568 Import ~
561 *:import* *:imp* 569 *:import* *:imp*
562 The exported items can be imported individually in another Vim9 script: > 570 The exported items can be imported individually in another Vim9 script: >
627 < This goes in .../import/someother.vim. 635 < This goes in .../import/someother.vim.
628 636
629 637
630 Import in legacy Vim script ~ 638 Import in legacy Vim script ~
631 639
632 If an `import` statement is used in legacy Vim script, for identifier the 640 If an `import` statement is used in legacy Vim script, the script-local "s:"
633 script-local "s:" namespace will be used, even when "s:" is not specified. 641 namespace will be used for the imported item, even when "s:" is not specified.
634 642
635 643
636 ============================================================================== 644 ==============================================================================
637 645
638 9. Rationale *vim9-rationale* 646 9. Rationale *vim9-rationale*
671 The syntax for types is similar to Java, since it is easy to understand and 679 The syntax for types is similar to Java, since it is easy to understand and
672 widely used. The type names are what was used in Vim before, with some 680 widely used. The type names are what was used in Vim before, with some
673 additions such as "void" and "bool". 681 additions such as "void" and "bool".
674 682
675 683
676 JavaScript/TypeScript syntax and semantics ~ 684 Compiling functions early ~
685
686 Functions are compiled when called or when `:defcompile` is used. Why not
687 compile them early, so that syntax and type errors are reported early?
688
689 The functions can't be compiled right away when encountered, because there may
690 be forward references to functions defined later. Consider defining functions
691 A, B and C, where A calls B, B calls C, and C calls A again. It's impossible
692 to reorder the functions to avoid forward references.
693
694 An alternative would be to first scan through the file to locate items and
695 figure out their type, so that forward refeferences are found, and only then
696 execute the script and compile the functions. This means the script has to be
697 parsed twice, which is slower, and some conditions at the script level, such
698 as checking if a feature is supported, are hard to use. An attempt was made
699 to see if it works, but it turned out to be impossible to make work nicely.
700
701 It would be possible to compile all the functions at the end of the script.
702 The drawback is that if a function never gets called, the overhead of
703 compiling it counts anyway. Since startup speed is very important, in most
704 cases it's better to do it later and accept that syntax and type errors are
705 only reported then. In case these errors should be found early, e.g. when
706 testing, the `:defcompile` command will help out.
707
708
709 TypeScript syntax and semantics ~
677 710
678 Script writers have complained that the Vim script syntax is unexpectedly 711 Script writers have complained that the Vim script syntax is unexpectedly
679 different from what they are used to. To reduce this complaint popular 712 different from what they are used to. To reduce this complaint popular
680 languages will be used as an example. At the same time, we do not want to 713 languages are used as an example. At the same time, we do not want to abandon
681 abandon the well-known parts of legacy Vim script. 714 the well-known parts of legacy Vim script.
682 715
683 Since Vim already uses `:let` and `:const` and optional type checking is 716 Since Vim already uses `:let` and `:const` and optional type checking is
684 desirable, the JavaScript/TypeScript syntax fits best for variable 717 desirable, the JavaScript/TypeScript syntax fits best for variable
685 declarations. > 718 declarations. >
686 const greeting = 'hello' " string type is inferred 719 const greeting = 'hello' " string type is inferred
693 || and && operators work. Legacy Vim script: > 726 || and && operators work. Legacy Vim script: >
694 let result = 44 727 let result = 44
695 ... 728 ...
696 return result || 0 " returns 1 729 return result || 0 " returns 1
697 730
698 Vim9 script works like JavaScript, keep the value: > 731 Vim9 script works like JavaScript/Typescript, keep the value: >
699 let result = 44 732 let result = 44
700 ... 733 ...
701 return result || 0 " returns 44 734 return result || 0 " returns 44
702 735
703 On the other hand, overloading "+" to use both for addition and string 736 On the other hand, overloading "+" to use both for addition and string
725 package, no need to search many directories. 758 package, no need to search many directories.
726 - Once an import has been used, it can be cached and loading it again can be 759 - Once an import has been used, it can be cached and loading it again can be
727 avoided. 760 avoided.
728 - The Vim-specific use of "s:" to make things script-local can be dropped. 761 - The Vim-specific use of "s:" to make things script-local can be dropped.
729 762
763 When sourcing a Vim9 script from a legacy script, only the items defined
764 globally can be used, not the exported items. Alternatives considered:
765 - All the exported items become available as script-local items. This makes
766 it uncontrollable what items get defined.
767 - Use the exported items and make them global. Disadvantage is that it's then
768 not possible to avoid name clashes in the global namespace.
769 - Completely disallow sourcing a Vim9 script, require using `:import`. That
770 makes it difficult to use scripts for testing, or sourcing them from the
771 command line to try them out.
772
730 773
731 Classes ~ 774 Classes ~
732 775
733 Vim supports interfaces to Perl, Python, Lua, Tcl and a few others. But 776 Vim supports interfaces to Perl, Python, Lua, Tcl and a few others. But
734 these have never become widespread. When Vim 9 was designed a decision was 777 these have never become widespread. When Vim 9 was designed a decision was