adam/vim
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

runtime(doc): Improve the documentation for Vim9 classes (#13828)

Browse Source 
* Emend textual typos
* Emend syntactic errors in examples
* Acknowledge no support for abstract static methods
* Acknowledge the non-ubiquity of instance qualification

"This" was never allowed in method declarations, e.g.:
    class A
        def this.M()
        enddef
    endclass

and, since patch 9.0.2167, "this" can no longer be used in field
declarations, e.g.:
    class B
        var this.f: string
    endclass

* Recognise abstract child classes
* Reword an ambiguous turn of phrase

Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Ernie Rael <errael@raelity.com>
Signed-off-by: Yegappan Lakshmanan <yegappan@yahoo.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
This commit is contained in:
Aliaksei Budavei
2024-01-07 17:52:10 +03:00
committed by GitHub
parent 5d5cbb2b9a
commit b21499537f
1 changed files with 21 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
runtime/doc/vim9class.txt
View File

@ -1,4 +1,4 @@
*vim9class.txt* For Vim version 9.1. Last change: 2024 Jan 01 *vim9class.txt* For Vim version 9.1. Last change: 2024 Jan 06
VIM REFERENCE MANUAL by Bram Moolenaar VIM REFERENCE MANUAL by Bram Moolenaar
@ -106,17 +106,17 @@ The object variables "lnum" and "col" can be accessed directly: >
echo $'The text position is ({pos.lnum}, {pos.col})' echo $'The text position is ({pos.lnum}, {pos.col})'
< *E1317* *E1327* *:this* < *E1317* *E1327* *:this*
If you have been using other object-oriented languages you will notice that in If you have been using other object-oriented languages you will notice that in
Vim, within a class definition, the object members are consistently referred Vim, within a class definition, the declared object members are consistently
to with the "this." prefix. This is different from languages like Java and referred to with the "this." prefix. This is different from languages like
TypeScript. The naming convention makes the object members easy to spot. Java and TypeScript. The naming convention makes the object members easy to
Also, when a variable does not have the "this." prefix you know it is not an spot. Also, when a variable does not have the "this." prefix you know it is
object variable. not an object variable.
*E1411* *E1411*
From outside the class definition, access an object's methods and variables by From outside the class definition, access an object's methods and variables by
using the object name followed by a dot following by the member: > using the object name followed by a dot following by the member: >
pos.lnum pos.lnum
pos.setCol(10) pos.SetCol(10)
< <
*E1405* *E1406* *E1405* *E1406*
A class name cannot be used as an expression. A class name cannot be used in A class name cannot be used as an expression. A class name cannot be used in
@ -164,7 +164,7 @@ from outside the class or its sub-classes, you can make them protected. This
is done by prefixing an underscore to the name: > is done by prefixing an underscore to the name: >
var _lnum: number var _lnum: number
var _col number var _col: number
Now you need to provide methods to get the value of the protected variables. Now you need to provide methods to get the value of the protected variables.
These are commonly called getters. We recommend using a name that starts with These are commonly called getters. We recommend using a name that starts with
@ -174,7 +174,7 @@ These are commonly called getters. We recommend using a name that starts with
return this._lnum return this._lnum
enddef enddef
def GetCol() number def GetCol(): number
return this._col return this._col
enddef enddef
@ -330,7 +330,8 @@ variables but they have no access to the object variables, they cannot use the
Inside the class the class method can be called by name directly, outside the Inside the class the class method can be called by name directly, outside the
class the class name must be prefixed: `OtherThing.ClearTotalSize()`. To use class the class name must be prefixed: `OtherThing.ClearTotalSize()`. To use
a super class method in a child class, the class name must be prefixed. a class method from a parent class in a child class, the class name must be
prefixed.
Just like object methods the access can be made protected by using an Just like object methods the access can be made protected by using an
underscore as the first character in the method name: > underscore as the first character in the method name: >
@ -492,17 +493,15 @@ prefix when defining the method: >
abstract class Shape abstract class Shape
abstract def Draw() abstract def Draw()
abstract static def SetColor()
endclass endclass
< <
A static method in an abstract class cannot be an abstract method. A static method in an abstract class cannot be an abstract method.
*E1373* *E1373*
A class extending the abstract class must implement all the abstract methods. A non-abstract class extending the abstract class must implement all the
The signature (arguments, argument types and return type) must be exactly the abstract methods. The signature (arguments, argument types and return type)
same. If the return type of a method is a class, then that class or one of must be exactly the same. If the return type of a method is a class, then
its subclasses can be used in the extended method. Class methods in an that class or one of its subclasses can be used in the extended method.
abstract class can also be abstract methods.
============================================================================== ==============================================================================
@ -610,7 +609,7 @@ once. They can appear in any order, although this order is recommended: >
< *E1355* *E1369* < *E1355* *E1369*
Each variable and method name can be used only once. It is not possible to Each variable and method name can be used only once. It is not possible to
define a method with the same name and different type of arguments. It is not define a method with the same name and different type of arguments. It is not
possible to use a public and protected member variable with the same name. A possible to use a public and protected member variable with the same name. An
object variable name used in a super class cannot be reused in a child class. object variable name used in a super class cannot be reused in a child class.
@ -688,7 +687,7 @@ Inside a class, in between `:class` and `:endclass`, these items can appear:
- A class variable declaration: > - A class variable declaration: >
static var _protectedClassVariableName: memberType static var _protectedClassVariableName: memberType
static var readonlyClassVariableName: memberType static var readonlyClassVariableName: memberType
static var public readwriteClassVariableName: memberType public static var readwriteClassVariableName: memberType
- A constructor method: > - A constructor method: >
def new(arguments) def new(arguments)
def newName(arguments) def newName(arguments)
@ -747,7 +746,7 @@ null object ~
When a variable is declared to have the type of an object, but it is not When a variable is declared to have the type of an object, but it is not
initialized, the value is null. When trying to use this null object Vim often initialized, the value is null. When trying to use this null object Vim often
does not know what class was supposed to be used. Vim then cannot check if does not know what class was supposed to be used. Vim then cannot check if
a variable name is correct and you will get an "Using a null object" error, a variable name is correct and you will get a "Using a null object" error,
even when the variable name is invalid. *E1360* *E1362* even when the variable name is invalid. *E1360* *E1362*
@ -787,7 +786,7 @@ the name, you can define the constructor like this: >
< <
When using the default new() method, if the order of the object variables in When using the default new() method, if the order of the object variables in
the class is changed later, then all the callers of the default new() method the class is changed later, then all the callers of the default new() method
needs to change. To avoid this, the new() method can be explicitly defined need to change. To avoid this, the new() method can be explicitly defined
without any arguments. without any arguments.
*E1328* *E1328*
@ -993,7 +992,7 @@ in the body, while for other variables this is not needed and often omitted.
This leads to a mix of variables with and without "this.", which is This leads to a mix of variables with and without "this.", which is
inconsistent. inconsistent.
For |Vim9| classes the "this." prefix is always used. Also for declaring the For |Vim9| classes the "this." prefix is always used for declared methods and
variables. Simple and consistent. When looking at the code inside a class variables. Simple and consistent. When looking at the code inside a class
it's also directly clear which variable references are object variables and it's also directly clear which variable references are object variables and
which aren't. which aren't.
@ -1029,7 +1028,7 @@ Following that Vim object variables could be declared like this: >
endclass endclass
Some users pointed out that this looks more like an assignment than a Some users pointed out that this looks more like an assignment than a
declaration. Adding "var" changes that: > declaration. Adding "var" and omitting "this." changes that: >
class Point class Point
var x: number var x: number
var y = 0 var y = 0