Difference between revisions of "GSREAD"

From BeebWiki
Jump to: navigation, search
(created)
m (Updated returned flags.)
(10 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"
| C || align="left" | undefined || align="left" | 0=Character valid<br>1=End of string reached
+
| A || align="left" | undefined || align="left" | Current character of string, terminating character if end of string
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| ?&F2 || align="left" | LSB of start of array || align="left" | preserved
+
| X || align="left" | undefined || align="left" | preserved
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| ?&F3 || align="left" | MSB of start of array || align="left" | preserved
+
| Y || align="left" | Offset of current character&nbsp;&nbsp; || align="left" | Offset of next character
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| A || align="left" | undefined || align="left" | Next character of string; =&0D if end of string reached
+
| (&F2),Y || align="left" | the string being parsed || align="left" | (&F2) preserved
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| Y || align="left" | Offset of current character || align="left" | Offset of next character
+
| Cy || align="left" | undefined || align="left" | CC = Character valid<br>&nbsp;&nbsp;VS = 7-bit control character, (A AND &7F)&lt;&20<br>&nbsp;&nbsp;VC = not 7-bit control character, (A AND &7F)&gt;&1F<br>&nbsp;&nbsp;PL/MI set from A: PL if A&lt;&80, MI if A&gt;&7F<br>&nbsp;&nbsp;EQ/NE set from A: EQ if A=0, NE if A&lt;&gt;0<br>CS = End of string reached<br>&nbsp;&nbsp;EQ = end of line<br>&nbsp;&nbsp;NE = not end of line, more text on line
 
|}
 
|}
  
Returns a character from a string found using [[GSINIT]]. 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.
+
Returns one character at a time from a string found using [[GSINIT]]. 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.
  
GSREAD parses the character sequence at the position given by (?&F2,?&F3)+Y and scans forward.
+
GSREAD parses the character sequence at the position given by (&F2),Y
 +
and scans forward.
  
If the string began with <tt>"</tt> then a character is returned unless the closing <tt>"</tt> is reached; then C=1 and A=&0D is returned. [[VDU 13|CR]] encountered before the closing <tt>"</tt> causes error &FD, '''Bad string'''.
+
If the string began with <tt>"</tt> then a character is returned with
 +
Carry Clear unless the closing <tt>"</tt> has been reached, then Carry Set
 +
is returned with A=&0D. [[VDU 13|CR]] encountered before the closing
 +
<tt>&quot;</tt> causes error &FD, '''Bad string'''.
  
Otherwise a character is returned unless CR or space (if C=0 to GSINIT), or CR only (if C=1 to GSINIT) is reached; then C=1 and A=&0D.
+
Otherwise a character is returned with Carry Clear unless it is a CR, or
 +
a space if GSINIT was called with Carry Clear, then Carry Set is returned
 +
with A=&0D.
  
(?&F2,?&F3)+Y points to the next character unless C=1, in which case GSREAD skips any spaces following the end of the string.
+
(&F2),Y is left pointing to the next character unless Carry Set is returned,
 +
in which case GSREAD skips any spaces following the end of the string.
 +
 
 +
While processing a command line, GSINIT returning Not Equal indicates that an
 +
argument is present. When the first call to GSREAD returns Carry Set, the flag
 +
from GSINIT distinguishes between an empty argument and no argument.
 +
 
 +
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==
 +
  \ Testing for no string present at all:
 +
  JSR GSINIT
 +
  BEQ errNoString
 +
 
 +
  \ Testing for null string:
 +
  JSR GSINIT
 +
  JSR GSREAD
 +
  BCS nullstring
 +
 
 +
  \ Stepping past a string (eg to step past a filename to following parameters):
 +
  JSR GSINIT
 +
  .loop
 +
  JSR GSREAD
 +
  BCC loop
 +
  \ Y now points to any parameter after the string
 +
 
 +
  \ Copying a string
 +
  JSR GSINIT
 +
  LDX #0
 +
  .loop
 +
  JSR GSREAD:BCS done
 +
  STA buffer,X
 +
  INX:BNE loop
 +
  .done
 +
  \ X=length of string parsed
 +
  \ Y=updated to parse another parameter, if present
 +
 
 +
==Workspace==
 +
GSREAD tests the top two bits of GSFLAG in location &E4, a zero page location set up
 +
by GSINIT but also modified while processing numerical *commands
 +
(<code>*FX</code>, <code>*OPT</code>, <code>*TV</code> ''etc.'')  The value
 +
is preserved during the call, and is made up as follows:
 +
 
 +
{| class="wikitable"
 +
! Bit !! Meaning
 +
|-
 +
| 7 || <tt>"</tt> found at start of string
 +
|-
 +
| 6 || CS on entry to GSINIT; only CR terminates unquoted string
 +
|-
 +
| 5..0 || Unused
 +
|}
  
==Calling from BBC BASIC==
+
GSREAD also updates GSCHAR in location &E5, clearing or setting bit seven to process the |! sequence.
  
 
==Entry points==
 
==Entry points==
 
* 6502 Entry Address: &FFC5 (I/O processor only)
 
* 6502 Entry Address: &FFC5 (I/O processor only)
  
[[User:Regregex|Regregex]] ([[User talk:Regregex|talk]]) 18:31, 11 January 2019 (CET)
+
[[User:Regregex|Regregex]] ([[User talk:Regregex|talk]]) 17:48, 18 August 2021 (CEST)

Revision as of 21:43, 7 September 2021

Read character from string

Specification

 6502  On entry: On exit:
A undefined Current character of string, terminating character if end of string
X undefined preserved
Y Offset of current character   Offset of next character
(&F2),Y the string being parsed (&F2) preserved
Cy undefined CC = Character valid
  VS = 7-bit control character, (A AND &7F)<&20
  VC = not 7-bit control character, (A AND &7F)>&1F
  PL/MI set from A: PL if A<&80, MI if A>&7F
  EQ/NE set from A: EQ if A=0, NE if A<>0
CS = End of string reached
  EQ = end of line
  NE = not end of line, more text on line

Returns one character at a time from a string found using GSINIT. 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.

GSREAD parses the character sequence at the position given by (&F2),Y and scans forward.

If the string began with " then a character is returned with Carry Clear unless the closing " has been reached, then Carry Set is returned with A=&0D. CR encountered before the closing " causes error &FD, Bad string.

Otherwise a character is returned with Carry Clear unless it is a CR, or a space if GSINIT was called with Carry Clear, then Carry Set is returned with A=&0D.

(&F2),Y is left pointing to the next character unless Carry Set is returned, in which case GSREAD skips any spaces following the end of the string.

While processing a command line, GSINIT returning Not Equal indicates that an argument is present. When the first call to GSREAD returns Carry Set, the flag from GSINIT distinguishes between an empty argument and no argument.

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

 \ Testing for no string present at all:
 JSR GSINIT
 BEQ errNoString
 \ Testing for null string:
 JSR GSINIT
 JSR GSREAD
 BCS nullstring
 \ Stepping past a string (eg to step past a filename to following parameters):
 JSR GSINIT
 .loop
 JSR GSREAD
 BCC loop
 \ Y now points to any parameter after the string
 \ Copying a string
 JSR GSINIT
 LDX #0
 .loop
 JSR GSREAD:BCS done
 STA buffer,X
 INX:BNE loop
 .done
 \ X=length of string parsed
 \ Y=updated to parse another parameter, if present

Workspace

GSREAD tests the top two bits of GSFLAG in location &E4, a zero page location set up by GSINIT but also modified while processing numerical *commands (*FX, *OPT, *TV etc.) The value is preserved during the call, and is made up as follows:

Bit Meaning
7 " found at start of string
6 CS on entry to GSINIT; only CR terminates unquoted string
5..0 Unused

GSREAD also updates GSCHAR in location &E5, clearing or setting bit seven to process the |! sequence.

Entry points

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

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