The Ring programming language version 1.7 book - Part 83 of 196

1. CHAPTER
SEVENTY
LOW LEVEL FUNCTIONS
In this chapter we will learn about the low level functions provided by Ring
• callgc()
• varptr()
• space()
• nullpointer()
• object2pointer()
• pointer2object()
• ptrcmp()
• ringvm_cfunctionslist()
• ringvm_functionslist()
• ringvm_classeslist()
• ringvm_packageslist()
• ringvm_memorylist()
• ringvm_calllist()
• ringvm_fileslist()
• ringvm_settrace()
• ringvm_tracedata()
• ringvm_traceevent()
• ringvm_tracefunc()
• ringvm_scopescount()
• ringvm_evalinscope()
• ringvm_passerror()
• ringvm_hideerrorMsg()
• ringvm_callfunc()
• ringvm_see()
• ringvm_give()
792

2. Ring Documentation, Release 1.7
70.1 callgc() function
Use this function to force calling the garbage collector during function execution when you use a loop that create temp.
variables that you don’t free using the assignment operation.
It’s very rare to need this function but it’s useful when you create something like event-loop for your game engine and
start creating lists on the fly when you call functions.
Example
While True
# process events
# call functions using temp. lists like myfunc(["temp list"])
# call the garbage collector
callgc()
End
Tip: In Ring the garbage collector works automatically in the end of function execution or when you use the assign-
ment statement.
70.2 varptr() function
Use the varptr() function when you need to pass a pointer to a C/C++ function.
Syntax:
varptr(cVariableName,cPointerType) —> Low Level Object (C Pointer)
example:
r = 10
z = 20
see r + nl
see varptr("r","int")
see varptr("z","int")
Output:
10
00E3C740
int
2
00E3BEC0
int
2
Note: the low level object is a list contains three items (The Pointer, The Type, The Status)
70.3 space() function
Use the space function to allocate a specific number of bytes in Memory.
70.1. callgc() function 793

3. Ring Documentation, Release 1.7
Syntax:
Space(nBytesCount) ---> String
Example:
mystring = space(200)
See "String Size : " + len(mystring) + nl
See "String : " + mystring + nl
See "String Pointer : "
See varptr("mystring","char *")
Output:
String Size : 200
String :
String Pointer : 00FF8FE8
char *
2
Note: You may need the space() and VarPtr() functions to pass buffers to C functions.
70.4 nullpointer() function
You may need to pass the NULL pointer to a C function that may expect a pointer as parameter and accept NULL
pointers for optional parameters.
Example:
The next example uses the SDL_BlitSurface() function from the LibSDL Library through RingSDL The function
accept SDL_Rect pointers in the second and the last parameter. Also the function accept NULL pointers, so we can
pass them using the NULLPointer() Function.
SDL_BlitSurface(text, nullpointer(), surface, nullpointer())
Note: The previous code doesn’t work alone, you need to learn how to use RingSDL first.
Tip: We can pass NULL as parameter instead of using NULLPointer()
70.5 object2pointer() function
Use this function to get a C pointer for Ring lists and objects
Syntax:
object2pointer(List|Object) --> Low Level Object ( C Pointer )
70.6 pointer2object() function
Use this function to get the Ring list and/or object from the low level object (C Pointer)
70.4. nullpointer() function 794

4. Ring Documentation, Release 1.7
Syntax:
pointer2object(Low Level Object) ---> List|Object
Example:
# Create the list
mylist = 1:5
# Create pointer to the list
x = object2pointer(mylist)
see x
see nl
# Add items to the list
mylist + "welcome"
# print the list items
y = pointer2object(x)
see y
Output:
0069A5D8
OBJECTPOINTER
0
1
2
3
4
5
welcome
Note: In Ring the assignment operator copy lists and objects by value, to copy by reference Just use the ob-
ject2pointer() and pointer2object() functions.
Tip: The object2pointer() and pointer2object() are used in the stdlib - Tree Class implementation to create a reference
for the parent node (object) in the child node (another object).
70.7 ptrcmp() function
We can compare between two pointers (C Objects) using the ptrcmp() function.
Syntax:
ptrcmp(oObject1,oObject2) ---> value = 1 if oObject1 = oObject2
value = 0 if oObject1 != oObject2
Example:
fp = fopen("ptrcmp.ring","r")
fp2 = fp
fp3 = fopen("ptrcmp.ring","r")
70.7. ptrcmp() function 795

