Reimplement live-reload module.

* sly/live-reload.scm (watch-files): New procedure.
  (live-reload): Rename to...
  (with-live-reload): This.
* doc/api/utils.tex ("Live Reloading"): Update docs.

1 files changed, 32 insertions, 6 deletions

diff --git a/doc/api/utils.texi b/doc/api/utils.texi
index 4858010..4c7c39f 100644
--- a/doc/api/utils.texi
+++ b/doc/api/utils.texi
@@ -42,12 +42,38 @@ Abort from the error handling loop prompt and resume the game loop.
 (use-modules (sly utils live-reload))
 @end example
 
-The live-reload module enables Sly programs to react to changes in the
-file system and reload assets automatically, which is useful when
-using external programs such as an image editor or map editor.  This
-makes it easy to see the changes made to game assets quickly.
+The @code{(sly live-reload)} module enables Sly programs to react to
+changes in the file system and reload assets automatically, which is
+useful when using external programs such as an image editor or map
+editor.  Live reloading reduces the time and effort needed to see the
+changes made to game assets.
 
-@defun live-reload @var{proc} [@var{polling-interval}]
+The following example uses the @code{with-live-reload} procedure to
+create a texturing loading procedure that automatically reloads
+textures when their associated file on disk changes:
+
+@example
+(use-modules (sly live-reload)
+             (sly signal)
+             (sly texture))
+
+(define load-texture/live (with-live-reload load-texture))
+
+(define-signal fox (load-texture/live "fox.png"))
+@end example
+
+The more generic @code{watch-files} procedure can be used to implement
+new types of live reloading procedures.
+
+@deffn {Scheme Procedure} watch-files @var{files} @var{thunk} [@var{polling-interval}]
+Watch @var{files}, a list of file names, and apply @var{thunk} each
+time one of them changes.  A signal (@pxref{Signals}) is returned that
+contains the current result of @var{thunk}.  The
+@var{polling-interval} flag determines how often @var{files} are
+polled for changes, defaulting to two seconds.
+@end deffn
+
+@deffn {Scheme Procedure} with-live-reload @var{proc} [@var{polling-interval}]
 Return a new procedure that re-applies @code{proc} whenever the
 associated file is modified.  The new procedure returns a signal
 (@pxref{Signals}) that contains the return value of @code{proc}.  The
@@ -55,7 +81,7 @@ first argument to @code{proc} must be a file name string.
 
 A simple polling method is used to test for updates.  Files are polled
 every @code{polling-interval} ticks (120 by default).
-@end defun
+@end deffn
 
 @node Miscellaneous-Utilities
 @subsection Miscellaneous