The Ring programming language version 1.5 book - Part 13 of 31

CHAPTER
SIXTYFIVE
COMMAND LINE OPTIONS
The ring language takes source code file (.ring) or the object file (.ringo) as input to execute, also the language provide
other options like
Option Description
-tokens Print a list of tokens in the source code file
-rules Print grammar rules applied on the tokens
-ic Print the intermediate byte code (before execution)
-icfinal Print the final byte code (after execution)
-cgi Print http response header before error messages
-norun Don’t run the program after compiling
-ins Print instruction operation code before execution
-performance Print clock before and after program execution
-go Generate Object File
-w Display Warnings
65.1 Printing Tokens
Example:
Func Main
See "Hello World" + nl
for x = 1 to 10
see x + nl
next
test()
func test
see "welcome" + nl
o1 = new point { x=10 y=20 z=30 }
see o1
class point x y z
Command:
ring test.ring -tokens -norun
Output:
===================================================
Tokens - Generated by the Scanner
===================================================
683

Ring Documentation, Release 1.5
Keyword : FUNC
Identifier : main
EndLine
Keyword : SEE
Literal : Hello World
Operator : +
Identifier : nl
EndLine
Keyword : FOR
Identifier : x
Operator : =
Number : 1
Keyword : TO
Number : 10
EndLine
Keyword : SEE
Identifier : x
Operator : +
Identifier : nl
EndLine
Keyword : NEXT
EndLine
Identifier : test
Operator : (
Operator : )
EndLine
Keyword : FUNC
Identifier : test
EndLine
Keyword : SEE
Literal : welcome
Operator : +
Identifier : nl
EndLine
Identifier : o1
Operator : =
Keyword : NEW
Identifier : point
Operator : {
Identifier : x
Operator : =
Number : 10
Identifier : y
Operator : =
Number : 20
Identifier : z
Operator : =
Number : 30
Operator : }
EndLine
Keyword : SEE
Identifier : o1
EndLine
Keyword : CLASS
Identifier : point
Identifier : x
Identifier : y
Identifier : z
65.1. Printing Tokens 684

EndLine
===================================================
65.2 Printing Rules
Command:
ring test.ring -rules -norun
Output:
===================================================
Grammar Rules Used by The Parser
===================================================
Rule : Program --> {Statement}
Line 1
Rule : Statement --> 'Func' Identifier [ParaList]
Line 2
Rule : Factor --> Literal
Rule : Range --> Factor
Rule : Term --> Range
Rule : Arithmetic --> Term
Rule : Factor --> Identifier [ {Mixer} | Assignment | PlusPlus | MinusMinus]
Rule : Arithmetic --> Arithmetic + Arithmetic
Rule : BitShift --> Arithmetic
Rule : BitAnd --> BitShift
Rule : BitOrXOR --> BitAnd
Rule : Compare --> BitOrXOR
Rule : EqualOrNot --> Compare
Rule : LogicNot -> EqualOrNot
Rule : Expr --> LogicNot
Rule : Statement --> 'See' Expr
Line 3
Rule : Factor --> Number
65.2. Printing Rules 685

Rule : Statement --> 'For' Identifier '=' Expr to Expr ['step' Expr]
Line 4
Line 5
Rule : Next --> 'Next'
Line 6
Rule : Mixer -> '(' [Expr { ',' Expr} ] ')'
Line 8
Rule : Statement --> Expr
Rule : Statement --> 'Func' Identifier [ParaList]
Line 9
Rule : Factor --> Literal

Line 10
Rule : Factor --> New Identifier {'.' Identifier }
Rule : Mixer --> '{' {Statement} BraceEnd
Rule : Assignment -> '=' Expr

Rule : BraceEnd --> '}'
Line 11

Line 13
Rule : Statement --> 'Class' Identifier
===================================================
65.3 Printing Intermediate Code
Command:
ring test.ring -ic -norun
Output:
65.3. Printing Intermediate Code 689

===================================================
Byte Code - Before Execution by the VM
===================================================
PC OPCode Data
1 ReturnNull
2 Func main
3 NewLine 2
4 FuncExE
5 PushC Hello World
6 LoadA nl 0
7 PushV
8 SUM 0
9 Print
10 NewLine 3
11 ExitMark 29 28
12 LoadAFirst x
13 PushN 1.000000
14 BeforeEqual 0
15 Assignment
16 PushN 1.000000
17 StepNumber
18 JumpVarLENum x 10.000000 29
19 NewLine 4
20 FuncExE
21 LoadA x 0
22 PushV
23 LoadA nl 0
24 PushV
25 SUM 0
26 Print
27 NewLine 5
28 IncJump x 18
29 POPExitMark
30 POPStep
31 NewLine 6
32 LoadFunc test
33 Call 0
34 NoOperation
35 NewLine 8
36 PushV
37 FreeStack
38 ReturnNull
39 Func test
40 NewLine 9
41 FuncExE
42 PushC welcome
43 LoadA nl 0
44 PushV
45 SUM 0
46 Print
47 NewLine 10
48 LoadA o1 0
49 AssignmentPointer
50 New point
51 SetScope
52 PushV

