## A.21 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 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)
  Diference-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 readine a block of lines upto 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.