document GOSUB/ENDPROC behaviour when loops are unterminated

Author: braindigitalis

docpages/basic-language-reference/keywords/ENDPROC.md

@@ -42,6 +42,14 @@ PROCprint_if_positive(0)
 - Using `ENDPROC` outside a procedure is an error.
 - Functions (`DEF FNname`) do **not** use `ENDPROC`; a function returns with a final line that **begins with `=`**.
 
+##### Loop scope
+
+Loops (`FOR`, `WHILE`, `REPEAT`) are scoped to the current procedure.
+
+Any active loops created inside a `PROC` are discarded when `ENDPROC` is reached unless they have already been exited normally.
+
+If execution continues and a loop-closing statement is encountered with no matching loop, a runtime error is raised (e.g. `NEXT without FOR`).
+
 **See also:**  
 \ref DEF "DEF" ·
 \ref PROC "PROC" ·

docpages/basic-language-reference/keywords/GOTO.md

@@ -40,6 +40,23 @@ Transfers control unconditionally to the line with the given **constant line num
 
 ---
 
+##### Control-flow behaviour
+
+`GOTO` performs a direct jump and does **not** unwind or restore any control structures.
+
+This means you may jump:
+
+* out of a loop (`FOR`, `WHILE`, `REPEAT`)
+* into the body of a loop
+* out of a `GOSUB` or `PROC`
+
+Retro Rocket BASIC does not crash in these cases, but the program may later raise a runtime error if
+control structures no longer match the current execution state (for example, `NEXT without FOR` or `RETURN without GOSUB`).
+
+This behaviour is defined.
+
+---
+
 ##### Notes
 - Jumping to a non-existent line raises a runtime error.
 - Heavy use of `GOTO` quickly reduces readability; use it only for compatibility with legacy code.

docpages/basic-language-reference/keywords/RETURN.md

@@ -26,7 +26,7 @@ Execution resumes at the **statement after** the `GOSUB` call.
 
 ---
 
-### Examples (line numbers permitted)
+### Examples
 
 **Simple subroutine**
 ```basic
@@ -60,6 +60,19 @@ Execution resumes at the **statement after** the `GOSUB` call.
 10 RETURN
 ```
 
+Here’s a concise section matching your style:
+
+### Loop scope
+
+Loops (`FOR`, `WHILE`, `REPEAT`) are scoped to the current `GOSUB`.
+
+Any active loops created inside a `GOSUB` are discarded when `RETURN` is executed unless they have already been exited normally.
+
+If execution continues and a loop-closing statement is encountered with no matching loop, a runtime error is raised (e.g. `NEXT without FOR`).
+
+This differs from BBC BASIC, where loops created inside a `GOSUB` could leak into the caller and corrupt the loop stack.
+
+
 ---
 
 ### See also

docs/ANIMATE.html

@@ -125,7 +125,7 @@ <h3 class="doxsection"><a class="anchor" id="example"></a>
 <div class="line">    FLIP</div>
 <div class="line">    SLEEP 66</div>
 <div class="line">    ANIMATE NEXT bad_apple</div>
-<div class="line">UNTIL INKEY$ &lt;&gt; &quot;&quot;</div>
+<div class="line">UNTIL INKEY$(&quot;&quot;) &lt;&gt; &quot;&quot;</div>
 <div class="line"> </div>
 <div class="line">AUTOFLIP TRUE</div>
 <div class="line">CLS</div>

docs/ASC.html

@@ -106,7 +106,7 @@ <h3 class="doxsection"><a class="anchor" id="examples-2"></a>
 <div class="line">PRINT ASC(C$)</div>
 </div><!-- fragment --><p>This example produces <span class="tt">82</span>, the ASCII code for <span class="tt">"R"</span>.</p>
 <div class="fragment"><div class="line">REM Using ASC to check a keypress</div>
-<div class="line">key$ = INKEY$</div>
+<div class="line">key$ = INKEY$(&quot;&quot;)</div>
 <div class="line">IF key$ &gt; &quot;&quot; THEN</div>
 <div class="line">    code = ASC(key$)</div>
 <div class="line">    PRINT &quot;You pressed: &quot;; code</div>

docs/ENDPROC.html

@@ -127,6 +127,11 @@ <h5 class="doxsection"><a class="anchor" id="rules--behaviour-1"></a>
 <li>Using <span class="tt">ENDPROC</span> outside a procedure is an error.</li>
 <li>Functions (<span class="tt">DEF FNname</span>) do <b>not</b> use <span class="tt">ENDPROC</span>; a function returns with a final line that <b>begins with <span class="tt">=</span></b>.</li>
 </ul>
