Короткий вступ у сучасний Object Pascal для програмістів

За доброю традицією знайомство з мовою починають із самої базової та простої програми "Привіт, світ!". На Pascal вона виглядає так:

Це повноцінна програма, яку можна компілювати та запускати.

Решта цієї книги розповідає про мову Object Pascal, тому не очікуйте побачити щось більш привабливе, ніж речі командного рядка. Якщо Ви хочете побачити щось класне, просто створіть новий проект GUI у Lazarus (Проєкт → Новий проєкт → Застосунок). Вуаля — робоча програма з графічним інтерфейсом користувача, кросплатформна, з рідним виглядом усюди, використовуючи зручну бібліотеку візуальних компонентів. Lazarus і Free Pascal Compiler постачаються з великою кількістю готових модулів для роботи в мережі, GUI, бази даних, форматів файлів (XML, json, зображення…​), потоків і всього іншого, що може знадобитися. Я вже згадував свій крутий Castle Game Engine раніше :)

Щоб повернути значення з функції, присвойте щось магічній змінні Result. Можна вільно читати і встановлювати Result, наче локальній змінні.

Також можна розглядати ім’я функції (наприклад, MyFunction у прикладі вище) як змінну, якій можна присвоїти значення. Але я б не рекомендував це використовувати в новому коді, оскільки коли ім’я функції використовується в правій частині виразу присвоєння, це виглядає підозрілим.

Якщо потрібно викликати саму функцію рекурсивно, Ви, звичайно, можете це зробити. Якщо Ви викликаєте функцію без параметрів рекурсивно, обов’язково вкажть дужки "()" після назви функці (хоча в Паскалі Ви зазвичай можете опускати дужки для функцій без параметрів), це робить рекурсивний виклик функції без параметрів, що відрізняється від доступу до поточного результату цієї функції. Ось так:

Ви можете викликати Exit, щоб завершити виконання процедури або функції до того, як вона досягне остаточного end;. Якщо ви викликаєте Exit без параметрів у функції, вона поверне останнє, що ви встановили як Result. Ви також можете використовувати конструкцію Exit(X), щоб установити результат функції та вийти зараз — це так само, як конструкція return X у C-подібних мовах.

Зверніть увагу, що результат функції можна відхилити. Будь-яку функцію можна використовувати як процедуру. Це має сенс, якщо функція має якийсь побічний ефект (наприклад, вона змінює глобальну змінну), крім обчислення результату. Наприклад:

Використовуйте кострукції if .. then чи if .. then .. else щоб виконати певний код коли задоволена певна умова. На відміну від C-подібних мов, у Pascal вам не потрібно закривати умову в дужки.

"else" поєднується з останнім "if". Отже, це працює так, як ви очікуєте:

Хоча наведений вище приклад із вкладеним if правильний, у таких випадках часто краще розмістити вкладений if всередині блоку begin …​ end. Це робить код більш очевидним для читача, і він залишатиметься очевидним, навіть якщо ви зіпсуєте відступ. Покращена версія прикладу наведена нижче. Коли ви додаєте або видаляєте речення else у наведеному нижче коді, очевидно, до якої умови воно застосовуватиметься (до тесту A чи B), тому воно менш схильне до помилок.

Логічні оператори називаються and, or, not, xor. Їх сенс, мабуть, очевидний (пошукайте "exclusive or" якщо Ви не впевннені що виконує xor :)). Вони приймають логічні аргументи, і повертають результат типу boolean. Вони також можуть виконувати роль побітових операторів у випадку коли обидва аргументи - цілочисельні значення, у цьому випадку вони повертають ціле число.

Оператори відношення (порівняння) наступні: =, <>, >, <, <=, >=. Якщо ви звикли до C-подібних мов, зауважте, що в Pascal ви порівнюєте два значення (перевіряєте, чи вони рівні) за допомогою одного символу рівності A = B (на відміну від C, де ви використовуєте A == B). Спеціальним оператором присвоєння в Pascal є :=.

Логічні (або побітові) оператори мають вищий пріоритет, ніж оператори відношення. Вам може знадобитися використовувати дужки навколо деяких виразів, щоб мати потрібний порядок обчислень.

Ось, наприклад, помилка компіляції:

Наведене вище не компілюється, тому що компілятор спочатку хоче виконати побітове and в середині виразу: (0 and B). Це побітова операція, яка повертає ціле значення. Потім компілятор застосовує оператор =, який дає логічне значення A = (0 and B). І, нарешті, помилка "невідповідність типу" виникає після спроби порівняти логічне значення A = (0 and B) і ціле значення 0.

Ось це правильно:

Використовується оцінка короткого замикання. Розглянемо такий вираз:

Якщо необхідно виконати іншу дію залежно від значення якогось виразу, тоді корисним буде оператор case .. of .. end.

Речення else є необов’язковим (і відповідає default у C-подібних мовах). Якщо жодна умова не відповідає, і немає else, нічого не відбувається.

Якщо ви походите з C-подібних мов, і порівняйте це з інструкцією switch у цих мовах, ви помітите, що немає автоматичного провалу. Це свідоме благословення в Паскалі. Вам не потрібно пам’ятати про розміщення інструкцій break. Під час кожного виконання виконується щонайбільше одна гілка case, і все.

Перелічуваний тип у Паскалі — дуже гарний, непрозорий тип. Ймовірно, ви використовуватимете його набагато частіше, ніж переліки в інших мовах:)

