From b04d845ec05b1b8b402cf61ab8df13a3d1cec742 Mon Sep 17 00:00:00 2001 From: Markus Triska Date: Thu, 26 Jan 2023 00:09:41 +0100 Subject: [PATCH] DOC: convert library(pio) documentation to DocLog format --- src/lib/pio.pl | 69 ++++++++++++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 33 deletions(-) diff --git a/src/lib/pio.pl b/src/lib/pio.pl index 42f641db..fdc5bcb1 100644 --- a/src/lib/pio.pl +++ b/src/lib/pio.pl @@ -1,13 +1,11 @@ -/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pure I/O - ======== +/** Pure I/O. Our goal is to encourage the use of definite clause grammars (DCGs) - for describing strings. The predicates phrase_from_file/[2,3], - phrase_to_file/[2,3] and phrase_to_stream/2 let us apply DCGs + for describing strings. The predicates `phrase_from_file/[2,3]`, + `phrase_to_file/[2,3]` and `phrase_to_stream/2` let us apply DCGs transparently to files and streams, and therefore decouple side-effects from declarative descriptions. -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */ +*/ :- module(pio, [phrase_from_file/2, phrase_from_file/3, @@ -29,16 +27,18 @@ :- meta_predicate(phrase_to_file(2, ?, ?)). :- meta_predicate(phrase_to_stream(2, ?)). -/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - phrase_from_file(GRBody, File) - - True if grammar rule body GRBody covers the contents of File, - represented as a list of characters. -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */ +%% phrase_from_file(+GRBody, +File) +% +% True if grammar rule body GRBody covers the contents of File, +% represented as a list of characters. 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) :- ( var(File) -> instantiation_error(phrase_from_file/3) ; must_be(list, Options), @@ -68,23 +68,22 @@ reader_step(Stream, Pos, Xs0) :- stream_to_lazy_list(Stream, Xs) ). -/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - phrase_to_stream(+GRBody, +Stream) - - Emit the list of characters described by the grammar rule body - GRBody to Stream. - - An ideal implementation of phrase_to_stream/2 writes each character - as soon as it becomes known and no choice-points remain, and thus - avoids the manifestation of the entire string in memory. See #691 - for more information. - - The current preliminary implementation is provided so that Prolog - programmers can already get used to describing output with DCGs, - and then writing it to a file when necessary. This simple - implementation suffices as long as the entire contents can be - represented in memory, and thus covers a large number of use cases. -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */ +%% phrase_to_stream(+GRBody, +Stream) +% +% Emit the list of characters described by the grammar rule body +% GRBody to Stream. +% +% An ideal implementation of `phrase_to_stream/2` writes each +% character as soon as it becomes known and no choice-points remain, +% and thus avoids the manifestation of the entire string in memory. +% See [#691](https://github.com/mthom/scryer-prolog/issues/691) for +% more information. +% +% The current preliminary implementation is provided so that Prolog +% programmers can already get used to describing output with DCGs, +% and then writing it to a file when necessary. This simple +% implementation suffices as long as the entire contents can be +% represented in memory, and thus covers a large number of use cases. phrase_to_stream(GRBody, Stream) :- phrase(GRBody, Cs), @@ -101,14 +100,18 @@ phrase_to_stream(GRBody, Stream) :- % maplist(put_char(Stream), Cs). It also works for binary streams. '$put_chars'(Stream, Cs). -/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - phrase_to_file(+GRBody, +File), writing the string described - by GRBody to File. -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */ +%% phrase_to_file(+GRBody, +File) +% +% Write the string described by GRBody to 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) :- setup_call_cleanup(open(File, write, Stream, Options), phrase_to_stream(GRBody, Stream), -- 2.54.0