Skip to content

Commit cdab307

Browse files
braindigitalisbraindigitalis
committed
add support for multi line EVAL
1 parent 4037b28 commit cdab307

117 files changed

Lines changed: 450 additions & 303 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docpages/basic-language-reference/keywords/EVAL.md‎

Lines changed: 35 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
\page EVAL EVAL Keyword
22
```basic
33
EVAL string-expression
4-
```
4+
````
5+
6+
Executes BASIC code supplied in `string-expression`.
57
6-
Executes a **single complete line of BASIC** supplied in `string-expression` in the **current program's context**.
8+
* If the string contains a **single line**, it is executed in the **current program's context**.
9+
* If the string contains **multiple lines**, it is executed as an **anonymous child program** in a new process context.
710
8-
- The string must form **one valid statement line** (for example `PRINT "Hello"`, `X = 10`, `PROCdemo`).
9-
- On **error**, `ERR$` is set to the error message and `ERR` is set to `1`. Execution then continues at the statement after `EVAL`.
10-
- **Recursive EVAL is not permitted** (code running under `EVAL` may not call `EVAL` again).
11+
On **error**, `ERR$` is set to the error message and `ERR` is set to `1`. Execution then continues at the statement after `EVAL`.
1112
13+
* Recursive **single-line EVAL** is not permitted.
1214
1315
\remark If you need a literal double quote inside the evaluated line, insert it using `CHR$(34)`.
1416
\remark For example: `EVAL "PRINT " + CHR$(34) + "Hello" + CHR$(34)`.
@@ -17,19 +19,22 @@ Executes a **single complete line of BASIC** supplied in `string-expression` in
1719
1820
### Examples
1921
20-
**Print from a generated line**
22+
**Print from a generated line (single-line)**
23+
2124
```basic
2225
EVAL "PRINT " + CHR$(34) + "Hello from EVAL!" + CHR$(34)
2326
```
2427

2528
**Set a variable dynamically**
29+
2630
```basic
2731
NAME$ = "COUNT"
2832
EVAL NAME$ + " = 42"
2933
PRINT COUNT
3034
```
3135

3236
**Call a procedure**
37+
3338
```basic
3439
DEF PROCgreet
3540
PRINT "Greetings"
@@ -38,7 +43,23 @@ ENDPROC
3843
EVAL "PROCgreet"
3944
```
4045

