Mercurial > vim

comparison runtime/doc/vim9.txt @ 29403:03e3b0034e31

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/5ed11535e0695163cec71033b98bb97356cf0113 Author: Bram Moolenaar <Bram@vim.org> Date: Wed Jul 6 13:18:11 2022 +0100 Update runtime files
author Bram Moolenaar <Bram@vim.org>
date Wed, 06 Jul 2022 14:30:05 +0200
parents f8116058ca76
children 34c1f4cd0c18
comparison
equal deleted inserted replaced
29402:cc9945ae0971 29403:03e3b0034e31
142 var name = value# error! 142 var name = value# error!
143 < *E1170* 143 < *E1170*
144 Do not start a comment with #{, it looks like the legacy dictionary literal 144 Do not start a comment with #{, it looks like the legacy dictionary literal
145 and produces an error where this might be confusing. #{{ or #{{{ are OK, 145 and produces an error where this might be confusing. #{{ or #{{{ are OK,
146 these can be used to start a fold. 146 these can be used to start a fold.
147
148 When starting to read a script file Vim doesn't know it is |Vim9| script until
149 the `vim9script` command is found. Until that point you would need to use
150 legacy comments: >
151 " legacy comment
152 vim9script
153 # Vim9 comment
154
155 That looks ugly, better put `vim9script` in the very first line: >
156 vim9script
157 # Vim9 comment
147 158
148 In legacy Vim script # is also used for the alternate file name. In Vim9 159 In legacy Vim script # is also used for the alternate file name. In Vim9
149 script you need to use %% instead. Instead of ## use %%% (stands for all 160 script you need to use %% instead. Instead of ## use %%% (stands for all
150 arguments). 161 arguments).
151 162
1685 1696
1686 1697
1687 Import ~ 1698 Import ~
1688 *:import* *:imp* *E1094* *E1047* *E1262* 1699 *:import* *:imp* *E1094* *E1047* *E1262*
1689 *E1048* *E1049* *E1053* *E1071* *E1236* 1700 *E1048* *E1049* *E1053* *E1071* *E1236*
1690 The exported items can be imported in another Vim9 script: > 1701 The exported items can be imported in another script. The import syntax has
1702 two forms. The simple form: >
1703 import {filename}
1704 <
1705 Where {filename} is an expression that must evaluate to a string. In this
1706 form the filename should end in ".vim" and the portion before ".vim" will
1707 become the script local name of the namespace. For example: >
1691 import "myscript.vim" 1708 import "myscript.vim"
1692 1709 <
1693 This makes each item available as "myscript.item". 1710 This makes each exported item in "myscript.vim" available as "myscript.item".
1694 *:import-as* *E1257* *E1261* 1711 *:import-as* *E1257* *E1261*
1695 In case the name is long or ambiguous, another name can be specified: > 1712 In case the name is long or ambiguous, this form can be used to specify
1696 import "thatscript.vim" as that 1713 another name: >
1714 import {longfilename} as {name}
1715 <
1716 In this form {name} becomes a specific script local name for the imported
1717 namespace. Therefore {name} must consist of letters, digits and '_', like
1718 |internal-variables|. The {longfilename} expression must evaluate to any
1719 filename. For example: >
1720 import "thatscript.vim.v2" as that
1697 < *E1060* *E1258* *E1259* *E1260* 1721 < *E1060* *E1258* *E1259* *E1260*
1698 Then you can use "that.EXPORTED_CONST", "that.someValue", etc. You are free 1722 Then you can use "that.item", etc. You are free to choose the name "that".
1699 to choose the name "that". Use something that will be recognized as referring 1723 Use something that will be recognized as referring to the imported script.
1700 to the imported script. Avoid command names, command modifiers and builtin 1724 Avoid command names, command modifiers and builtin function names, because the
1701 function names, because the name will shadow them. 1725 name will shadow them. Better not start the name starts with a capital
1702 If the name starts with a capital letter it can also shadow global user 1726 letter, since it can then also shadow global user commands and functions.
1703 commands and functions. Also, you cannot use the name for something else in 1727 Also, you cannot use the name for something else in the script, such as a
1704 the script, such as a function or variable name. 1728 function or variable name.
1705 1729
1706 In case the dot in the name is undesired, a local reference can be made for a 1730 In case the dot in the name is undesired, a local reference can be made for a
1707 function: > 1731 function: >
1708 var LongFunc = that.LongFuncName 1732 var LongFunc = that.LongFuncName
1709 1733
1711 const MAXLEN = that.MAX_LEN_OF_NAME 1735 const MAXLEN = that.MAX_LEN_OF_NAME
1712 1736
1713 This does not work for variables, since the value would be copied once and 1737 This does not work for variables, since the value would be copied once and
1714 when changing the variable the copy will change, not the original variable. 1738 when changing the variable the copy will change, not the original variable.
1715 You will need to use the full name, with the dot. 1739 You will need to use the full name, with the dot.
1716
1717 The full syntax of the command is:
1718 import {filename} [as {name}]
1719 Where {filename} is an expression that must evaluate to a string. Without the
1720 "as {name}" part it must end in ".vim". {name} must consist of letters,
1721 digits and '_', like |internal-variables|.
1722
1723 `:import` can also be used in legacy Vim script. The imported items still
1724 become script-local, even when the "s:" prefix is not given.
1725 1740
1726 `:import` can not be used in a function. Imported items are intended to exist 1741 `:import` can not be used in a function. Imported items are intended to exist
1727 at the script level and only imported once. 1742 at the script level and only imported once.
1728 1743
1729 The script name after `import` can be: 1744 The script name after `import` can be:
1750 echo that. 1765 echo that.
1751 name # Error! 1766 name # Error!
1752 echo that 1767 echo that
1753 .name # Error! 1768 .name # Error!
1754 1769
1755 To refer to a function in an imported script in a mapping, |<SID>| can be 1770 When you've imported a function from one script into a vim9 script you can
1756 used: > 1771 refer to the imported function in a mapping by prefixing it with |<SID>|: >
1757 noremap <silent> ,a :call <SID>name.Function()<CR> 1772 noremap <silent> ,a :call <SID>name.Function()<CR>
1758 1773
1759 When the mapping is defined "<SID>name." will be replaced with <SNR> and the 1774 When the mapping is defined "<SID>name." will be replaced with <SNR> and the
1760 script ID of the imported script. 1775 script ID of the imported script.
1761 An even simpler solution is using |<ScriptCmd>|: > 1776 An even simpler solution is using |<ScriptCmd>|: >
1762 noremap ,a <ScriptCmd>name.Function()<CR> 1777 noremap ,a <ScriptCmd>name.Function()<CR>
1778
1779 Note that this does not work for variables, only for functions.
1780
1781 *import-legacy* *legacy-import*
1782 `:import` can also be used in legacy Vim script. The imported namespace still
1783 becomes script-local, even when the "s:" prefix is not given. For example: >
1784 import "myfile.vim"
1785 call s:myfile.MyFunc()
1786
1787 And using the "as name" form: >
1788 import "otherfile.vim9script" as that
1789 call s:that.OtherFunc()
1790
1791 However, the namespace cannot be resolved on it's own: >
1792 import "that.vim"
1793 echo s:that
1794 " ERROR: E1060: Expected dot after name: s:that
1795 <
1796 This also affects the use of |<SID>| in the legacy mapping context. Since
1797 |<SID>| is only a valid prefix for a function and NOT for a namespace, you
1798 cannot use it
1799 to scope a function in a script local namespace. Instead of prefixing the
1800 function with |<SID>| you should use|<ScriptCmd>|. For example: >
1801 noremap ,a <ScriptCmd>:call s:that.OtherFunc()<CR>
1763 < 1802 <
1764 *:import-cycle* 1803 *:import-cycle*
1765 The `import` commands are executed when encountered. If script A imports 1804 The `import` commands are executed when encountered. If script A imports
1766 script B, and B (directly or indirectly) imports A, this will be skipped over. 1805 script B, and B (directly or indirectly) imports A, this will be skipped over.
1767 At this point items in A after "import B" will not have been processed and 1806 At this point items in A after "import B" will not have been processed and