This document discusses Ring documentation for version 1.10 and covers: 1. How to return values from Ring functions using the Ring API return functions. 2. The function prototype for defining new functions for RingVM extensions. 3. An example implementation of the sin() math function using the Ring API.

1. Ring Documentation, Release 1.10
82.9 Return Value
We can return values from our function using the next functions.
RING_API_RETNUMBER(double nValue);
RING_API_RETSTRING(const char *cString);
RING_API_RETSTRING2(const char *cString,int nStringSize);
RING_API_RETLIST(List *pList);
RING_API_RETCPOINTER(void *pValue,const char *cPointerType);
RING_API_RETMANAGEDCPOINTER(void *pValue,const char *cPointerType,
void (* pFreeFunc)(void *,void *))
82.10 Function Prototype
When we define new function to be used for RingVM extension, we use the next prototype
void my_function_name( void *pPointer );
or we can use the RING_FUNC() Macro
RING_FUNC(my_function_name);
82.11 Sin() Function Implementation
The next code represents the sin() function implementation using the Ring API and the sin() C function.
void ring_vm_math_sin ( void *pPointer )
{
if ( RING_API_PARACOUNT != 1 ) {
RING_API_ERROR(RING_API_MISS1PARA);
return ;
}
if ( RING_API_ISNUMBER(1) ) {
RING_API_RETNUMBER(sin(RING_API_GETNUMBER(1)));
} else {
RING_API_ERROR(RING_API_BADPARATYPE);
}
}
82.12 Fopen() and Fclose() Functions Implementation
The next code represents the fopen() function implementation using the Ring API and the fopen() C Function.
The function takes two parameters, the first parameter is the file name as string. The second parameter is the mode as
string.
In the file ring_vmfile.h we have some constants to use as the pointer type like
#define RING_VM_POINTER_FILE "file"
#define RING_VM_POINTER_FILEPOS "filepos"
The function implementation in ring_vmfile.c
82.9. Return Value 918

2. Ring Documentation, Release 1.10
void ring_vm_file_fopen ( void *pPointer )
{
FILE *fp ;
if ( RING_API_PARACOUNT != 2 ) {
RING_API_ERROR(RING_API_MISS2PARA);
return ;
}
if ( RING_API_ISSTRING(1) && RING_API_ISSTRING(2) ) {
fp = fopen(RING_API_GETSTRING(1),RING_API_GETSTRING(2));
RING_API_RETCPOINTER(fp,RING_VM_POINTER_FILE);
} else {
RING_API_ERROR(RING_API_BADPARATYPE);
}
}
The next code represents the fclose() function implementation
void ring_vm_file_fclose ( void *pPointer )
{
FILE *fp ;
if ( RING_API_PARACOUNT != 1 ) {
RING_API_ERROR(RING_API_MISS1PARA);
return ;
}
if ( RING_API_ISPOINTER(1) ) {
fp = (FILE *) RING_API_GETCPOINTER(1,RING_VM_POINTER_FILE) ;
if ( fp != NULL ) {
RING_API_RETNUMBER(fclose(fp));
RING_API_SETNULLPOINTER(1);
}
} else {
RING_API_ERROR(RING_API_BADPARATYPE);
}
}
From fopen() and fclose() implementation we learned
1 - how to return C pointer using RING_API_RETCPOINTER() function
2 - how to check if the parameter is a pointer using the RING_API_ISPOINTER() function
3 - how to get C pointer value using the RING_API_GETCPOINTER() function
4 - how to set the C pointer variable (in RingVM) to NULL using the RING_API_SETNULLPOINTER() function
82.13 Ring API - List Functions
In this section we will learn about the list functions provided by the Ring API to create new lists and manipulate the
list items.
List * ring_list_new ( int nSize ) ;
void ring_list_newitem ( List *pList ) ;
Item * ring_list_getitem ( List *pList,int index ) ;
List * ring_list_delete ( List *pList ) ;
void ring_list_deleteitem ( List *pList,int index ) ;
void ring_list_print ( List *pList ) ;
int ring_list_gettype ( List *pList, int index ) ;
void ring_list_setint ( List *pList, int index ,int number ) ;
82.13. Ring API - List Functions 919

