linein()


>>-linein--(--+-----------------------------+--)---------------><
              '-name--+-------------------+-'      
                      '-,start-+--------+-'        
                               '-,count-'

Function

Returns one line or no lines from the stream specified in name, and sets the location for the next read to the beginning of the next line. The data is assumed to be text. The newline character is the line delimiter and is not returned. A null string is returned if no line is returned; this appears the same as a null line in the file. Use chars() or lines() to determine if you are at end of file. Use stream() to determine if there is an error condition on the stream.

Parameters

name: The name for the stream can be a path name or a string that was returned from the stream open or popen commands. If name is omitted, the standard input stream is used.
start: For a persistent stream only, this argument can have the value 1, to begin reading at the beginning of the stream. No other value for start is supported. Do not specify start for other types of streams.
count: Specify 0 or 1 for the number of lines to be returned by the function. If one line is not available in the stream, the function returns a null string and marks an error condition on the stream. For non-persistent streams, this function either blocks until a line is available, or returns as though it is end of file, depending on whether any data remains in the file, on the file open flags, and on the type of file. If count is 0, no lines are read, a null string is returned, and, if start is 1, the read position is set to the beginning of the stream.

Example

To read the next line:

line=linein(file)

To read the first line in the file:

line=linein(file,1)