doc/embedding.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Embedding Ring Interpreter in C/C++ Programs &mdash; Ring 1.0 documentation</title>
    
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '1.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
    <link rel="top" title="Ring 1.0 documentation" href="index.html" />
    <link rel="next" title="Command Line Options" href="interpreter.html" />
    <link rel="prev" title="Extension using the C/C++ languages" href="extension.html" /> 
  </head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="interpreter.html" title="Command Line Options"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="extension.html" title="Extension using the C/C++ languages"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Ring 1.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="embedding-ring-interpreter-in-c-c-programs">
<h1>Embedding Ring Interpreter in C/C++ Programs<a class="headerlink" href="#embedding-ring-interpreter-in-c-c-programs" title="Permalink to this headline">¶</a></h1>
<p>We can call the Ring interpreter from C/C++ programs using the next functions</p>
<div class="highlight-C"><div class="highlight"><pre><span class="n">RingState</span> <span class="o">*</span><span class="nf">ring_state_init</span><span class="p">();</span>
<span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">RingState</span> <span class="o">*</span><span class="n">pState</span><span class="p">,</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">cCode</span><span class="p">);</span>
<span class="n">ring_state_delete</span><span class="p">(</span><span class="n">RingState</span> <span class="o">*</span><span class="n">pState</span><span class="p">);</span>
</pre></div>
</div>
<div class="section" id="ring-state">
<span id="index-0"></span><h2>Ring State<a class="headerlink" href="#ring-state" title="Permalink to this headline">¶</a></h2>
<p>The idea is to use the ring_state_init() to create new state for the Ring Interpreter
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.</p>
<p>Example:</p>
<div class="highlight-C"><div class="highlight"><pre><span class="cp">#include &quot;ring.h&quot;</span>
<span class="cp">#include &quot;stdlib.h&quot;</span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span>
<span class="p">{</span>
  <span class="n">RingState</span> <span class="o">*</span><span class="n">pState</span> <span class="o">=</span> <span class="n">ring_state_init</span><span class="p">();</span>
  <span class="n">printf</span><span class="p">(</span><span class="s">&quot;welcome</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
  <span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;see &#39;hello world from the ring programming language&#39;+nl&quot;</span><span class="p">);</span>
  <span class="n">ring_state_delete</span><span class="p">(</span><span class="n">pState</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Output:</p>
<div class="highlight-C"><div class="highlight"><pre><span class="n">welcome</span>
<span class="n">hello</span> <span class="n">world</span> <span class="n">from</span> <span class="n">the</span> <span class="n">ring</span> <span class="n">programming</span> <span class="n">language</span>
</pre></div>
</div>
</div>
<div class="section" id="ring-state-functions">
<span id="index-1"></span><h2>Ring State Functions<a class="headerlink" href="#ring-state-functions" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<div class="highlight-C"><div class="highlight"><pre><span class="n">RingState</span> <span class="o">*</span> <span class="nf">ring_state_init</span> <span class="p">(</span> <span class="kt">void</span> <span class="p">)</span> <span class="p">;</span>
<span class="n">RingState</span> <span class="o">*</span> <span class="nf">ring_state_delete</span> <span class="p">(</span> <span class="n">RingState</span> <span class="o">*</span><span class="n">pRingState</span> <span class="p">)</span> <span class="p">;</span>
<span class="kt">void</span> <span class="nf">ring_state_runcode</span> <span class="p">(</span> <span class="n">RingState</span> <span class="o">*</span><span class="n">pRingState</span><span class="p">,</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">cStr</span> <span class="p">)</span> <span class="p">;</span>
<span class="n">List</span> <span class="o">*</span> <span class="nf">ring_state_findvar</span> <span class="p">(</span> <span class="n">RingState</span> <span class="o">*</span><span class="n">pRingState</span><span class="p">,</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">cStr</span> <span class="p">)</span> <span class="p">;</span>
<span class="n">List</span> <span class="o">*</span> <span class="nf">ring_state_newvar</span> <span class="p">(</span> <span class="n">RingState</span> <span class="o">*</span><span class="n">pRingState</span><span class="p">,</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">cStr</span> <span class="p">)</span> <span class="p">;</span>
<span class="kt">void</span> <span class="nf">ring_state_main</span> <span class="p">(</span> <span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[]</span> <span class="p">)</span> <span class="p">;</span>
<span class="kt">void</span> <span class="nf">ring_state_runfile</span> <span class="p">(</span> <span class="n">RingState</span> <span class="o">*</span><span class="n">pRingState</span><span class="p">,</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">cFileName</span> <span class="p">)</span> <span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="ring-state-variables">
<span id="index-2"></span><h2>Ring State Variables<a class="headerlink" href="#ring-state-variables" title="Permalink to this headline">¶</a></h2>
<p>We can create more than one ring state in the same program and we can create and modify variable values.</p>
<p>To get the variable list we can use the ring_state_findvar() function.</p>
<p>To create new variable we can use the ring_state_newvar() function.</p>
<p>Example:</p>
<div class="highlight-C"><div class="highlight"><pre><span class="cp">#include &quot;ring.h&quot;</span>
<span class="cp">#include &quot;stdlib.h&quot;</span>

<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span>
<span class="p">{</span>
  <span class="n">List</span> <span class="o">*</span><span class="n">pList</span><span class="p">;</span>

  <span class="n">RingState</span> <span class="o">*</span><span class="n">pState</span> <span class="o">=</span> <span class="n">ring_state_init</span><span class="p">();</span>
  <span class="n">RingState</span> <span class="o">*</span><span class="n">pState2</span> <span class="o">=</span> <span class="n">ring_state_init</span><span class="p">();</span>

  <span class="n">printf</span><span class="p">(</span><span class="s">&quot;welcome</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
  <span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;see &#39;hello world from the ring programming language&#39;+nl&quot;</span><span class="p">);</span>

  <span class="n">printf</span><span class="p">(</span><span class="s">&quot;Again from C we will call ring code</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
  <span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;for x = 1 to 10 see x + nl next&quot;</span><span class="p">);</span>

  <span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">pState2</span><span class="p">,</span><span class="s">&quot;for x = 1 to 5 see x + nl next&quot;</span><span class="p">);</span>

  <span class="n">printf</span><span class="p">(</span><span class="s">&quot;Now we will display the x variable value from ring code</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
  <span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;see &#39;x value : &#39; + x + nl &quot;</span><span class="p">);</span>
  <span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">pState2</span><span class="p">,</span><span class="s">&quot;see &#39;x value : &#39; + x + nl &quot;</span><span class="p">);</span>

  <span class="n">pList</span> <span class="o">=</span> <span class="n">ring_state_findvar</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;x&quot;</span><span class="p">);</span>

  <span class="n">printf</span><span class="p">(</span><span class="s">&quot;Printing Ring variable value from C , %.0f</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span>
                <span class="n">ring_list_getdouble</span><span class="p">(</span><span class="n">pList</span><span class="p">,</span><span class="n">RING_VAR_VALUE</span><span class="p">));</span>

  <span class="n">printf</span><span class="p">(</span><span class="s">&quot;now we will set the ring variable value from C</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
  <span class="n">ring_list_setdouble</span><span class="p">(</span><span class="n">pList</span><span class="p">,</span><span class="n">RING_VAR_VALUE</span><span class="p">,</span><span class="mi">20</span><span class="p">);</span>

  <span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;see &#39;x value after update : &#39; + x + nl &quot;</span><span class="p">);</span>

  <span class="n">pList</span> <span class="o">=</span> <span class="n">ring_state_newvar</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;v1&quot;</span><span class="p">);</span>
  <span class="n">ring_list_setdouble</span><span class="p">(</span><span class="n">pList</span><span class="p">,</span><span class="n">RING_VAR_VALUE</span><span class="p">,</span><span class="mi">10</span><span class="p">);</span>

  <span class="n">pList</span> <span class="o">=</span> <span class="n">ring_state_newvar</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;v2&quot;</span><span class="p">);</span>
  <span class="n">ring_list_setdouble</span><span class="p">(</span><span class="n">pList</span><span class="p">,</span><span class="n">RING_VAR_VALUE</span><span class="p">,</span><span class="mi">20</span><span class="p">);</span>

  <span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;see &#39;v1 + v2 = &#39; see v1+v2 see nl&quot;</span><span class="p">);</span>

  <span class="n">ring_state_runcode</span><span class="p">(</span><span class="n">pState</span><span class="p">,</span><span class="s">&quot;see &#39;end of test&#39; + nl&quot;</span><span class="p">);</span>

  <span class="n">ring_state_delete</span><span class="p">(</span><span class="n">pState</span><span class="p">);</span>
  <span class="n">ring_state_delete</span><span class="p">(</span><span class="n">pState2</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Output:</p>
<div class="highlight-none"><div class="highlight"><pre>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
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Embedding Ring Interpreter in C/C++ Programs</a><ul>
<li><a class="reference internal" href="#ring-state">Ring State</a></li>
<li><a class="reference internal" href="#ring-state-functions">Ring State Functions</a></li>
<li><a class="reference internal" href="#ring-state-variables">Ring State Variables</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="extension.html"
                        title="previous chapter">Extension using the C/C++ languages</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="interpreter.html"
                        title="next chapter">Command Line Options</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/embedding.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="interpreter.html" title="Command Line Options"
             >next</a> |</li>
        <li class="right" >
          <a href="extension.html" title="Extension using the C/C++ languages"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Ring 1.0 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &copy; Copyright 2016, Mahmoud Samir Fayed.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.1.
    </div>
  </body>
</html>