46+
**Multi-line anonymous program**
47+
48+
```basic
49+
EVAL "A=1" + CHR$(10) + "PRINT A"
50+
```
51+
52+
**Using GLOBAL variables in multi-line EVAL**
53+
54+
```basic
55+
GLOBAL A
56+
A = 5
57+
58+
EVAL "PRINT A"
59+
```
60+
4161
**Error handling (ERR/ERR$ set, program continues)**
62+
4263
```basic
4364
ERR = 0
4465
ERR$ = ""
@@ -53,9 +74,13 @@ ENDIF
5374
---
5475

5576
### Notes
56-
- Provide **exactly one** statement; statement separators are not supported.
57-
- The evaluated line runs with access to the program's current variables, procedures, and functions.
58-
- Use `EVAL` for small, dynamic actions. For larger logic, write normal procedures/functions and call them directly.
77+
78+
* A **single-line** EVAL executes in the current context and has access to all variables, procedures, and functions.
79+
* A **multi-line** EVAL runs as an anonymous child program.
80+
* Anonymous child programs inherit `GLOBAL` variables from the parent.
81+
* Single-line EVAL executes via a temporary injected line; therefore, recursive single-line EVAL is not permitted.
82+
* Provide **exactly one statement** when using single-line EVAL; statement separators are not supported.
83+
* Use EVAL for dynamic or generated code. For larger logic, prefer normal procedures or separate programs.
5984

6085
**See also:**
61-
\ref DEF "DEF", \ref PROC "PROC", \ref FN "FN", [`ERR`/`ERR$`](https://github.com/brainboxdotcc/retro-rocket/wiki/Builtin-Variables)
86+
\ref DEF "DEF", \ref PROC "PROC", \ref FN "FN", `ERR`, `ERR$`

‎docs/EVAL.html‎

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -96,44 +96,47 @@
9696
</div><!--header-->
9797
<div class="contents">
9898
<div class="textblock"><div class="fragment"><div class="line">EVAL string-expression</div>
99-
</div><!-- fragment --><p>Executes a <b>single complete line of BASIC</b> supplied in <span class="tt">string-expression</span> in the <b>current program's context</b>.</p>
100-
<ul>
101-
<li>The string must form <b>one valid statement line</b> (for example <span class="tt">PRINT "Hello"</span>, <span class="tt">X = 10</span>, <span class="tt">PROCdemo</span>).</li>
102-
<li>On <b>error</b>, <span class="tt">ERR$</span> is set to the error message and <span class="tt">ERR</span> is set to <span class="tt">1</span>. Execution then continues at the statement after <span class="tt">EVAL</span>.</li>
103-
<li><b>Recursive EVAL is not permitted</b> (code running under <span class="tt">EVAL</span> may not call <span class="tt">EVAL</span> again).</li>
104-
</ul>
105-
<dl class="section remark"><dt>Remarks</dt><dd>If you need a literal double quote inside the evaluated line, insert it using <span class="tt">CHR$(34)</span>. </dd>
106-
<dd>
107-
For example: <span class="tt">EVAL "PRINT " + CHR$(34) + "Hello" + CHR$(34)</span>.</dd></dl>
108-
<hr />
109-
<h3 class="doxsection"><a class="anchor" id="examples-128"></a>
110-
Examples</h3>
111-
<p><b>Print from a generated line</b> </p><div class="fragment"><div class="line">EVAL &quot;PRINT &quot; + CHR$(34) + &quot;Hello from EVAL!&quot; + CHR$(34)</div>
112-
</div><!-- fragment --><p><b>Set a variable dynamically</b> </p><div class="fragment"><div class="line">NAME$ = &quot;COUNT&quot;</div>
113-
<div class="line">EVAL NAME$ + &quot; = 42&quot;</div>
114-
<div class="line">PRINT COUNT</div>
115-
</div><!-- fragment --><p><b>Call a procedure</b> </p><div class="fragment"><div class="line">DEF PROCgreet</div>
116-
<div class="line"> PRINT &quot;Greetings&quot;</div>
117-
<div class="line">ENDPROC</div>
99+
<div class="line">````</div>
100+
<div class="line"> </div>
101+
<div class="line">Executes BASIC code supplied in `string-expression`.</div>
102+
<div class="line"> </div>
103+
<div class="line">* If the string contains a **single line**, it is executed in the **current program&#39;s context**.</div>
104+
<div class="line">* If the string contains **multiple lines**, it is executed as an **anonymous child program** in a new process context.</div>
118105
<div class="line"> </div>
119-
<div class="line">EVAL &quot;PROCgreet&quot;</div>
120-
</div><!-- fragment --><p><b>Error handling (ERR/ERR$ set, program continues)</b> </p><div class="fragment"><div class="line">ERR = 0</div>
121-
<div class="line">ERR$ = &quot;&quot;</div>
106+
<div class="line">On **error**, `ERR$` is set to the error message and `ERR` is set to `1`. Execution then continues at the statement after `EVAL`.</div>
122107
<div class="line"> </div>
123-
<div class="line">EVAL &quot;A = 1/0&quot;</div>
108+
<div class="line">* Recursive **single-line EVAL** is not permitted.</div>
124109
<div class="line"> </div>
125-
<div class="line">IF ERR &lt;&gt; 0 THEN</div>
126-
<div class="line"> PRINT &quot;EVAL failed: &quot;; ERR$</div>
127-
<div class="line">ENDIF</div>
128-
</div><!-- fragment --><hr />
110+
<div class="line">\remark If you need a literal double quote inside the evaluated line, insert it using `CHR$(34)`.</div>
111+
<div class="line">\remark For example: `EVAL &quot;PRINT &quot; + CHR$(34) + &quot;Hello&quot; + CHR$(34)`.</div>
112+
<div class="line"> </div>
113+
<div class="line">---</div>
114+
<div class="line"> </div>
115+
<div class="line">### Examples</div>
116+
<div class="line"> </div>
117+
<div class="line">**Print from a generated line (single-line)**</div>
118+
</div><!-- fragment --><p> basic EVAL "PRINT " + CHR$(34) + "Hello from EVAL!" + CHR$(34) </p><div class="fragment"><div class="line">**Set a variable dynamically**</div>
119+
</div><!-- fragment --><p> basic NAME$ = "COUNT" EVAL NAME$ + " = 42" PRINT COUNT </p><div class="fragment"><div class="line">**Call a procedure**</div>
120+
</div><!-- fragment --><p> basic DEF PROCgreet PRINT "Greetings" ENDPROC</p>
121+
<p>EVAL "PROCgreet" </p><div class="fragment"><div class="line">**Multi-line anonymous program**</div>
122+
</div><!-- fragment --><p> basic EVAL "A=1" + CHR$(10) + "PRINT A" </p><div class="fragment"><div class="line">**Using GLOBAL variables in multi-line EVAL**</div>
123+
</div><!-- fragment --><p> basic GLOBAL A A = 5</p>
124+
<p>EVAL "PRINT A" </p><div class="fragment"><div class="line">**Error handling (ERR/ERR$ set, program continues)**</div>
125+
</div><!-- fragment --><p> basic ERR = 0 ERR$ = ""</p>
126+
<p>EVAL "A = 1/0"</p>
127+
<p>IF ERR &lt;&gt; 0 THEN PRINT "EVAL failed: "; ERR$ ENDIF ```</p>
128+
<hr />
129129
<h3 class="doxsection"><a class="anchor" id="notes-139"></a>
130130
Notes</h3>
131131
<ul>
132-
<li>Provide <b>exactly one</b> statement; statement separators are not supported.</li>
133-
<li>The evaluated line runs with access to the program's current variables, procedures, and functions.</li>
134-
<li>Use <span class="tt">EVAL</span> for small, dynamic actions. For larger logic, write normal procedures/functions and call them directly.</li>
132+
<li>A <b>single-line</b> EVAL executes in the current context and has access to all variables, procedures, and functions.</li>
133+
<li>A <b>multi-line</b> EVAL runs as an anonymous child program.</li>
134+
<li>Anonymous child programs inherit <span class="tt">GLOBAL</span> variables from the parent.</li>
135+
<li>Single-line EVAL executes via a temporary injected line; therefore, recursive single-line EVAL is not permitted.</li>
136+
<li>Provide <b>exactly one statement</b> when using single-line EVAL; statement separators are not supported.</li>
137+
<li>Use EVAL for dynamic or generated code. For larger logic, prefer normal procedures or separate programs.</li>
135138
</ul>
136-
<p><b>See also:</b> <a class="el" href="DEF.html">DEF</a>, <a class="el" href="PROC.html">PROC</a>, <a class="el" href="FN.html">FN</a>, <a href="https://github.com/brainboxdotcc/retro-rocket/wiki/Builtin-Variables"><span class="tt">ERR</span>/<span class="tt">ERR$</span></a> </p>
139+
<p><b>See also:</b> <a class="el" href="DEF.html">DEF</a>, <a class="el" href="PROC.html">PROC</a>, <a class="el" href="FN.html">FN</a>, <span class="tt">ERR</span>, <span class="tt">ERR$</span> </p>
137140
</div></div><!-- contents -->
138141
</div><!-- PageDoc -->
139142
</div><!-- doc-content -->

