From 0962cfa1a3567218980dd29d3a47234535722894 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Sat, 27 Feb 2016 14:13:15 -0500 Subject: doc: Spruce things up a bit. --- doc/api/time.texi | 61 ++++++++++++++++++++++++++++++++++-------------------- doc/api/utils.texi | 5 ----- doc/sly.texi | 4 +--- 3 files changed, 39 insertions(+), 31 deletions(-) diff --git a/doc/api/time.texi b/doc/api/time.texi index cc637f2..0b74782 100644 --- a/doc/api/time.texi +++ b/doc/api/time.texi @@ -7,14 +7,10 @@ loop. This manual refers to a ``tick'' as the smallest unit of time. There are a user-defined amount of ticks in a real world second, but by default it is 60. -Sly includes several useful modules for working with time. Coroutines -are procedures that can be paused and resumed, agendas are procedure -schedulers, and signals built atop both agendas and coroutines to -provide a high-level functional reactive programming API. - -For most use-cases, the signal module should be used exclusively, but -the agenda and coroutine modules are useful for building new -high-level abstractions. +Sly includes several useful modules for working with time. For nearly +all use-cases, the signal module should be used exclusively, but the +agenda and coroutine modules are useful for building the foundation +for new high-level abstractions. @menu * Signals:: Functional reactive programming. @@ -31,19 +27,29 @@ high-level abstractions. Game state is a function of time. The player's score, the current stage, an enemy's hit points, etc. all change in response to events -that happen at discrete points in time. Typically, this means that a -number of callback procedures are registered to respond to events -which mutate the relevant data structures. However, this approach, -while simple and effective, comes at the price of readability, -reproducibility, and expression. Instead of explicitly mutating data -and entering ``callback hell'', Sly abstracts and formalizes the -process using a functional reactive programming style. +that happen at discrete points in time. In traditional game engines +this means that a number of callback procedures are registered to +respond to events which mutate the relevant data structures to update +the state of the game world. However, this approach, while simple and +effective, comes at the price of readability, reproducibility, and +expression. Callback-heavy code can be very difficult to read because +the control flow is not made obvious by the structure of the code +itself and requires more cognitive effort to trace the effects of +events. Furthermore, mutation-heavy, imperative code introduces a +class of bugs that are not present in functional programs, order of +operations bugs, that make large programs difficult to reason about. +Therefore, we believe that imperative event callbacks are too +low-level to express asynchronous programs in an understandable way. +Instead of explicitly mutating data and entering ``callback hell'', +Sly abstracts and formalizes the process using a functional reactive +programming style. In Sly, time-varying values are called ``signals'', and they are defined in a declarative and functional manner. Rather than -describing the process of mutation procedurally, one describes the -relationships between signals instead. The result is a ``signal -graph'', a directed acyclic graph of event responses. +describing the process of mutation procedurally, one @emph{declares} +the relationships between signals and how values are transformed as +they propagate. The result is a ``signal graph'', a directed acyclic +graph of event responses, that makes data flow explicit. @example (define-signal position @@ -130,11 +136,14 @@ Create a new signal whose value is a list of the values stored in @var{signals}. @end deffn -@deffn {Scheme Procedure} signal-map @var{proc} @var{signal} . @var{rest} -Create a new signal that applies @var{proc} to the values of -@var{SIGNAL}. More than one input signal may be specified, in which -case @var{proc} must accept as many arguments as there are input -signals. +@deffn {Scheme Procedure} signal-map @var{proc} @var{signal} @dots{} +Create a new signal that applies @var{proc} to the values stored in +one or more @var{signals}. +@end deffn + +@deffn {Scheme Procedure} signal-map-maybe @var{proc} @var{signal} @dots{} +Create a new signal that applies @var{proc} to the values of one or +more @var{signals} @emph{if} all of them are not @code{#f}. @end deffn @deffn {Scheme Procedure} signal-sample-on @var{value-signal} @var{sample-signal} @@ -180,6 +189,12 @@ the signal @var{predicate} is true, or the value of the signal @var{off} otherwise. @end deffn +@deffn {Scheme Procedure} signal-if @var{predicate} @var{on} @var{off} +Create a new signal whose value is the result of evaluating +@var{consequent} when the value of the signal @var{predicate} is +truth, otherwise @var{alternate} is evaluated. +@end deffn + @deffn {Scheme Procedure} signal-constant @var{constant} @var{signal} Create a new signal whose value is always @var{constant} no matter the value received from @var{signal}. diff --git a/doc/api/utils.texi b/doc/api/utils.texi index 4c7c39f..4eeb9d1 100644 --- a/doc/api/utils.texi +++ b/doc/api/utils.texi @@ -102,11 +102,6 @@ from the same thread that is running the game loop. 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. diff --git a/doc/sly.texi b/doc/sly.texi index 275b12a..e0c081d 100644 --- a/doc/sly.texi +++ b/doc/sly.texi @@ -119,9 +119,7 @@ Sly depends on the following packages: @itemize @item @url{https://gnu.org/software/guile, GNU Guile}, version 2.0.11 or later; @item @url{https://gnu.org/software/guile-opengl, GNU guile-opengl}, version 0.1 or later. -@item @url{https://gnu.org/software/guile-sdl, GNU guile-sdl}, version 0.5.0 or later; -@item @url{https://gnu.org/software/gsl, GNU Scientific Library}, version 1.16 or later; -@item @url{http://freeimage.sourceforge.net/, FreeImage}, version 3 or later +@item @url{https://dthompson.us/pages/software/guile-sdl2.html, guile-sdl2}, version 0.2.0 or later; @end itemize @node Examples -- cgit v1.2.3