3. Ring Documentation, Release 1.10
void ring_list_addint ( List *pList,int x ) ;
void ring_list_setpointer ( List *pList, int index ,void *pValue ) ;
void ring_list_addpointer ( List *pList,void *pValue ) ;
void ring_list_setfuncpointer ( List *pList, int index ,void (*pFunc)(void *) ) ;
void ring_list_addfuncpointer ( List *pList,void (*pFunc)(void *) ) ;
int ring_list_isfuncpointer ( List *pList, int index ) ;
void ring_list_setdouble ( List *pList, int index ,double number ) ;
void ring_list_adddouble ( List *pList,double x ) ;
void ring_list_setstring ( List *pList, int index ,const char *str ) ;
void ring_list_setstring2 ( List *pList, int index ,const char *str,int nStrSize ) ;
void ring_list_addstring ( List *pList,const char *str ) ;
void ring_list_addstring2 ( List *pList,const char *str,int nStrSize ) ;
List * ring_list_newlist ( List *pList ) ;
List * ring_list_getlist ( List *pList, int index ) ;
void ring_list_setlist ( List *pList, int index ) ;
void ring_list_setactiveitem ( List *pList, Items *pItems, int index ) ;
void ring_list_copy ( List *pNewList, List *pList ) ;
int ring_list_isnumber ( List *pList, int index ) ;
int ring_list_isstring ( List *pList, int index ) ;
int ring_list_islist ( List *pList, int index ) ;
int ring_list_ispointer ( List *pList, int index ) ;
void ring_list_deleteallitems ( List *pList ) ;
void ring_list_insertitem ( List *pList,int x ) ;
void ring_list_insertint ( List *pList,int nPos,int x ) ;
void ring_list_insertdouble ( List *pList,int nPos,double x ) ;
void ring_list_insertpointer ( List *pList,int nPos,void *pValue ) ;
void ring_list_insertstring ( List *pList,int nPos,const char *str ) ;
void ring_list_insertstring2 ( List *pList,int nPos,const char *str,int nStrSize ) ;
void ring_list_insertfuncpointer ( List *pList,int nPos,void (*pFunc)(void *) ) ;
List * ring_list_insertlist ( List *pList,int nPos ) ;
int ring_list_isiteminsidelist ( List *pList,Item *pItem ) ;
int ring_list_findstring ( List *pList,const char *str,int nColumn ) ;
int ring_list_finddouble ( List *pList,double nNum1,int nColumn ) ;
void ring_list_sortnum ( List *pList,int left,int right,int nColumn ) ;
void ring_list_sortstr ( List *pList,int left,int right,int nColumn ) ;
int ring_list_binarysearchnum ( List *pList,double nNum1,int nColumn ) ;
int ring_list_binarysearchstr ( List *pList,const char *cFind,int nColumn ) ;
void ring_list_swap ( List *pList,int x,int y ) ;
double ring_list_getdoublecolumn ( List *pList,int nIndex,int nColumn ) ;
char * ring_list_getstringcolumn ( List *pList,int nIndex,int nColumn ) ;
void ring_list_genarray ( List *pList ) ;
void ring_list_deletearray ( List *pList ) ;
void ring_list_genhashtable ( List *pList ) ;
void ring_list_genhashtable2 ( List *pList ) ;
void ring_list_refcopy ( List *pNewList, List *pList ) ;
void ring_list_clear ( List *pList ) ;
/* Macro */
ring_list_isdouble(pList,index)
ring_list_isint(pList,index)
ring_list_deletelastitem(x)
ring_list_gethashtable(x)
ring_list_getint(pList,index)
ring_list_getpointer(pList,index)
ring_list_getfuncpointer(pList,index)
ring_list_callfuncpointer(pList,index,x)
ring_list_getdouble(pList,index)
ring_list_getstring(pList,index)
ring_list_getstringobject(pList,index)
82.13. Ring API - List Functions 920

