StdInputLine function

 

Usage:

StringVar$ = StdInputLine

 

Legacy Syntax:

STDIN LINE StringVar$

 

Pseudo-object Syntax:

CON.STDIN.LINE TO StringVar$

 

Reads a text line, terminated by a CR code, from the standard input device.

 

A Ctrl+Z code in the stream terminates all input. No more lines of text can follow a Ctrl+Z. If standard input is redirected to come from a disk file, the physical end-of-file, if encountered before a Ctrl+Z code, has the same effect as a Ctrl+Z code.

 

If no redirection is in effect, standard input is the keyboard. It is expected that StdInputLine will be useful only when input is expected to be redirected (such as in CGI applications), otherwise ConInputLine is a better choice to read line input from the keyboard.

 

If a line of text terminated by a CR (or Ctrl+Z) is immediately available when StdInputLine is called, it is immediately returned. The CR (or Ctrl+Z) code is not included in the returned string. Otherwise, StdInputLine waits for a CR (or Ctrl+Z) code before returning. If there are no significant characters before the CR (or Ctrl+Z) code, a null string is returned.

 

A LF code is not included in the returned string. A Ctrl+H (BS) code is acted upon to delete the last character. The last character and the BS code are excluded from the returned string. A Ctrl+Z code terminates input. The Ctrl+Z is not included in the returned string. All other control codes are included in the returned string as raw codes. No more characters or codes are added to the return string after a Ctrl+Z is seen.

 

The action on Ctrl+Z, and whether or not the input is echoed, is dependent on whether standard input is redirected or coming from the keyboard.

 

If standard input is redirected (the normal situation), StdInputLine will return immediately when a Ctrl+Z code, or physical end-of-file, is seen. Another call to StdInputLine after EOF has been seen on a previous call will result in immediate return with a null string. Use the StdInEOF function to avoid calling StdInputLine beyond the end-of-file. If standard input is redirected, input is not echoed. Note that EOF does not cancel input redirection. After EOF has been seen, StdInputLine will return no more data during this execution of the program.

 

If standard input is coming from the keyboard, the input is echoed to the active console page. CR is echoed as CR+LF. LF and BS are not echoed (and BS causes the last character to be erased from the echoed line). Ctrl+Z is echoed as "^Z". All other control codes are echoed as printable characters from the OEM character set. After a Ctrl+Z has been seen, StdInputLine will continue to wait for a CR code before echoing the CR as CR+LF and returning. CR is the only character or code recognized by StdInputLine after receipt of a Ctrl+Z. If StdInputLine is called again after the Ctrl+Z has been seen, "^Z" is immediately echoed before waiting for another CR. Nothing else is echoed and a null string is returned. This remains true for the entire remainder of this execution of the program. However, ConInputLine, ConInKey$ and ConWaitKey$ continue to work normally to return keyboard input. If standard output is redirected, standard output does not receive the echoed characters. Echo is specifically to the active console page.

 

Conversion:

 

#IF %DEF(%PB_CC32)

  STDIN LINE StringVar$

#ELSE

  StringVar$ = StdInputLine

#ENDIF

 

CON.STDIN.LINE TO or CONSOLE.STDIN.LINE TO may be substituted for STDIN LINE in programs written for PB/CC 6.  The syntax "StringVar$ = ..." is not listed as an option.

 

See Also: StdInEOF, ConStdIn, ConInputLine