5. Ring Documentation, Release 1.7
see ptrcmp(fp,fp2) + nl
see ptrcmp(fp,fp3) + nl
fclose(fp)
fclose(fp3)
Output:
1
0
70.8 ringvm_cfunctionslist() function
The Function return a list of functions written in C.
Syntax:
RingVM_CFunctionsList() ---> List
Example:
See RingVM_CFunctionsList()
70.9 ringvm_functionslist() function
The Function return a list of functions written in Ring.
Each List Member is a list contains the next items
• Function Name
• Program Counter (PC) - Function Position in Byte Code.
• Source Code File Name
• Private Flag (For Private Methods in Classes)
Syntax:
RingVM_FunctionsList() ---> List
Example:
test()
func test
see ringvm_functionslist()
Output:
test
8
B:/ring/tests/scripts/functionslist.ring
0
70.8. ringvm_cfunctionslist() function 796

6. Ring Documentation, Release 1.7
70.10 ringvm_classeslist() function
The Function return a list of Classes.
Each List Member is a list contains the next items
• Class Name
• Program Counter (PC) - Class Position in Byte Code.
• Parent Class Name
• Methods List
• Flag (Is parent class information collected)
• Pointer to the package (or NULL if no package is used)
Syntax:
RingVM_ClassesList() ---> List
Example:
see ringvm_classeslist()
class class1
func f1
class class2 from class1
class class3 from class1
Output:
class1
9
f1
13
B:/ring/tests/scripts/classeslist.ring
0
0
00000000
class2
16
class1
0
00000000
class3
20
class1
0
00000000
70.11 ringvm_packageslist() function
The Function return a list of Packages.
Each List Member is a list contains the next items
• Package Name
70.10. ringvm_classeslist() function 797

7. Ring Documentation, Release 1.7
• Classes List
Syntax:
RingVM_PackagesList() ---> List
Example:
see ringvm_packageslist()
package package1
class class1
package package2
class class1
package package3
class class1
Output:
package1
class1
11
0
00FEF838
package2
class1
17
0
00FEF978
package3
class1
23
0
00FEFF68
70.12 ringvm_memorylist() function
The Function return a list of Memory Scopes and Variables.
Each List Member is a list contains variables in a different scope.
Each Item in the scope list is a list contains the next items
• Variable Name
• Variable Type
• Variable Value
• Pointer Type (List/Item) if the value is a list
• Private Flag (if the variable is an attribute in a Class)
Syntax:
70.12. ringvm_memorylist() function 798

8. Ring Documentation, Release 1.7
RingVM_MemoryList() ---> List
Example:
x = 10
test()
func test
y = 20
see ringvm_memorylist()
Output:
true
2
1
0
0
false
2
0
0
0
nl
1
0
0
null
1
0
0
ring_gettemp_var
4
00000000
0
0
ccatcherror
1
NULL
0
0
ring_settemp_var
4
00000000
0
0
ring_tempflag_var
2
0
0
0
stdin
3
50512DB8
file
0
0
70.12. ringvm_memorylist() function 799

9. Ring Documentation, Release 1.7
0
stdout
3
50512DD8
file
0
0
0
stderr
3
50512DF8
file
0
0
0
this
4
00000000
0
0
sysargv
3
B:ringbin/ring
B:/ring/tests/scripts/memorylist.ring
0
0
x
2
10
0
0
y
2
20
0
0
70.13 ringvm_calllist() function
The Function return a list of the functions call list.
Each List Member is a list contains the next items
• Function Type
• Function Name
• Program Counter (PC)
• Stack Pointer (SP)
• Temp. Memory List
• Method or Function Flag
• Caller PC
• FuncExec Flag
• ListStart Flag
70.13. ringvm_calllist() function 800

10. Ring Documentation, Release 1.7
• Nested Lists Pointer
• State List
Syntax:
RingVM_CallList() ---> List
Example:
hello()
func hello
test()
func test
mylist = ringvm_calllist()
for t in mylist see t[2] + nl next
Output:
function hello() in file B:/ring/tests/scripts/calllist.ring
called from line 1
function test() in file B:/ring/tests/scripts/calllist.ring
called from line 3
ringvm_calllist
70.14 ringvm_fileslist() function
Function return a list of the Ring Files.
Syntax:
RingVM_FilesList() ---> List
Example:
load "stdlib.ring"
see ringvm_fileslist()
Output:
B:/ring/tests/scripts/fileslist.ring
B:ringbinstdlib.ring
eval
stdlib.ring
stdlib.rh
stdclasses.ring
stdfunctions.ring
stdbase.ring
stdstring.ring
stdlist.ring
stdstack.ring
stdqueue.ring
stdmath.ring
stddatetime.ring
stdfile.ring
stdsystem.ring
stddebug.ring
stddatatype.ring
70.14. ringvm_fileslist() function 801