4. Ring Documentation, Release 1.10
ring_list_getstringsize(pList,index)
ring_list_getsize(x) (x->nSize)
82.14 Ring API - String Functions
In this section we will learn about the string functions provided by the Ring API to create new string and manipulate
the string content.
String * ring_string_new ( const char *str ) ;
String * ring_string_new2 ( const char *str,int nStrSize ) ;
String * ring_string_delete ( String *pString ) ;
int ring_string_size ( String *pString ) ;
void ring_string_set ( String *pString,const char *str ) ;
void ring_string_set2 ( String *pString,const char *str,int nStrSize ) ;
void ring_string_add ( String *pString,const char *str ) ;
void ring_string_add2 ( String *pString,const char *str,int nStrSize ) ;
void ring_string_print ( String *pString ) ;
void ring_string_setfromint ( String *pString,int x ) ;
char * ring_string_lower ( char *cStr ) ;
char * ring_string_upper ( char *cStr ) ;
char * ring_string_lower2 ( char *cStr,int nStrSize ) ;
char * ring_string_upper2 ( char *cStr,int nStrSize ) ;
char * ring_string_find ( char *cStr1,char *cStr2 ) ;
char * ring_string_find2 ( char *cStr1,int nStrSize1,char *cStr2,int nStrSize2 ) ;
/* Macro */
ring_string_tolower(x)
ring_string_toupper(x)
ring_string_get(x)
82.15 MySQL_Columns() Function Implementation
The next code presents the MySQL_Columns() function implementation.
This function returns table columns information.
void ring_vm_mysql_columns ( void *pPointer )
{
MYSQL *con ;
MYSQL_RES *result ;
int nColumns,x ;
MYSQL_ROW row ;
MYSQL_FIELD *field ;
List *pList, *pList2 ;
if ( RING_API_PARACOUNT != 1 ) {
RING_API_ERROR(RING_API_MISS1PARA);
return ;
}
if ( RING_API_ISPOINTER(1) ) {
con = (MYSQL *) RING_API_GETCPOINTER(1,RING_VM_POINTER_MYSQL) ;
if ( con == NULL ) {
return ;
}
result = mysql_store_result(con);
if ( result == NULL ) {
82.14. Ring API - String Functions 921

5. Ring Documentation, Release 1.10
RING_API_RETNUMBER(0);
return ;
}
pList = RING_API_NEWLIST ;
nColumns = mysql_num_fields(result);
if ( row = mysql_fetch_row(result) ) {
while ( field = mysql_fetch_field(result) ) {
pList2 = ring_list_newlist(pList);
ring_list_addstring(pList2,field->name);
ring_list_adddouble(pList2,field->length);
ring_list_adddouble(pList2,field->type);
ring_list_adddouble(pList2,field->flags);
}
}
mysql_free_result(result);
RING_API_RETLIST(pList);
} else {
RING_API_ERROR(RING_API_BADPARATYPE);
}
}
Lists are of type List, in the previoud function we declared two pointers of type List using List *pList, *pList2;
Note: The function uses RING_API_NEWLIST to create new list instead of ring_list_new() to create the list in
Temp. Memory related to the function scope. This way we can return the list from the function. Also we don’t delete
the list, if it’s stored in a variable by Ring Code it will be saved, if not it will be automatically deleted by RingVM.
The list can contains sub lists, we used the function ring_list_newlist() to create a sublist.
The function ring_list_addstring() is used to add string items to the list/sublist.
The function ring_list_adddouble() is used to add numeric items to the list/sublist.
Note: All numeric items in lists returned from RingVM extension functions must be of type double and added to the
list using ring_list_adddouble() function.
We return the list from the extension function using the RING_API_RETLIST() function.
82.16 Dynamic/Shared Libraries (DLL/So/Dylib) and LoadLib() func-
tion
Instead of rebuilding the RingVM after writing new functions using C/C++ and the Ring API, we can create a
DLL/So/Dylib file and dynamically use the functions provided by this file in the runtime using the LoadLib() function.
Dynamic library example in C
#include "ring.h"
RING_DLL __declspec(dllexport)
RING_FUNC(ring_ringlib_dlfunc)
{
printf("Message from dlfunc");
}
82.16. Dynamic/Shared Libraries (DLL/So/Dylib) and LoadLib() function 922

