Difference between revisions of "GSINIT"

From BeebWiki
Jump to: navigation, search
(define missing closing ")
m (Specification)
 
(14 intermediate revisions by 2 users not shown)
Line 6: Line 6:
 
|  6502  || align="left" | '''On entry:''' || align="left" | '''On exit:'''
 
|  6502  || align="left" | '''On entry:''' || align="left" | '''On exit:'''
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| Z || align="left" | undefined || align="left" | 0=String is non-empty or quoted<br>1=String is empty and unquoted
+
| Cy || align="left" | CC = Space or CR terminates unquoted string&nbsp;&nbsp;<br>CS = CR terminates unquoted string || align="left" | undefined
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| C || align="left" | 0=String terminates at second <tt>"</tt>, otherwise at first CR or space<br>1=String terminates at second <tt>"</tt">, otherwise at first CR || align="left" | undefined
+
| Z || align="left" | undefined || align="left" | NE = String present<br>EQ = No string, end of line
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| A || align="left" | undefined || align="left" | First character of string; =&0D if string empty and unquoted
+
| A || align="left" | undefined || align="left" | Opening character of string;<br>&0D if no string present, end of line
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| Y || align="left" | Offset to start scan || align="left" | Offset of first character of string
+
| X || align="left" | undefined || align="left" | preserved
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| ?&F2 || align="left" | LSB of start of array || align="left" | preserved
+
| Y || align="left" | Offset of first character to scan || align="left" | Offset of first character of string
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| ?&F3 || align="left" | MSB of start of array || align="left" | preserved
+
| (&F2),Y&nbsp;&nbsp; || align="left" | Points to start of string || align="left" | (&F2) preserved, Y updated
 
|}
 
|}
  
