From: Markus Triska <triska@metalevel.at>
Date: Wed, 25 Jan 2023 22:54:30 +0000 (+0100)
Subject: DOC: add documentation for library(freeze) in DocLog format
X-Git-Tag: v0.9.2~210^2
X-Git-Url: https://git.sagredo.dev/?a=commitdiff_plain;h=a8ea2b0f9735a853b50efc7e657ee364555fc7e0;p=scryer-prolog.git

DOC: add documentation for library(freeze) in DocLog format
---

diff --git a/src/lib/freeze.pl b/src/lib/freeze.pl
index b9f8005d..c6554fa4 100644
--- a/src/lib/freeze.pl
+++ b/src/lib/freeze.pl
@@ -1,5 +1,8 @@
 :- module(freeze, [freeze/2]).
 
+/** Provides the constraint `freeze/2`.
+*/
+
 :- use_module(library(atts)).
 :- use_module(library(dcgs)).
 
@@ -19,6 +22,15 @@ verify_attributes(Var, Other, Goals) :-
         ).
 verify_attributes(_, _, []).
 
+%% freeze(Var, Goal)
+%
+%  Schedules Goal to be executed when Var is instantiated. This can
+%  be useful to observe the exact moment a variable becomes bound to a
+%  more concrete term, for example when creating animations of search
+%  processes. Higher-level constructs such as `phrase_from_file/2` can
+%  also be implemented with `freeze/2`, by scheduling a goal that
+%  reads additional data from a file as soon as it is needed.
+
 freeze(X, Goal) :-
     put_atts(Fresh, frozen(Goal)),
     Fresh = X.