Line Input

Reads one line of input from the keyboard

Syntax
	Line Input [;] [promptstring {;|,} ] stringvariable1
		or
	Line Input [;] promptstring {;|,} stringvariable2 , maxlength

Parameters
	promptstring
		prompt to display before waiting for input. If it is followed by a 
		semicolon (;), a question mark ("? ") will be appended to the prompt. 
		If it is followed by a comma, nothing will be appended.
	stringvariable1
		variable-length or fixed_length (and known) string, to receive the 
		line of text
	stringvariable2
		dereferenced {z|w}string pointer or {z|w}string variable passed by 
		reference (string buffer size unknown for both), to receive the line 
		of text
	maxlength
		maximum number of characters allowed to be written to the string 
		buffer, including the NULL terminator

Description
	Reads a line of text from the keyboard and stores it in a string 
	variable.

	The promptstring - if any - is written to the screen at the current 
	cursor location, and characters read are echoed to the screen 
	immediately following the prompt. If no prompt is specified, characters 
	are echoed at the current cursor location.

	The optional leading semicolon (;) after Line Input is similar to the 
	optional trailing semicolon in a KeyPgPrintPrint statement: the cursor will remain 
	on the same line after all of the characters have been echoed, 
	otherwise, the cursor will move to the beginning of the next line.

	Line Input has a limited edit capacity: it allows to use the left and 
	right cursor keys to navigate the text, and to erase or insert 
	characters. If a better user interface is needed, a custom input routine 
	should be used.

	Two syntaxes are available:
		* The first syntax is only allowed when the string buffer size 
		  (provided by stringvariable1) is either variable or fixed (and 
		  known). For this first syntax, the promptstring parameter is 
		  optional.
		* The second syntax with maxlength parameter is only allowed when 
		  the string buffer size (provided by stringvariable2) is unknown. 
		  This happens for dereferenced KeyPgZstringZString/KeyPgWstringWString pointers, or KeyPgZstringZString/
		  KeyPgWstringWString variables passed by reference. This can used to truncate 
		  the text line to be read, or avoid overflowing beyond allocated 
		  data of the provided string buffer. For this second syntax, the 
		  promptstring parameter is mandatory even if it is empty (use "").

Example
	Dim s As String
	Line Input "Enter a line"; s
	Print "Full line that you entered:"
	Print "'"; s; "'"
	Print

	Const maxlength = 11  '' max 10 characters plus 1 null terminal character
	Dim pz As ZString Ptr = CAllocate(maxlength, SizeOf(ZString))
	Line Input "Enter a line"; *pz, maxlength
	Print "First " & maxlength - 1 & " characters that you entered:"
	Print "'"; *pz; "'"
	Deallocate(pz)

Version
	* Before fbc 1.10.0, the second syntax (with maxlength parameter) was 
	  not supported.

Differences from QB
	* QBASIC only allowed literal strings for the prompt text.  FreeBASIC 
	  allows any variable or constant string expression.

See also
	* KeyPgLineinputPpLine Input #
	* KeyPgInputInput

