A.28 library(readutil): Reading lines, streams and files

This library contains primitives to read lines, files, multiple terms, etc. The package clib provides a shared object (DLL) named readutil. If the library can locate this shared object it will use the foreign implementation for reading character codes. Otherwise it will use a Prolog implementation. Distributed applications should make sure to deliver the readutil shared object if performance of these predicates is critical.

read_line_to_codes(+Stream, -Codes)

Read the next line of input from Stream and unify the result with Codes after the line has been read. A line is ended by a newline character or end-of-file. Unlike read_line_to_codes/3, this predicate removes a trailing newline character.

On end-of-file the atom end_of_file is returned. See also at_end_of_stream/[0,1].

read_line_to_codes(+Stream, -Codes, ?Tail)

Difference-list version to read an input line to a list of character codes. Reading stops at the newline or end-of-file character, but unlike read_line_to_codes/2, the newline is retained in the output. This predicate is especially useful for reading a block of lines up to some delimiter. The following example reads an HTTP header ended by a blank line:

read_header_data(Stream, Header) :-
        read_line_to_codes(Stream, Header, Tail),
        read_header_data(Header, Stream, Tail).

read_header_data("\r\n", _, _) :- !.
read_header_data("\n", _, _) :- !.
read_header_data("", _, _) :- !.
read_header_data(_, Stream, Tail) :-
        read_line_to_codes(Stream, Tail, NewTail),
        read_header_data(Tail, Stream, NewTail).

read_stream_to_codes(+Stream, -Codes)

Read all input until end-of-file and unify the result to Codes.

read_stream_to_codes(+Stream, -Codes, ?Tail)

Difference-list version of read_stream_to_codes/2.

read_file_to_codes(+Spec, -Codes, +Options)

Read a file to a list of character codes. Spec is a file specification for absolute_file_name/3. Codes is the resulting code list. Options is a list of options for absolute_file_name/3 and open/4. In addition, the option tail(Tail) is defined, forming a difference-list.

read_file_to_terms(+Spec, -Terms, +Options)

Read a file to a list of Prolog terms (see read/1). Spec is a file specification for absolute_file_name/3. Terms is the resulting list of Prolog terms. Options is a list of options for absolute_file_name/3 and open/4. In addition, the option tail(Tail) is defined, forming a difference-list.