+<h5 class="doxsection"><a class="anchor" id="loop-scope"></a>
+Loop scope</h5>
+<p>Loops (<span class="tt">FOR</span>, <span class="tt">WHILE</span>, <span class="tt">REPEAT</span>) are scoped to the current procedure.</p>
+<p>Any active loops created inside a <span class="tt">PROC</span> are discarded when <span class="tt">ENDPROC</span> is reached unless they have already been exited normally.</p>
+<p>If execution continues and a loop-closing statement is encountered with no matching loop, a runtime error is raised (e.g. <span class="tt">NEXT without FOR</span>).</p>
 <p><b>See also:</b> <br  />
  <a class="el" href="DEF.html">DEF</a> · <a class="el" href="PROC.html">PROC</a> · <a class="el" href="FN.html">FN</a> </p>
 </div></div><!-- contents -->

docs/GOTO.html

@@ -127,6 +127,18 @@ <h5 class="doxsection"><a class="anchor" id="examples-133"></a>
 <div class="line">40 IF I &lt;= 5 THEN GOTO 20</div>
 <div class="line">50 PRINT &quot;Done&quot;</div>
 </div><!-- fragment --><hr  />
+<h5 class="doxsection"><a class="anchor" id="control-flow-behaviour"></a>
+Control-flow behaviour</h5>
+<p><span class="tt">GOTO</span> performs a direct jump and does <b>not</b> unwind or restore any control structures.</p>
+<p>This means you may jump:</p>
+<ul>
+<li>out of a loop (<span class="tt">FOR</span>, <span class="tt">WHILE</span>, <span class="tt">REPEAT</span>)</li>
+<li>into the body of a loop</li>
+<li>out of a <span class="tt">GOSUB</span> or <span class="tt">PROC</span></li>
+</ul>
+<p>Retro Rocket BASIC does not crash in these cases, but the program may later raise a runtime error if control structures no longer match the current execution state (for example, <span class="tt">NEXT without FOR</span> or <span class="tt">RETURN without GOSUB</span>).</p>
+<p>This behaviour is defined.</p>
+<hr  />
 <h5 class="doxsection"><a class="anchor" id="notes-144"></a>
 Notes</h5>
 <ul>

docs/INKEY.html

@@ -95,16 +95,20 @@
   <div class="headertitle"><div class="title">INKEY$ Function </div></div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><div class="fragment"><div class="line">A$= INKEY$</div>
-</div><!-- fragment --><p>Returns the <b>key that has been pressed</b> as a string. If no key has been pressed since the last call, it returns an <b>empty string</b>.</p>
-<p><span class="tt">INKEY$</span> consumes input from the <b>keyboard buffer</b>. If multiple keys have been pressed between this call and the last call to <span class="tt">INKEY$</span> (or an <span class="tt">INPUT</span> statement), it will take multiple calls to retrieve them all.</p>
+<div class="textblock"><div class="fragment"><div class="line">A$= INKEY$(STRING)</div>
+</div><!-- fragment --><p>INKEY$ checks for key state on the keyboard. It has two modes of operation:</p>
+<ul>
+<li>If the string parameter passed is an empty string, it will check if any key is waiting in the keyboard buffer, consuming it from the buffer and returning it, or returning an empty string if no key is available.</li>
+<li>If the string parameter passed in is a non-empty single-character string, it will check if that key is currently held, and will not consume it from the buffer. Because this form of the function is not consuming from the buffer you may use this form to concurrently check for multiple depressed keys at the same time. Note that you must still drain the buffer. Use a separate INKEY$("") call to drain any pending key presses so the buffer does not fill. <b>US-ASCII values (A-Z) are considered case-insensitive</b> in the parameter when using this form of <span class="tt">INKEY$</span>.</li>
+<li>When <span class="tt">INKEY$</span> consumes input from the <b>keyboard buffer</b> by using an empty parameter, if multiple keys have been pressed between this call and the last call to <span class="tt">INKEY$</span> (or an <span class="tt">INPUT</span> statement), it will take multiple calls to retrieve them all.</li>
+</ul>
 <hr  />
 <h3 class="doxsection"><a class="anchor" id="extended-keys"></a>
 Extended keys</h3>
 <p>Some non-printing keys return special character codes rather than ASCII. These values can be retrieved by wrapping <span class="tt">INKEY$</span> with <span class="tt">ASC()</span>.</p>
 <table class="markdownTable">
 <tr class="markdownTableHead">
-<th class="markdownTableHeadNone">Key  </th><th class="markdownTableHeadNone"><span class="tt">ASC(INKEY$)</span> value  </th></tr>
+<th class="markdownTableHeadNone">Key  </th><th class="markdownTableHeadNone"><span class="tt">ASC(INKEY$(""))</span> value  </th></tr>
 <tr class="markdownTableRowOdd">
 <td class="markdownTableBodyNone">PAGEUP  </td><td class="markdownTableBodyNone">245  </td></tr>
 <tr class="markdownTableRowEven">
@@ -132,23 +136,29 @@ <h3 class="doxsection"><a class="anchor" id="examples-100"></a>
 <div class="fragment"><div class="line">REM Wait for a keypress</div>
 <div class="line">PRINT &quot;Press a key...&quot;</div>
 <div class="line">REPEAT</div>
