Ring Documentation, Release 1.

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).

55.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")

see ptrcmp(fp,fp2) + nl
see ptrcmp(fp,fp3) + nl

fclose(fp)
fclose(fp3)

Output:
1
0

55.8 ringvm_cfunctionslist() function

The Function return a list of functions written in C.

Syntax:

55.7. ptrcmp() function 540

 Ring Documentation, Release 1.2

RingVM_CFunctionsList() ---> List

Example:
See RingVM_CFunctionsList()

55.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

55.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

55.9. ringvm_functionslist() function 541

 Ring Documentation, Release 1.2

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

55.11 ringvm_packageslist() function

The Function return a list of Packages.

Each List Member is a list contains the next items
Package Name
Classes List
Syntax:
RingVM_PackagesList() ---> List

Example:
see ringvm_packageslist()

package package1
class class1

package package2
class class1

package package3
class class1

Output:

55.11. ringvm_packageslist() function 542

 Ring Documentation, Release 1.2

package1
class1
11

0
00FEF838
package2
class1
17

0
00FEF978
package3
class1
23

0
00FEFF68

55.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:
RingVM_MemoryList() ---> List

Example:
x = 10
test()
func test
y = 20
see ringvm_memorylist()

Output:
true
2
1
0
0
false
2
0
0

55.12. ringvm_memorylist() function 543

 Ring Documentation, Release 1.2

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
0
stdout
3
50512DD8
file
0
0
0
stderr
3
50512DF8
file
0
0
0
this
4
00000000
0
0

55.12. ringvm_memorylist() function 544

 Ring Documentation, Release 1.2

sysargv
3
B:\ring\bin/ring
B:/ring/tests/scripts/memorylist.ring
0
0
x
2
10
0
0
y
2
20
0
0

55.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
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:

55.13. ringvm_calllist() function 545

 Ring Documentation, Release 1.2

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

55.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:\ring\bin\stdlib.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
stdconversion.ring
stdodbc.ring
stdmysql.ring
stdsecurity.ring
stdinternet.ring
stdhashtable.ring
stdtree.ring

55.14. ringvm_fileslist() function 546

 CHAPTER

FIFTYSIX

EXTENSION USING THE C/C++ LANGUAGES

We can extend the Ring Virtual Machine (RingVM) by adding new functions written in the C programming language
or C++. The RingVM comes with many functions written in C that we can call like any Ring function.
We can extend the language by writing new functions then rebuilding the RingVM again, or we can create shared
library (DLL/So) file to extend the RingVM without the need to rebuild it.
The Ring language source code comes with two files to add new modules to the RingVM, ring_ext.h and ring_ext.c

56.1 ring_ext.h

The file ring_ext.h contains constants that we can change to include/exclude modules during the build process.
#ifndef ringext_h
#define ringext_h
/* Constants */
#define RING_VM_LISTFUNCS 1
#define RING_VM_REFMETA 1
#define RING_VM_MATH 1
#define RING_VM_FILE 1
#define RING_VM_OS 1
#define RING_VM_MYSQL 1
#define RING_VM_ODBC 1
#define RING_VM_OPENSSL 1
#define RING_VM_CURL 1
#define RING_VM_DLL 1
#endif

56.2 ring_ext.c

The file ring_ext.c check constants defined in ring_ext.h before calling the start-up function in each module.
Each module contains a function that register the module functions in the RingVM.
#include "ring.h"

void ring_vm_extension ( RingState *pRingState )

{
/* Reflection and Meta-programming */
#if RING_VM_REFMETA
ring_vm_refmeta_loadfunctions(pRingState);
#endif

547
 Ring Documentation, Release 1.2

/* List Functions */
#if RING_VM_LISTFUNCS
ring_vm_listfuncs_loadfunctions(pRingState);
#endif
/* Math */
#if RING_VM_MATH
ring_vm_math_loadfunctions(pRingState);
#endif
/* File */
#if RING_VM_FILE
ring_vm_file_loadfunctions(pRingState);
#endif
/* OS */
#if RING_VM_OS
ring_vm_os_loadfunctions(pRingState);
#endif
/* MySQL */
#if RING_VM_MYSQL
ring_vm_mysql_loadfunctions(pRingState);
#endif
/* ODBC */
#if RING_VM_ODBC
ring_vm_odbc_loadfunctions(pRingState);
#endif
/* OPENSSL */
#if RING_VM_OPENSSL
ring_vm_openssl_loadfunctions(pRingState);
#endif
/* CURL */
#if RING_VM_CURL
ring_vm_curl_loadfunctions(pRingState);
#endif
/* DLL */
#if RING_VM_DLL
ring_vm_dll_loadfunctions(pRingState);
#endif
}

56.3 Module Organization

Each module starts by include the ring header file (ring.h). This files contains the Ring API that we can use to extend
the RingVM.
Each module comes with a function to register the module functions in the RingVM The registration is done by using
ring_vm_funcregister() function.
The ring_vm_funcregister() function takes two parameters, the first is the function name that will be used by Ring
programs to call the function. The second parameter is the function pointer in the C program.
for example, the ring_vmmath.c module contains the next code to register the module functions
#include "ring.h"

void ring_vm_math_loadfunctions ( RingState *pRingState )

{
ring_vm_funcregister("sin",ring_vm_math_sin);
ring_vm_funcregister("cos",ring_vm_math_cos);

56.3. Module Organization 548

 Ring Documentation, Release 1.2

ring_vm_funcregister("tan",ring_vm_math_tan);
ring_vm_funcregister("asin",ring_vm_math_asin);
ring_vm_funcregister("acos",ring_vm_math_acos);
ring_vm_funcregister("atan",ring_vm_math_atan);
ring_vm_funcregister("atan2",ring_vm_math_atan2);
ring_vm_funcregister("sinh",ring_vm_math_sinh);
ring_vm_funcregister("cosh",ring_vm_math_cosh);
ring_vm_funcregister("tanh",ring_vm_math_tanh);
ring_vm_funcregister("exp",ring_vm_math_exp);
ring_vm_funcregister("log",ring_vm_math_log);
ring_vm_funcregister("log10",ring_vm_math_log10);
ring_vm_funcregister("ceil",ring_vm_math_ceil);
ring_vm_funcregister("floor",ring_vm_math_floor);
ring_vm_funcregister("fabs",ring_vm_math_fabs);
ring_vm_funcregister("pow",ring_vm_math_pow);
ring_vm_funcregister("sqrt",ring_vm_math_sqrt);
ring_vm_funcregister("unsigned",ring_vm_math_unsigned);
ring_vm_funcregister("decimals",ring_vm_math_decimals);
ring_vm_funcregister("murmur3hash",ring_vm_math_murmur3hash);
}

Tip: Remember that the function ring_vm_math_loadfunctions() will be called by the ring_vm_extension() function
(in the ring_ext.c file).

56.4 Function Structure

Each module function may contains the next steps

1 - Check Parameters Count
2 - Check Parameters Type
3 - Get Parameters Values
4 - Execute Code/Call Functions
5 - Return Value
The structure is very similar to any function (Input - Process - Output) But here we will use the Ring API for the steps
1,2,3 and 5.

56.5 Check Parameters Count

We can check the parameters count using the RING_API_PARACOUNT macro.

We can compare RING_API_PARACOUNT with any numeric value using == or != operators.
Example:
if ( RING_API_PARACOUNT != 1 ) {
/* code */
}

Example:

56.4. Function Structure 549