Prepares [[GSREAD]] to read a string from a character array. The string may be enclosed in double quotes (<tt>"</tt>) in which case spaces in the string are preserved. The string may also contain control codes and high-order characters encoded with an escape sequence.
+
Prepares [[GSREAD]] to read a string from a character array. The string may
 +
be enclosed in double quotes (<tt>"</tt>) in which case spaces in the string
 +
are preserved. The string may also contain control codes and high-order
 +
characters encoded with an escape sequence.
  
GSINIT starts at the position given by (?&F2,?&F3)+Y and scans forward, incrementing Y until a character other than space or [[VDU 13|CR]] is found.  
+
GSINIT starts at the position given by (&F2),Y and scans forward, skipping
 +
leading spaces.
  
If the string begins with <tt>"</tt> then &22 is returned in A and (?&F2,?&F3)+Y points to the character after the <tt>"</tt>. The carry flag input to GSINIT has no effect; GSREAD will return characters until the closing <tt>"</tt> is reached. CR encountered before the closing <tt>"</tt> causes error &FD, '''Bad string'''.
+
If the string begins with <tt>"</tt> then &22 is returned in A and
 +
(&F2),Y points to the character after the <tt>"</tt>. In this case the
 +
Carry flag input to GSINIT has no effect, GSREAD will return characters
 +
until the closing <tt>"</tt> is reached. A CR encountered before the closing
 +
<tt>"</tt> causes error &FD, '''Bad string'''.
  
Otherwise (?&F2,?&F3)+Y points to the first non-space character, which is returned in A. Z is set if this is CR, indicating an empty, unquoted string. GSINIT will return characters until CR or space (if C=0 to GSINIT), or CR only (if C=1 to GSINIT) is reached.
+
Otherwise (&F2),Y points to the first non-space character, which is
 +
returned in A. The Zero flag returns EQ if this is CR, indicating an empty,
 +
unquoted string. GSREAD will return characters until CR is reached, or also
 +
space if GSINIT was called with Carry Clear.
  
It is safe to call GSREAD at least once following GSINIT.
+
While processing a command line, the Zero flag set to NE on exit from GSINIT
 +
indicates that an argument is present. GSINIT returning EQ is distinct from
 +
the first call to GSREAD returning CS which indicates a null string, not an
 +
absent string.
 +
 
 +
It is safe to call GSREAD at least once following GSINIT. However, after
 +
GSREAD returns Carry Set it must not be called again without an intervening
 +
GSINIT; otherwise, overshooting a closing <tt>"</tt> and reaching CR also
 +
raises a '''Bad string''' error.
  
 
;Note
 
;Note
The character returned by GSINIT is ''not'' necessarily the character returned by the first call to [[GSREAD]].
+
The character returned by GSINIT is ''not'' necessarily the character
 +
returned by the first call to [[GSREAD]].
 +
 
 +
==Examples==
 +
The following examples should make the CLC/SEC entry options clearer. In each case it shows
 +
where the string is terminated indicated with a | character.
 +
 
 +
===CLC on entry===
 +
* some| words
 +
* alongstringofwords|
 +
* &quot;some words&quot;| and more words
 +
* some&quot;words| and&quot; more words
 +
 
 +
This is <code>*LOAD</code> filename style parsing.
 +
 
 +
===SEC on entry===
 +
* some words|
 +
* alongstringofwords|
 +
* &quot;some words&quot;| and more words
 +
* some&quot;words and&quot; more words|
 +
 
 +
This is <code>*KEY</code> style parsing.
 +
 
 +
==Workspace==
 +
GSINIT modifies GSFLAG in location &E4, a zero page location also used while
 +
processing numerical *commands (<code>*FX</code>, <code>*OPT</code>,
 +
<code>*TV</code> ''etc.'')  The value on exit is used by subsequent GSREAD
 +
calls, and is made up as follows:
  
==Calling from BBC BASIC==
+
{| class="wikitable"
 +
! Bit !! Meaning
 +
|-
 +
| 7 || <tt>"</tt> found at start of string
 +
|-
 +
| 6 || CS on entry; only CR terminates unquoted string
 +
|-
 +
| 5..0 || Unused; bits 7..2 of previous value
 +
|}
  
 
==Entry points==
 
==Entry points==
 
* 6502 Entry Address: &FFC2 (I/O processor only)
 
* 6502 Entry Address: &FFC2 (I/O processor only)
  
[[User:Regregex|Regregex]] ([[User talk:Regregex|talk]]) 17:53, 11 January 2019 (CET)
+
[[User:Regregex|Regregex]] ([[User talk:Regregex|talk]]) 17:42, 18 August 2021 (CEST)

Latest revision as of 21:51, 7 September 2021

Initialize to read a string

Specification

 6502  On entry: On exit:
Cy CC = Space or CR terminates unquoted string  
CS = CR terminates unquoted string
undefined
Z undefined NE = String present
EQ = No string, end of line
A undefined Opening character of string;
&0D if no string present, end of line
X undefined preserved
Y Offset of first character to scan Offset of first character of string
(&F2),Y   Points to start of string (&F2) preserved, Y updated

Prepares GSREAD to read a string from a character array. The string may be enclosed in double quotes (") in which case spaces in the string are preserved. The string may also contain control codes and high-order characters encoded with an escape sequence.

GSINIT starts at the position given by (&F2),Y and scans forward, skipping leading spaces.

If the string begins with " then &22 is returned in A and (&F2),Y points to the character after the ". In this case the Carry flag input to GSINIT has no effect, GSREAD will return characters until the closing " is reached. A CR encountered before the closing " causes error &FD, Bad string.

Otherwise (&F2),Y points to the first non-space character, which is returned in A. The Zero flag returns EQ if this is CR, indicating an empty, unquoted string. GSREAD will return characters until CR is reached, or also space if GSINIT was called with Carry Clear.

While processing a command line, the Zero flag set to NE on exit from GSINIT indicates that an argument is present. GSINIT returning EQ is distinct from the first call to GSREAD returning CS which indicates a null string, not an absent string.

It is safe to call GSREAD at least once following GSINIT. However, after GSREAD returns Carry Set it must not be called again without an intervening GSINIT; otherwise, overshooting a closing " and reaching CR also raises a Bad string error.

Note

The character returned by GSINIT is not necessarily the character returned by the first call to GSREAD.

Examples

The following examples should make the CLC/SEC entry options clearer. In each case it shows where the string is terminated indicated with a | character.

CLC on entry

  • some| words
  • alongstringofwords|
  • "some words"| and more words
  • some"words| and" more words

This is *LOAD filename style parsing.

SEC on entry

  • some words|
  • alongstringofwords|
  • "some words"| and more words
  • some"words and" more words|

This is *KEY style parsing.

Workspace

GSINIT modifies GSFLAG in location &E4, a zero page location also used while processing numerical *commands (*FX, *OPT, *TV etc.) The value on exit is used by subsequent GSREAD calls, and is made up as follows:

Bit Meaning
7 " found at start of string
6 CS on entry; only CR terminates unquoted string
5..0 Unused; bits 7..2 of previous value

Entry points

  • 6502 Entry Address: &FFC2 (I/O processor only)

Regregex (talk) 17:42, 18 August 2021 (CEST)