‎docs/FN.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@
109109
<li>A function defined with <span class="tt">DEF FN...</span> returns its value on a line that begins with <span class="tt">=</span> in the definition.</li>
110110
</ul>
111111
<hr />
112-
<h3 class="doxsection"><a class="anchor" id="examples-129"></a>
112+
<h3 class="doxsection"><a class="anchor" id="examples-128"></a>
113113
Examples</h3>
114114
<p>Integer result </p><div class="fragment"><div class="line">DEF FNadd(A, B)</div>
115115
<div class="line">= A + B</div>

‎docs/FOR.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@
106106
<p>Loops may be nested. <span class="tt">NEXT</span> closes the nearest unmatched <span class="tt">FOR</span>.</p>
107107
<dl class="section note"><dt>Note</dt><dd><span class="tt">start</span>, <span class="tt">to</span>, and <span class="tt">step</span> are evaluated once at loop entry. The counter is initialised to <span class="tt">start</span>. The body executes at least once. On <span class="tt">NEXT</span>, the counter is increased by <span class="tt">step</span> and compared to <span class="tt">to</span>. The loop continues while (<span class="tt">step</span> &gt; 0 AND <span class="tt">counter</span> &lt;= <span class="tt">to</span>) or (<span class="tt">step</span> &lt; 0 AND <span class="tt">counter</span> &gt;= <span class="tt">to</span>). If <span class="tt">step</span> evaluates to 0, a runtime error is raised.</dd></dl>
108108
<hr />
109-
<h3 class="doxsection"><a class="anchor" id="examples-130"></a>
109+
<h3 class="doxsection"><a class="anchor" id="examples-129"></a>
110110
Examples</h3>
111111
<p>Count up by 1 </p><div class="fragment"><div class="line">FOR I = 1 TO 5</div>
112112
<div class="line"> PRINT &quot;I = &quot;; I</div>