-<div class="line">    k$ = INKEY$</div>
+<div class="line">    k$ = INKEY$(&quot;&quot;)</div>
 <div class="line">UNTIL k$ &gt; &quot;&quot;</div>
 <div class="line">PRINT &quot;You pressed: &quot;; k$</div>
 </div><!-- fragment --><div class="fragment"><div class="line">REM Handle arrow keys</div>
-<div class="line">k$ = INKEY$</div>
+<div class="line">k$ = INKEY$(&quot;&quot;)</div>
 <div class="line">IF k$ &gt; &quot;&quot; THEN</div>
 <div class="line">    code = ASC(k$)</div>
 <div class="line">    IF code = 250 THEN PRINT &quot;Up arrow pressed&quot;</div>
 <div class="line">    IF code = 251 THEN PRINT &quot;Down arrow pressed&quot;</div>
 <div class="line">ENDIF</div>
+</div><!-- fragment --><div class="fragment"><div class="line">REM multiple key example</div>
+<div class="line">PRINT &quot;Press both A and Z together to exit&quot;</div>
+<div class="line">REPEAT</div>
+<div class="line">UNTIL INKEY$(&quot;A&quot;) &lt;&gt; &quot;&quot; AND INKEY$(&quot;Z&quot;) &lt;&gt; &quot;&quot;</div>
+<div class="line">END</div>
 </div><!-- fragment --><hr  />
 <h3 class="doxsection"><a class="anchor" id="notes-99"></a>
 Notes</h3>
 <ul>
 <li>Printable characters return their usual ASCII values (e.g. <span class="tt">"A"</span> → 65).</li>
 <li>Extended keys must be checked via <span class="tt">ASC()</span>.</li>
-<li>If no key is pressed, result is <span class="tt">""</span> (empty string).</li>
+<li>If no key is pressed, the result is <span class="tt">""</span> (empty string).</li>
+<li>If the parameter to <span class="tt">INKEY$</span> contains more than one character, any characters except the first are ignored.</li>
 </ul>
 <hr  />
 <p><b>See also:</b> <a class="el" href="ASC.html">ASC</a> · <a class="el" href="INPUT.html">INPUT</a> </p>

docs/REPEAT.html

@@ -138,7 +138,7 @@ <h3 class="doxsection"><a class="anchor" id="examples-161"></a>
 </div><!-- fragment --><p><b>Loop until a key is pressed</b> </p><div class="fragment"><div class="line">PRINT &quot;Press any key to stop.&quot;</div>
 <div class="line">REPEAT</div>
 <div class="line">    REM do some periodic work here</div>
-<div class="line">UNTIL INKEY$ &lt;&gt; &quot;&quot;</div>
+<div class="line">UNTIL INKEY$(&quot;&quot;) &lt;&gt; &quot;&quot;</div>
 </div><!-- fragment --><hr  />
 <h3 class="doxsection"><a class="anchor" id="notes-166"></a>
 Notes</h3>

docs/RETURN.html

@@ -117,8 +117,8 @@ <h3 class="doxsection"><a class="anchor" id="behaviour-6"></a>
 </li>
 </ul>
 <hr  />
-<h3 class="doxsection"><a class="anchor" id="examples-line-numbers-permitted"></a>
-Examples (line numbers permitted)</h3>
+<h3 class="doxsection"><a class="anchor" id="examples-162"></a>
+Examples</h3>
 <p><b>Simple subroutine</b> </p><div class="fragment"><div class="line">10 PRINT &quot;Start&quot;</div>
 <div class="line">20 GOSUB 1000</div>
 <div class="line">30 PRINT &quot;Back in main code&quot;</div>
@@ -139,7 +139,14 @@ <h3 class="doxsection"><a class="anchor" id="examples-line-numbers-permitted"></
 <div class="line">2000 PRINT &quot;Second level&quot;</div>
 <div class="line">2010 RETURN</div>
 </div><!-- fragment --><p><b>Error: RETURN without GOSUB (do not do this)</b> </p><div class="fragment"><div class="line">10 RETURN</div>
-</div><!-- fragment --><hr  />
+</div><!-- fragment --><p>Here’s a concise section matching your style:</p>
+<h3 class="doxsection"><a class="anchor" id="loop-scope-1"></a>
+Loop scope</h3>
+<p>Loops (<span class="tt">FOR</span>, <span class="tt">WHILE</span>, <span class="tt">REPEAT</span>) are scoped to the current <span class="tt">GOSUB</span>.</p>
+<p>Any active loops created inside a <span class="tt">GOSUB</span> are discarded when <span class="tt">RETURN</span> is executed unless they have already been exited normally.</p>
+<p>If execution continues and a loop-closing statement is encountered with no matching loop, a runtime error is raised (e.g. <span class="tt">NEXT without FOR</span>).</p>
+<p>This differs from BBC BASIC, where loops created inside a <span class="tt">GOSUB</span> could leak into the caller and corrupt the loop stack.</p>
+<hr  />
 <h3 class="doxsection"><a class="anchor" id="see-also-4"></a>
 See also</h3>
 <ul>