From: Rico Tzschichholz Date: Wed, 19 Aug 2020 06:35:52 +0000 (+0200) Subject: manual: Update from wiki.gnome.org X-Git-Tag: 0.49.91~10 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ec3dbf3c1f06fcbca1e1fe46b83fff71475f815a;p=thirdparty%2Fvala.git manual: Update from wiki.gnome.org --- diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 1c0c95928..727dbcdbc 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -43,7 +43,7 @@
Vala source files There are two types of Vala input files. Vala source files (with a ".vala" extension) contain compileable Vala code. VAPI files (with a ".vapi" extension) describe an interface to a library, which can be written in either Vala or C. VAPI files are not compileable, and cannot contain any executable code - they are used when compiling Vala source files. -There are no requirements for how Vala source files are named, although there are conventions that can be followed. VAPI files are usually named to matched the pkg-config name of the library they relate to; they are described more fully in the documention about bindings. +There are no requirements for how Vala source files are named, although there are conventions that can be followed. VAPI files are usually named to matched the pkg-config name of the library they relate to; they are described more fully in the documentation about bindings. All Vala input files should be encoded in UTF-8.
@@ -62,7 +62,7 @@
Vala syntax -Vala's syntax is modelled on C#'s, and is therefore similar to all C-like languages. Curly braces are the basic delimeter, marking the start and end of a declaration or block of code. +Vala's syntax is modelled on C#'s, and is therefore similar to all C-like languages. Curly braces are the basic delimiter, marking the start and end of a declaration or block of code. There is no whitespace requirement, though this is a standard format that is used in Vala itself, and in many Vala projects. This format is a version of the coding style used for glib and gnome projects, but is not fully described in this document, other than being used for all examples. There is flexibility in the order of declarations in Vala. It is not required to pre-declare anything in order to use it before its declaration. Identifiers all follow the same rules, whether for local variables or class names. Legal identifiers must begin with one alphabetic character or underscore, followed by any number (zero or more) of alphanumerics or underscores (/[:alpha:_]([:alphanum:_])*/). It is also possible to use language keywords as identifiers, provided they are prefixed with a "@" when used in this way - the "@" is not considered a part of the identifier, it simply informs the compiler that the token should be considered as an identifier. @@ -79,7 +79,7 @@
Memory management Vala automatically uses the memory management system in GLib, which is a reference counting system. In order for this to work, the types used must support reference counting, as is the case with all GObject derived types and some others. -Memory is allocated and initialised by Vala when needed. The memory management scheme means it is also freed when possible. There is though no garbage collector, and currently reference cycles are not automatically broken. This can lead to memory being leaked. The main way to avoid this problem is to use weak references - these are not counted references and so cannot prevent memory being released, at the cost that they can be left refering to non existent data. +Memory is allocated and initialised by Vala when needed. The memory management scheme means it is also freed when possible. There is though no garbage collector, and currently reference cycles are not automatically broken. This can lead to memory being leaked. The main way to avoid this problem is to use weak references - these are not counted references and so cannot prevent memory being released, at the cost that they can be left referring to non existent data. Vala also allows use of pointers in much the same way as C. An instance of a pointer type refers directly to an address in memory. Pointers are not references, and therefore the automatic memory management rules do not apply in the same way. See Types/Pointer types. There are more details about memory management elsewhere, see Types, see Concepts.
@@ -118,7 +118,7 @@ Variables Within executable code in a method, an instance may be assigned to a variable. A variable has a name and is declared to refer to an instance of a particular data type. A typical variable declaration would be: -This declaration defines that "a" should become an expression that evaluates to an instance of the int type. The actual value of this expression will depend on which int instance is assigned to the variable. "a" can be assigned to more than once, with the most recent assigment being the only one considered when "a" is evaluated. Assignment to the variable is achieved via an assignment expression. Generally, the semantics of an assignment expression depends on the type of the variable. +This declaration defines that "a" should become an expression that evaluates to an instance of the int type. The actual value of this expression will depend on which int instance is assigned to the variable. "a" can be assigned to more than once, with the most recent assignment being the only one considered when "a" is evaluated. Assignment to the variable is achieved via an assignment expression. Generally, the semantics of an assignment expression depends on the type of the variable. A variable can take ownership of an instance, the precise meaning of which depends on the data type. In the context of reference types, it is possible to declare that a variable should not ever take ownership of an instance, this is done with the unowned keyword. See Types/Reference types. If a type is directly instantiated in a variable declaration statement, then the variable will be created owning that new instance, for example: @@ -183,7 +183,7 @@ -Whenever a SuperType instance is required, a SubType instance may be used. This is the extent of inheritence allowed to compact classes, but full classes are more featured. All classes that are not of compact type, can have virtual methods, and can implement interfaces. +Whenever a SuperType instance is required, a SubType instance may be used. This is the extent of inheritance allowed to compact classes, but full classes are more featured. All classes that are not of compact type, can have virtual methods, and can implement interfaces. To explain virtual functions, it makes sense to look at the alternative first. In the above example, it is legal for SubType to also define a method called "act" - this is called overriding. In this case, when a method called "act" is called on a SubType instance, which method is invoked depends on what type the invoker believed it was dealing with. The following example demonstrates this: @@ -317,7 +317,7 @@
Reference types -Instances of reference types are always stored on the heap. Variables of reference types contain references to the instances, rather than the instances themselves. Assinging an instance of a reference type to a variable or field will not make a copy of the data, instead only the reference to the data is copied. This means that both variables will refer to the same data, and so changes made to that data using one of the references will be visible when using the other. +Instances of reference types are always stored on the heap. Variables of reference types contain references to the instances, rather than the instances themselves. Assigning an instance of a reference type to a variable or field will not make a copy of the data, instead only the reference to the data is copied. This means that both variables will refer to the same data, and so changes made to that data using one of the references will be visible when using the other. Instances of any reference type can be assigned a variable that is declared "weak". This implies that the variable must not be known to the type instance. A reference counted type does not increase its reference count after being assigned to a weak variable: a weak variable cannot take ownership of an instance. reference-type: classed-type @@ -784,11 +784,11 @@ The Empty Statement does nothing, but is a valid statement nonetheless, and so can be used wherever a statement is required. empty-statement: ; -A Simple Statement consists of one a subset of expressions that are considered free-standing. Not all expressions are allowed, only those that potentially have a useful side effect - for example, arithmetic expressions cannot form simple statements on their own, but are allowed as part of an assignement expressions, which has a useful side effect. +A Simple Statement consists of one a subset of expressions that are considered free-standing. Not all expressions are allowed, only those that potentially have a useful side effect - for example, arithmetic expressions cannot form simple statements on their own, but are allowed as part of an assignment expressions, which has a useful side effect. simple-statement: statement-expression ; statement-expression: -assigment-expression +assignment-expression class-instantiation-expression struct instantiation-expression invocation-expression @@ -890,7 +890,7 @@
Jump Statements -Jump statements move execution to an arbitary point, dependent on the type of statement and its location. In any of these cases any transient scopes are ended appropriately: Concepts/Scope and naming and Statements/Simple statements. +Jump statements move execution to an arbitrary point, dependent on the type of statement and its location. In any of these cases any transient scopes are ended appropriately: Concepts/Scope and naming and Statements/Simple statements. A break statement moves execution to the first statement after the nearest enclosing while, do, for, or foreach statement. break-statement: break ; @@ -955,7 +955,7 @@
The global namespace Everything not declared within a particular namespace declaration is automatically in the global namespace. All defined namespaces are nested inside the global namespace at some depth. This is also where the fundamental types are defined. -If there is ever a need to explictly refer to an identifier in the global namespace, the identifier can be prefixed with global::. This will allow you, for example, to refer to a namespace which has the same name as a local variable. +If there is ever a need to explicitly refer to an identifier in the global namespace, the identifier can be prefixed with global::. This will allow you, for example, to refer to a namespace which has the same name as a local variable.
@@ -1133,7 +1133,7 @@
Types of delegate All delegate types in Vala are defined to be either static or instance delegates. This refers to whether the methods that may be considered instances of the delegate type are instance members of classes or structs, or not. -To assign an instance of an instance delegate, you must give the method name qualified with an identifier that refers to a class or struct instance. When an instance of an instance delegate is invoked, the method will act as though the method had been invoked directly: the "this" keyword will be usuable, instance data will be accessible, etc. +To assign an instance of an instance delegate, you must give the method name qualified with an identifier that refers to a class or struct instance. When an instance of an instance delegate is invoked, the method will act as though the method had been invoked directly: the "this" keyword will be usable, instance data will be accessible, etc. Instance and static delegate instances are not interchangeable.
@@ -1151,12 +1151,12 @@ [ qualified-namespace-name . ] delegate-name delegate-name: identifier -Parts of this syntax are based on the respective sections of the method decleration syntax (see Methods for details). +Parts of this syntax are based on the respective sections of the method declaration syntax (see Methods for details).
Using delegates -A delegate declaration defines a type. Instances of this type can then be assigned to variables (or fields, or paramaters) of this type. Vala does not allow creating methods at runtime, and so the values of delegate-type instances will be references to methods known at compile time. To simplify the process, inlined methods may be written (see Methods/Lambdas). +A delegate declaration defines a type. Instances of this type can then be assigned to variables (or fields, or parameters) of this type. Vala does not allow creating methods at runtime, and so the values of delegate-type instances will be references to methods known at compile time. To simplify the process, inlined methods may be written (see Methods/Lambdas). To call the method referenced by a delegate-type instance, use the same notation as for calling a method; instead of giving the method's name, give the identifier of the variable, as described in Expressions/Invocation expressions.
@@ -1228,7 +1228,7 @@ qualified-error-domain . error-type qualified-error-domain: [ qualified-namespace-name . ] error-domain-name -That is, throw an error that has already been created and can be identified by a name, or a new error created with a textual description. The message-expression is any expression that evaluates to a instace of the string type. +That is, throw an error that has already been created and can be identified by a name, or a new error created with a textual description. The message-expression is any expression that evaluates to a instance of the string type.
@@ -1302,7 +1302,7 @@ Types of class Vala supports three different types of class: GObject subclasses are any classes derived directly or indirectly from GLib.Object. This is the most powerful type of class, supporting all features described in this page. This means signals, managed properties, interfaces and complex construction methods, plus all features of the simpler class types. -Fundamental GType classes are those either without any superclass or that don't inherit at any level from GLib.Object. These classes support inheritence, interfaces, virtual methods, reference counting, unmanaged properties, and private fields. They are instantiated faster than GObject subclasses but are less powerful - it isn't recommended in general to use this form of class unless there is a specific reason to. +Fundamental GType classes are those either without any superclass or that don't inherit at any level from GLib.Object. These classes support inheritance, interfaces, virtual methods, reference counting, unmanaged properties, and private fields. They are instantiated faster than GObject subclasses but are less powerful - it isn't recommended in general to use this form of class unless there is a specific reason to. Compact classes, so called because they use less memory per instance, are the least featured of all class types. They are not registered with the GType system and do not support reference counting, virtual methods, or private fields. They do support unmanaged properties. Such classes are very fast to instantiate but not massively useful except when dealing with existing libraries. They are declared using the Compact attribute on the class, See Any non-compact class can also be defined as abstract. An abstract class cannot be instantiated and is used as a base class for derived classes.
@@ -1313,7 +1313,7 @@ Instance members are held per instance of the class. That is, each instance has its own copies of the members in its own instance scope. Changes to instance fields will only apply to that instance, calling instance methods will cause them to be executed in the scope of that instance. Class members are shared between all instances of a class. They can be accessed without an instance of the class, and class methods will execute in the scope of the class. Static members are shared between all instances of a class and any sub-classes of it. They can be accessed without an instance of the class, and static methods will execute in the scope of the class. -The distinction between class and static members is not common to other object models. The essential difference is that a sub-class will recieve a copy of all its base classes' class members. This is opposed to static members, of which there is only one copy - sub classes access can their base classes' static members because they are automatically imported into the class' scope. +The distinction between class and static members is not common to other object models. The essential difference is that a sub-class will receive a copy of all its base classes' class members. This is opposed to static members, of which there is only one copy - sub classes access can their base classes' static members because they are automatically imported into the class' scope.
@@ -1391,7 +1391,7 @@ inner-class-declaration: [ access-modifier ] class class-name [ inheritance-list ] { [ class-members ] } In Vala, a class must have either one or zero superclasses, where have zero superclasses has the result described in Classes/Types of class section. A class must meet all the prerequisites defined by the interfaces it wishes to implement, by implementing prerequisite interfaces or inheriting from a particular class. This latter requirement means it is potentially possible to have two interfaces that cannot be implemented by a single class. -Note: Interfaces are only supported for GType classes. Compact classes have access only to a limited form of inheritence, whereby they may inherit from exactly one or zero other compact classes. +Note: Interfaces are only supported for GType classes. Compact classes have access only to a limited form of inheritance, whereby they may inherit from exactly one or zero other compact classes. When declaring which class, if any, a new class subclasses, and which interfaces it implements, the names of those other classes or interfaces can be qualified relative to the class being declared. This means that, for example, if the class is declared as "class foo.Bar" (class "Bar" in namespace "foo") then it may subclass class "Base" in namespace "foo" simply with "class foo.Bar : Base". If an access modifier for the class is not given, the default "internal" is used. It is possible to declare a class definition to be "abstract." An abstract class is one they may not be instantiated, instead it first be subclassed by a non-abstract ("concrete") class. An abstract class declaration may include abstract class instance members. These act as templates for methods or properties that must be implemented in all concrete subclasses of the abstract class. It is thus guaranteed that any instance of the abstract class (which must be in fact an instance of a concrete subclass) will have a method or property as described in the abstract class definition. @@ -1435,7 +1435,7 @@ Construction Note: Construction only follows this process in GObject derived classes. -During instantiaion, after construction properties have been set, a series of blocks of code are executed. This is the process that prepares the instance for use. There are three types of construct blocks that a class may define: +During instantiation, after construction properties have been set, a series of blocks of code are executed. This is the process that prepares the instance for use. There are three types of construct blocks that a class may define: class-instance-constructor-declaration: construct { statement-list } Code in this block is executed on every instance of the class that is instantiated. It is run after construction properties have been set. @@ -1567,7 +1567,7 @@ Signals Note Signals are only available to GObject derived classes. -Signals are a system allowing a classed-type instance to emit events which can be recieved by arbitrary listeners. Receiving these events is achieved by connecting the signal to a handler, for which Vala has a specific syntax. Signals are integrated with the GLib MainLoop system, which provides a system for queueing events (i.e. signal emissions,) when needed - though this capability is not needed non-threaded applications. +Signals are a system allowing a classed-type instance to emit events which can be received by arbitrary listeners. Receiving these events is achieved by connecting the signal to a handler, for which Vala has a specific syntax. Signals are integrated with the GLib MainLoop system, which provides a system for queueing events (i.e. signal emissions,) when needed - though this capability is not needed non-threaded applications. class-instance-signal-declaration: [ class-member-visibility-modifier ] [ class-method-type-modifier ] signal return-type signal-name ( [ params-list ] ) ; signal-name: @@ -1585,7 +1585,7 @@ qualified-method-name lambda-expression This expression will request that the signal handler given be invoked whenever the signal is emitted. In order for such a connection expression to be legal, the handler must have the correct signature. The handler should be defined to accept as parameters the same types as the signal, but with an extra parameter before. This parameter should have the type of the class in which the signal is declared. When a signal is emitted all handlers are called with this parameter being the object by which the signal was emitted. -The time that an arbtirary expression is acceptable in this expression is when that expression evaluates to an instance of a delegate type, i.e. to a method that is a legal handler for the signal. For details on delegates, see Delegates. For details on lambda expressions see Methods/Lambdas. +The time that an arbitrary expression is acceptable in this expression is when that expression evaluates to an instance of a delegate type, i.e. to a method that is a legal handler for the signal. For details on delegates, see Delegates. For details on lambda expressions see Methods/Lambdas. Note that optional signal detail should be directly appended to the signal name, with no white space, e.g. o.notify["name"] += ... It is also possible to disconnect a signal handler using the following expression form: signal-disconnection-expression: @@ -1705,7 +1705,7 @@ - + @@ -1765,7 +1765,7 @@ The simplest interface declaration looks like this: -Unlike C# or Java, Vala's interfaces may include implemented methods, and so provide premade functionality to an implementing class, similar to mixins in other languages. All methods defined in a Vala interface are automatically considered to be virtual. Interfaces in Vala may also have prerequisites - classes or other interfaces that implementing classes must inherit from or implement. This is a more general form of the interface inheritence found in other languages. It should be noted that if you want to guarantee that all implementors of an interface are GObject type classes, you should give that class as a prerequisite for the interface. +Unlike C# or Java, Vala's interfaces may include implemented methods, and so provide premade functionality to an implementing class, similar to mixins in other languages. All methods defined in a Vala interface are automatically considered to be virtual. Interfaces in Vala may also have prerequisites - classes or other interfaces that implementing classes must inherit from or implement. This is a more general form of the interface inheritance found in other languages. It should be noted that if you want to guarantee that all implementors of an interface are GObject type classes, you should give that class as a prerequisite for the interface. Interfaces in Vala have a static scope, identified by the name of the interface. This is the only scope associated with them (i.e. there is no class or instance scope created for them at any time.) Non-instance members of the interface (static members and other declarations,) can be identified using this scope. For an overview of object oriented programming, see Concepts/Object oriented programming.