53 BraceStart
54 LoadA x 0 58
56 PushN 10.000000
57 BeforeEqual 0
58 Assignment 0 0
59 FreeStack
60 LoadA y 0 64
62 PushN 20.000000
63 BeforeEqual 0
64 Assignment 0 0
65 FreeStack
66 LoadA z 0 70
68 PushN 30.000000
69 BeforeEqual 0
70 Assignment 0 0
71 FreeStack
72 LoadFunc ismethod
73 LoadA self 0
74 PushV
75 PushC braceend
76 Call
77 NoOperation
78 PushV
79 JumpZ 85
80 LoadFunc braceend
81 Call
82 NoOperation
83 PushV
84 FreeStack
85 BraceEnd
86 FreeStack
87 NewLine 11
88 FuncExE
89 LoadA o1 0
90 PushV
91 Print
92 NewLine 13
93 ReturnNull
94 Class point 006E8BC0
95 NewLabel
96 LoadA x 0
97 PushV
98 FreeStack
99 LoadA y 0
100 PushV
101 FreeStack
102 LoadA z 0
103 PushV
104 FreeStack
105 ReturnNull
===================================================

65.4 Printing Final Intermediate Code
Command:
ring test.ring -icfinal
Output:
Hello World
1
2
3
4
5
6
7
8
9
10
welcome
x: 10.000000
y: 20.000000
z: 30.000000
===================================================
Byte Code - After Execution by the VM
===================================================
PC OPCode Data
1 ReturnNull
2 Func main
3 NewLine 2
4 FuncExE
5 PushC Hello World
6 PushP 007D3670 0
7 PushV
8 SUM 0
9 Print
10 NewLine 3
11 ExitMark 29 28
12 LoadAFirst x
13 PushN 1.000000
14 BeforeEqual 0
15 Assignment
16 PushN 1.000000
17 StepNumber
18 JumpVarLPLENum x 10.000000 29
19 NewLine 4
20 FuncExE
21 PushPLocal x 0
22 PushV
23 PushP 007D3670 0
24 PushV
25 SUM 0
26 Print
27 NewLine 5
65.4. Printing Final Intermediate Code 692

28 IncLPJump x 18
29 POPExitMark
30 POPStep
31 NewLine 6
32 LoadFuncP test
33 Call 0
34 NoOperation
35 NewLine 8
36 PushV
37 FreeStack
38 ReturnNull
39 Func test
40 NewLine 9
41 FuncExE
42 PushC welcome
43 PushP 007D3670 0
44 PushV
45 SUM 0
46 Print
47 NewLine 10
48 PushPLocal o1 0
50 New point
51 SetScope
52 PushV
53 BraceStart
54 LoadA x 0 58
56 PushN 10.000000
57 BeforeEqual 0
58 SetProperty 0 106
59 FreeStack
60 LoadA y 0 64
62 PushN 20.000000
63 BeforeEqual 0
65 FreeStack
66 LoadA z 0 70
68 PushN 30.000000
69 BeforeEqual 0
71 FreeStack
73 LoadA self 0
74 PushV
75 PushC braceend
76 Call
77 NoOperation
78 PushV
79 JumpZ 85
80 LoadFunc braceend
81 Call
82 NoOperation
83 PushV
84 FreeStack
85 BraceEnd

86 FreeStack
87 NewLine 11
88 FuncExE
89 PushPLocal o1 0
90 PushV
91 Print
92 NewLine 13
93 ReturnNull
94 Class point 007D8470
95 NewLabel
96 LoadA x 0
97 PushV
98 FreeStack
99 LoadA y 0
100 PushV
101 FreeStack
102 LoadA z 0
103 PushV
104 FreeStack
105 ReturnNull
107 LoadA ring_gettemp_var 0
108 PushV
109 PushC setx
110 Call 0
111 NoOperation
112 PushV
113 JumpZ 132
114 NewLine 2
116 LoadMethod setx
117 LoadA ring_settemp_var 0
118 PushV
119 Call 0 1
120 AfterCallMethod
121 PushV
122 FreeStack
123 NewLine 3
124 LoadA ring_tempflag_var 0 128
126 PushN 0.000000
127 BeforeEqual 0
128 Assignment 0 0
129 FreeStack
130 NewLine 4
131 Jump 140
132 NewLine 5
133 PushP 007D37D8 0 137
135 PushN 1.000000
136 BeforeEqual 0
137 Assignment 0 0
138 FreeStack
139 NewLine 6
140 Return
143 PushV

