Controlling Text Input and Output

This section describes text and character input and output commands.

Table 4-20 lists commands to control text input.

Table 4-20 Controlling Text Input

Command	Stack Diagram	Description
( ccc )	( -- )	Create 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.
accept	( addr len1 -- len2 )	Get a line of edited input from the console input device; store at addr. len1 is the maximum allowed length. len2 is the actual length received.
expect	( addr len -- )	Get and display a line of input from the console; store at addr. (Recommend using accept instead.)
key	( -- char )	Read a character from the console input device.
key?	( -- flag )	True if a key has been typed on the console input device.
parse	( char -- str len )	Parse text from the input buffer delimited by char.
parse-word	( -- str len )	Skip leading spaces and parse text from the input buffer delimited by white space.
word	( char -- pstr )	Collect a string delimited by char from the input buffer and place it as a packed string in memory at pstr. (Recommend using parse instead.)

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 whether the user has recently typed 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-21 lists general-purpose text display commands.

Table 4-21 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/linefeed sequence to the console output device. 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-22 shows commands used to manipulate text strings.

Table 4-22 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.
." ccc"		Display the string ccc .
.( ccc)	( -- )	Display the string ccc 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 )	Store the string addr,len as a packed string at pstr.
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 immediately when it is encountered by the interpreter. 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 

---

When " is used outside a colon definition, only two interpreted strings of up to 80 characters each can be assembled concurrently. This limitation does not apply in colon definitions.