Server IP : 85.214.239.14 / Your IP : 3.137.170.38 Web Server : Apache/2.4.62 (Debian) System : Linux h2886529.stratoserver.net 4.9.0 #1 SMP Tue Jan 9 19:45:01 MSK 2024 x86_64 User : www-data ( 33) PHP Version : 7.4.18 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, MySQL : OFF | cURL : OFF | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : OFF Directory : /proc/self/root/proc/2/cwd/usr/share/vim/vim90/doc/ |
Upload File : |
*vim9class.txt* For Vim version 9.0. Last change: 2023 Feb 26 VIM REFERENCE MANUAL by Bram Moolenaar 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. 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 ============================================================================== 1. Overview *Vim9-class-overview* The fancy term is "object-oriented programming". You can find lots of study 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 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 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 (class members). - A hierarchy of classes, with super-classes and sub-classes, inheritance. An interface is used to specify properties of an object: - An object can declare several interfaces that it implements. - Different objects implementing the same interface can be used the same way. The class hierarchy allows for single inheritance. Otherwise interfaces are to be used where needed. Class modeling ~ You can model classes any way you like. Keep in mind what you are building, don't try to model the real world. This can be confusing, especially because 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. 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 (see below for how to do this more efficiently): > class TextPosition this.lnum: number this.col: number def new(lnum: number, col: number) this.lnum = lnum this.col = col enddef def SetLnum(lnum: number) this.lnum = lnum enddef def SetCol(col: number) this.col = col enddef def SetPosition(lnum: number, col: number) this.lnum = lnum this.col = col enddef endclass < *object* *Object* You can create an object from this class with the new() method: > var pos = TextPosition.new(1, 1) The object members "lnum" and "col" can be accessed directly: > echo $'The text position is ({pos.lnum}, {pos.col})' < *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. 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. Member write access ~ Now try to change an object member directly: > pos.lnum = 9 < *E1335* This will give you an error! That is because by default object members can be read but not set. That's why the TextPosition class provides a method for it: > pos.SetLnum(9) Allowing to read but not set an object member is the most common and safest 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* 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 Now you don't need the SetLnum(), SetCol() and SetPosition() methods, setting "pos.lnum" directly above will no longer give an error. *E1334* If you try to set an object member that doesn't exist you get an error: > pos.other = 9 < E1334: Object member not found: other ~ Private members ~ *E1332* *E1333* On the other hand, if you do not want the object members to be read directly, you can make them private. This is done by prefixing an underscore to the name: > this._lnum: number this._col number Now you need to provide methods to get the value of the private members. These are commonly called getters. We recommend using a name that starts with "Get": > def GetLnum(): number return this._lnum enddef def GetCol() number return this._col enddef This example isn't very useful, the members might as well have been public. It does become useful if you check the value. For example, restrict the line number to the total number of lines: > def GetLnum(): number if this._lnum > this._lineCount return this._lineCount endif return this._lnum enddef 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 def new(lnum: number, col: number) 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: > def new(this.lnum, this.col) enddef 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 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. 2. For each declared member that has an initializer, the expression is evaluated and assigned to the member. This happens in the sequence the members are declared in the class. 3. Arguments in the new() method in the "this.name" form are assigned. 4. The body of the new() method is executed. 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. class members and functions *Vim9-class-member* *:static* *E1337* *E1338* Class members are declared with "static". They are used by the name without a prefix: > class OtherThing this.size: number static totalSize: number def new(this.size) totalSize += this.size enddef endclass < *E1340* *E1341* Since the name is used as-is, shadowing the name by a function argument name 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-function* Class functions are also declared with "static". They have no access to object members, they cannot use the "this" keyword. > class OtherThing this.size: number static totalSize: number # Clear the total size and return the value it had before. static def ClearTotalSize(): number var prev = totalSize totalSize = 0 return prev 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 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 does not have any new() method. *E1359* ============================================================================== 5. Using an interface *Vim9-using-interface* The example above with Shape, Square and Triangle can be made more useful if we add a method to compute the surface of the object. For that we create the interface called HasSurface, which specifies one method Surface() that returns a number. This example extends the one above: > abstract class Shape this.color = Color.Black this.thickness = 10 endclass interface HasSurface def Surface(): number endinterface class Square extends Shape implements HasSurface this.size: number def new(this.size) enddef def Surface(): number return this.size * this.size enddef endclass class Triangle extends Shape implements HasSurface this.base: number this.height: number def new(this.base, this.height) enddef def Surface(): number return this.base * this.height / 2 enddef endclass If a class declares to implement an interface, all the items specified in the interface must appear in the class, with the same types. *E1348* *E1349* The interface name can be used as a type: > var shapes: list<HasSurface> = [ Square.new(12), Triangle.new(8, 15), ] for shape in shapes echo $'the surface is {shape.Surface()}' endfor ============================================================================== 6. More class details *Vim9-class* *Class* *class* Defining a class ~ *:class* *:endclass* *:abstract* A class is defined between `:class` and `:endclass`. The whole class is defined in one script file. It is not possible to add to a class later. A class can only be defined in a |Vim9| script file. *E1316* A class cannot be defined inside a function. It is possible to define more than one class in a script file. Although it usually is better to export only one main class. It can be useful to define types, enums and helper classes though. The `:abstract` keyword may be prefixed and `:export` may be used. That gives these variants: > class ClassName endclass export class ClassName endclass abstract class ClassName endclass export abstract class ClassName endclass < *E1314* The class name should be CamelCased. It must start with an uppercase letter. That avoids clashing with builtin types. *E1315* After the class name these optional items can be used. Each can appear only once. They can appear in any order, although this order is recommended: > extends ClassName implements InterfaceName, OtherInterface specifies SomeInterface < *E1355* Each member and function name can be used only once. It is not possible to define a function with the same name and different type of arguments. Extending a class ~ *extends* A class can extend one other class. *E1352* *E1353* *E1354* The basic idea is to build on top of an existing class, add properties to it. The extended class is called the "base class" or "super class". The new class is called the "child class". Object members from the base class are all taken over by the child class. It is not possible to override them (unlike some other languages). *E1356* *E1357* *E1358* Object methods of the base class can be overruled. The signature (arguments, argument types and return type) must be exactly the same. The method of the base class can be called by prefixing "super.". Other object methods of the base class are taken over by the child class. Class functions, including functions starting with "new", can be overruled, like with object methods. The function on the base class can be called by prefixing the name of the class (for class functions) or "super.". Unlike other languages, the constructor of the base class does not need to be invoked. In fact, it cannot be invoked. If some initialization from the base class also needs to be done in a child class, put it in an object method and call that method from every constructor(). If the base class did not specify a new() function then one was automatically created. This function will not be taken over by the child class. The child class can define its own new() function, or, if there isn't one, a new() function will be added automatically. A class implementing an interface ~ *implements* *E1346* *E1347* A class can implement one or more interfaces. The "implements" keyword can only appear once *E1350* . Multiple interfaces can be specified, separated by commas. Each interface name can appear only once. *E1351* A class defining an interface ~ *specifies* A class can declare its interface, the object members and methods, with a named interface. This avoids the need for separately specifying the interface, which is often done in many languages, especially Java. Items in a class ~ *E1318* *E1325* *E1326* Inside a class, in between `:class` and `:endclass`, these items can appear: - An object member declaration: > this._memberName: memberType this.memberName: memberType public this.memberName: memberType - A constructor method: > def new(arguments) def newName(arguments) - An object method: > def SomeMethod(arguments) < *E1329* For the object member the type must be specified. The best way is to do this explicitly with ": {type}". For simple types you can also use an initializer, such as "= 123", and Vim will see that the type is a number. Avoid doing this for more complex types and when the type will be incomplete. For example: > this.nameList = [] This specifies a list, but the item type is unknown. Better use: > this.nameList: list<string> The initialization isn't needed, the list is empty by default. *E1330* Some types cannot be used, such as "void", "null" and "v:none". Defining an interface ~ *:interface* *:endinterface* An interface is defined between `:interface` and `:endinterface`. It may be prefixed with `:export`: > interface InterfaceName endinterface export interface InterfaceName endinterface < *E1344* An interface can declare object members, just like in a class but without any initializer. *E1345* An interface can declare methods with `:def`, including the arguments and return type, but without the body and without `:enddef`. Example: > interface HasSurface this.size: number def Surface(): number endinterface An interface name must start with an uppercase letter. *E1343* The "Has" prefix can be used to make it easier to guess this is an interface name, with a hint about what it provides. An interface can only be defined in a |Vim9| script file. *E1342* null object ~ 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 does not know what class was supposed to be used. Vim then cannot check if a member name is correct and you will get an "Using a null object" error, even when the member name is invalid. *E1360* *E1362* Default constructor ~ In case you define a class without a new() method, one will be automatically defined. This default constructor will have arguments for all the object members, in the order they were specified. Thus if your class looks like: > class AutoNew this.name: string this.age: number this.gender: Gender endclass Then The default constructor will be: > def new(this.name = v:none, this.age = v:none, this.gender = v:none) enddef The "= v:none" default values make the arguments optional. Thus you can also call `new()` without any arguments. No assignment will happen and the default value for the object members will be used. This is a more useful example, with default values: > class TextPosition this.lnum: number = 1 this.col: number = 1 endclass If you want the constructor to have mandatory arguments, you need to write it yourself. For example, if for the AutoNew class above you insist on getting the name, you can define the constructor like this: > def new(this.name, this.age = v:none, this.gender = v:none) enddef < *E1328* Note that you cannot use another default value than "v:none" here. If you want to initialize the object members, do it where they are declared. This way you only need to look in one place for the default values. All object members will be used in the default constructor, also private access ones. If the class extends another one, the object members of that class will come first. Multiple constructors ~ Normally a class has just one new() constructor. In case you find that the constructor is often called with the same arguments you may want to simplify your code by putting those arguments into a second constructor method. For example, if you tend to use the color black a lot: > def new(this.garment, this.color, this.size) enddef ... var pants = new(Garment.pants, Color.black, "XL") var shirt = new(Garment.shirt, Color.black, "XL") var shoes = new(Garment.shoes, Color.black, "45") Instead of repeating the color every time you can add a constructor that includes it: > def newBlack(this.garment, this.size) this.color = Color.black enddef ... var pants = newBlack(Garment.pants, "XL") var shirt = newBlack(Garment.shirt, "XL") var shoes = newBlack(Garment.shoes, "9.5") Note that the method name must start with "new". If there is no method called "new()" then the default constructor is added, even though there are other constructor methods. ============================================================================== 7. Type definition *Vim9-type* *:type* A type definition is giving a name to a type specification. For Example: > :type ListOfStrings list<string> TODO: more explanation ============================================================================== 8. Enum *Vim9-enum* *:enum* *:endenum* An enum is a type that can have one of a list of values. Example: > :enum Color White Red Green Blue Black :endenum TODO: more explanation ============================================================================== 9. Rationale Most of the choices for |Vim9| classes come from popular and recently developed languages, such as Java, TypeScript and Dart. The syntax has been made to fit with the way Vim script works, such as using `endclass` instead of using curly braces around the whole class. Some common constructs of object-oriented languages were chosen very long ago when this kind of programming was still new, and later found to be sub-optimal. By this time those constructs were widely used and changing them was not an option. In Vim we do have the freedom to make different choices, since classes are completely new. We can make the syntax simpler and more consistent than what "old" languages use. Without diverting too much, it should still mostly look like what you know from existing languages. Some recently developed languages add all kinds of fancy features that we don't need for Vim. But some have nice ideas that we do want to use. Thus we end up with a base of what is common in popular languages, dropping what looks like a bad idea, and adding some nice features that are easy to understand. The main rules we use to make decisions: - Keep it simple. - No surprises, mostly do what other languages are doing. - Avoid mistakes from the past. - Avoid the need for the script writer to consult the help to understand how things work, most things should be obvious. - Keep it consistent. - Aim at an average size plugin, not at a huge project. Using new() for the constructor ~ Many languages use the class name for the constructor method. A disadvantage is that quite often this is a long name. And when changing the class name all constructor methods need to be renamed. Not a big deal, but still a disadvantage. Other languages, such as TypeScript, use a specific name, such as "constructor()". That seems better. However, using "new" or "new()" to create a new object has no obvious relation with "constructor()". For |Vim9| script using the same method name for all constructors seemed like the right choice, and by calling it new() the relation between the caller and the method being called is obvious. No overloading of the constructor ~ In Vim script, both legacy and |Vim9| script, there is no overloading of functions. That means it is not possible to use the same function name with different types of arguments. Therefore there also is only one new() constructor. With |Vim9| script it would be possible to support overloading, since arguments are typed. However, this gets complicated very quickly. Looking at a new() call one has to inspect the types of the arguments to know which of several new() methods is actually being called. And that can require inspecting quite a bit of code. For example, if one of the arguments is the return value of a method, you need to find that method to see what type it is returning. Instead, every constructor has to have a different name, starting with "new". That way multiple constructors with different arguments are possible, while it is very easy to see which constructor is being used. And the type of arguments can be properly checked. No overloading of methods ~ Same reasoning as for the constructor: It is often not obvious what type arguments have, which would make it difficult to figure out what method is actually being called. Better just give the methods a different name, then type checking will make sure it works as you intended. This rules out polymorphism, which we don't really need anyway. Single inheritance and interfaces ~ Some languages support multiple inheritance. Although that can be useful in some cases, it makes the rules of how a class works quite complicated. Instead, using interfaces to declare what is supported is much simpler. The very popular Java language does it this way, and it should be good enough for Vim. The "keep it simple" rule applies here. Explicitly declaring that a class supports an interface makes it easy to see what a class is intended for. It also makes it possible to do proper type checking. When an interface is changed any class that declares to implement it will be checked if that change was also changed. The mechanism to assume a class implements an interface just because the methods happen to match is brittle and leads to obscure problems, let's not do that. Using "this.member" everywhere ~ The object members in various programming languages can often be accessed in different ways, depending on the location. Sometimes "this." has to be prepended to avoid ambiguity. They are usually declared without "this.". That is quite inconsistent and sometimes confusing. A very common issue is that in the constructor the arguments use the same name as the object member. Then for these members "this." needs to be prefixed in the body, while for other members this is not needed and often omitted. This leads to a mix of members with and without "this.", which is inconsistent. For |Vim9| classes the "this." prefix is always used. Also for declaring the members. Simple and consistent. When looking at the code inside a class it's also directly clear which variable references are object members and which aren't. Using class members ~ Using "static member" to declare a class member is very common, nothing new here. In |Vim9| script these can be accessed directly by their name. Very much like how a script-local variable can be used in a function. Since object members are always accessed with "this." prepended, it's also quickly clear what kind of member it is. TypeScript prepends the class name before the class member, also inside the class. This has two problems: The class name can be rather long, taking up quite a bit of space, and when the class is renamed all these places need to be changed too. Declaring object and class members ~ The main choice is whether to use "var" as with variable declarations. TypeScript does not use it: > class Point { x: number; y = 0; } Following that Vim object members could be declared like this: > class Point this.x: number this.y = 0 endclass Some users pointed out that this looks more like an assignment than a declaration. Adding "var" changes that: > class Point var this.x: number var this.y = 0 endclass We also need to be able to declare class members using the "static" keyword. There we can also choose to leave out "var": > class Point var this.x: number static count = 0 endclass Or do use it, before "static": > class Point var this.x: number var static count = 0 endclass Or after "static": > class Point var this.x: number static var count = 0 endclass This is more in line with "static def Func()". There is no clear preference whether to use "var" or not. The two main reasons to leave it out are: 1. TypeScript, Java and other popular languages do not use it. 2. Less clutter. Using "ClassName.new()" to construct an object ~ Many languages use the "new" operator to create an object, which is actually kind of strange, since the constructor is defined as a method with arguments, not a command. TypeScript also has the "new" keyword, but the method is called "constructor()", it is hard to see the relation between the two. In |Vim9| script the constructor method is called new(), and it is invoked as new(), simple and straightforward. Other languages use "new ClassName()", while there is no ClassName() method, it's a method by another name in the class called ClassName. Quite confusing. Default read access to object members ~ Some users will remark that the access rules for object members are asymmetric. Well, that is intentional. Changing a value is a very different action than reading a value. The read operation has no side effects, it can be done any number of times without affecting the object. Changing the value can have many side effects, and even have a ripple effect, affecting other objects. When adding object members one usually doesn't think much about this, just get the type right. And normally the values are set in the new() method. Therefore defaulting to read access only "just works" in most cases. And when directly writing you get an error, which makes you wonder if you actually want to allow that. This helps writing code with fewer mistakes. Making object members private with an underscore ~ When an object member is private, it can only be read and changed inside the class (and in sub-classes), then it cannot be used outside of the class. Prepending an underscore is a simple way to make that visible. Various programming languages have this as a recommendation. In case you change your mind and want to make the object member accessible outside of the class, you will have to remove the underscore everywhere. Since the name only appears in the class (and sub-classes) they will be easy to find and change. The other way around is much harder: you can easily prepend an underscore to the object member inside the class to make it private, but any usage elsewhere you will have to track down and change. You may have to make it a "set" method call. This reflects the real world problem that taking away access requires work to be done for all places where that access exists. An alternative would have been using the "private" keyword, just like "public" changes the access in the other direction. Well, that's just to reduce the number of keywords. No protected object members ~ Some languages provide several ways to control access to object members. The most known is "protected", and the meaning varies from language to language. Others are "shared", "private" and even "friend". These rules make life more difficult. That can be justified in projects where many people work on the same, complex code where it is easy to make mistakes. Especially when refactoring or other changes to the class model. The Vim scripts are expected to be used in a plugin, with just one person or a small team working on it. Complex rules then only make it more complicated, the extra safety provide by the rules isn't really needed. Let's just keep it simple and not specify access details. ============================================================================== 10. To be done later Can a newSomething() constructor invoke another constructor? If yes, what are the restrictions? Thoughts: - Generics for a class: `class <Tkey, Tentry>` - Generics for a function: `def <Tkey> GetLast(key: Tkey)` - Mixins: not sure if that is useful, leave out for simplicity. Some things that look like good additions: - For testing: Mock mechanism An important class to be provided is "Promise". Since Vim is single threaded, connecting asynchronous operations is a natural way of allowing plugins to do their work without blocking the user. It's a uniform way to invoke callbacks and handle timeouts and errors. vim:tw=78:ts=8:noet:ft=help:norl: