Controlling Text Input and Output

This section describes text input and output commands. These commands control strings or character arrays, and allow you to enter comments and control keyboard scanning.

Table 4-12 lists commands to control text input.

Table 4-12 Controlling Text Input

Command	Stack Diagram	Description
( ccc )	( -- )	Begin a comment. Conventionally used for stack diagrams.
\ rest-of-line	( -- )	Treat the rest of the line as a comment.
ascii ccc	( -- char )	Get numerical value of first ASCII character of next word.
expect	( addr +n -- )	Get a line of edited input from the assigned input device's keyboard; store at addr.
key	( -- char )	Read a character from the assigned input device's keyboard.
key?	( -- flag )	True if a key has been typed on the input device's keyboard.
span	( -- waddr )	Variable containing the number of characters read by expect.
word	( char -- pstr )	Collect a string delimited by char from input string and place in memory at pstr.

Comments are used with Forth source code (generally in a text file) to describe the function of the code. The ( (open parenthesis) is the Forth word that begins a comment. Any character up to the closing parenthesis ) is ignored by the Forth interpreter. Stack diagrams are one example of comments using (.

---

Note -

Remember to follow the( with a space, so that it is recognized as a Forth word.

---

\ (backslash) indicates a comment terminated by the end of the line of text.

key waits for a key to be pressed, then returns the ASCII value of that key on the stack.

ascii, used in the form ascii x, returns on the stack the numerical code of the character x.

key? looks at the keyboard to see if the user has recently pressed any key. It returns a flag on the stack: true if a key has been pressed and false otherwise. See "Conditional Flags" for a discussion on the use of flags.

Table 4-13 lists general-purpose text display commands.

Table 4-13 Displaying Text Output

Command	Stack Diagram	Description
." ccc"	( -- )	Compile a string for later display.
(cr	( -- )	Move the output cursor back to the beginning of the current line.
cr	( -- )	Terminate a line on the display and go to the next line.
emit	( char -- )	Display the character.
exit?	( -- flag )	Enable the scrolling control prompt: More [<space>,<cr>,q] ? The return flag is true if the user wants the output to be terminated.
space	( -- )	Display a space character.
spaces	( +n -- )	Display +n spaces.
type	( addr +n -- )	Display the +n characters beginning at addr.

cr sends a carriage-return character to the output. For example:

---

ok 3 . 44 . cr 5 .
3 44
5
ok 

---

emit displays the letter whose ASCII value is on the stack.

---

ok ascii a 
61 ok 42
61 42 ok emit emit
Ba
ok 

---

Table 4-14 shows commands used to manipulate text strings.

Table 4-14 Manipulating Text Strings

Command	Stack Diagram	Description
",	( addr len -- )	Compile an array of bytes from addr of length len, at the top of the dictionary as a packed string.
" ccc"	( -- addr len )	Collect an input stream string, either interpreted or compiled. Within the string, "(00,ff) can be used to include arbitrary byte values.
.( ccc)	( -- )	Display a string immediately.
-trailing	( addr +n1 -- addr +n2 )	Remove trailing spaces.
bl	( -- char )	ASCII code for the space character; decimal 32.
count	( pstr -- addr +n )	Unpack a packed string.
lcc	( char -- lowercase-char )	Convert a character to lowercase.
left-parse-string	( addr len char -- addrR lenR addrL lenL )	Split a string at char (which is discarded).
pack	( addr len pstr -- pstr )	Make a packed string from addr len; place it at pstr.
"p" ccc	( -- pstr )	Collect a string from the input stream; store as a packed string.
upc	( char -- uppercase-char )	Convert a character to uppercase.

Some string commands specify an address (the location in memory where the characters reside) and a length (the number of characters in the string). Other commands use a packed string or pstr, which is a location in memory containing a byte for the length, immediately followed by the characters. The stack diagram for the command indicates which form is used. For example, count converts a packed string to an address-length string.

The command ." is used in the form: ." string". It outputs text when needed. A " (double quotation mark) marks the end of the text string. For example:

---

ok  : testing 34 .  ." This is a test"  55 . ;
ok
ok testing
34 This is a test55
ok 

---