144 PushC sety
145 Call 0
146 NoOperation
147 PushV
148 JumpZ 167
149 NewLine 2
151 LoadMethod sety
153 PushV
154 Call 0 1
155 AfterCallMethod
156 PushV
157 FreeStack
158 NewLine 3
161 PushN 0.000000
162 BeforeEqual 0
163 Assignment 0 0
164 FreeStack
165 NewLine 4
166 Jump 175
167 NewLine 5
168 PushP 007D37D8 0 172
170 PushN 1.000000
171 BeforeEqual 0
172 Assignment 0 0
173 FreeStack
174 NewLine 6
175 Return
178 PushV
179 PushC setz
180 Call 0
181 NoOperation
182 PushV
183 JumpZ 202
184 NewLine 2
186 LoadMethod setz
188 PushV
189 Call 0 1
190 AfterCallMethod
191 PushV
192 FreeStack
193 NewLine 3
196 PushN 0.000000
197 BeforeEqual 0
198 Assignment 0 0
199 FreeStack
200 NewLine 4
201 Jump 210

202 NewLine 5
203 PushP 007D37D8 0 207
205 PushN 1.000000
206 BeforeEqual 0
207 Assignment 0 0
208 FreeStack
209 NewLine 6
210 Return
===================================================
65.5 CGI Support
Command:
ring test.ring -cgi
65.6 No Run
Command:
ring test.ring -norun
65.7 Printing Instruction Operation Code
Command:
ring test.ring -ins
Output:
===================================================
Operation : ReturnNull
PC : 1
Line Number : 1 , File test.ring
SP (After) : 0 - FuncSP : 0
LineNumber 1
===================================================
.....
.....
.....
Tip: Output removed from the previous example because it’s very large!
65.8 Performance
Command:
65.5. CGI Support 696

ring test.ring -performance
Output:
===================================================
Date : 2015/09/15 Time : 15:56:17
Clock : 0
===================================================
Hello World
1
2
3
4
5
6
7
8
9
10
welcome
x: 10.000000
y: 20.000000
z: 30.000000
===================================================
Date : 2015/09/15 Time : 15:56:17
Clock : 0
===================================================
65.9 Generate Object File
You can generate object file (.ringo) from your source code file (.ring) using -go option
Tip: You will get one object file to use for distributing/running your application which may contains one or many
ring source files that you can keep or distribute based on the application (commercial or open source).
Command:
ring test.ring -go
To run the compiled object file
ring test.ringo
65.9. Generate Object File 697

CHAPTER
SIXTYSIX
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_ﬁleslist()
• ringvm_settrace()
• ringvm_tracedata()
• ringvm_traceevent()
• ringvm_tracefunc()
• ringvm_scopescount()
• ringvm_evalinscope()
• ringvm_passerror()
• ringvm_hideerrorMsg()
• ringvm_callfunc()
698

66.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 ﬂy 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.
66.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)
66.3 space() function
Use the space function to allocate a speciﬁc number of bytes in Memory.
66.1. callgc() function 699

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.
66.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 ﬁrst.
Tip: We can pass NULL as parameter instead of using NULLPointer()
66.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 )
66.6 pointer2object() function
Use this function to get the Ring list and/or object from the low level object (C Pointer)
66.4. nullpointer() function 700

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).
66.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")
66.7. ptrcmp() function 701

see ptrcmp(fp,fp2) + nl
see ptrcmp(fp,fp3) + nl
fclose(fp)
fclose(fp3)
Output:
1
0
66.8 ringvm_cfunctionslist() function
The Function return a list of functions written in C.
Syntax:
RingVM_CFunctionsList() ---> List
Example:
See RingVM_CFunctionsList()
66.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
66.8. ringvm_cfunctionslist() function 702

66.10 ringvm_classeslist() function
The Function return a list of Classes.
• 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
66.11 ringvm_packageslist() function
The Function return a list of Packages.
• Package Name
66.10. ringvm_classeslist() function 703

• 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
66.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:
66.12. ringvm_memorylist() function 704

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
66.12. ringvm_memorylist() function 705

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
66.13 ringvm_calllist() function
The Function return a list of the functions call list.
• Function Type
• Function Name
• Program Counter (PC)
• Stack Pointer (SP)
• Temp. Memory List
• Method or Function Flag
• Caller PC
• FuncExec Flag
• ListStart Flag
66.13. ringvm_calllist() function 706

• 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
66.14 ringvm_ﬁleslist() 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
66.14. ringvm_ﬁleslist() function 707

stdconversion.ring
stdodbc.ring
stdmysql.ring
stdsecurity.ring
stdinternet.ring
stdhashtable.ring
stdtree.ring
66.15 ringvm_settrace()
The function ringvm_settrace() determine the Trace function name
The trace function is a Ring function that will be called for each event
Syntax:
RingVM_SetTrace(cCode)
66.16 ringvm_tracedata()
Inside the function that we will use for tracing events
We can use the ringvm_tracedata() function to get the event data.
The event data is a list contains the next items
• The Source Code Line Number
• The Source File Name
• The Function/Method Name
• Method or Function (Bool : True=Method, False=Function/File)
Syntax:
RingVM_TraceData() ---> aDataList
66.17 ringvm_traceevent()
Inside the function that we will use for tracing events
We can use ringvm_traceevent() to know the event type
• New Line
• Before Function
• After Function
• Runtime Error
• Before C Function
• After C Function
Syntax:
66.15. ringvm_settrace() 708

