summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/api/signals.texi225
1 files changed, 0 insertions, 225 deletions
diff --git a/doc/api/signals.texi b/doc/api/signals.texi
deleted file mode 100644
index f2773d2..0000000
--- a/doc/api/signals.texi
+++ /dev/null
@@ -1,225 +0,0 @@
-@node Signals
-@section Signals
-
-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.
-
-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.
-
-@example
-(define-signal position
- (signal-fold v+ (vector2 320 240)
- (signal-map (lambda (v) (v* v 4))
- (signal-sample 1 key-arrows))))
-@end example
-
-This signal describes a relationship between the arrow keys on the
-keyboard and the position of the player. @code{signal-sample} is used
-to trigger a signal update upon every game tick that provides the
-current state of the arrow keys. @code{key-arrows} is a 2D vector
-that maps to the current state of the arrow keys, allowing for 8
-directional movement. This vector is then scaled 4x to make the
-player move faster. Finally, the scaled vector is added to the
-previous player position via @code{signal-fold}. The player's
-position is at (320, 240) initially. As you can see, there are no
-callbacks and explicit mutation needed, and the position seems to
-magically change with the passage of time and pushing of the arrow
-keys.
-
-@deffn {Scheme Procedure} signal? @var{obj}
-Return @code{#t} if @var{obj} is a signal.
-@end deffn
-
-@deffn {Scheme Procedure} make-signal @var{value}
-Wrap @var{value} in a signal.
-@end deffn
-
-@deffn {Scheme Syntax} define-signal @var{name} @var{value}
-Create a top-level signal variable called @var{name}. If the variable
-already exists and refers to a signal then its outputs will be spliced
-into the new signal. If the given value is not a signal then it will
-be put into one via @code{make-signal}.
-
-@code{define-signal} is particularly useful when working at the REPL.
-A top-level signal variable defined by @code{define-signal} can be
-redefined at runtime, and the signals that depended on the old signal
-will continue to work with the new signal.
-@end deffn
-
-@deffn {Scheme Procedure} signal-ref @var{signal}
-Return the value stored within @var{signal}.
-@end deffn
-
-@deffn {Scheme Procedure} signal-ref-maybe object
-Return the value stored within @var{object} if @var{object} is a
-signal. Otherwise, return @var{object}.
-@end deffn
-
-@deffn {Scheme Syntax} signal-let ((@var{var} @var{signal}) @dots{}) @var{body} @dots{}
-Evaluate @var{body} in the context of the local bindings defined by
-the two-element lists @code{((var signal) @dots{})}.
-@code{signal-let} works like regular @code{let}, except that it
-derefences @var{signal} before binding to @var{var}.
-@end deffn
-
-@deffn {Scheme Syntax} signal-let* ((@var{var} @var{signal}) @dots{}) @var{body} @dots{}
-Similar to @code{signal-let}, but the variable bindings are performed
-sequentially. This means that all initialization expressions are
-allowed to use the variables defined to the their left in the binding
-list.
-@end deffn
-
-@deffn {Scheme Procedure} signal-set! signal-box value
-Change the contents of @var{signal} to @var{value}. This procedure
-should almost never be used, except to bootstrap a root node of a
-signal graph.
-@end deffn
-
-@deffn {Scheme Procedure} hook->signal @var{hook} @var{init} @var{proc}
-Create a new signal whose initial value is @var{init} and whose future
-values are calculated by applying @var{proc} to the arguments passed
-when @var{hook} is run.
-@end deffn
-
-@deffn {Scheme Procedure} signal-merge @var{signal1} @var{signal2} . @var{rest}
-Create a new signal whose value is the that of the most recently
-updated signal in @var{signal1}, @var{signal2}, etc. The initial
-value is that of @var{signal1}.
-@end deffn
-
-@deffn {Scheme Procedure} signal-zip . @var{signals}
-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.
-@end deffn
-
-@deffn {Scheme Procedure} signal-sample-on @var{value-signal} @var{sample-signal}
-Create a new signal that takes on the value of @var{value-signal}
-whenever @var{sample-signal} receives a new value.
-@end deffn
-
-@deffn {Scheme Procedure} signal-negate @var{signal}
-Create a new signal whose value is the negation of @var{signal} by
-applying @code{not} to each value received.
-@end deffn
-
-@deffn {Scheme Procedure} signal-fold @var{proc} @var{init} @var{signal} . @var{rest}
-Create a new signal that applies @var{proc} with the value received
-from @var{signal} and the past value of itself, starting with
-@var{init}. Like @code{signal-map}, more than one input signal may be
-given.
-@end deffn
-
-@deffn {Scheme Procedure} signal-filter @var{predicate} @var{default} @var{signal}
-Create a new signal that takes on the value received from @var{signal}
-when it satisfies the procedure @var{predicate}. The value of the
-signal is @var{default} in the case that the predicate is never
-satisfied.
-@end deffn
-
-@deffn {Scheme Procedure} signal-drop @var{predicate} @var{default} @var{signal}
-Create a new signal that takes on the value received from @var{signal}
-when it does @emph{not} satisfy the procedure @var{predicate}. The
-value of the signal is @var{default} in the case that the predicate is
-never satisfied.
-@end deffn
-
-@deffn {Scheme Procedure} signal-drop-repeats @var{signal} [@var{equal?}]
-Create a new signal that drops the value received from @var{signal}
-when it is equivalent to the current value. By default, @code{equal?}
-is used for testing equivalence.
-@end deffn
-
-@deffn {Scheme Procedure} signal-switch @var{predicate} @var{on} @var{off}
-Create a new signal whose value is that of the signal @var{on} when
-the signal @var{predicate} is true, or the value of the signal
-@var{off} otherwise.
-@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}.
-@end deffn
-
-@deffn {Scheme Procedure} signal-count @var{signal} [@var{start}] [@var{step}]
-Create a new signal that increments a counter by @var{step} when a
-value from @var{signal} is received, starting from @var{start}. By
-default, @var{start} is 0 and @var{step} is 1.
-@end deffn
-
-@deffn {Scheme Procedure} signal-tap @var{proc} @var{signal}
-Create a new signal that applies @var{proc} for side-effects when a
-value from @var{signal} is received. The value of the new signal will
-always be the value of @var{signal}. This signal is a convenient way
-to sneak in a procedure that with a side-effect into a signal graph.
-Such a signal might write text to a file, or play a sound.
-@end deffn
-
-@deffn {Scheme Procedure} signal-timestamp @var{signal}
-Create a new signal whose value is a pair, the car of which is the
-time that the value of @var{signal} was received and the cdr of which
-is the received value.
-@end deffn
-
-@deffn {Scheme Procedure} signal-time @var{signal}
-Create a new signal whose value is the time that the value of
-@var{signal} was received.
-@end deffn
-
-@deffn {Scheme Procedure} signal-sample @var{step} @var{signal}
-Create a new signal that takes on the value of @var{signal} every
-@var{step} ticks.
-@end deffn
-
-@deffn {Scheme Procedure} signal-every @var{step}
-Create a new signal that emits @var{step} every @var{step} ticks.
-@end deffn
-
-@deffn {Scheme Procedure} signal-timer [@var{step}]
-Create a new signal that emits the total time elapsed since its
-creation every @var{step} (1 by default) ticks.
-@end deffn
-
-@deffn {Scheme Procedure} signal-since @var{step} @var{signal}
-Create a new signal that emits the time since @var{signal} was updated
-ever @var{step} ticks.
-@end deffn
-
-@deffn {Scheme Procedure} signal-delay @var{delay} @var{signal}
-Create a new signal that delays propagation of @var{signal} by
-@var{delay} ticks..
-@end deffn
-
-@deffn {Scheme Procedure} signal-throttle delay signal
-Create a new signal that propagates @var{signal} at most once every
-@var{delay} ticks.
-@end deffn
-
-@deffn {Scheme Syntax} signal-generator @var{body} @dots{}
-Create a new signal whose value is the most recently yielded value of
-the coroutine defined by @var{body}. A special @code{yield} syntax is
-available within @var{body} to specify which values are passed to the
-signal.
-@end deffn
-
-@deffn {Scheme Procedure} signal-call @var{proc-signal} . @var{arg-signals}
-Create a new signal that applies the procedure within
-@var{proc-signal} to the arguments in @var{arg-signals}.
-@end deffn