summaryrefslogtreecommitdiff
path: root/doc/api
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2016-02-27 14:13:15 -0500
committerDavid Thompson <dthompson2@worcester.edu>2016-02-27 14:13:15 -0500
commit0962cfa1a3567218980dd29d3a47234535722894 (patch)
tree412df0c827ecd37ed4447021b4815c98c7628dec /doc/api
parent462e6e38841dab4cb37fd6ebf8f15e2c01e3d36a (diff)
doc: Spruce things up a bit.
Diffstat (limited to 'doc/api')
-rw-r--r--doc/api/time.texi61
-rw-r--r--doc/api/utils.texi5
2 files changed, 38 insertions, 28 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.