‎docs/GCOL.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@
103103
</ul>
104104
<dl class="section remark"><dt>Remarks</dt><dd><span class="tt">GCOL</span> affects <b>graphics</b> drawing only. For <b>text</b> colours see <a class="el" href="COLOUR.html">COLOUR</a> and <a class="el" href="BACKGROUND.html">BACKGROUND</a>.</dd></dl>
105105
<hr />
106-
<h3 class="doxsection"><a class="anchor" id="examples-131"></a>
106+
<h3 class="doxsection"><a class="anchor" id="examples-130"></a>
107107
Examples</h3>
108108
<p>Set a graphics colour then draw an outline circle </p><div class="fragment"><div class="line">GCOL RGB(255,0,0)</div>
109109
<div class="line">CIRCLE 200, 150, 80, FALSE</div>

‎docs/GLOBAL.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ <h3 class="doxsection"><a class="anchor" id="behaviour-1"></a>
112112
</li>
113113
</ul>
114114
<hr />
115-
<h3 class="doxsection"><a class="anchor" id="examples-132"></a>
115+
<h3 class="doxsection"><a class="anchor" id="examples-131"></a>
116116
Examples</h3>
117117
<p><b>Pass a string and number to a child</b></p>
118118
<p>Parent program: </p><div class="fragment"><div class="line">GLOBAL USERNAME$ = &quot;guest&quot;</div>

‎docs/GOTO.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@
115115
<li>Jumps may be forward or backward within the <b>same program</b>.</li>
116116
</ul>
117117
<hr />
118-
<h5 class="doxsection"><a class="anchor" id="examples-133"></a>
118+
<h5 class="doxsection"><a class="anchor" id="examples-132"></a>
119119
Examples</h5>
120120
<p><b>Forward jump</b> </p><div class="fragment"><div class="line">10 PRINT &quot;Start&quot;</div>
121121
<div class="line">20 GOTO 100</div>

‎docs/GRAPHPRINT.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ <h3 class="doxsection"><a class="anchor" id="errors-1"></a>
123123
<li>An error occurs if <span class="tt">printable</span> is omitted.</li>
124124
</ul>
125125
<hr />
126-
<h3 class="doxsection"><a class="anchor" id="examples-134"></a>
126+
<h3 class="doxsection"><a class="anchor" id="examples-133"></a>
127127
Examples</h3>
128128
<p><b>Draw a label in magenta</b></p>
129129
<div class="fragment"><div class="line">GCOL &amp;FF00FF</div>

‎docs/INPUT.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@
109109
<dd>
110110
With an <span class="tt">ON ERROR</span> handler, control passes there instead.</dd></dl>
111111
<hr />
112-
<h3 class="doxsection"><a class="anchor" id="examples-135"></a>
112+
<h3 class="doxsection"><a class="anchor" id="examples-134"></a>
113113
Examples</h3>
114114
<p><b>Read a number</b> </p><div class="fragment"><div class="line">PRINT &quot;Enter a number:&quot;</div>
115115
<div class="line">INPUT N</div>

‎docs/LET.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@
104104
<li>name ending with <span class="tt">$</span> -&gt; string</li>
105105
</ul>
106106
<hr />
107-
<h3 class="doxsection"><a class="anchor" id="examples-136"></a>
107+
<h3 class="doxsection"><a class="anchor" id="examples-135"></a>
108108
Examples</h3>
109109
<p>Integer assignment (with and without <span class="tt">LET</span>) </p><div class="fragment"><div class="line">LET N = 10</div>
110110
<div class="line">M = 20</div>

0 commit comments

Comments
 (0)