6. Ring Documentation, Release 1.10
RING_DLL void ringlib_init(RingState *pRingState)
{
ring_vm_funcregister("dlfunc",ring_ringlib_dlfunc);
}
the idea is to create the ringlib_init() function, this function will be called by the RingVM when we use the generated
DLL file though the LoadLib() function.
Inside the ringlib_init() function we can register the module function or call a function that do the registration process
for all of the module functions.
The next Ring code demonstrates how to use the DLL library during the runtime.
See "Dynamic DLL" + NL
LoadLib("ringlib.dll")
dlfunc()
Output:
Dynamic DLL
Message from dlfunc
82.17 Using RING_API_RETMANAGEDCPOINTER()
Using RING_API_RETMANAGEDCPOINTER() the Ring extensions written in C/C++ languages can return a man-
aged pointer to Ring. This pointer can be controlled by the Ring VM using reference counting.
This is important to avoid the need to write code that free the unmanaged resources like QPixMap objects in RingQt.
Also the Code Generator for extensions is updated to automatically use RING_API_RETMANAGEDCPOINTER()
based on need.
Syntax:
RING_API_RETMANAGEDCPOINTER(void *pValue,const char *cPointerType,
void (* pFreeFunc)(void *,void *))
Example:
The next example from ring_qt.cpp - QPixMap Class - Scaled() Method.
RING_FUNC(ring_QPixmap_scaled)
{
QPixmap *pObject ;
if ( RING_API_PARACOUNT != 5 ) {
RING_API_ERROR(RING_API_BADPARACOUNT);
return ;
}
RING_API_IGNORECPOINTERTYPE ;
if ( ! RING_API_ISPOINTER(1) ) {
RING_API_ERROR(RING_API_BADPARATYPE);
return ;
}
pObject = (QPixmap *) RING_API_GETCPOINTER(1,"QPixmap");
if ( ! RING_API_ISNUMBER(2) ) {
RING_API_ERROR(RING_API_BADPARATYPE);
return ;
}
if ( ! RING_API_ISNUMBER(3) ) {
82.17. Using RING_API_RETMANAGEDCPOINTER() 923

7. Ring Documentation, Release 1.10
RING_API_ERROR(RING_API_BADPARATYPE);
return ;
}
if ( ! RING_API_ISNUMBER(4) ) {
RING_API_ERROR(RING_API_BADPARATYPE);
return ;
}
if ( ! RING_API_ISNUMBER(5) ) {
RING_API_ERROR(RING_API_BADPARATYPE);
return ;
}
{
QPixmap *pValue ;
pValue = new QPixmap() ;
*pValue = pObject->scaled( (int ) RING_API_GETNUMBER(2),
(int ) RING_API_GETNUMBER(3),
(Qt::AspectRatioMode ) (int) RING_API_GETNUMBER(4),
(Qt::TransformationMode ) (int) RING_API_GETNUMBER(5));
RING_API_RETMANAGEDCPOINTER(pValue,"QPixmap",ring_QPixmap_freefunc);
}
}
The function that will free the memory takes two parameters (Ring State and the allocated Memory Pointer)
Example:
void ring_QPixmap_freefunc(void *pState,void *pPointer)
{
QPixmap *pObject ;
pObject = (QPixmap *) pPointer;
delete pObject ;
}
82.17. Using RING_API_RETMANAGEDCPOINTER() 924