RingVM_TraceEvent() ---> nTraceEvent
66.18 ringvm_tracefunc()
The function return the name of the function that we are using for tracing events.
Syntax:
RingVM_TraceEvent() ---> cCode
66.19 ringvm_scopescount()
We can use the RingVM_ScopesCount() function to know the number of scopes used in the application.
In the start of the program, We have the (global scope only)
When we call a function, A new scope is created.
When the function execution is done, the function scope is deleted.
Syntax:
RingVM_ScopesCount() ---> nScopes
66.20 ringvm_evalinscope()
The function ringvm_evalinscope() is similar to the eval() function
Unlike eval() which execute the code in the current scope
Using RingVM_EvalInScope() we can execute the scope in a speciﬁc scope.
Syntax:
RingVM_EvalInScope(nScope,cCode)
66.21 ringvm_passerror()
When we have runtime error, After printing the Error message, Ring will end the execution of the program.
Using ringvm_passerror() we can avoid that, and continue the execution of our program.
Syntax:
RingVM_PassError()
66.22 ringvm_hideerrormsg()
We can disable/enable displaying the runtime error messages using the RingVM_HideErrorMsg() function.
Syntax:
66.18. ringvm_tracefunc() 709

RingVM_HideErrorMsg(lStatus)
66.23 ringvm_callfunc()
We can call a function from a string without using eval() using the ringvm_callfunc()
Syntax:
RingVM_CallFunc(cFuncName)
66.24 Example - Using the Trace Functions
The next example use the Trace Functions to trace the program Events!
In practical, We will use the Trace Library instead of these low level functions!
load "tracelib.ring"
ringvm_settrace("mytrace()")
see "Hello, world!" + nl
see "Welcome" + nl
see "How are you?" +nl
mytest()
new myclass { mymethod() }
func mytest
see "Message from mytest" + nl
func mytrace
see "====== The Trace function is Active ======" + nl +
"Trace Function Name : " + ringvm_TraceFunc() + nl +
"Trace Event : "
switch ringvm_TraceEvent()
on TRACEEVENT_NEWLINE see "New Line"
on TRACEEVENT_NEWFUNC see "New Function"
on TRACEEVENT_RETURN see "Return"
on TRACEEVENT_ERROR see "Error"
on TRACEEVENT_BEFORECFUNC see "Before C Function"
on TRACEEVENT_AFTERCFUNC see "After C Function"
off
see nl +
"Line Number : " + ringvm_tracedata()[TRACEDATA_LINENUMBER] + nl +
"File Name : " + ringvm_tracedata()[TRACEDATA_FILENAME] + nl +
"Function Name : " + ringvm_tracedata()[TRACEDATA_FUNCNAME] + nl +
"Method or Function : "
if ringvm_tracedata()[TRACEDATA_METHODORFUNC] =
TRACEDATA_METHODORFUNC_METHOD
see "Method"
else
if ringvm_tracedata()[TRACEDATA_FUNCNAME] = NULL
see "Command"
else
see "Function"
66.23. ringvm_callfunc() 710

ok
ok
see nl + Copy("=",42) + nl
class myclass
func mymethod
see "Message from mymethod" + nl
Output:
====== The Trace function is Active ======
Trace Function Name : mytrace()
Trace Event : After C Function
Line Number : 3
File Name : test1.ring
Function Name : ringvm_settrace
Method or Function : Function
==========================================
Trace Event : New Line
Line Number : 5
Function Name :
Method or Function : Command
==========================================
Hello, world!
Line Number : 6
Function Name :
==========================================
Welcome
Line Number : 7
Function Name :
==========================================
How are you?
Line Number : 8
Function Name :
==========================================
Trace Event : New Function
Line Number : 8
66.24. Example - Using the Trace Functions 711

Function Name : mytest
==========================================
Line Number : 12
==========================================
Message from mytest
Line Number : 14
==========================================
Trace Event : Return
Line Number : 8
Function Name :
==========================================
Line Number : 9
Function Name :
==========================================
Line Number : 43
Function Name :
==========================================
Trace Event : Before C Function
Line Number : 9
Function Name : ismethod
==========================================
Line Number : 9

==========================================
Trace Event : New Function
Line Number : 9
Function Name : mymethod
Method or Function : Method
==========================================
Line Number : 44
Function Name : mymethod
Method or Function : Method
==========================================
Message from mymethod
Trace Event : Return
Line Number : 9
Function Name :
==========================================
Line Number : 9
==========================================
Line Number : 9
==========================================
Line Number : 9
==========================================
Line Number : 9

