summaryrefslogtreecommitdiff
path: root/doc/api
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2015-01-18 22:48:15 -0500
committerDavid Thompson <dthompson2@worcester.edu>2015-01-18 22:48:15 -0500
commit1139ed32756fd18a59f072c3ae5e0dcfc67bf16d (patch)
tree1ec36ec7e7a5af050c12c30a6a45a26c7574f8e6 /doc/api
parent3320c39a743c66b5b5e33d8b2c8b1823e3f71dd1 (diff)
doc: Document utility modules.
* doc/api/utils.texi: Document the REPL, live-reload, and utils modules.
Diffstat (limited to 'doc/api')
-rw-r--r--doc/api/utils.texi81
1 files changed, 81 insertions, 0 deletions
diff --git a/doc/api/utils.texi b/doc/api/utils.texi
index e75dd47..308daee 100644
--- a/doc/api/utils.texi
+++ b/doc/api/utils.texi
@@ -14,6 +14,27 @@
(use-modules (sly utils repl))
@end example
+The Sly REPL is a cooperative REPL server that is integrated into the
+game loop. It is the key to live coding games with Sly. To connect
+to the REPL server, use the @uref{http://www.nongnu.org/geiser/,
+Geiser} extension for GNU Emacs.
+
+@deffn {Scheme Procedure} start-sly-repl [@var{port}]
+Start a cooperative REPL server that listens on the given @code{port}.
+By default, this port is 37146. Additionally, a process is scheduled
+to poll the REPL server upon every tick of the game loop.
+@end deffn
+
+The Sly REPL detects when the game loop throws an error and enters a
+special loop for debugging. When in this state, game state will not
+be updated or rendered. When the errors have been fixed, calling the
+@code{resume-game-loop} procedure will hand control back to the game
+loop.
+
+@deffn {Scheme Procedure} resume-game-loop
+Abort from the error handling loop prompt and resume the game loop.
+@end deffn
+
@node Live Reloading
@subsection Live Reloading
@@ -21,9 +42,69 @@
(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.
+
+@defun 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
+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
+
@node Miscellaneous-Utilities
@subsection Miscellaneous
@example
(use-modules (sly utils))
@end example
+
+Miscellaneous helpful procedures.
+
+@deffn {Scheme Syntax} define-guardian @var{name} @var{reaper}
+Define a new guardian called @code{name} and call @code{reaper} when
+an object within the guardian is GC'd. Reaping is ensured to happen
+from the same thread that is running the game loop.
+@end deffn
+
+@deffn memoize @var{proc}
+Return a memoizing version of @code{proc}.
+@end deffn
+
+@deffn {Scheme Syntax} forever @var{body} @dots{}
+Evaluate @code{body} in an unbounded loop. Useful in coroutines that
+have no end.
+@end deffn
+
+@deffn {Scheme Syntax} trampoline @var{proc-name}
+Create a new procedure that applies the procedure bound to
+@code{proc-name} with all given arguments.
+@end deffn
+
+@deffn {Scheme Syntax} chain* @var{args} (@var{proc} @dots{}) . @var{rest}
+Handy macro for flattening nested procedure calls where the output of
+an inner call is the last argument to the outer call.
+
+@example
+(chain* (list '(1 2) '(3 4))
+ (map +)
+ (fold + 0)) ;; => 10
+@end example
+
+@end deffn
+
+@deffn {Scheme Syntax} chain @var{arg} (@var{proc} @dots{}) . @var{rest}
+Like @code{chain*} but for a single argument.
+
+@example
+(chain '(1 2 3 4)
+ (map 1+)
+ (fold + 0)) ;; => 14
+@end example
+
+@end deffn