8. CHAPTER
EIGHTYTHREE
EMBEDDING RING LANGUAGE IN C/C++ PROGRAMS
We can use the Ring language from C/C++ programs using the next functions
RingState *ring_state_init();
ring_state_runcode(RingState *pState,const char *cCode);
ring_state_delete(RingState *pState);
83.1 Ring State
The idea is to use the ring_state_init() to create new state for the Ring Language then call the ring_state_runcode()
function to execut Ring code using the same state. When we are done, we call the ring_state_delete() to free the
memory.
Example:
#include "ring.h"
#include "stdlib.h"
int main(int argc, char *argv[])
{
RingState *pState = ring_state_init();
printf("welcomen");
ring_state_runcode(pState,"see 'hello world from the ring programming language'+nl");
ring_state_delete(pState);
}
Output:
welcome
hello world from the ring programming language
83.2 Ring State Functions
The Ring API comes with the next functions to create and delete the state. Also we have functions to create new
variables and get variables values.
RingState * ring_state_init ( void ) ;
RingState * ring_state_delete ( RingState *pRingState ) ;
void ring_state_runcode ( RingState *pRingState,const char *cStr ) ;
List * ring_state_findvar ( RingState *pRingState,const char *cStr ) ;
List * ring_state_newvar ( RingState *pRingState,const char *cStr ) ;
void ring_state_main ( int argc, char *argv[] ) ;
925

9. Ring Documentation, Release 1.10
void ring_state_runfile ( RingState *pRingState,const char *cFileName ) ;
void ring_state_runobjectfile ( RingState *pRingState,const char *cFileName ) ;
83.3 Ring State Variables
We can create more than one ring state in the same program and we can create and modify variable values.
To get the variable list we can use the ring_state_findvar() function.
To create new variable we can use the ring_state_newvar() function.
Example:
#include "ring.h"
#include "stdlib.h"
int main(int argc, char *argv[])
{
List *pList;
RingState *pState = ring_state_init();
RingState *pState2 = ring_state_init();
printf("welcomen");
ring_state_runcode(pState,"see 'hello world from the ring programming language'+nl");
printf("Again from C we will call ring coden");
ring_state_runcode(pState,"for x = 1 to 10 see x + nl next");
ring_state_runcode(pState2,"for x = 1 to 5 see x + nl next");
printf("Now we will display the x variable value from ring coden");
ring_state_runcode(pState,"see 'x value : ' + x + nl ");
ring_state_runcode(pState2,"see 'x value : ' + x + nl ");
pList = ring_state_findvar(pState,"x");
printf("Printing Ring variable value from C , %.0fn",
ring_list_getdouble(pList,RING_VAR_VALUE));
printf("now we will set the ring variable value from Cn");
ring_list_setdouble(pList,RING_VAR_VALUE,20);
ring_state_runcode(pState,"see 'x value after update : ' + x + nl ");
pList = ring_state_newvar(pState,"v1");
ring_list_setdouble(pList,RING_VAR_VALUE,10);
pList = ring_state_newvar(pState,"v2");
ring_list_setdouble(pList,RING_VAR_VALUE,20);
ring_state_runcode(pState,"see 'v1 + v2 = ' see v1+v2 see nl");
ring_state_runcode(pState,"see 'end of test' + nl");
ring_state_delete(pState);
83.3. Ring State Variables 926

10. Ring Documentation, Release 1.10
ring_state_delete(pState2);
}
Output:
welcome
hello world from the ring programming language
Again from C we will call ring code
1
2
3
4
5
6
7
8
9
10
1
2
3
4
5
Now we will display the x variable value from ring code
x value : 11
x value : 6
Printing Ring variable value from C , 11
now we will set the ring variable value from C
x value after update : 20
v1 + v2 = 30
end of test
83.3. Ring State Variables 927