==========================================
Line Number : 11
Function Name :
==========================================
66.25 Example - The Trace Library
The next example uses the Trace functions provided by the Ring language to create the Trace library.
Using the Trace library we have nice Tracing tools and Interaction debugger too.
# Trace Events
TRACEEVENT_NEWLINE = 1
TRACEEVENT_NEWFUNC = 2
TRACEEVENT_RETURN = 3
TRACEEVENT_ERROR = 4
TRACEEVENT_BEFORECFUNC = 5
TRACEEVENT_AFTERCFUNC = 6
# Trace Data
TRACEDATA_LINENUMBER = 1
TRACEDATA_FILENAME = 2
TRACEDATA_FUNCNAME = 3
TRACEDATA_METHODORFUNC = 4
# Method of Function
TRACEDATA_METHODORFUNC_METHOD = TRUE
TRACEDATA_METHODORFUNC_NOTMETHOD = FALSE
TRACE_BREAKPOINTS = TRUE
TRACE_TEMPLIST = []
func Trace cType
switch trim(lower(cType))
on :AllEvents
ringvm_settrace("TraceLib_AllEvents()")
on :Functions
ringvm_settrace("TraceLib_Functions()")
on :PassError
ringvm_settrace("TraceLib_PassError()")
on :Debugger
ringvm_settrace("TraceLib_Debugger()")
on :LineByLine
ringvm_settrace("TraceLib_LineByLine()")
off
func TraceLib_AllEvents
if right(ringvm_tracedata()[TRACEDATA_FILENAME],13) = "tracelib.ring"
return
ok
see "====== The Trace function is Active ======" + nl +
66.25. Example - The Trace Library 714

"Trace Function Name : " + ringvm_TraceFunc() + nl +
"Trace Event : "
on TRACEEVENT_NEWLINE see "New Line"
on TRACEEVENT_NEWFUNC see "New Function"
on TRACEEVENT_RETURN see "Return"
on TRACEEVENT_ERROR see "Error"
on TRACEEVENT_BEFORECFUNC see "Before C Function"
on TRACEEVENT_AFTERCFUNC see "After C Function"
off
see nl +
"Line Number : " + ringvm_tracedata()[TRACEDATA_LINENUMBER] + nl +
"File Name : " + ringvm_tracedata()[TRACEDATA_FILENAME] + nl +
"Function Name : " + ringvm_tracedata()[TRACEDATA_FUNCNAME] + nl +
"Method or Function : "
if ringvm_tracedata()[TRACEDATA_METHODORFUNC] =
TRACEDATA_METHODORFUNC_METHOD
see "Method"
else
if ringvm_tracedata()[TRACEDATA_FUNCNAME] = NULL
see "Command"
else
see "Function"
ok
ok
see nl + Copy("=",42) + nl
func TraceLib_Functions
return
ok
on TRACEEVENT_NEWFUNC
see "Open Func : " +
ringvm_TraceData()[TRACEDATA_FUNCNAME] + nl
on TRACEEVENT_RETURN
see "Return to Func : " +
ringvm_TraceData()[TRACEDATA_FUNCNAME] + nl
off
func TraceLib_PassError
return
ok
on TRACEEVENT_ERROR
see nl
see "TraceLib : After Error !" + nl
ringvm_passerror()
off
func TraceLib_Debugger
return
ok
on TRACEEVENT_ERROR
_BreakPoint()

off
func TraceLib_LineByLine
if right(ringvm_tracedata()[TRACEDATA_FILENAME],13) = "tracelib.ring" or
ringvm_TraceEvent() != TRACEEVENT_NEWLINE
return
ok
aList = ringvm_tracedata()
see "Before Line : " + aList[TRACEDATA_LINENUMBER] + nl
_BreakPoint()
func BreakPoint
if not TRACE_BREAKPOINTS
return
ok
_BreakPoint()
func _BreakPoint
see nl+nl+Copy("=",60) + nl +
Copy(" ",20)+"Interactive Debugger" + nl +
Copy("=",60) + nl +
"Command (Exit) : End Program" + nl +
"Command (Cont) : Continue Execution" + nl +
"Command (Locals) : Print local variables names" + nl +
"Command (LocalsData) : Print local variables data" + nl +
"Command (Globals) : Print global variables names" + nl +
"We can execute Ring code" + nl +
Copy("=",60) + nl
while true
see nl + "code:> "
give cCode
cmd = trim(lower(cCode))
if cmd = "exit" or cmd = "bye"
shutdown()
ok
nScope = ringvm_scopescount()-2
switch cmd
on "locals"
ringvm_EvalInScope(nScope,"see locals() callgc()")
loop
on "localsdata"
PrintLocalsData(nScope)
loop
on "globals"
ringvm_EvalInScope(nScope,"see globals() callgc()")
loop
on "cont"
ringvm_passerror()
exit
off
Try
ringvm_EvalInScope(nScope,cCode)
catch
see cCatchError
done
end
func NoBreakPoints

