Potluck dish - Simple functional reactive programming

Potluck dish - Simple functional reactive programming

[David Thompson]

[-- Attachment #1: Type: text/plain, Size: 2633 bytes --]

Hello Guilers,

I didn't have time to put together a proper potluck dish, but I wanted
to find something to share anyway.

Lately I've been playing around with functional reactive programming
(FRP) applied to video games.  This style of programming allows for a
declarative, functional way of describing time-varying values.  Contrast
this method of programming with more traditional hooks and callbacks.
My FRP module can be used on top of hooks to escape callback hell.

And now for a simple example.  This morning I was writing a program
using my game engine, guile-2d, and I wanted to display the number of
times the GC has been run in the game window.  Without FRP I could have
done something like:

(define gc-label-position (vector2 0 40))
(define gc-counter 0)
(define (make-gc-label)
  (let ((text (format #f "GCs: ~d" counter)))
    (make-label font text gc-label-position)))
(define gc-label (make-gc-label))

(add-hook! after-gc-hook
           (lambda ()
             (set! gc-counter (1+ gc-counter))
             (set! gc-label (make-gc-label))))

This code isn't terrible, but wouldn't it be nice to declare that
'gc-label' will always contain a string with the number of GC runs in
it instead?  Enter FRP:

(define gc-label-position (vector2 0 40))
(define gc-counter (make-root-signal 0))
(define gc-label
  (signal-map (lambda (counter)
                (let ((text (format #f "GCs: ~d" counter)))
                  (make-label font text gc-label-position)))
              gc-counter))

(add-hook! after-gc-hook
           (lambda ()
             (signal-set! gc-counter (1+ (signal-ref gc-counter)))))

'gc-counter' and 'gc-label' both become 'signals', or time-varying
values.  Now, when the GC runs, the 'gc-counter' signal is incremented
by 1.  The act of setting 'gc-counter' triggers propagation of the
counter to the 'gc-label' signal which maps the counter to a new label
that prints the current number of GC runs.  Magic!  Note that
'after-gc-hook' is still needed to bootstrap the signal graph, but once
that is out of the way it's signals all the way down.

This example was fairly trivial, but what if the desired chain reaction
was more complicated?  Writing the logic using regular callback
procedures would become a nightmare.  The nightmare that JavaScript
programmers constantly find themselves in.

And that's my potluck dish!  I'm currently working on a new version of
this API that will allow the signal graph to handle the dynamic
environment of the REPL, but it's not ready yet.

Thanks to all of the Guile maintainers and contributors for the great
work these past 3 years!

- David Thompson

[-- Attachment #2: signals.scm --]
[-- Type: application/octet-stream, Size: 8741 bytes --]

;;; guile-2d
;;; Copyright (C) 2013 David Thompson <dthompson2@worcester.edu>
;;;
;;; Guile-2d is free software: you can redistribute it and/or modify it
;;; under the terms of the GNU Lesser General Public License as
;;; published by the Free Software Foundation, either version 3 of the
;;; License, or (at your option) any later version.
;;;
;;; Guile-2d is distributed in the hope that it will be useful, but
;;; WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
;;; Lesser General Public License for more details.
;;;
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with this program.  If not, see
;;; <http://www.gnu.org/licenses/>.

;;; Commentary:
;;
;; Simple functional reactive programming API.
;;
;;; Code:

(define-module (2d signals)
  #:use-module (srfi srfi-1)
  #:use-module (srfi srfi-9)
  #:use-module (srfi srfi-26)
  #:export (signal?
            root-signal?
            make-signal
            make-root-signal
            signal-ref
            signal-ref-maybe
            signal-receiver
            signal-inputs
            signal-outputs
            signal-connect!
            signal-disconnect!
            signal-clear!
            signal-set!
            signal-merge
            signal-combine
            signal-do
            signal-map
            signal-fold
            signal-filter
            signal-reject
            signal-constant
            signal-count))

;;;
;;; Signals
;;;

;; Signals are time-varying values. For example, a signal could
;; represent the mouse position at the current point in time. The
;; signals API provides an abstraction over regular event-based
;; programming. State mutation is hidden away and a functional,
;; declarative interface is exposed.
(define-record-type <signal>
  (%make-signal value proc inputs outputs)
  signal?
  (value signal-ref %signal-set!)
  (proc signal-proc)
  (inputs signal-inputs set-signal-inputs!)
  (outputs signal-outputs set-signal-outputs!))

(define (make-signal init proc inputs)
  "Create a new signal with initial value INIT, a procedure PROC
to transform incoming signal values and one or more signals to connect
to."
  (let ((signal (%make-signal init proc inputs '())))
    (for-each (cut signal-connect! <> signal) inputs)
    signal))

(define (make-root-signal init)
  "Create a new root level signal with initial value INIT."
  (%make-signal init #f '() '()))

(define (root-signal? signal)
  "Returns true if a signal has no receiver procedure or false
otherwise."
  (not (signal-proc signal)))

(define (signal-ref-maybe object)
  "Retrieves the signal value from OBJECT if it is a signal and or
simply returns OBJECT otherwise."
  (if (signal? object)
      (signal-ref object)
      object))

(define (signal-connect! signal-in signal-out)
  "Attach SIGNAL-OUT to SIGNAL-IN. When the value of SIGNAL-IN
changes, the value will be propagated to SIGNAL-OUT."
  (if (root-signal? signal-out)
      (error 'root-signal-error
             "Cannot connect to a root signal"
             signal-out)
      (let ((outputs (signal-outputs signal-in)))
        (set-signal-outputs! signal-in  (cons signal-out outputs)))))

(define (signal-disconnect! signal-in signal-out)
  "Detach SIGNAL-OUT from SIGNAL-IN."
  (let ((inputs (signal-inputs signal-out))
        (outputs (signal-outputs signal-in)))
    (set-signal-inputs!  signal-out (delete signal-in  inputs  eq?))
    (set-signal-outputs! signal-in  (delete signal-out outputs eq?))
    ;; Disconnect all inputs when the input signal has no remaining
    ;; outputs in order to prevent memory leaks and unnecessary
    ;; computation.
    (when (null? (signal-outputs signal-in))
      (signal-clear-inputs! signal-in))))

(define (signal-clear-outputs! signal)
  "Disconnect all output signals from SIGNAL."
  (for-each (cut signal-disconnect! signal <>)
            (signal-outputs signal))
  (set-signal-outputs! signal '()))

(define (signal-clear-inputs! signal)
  "Disconnect all inputs signals from SIGNAL."
  (for-each (cut signal-disconnect! <> signal)
            (signal-inputs signal))
  (set-signal-inputs! signal '()))

(define (signal-update! signal from)
  "Re-evaluate the signal procedure for the signal SIGNAL as ordered
by the signal FROM."
  ((signal-proc signal) signal from))

(define (signal-propagate! signal)
  "Notify all output signals about the current value of SIGNAL."
  (for-each (cut signal-update! <> signal)
            (signal-outputs signal)))

(define (signal-set! signal value)
  "Change the current value of SIGNAL to VALUE and propagate SIGNAL to
all connected signals."
  (%signal-set! signal value)
  (signal-propagate! signal))

(define (splice-signals! old new)
  "Remove the inputs and outputs from the signal OLD, connect the
outputs to the signal NEW, and return NEW."
  (when (signal? old)
    (let ((outputs (signal-outputs old)))
      (signal-clear-inputs! old)
      (signal-clear-outputs! old)
      (for-each (cut signal-connect! new <>) outputs))
    (signal-propagate! new))
  new)

(define-syntax define-signal
  (lambda (x)
    (syntax-case x ()
      ;; Splice in new signal if a signal with this name already
      ;; exists.
      ((_ name (signal ...))
       (defined? (syntax->datum #'name))
       #'(define name (splice-signals! name (signal ...))))
      ((_ name (signal ...))
       #'(define name (signal ...))))))

;;;
;;; Higher Order Signals
;;;

(define (signal-merge signal1 signal2 . rest)
  "Create a new signal whose value is the that of the most recently
changed signal in SIGNALs.  The initial value is that of the first
signal in SIGNALS."
  (let ((signals (append (list signal1 signal2) rest)))
    (make-signal (signal-ref (car signals))
                 (lambda (self from)
                   (signal-set! self (signal-ref from)))
                 signals)))

(define (signal-combine . signals)
  "Create a new signal whose value is a list of the values stored in
the given signals."
  (define (update signals)
    (map signal-ref signals))

  (make-signal (update signals)
               (lambda (self from)
                 (signal-set! self (update (signal-inputs self))))
               signals))

(define (signal-map proc signal . signals)
  "Create a new signal that applies PROC to the values stored in one
or more SIGNALS."
  (define (update signals)
    (apply proc (map signal-ref signals)))

  (let ((signals (cons signal signals)))
    (make-signal (update signals)
                 (lambda (self from)
                   (signal-set! self (update (signal-inputs self))))
                 signals)))

(define (signal-fold proc init signal)
  "Create a new signal that applies PROC to the values stored in
SIGNAL. PROC is applied with the current value of SIGNAL and the
previously computed value, or INIT for the first call."
  (make-signal init
               (let ((previous init))
                 (lambda (self from)
                   (let ((value (proc (signal-ref from) previous)))
                     (set! previous value)
                     (signal-set! self value))))
               (list signal)))

(define (signal-filter predicate default signal)
  "Create a new signal that keeps an incoming value from SIGNAL when
it satifies the procedure PREDICATE.  The value of the signal is
DEFAULT when the predicate is never satisfied."
  (make-signal (if (predicate (signal-ref signal))
                   (signal-ref signal)
                   default)
               (lambda (self signal)
                 (when (predicate (signal-ref signal))
                   (signal-set! self (signal-ref signal))))
               (list signal)))

(define (signal-reject predicate default signal)
  "Create a new signal that does not keep an incoming value from
SIGNAL when it satisfies the procedure PREDICATE.  The value of the
signal is DEFAULT when the predicate is never satisfied."
  (signal-filter (lambda (x) (not (predicate x))) default signal))

(define (signal-constant constant signal)
  "Create a new signal whose value is always CONSTANT regardless of
what the value received from SIGNAL."
  (signal-map (lambda (value) constant) signal))

(define (signal-count signal)
  "Create a new signal that increments a counter every time a new
value from SIGNAL is received."
  (signal-fold + 0 (signal-constant 1 signal)))

(define (signal-do proc signal)
  "Create a new signal that applies PROC when a new values is received
from SIGNAL.  The value of the new signal will always be the value of
SIGNAL.  This signal is a convenient way to sneak a procedure that has
a side-effect into a signal chain."
  (signal-map (lambda (x) (proc x) x) signal))

Re: Potluck dish - Simple functional reactive programming

[Ludovic Courtès]

David Thompson <dthompson2@worcester.edu> skribis:

> This code isn't terrible, but wouldn't it be nice to declare that
> 'gc-label' will always contain a string with the number of GC runs in
> it instead?  Enter FRP:
>
> (define gc-label-position (vector2 0 40))
> (define gc-counter (make-root-signal 0))
> (define gc-label
>   (signal-map (lambda (counter)
>                 (let ((text (format #f "GCs: ~d" counter)))
>                   (make-label font text gc-label-position)))
>               gc-counter))
>
> (add-hook! after-gc-hook
>            (lambda ()
>              (signal-set! gc-counter (1+ (signal-ref gc-counter)))))

Neat!  I’m a big fan.

I think we should consider adding an FRP module to Guile eventually.

Cheers,
Ludo’.

Re: Potluck dish - Simple functional reactive programming

[David Thompson]

[-- Attachment #1: Type: text/plain, Size: 2514 bytes --]

David Thompson <dthompson2@worcester.edu> writes:
> Lately I've been playing around with functional reactive programming
> (FRP) applied to video games.  This style of programming allows for a
> declarative, functional way of describing time-varying values.  Contrast
> this method of programming with more traditional hooks and callbacks.
> My FRP module can be used on top of hooks to escape callback hell.

I spent the day improving my potluck dish.  The public API remains the
same, but the implementation is quite a bit different.  The previous
implementation suffered from 2 major flaws:

1) The GC would never collect orphaned signals because of the doubly
linked structure of the graph

2) Redefining a signal 'foo' at the REPL doesn't splice the new value of
'foo' into the graph where the old value of 'foo' was.  Thus, working
with signals at the REPL was painful.

So, this new implementation uses an additional data type called
<signal-box> to deal with the dynamic nature of REPL-driven development.
The user is always working with signal boxes, not the signals
themselves.  By using the 'define-signal' macro, redefining the signal
'foo' at the REPL will replace the contents of the box with the new
signal.  If any other signals depended on 'foo', they automagically
begin to work with the signal within the box 'foo'.

To deal with doubly linked nodes, a weak key hash table is used to store
signal outputs.  This allows input signals to push values to output
signals without protecting them from the clutches of the garbage
collector.  When an output signal is no longer referenced, the input
signal will stop pushing new values to it.

Here's the updated version of the example from last time.  Note that
using 'after-gc-hook' is actually a bad idea, but I did it anyway. ;)

(define-signal gc-counter (make-signal 0))
(define-signal gc-label
  (signal-map (lambda (counter)
                (let ((text (format #f "GCs: ~d" counter)))
                  (make-label font text (vector2 0 40))))
              gc-counter))

(add-hook! after-gc-hook
           (lambda ()
             (schedule game-agenda
                       (lambda ()
                         (signal-set! gc-counter
                                      (1+ (signal-ref gc-counter)))))))

This module is currently part of the wip-frp branch of the guile-2d repo
on gitorious.

https://gitorious.org/guile-2d/guile-2d/source/3a786ddee63d4505cdb142442e880950698223f0:2d/signal.scm

Thanks for following along,
- David Thompson

[-- Attachment #2: signal.scm --]
[-- Type: application/octet-stream, Size: 10107 bytes --]

;;; guile-2d
;;; Copyright (C) 2013, 2014 David Thompson <dthompson2@worcester.edu>
;;;
;;; Guile-2d is free software: you can redistribute it and/or modify it
;;; under the terms of the GNU Lesser General Public License as
;;; published by the Free Software Foundation, either version 3 of the
;;; License, or (at your option) any later version.
;;;
;;; Guile-2d is distributed in the hope that it will be useful, but
;;; WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
;;; Lesser General Public License for more details.
;;;
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with this program.  If not, see
;;; <http://www.gnu.org/licenses/>.

;;; Commentary:
;;
;; Simple functional reactive programming API.
;;
;;; Code:

(define-module (2d signal)
  #:use-module (srfi srfi-1)
  #:use-module (srfi srfi-9)
  #:use-module (srfi srfi-26)
  #:use-module (2d agenda)
  #:export (signal?
            make-signal
            define-signal
            hook->signal
            signal-ref
            signal-ref-maybe
            signal-set!
            signal-proc
            signal-merge
            signal-combine
            signal-map
            signal-fold
            signal-filter
            signal-reject
            signal-constant
            signal-count
            signal-do
            signal-sample
            signal-delay
            signal-throttle))

;;;
;;; Signals
;;;

;; Signals are time-varying values. For example, a signal could
;; represent the mouse position at the current point in time. The
;; signals API provides an abstraction over regular event-based
;; programming. State mutation is hidden away and a functional,
;; declarative interface is exposed.
(define-record-type <signal>
  (%%make-signal value proc inputs outputs)
  %signal?
  (value %signal-ref %%signal-set!)
  (proc signal-proc)
  (inputs signal-inputs)
  (outputs signal-outputs))

(define-record-type <signal-box>
  (make-signal-box signal)
  signal-box?
  (signal signal-unbox signal-box-set!))

;; Alternate spelling of signal-box? for the public API.
(define signal? signal-box?)

(define (%make-signal init proc inputs)
  "Create a new signal with initial value INIT."
  (let ((signal (%%make-signal init proc inputs (make-weak-key-hash-table))))
    (for-each (cut signal-connect! signal <>) inputs)
    signal))

(define (make-signal init)
  "Return a signal box with initial value INIT."
  (make-signal-box (%make-signal init #f '())))

(define (make-boxed-signal init proc inputs)
  "Return a signal box containing a signal with value INIT, updating
procedure PROC, and a list of INPUTS."
  (make-signal-box (%make-signal init proc inputs)))

(define (signal-connect! signal-out signal-box-in)
  "Attach SIGNAL-OUT to SIGNAL-BOX-IN.  When the signal within
SIGNAL-BOX-IN changes, the value will be propagated to SIGNAL-OUT."
  (hashq-set! (signal-outputs (signal-unbox signal-box-in)) signal-out #f))

(define (signal-ref signal-box)
  "Return the current value of the signal contained within
SIGNAL-BOX."
  (%signal-ref (signal-unbox signal-box)))

(define (signal-ref-maybe object)
  "Retrieves the signal value from OBJECT if it is a signal and or
simply returns OBJECT otherwise."
  (if (signal-box? object)
      (signal-ref object)
      object))

(define (signal-propagate! signal)
  "Notify all output signals about the current value of SIGNAL."
  (hash-for-each (lambda (output unused)
                   ((signal-proc output) output (%signal-ref signal)))
                 (signal-outputs signal)))

(define (%signal-set! signal value)
  "Change the current value of SIGNAL to VALUE and propagate VALUE to
all output signals."
  (%%signal-set! signal value)
  (signal-propagate! signal)
  *unspecified*)

(define (signal-set! signal-box value)
  "Change the current value contained within SIGNAL-BOX to VALUE."
  (%signal-set! (signal-unbox signal-box) value))

(define (splice-signals! box-to box-from)
  "Replace the contents of BOX-TO with the contents of BOX-FROM and
transfer all output signals."
  (when (signal-box? box-to)
    (let ((outputs (signal-outputs (signal-unbox box-to))))
      (hash-for-each (lambda (signal unused)
                       (signal-connect! signal box-from))
                     outputs))
    (signal-box-set! box-to (signal-unbox box-from))))

(define-syntax define-signal
  (lambda (x)
    "Define a variable that contains a signal, with the added bonus
that if the variable already contains a signal then its outputs will
be spliced into the new signal."
    (syntax-case x ()
      ((_ name (signal ...))
       (defined? (syntax->datum #'name))
       #'(begin
           (splice-signals! name (signal ...))
           (signal-propagate! (signal-unbox name))))
      ((_ name (signal ...))
       #'(define name (signal ...)))
      ((_ name value)
       #'(define name value)))))

;;;
;;; Higher Order Signals
;;;

(define (hook->signal hook init proc)
  "Return a new signal whose initial value is INIT and has future
values calculated by applying PROC to the arguments sent when HOOK is
run."
  (let ((signal (make-signal init)))
    (add-hook! hook
               (lambda args
                 (signal-set! signal (apply proc args))))
    signal))

(define (signal-merge signal1 signal2 . rest)
  "Create a new signal whose value is the that of the most recently
changed signal in SIGNALs.  The initial value is that of the first
signal in SIGNALS."
  (let ((inputs (append (list signal1 signal2) rest)))
    (make-boxed-signal (signal-ref (car inputs))
                       (lambda (self value)
                         (%signal-set! self value))
                       inputs)))

(define (signal-combine . signals)
  "Create a new signal whose value is a list of the values stored in
the given signals."
  (define (current-value)
    (map signal-ref signals))
  (make-boxed-signal (current-value)
                     (lambda (self value)
                       (%signal-set! self (current-value)))
                     signals))

(define (signal-map proc signal . rest)
  "Create a new signal that applies PROC to the values stored in one
or more SIGNALS."
  (let ((inputs (cons signal rest)))
    (define (current-value)
      (apply proc (map signal-ref inputs)))
    (make-boxed-signal (current-value)
                       (lambda (self value)
                         (%signal-set! self (current-value)))
                       inputs)))

(define (signal-fold proc init signal . rest)
  "Create a new signal that applies PROC to the values stored in
SIGNAL. PROC is applied with the current value of SIGNAL and the
previously computed value, or INIT for the first call."
  (let ((inputs (cons signal rest)))
    (make-boxed-signal init
                       (let ((previous init))
                         (lambda (self value)
                           (let ((x (apply proc
                                           (append (map signal-ref inputs)
                                                   (list previous)))))
                             (set! previous x)
                             (%signal-set! self x))))
                       inputs)))

(define (signal-filter predicate default signal)
  "Create a new signal that keeps an incoming value from SIGNAL when
it satifies the procedure PREDICATE.  The value of the signal is
DEFAULT when the predicate is never satisfied."
  (make-boxed-signal (if (predicate (signal-ref signal))
                         (signal-ref signal)
                         default)
                     (lambda (self value)
                       (when (predicate value)
                         (%signal-set! self value)))
                     (list signal)))

(define (signal-reject predicate default signal)
  "Create a new signal that does not keep an incoming value from
SIGNAL when it satisfies the procedure PREDICATE.  The value of the
signal is DEFAULT when the predicate is never satisfied."
  (signal-filter (lambda (x) (not (predicate x))) default signal))

(define (signal-constant constant signal)
  "Create a new signal whose value is always CONSTANT regardless of
what the value received from SIGNAL."
  (signal-map (lambda (value) constant) signal))

(define (signal-count signal)
  "Create a new signal that increments a counter every time a new
value from SIGNAL is received."
  (signal-fold + 0 (signal-constant 1 signal)))

(define (signal-do proc signal)
  "Create a new signal that applies PROC when a new values is received
from SIGNAL.  The value of the new signal will always be the value of
SIGNAL.  This signal is a convenient way to sneak a procedure that has
a side-effect into a signal chain."
  (signal-map (lambda (x) (proc x) x) signal))

(define (signal-sample agenda delay signal)
  "Create a new signal that emits the value contained within SIGNAL
every DELAY ticks of AGENDA."
  (let ((sampler (%make-signal (signal-ref signal) #f '())))
    (define (tick)
      (%signal-set! sampler (signal-ref signal)))
    (schedule-interval agenda tick delay)
    (make-signal-box sampler)))

(define (signal-delay agenda delay signal)
  "Create a new signal that delays propagation of SIGNAL by DELAY
ticks of AGENDA."
  (make-boxed-signal (signal-ref signal)
                     (lambda (self value)
                       (schedule agenda
                                 (lambda ()
                                   (%signal-set! self value))
                                 delay))
                     (list signal)))

(define (signal-throttle agenda delay signal)
  "Return a new signal that propagates SIGNAL at most once every DELAY
ticks of AGENDA."
  (make-boxed-signal (signal-ref signal)
                     (let ((last-time (agenda-time agenda)))
                       (lambda (self value)
                         (when (>= (- (agenda-time agenda) last-time) delay)
                           (%signal-set! self value)
                           (set! last-time (agenda-time agenda)))))
                     (list signal)))

Re: Potluck dish - Simple functional reactive programming

[Panicz Maciej Godek]

Hi,
it's been over a month, and I finally had an opportunity to take a
closer look at your signal library (and also the video demonstration
available at your blog). I have to say that I'm truly impressed with
the code and grateful for it, and I find it very inspiring.

However, if it comes to the names that you chose for various routines,
I find them quite puzzling. I mean signal-map, signal-filter and
signal-fold.

I understand that while map works on lists and has its stream
counterpart defined in SICP, your idea was that the "collection" that
signal-map iterates over is a temporal sequence of changes, or
consecutive states that a program takes during its execution, which
are represented by signals.

I wanted to say that this name is a little bit confusing and propose a
better one, but after giving it a thought I concluded that the names
are really excellent and the concept is brilliant, so thanks again :)

M.

Re: Potluck dish - Simple functional reactive programming

[Thompson, David]

On Thu, Mar 20, 2014 at 11:46 AM, Panicz Maciej Godek
<godek.maciek@gmail.com> wrote:
> Hi,
> it's been over a month, and I finally had an opportunity to take a
> closer look at your signal library (and also the video demonstration
> available at your blog). I have to say that I'm truly impressed with
> the code and grateful for it, and I find it very inspiring.
>
> However, if it comes to the names that you chose for various routines,
> I find them quite puzzling. I mean signal-map, signal-filter and
> signal-fold.
>
> I understand that while map works on lists and has its stream
> counterpart defined in SICP, your idea was that the "collection" that
> signal-map iterates over is a temporal sequence of changes, or
> consecutive states that a program takes during its execution, which
> are represented by signals.
>
> I wanted to say that this name is a little bit confusing and propose a
> better one, but after giving it a thought I concluded that the names
> are really excellent and the concept is brilliant, so thanks again :)
>
> M.

Thanks!  I'm glad you enjoyed it.  I got my inspiration from the Elm
language (http://elm-lang.org/).  Feel free to email about any
comments/criticism to help me improve the API. :)

- Dave