Version 1 of lgets

Updated 2009-08-13 11:55:03 by LV

This command is part of the TclX package.

lgets fileid ?varname?

Reads the next Tcl list from the given fileid, returning the list or, if varname is given, storing the list in the variable and returning the number of characters read (not including the terminating newline) or -1 in an error case (similar to gets).

Use puts to reverse the operation.

This command differs from the gets command, in that it reads Tcl lists rather than lines. If the list contains newlines or binary data, then the newlines or bytes of zero will be returned as part of the result. Only a newline not quoted as part of the list indicates the end of the list.

If varName is specified, then the line is placed in the variable by that name and the return value is a count of the number of characters read (not including the newline). If the end of the file is reached before reading any characters then -1 is returned and varName is set to an empty string. If varName is specified and an error occurs, what ever data was read will be returned in the variable, however the resulting string may not be a valid list.

If varName is not specified, then the return value will be the list (minus the newline character) or an empty string if the end of the file is reached before reading any characters. An empty string will also be returned if a line contains no characters except the newline, so eof may have to be used to determine what really happened.

The lgets command may be used to read lists containing binary data, however translation must be set to lf or the data may be corrupted.