SPLAT documentation - chapter 3
The define-splat syntax form

The form (define-splat (name . args) . body) is a Scheme special form. Arguments are not evaluated in the normal way, and the body of the form can contain only a small set of recognized sub-forms. This section describes the recognized parts of a define-splat form. The general form of the syntax is: 
(define-splat (name arg1 arg2 ... argn)
  (local-vars (var1 value1) 
              (var2 value2)
              ... 
              (varn valuen))
  (preconditions . body)
  (initializer . body)
  (finalizer . body)
  (wait-for fluent-list . body)
  (event-handler 
     (event predicate)
     (action action)
  (method context . body))

The wait-for, event-handler, and method forms can be repeated as necessary to describe all of the relevant parts. Any of the parts except the initial (name . args) binding form can be omitted, and parts can appear in any order.

3.1 (name . args)

The first argument to define-splat, and the only one that is required, is the (name . args) binding form. This has exactly the same syntax as the (name . args) part of the (define (name . args) . body) function definition shortcut, including typing of arguments. The arguments are in scope throughout the define-splat form.

The symbol name is bound to a function which has the argument signature specified in the binding form. This function returns a data structure of type <splat> which can be thought of as a handle or process structure connected to an active task of the type defined by the define-splat form. Within the body of the define-splat form, this structure can be referred to by the variable self, which is in scope everywhere in the body of the define-splat form. Invoking the function defined by define-splat does not start execution of the task; this must be done by a call to run, run-top-level or start-task.

3.2 (local-vars (arg val) ...)

Defines variables that will be in scope for the entire body of the define-splat form but which are not arguments to the splat. Use local-vars to hold information that must be passed between earlier phases of splat execution (such as initializers) and later phases such as execution methods.

The syntax of the variable binding forms is identical to that of the binding forms of a normal let* form. Not surprisingly, the local-vars form expands a let* internally, which means that the variable binding forms are evaluated at the time that the splat instantiation function (the procedure bound to name by the define-splat form) is called.

3.3 (preconditions . body)

Defines the conditions that must be true for this splat to be applicable. body is a list of predicates that are evaluated before method selection. Preconditions are evaluated in a short-circuit fashion like (and ...). All must all be true for the SPLAT to run. If any of the precondition predicates return #f, the SPLAT fails without a method being selected, and the return value (return-value splat) returning 'precond-failed.

3.4 (initializer . body)

Defines one or more actions to be taken before method selection. Initializers are run immediately after preconditions have succeeded.

3.5 (finalizer . body)

Defines one or more actions to be taken to "finalize" or shut down the splat after execution. Finalizers are the companion to initializers, run after the splat has finished (in the case of either failure or success).

3.6 (wait-for fluent-list . body)

Describes an execution barrier which causes the splat to pause in execution until the predicate becomes true. fluent-list lists the splat-fluent objects referred to in the body predicate. The predicate form is evaluated only when one or more of these fluents changes in value. See the splat-predicated-action description in <splat-fluent> and <splat-predicated-action> , section 5.3 for more details.

3.7 (event-handler (event fluent-list . body) (action . body))

Defines a predicate on the splat fluents in fluent-list which will cause the specified action to take place when it becomes true. The event-handlers are one-shot and must be explicitly reenabled by their handlers if repeated execution is desired.

3.8 (method context . body)

Defines a method for executing the splat. At run time, a method is selected based on the context form. The first method for which the context form returns a true value is selected and executed.

The value that a method returns determines the action taken by the splat engine. If the value is 'method-succeeded, the method is considered to have succeeded and the splat invokes finalizers and exits. If a method returns any other value, another method is selected and run if a relevant one can be found. If no other relevant method can be found, the splat engine runs finalizers and exits.

The fate of a splat can be found by the (return-code splat). This is set to the value returned from a selected method, or another value reflecting the reason the splat finished. Meaningful values for the return code are:

'method-succeeded
The selected method succeeded.

'no-method
No method was valid in the current context. This could mean that all valid methods have been tried and failed, or that no valid method existed.

'failed-precond
The preconditions for the splat were not all true, and the splat exited without selecting a method.

Two functions can cause the splat to exit immediately with a specified return code. (method-finish splat retval) immediately returns from the method with the specified return value. If retval is not 'method-succeeded, another method is selected. (finish splat retval) causes the splat to exit absolutely with the specified return code, not selecting another method regardless of the value of retval.
SPLAT documentation - Copyright ©1996-1997 Bill Gribble.
Contents; next; back.
2 September 1997
Bill Gribble grib@cs.utexas.edu