TRACE_BREAKPOINTS = FALSE
func PrintLocalsData nScope
if nScope = 1 # Global
ringvm_Evalinscope(nScope,'TRACE_TEMPLIST = globals()')
else
ringvm_Evalinscope(nScope,'TRACE_TEMPLIST = locals() callgc()')
ok
see nl
aTempList = TRACE_TEMPLIST
TRACE_TEMPLIST = []
nSpaces = 5
for TRACE_ITEM in aTempList
if len(TRACE_ITEM) + 5 > nSpaces
nSpaces = len(TRACE_ITEM) + 5
ok
next
for TRACE_ITEM in aTempList
see "Variable : " + TRACE_ITEM
cVarName = TRACE_ITEM
see copy(" ",nSpaces-len(cVarName)) + " Type : "
ringvm_Evalinscope(nScope,"see type(" + TRACE_ITEM +")")
ringvm_Evalinscope(nScope,"see Copy(' ',fabs(15-len(type(" +
TRACE_ITEM +"))))")
see " Value : "
ringvm_Evalinscope(nScope,"see " + TRACE_ITEM)
see nl
next

CHAPTER
SIXTYSEVEN
THE TRACE LIBRARY AND THE INTERACTIVE DEBUGGER
In this chapter we will learn about the Trace Library and the Interactive Debugger
67.1 Loading the Trace library
To start using the Trace library, We must load it first!
67.2 Trace All Events
The next example demonstrates the Trace library usage to trace all events.
# Trace All Events
trace(:AllEvents)
see "Hello, world!" + nl
see "Welcome" + nl
see "How are you?" +nl
mytest()
new myclass { mymethod() }
func mytest
see "Message from mytest" + nl
class myclass
func mymethod
see "Message from mymethod" + nl
67.3 Trace control flow between functions
The next example demonstrates the Trace library usage to trace the control flow between functions.
Trace(:Functions)
test1()
718

func test1
see :test1 + nl
test2()
func test2
see :test2 + nl
see test3() + nl
func test3
see :test3 + nl
return "test 3 output"
67.4 Pass Error
The next example demonstrates the Trace library usage to pass an error!
Trace(:PassError)
test1()
func test1
x = 10
see :test1 + nl
test2() # Runtime Error!
see "We can continue!"
67.5 Interactive Debugger
The next example demonstrates the Trace library usage to use the Interactive Debugger
Trace(:Debugger)
test1()
see "good bye!" + nl
func test1
x = 10
see :test1 + nl
t = 12
test2() # Runtime Error!
see "After Error!" +nl
see "t = " see t see nl
see "x = " see x see nl
67.6 Execute Program Line by Line
The next example demonstrates the Trace library usage to execute the program line by line!
Trace(:LineByLine)
test1()
67.4. Pass Error 719

func test1
x = 10
see :test1 + nl
t = 12
test2()
see "After Error!" +nl
see "t = " + t + nl
67.7 BreakPoint
The next example demonstrates the Trace library usage to stop at a breakpoint!
test1()
func test1
x = 10
see :test1 + nl
t = 12
BreakPoint()
see "After breakpoint!" +nl
see "t = " + t + nl
see "End of program!" + nl
67.8 Disable BreakPoints
The next example demonstrates the Trace library usage and how to disable the Breakpoints!
NoBreakPoints()
test1()
func test1
x = 10
see :test1 + nl
t = 12
BreakPoint()
see "t = " + t + nl
67.9 Using the Interactive Debugger
The next example uses a Breakpoint to open the Interactive Debugger!
test1()
func test1
x = 10
see :test1 + nl
t = 12
67.7. BreakPoint 720

BreakPoint()
see "t = " + t + nl
Screen Shots:
We have the Interactive Debugger at the Breakpoint!
We can print the variables values
We can change the variables values then continue execution
67.9. Using the Interactive Debugger 721

We can run the Interactive Debugger in the Output Window
67.9. Using the Interactive Debugger 722

CHAPTER
SIXTYEIGHT
EMBEDDING RING IN RING
In this chapter we will learn about embedding Ring in Ring programs and applications.
68.1 Embedding Ring in Ring without sharing the State
From Ring 1.0 we already have functions for embedding Ring in the C language. Also we can execute Ring code
inside Ring programs using the eval() function. In this release we provide functions for embedding Ring in Ring
programs without sharing the state.
Advantages:
1. Quick integration for Ring programs and applications together without conﬂicts.
2. Execute and run Ring code in safe environments that we can trace.
Example:
pState = ring_state_init()
ring_state_runcode(pState,"See 'Hello, World!'+nl")
ring_state_runcode(pState,"x = 10")
pState2 = ring_state_init()
ring_state_runcode(pState2,"See 'Hello, World!'+nl")
ring_state_runcode(pState2,"x = 20")
ring_state_runcode(pState,"see x +nl")
ring_state_runcode(pState2,"see x +nl")
v1 = ring_state_findvar(pState,"x")
v2 = ring_state_findvar(pState2,"x")
see v1[3] + nl
see V2[3] + nl
ring_state_delete(pState)
ring_state_delete(pState2)
Output:
Hello, World!
Hello, World!
10
20
10
20
723

