Read line

Purpose: Read text file line by line in a loop.

 read-line <file> to <line content> [ status <status> ] [ delimiter <delimiter> ]

 <any code>

 end-read-line

read-line starts the loop in which a text <file> is read line by line into string <line content>, with end-read-line ending this loop. Once the end of <file> has been reached, or an error occurs, the loop exits.

<file> can be a full path name, or a path relative to the application home directory (see directories).

<status> number will be GG_ERR_READ if there is an error in reading file, or GG_ERR_OPEN if file cannot be opened, or GG_OKAY if end-of-file has been reached. Check for error after end-read-line statement. If a line was read successfully, then <status> is its length.

<line content> is allocated when a line is read and freed just before the next line is read or if there are no more lines to read. If you want to use <line content> outside of this scope, save it or stash it somewhere first.

String <delimiter> separates the lines in the file, and is by default new line, however it can be any character (note that it is a first character of string <delimiter>).

A new line (or a <delimiter>) remains in <line content> if it was present in the file (note that the very last line may not have it).

Use break-loop and continue-loop statements to exit and continue the loop.

Examples

To read a text file line by line, and display as a web page with line breaks:

 read-line "/home/bear/tmp/ll/filexx" to one_line status st
     string-length one_line to line_len
     @Line length is <<p-num line_len>>, line is <<p-web one_line>> status <<p-num st>><br/>
 end-read-line
 if-true st lesser-than 0
     get-req error to err
     @Error in reading, error [<<p-out err>>]
 end-if

To read a text file delimited by "|" character:

 read-line "/home/user/dir/file" to one_line status len delimiter '|'
 ...