rishi/scryer-prolog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #1709 from triska/pio_doc

Browse Source 
DOC: convert library(pio) documentation to DocLog format
This commit is contained in:
Mark Thom
2023-01-26 02:02:47 +01:00
committed by GitHub
parent 409287e8f8 b04d845ec0
commit e7cf70936a
1 changed files with 36 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
src/lib/pio.pl
View File

@@ -1,13 +1,11 @@
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - /** Pure I/O.
Pure I/O
========
Our goal is to encourage the use of definite clause grammars (DCGs) Our goal is to encourage the use of definite clause grammars (DCGs)
for describing strings. The predicates phrase_from_file/[2,3], for describing strings. The predicates `phrase_from_file/[2,3]`,
phrase_to_file/[2,3] and phrase_to_stream/2 let us apply DCGs `phrase_to_file/[2,3]` and `phrase_to_stream/2` let us apply DCGs
transparently to files and streams, and therefore decouple side-effects transparently to files and streams, and therefore decouple side-effects
from declarative descriptions. from declarative descriptions.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */ */
:- module(pio, [phrase_from_file/2, :- module(pio, [phrase_from_file/2,
phrase_from_file/3, phrase_from_file/3,
@@ -29,16 +27,18 @@
:- meta_predicate(phrase_to_file(2, ?, ?)). :- meta_predicate(phrase_to_file(2, ?, ?)).
:- meta_predicate(phrase_to_stream(2, ?)). :- meta_predicate(phrase_to_stream(2, ?)).
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %% phrase_from_file(+GRBody, +File)
phrase_from_file(GRBody, File) %
% True if grammar rule body GRBody covers the contents of File,
True if grammar rule body GRBody covers the contents of File, % represented as a list of characters.
represented as a list of characters.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
phrase_from_file(NT, File) :- phrase_from_file(NT, File) :-
phrase_from_file(NT, File, []). phrase_from_file(NT, File, []).
%% phrase_from_file(+GRBody, +File, +Options)
%
% Like `phrase_from_file/2`, using Options to open the file.
phrase_from_file(NT, File, Options) :- phrase_from_file(NT, File, Options) :-
( var(File) -> instantiation_error(phrase_from_file/3) ( var(File) -> instantiation_error(phrase_from_file/3)
; must_be(list, Options), ; must_be(list, Options),
@@ -68,23 +68,22 @@ reader_step(Stream, Pos, Xs0) :-
stream_to_lazy_list(Stream, Xs) stream_to_lazy_list(Stream, Xs)
). ).
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %% phrase_to_stream(+GRBody, +Stream)
phrase_to_stream(+GRBody, +Stream) %
% Emit the list of characters described by the grammar rule body
Emit the list of characters described by the grammar rule body % GRBody to Stream.
GRBody to Stream. %
% An ideal implementation of `phrase_to_stream/2` writes each
An ideal implementation of phrase_to_stream/2 writes each character % character as soon as it becomes known and no choice-points remain,
as soon as it becomes known and no choice-points remain, and thus % and thus avoids the manifestation of the entire string in memory.
avoids the manifestation of the entire string in memory. See #691 % See [#691](https://github.com/mthom/scryer-prolog/issues/691) for
for more information. % more information.
%
The current preliminary implementation is provided so that Prolog % The current preliminary implementation is provided so that Prolog
programmers can already get used to describing output with DCGs, % programmers can already get used to describing output with DCGs,
and then writing it to a file when necessary. This simple % and then writing it to a file when necessary. This simple
implementation suffices as long as the entire contents can be % implementation suffices as long as the entire contents can be
represented in memory, and thus covers a large number of use cases. % represented in memory, and thus covers a large number of use cases.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
phrase_to_stream(GRBody, Stream) :- phrase_to_stream(GRBody, Stream) :-
phrase(GRBody, Cs), phrase(GRBody, Cs),
@@ -101,14 +100,18 @@ phrase_to_stream(GRBody, Stream) :-
% maplist(put_char(Stream), Cs). It also works for binary streams. % maplist(put_char(Stream), Cs). It also works for binary streams.
'$put_chars'(Stream, Cs). '$put_chars'(Stream, Cs).
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %% phrase_to_file(+GRBody, +File)
phrase_to_file(+GRBody, +File), writing the string described %
by GRBody to File. % Write the string described by GRBody to File.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
phrase_to_file(GRBody, File) :- phrase_to_file(GRBody, File) :-
phrase_to_file(GRBody, File, []). phrase_to_file(GRBody, File, []).
%% phrase_to_file(+GRBody, +File, +Options)
%
% Like `phrase_to_file/2`, using Options to open the file.
phrase_to_file(GRBody, File, Options) :- phrase_to_file(GRBody, File, Options) :-
setup_call_cleanup(open(File, write, Stream, Options), setup_call_cleanup(open(File, write, Stream, Options),
phrase_to_stream(GRBody, Stream), phrase_to_stream(GRBody, Stream),