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 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 ZString/WString pointers, or ZString/
        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
   * Line Input #
   * Input