68.2 Serial Execution of Programs
We can execute application after another application using ring_state_main()
Example:
chdir(exefolder()+"/../applications/formdesigner")
ring_state_main('formdesigner.ring')
chdir(exefolder()+"/../applications/cards")
ring_state_main('cards.ring')
68.2. Serial Execution of Programs 724

CHAPTER
SIXTYNINE
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
69.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
69.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
725

/* 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
}
69.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);
69.3. Module Organization 726

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 ﬁle).
69.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.
69.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:
69.4. Function Structure 727

if ( RING_API_PARACOUNT == 1 ) {
/* code */
}
69.6 Display Error Message
We can display error messages using the RING_API_ERROR() function.
The function will display the error and end the execution of the program.
Note: the behaviour of this function can be changed by the Ring code using Try/Catch/Done statements, so in your C
code, use Return after this function.
Syntax:
RING_API_ERROR(const char *cErrorMsg);
The Ring API comes with some of predeﬁned error messages that we can use
#define RING_API_MISS1PARA "Bad parameters count, the function expect one parameter"
#define RING_API_MISS2PARA "Bad parameters count, the function expect two parameters"
#define RING_API_MISS3PARA "Bad parameters count, the function expect three parameters"
#define RING_API_MISS4PARA "Bad parameters count, the function expect four parameters"
#define RING_API_BADPARATYPE "Bad parameter type!"
#define RING_API_BADPARACOUNT "Bad parameters count!"
#define RING_API_BADPARARANGE "Bad parameters value, error in range!"
#define RING_API_NOTPOINTER "Error in parameter, not pointer!"
#define RING_API_NULLPOINTER "Error in parameter, NULL pointer!"
#define RING_API_EMPTYLIST "Bad parameter, empty list!"
69.7 Check Parameters Type
We can check the parameter type using the next functions
int RING_API_ISNUMBER(int nParameterNumber);
int RING_API_ISSTRING(int nParameterNumber);
int RING_API_ISLIST(int nParameterNumber);
int RING_API_ISPOINTER(int nParameterNumber);
The output of these functions will be 1 (True) or 0 (False).
69.8 Get Parameters Values
We can get paramters values using the next functions
double RING_API_GETNUMBER(int nParameterNumber);
const char *RING_API_GETSTRING(int nParameterNumber);
int RING_API_GETSTRINGSIZE(int nParameterNumber);
List *RING_API_GETLIST(int nParameterNumber);
void *RING_API_GETCPOINTER(int nParameterNumber, const char *cPoinerType);
int RING_API_GETPOINTERTYPE(int nParameterNumber);
69.6. Display Error Message 728

69.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);
69.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);
69.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 )
{
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);
}
}
69.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
69.9. Return Value 729

void ring_vm_file_fopen ( void *pPointer )
{
FILE *fp ;
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 {
}
}
The next code represents the fclose() function implementation
void ring_vm_file_fclose ( void *pPointer )
{
FILE *fp ;
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 {
}
}
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
69.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 ) ;
69.13. Ring API - List Functions 730

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)
69.13. Ring API - List Functions 731

ring_list_getstringsize(pList,index)
ring_list_getsize(x) (x->nSize)
69.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)
69.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 ;
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 ) {
69.14. Ring API - String Functions 732

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 {
}
}
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.
69.16 Dynamic/Shared Libraries (DLL/So) and LoadLib() function
Instead of rebuilding the RingVM after writing new functions using C/C++ and the Ring API, we can create a DLL/So
ﬁle and dynamically use the functions provided by this ﬁle 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");
}
RING_DLL void ringlib_init(RingState *pRingState)
{
69.16. Dynamic/Shared Libraries (DLL/So) and LoadLib() function 733

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 ﬁle 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
69.16. Dynamic/Shared Libraries (DLL/So) and LoadLib() function 734

CHAPTER
SEVENTY
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);
70.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
70.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[] ) ;
735

void ring_state_runfile ( RingState *pRingState,const char *cFileName ) ;
void ring_state_runobjectfile ( RingState *pRingState,const char *cFileName ) ;
70.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_ﬁndvar() 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");
pList = ring_state_newvar(pState,"v2");
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);
70.3. Ring State Variables 736

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
70.3. Ring State Variables 737

