This library provides pure list-based I/O processing for Prolog, where the communication to the actual I/O device is performed transparently through coroutining. This module itself is just an interface to the actual implementation modules.

author

- Ulrich Neumerkel

- Jan Wielemaker

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

 phrase_from_file(:Grammar, +File) is nondet

 phrase_from_file(:Grammar, +File, +Options) is nondet

Process the content of File using the DCG rule Grammar. The space usage of this mechanism depends on the length of the not committed part of Grammar. Committed parts of the temporary list are reclaimed by the garbage collector, while the list is extended on demand due to unification of the attributed tail variable.

Options are passed to open/4 and phrase_from_stream/3. The latter notable allows for as(chars) to call a DCG compiled for dealing with character lists rather than codes.

Below is an example that counts the number of times a string appears in a file. The library dcg/basics provides string//1 matching an arbitrary string and remainder//1 which matches the remainder of the input without parsing.

:- use_module(library(dcg/basics)).

file_contains(File, Pattern) :-
        phrase_from_file(match(Pattern), File).

match(Pattern) -->
        string(_),
        string(Pattern),
        remainder(_).

match_count(File, Pattern, Count) :-
        aggregate_all(count, file_contains(File, Pattern), Count).

This can be called as (note that the pattern must be a string (code list)):

?- match_count('pure_input.pl', `file`, Count).

 phrase_from_file(:Grammar, +File) is nondet

 phrase_from_file(:Grammar, +File, +Options) is nondet

Process the content of File using the DCG rule Grammar. The space usage of this mechanism depends on the length of the not committed part of Grammar. Committed parts of the temporary list are reclaimed by the garbage collector, while the list is extended on demand due to unification of the attributed tail variable.

Options are passed to open/4 and phrase_from_stream/3. The latter notable allows for as(chars) to call a DCG compiled for dealing with character lists rather than codes.

Below is an example that counts the number of times a string appears in a file. The library dcg/basics provides string//1 matching an arbitrary string and remainder//1 which matches the remainder of the input without parsing.

:- use_module(library(dcg/basics)).

file_contains(File, Pattern) :-
        phrase_from_file(match(Pattern), File).

match(Pattern) -->
        string(_),
        string(Pattern),
        remainder(_).

match_count(File, Pattern, Count) :-
        aggregate_all(count, file_contains(File, Pattern), Count).

This can be called as (note that the pattern must be a string (code list)):

?- match_count('pure_input.pl', `file`, Count).

 phrase_from_stream(:Grammar, +Stream)

 phrase_from_stream(:Grammar, +Stream, +Options)

Run Grammer against the character codes on Stream. Stream must be buffered. Options:

as(Type)

Where Type is one of codes (default) or chars. See also stream_to_lazy_codes/2 and stream_to_lazy_chars/2.

 phrase_from_stream(:Grammar, +Stream)

 phrase_from_stream(:Grammar, +Stream, +Options)

Run Grammer against the character codes on Stream. Stream must be buffered. Options:

as(Type)

Where Type is one of codes (default) or chars. See also stream_to_lazy_codes/2 and stream_to_lazy_chars/2.

 stream_to_lazy_codes(+Stream, -List) is det

 stream_to_lazy_chars(+Stream, -List) is det

 stream_to_lazy_list(+Stream, -List) is det

Create a lazy list representing the character codes (chars) in Stream. List is a partial list ending in an attributed variable. Unifying this variable reads the next block of data. The block is stored with the attribute value such that there is no need to re-read it.

deprecated

- stream_to_lazy_list/2 is a backward compatibility alias for stream_to_lazy_codes/2.

Compatibility

- Unlike the previous version of this predicate this version does not require a repositionable stream. It does require a buffer size of at least the maximum number of bytes of a multi-byte sequence (6).

 stream_to_lazy_codes(+Stream, -List) is det

 stream_to_lazy_chars(+Stream, -List) is det

 stream_to_lazy_list(+Stream, -List) is det

Create a lazy list representing the character codes (chars) in Stream. List is a partial list ending in an attributed variable. Unifying this variable reads the next block of data. The block is stored with the attribute value such that there is no need to re-read it.

deprecated

- stream_to_lazy_list/2 is a backward compatibility alias for stream_to_lazy_codes/2.

Compatibility

- Unlike the previous version of this predicate this version does not require a repositionable stream. It does require a buffer size of at least the maximum number of bytes of a multi-byte sequence (6).

 stream_to_lazy_codes(+Stream, -List) is det

 stream_to_lazy_chars(+Stream, -List) is det

 stream_to_lazy_list(+Stream, -List) is det

Create a lazy list representing the character codes (chars) in Stream. List is a partial list ending in an attributed variable. Unifying this variable reads the next block of data. The block is stored with the attribute value such that there is no need to re-read it.

deprecated

- stream_to_lazy_list/2 is a backward compatibility alias for stream_to_lazy_codes/2.

Compatibility

- Unlike the previous version of this predicate this version does not require a repositionable stream. It does require a buffer size of at least the maximum number of bytes of a multi-byte sequence (6).

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 syntax_error(Arg1, Arg2, Arg3)

 lazy_list_location(Arg1, Arg2, Arg3)

 lazy_list_character_count(Arg1, Arg2, Arg3)