Procedures and Event Handlers
|Top Previous Next|
Procedures: subs and functions
Tibbo BASIC offers two kinds of procedures: subs, which are procedures that do not return a value (directly), and functions, which are procedures that do return a value.
Both subs and functions can have arguments.
The parallel structures in Tibbo C are a void function and a non-void function.
You must always specify the return type for the function. We do not allow omitting this.
Notice how the BASIC function returns the value: a function named sum_total will have a local automatically created variable with the same name.
Set this variable to the desired return value.
Procedures must be defined or declared before use
In Tibbo BASIC/C procedures must be defined or declared before they are used.
Procedure definition is its body. Place the body above the first call to this procedure, and there is no need for a declaration:
If a procedure is called first and defined later, place a declaration before the first call:
As each source code (and HTML file) is compiled separately, it is necessary to declare procedures defined in other files before they can be called:
Such declarations are usually placed in header files — .TPH for Tibbo BASIC and .TH for Tibbo C.
Header files must be included into your source code file, it's not enough to simply have them in the project tree:
Event handlers are subs in Tibbo BASIC and void functions in Tibbo C.
These require no declaration because they are already declared in platform files.
Whenever the VM gets to handling a certain event, it calls the corresponding event handler for this event, provided such handler exists in your code.
How do you tell if a procedure is an event handler or not? Names of event handlers are highlighted in green.
Additionally, all event handler names start with on_, which means on x happening, do....
The list of available events can be found in the Project Browser pane: View > Project-Browser -> Events.
Inactive events (those with no event handlers) are grayed. Double-click on an inactive event to add its event handler to the bottom of the current file.
Double-click on an active event to "teleport" to this event handler's body.
Events are actually a part of platform objects, the subject of the Objects and Syscalls section.
Direct argument passing
In Tibbo BASIC procedure arguments can be passed by value (ByVal) or by reference (ByRef). ByVal is the default mode, so you don't have to specify it.
ByVal argument passes a copy of the value. If the procedure called modifies this value then only that copy is modified and the original instance stays the same.
The equivalent of this in the C world is passing an argument and not a pointer to this argument.
In Tibbo BASIC and C even "bulky" items can be passed directly.
For Tibbo BASIC such bulky items are string variables and types (structures). For Tibbo C these are string variables, arrays, structures, and unions.
Have you noticed? Arrays are not listed for BASIC! In Tibbo BASIC it's not possible to pass an array to a sub/function or return an array from a function.
Here is an example of a function that increments each member of an array and then returns the array back.
Since arrays cannot be passed to/from BASIC procedures, the BASIC code example below wraps an array into a type.
Notice a very interesting syntax that is used to specify that the C functions returns an array.
Indirect argument passing
In Tibbo BASIC, a ByRef argument passes a reference to the value. If the procedure called modifies this argument then the original instance gets modified.
This is roughly equivalent to using a pointer in C, except the pointer itself is not available to the BASIC code and can't be modified by it.
ByRef argument passing in BASIC and pointers in C are recommended for bulky types. This saves memory and improves the performance.
ByRef/pointers can also be used to indirectly return a value from a procedure (void function).
Here is the previous array increment example, now rewritten to use a ByRef argument and a pointer. It is much more efficient as no unnecessary copying takes place.
Tibbo BASIC and C will never automatically switch to using the ByRef (pointer) method instead of passing the value itself.
Some languages practice automatic switching whenever there is a bulky item to pass.
For example, there are systems that won't pass a structure directly and won't tell you about the substitution that took place.
We consider this to be extremely misleading. In Tibbo BASIC (and C) "what you define is what you get".
No recursion, reentrant code, or function pointers
Tibbo BASIC and Tibbo C do not allow recursion. Meaning: procedures cannot call themselves (even indirectly).
It is also not possible to create re-entrant functions.
Additionally, pointers to functions are not allowed in Tibbo C.
All of this has to do to how the memory is allocated for procedures.