From: Markus Triska <triska@metalevel.at>
Date: Mon, 8 Nov 2021 20:48:50 +0000 (+0100)
Subject: add motivation and comments about library(pio) predicates
X-Git-Tag: v0.9.0~30^2~2
X-Git-Url: https://git.sagredo.dev/?a=commitdiff_plain;h=0677f517173409d1cd09235f6f92b24789b77d11;p=scryer-prolog.git

add motivation and comments about library(pio) predicates
---

diff --git a/src/lib/pio.pl b/src/lib/pio.pl
index 25a2cba8..18ceaab5 100644
--- a/src/lib/pio.pl
+++ b/src/lib/pio.pl
@@ -1,3 +1,14 @@
+/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+   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 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,
                 phrase_to_file/2,
@@ -16,6 +27,13 @@
 :- 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(NT, File) :-
     phrase_from_file(NT, File, []).