diff options
author | Bram Moolenaar <Bram@vim.org> | 2023-02-02 13:59:48 +0000 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2023-02-02 13:59:48 +0000 |
commit | be4e01637e71c8d5095c33b9861fd70b41476732 (patch) | |
tree | d521021e32c070a7c7a913fc96a14b3de8c81afe /runtime/doc | |
parent | 685bf83b73d0fe6fd36bb2949bebd6aae66a139e (diff) |
Update runtime files.
Diffstat (limited to 'runtime/doc')
-rw-r--r-- | runtime/doc/builtin.txt | 2 | ||||
-rw-r--r-- | runtime/doc/diff.txt | 4 | ||||
-rw-r--r-- | runtime/doc/eval.txt | 2 | ||||
-rw-r--r-- | runtime/doc/fold.txt | 4 | ||||
-rw-r--r-- | runtime/doc/ft_context.txt | 2 | ||||
-rw-r--r-- | runtime/doc/ft_mp.txt | 2 | ||||
-rw-r--r-- | runtime/doc/options.txt | 14 | ||||
-rw-r--r-- | runtime/doc/quickfix.txt | 4 | ||||
-rw-r--r-- | runtime/doc/tags | 16 | ||||
-rw-r--r-- | runtime/doc/term.txt | 9 | ||||
-rw-r--r-- | runtime/doc/testing.txt | 6 | ||||
-rw-r--r-- | runtime/doc/textprop.txt | 6 | ||||
-rw-r--r-- | runtime/doc/todo.txt | 55 | ||||
-rw-r--r-- | runtime/doc/usr_41.txt | 2 | ||||
-rw-r--r-- | runtime/doc/vim9.txt | 16 | ||||
-rw-r--r-- | runtime/doc/vim9class.txt | 227 |
16 files changed, 239 insertions, 132 deletions
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 265111d912..8b0da25ecc 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -1,4 +1,4 @@ -*builtin.txt* For Vim version 9.0. Last change: 2022 Dec 23 +*builtin.txt* For Vim version 9.0. Last change: 2023 Jan 17 VIM REFERENCE MANUAL by Bram Moolenaar diff --git a/runtime/doc/diff.txt b/runtime/doc/diff.txt index 2c1233bf63..40167a1b59 100644 --- a/runtime/doc/diff.txt +++ b/runtime/doc/diff.txt @@ -1,4 +1,4 @@ -*diff.txt* For Vim version 9.0. Last change: 2022 Dec 24 +*diff.txt* For Vim version 9.0. Last change: 2023 Jan 21 VIM REFERENCE MANUAL by Bram Moolenaar @@ -136,7 +136,7 @@ file for a moment and come back to the same file and be in diff mode again. buffers. The `:diffoff` command resets the relevant options to the values they had when -using `:diffsplit`, `:diffpatch` , `:diffthis`. or starting Vim in diff mode. +using `:diffsplit`, `:diffpatch`, `:diffthis`. or starting Vim in diff mode. When using `:diffoff` twice the last saved values are restored. Otherwise they are set to their default value: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 5fff3e8598..b133c5aa1a 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 9.0. Last change: 2023 Jan 03 +*eval.txt* For Vim version 9.0. Last change: 2023 Jan 12 VIM REFERENCE MANUAL by Bram Moolenaar diff --git a/runtime/doc/fold.txt b/runtime/doc/fold.txt index 6da244d5aa..bb1dcb6739 100644 --- a/runtime/doc/fold.txt +++ b/runtime/doc/fold.txt @@ -1,4 +1,4 @@ -*fold.txt* For Vim version 9.0. Last change: 2022 Nov 26 +*fold.txt* For Vim version 9.0. Last change: 2023 Jan 29 VIM REFERENCE MANUAL by Bram Moolenaar @@ -202,7 +202,7 @@ non-matching marker pairs. Example: > /* funcB() {{{2 */ void funcB() {} - +< *{{{* *}}}* A fold starts at a "{{{" marker. The following number specifies the fold level. What happens depends on the difference between the current fold level and the level given by the marker: diff --git a/runtime/doc/ft_context.txt b/runtime/doc/ft_context.txt index 9b081976eb..6303357ec7 100644 --- a/runtime/doc/ft_context.txt +++ b/runtime/doc/ft_context.txt @@ -48,7 +48,7 @@ typesetting command. That must be a function that takes a path and returns the command as a List. For example: > def ConTeXtCustomCommand(path: string): list<string> - return ['mtxrun', '--script', 'context', '--nonstopmode, path] + return ['mtxrun', '--script', 'context', '--nonstopmode', path] enddef context.ConTeXtTypeset("%", v:none, ConTeXtCustomCommand) diff --git a/runtime/doc/ft_mp.txt b/runtime/doc/ft_mp.txt index 0c6646f19e..595bc0241c 100644 --- a/runtime/doc/ft_mp.txt +++ b/runtime/doc/ft_mp.txt @@ -84,7 +84,7 @@ METAFONT buffers, and it is set to 0 by default in MetaPost buffers. Define additional keywords that end indented blocks. For instance, if you define: > - g:mp_end_tag = ['\<endfoo\>'] + g:mp_close_tag = ['\<endfoo\>'] < any line starting with `endfoo` will be de-indented compared to its previous line. diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 0fc00b4fb1..eece6008ed 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -1,4 +1,4 @@ -*options.txt* For Vim version 9.0. Last change: 2023 Jan 02 +*options.txt* For Vim version 9.0. Last change: 2023 Feb 01 VIM REFERENCE MANUAL by Bram Moolenaar @@ -1899,7 +1899,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'allowrevins' + off no CTRL-_ command 'antialias' + off don't use antialiased fonts - 'arabic' + off reset arabic-related options + 'arabic' + off reset arabic-related options 'arabicshape' + on correct character shapes 'backspace' + "" normal backspace 'backup' + off no backup file @@ -4943,7 +4943,7 @@ A jump table for the options with a short description can be found at |Q_op|. empty. Then set the 'term' option to have it take effect: > set keyprotocol= let &term = &term - +< *'keywordprg'* *'kp'* 'keywordprg' 'kp' string (default "man" or "man -s", DOS: ":help", @@ -5201,8 +5201,8 @@ A jump table for the options with a short description can be found at |Q_op|. are left blank. *lcs-multispace* multispace:c... - One or more characters to use cyclically to show for - multiple consecutive spaces. Overrides the "space" + One or more characters to use cyclically to show for + multiple consecutive spaces. Overrides the "space" setting, except for single spaces. When omitted, the "space" setting is used. For example, `:set listchars=multispace:---+` shows ten consecutive @@ -7784,8 +7784,8 @@ A jump table for the options with a short description can be found at |Q_op|. windows. * - Set highlight group to User{N}, where {N} is taken from the minwid field, e.g. %1*. Restore normal highlight with %* or %0*. - The difference between User{N} and StatusLine will be applied - to StatusLineNC for the statusline of non-current windows. + The difference between User{N} and StatusLine will be applied to + StatusLineNC for the statusline of non-current windows. The number N must be between 1 and 9. See |hl-User1..9| When displaying a flag, Vim removes the leading comma, if any, when diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index 7dc4fa3035..438cc6f65c 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -1,4 +1,4 @@ -*quickfix.txt* For Vim version 9.0. Last change: 2022 Sep 26 +*quickfix.txt* For Vim version 9.0. Last change: 2023 Jan 18 VIM REFERENCE MANUAL by Bram Moolenaar @@ -365,8 +365,6 @@ processing a quickfix or location list command, it will be aborted. If numbers [from] and/or [to] are given, the respective range of errors is listed. A negative number counts from the last error backwards, -1 being the last error. - The 'switchbuf' settings are respected when jumping - to a buffer. The |:filter| command can be used to display only the quickfix entries matching a supplied pattern. The pattern is matched against the filename, module name, diff --git a/runtime/doc/tags b/runtime/doc/tags index 49cabaa0e2..051c74b950 100644 --- a/runtime/doc/tags +++ b/runtime/doc/tags @@ -438,8 +438,10 @@ $quote eval.txt /*$quote* 'keymap' options.txt /*'keymap'* 'keymodel' options.txt /*'keymodel'* 'keyprotocol' options.txt /*'keyprotocol'* +'keywordprg' options.txt /*'keywordprg'* 'km' options.txt /*'km'* 'kmp' options.txt /*'kmp'* +'kp' options.txt /*'kp'* 'kpc' options.txt /*'kpc'* 'langmap' options.txt /*'langmap'* 'langmenu' options.txt /*'langmenu'* @@ -4416,6 +4418,11 @@ E1351 vim9class.txt /*E1351* E1352 vim9class.txt /*E1352* E1353 vim9class.txt /*E1353* E1354 vim9class.txt /*E1354* +E1355 vim9class.txt /*E1355* +E1356 vim9class.txt /*E1356* +E1357 vim9class.txt /*E1357* +E1358 vim9class.txt /*E1358* +E1359 vim9class.txt /*E1359* E136 starting.txt /*E136* E137 starting.txt /*E137* E138 starting.txt /*E138* @@ -5633,6 +5640,7 @@ View starting.txt /*View* Vim9 vim9.txt /*Vim9* Vim9-abstract-class vim9class.txt /*Vim9-abstract-class* Vim9-class vim9class.txt /*Vim9-class* +Vim9-class-member vim9class.txt /*Vim9-class-member* Vim9-class-overview vim9class.txt /*Vim9-class-overview* Vim9-enum vim9class.txt /*Vim9-enum* Vim9-script vim9.txt /*Vim9-script* @@ -6311,7 +6319,6 @@ cino-} indent.txt /*cino-}* cinoptions-values indent.txt /*cinoptions-values* class vim9class.txt /*class* class-function vim9class.txt /*class-function* -class-member vim9class.txt /*class-member* clear-undo undo.txt /*clear-undo* clearmatches() builtin.txt /*clearmatches()* client-server remote.txt /*client-server* @@ -7558,6 +7565,7 @@ getbufinfo() builtin.txt /*getbufinfo()* getbufline() builtin.txt /*getbufline()* getbufoneline() builtin.txt /*getbufoneline()* getbufvar() builtin.txt /*getbufvar()* +getcellwidths() builtin.txt /*getcellwidths()* getchangelist() builtin.txt /*getchangelist()* getchar() builtin.txt /*getchar()* getcharmod() builtin.txt /*getcharmod()* @@ -10042,6 +10050,7 @@ t_channel-variable eval.txt /*t_channel-variable* t_ci version4.txt /*t_ci* t_cil version4.txt /*t_cil* t_cl term.txt /*t_cl* +t_class-variable eval.txt /*t_class-variable* t_cm term.txt /*t_cm* t_cri version4.txt /*t_cri* t_cs term.txt /*t_cs* @@ -10106,6 +10115,7 @@ t_ms term.txt /*t_ms* t_nd term.txt /*t_nd* t_none-variable eval.txt /*t_none-variable* t_number-variable eval.txt /*t_number-variable* +t_object-variable eval.txt /*t_object-variable* t_op term.txt /*t_op* t_se term.txt /*t_se* t_sf1 version4.txt /*t_sf1* @@ -10614,6 +10624,7 @@ v:t_TYPE eval.txt /*v:t_TYPE* v:t_blob eval.txt /*v:t_blob* v:t_bool eval.txt /*v:t_bool* v:t_channel eval.txt /*v:t_channel* +v:t_class eval.txt /*v:t_class* v:t_dict eval.txt /*v:t_dict* v:t_float eval.txt /*v:t_float* v:t_func eval.txt /*v:t_func* @@ -10621,6 +10632,7 @@ v:t_job eval.txt /*v:t_job* v:t_list eval.txt /*v:t_list* v:t_none eval.txt /*v:t_none* v:t_number eval.txt /*v:t_number* +v:t_object eval.txt /*v:t_object* v:t_string eval.txt /*v:t_string* v:termblinkresp eval.txt /*v:termblinkresp* v:termrbgresp eval.txt /*v:termrbgresp* @@ -11208,6 +11220,8 @@ zz scroll.txt /*zz* {rhs} map.txt /*{rhs}* {server} remote.txt /*{server}* {subject} helphelp.txt /*{subject}* +{{{ fold.txt /*{{{* {} intro.txt /*{}* } motion.txt /*}* +}}} fold.txt /*}}}* ~ change.txt /*~* diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt index 3336889852..cb4c676834 100644 --- a/runtime/doc/term.txt +++ b/runtime/doc/term.txt @@ -1,4 +1,4 @@ -*term.txt* For Vim version 9.0. Last change: 2023 Jan 09 +*term.txt* For Vim version 9.0. Last change: 2023 Jan 15 VIM REFERENCE MANUAL by Bram Moolenaar @@ -322,9 +322,14 @@ using the "xterm" workaround. These are the relevant entries (so far): PS "\033[200~" pasted text start |t_PS| PE "\033[201~" pasted text end |t_PE| - XM "\033[?1006;1000%?%p1%{1}%=%th%el%;" + XM "\033[?1006;1004;1000%?%p1%{1}%=%th%el%;" mouse enable / disable |t_XM| +The "XM" entry includes "1006" to enable SGR style mouse reporting. This +supports columns above 223. It also includes "1004" which enables focus +reporting. The t_fe and t_fd entries can be left empty (they don't have +entries in terminfo/termcap anyway). + *xterm-kitty* *kitty-terminal* The Kitty terminal is a special case. Mainly because it works differently from most other terminals, but also because, instead of trying the fit in and diff --git a/runtime/doc/testing.txt b/runtime/doc/testing.txt index beef79d486..71e5f7ccd5 100644 --- a/runtime/doc/testing.txt +++ b/runtime/doc/testing.txt @@ -223,12 +223,12 @@ test_ignore_error({expr}) *test_ignore_error()* Can also be used as a |method|: > GetErrorText()->test_ignore_error() - + test_mswin_event({event}, {args}) *test_mswin_event()* Generate a low-level MS-Windows {event} with arguments {args} - for testing Vim functionality. It works for MS-Windows GUI + for testing Vim functionality. It works for MS-Windows GUI and for the console. - + {event} is a String and the supported values are: "mouse" mouse event. "key" keyboard event. diff --git a/runtime/doc/textprop.txt b/runtime/doc/textprop.txt index c6178c39c1..3d0be6a1dd 100644 --- a/runtime/doc/textprop.txt +++ b/runtime/doc/textprop.txt @@ -108,7 +108,7 @@ prop_type_list([{props}]) get list of property types Manipulating text properties: prop_add({lnum}, {col}, {props}) add a text property -prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) +prop_add_list({props}, [{item}, ...]) add a text property at multiple positions. prop_clear({lnum} [, {lnum-end} [, {bufnr}]]) @@ -263,12 +263,12 @@ prop_add_list({props}, [{item}, ...]) It is not possible to add a text property with a "text" field here. - Example: + Example: > call prop_add_list(#{type: 'MyProp', id: 2}, \ [[1, 4, 1, 7], \ [1, 15, 1, 20], \ [2, 30, 3, 30]] - +< Can also be used as a |method|: > GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]]) diff --git a/runtime/doc/todo.txt b/runtime/doc/todo.txt index be14871779..4e58fa5522 100644 --- a/runtime/doc/todo.txt +++ b/runtime/doc/todo.txt @@ -1,4 +1,4 @@ -*todo.txt* For Vim version 9.0. Last change: 2023 Jan 09 +*todo.txt* For Vim version 9.0. Last change: 2023 Feb 02 VIM REFERENCE MANUAL by Bram Moolenaar @@ -38,6 +38,13 @@ browser use: https://github.com/vim/vim/issues/1234 *known-bugs* -------------------- Known bugs and current work ----------------------- +Errors when running tests with valgrind: +- test_codestyle.vim: e.g.: + command line..script /home/mool/vim/vim90/src/testdir/runtest.vim[569]..function RunTheTest[52]..Test_test_files line 6: keycode_check.vim: space before tab: Expected 0 but got 7 + command line..script /home/mool/vim/vim90/src/testdir/runtest.vim[569]..function RunTheTest[52]..Test_test_files line 10: setup.vim: trailing white space: Expected 0 but got 23 +- test_gui.vim: + Found errors in Test_gui_mouse_event(): + Upcoming larger works: - Make spell checking work with recent .dic/.aff files, e.g. French. #4916 Make Vim understand the format somehow? Search for "spell" below. @@ -53,18 +60,29 @@ Upcoming larger works: Further Vim9 improvements, possibly after launch: -- implement :class and :interface: See |vim9-classes| #11544 - inheritance: how about super()? - inheritance: new() method from parent used in child? - import/export of a class - type() should return different type for each class? - give error for shadowing (variable and argument) when defining a class or - interface, not later when compiling it. - object empty(), len() - can class define a method to be used for them? - how about lock/unlock? - When checking "implements" also check types of members and function args. +- implement :class and :interface: See |vim9-classes + - Change access: public by default, private by prefixing "_". + Check for error: can't have same name twice (ignoring "_" prefix). + - Private methods? + either: private def Func() + or: def _Func() + Perhaps use "private" keyword instead of "_" prefix? + - "final" object members - can only be set in the constructor. + - object empty(), len() - can class define a method to be used for them? + - how about lock/unlock? + - When checking "implements" also check types of members and function args. + - For chaining, allow using the class name as type for function return + value. + - Implement generics + - Add "instanceof" + - More efficient way for interface member index than iterating over list? + - a variant of type() that returns a different type for each class? + list<number> and list<string> should also differ. + - Issue #11822: any.Func() can be a dict or an object call, need to handle + this at runtime. - implement :type - implement :enum +- class local to a function - Use Vim9 for more runtime files. - Inline call to map() and filter(), better type checking. - When evaluating constants for script variables, some functions could work: @@ -72,16 +90,19 @@ Further Vim9 improvements, possibly after launch: - Implement as part of an expression: ++expr, --expr, expr++, expr--. Information missing in terminfo: -Priority: - t_RV request terminal version string; xterm: "\033[>c" - change in terminfo for "RV" uses the wrong escape sequence... ? -Mouse support: - on/off: hard coded in mch_setmouse() - use "XM" terminfo/termcap entry; - If it starts with "\E[?1006;1000%" then set 'ttymouse' to "sgr". + change in terminfo for "RV" uses the wrong escape sequence 7 - 14 Jan only Codes used for focus gained and lost (currently using use_xterm_like_mouse()) termcodes are hard-coded in set_termname(), not named. + Use the XF flag? enables recognizing the focus in/out events. + Check if t_fe is not empty. + Check for "1004" in t_XM. (disadvantage: only focus events when mouse is + used) - t_fe enable focus-event tracking - t_fd disable focus-event tracking +Modifiers for various keys +- Decode kitty key protocol Meta and use MOD_MASK_META. Document <T-k> +- flag to indicate "xterm compatible modifiers" ? Underline and similar: - t_AU - Set underline color: like "AF" and "AB" entries. - t_Ce undercurl and underline end @@ -124,6 +145,8 @@ Probably Vim internal, not in terminfo: - t_RK request terminal keyboard protocol state; sent after |t_TI| Already working, not properly documented: - t_u7 request cursor position +Also, with Alt-b we get รข, with Alt-Shift-b we should bet another character. +That does not appear to work with Kitty. #11913 Popup windows: - Add a function to redraw a specific popup window. Esp. to be used when diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 7a706af3cb..4e0cc480ca 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -1,4 +1,4 @@ -*usr_41.txt* For Vim version 9.0. Last change: 2022 Dec 20 +*usr_41.txt* For Vim version 9.0. Last change: 2023 Jan 17 VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/vim9.txt b/runtime/doc/vim9.txt index e13feee467..eb26982cae 100644 --- a/runtime/doc/vim9.txt +++ b/runtime/doc/vim9.txt @@ -105,7 +105,7 @@ script and `:def` functions; details are below: `:open` `:s` with only flags `:t` - `:xit` + `:xit` - Some commands, especially those used for flow control, cannot be shortened. E.g., `:throw` cannot be written as `:th`. *vim9-no-shorten* - You cannot use curly-braces names. @@ -265,7 +265,7 @@ Detail: this is because "Inner" will actually become a function reference to a function with a generated name. It is not possible to define a script-local function in a function. You can -define a local function and assign it to a script-local funcref (it must have +define a local function and assign it to a script-local Funcref (it must have been declared at the script level). It is possible to define a global function by using the "g:" prefix. @@ -388,7 +388,6 @@ used: > echo temp # Error! This is especially useful in a user command: > - command -range Rename { var save = @a @a = 'some expression' @@ -397,7 +396,6 @@ This is especially useful in a user command: > } And with autocommands: > - au BufWritePre *.go { var save = winsaveview() silent! exe ':%! some formatting command' @@ -746,7 +744,7 @@ continuation is used without a backslash and a line starts with a bar: > *E1050* To make it possible for the operator at the start of the line to be recognized, it is required to put a colon before a range. This example will -add "start" and print: > +add "start" and "print": > var result = start + print Like this: > @@ -805,7 +803,7 @@ Notes: echo [1, 2] [3, 4] - In some cases it is difficult for Vim to parse a command, especially when - commands are used as an argument to another command, such as `windo`. In + commands are used as an argument to another command, such as `:windo`. In those cases the line continuation with a backslash has to be used. @@ -1311,7 +1309,7 @@ Closures defined in a loop will share the same context. For example: > < *E1271* A closure must be compiled in the context that it is defined in, so that variables in that context can be found. This mostly happens correctly, except -when a function is marked for debugging with `breakadd` after it was compiled. +when a function is marked for debugging with `:breakadd` after it was compiled. Make sure to define the breakpoint before compiling the outer function. The "inloop" variable will exist only once, all closures put in the list refer @@ -1353,7 +1351,7 @@ closure: > } endfor -Using `echowindow` is useful in a timer, the messages go into a popup and will +Using `:echowindow` is useful in a timer, the messages go into a popup and will not interfere with what the user is doing when it triggers. @@ -1594,7 +1592,7 @@ That is because the declaration looks like a list of numbers, thus is equivalent to: > var ll: list<number> = [1, 2, 3] If you do want a more permissive list you need to declare the type: > - var ll: list<any = [1, 2, 3] + var ll: list<any> = [1, 2, 3] ll->extend(['x']) # OK diff --git a/runtime/doc/vim9class.txt b/runtime/doc/vim9class.txt index 135b3093bb..250e67537d 100644 --- a/runtime/doc/vim9class.txt +++ b/runtime/doc/vim9class.txt @@ -1,21 +1,22 @@ -*vim9class.txt* For Vim version 9.0. Last change: 2023 Jan 09 +*vim9class.txt* For Vim version 9.0. Last change: 2023 Jan 17 VIM REFERENCE MANUAL by Bram Moolenaar -NOTE - This is under development, anything can still change! - NOTE +NOTE - This is not finished yet, anything can still change! - NOTE Vim9 classes, objects, interfaces, types and enums. 1. Overview |Vim9-class-overview| 2. A simple class |Vim9-simple-class| -3. Using an abstract class |Vim9-abstract-class| -4. Using an interface |Vim9-using-interface| -5. More class details |Vim9-class| -6. Type definition |Vim9-type| -7. Enum |Vim9-enum| +3. Class members and functions |Vim9-class-member| +4. Using an abstract class |Vim9-abstract-class| +5. Using an interface |Vim9-using-interface| +6. More class details |Vim9-class| +7. Type definition |Vim9-type| +8. Enum |Vim9-enum| 9. Rationale 10. To be done later @@ -25,25 +26,25 @@ Vim9 classes, objects, interfaces, types and enums. 1. Overview *Vim9-class-overview* The fancy term is "object-oriented programming". You can find lots of study -material about this subject. Here we document what |Vim9| script provides, -assuming you know the basics already. Added are helpful hints about how -to use this functionality effectively. +material on this subject. Here we document what |Vim9| script provides, +assuming you know the basics already. Added are helpful hints about how to +use this functionality effectively. The basic item is an object: - An object stores state. It contains one or more variables that can each have a value. -- An object usually provides functions that manipulate its state. These +- An object provides functions that use and manipulate its state. These functions are invoked "on the object", which is what sets it apart from the traditional separation of data and code that manipulates the data. - An object has a well defined interface, with typed member variables and member functions. -- Objects are created by a class and all objects have the same interface. - This never changes, it is not dynamic. +- Objects are created from a class and all objects have the same interface. + This does not change at runtime, it is not dynamic. An object can only be created by a class. A class provides: - A new() method, the constructor, which returns an object for the class. This method is invoked on the class name: MyClass.new(). -- State shared by all objects of the class: class variables and constants. +- State shared by all objects of the class: class variables (class members). - A hierarchy of classes, with super-classes and sub-classes, inheritance. An interface is used to specify properties of an object: @@ -62,17 +63,18 @@ teachers use real-world objects to explain class relations and you might think your model should therefore reflect the real world. It doesn't! The model should match your purpose. -You will soon find that composition is often better than inheritance. Don't -waste time trying to find the optimal class model. Or waste time discussing -whether a square is a rectangle or that a rectangle is a square. It doesn't -matter. +Keep in mind that composition (an object contains other objects) is often +better than inheritance (an object extends another object). Don't waste time +trying to find the optimal class model. Or waste time discussing whether a +square is a rectangle or that a rectangle is a square. It doesn't matter. ============================================================================== 2. A simple class *Vim9-simple-class* -Let's start with a simple example: a class that stores a text position: > +Let's start with a simple example: a class that stores a text position (see +below for how to do this more efficiently): > class TextPosition this.lnum: number @@ -107,7 +109,7 @@ The object members "lnum" and "col" can be accessed directly: > < *E1317* *E1327* If you have been using other object-oriented languages you will notice that in Vim the object members are consistently referred to with the "this." -prefix. This is different from languages like Java and TypeScript. This +prefix. This is different from languages like Java and TypeScript. The naming convention makes the object members easy to spot. Also, when a variable does not have the "this." prefix you know it is not an object member. @@ -117,9 +119,9 @@ Member write access ~ Now try to change an object member directly: > pos.lnum = 9 -< *E1335* +< *E1335* This will give you an error! That is because by default object members can be -read but not set. That's why the class provides a method for it: > +read but not set. That's why the TextPosition class provides a method for it: > pos.SetLnum(9) @@ -128,12 +130,12 @@ way. Most often there is no problem using a value, while setting a value may have side effects that need to be taken care of. In this case, the SetLnum() method could check if the line number is valid and either give an error or use the closest valid value. - *:public* *E1331* + *:public* *E1331* If you don't care about side effects and want to allow the object member to be changed at any time, you can make it public: > public this.lnum: number - public this.col number + public this.col: number Now you don't need the SetLnum(), SetCol() and SetPosition() methods, setting "pos.lnum" directly above will no longer give an error. @@ -153,7 +155,7 @@ name: > this._col number Now you need to provide methods to get the value of the private members. -These are commonly call getters. We recommend using a name that starts with +These are commonly called getters. We recommend using a name that starts with "Get": > def GetLnum(): number @@ -181,6 +183,7 @@ Simplifying the new() method ~ Many constructors take values for the object members. Thus you very often see this pattern: > + class SomeClass this.lnum: number this.col: number @@ -188,6 +191,7 @@ this pattern: > this.lnum = lnum this.col = col enddef + endclass Not only is this text you need to write, it also has the type of each member twice. Since this is so common a shorter way to write new() is provided: > @@ -197,8 +201,24 @@ twice. Since this is so common a shorter way to write new() is provided: > The semantics are easy to understand: Providing the object member name, including "this.", as the argument to new() means the value provided in the -new() call is assigned to that object member. This mechanism is coming from -the Dart language. +new() call is assigned to that object member. This mechanism comes from the +Dart language. + +Putting together this way of using new() and making the members public results +in a much shorter class definition as what we started with: > + + class TextPosition + public this.lnum: number + public this.col: number + + def new(this.lnum, this.col) + enddef + + def SetPosition(lnum: number, col: number) + this.lnum = lnum + this.col = col + enddef + endclass The sequence of constructing a new object is: 1. Memory is allocated and cleared. All values are zero/false/empty. @@ -208,48 +228,15 @@ The sequence of constructing a new object is: 3. Arguments in the new() method in the "this.name" form are assigned. 4. The body of the new() method is executed. -TODO: for a sub-class the constructor of the parent class will be invoked -somewhere. - +If the class extends a parent class, the same thing happens. In the second +step the members of the parent class are done first. There is no need to call +"super()" or "new()" on the parent. ============================================================================== -3. Using an abstract class *Vim9-abstract-class* - -An abstract class forms the base for at least one sub-class. In the class -model one often finds that a few classes have the same properties that can be -shared, but a class with those properties does not have enough state to create -an object from. A sub-class must extend the abstract class and add the -missing state and/or methods before it can be used to create objects for. - -An abstract class does not have a new() method. - -For example, a Shape class could store a color and thickness. You cannot -create a Shape object, it is missing the information about what kind of shape -it is. The Shape class functions as the base for a Square and a Triangle -class, for which objects can be created. Example: > - - abstract class Shape - this.color = Color.Black - this.thickness = 10 - endclass - - class Square extends Shape - this.size: number - - def new(this.size) - enddef - endclass - - class Triangle extends Shape - this.base: number - this.height: number +3. class members and functions *Vim9-class-member* - def new(this.base, this.height) - enddef - endclass -< - *class-member* *:static* *E1337* *E1338* + *:static* *E1337* *E1338* Class members are declared with "static". They are used by the name without a prefix: > @@ -263,18 +250,19 @@ prefix: > endclass < *E1340* *E1341* Since the name is used as-is, shadowing the name by a function argument name -or variable name is not allowed. +or local variable name is not allowed. Just like object members the access can be made private by using an underscore as the first character in the name, and it can be made public by prefixing "public": > - class OtherThing - static total: number # anybody can read, only class can write - static _sum: number # only class can read and write - public static result: number # anybody can read and write - endclass + + class OtherThing + static total: number # anybody can read, only class can write + static _sum: number # only class can read and write + public static result: number # anybody can read and write + endclass < - *class-function* + *class-function* Class functions are also declared with "static". They have no access to object members, they cannot use the "this" keyword. > @@ -282,7 +270,7 @@ object members, they cannot use the "this" keyword. > this.size: number static totalSize: number - " Clear the total size and return the value it had before. + # Clear the total size and return the value it had before. static def ClearTotalSize(): number var prev = totalSize totalSize = 0 @@ -290,10 +278,51 @@ object members, they cannot use the "this" keyword. > enddef endclass +Inside the class the function can be called by name directly, outside the +class the class name must be prefixed: `OtherThing.ClearTotalSize()`. ============================================================================== -4. Using an interface *Vim9-using-interface* +4. Using an abstract class *Vim9-abstract-class* + +An abstract class forms the base for at least one sub-class. In the class +model one often finds that a few classes have the same properties that can be +shared, but a class with these properties does not have enough state to create +an object from. A sub-class must extend the abstract class and add the +missing state and/or methods before it can be used to create objects for. + +For example, a Shape class could store a color and thickness. You cannot +create a Shape object, it is missing the information about what kind of shape +it is. The Shape class functions as the base for a Square and a Triangle +class, for which objects can be created. Example: > + + abstract class Shape + this.color = Color.Black + this.thickness = 10 + endclass + + class Square extends Shape + this.size: number + + def new(this.size) + enddef + endclass + + class Triangle extends Shape + this.base: number + this.height: number + + def new(this.base, this.height) + enddef + endclass +< +An abstract class is defined the same way as a normal class, except that it< |