CHAPTER
SEVENTYONE
CODE GENERATOR FOR WRAPPING C/C++ LIBRARIES
In this chapter we will learn how to use the code generator to wrap C/C++ Libraries to use it in our Ring applications.
71.1 Using the tool
The code generator program is parsec.ring that can be executed as any ring code using the ring language.
URL : https://github.com/ring-lang/ring/tree/master/extensions/codegen
for example to read a configuration file called test.cf to generate the source code file test.c run parsec.ring as in the
next command
ring parsec.ring test.cf test.c
71.2 Configuration file
The configuration file (*.cf) is the input file that we pass to the code generator. This file determine the functions
prototypes that we need to use from a C/C++ library.
Writing configuration files is simple according to the next rules
71.3 Using the function prototype
• To generate code that wraps a C function, we just write the C function prototype
Example:
ALLEGRO_DISPLAY *al_create_display(int w, int h)
void al_destroy_display(ALLEGRO_DISPLAY *display)
int al_get_new_display_flags(void)
void al_set_new_display_flags(int flags)
int al_get_new_display_option(int option, int *importance)
The previous example will guide the code generator to generate 5 functions that wraps the al_create_display(),
al_destroy_display(), al_get_new_display_flags(), al_set_new_diplay_flas() and al_get_new_display_option() func-
tions.
The generated code will be as in the next example
738

RING_FUNC(ring_al_create_display)
{
return ;
}
if ( ! RING_API_ISNUMBER(1) ) {
return ;
}
return ;
}
RING_API_RETCPOINTER(al_create_display( (int ) RING_API_GETNUMBER(1),
(int ) RING_API_GETNUMBER(2)),"ALLEGRO_DISPLAY");
}
RING_FUNC(ring_al_destroy_display)
{
return ;
}
if ( ! RING_API_ISPOINTER(1) ) {
return ;
}
al_destroy_display((ALLEGRO_DISPLAY *) RING_API_GETCPOINTER(1,"ALLEGRO_DISPLAY"));
}
RING_FUNC(ring_al_get_new_display_flags)
{
RING_API_ERROR(RING_API_BADPARACOUNT);
return ;
}
RING_API_RETNUMBER(al_get_new_display_flags());
}
RING_FUNC(ring_al_set_new_display_flags)
{
return ;
}
return ;
}
al_set_new_display_flags( (int ) RING_API_GETNUMBER(1));
}
RING_FUNC(ring_al_get_new_display_option)
71.3. Using the function prototype 739

{
return ;
}
return ;
}
if ( ! RING_API_ISSTRING(2) ) {
return ;
}
RING_API_RETNUMBER(al_get_new_display_option( (int ) RING_API_GETNUMBER(1),
RING_API_GETINTPOINTER(2)));
RING_API_ACCEPTINTVALUE(2) ;
}
from the previous example we can see how much of time and effort is saved using the Code Generator.
71.4 Adding code to the generated code
• To generate code directly type it between <code> and </code>
Example :
<code>
/* some C code will be written here */
</code>
We use this feature when we need to do something without the help of the code generator. for example including
header files and defining constants using Macro.
71.5 Prefix for Functions Names
• To determine a prefix in all of the functions names type it between <funcstart> and </funcstart> for ex-
ample when we wrap the Allegro game programming library and we need all of the library functions
to start with “al” we type the next code in the configuration file
<funcstart>
al
</funcstart>
71.6 Generate function to wrap structures
• To generate functions that wrap structures (create/delete/get structure members)
just type the structures names between <struct> and </struct> also after the structure name you can type the structure
members between { } separated by comma.
Example
71.4. Adding code to the generated code 740

<struct>
ALLEGRO_COLOR
ALLEGRO_EVENT { type , keyboard.keycode , mouse.x , mouse.y }
</struct>
from the previous example we will generate two function to create/delete the structure ALLEGRO_COLOR Also we
will generate two functions to create/delete the structure ALLEGRO_EVENT and four functions to get the structure
ALLEGRO_EVENT members (type, keyboard.keycode, mouse.x, mouse.y).
71.7 Determine Structure Members Types
You can determine the pointer name before the strucuture member name.
Example:
SDL_Surface {flags,SDL_PixelFormat *format,w,h,pitch,void *pixels}
71.8 Defining Constants
You can define constants using <constant> and </constant>
The generator will generate the required functions to get the constant values
And will define the constants to be used with the same name in Ring code using *.rh file that will be generated too.
rh = Ring Header
Example:
<constant>
MIX_DEFAULT_FORMAT
SDL_QUIT
SDL_BUTTON_LEFT
SDL_BUTTON_MIDDLE
SDL_BUTTON_RIGHT
</constant>
Note: You will need to pass the *.rh file name to parsec.ring after the generated source file name.
Example:
ring ..codegenparsec.ring libsdl.cf ring_libsdl.c ring_libsdl.rh
71.9 Register New Functions
We can register functions by typing the function prototype between <register> and </register> We need this feature
only when we don’t provide the function prototype as input directly where we need to write the code of this function.
Example:
<register>
void al_exit(void)
</register>
71.7. Determine Structure Members Types 741

The Ring programming language version 1.5 book - Part 13 of 31

More Related Content

Similar to The Ring programming language version 1.5 book - Part 13 of 31 (20)

More from Mahmoud Samir Fayed (20)

Recently uploaded (20)

The Ring programming language version 1.5 book - Part 13 of 31