Згідно з домовленістю до імен enum ставиться дволітерне скорочення імені типу, отже ak = скорочення для "Animal Kind". Це корисна домовленість, оскільки імена enum знаходяться в просторі імен модуля (глобальному). Таким чином, додавши до них префікс ak, ви мінімізуєте ймовірність конфліктів з іншими ідентифікаторами.

Той факт, що перерахований тип є непрозорим, означає, що його не можна просто призначити цілому числу. Однак для спеціального використання ви можете використати Ord(MyAnimalKind) для примусового перетворення enum на int або приведення типу TAnimalKind(MyInteger) для примусового перетворення int на enum. В останньому випадку переконайтеся, що спершу перевірте, чи MyInteger знаходиться в належному діапазоні (від 0 до Ord(High(TAnimalKind))).

Перелічувані та порядкові типи можуть використовуватися як індекси масиву:

Вони також можуть бути використані для створення наборів (внутрішніх бітових полів):

Про цикли repeat і while:

There are two differences between these loop types:

About the for I := …​ loops`:

The for I := .. to .. do …​ construction it similar to the C-like for loop. However, it’s more constrained, as you cannot specify arbitrary actions/tests to control the loop iteration. This is strictly for iterating over a consecutive numbers (or other ordinal types). The only flexibility you have is that you can use downto instead of to, to make numbers go downward.

In exchange, it looks clean, and is very optimized in execution. In particular, the expressions for the lower and higher bound are only calculated once, before the loop starts.

Note that the value of the loop counter variable (I in this example) should be considered undefined after the loop has finished, due to possible optimizations. Accessing the value of I after the loop may cause a compiler warning. Unless you exit the loop prematurely by Break or Exit: in such case, the counter variable is guaranteed to retain the last value.

About the for I in …​ loops:

The for I in .. do .. is similar to foreach construct in many modern languages. It works intelligently on many built-in types:

To simply output strings in Pascal, use the Write or WriteLn routine. The latter automatically adds a newline at the end.

This is a "magic" routine in Pascal. It takes a variable number of arguments and they can have any type. They are all converted to strings when displaying, with a special syntax to specify padding and number precision.

To explicitly use newline in the string, use the LineEnding constant (from FPC RTL). (The Castle Game Engine defines also a shorter NL constant.) Pascal strings do not interpret any special backslash sequences, so writing

doesn’t work like some of you would think. This will work:

or just this:

Note that this will only work in console applications. Make sure you have {$apptype CONSOLE} (and not {$apptype GUI}) defined in your main program file. On some operating systems it actually doesn’t matter and will work always (Unix), but on some operating systems trying to write something from a GUI application is an error (Windows).

In the Castle Game Engine: use WriteLnLog or WriteLnWarning, never WriteLn, to print debug information. They will be always directed to some useful output. On Unix, standard output. On Windows GUI application, log file. On Android, the Android logging facility (visible when you use adb logcat). The use of WriteLn should be limited to the cases when you write a command-line application (like a 3D model converter / generator) and you know that the standard output is available.

To convert an arbitrary number of arguments to a string (instead of just directly outputting them), you have a couple of options.

One unit can also use another unit. Another unit can be used in the interface section, or only in the implementation section. The former allows to define new public stuff (procedures, types…​) on top of another unit’s stuff. The latter is more limited (if you use a unit only in the implementation section, you can use its identifiers only in your implementation).

It is not allowed to have circular unit dependencies in the interface. That is, two units cannot use each other in the interface section. The reason is that in order to "understand" the interface section of a unit, the compiler must first "understand" all the units it uses in the interface section. Pascal language follows this rule strictly, and it allows a fast compilation and fully automatic detection on the compiler side what units need to be recompiled. There is no need to use complicated Makefile files for a simple task of compilation in Pascal, and there is no need to recompile everything just to make sure that all dependencies are updated correctly.

It is OK to make a circular dependency between units when at least one "usage" is only in the implementation. So it’s OK for unit A to use unit B in the interface, and then unit B to use unit A in the implementation.

Different units may define the same identifier. To keep the code simple to read and search, you should usually avoid it, but it’s not always possible. In such cases, the last unit on the uses clause "wins", which means that the identifiers it introduces hide the same identifiers introduced by earlier units.

You can always explicitly define a unit of a given identifier, by using it like MyUnit.MyIdentifier. This is the usual solution when the identifier you want to use from MyUnit is hidden by another unit. Of course you can also rearrange the order of units on your uses clause, although this can affect other declarations than the one you’re trying to fix.

In case of units, remember that they have two uses clauses: one in the interface, and another one in the implementation. The rule later units hide the stuff from earlier units is applied here consistently, which means that units used in the implementation section can hide identifiers from units used in the interface section. However, remember that when reading the interface section, only the units used in the interface matter. This may create a confusing situation, where two seemingly-equal declarations are considered different by the compiler:

The unit Graphics (from Lazarus LCL) defines the TColor type. But the compiler will fail to compile the above unit, claiming that you don’t implement a procedure ShowColor that matches the interface declaration. The problem is that unit GoogleMapsEngine also defines a TColor type. And it is used only in the implementation section, therefore it shadows the TColor definition only in the implementation. The equivalent version of the above unit, where the error is obvious, looks like this:

The solution is trivial in this case, just change the implementation to explicitly use TColor from Graphics unit. You could fix it also by moving the GoogleMapsEngine usage, to the interface section and earlier than Graphics, although this could result in other consequences in real-world cases, when UnitUsingColors would define more things.

Sometimes you want to take an identifier from one unit, and expose it in a new unit. The end result should be that using the new unit will make the identifier available in the namespace.

Sometimes this is necessary to preserve backward compatibility with previous unit versions. Sometimes it’s nice to "hide" an internal unit this way.

This can be done by redefining the identifier in your new unit.

Note that this trick cannot be done as easily with global procedures, functions and variables. With procedures and functions, you could expose a constant pointer to a procedure in another unit (see Callbacks (aka events, aka pointers to functions, aka procedural variables)), but that looks quite dirty.

The usual solution is then to create a trivial "wrapper" functions that underneath simply call the functions from the internal unit, passing the parameters and return values around.

To make this work with global variables, one can use global (unit-level) properties, see Properties.

We have classes. At the basic level, a class is just a container for

We have inheritance and virtual methods.

By default methods are not virtual, declare them with virtual to make them. Overrides must be marked with override, otherwise you will get a warning. To hide a method without overriding (usually you don’t want to do this, unless you now what you’re doing) use reintroduce.

To test the class of an instance at runtime, use the is operator. To typecast the instance to a specific class, use the as operator.

Instead of casting using X as TMyClass, you can also use the unchecked typecast TMyClass(X). This is faster, but results in an undefined behavior if the X is not, in fact, a TMyClass descendant. So don’t use the TMyClass(X) typecast, or use it only in a code where it’s blindingly obvious that it’s correct, for example right after testing with is:

Properties are a very nice "syntax sugar" to

Note that instead of specifying a method, you can also specify a field (typically a private field) to directly get or set. In the example above, the Color property uses a setter method SetColor. But for getting the value, the Color property refers directly to the private field FColor. Directly referring to a field is faster than implementing trivial getter or setter methods (faster for you, and faster at execution).

When declaring a property you specify:

The compiler checks that the types and parameters of indicated fields and methods match with the property type. For example, to read an Integer property you have to either provide an Integer field, or a parameter-less method that returns an Integer.

Technically, for the compiler, the "getter" and "setter" methods are just normal methods and they can do absolutely anything (including side-effects or randomization). But it’s a good convention to design properties to behave more-or-less like fields:

We have exceptions. They can be caught with try …​ except …​ end clauses, and we have finally sections like try …​ finally …​ end.

Note that the finally clause is executed even if you exit the block using the Exit (from function / procedure / method) or Break or Continue (from loop body).

See the Exceptions chapter for more in-depth description of exceptions.

As in most object-oriented languages, we have visibility specifiers to hide fields / methods / properties.

The basic visibility levels are:

The explanation of private and protected visibility above is not precisely true. The code in the same unit can overcome their limits, and access the private and protected stuff freely. Sometimes this is a nice feature, allows you to implement tightly-connected classes. Use strict private or strict protected to secure your classes more tightly. See the Private and strict private.

By default, if you don’t specify the visibility, then the visibility of declared stuff is public. The exception is for classes compiled with {$M+}, or descendants of classes compiled with {$M+}, which includes all descendants of TPersistent, which also includes all descendants of TComponent (since TComponent descends from TPersistent). For them, the default visibility specifier is published, which is like public, but in addition the streaming system knows to handle this.

Not every field and property type is allowed in the published section (not every type can be streamed, and only classes can be streamed from simple fields). Just use public if you don’t care about streaming but want something available to all users.

If you don’t declare the ancestor type, every class inherits from TObject.

The special keyword Self can be used within the class implementation to explicitly refer to your own instance. It is equivalent to this from C++, Java and similar languages.

Within a method implementation, if you call another method, then by default you call the method of your own class. In the example code below, TMyClass2.MyOtherMethod calls MyMethod, which ends up calling TMyClass2.MyMethod.

If the method is not defined in a given class, then it calls the method of an ancestor class. In effect, when you call MyMethod on an instance of TMyClass2, then

You can test it by commenting out the TMyClass2.MyMethod definition in the example above. In effect, TMyClass1.MyMethod will be called by TMyClass2.MyOtherMethod.

Sometimes, you don’t want to call the method of your own class. You want to call the method of an ancestor (or ancestor’s ancestor, and so on). To do this, add the keyword inherited before the call to MyMethod, like this:

This way you force the compiler to start searching from an ancestor class. In our example, it means that compiler is searching for MyMethod inside TMyClass1.MyMethod, then TObject.MyMethod, and then gives up. It does not even consider using the implementation of TMyClass2.MyMethod.

The inherited call is often used to call the ancestor method of the same name. This way the descendants can enhance the ancestors (keeping the ancestor functionality, instead of replacing the ancestor functionality). Like in the example below.

Since using inherited to call a method with the same name, with the same arguments, is a very often case, there is a special shortcut for it: you can just write inherited; (inherited keyword followed immediately by a semicolon, instead of a method name). This means "call an inherited method with the same name, passing it the same arguments as the current method".

Note 1: The inherited; is really just a shortcut for calling the ancestor’s method with the same variables passed in. If you have modified your own parameter (which is possible, if the parameter is not const), then the ancestor’s method can receive different input values from your descendant. Consider this:

Note 2: You usually want to make the MyMethod virtual when many classes (along the "inheritance chain") define it. More about the virtual methods in the section below. But the inherited keyword works regardless if the method is virtual or not. The inherited always means that the compiler starts searching for the method in an ancestor, and it makes sense for both virtual and not virtual methods.

By default, the methods are not virtual. This is similar to C++, and unlike Java.

When a method is not virtual, the compiler determines which method to call based on the currently declared class type, not based on the actually created class type. The difference seems subtle, but it’s important when your variable is declared to have a class like TFruit, but it may be in fact a descendant class like TApple.

The idea of the object-oriented programming is that the descendant class is always as good as the ancestor, so the compiler allows to use a descendant class always when the ancestor is expected. When your method is not virtual, this can have undesired consequences. Consider the example below:

This example will print

In effect, the call Fruit.Eat called the TFruit.Eat implementation, and nothing calls the TApple.Eat implementation.

If you think about how the compiler works, this is natural: when you wrote the Fruit.Eat, the Fruit variable was declared to hold a class TFruit. So the compiler was searching for the method called Eat within the TFruit class. If the TFruit class would not contain such method, the compiler would search within an ancestor (TObject in this case). But the compiler cannot search within descendants (like TApple), as it doesn’t know whether the actual class of Fruit is TApple, TFruit, or some other TFruit descendant (like a TOrange, not shown in the example above).

In other words, the method to be called is determined at compile-time.

Using the virtual methods changes this behavior. If the Eat method would be virtual (an example of it is shown below), then the actual implementation to be called is determined at runtime. If the Fruit variable will hold an instance of the class TApple (even if it’s declared as TFruit), then the Eat method will be searched within the TApple class first.

In Object Pascal, to define a method as virtual, you need to

This example will print

Internally, virtual methods work by having so-called virtual method table associated with each class. This table is a list of pointers to the implementations of virtual methods for this class. When calling the Eat method, the compiler looks into a virtual method table associated with the actual class of Fruit, and uses a pointer to the Eat implementation stored there.

If you don’t use the override keyword, the compiler will warn you that you’re hiding (obscuring) the virtual method of an ancestor with a non-virtual definition. If you’re sure that this is what you want, you can add a reintroduce keyword. But in most cases, you will rather want to keep the method virtual, and add the override keyword, thus making sure that it’s always invoked correctly.

The class instances have to be manually freed, otherwise you get memory leaks. I advise using FPC -gl -gh options to detect memory leaks (see https://castle-engine.io/manual_optimization.php#section_memory ).

Note that this doesn’t concern raised exceptions. Although you do create a class when raising an exception (and it’s a perfectly normal class, and you can create your own classes for this purpose too). But this class instance is freed automatically.

To free the class instance, it’s best to call FreeAndNil(A) from SysUtils unit on your class instance. It checks whether A is nil, if not — calls its destructor, and sets A to nil. So calling it many times in a row is not an error.

It is more-or-less a shortcut for

Actually, that’s an oversimplification, as FreeAndNil does a useful trick and sets the variable A to nil before calling the destructor on a suitable reference. This helps to prevent a certain class of bugs — the idea is that the "outside" code should never access a half-destructed instance of the class.

Often you will also see people using the A.Free method, which is like doing

This frees the A, unless it’s nil.

Note that in normal circumstances, you should never call a method on an instance which may be nil. So the call A.Free may look suspicious at the first sight, if A can be nil. However, the Free method is an exception to this rule. It does something dirty in the implementation — namely, checks whether Self <> nil. This dirty trick works only in non-virtual methods (that don’t call any virtual methods and don’t access any fields).

I advise using FreeAndNil(A) always, without exceptions, and never to call directly the Free method or Destroy destructor. The Castle Game Engine does it like that. It helps to keep a nice assertion that all references are either nil, or point to valid instances.

In many situations, the need to free the instance is not much problem. You just write a destructor, that matches a constructor, and deallocates everything that was allocated in the constructor (or, more completely, in the whole lifetime of the class). Be careful to only free each thing once. Usually it’s a good idea to set the freed reference to nil, usually it’s most comfortable to do it by calling the FreeAndNil(A).

So, like this:

To avoid the need to explicitly free the instance, one can also use the TComponent feature of "ownership". An object that is owned will be automatically freed by the owner. The mechanism is smart and it will never free an already freed instance (so things will also work correctly if you manually free the owned object earlier). We can change the previous example to this:

Note that we need to override a virtual TComponent constructor here. So we cannot change the constructor parameters. (Actually, you can — declare a new constructor with reintroduce. But be careful, as some functionality, e.g. streaming, will still use the virtual constructor, so make sure it works right in either case.)

Note that you can always use nil value for the owner. This way the "ownership" mechanism will not be used for this component. It makes sense if you need to use the TComponent descendant, but you want to always manually free it. To do this, you would create a component descendant like this: ManualGun := TGun.Create(nil);.

Another mechanism for automatic freeing is the OwnsObjects functionality (by default already true!) of list-classes like TFPGObjectList or TObjectList. So we can also write:

Beware that the list classes "ownership" mechanism is simple, and you will get an error if you free the instance using some other means, while it’s also contained within a list. Use the Extract method to remove something from a list without freeing it, thus taking the responsibility to free it yourself.

In the Castle Game Engine: The descendants of TX3DNode have automatic memory management when inserted as children of another TX3DNode. The root X3D node, TX3DRootNode, is in turn usually owned by TCastleSceneCore. Some other things also have a simple ownership mechanism — look for parameters and properties called OwnsXxx.

As you saw in the examples above, when the class is destroyed, its destructor called Destroy is called.

In theory, you could have multiple destructors, but in practice it’s almost never a good idea. It’s much easier to have only one destructor called Destroy, which is in turn called by the Free method, which is in turn called by the FreeAndNil procedure.

The Destroy destructor in the TObject is defined as a virtual method, so you should always mark it with the override keyword in all your classes (since all classes descend from TObject). This makes the Free method work correctly. Recall how the virtual methods work from the Virtual methods, override and reintroduce.

If you copy a reference to the instance, such that you have two references to the same memory, and then one of them is freed — the other one becomes a "dangling pointer". It should not be accessed, as it points to a memory that is no longer allocated. Accessing it may result in a runtime error, or garbage being returned (as the memory may be reused for other stuff in your program).

Using the FreeAndNil to free the instance doesn’t help here. FreeAndNil sets to nil only the reference it got — there’s no way for it to set all other references automatically. Consider this code:

There are various solutions to it:

In Castle Game Engine we encourage to use TFreeNotificationObserver from CastleClassUtils unit instead of directly calling FreeNotification, RemoveFreeNotification and overriding Notification.

In general using TFreeNotificationObserver looks a bit simpler than using FreeNotification mechanism directly (though I admit it is a matter of taste). But in particular when the same class instance must be observed because of multiple reasons then TFreeNotificationObserver is much simpler to use (directly using FreeNotification in this case can get complicated, as you have to watch to not unregister the notification too soon).

This is the example code using TFreeNotificationObserver, to achieve the same effect as example in the previous section:

See https://castle-engine.io/custom_components .

Exceptions allow to interrupt the normal execution of the code.

An "exception" is, in general, any class instance.

If you want to raise your own exception, declare it and call raise …​ when appropriate:

Note that the expression following the raise should be a valid class instance to raise. You will almost always create the exception instance here.

You can also use the CreateFmt constructor, which is a comfortable shortcut to Create(Format(MessageFormat, MessageArguments)). This is a common way to provide more information to the exception message. We can improve the previous example like this:

You can catch an exception like this:

To improve the above example, we can declare the name for the exception instance (we will use E in the example). This way we can print the exception message:

One could also test for multiple exception classes:

You can also react to any exception raised, if you don’t use any on expression:

In general you should only catch exceptions of a specific class, that signal a particular problem that you know what to do with. Be careful with catching exceptions of a general type (like catching any Exception or any TObject), as you may easily catch too much, and later cause troubles when debugging other problems. As in all programming languages with exceptions, the good rule to follow is to never capture an exception that you do not know how to handle. In particular, do not capture an exception just as a simple workaround of the problem, without investigating first why the exception occurs.

Another way to capture all exceptions is to use:

Although usually it is enough to capture Exception:

You can "re-raise" the exception in the except …​ end block, if you decide so. You can just do raise E if the exception instance is E, you can also just use parameter-less raise. For example:

Note that, although the exception is an instance of an object, you should never manually free it after raising. The compiler will generate proper code that makes sure to free the exception object once it’s handled.

Often you use try .. finally .. end construction to free an instance of some object, regardless if an exception occurred when using this object. The way to write it looks like this:

This works reliably always, and does not cause memory leaks, even if MyInstance.DoSomething or MyInstance.DoSomethingElse raise an exception.

Note that this takes into account that local variables, like MyInstance above, have undefined values (may contain random "memory garbage") before the first assignment. That is, writing something like this would not be valid:

The above example is not valid: if an exception occurs within TMyClass.Create (a constructor may also raise an exception), or within the CallSomeOtherProcedure, then the MyInstance variable is not initialized. Calling FreeAndNil(MyInstance) will try to call destructor of MyInstance, which will most likely crash with Access Violation (Segmentation Fault). In effect, one exception causes another exception, which will make the error report not very useful: you will not see the message of the original exception.

Sometimes it is justified to fix the above code by first initializing all local variables to nil (on which calling FreeAndNil is safe, and will not do anything). This makes sense if you free a lot of class instances. So the two code examples below work equally well:

It is probably more readable in the form below:

Modern programs should use TStream class and its many descendants to do input / output. It has many useful descendants, like TFileStream, TMemoryStream, TStringStream.

In the Castle Game Engine: You should use the Download function to create a stream that obtains data from any URL. Regular files, HTTP and HTTPS resources, Android assets and more are supported this way. Moreover, to open the resource inside your game data (in the data subdirectory) use the special castle-data:/xxx URL. Examples:

To read text files, we advise using the TTextReader class. It provides a line-oriented API, and wraps a TStream inside. The TTextReader constructor can take a ready URL, or you can pass there your custom TStream source.

The language and run-time library offer various flexible containers. There are a number of non-generic classes (like TList and TObjectList from the Contnrs unit), there are also dynamic arrays (array of TMyType). But to get the most flexibility and type-safety, I advise using generic containers for most of your needs.

The generic containers give you a lot of helpful methods to add, remove, iterate, search, sort…​ The compiler also knows (and checks) that the container holds only items of the appropriate type.

There are three libraries providing generics containers in FPC now:

We advise using the Generics.Collections unit. The generic containers it implements are

In the Castle Game Engine: We use the Generics.Collections intensively throughout the engine, and advise you to use Generics.Collections in your applications too!

Most important classes from the Generics.Collections unit are:

Here’s how to you use a simple generic TObjectList:

Note that some operations require comparing two items, like sorting and searching (e.g. by Sort and IndexOf methods). The Generics.Collections containers use for this a comparer. The default comparer is reasonable for all types, even for records (in which case it compares memory contents, which is a reasonable default at least for searching using IndexOf).

When sorting the list you can provide a custom comparer as a parameter. The comparer is a class implementing the IComparer interface. In practice, you usually define the appropriate callback, and use TComparer<T>.Construct method to wrap this callback into an IComparer instance. An example of doing this is below:

The TDictionary class implements a dictionary, also known as a map (key → value), also known as an associative array. Its API is a bit similar to the C# TDictionary class. It has useful iterators for keys, values, and pairs of key→value.

An example code using a dictionary:

The TObjectDictionary can additionally own the dictionary keys and/or values, which means that they will be automatically freed. Be careful to only own keys and/or values if they are object instances. If you set to "owned" some other type, like an Integer (for example, if your keys are Integer, and you include doOwnsKeys), you will get a nasty crash when the code executes.

An example code using the TObjectDictionary is below. Compile this example with memory leak detection, like fpc -gl -gh generics_object_dictionary.lpr, to see that everything is freed when program exits.

If you prefer using the FGL unit instead of Generics.Collections, the most important classes from the FGL unit are:

In FGL unit, the TFPGList can be only used for types for which the equality operator (=) is defined. For TFPGMap the "greater than" (>) and "less than" (<) operators must be defined for the key type. If you want to use these lists with types that don’t have built-in comparison operators (e.g. with records), you have to overload their operators as shown in the Operator overloading.

In the Castle Game Engine we include a unit CastleGenericLists that adds TGenericStructList and TGenericStructMap classes. They are similar to TFPGList and TFPGMap, but they do not require a definition of the comparison operators for the appropriate type (instead, they compare memory contents, which is often appropriate for records or method pointers). But the CastleGenericLists unit is deprecated since the engine version 6.3, as we advise using Generics.Collections instead.

If you want to know more about the generics, see Generics.

Copying the class instances by a simple assignment operator copies the reference.

To copy the class instance contents, the standard approach is to derive your class from TPersistent, and override its Assign method. Once it’s implemented properly in TMyObject, you use it like this:

To make it work, you need to implement the Assign method to actually copy the fields you want. You should carefully implement the Assign method, to copy from a class that may be a descendant of the current class.

Sometimes it’s more comfortable to alternatively override the AssignTo method in the source class, instead of overriding the Assign method in the destination class.

Be careful when you call inherited in the overridden Assign implementation. There are two situations:

To understand the reason behind the above rule (when you should call, and when you should not call inherited from the Assign implementation), and how it relates to the AssignTo method, let’s look at the TPersistent.Assign and TPersistent.AssignTo implementations:

The conclusions you can get from the above are:

When you have a class like TApple, your TApple.Assign implementation usually deals with copying fields that are specific to the TApple class (not to the TApple ancestor, like TFruit). So, the TApple.Assign implementation usually checks whether Source is TApple at the beginning, before copying apple-related fields. Then, it calls inherited to allow TFruit to handle the rest of the fields.

Assuming that you implemented TFruit.Assign and TApple.Assign following the standard pattern (as shown in the example above), the effect is like this:

Inside a larger routine (function, procedure, method) you can define a helper routine.

The local routine can freely access (read and write) all the parameters of a parent, and all the local variables of the parent that were declared above it. This is very powerful. It often allows to split long routines into a couple of small ones without much effort (as you don’t have to pass around all the necessary information in the parameters). Be careful to not overuse this feature — if many nested functions use (and even change) the same variable of the parent, the code may get hard to follow.

These two examples are equivalent:

Another version, where we let the local routine Square to access I directly:

Local routines can go to any depth — which means that you can define a local routine within another local routine. So you can go wild (but please don’t go too wild, or the code will get unreadable:).

They allow to call a function indirectly, through to a variable. The variable can be assigned at runtime to point to any function with matching parameter types and return types.

The callback can be:

A powerful feature of any modern language. The definition of something (typically, of a class) can be parameterized with another type. The most typical example is when you need to create a container (a list, dictionary, tree, graph…​): you can define a list of type T, and then specialize it to instantly get a list of integers, a list of strings, a list of TMyRecord, and so on.

The generics in Pascal work much like generics in C++. Which means that they are "expanded" at the specialization time, a little like macros (but much safer than macros; for example, the identifiers are resolved at the time of generic definition, not at specialization, so you cannot "inject" any unexpected behavior when specializing the generic). In effect this means that they are very fast (can be optimized for each particular type) and work with types of any size. You can use a primitive type (integer, float) as well as a record, as well as a class when specializing a generic.

Generics are not limited to classes, you can have generic functions and procedures as well:

See also the Containers (lists, dictionaries) using generics about important standard classes using generics.

Methods (and global functions and procedures) with the same name are allowed, as long as they have different parameters. At compile time, the compiler detects which one you want to use, knowing the parameters you pass.

By default, the overloading uses the FPC approach, which means that all the methods in given namespace (a class or a unit) are equal, and hide the other methods in namespaces with less priority. For example, if you define a class with methods Foo(Integer) and Foo(string), and it descends from a class with method Foo(Float), then the users of your new class will not be able to access the method Foo(Float) easily (they still can --- if they typecast the class to its ancestor type). To overcome this, use the overload keyword.

You can use simple preprocessor directives for

Note that macros with parameters are not allowed. In general, you should avoid using the preprocessor stuff…​ unless it’s really justified. The preprocessing happens before parsing, which means that you can "break" the normal syntax of the Pascal language. This is a powerful, but also somewhat dirty, feature.

Include files have commonly the .inc extension, and are used for two purposes:

Record is just a container for other variables. It’s like a much, much simplified class: there is no inheritance or virtual methods. It is like a structure in C-like languages.

If you use the {$modeswitch advancedrecords} directive, records can have methods and visibility specifiers. In general, language features that are available for classes, and do not break the simple predictable memory layout of a record, are then possible.

In modern Object Pascal, your first instinct should be to design a class, not a record — because classes are packed with useful features, like constructors and inheritance.

But records are still very useful when you need speed or a predictable memory layout:

In the old days, Turbo Pascal introduced another syntax for class-like functionality, using the object keyword. It’s somewhat of a blend between the concept of a record and a modern class.

It’s discouraged to use the old-style objects in most cases. Modern classes provide much more functionality. And when needed, records (including advanced records) can be used for performance. These concepts are usually a better idea than old-style objects.

You can create a pointer to any other type. The pointer to type TMyRecord is declared as ^TMyRecord, and by convention is called PMyRecord. This is a traditional example of a linked list of integers using records:

Note that the definition is recursive (type PMyRecord is defined using type TMyRecord, while TMyRecord is defined using PMyRecord). It is allowed to define a pointer type to a not-yet-defined type, as long as it will be resolved within the same type block.

You can allocate and free pointers using the New / Dispose methods, or (more low-level, not type-safe) GetMem / FreeMem methods. You dereference the pointer (to access the stuff pointed by) you append the ^ operator (e.g. MyInteger := MyPointerToInteger^). To make the inverse operation, which is to get a pointer of an existing variable, you prefix it with @ operator (e.g. MyPointerToInteger := @MyInteger).

There is also an untyped Pointer type, similar to void* in C-like languages. It is completely unsafe, and can be typecasted to any other pointer type.

Remember that a class instance is also in fact a pointer, although it doesn’t require any ^ or @ operators to use it. A linked list using classes is certainly possible, it would simply be this:

You can override the meaning of many language operators, for example to allow addition and multiplication of your custom types. Like this:

You can override operators on classes too. Since you usually create new instances of your classes inside the operator function, the caller must remember to free the result.

You can override operators on records too. This is usually easier than overloading them for classes, as the caller doesn’t have to deal then with memory management.

For records, it’s advised to use {$modeswitch advancedrecords} and override operators as class operator inside the record. This allows to use generic classes that depend on some operator existence (like TFPGList, that depends on equality operator being available) with such records. Otherwise the "global" definition of an operator (not inside the record) would not be found (because it’s not available at the code that implements the TFPGList), and you could not specialize a list like specialize TFPGList<TMyRecord>.

The private visibility specifier means that the field (or method) is not accessible outside of this class. But it allows an exception: all the code defined in the same unit can break this, and access private fields and methods. A C++ programmer would say that in Pascal all classes within a single unit are friends. This is often useful, and doesn’t break your encapsulation, since it’s limited to a unit.

However, if you create larger units, with many classes (that are not tightly integrated with each other), it’s safer to use strict private. It means that the field (or method) is not accessible outside of this class — period. No exceptions.

In a similar manner, there’s protected visibility (visible to descendants, or friends in the same unit) and strict protected (visible to descendants, period).

You can open a section of constants (const) or types (type) within a class. This way, you can even define a class within a class. The visibility specifiers work as always, in particular the nested class can be private (not visible to the outside world), which is often useful.

Note that to declare a field after a constant or type you will need to open a var block.

These are methods you can call having a class reference (TMyClass), not necessarily a class instance.

Note that they can be virtual — it makes sense, and is sometimes very useful, when combined with Class references.

The class methods can also be limited by the Visibility specifiers, like private or protected. Just like regular methods.

Note that a constructor always acts like a class method when called in a normal fashion (MyInstance := TMyClass.Create(…​);). Although it’s possible to also call a constructor from within the class itself, like a normal method, and then it acts like a normal method. This is a useful feature to "chain" constructors, when one constructor (e.g. overloaded to take an integer parameter) does some job, and then calls another constructor (e.g. parameter-less).

Class reference allows you to choose the class at runtime, for example to call a class method or constructor without knowing the exact class at compile-time. It is a type declared as class of TMyClass.

Class references can be combined with virtual class methods. This gives a similar effect as using classes with virtual methods — the actual method to be executed is determined at runtime.

If you have an instance, and you would like to get a reference to its class (not the declared class, but the final descendant class used at its construction), you can use the ClassType property. The declared type of ClassType is TClass, which stands for class of TObject. Often you can safely typecast it to something more specific, when you know that the instance is something more specific than TObject.

In particular, you can use the ClassType reference to call virtual methods, including virtual constructors. This allows you to create a method like Clone that constructs an instance of the exact run-time class of the current object. You can combine it with Cloning: TPersistent.Assign to have a method that returns a newly-constructed clone of the current instance.

Remember that it only works when the constructor of your class is virtual. For example, it can be used with the standard TComponent descendants, since they all must override TComponent.Create(AOwner: TComponent) virtual constructor.

To understand the static class methods, you have to understand how the normal class methods (described in the previous sections) work. Internally, normal class methods receive a class reference of their class (it is passed through a hidden, implicitly added 1st parameter of the method). This class reference can be even accessed explicitly using the Self keyword inside the class method. Usually, it’s a good thing: this class reference allows you to call virtual class methods (through the virtual method table of the class).

While this is nice, it makes the normal class methods incompatible when assigning to a global procedure pointer. That is, this will not compile:

The above example fails to compile, because the Callback is incompatible with the class method Foo. And it’s incompatible because internally the class method has that special hidden implicit parameter to pass a class reference.

One way to fix the above example is to change the definition of TMyCallback. It will work if it is a method callback, declared as TMyCallback = procedure (A: Integer) of object;. But sometimes, it’s not desirable.

Here comes the static class method. It is, in essence, just a global procedure / function, but its namespace is limited inside the class. It does not have any implicit class reference (and so, it cannot be virtual and it cannot call virtual class methods). On the upside, it is compatible with normal (non-object) callbacks. So this will work:

A class property is a property that can be accessed through a class reference (it does not need a class instance).

It is quite straightforward analogy of a regular property (see Properties). For a class property, you define a getter and / or a setter. They may refer to a class variable or a static class method.

A class variable is, you guessed it, like a regular field but you don’t need a class instance to access it. In effect, it’s just like a global variable, but with the namespace limited to the containing class. It can be declared within the class var section of the class. Alternatively it can be declared by following the normal field definition with the keyword static.

And a static class method is just like a global procedure / function, but with the namespace limited to the containing class. More about static class methods in the section above, see Static class methods.

The method is just a procedure or function inside a class. From the outside of the class, you call it with a special syntax MyInstance.MyMethod(…​). After a while you grow accustomed to thinking that if I want to make action Action on instance X, I write `X.Action(…​)`.

But sometimes, you need to implement something that conceptually is an action on class TMyClass without modifying the TMyClass source code. Sometimes it’s because it’s not your source code, and you don’t want to change it. Sometimes it’s because of the dependencies — adding a method like Render to a class like TMy3DObject seems like a straightforward idea, but maybe the base implementation of class TMy3DObject should be kept independent from the rendering code? It would be better to "enhance" an existing class, to add functionality to it without changing its source code.

Simple way to do it is then to create a global procedure that takes an instance of TMy3DObject as its 1st parameter.

This works perfectly, but the downside is that calling it looks a little ugly. While usually you call actions like X.Action(…​), in this case you have to call them like Render(X, …​). It would be cool to be able to just write X.Render(…​), even when Render is not implemented in the same unit as TMy3DObject.

And this is where you use class helpers. They are just a way to implement procedures / functions that operate on given class, and that are called like methods, but are not in fact normal methods — they were added outside of the TMy3DObject definition.

Destructor name is always Destroy, it is virtual (since you can call it without knowing the exact class at compile-time) and parameter-less.

Constructor name is by convention Create.

You can change this name, although be careful with this — if you define CreateMy, always redefine also the name Create, otherwise the user can still access the constructor Create of the ancestor, bypassing your CreateMy constructor.

In the base TObject it is not virtual, and when creating descendants you’re free to change the parameters. The new constructor will hide the constructor in ancestor (note: don’t put here overload, unless you want to break it).

In the TComponent descendants, you should override its constructor Create(AOwner: TComponent);. For streaming functionality, to create a class without knowing its type at compile time, having virtual constructors is very useful (see Class references above).

What happens if an exception happens during a constructor? The line

does not execute to the end in this case, X cannot be assigned, so who will cleanup after a partially-constructed class?

The solution of Object Pascal is that, in case an exception occurs within a constructor, then the destructor is called. This is a reason why your destructor must be robust, which means it should work in any circumstances, even on a half-created class instance. Usually this is easy if you release everything safely, like by FreeAndNil.

We also have to depend in such cases that the memory of the class is guaranteed to be zeroed right before the constructor code is executed. So we know that at the beginning, all class references are nil, all integers are 0 and so on.

So below works without any memory leaks:

An interface declares an API, much like a class, but it does not define the implementation. A class can implement many interfaces, but it can only have one ancestor class.

You can cast a class to any interface it supports, and then call the methods through that interface. This allows to treat in a uniform fashion the classes that don’t descend from each other, but still share some common functionality. Useful when a simple class inheritance is not enough.

The CORBA interfaces in Object Pascal work pretty much like interfaces in Java (https://docs.oracle.com/javase/tutorial/java/concepts/interface.html) or C# (https://msdn.microsoft.com/en-us/library/ms173156.aspx).

GUIDs are the seemingly random characters ['{ABCD1234-…​}'] that you see placed at every interface definition. Yes, they are just random. Unfortunately, they are necessary.

The GUIDs have no meaning if you don’t plan on integrating with communication technologies like COM nor CORBA. But they are necessary, for implementation reasons. Don’t be fooled by the compiler, that unfortunately allows you to declare interfaces without GUIDs.

Without the (unique) GUIDs, your interfaces will be treated equal by the is operator. In effect, it will return true if your class supports any of your interfaces. The magic function Supports(ObjectInstance, IMyInterface) behaves slightly better here, as it refuses to be compiled for interfaces without a GUID. This is true for both CORBA and COM interfaces, as of FPC 3.0.0.

So, to be on the safe side, you should always declare a GUID for your interface. You can use Lazarus GUID generator (Ctrl + Shift + G shortcut in the editor). Or you can use an online service like https://www.guidgenerator.com/ .

Or you can write your own tool for this, using the CreateGUID and GUIDToString functions in RTL. See the example below:

The COM interfaces bring two additional features:

When using COM interfaces, you need to be aware of their automatic destruction mechanism and relation to COM technology.

In practice, this means that:

The safest approach to using COM interfaces is to

This is an example of such interface use:

As mentioned in the previous section, your class can descend from TComponent (or a similar class like TNonRefCountedInterfacedObject and TNonRefCountedInterfacedPersistent) which disables reference-counting for COM interfaces. This allows you to use COM interfaces, and still free the class instance manually.

You need to be careful in this case to not free the class instance when some interface variable may refer to it. Remember that every typecast Cx as IMyInterface also creates a temporary interface variable, which may be present even until the end of the current procedure. For this reason, the example below uses a UseInterfaces procedure, and it frees the class instances outside of this procedure (when we can be sure that temporary interface variables are out of scope).

To avoid this mess, it’s usually better to use CORBA interfaces, if you don’t want reference-counting with your interfaces.

This section applies to both CORBA and COM interfaces (however, it has some explicit exceptions for CORBA).

To test it all, play around with this example code: