Nyquist / XLISP 2.0 - Contents | Tutorials | Examples | Reference

# Multiple Values

1. Multiple Values

- Nyquist/XLISP helpers

- cl:*multiple-values* - [Variable] - signals if a function has returned multiple values
- cl:debug:mv - [Function] - debug multiple values

- Returning Multiple Values

- cl:values - [Function] - return multiple values
- cl:values-list - [Function] - return multiple values from a list

- Working with Multiple Values

- cl:multiple-value-list - [Macro] - evaluate an expression and return all values in a list
- cl:multiple-value-bind - [Macro] - bind multiple values to multiple let variables
- cl:multiple-value-setq - [Macro] - assign multiple values to multiple variables using setq
- cl:multiple-value-prog1 - [Macro] - eveluate multiple expressions, return the values of the first expression
- cl:multiple-value-call - [Macro] - apply a function to multiple values collected in a list

## Multiple Values

This is a port of the Common List framework for passing multiple values from one place to another. It is most often used to return multiple values from a function with cl:values or to bind multiple values to multiple variables with cl:multiple-value-bind or cl:multiple-value-setq.

The multiple value functions and macros use the Nyquist/XLISP *rslt* variable to store the values as a list, while the cl:*multiple-values* variable is used as a flag to indicate if a function has returned multiple values.

What happens if a normal Lisp function are given multiple values?

A normal Lisp function only sees the 'primary' return value, as returned by every Lisp function. The additional return values [including the primary return value] are stored in the *rslt* variable and are only read by the multiple value functions. This also means that with multiple values, the most important value should always be returned as the first value, because only the first value can be seen by a normal Lisp function. See cl:values for examples.

What happens if a function expecting multiple values is given a normal Lisp return value?

The first symbol will be set to the function's return value, while all other symbol will be set to NIL. No symbol will be left unset. All functions expecting multiple values are protected against a wrong number of values. If there are more symbols than values, then the extra symbols are set to NIL, if there are more values than symbols, the extra values will be ignored.

Known Limitations

1. In Nyquist/XLISP, cl:values cannot be used as argument to setf. But this is not a real problem, because the values are stored as a simple list in the *rslt* variable, where they can be manipulated with any arbitrary Lisp functions, not only with setf.

2. In Common Lisp there exists the option to return 'no value' by calling the 'values' function with no arguments. In Nyquist/XLISP there is no built-in way to return 'no value' from a function. The symbol *unbound* cannot be used for this because in Common Lisp, if 'no value' is assigned to a symbol as variable value, the new value will be NIL and not *unbound*.

In Nyquist/XLISP, the cl:values function, if called with no arguments, always returns NIL, and the *rslt* variable will be set to NIL, too:

    (cl:values)      => NIL  ; *rslt* = NIL
    (cl:values nil)  => NIL  ; *rslt* = (NIL)

Maybe this observation helps to write a 'no values' test if anybody really needs it.

3. Neither in Common Lisp nor in Nyquist/XLISP is it possibe to return nested multiple values:

    (cl:values (1 (cl:values 2 3) 4)  => 1  ; *rslt* = (1 2 4)

Back to top

Nyquist / XLISP 2.0 - Contents | Tutorials | Examples | Reference