docs/en/source/embedding.txt

   1 .. index::
   2         single: Embedding Ring Language in C/C++ Programs; Introduction
   3
   4 =============================================
   5 Embedding Ring Language in C/C++ Programs
   6 =============================================
   7
   8 We can use the Ring language from C/C++ programs using the next functions
   9
  10 .. code-block:: C
  11
  12         RingState *ring_state_init();
  13         ring_state_runcode(RingState *pState,const char *cCode);
  14         ring_state_delete(RingState *pState);
  15
  16 .. index::
  17         pair: Embedding Ring Language in C/C++ Programs; Ring State
  18
  19 Ring State
  20 ==========
  21
  22 The idea is to use the ring_state_init() to create new state for the Ring Language
  23 then call the ring_state_runcode() function to execut Ring code using the same state.
  24 When we are done, we call the ring_state_delete() to free the memory.
  25
  26 Example:
  27
  28 .. code-block:: C
  29
  30         #include "ring.h"
  31         #include "stdlib.h"
  32         int main(int argc, char *argv[])
  33         {
  34           RingState *pState = ring_state_init();
  35           printf("welcome\n");
  36           ring_state_runcode(pState,"see 'hello world from the ring programming language'+nl");
  37           ring_state_delete(pState);
  38         }
  39
  40 Output:
  41
  42 .. code-block:: C
  43
  44         welcome
  45         hello world from the ring programming language
  46
  47 .. index::
  48         pair: Embedding Ring Language in C/C++ Programs; Ring State Functions
  49
  50 Ring State Functions
  51 ====================
  52
  53 The Ring API comes with the next functions to create and delete the state.
  54 Also we have functions to create new variables and get variables values.
  55
  56 .. code-block:: C
  57
  58         RingState * ring_state_init ( void ) ;
  59         RingState * ring_state_delete ( RingState *pRingState ) ;
  60         void ring_state_runcode ( RingState *pRingState,const char *cStr ) ;
  61         List * ring_state_findvar ( RingState *pRingState,const char *cStr ) ;
  62         List * ring_state_newvar ( RingState *pRingState,const char *cStr ) ;
  63         void ring_state_main ( int argc, char *argv[] ) ;
  64         void ring_state_runfile ( RingState *pRingState,const char *cFileName ) ;
  65         void ring_state_runobjectfile ( RingState *pRingState,const char *cFileName ) ;
  66
  67 .. index::
  68         pair: Embedding Ring Language in C/C++ Programs; Ring State Variables
  69
  70 Ring State Variables
  71 ====================
  72
  73 We can create more than one ring state in the same program and we can create and modify variable values.
  74
  75 To get the variable list we can use the ring_state_findvar() function.
  76
  77 To create new variable we can use the ring_state_newvar() function.
  78
  79 Example:
  80
  81 .. code-block:: C
  82
  83         #include "ring.h"
  84         #include "stdlib.h"
  85
  86         int main(int argc, char *argv[])
  87         {
  88           List *pList;
  89
  90           RingState *pState = ring_state_init();
  91           RingState *pState2 = ring_state_init();
  92
  93           printf("welcome\n");
  94           ring_state_runcode(pState,"see 'hello world from the ring programming language'+nl");
  95
  96           printf("Again from C we will call ring code\n");
  97           ring_state_runcode(pState,"for x = 1 to 10 see x + nl next");
  98
  99           ring_state_runcode(pState2,"for x = 1 to 5 see x + nl next");
 100
 101           printf("Now we will display the x variable value from ring code\n");
 102           ring_state_runcode(pState,"see 'x value : ' + x + nl ");
 103           ring_state_runcode(pState2,"see 'x value : ' + x + nl ");
 104
 105           pList = ring_state_findvar(pState,"x");
 106
 107           printf("Printing Ring variable value from C , %.0f\n",
 108                         ring_list_getdouble(pList,RING_VAR_VALUE));
 109
 110           printf("now we will set the ring variable value from C\n");
 111           ring_list_setdouble(pList,RING_VAR_VALUE,20);
 112
 113           ring_state_runcode(pState,"see 'x value after update : ' + x + nl ");
 114
 115           pList = ring_state_newvar(pState,"v1");
 116           ring_list_setdouble(pList,RING_VAR_VALUE,10);
 117
 118           pList = ring_state_newvar(pState,"v2");
 119           ring_list_setdouble(pList,RING_VAR_VALUE,20);
 120
 121           ring_state_runcode(pState,"see 'v1 + v2 = ' see v1+v2 see nl");
 122
 123           ring_state_runcode(pState,"see 'end of test' + nl");
 124
 125           ring_state_delete(pState);
 126           ring_state_delete(pState2);
 127         }
 128
 129 Output:
 130
 131 .. code-block:: ring
 132
 133         welcome
 134         hello world from the ring programming language
 135         Again from C we will call ring code
 136         1
 137         2
 138         3
 139         4
 140         5
 141         6
 142         7
 143         8
 144         9
 145         10
 146         1
 147         2
 148         3
 149         4
 150         5
 151         Now we will display the x variable value from ring code
 152         x value : 11
 153         x value : 6
 154         Printing Ring variable value from C , 11
 155         now we will set the ring variable value from C
 156         x value after update : 20
 157         v1 + v2 = 30
 158         end of test