# The multiple-value-variants Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

# The multiple-value-variants Reference Manual

This is the multiple-value-variants Reference Manual, version 1.0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:20:46 2018 GMT+0.

Next: , Previous: , Up: Top   [Contents][Index]

## 1 Introduction

```Project's home: http://www.hexstreamsoft.com/projects/multiple-value-variants/

operators through one macro: MULTIPLE-VALUE. There are built-in
variants for some standard operators; it's easy to create your own
variants for other operators. The multiple-value mapping operators are
especially useful.

Examples
--------

(multiple-value () (progn 1 2 3))
=> 3

(multiple-value () (progn))
=> [no values]

(multiple-value ()
(and (values nil 'other 'values)
t))
=> NIL, OTHER, VALUES

(multiple-value ()
(or (find-symbol "OR" '#:cl)
(find-symbol "XOR" '#:cl)))
=> OR, :EXTERNAL

(let ((hash (make-hash-table)))
(multiple-value () (cond ((gethash 'key hash))
((values)))))
=> [no values]

(let ((hash (make-hash-table)))
(setf (gethash 'key hash) 'value)
(multiple-value () (cond ((gethash 'key hash))
((values)))))
=> VALUE, T

(multiple-value ()
(when nil
(print "side-effect")))
=> [no values]

(multiple-value (2)
(mapcar #'truncate '(3 5/4 5.5)))
=> (3 1 5), (0 1/4 0.5)

(multiple-value 2
(mapcan (lambda (object)
(if (numberp object)
(values (list object) nil)
(values nil (list object))))
'(0 a 2 3/4 c)))
=> (0 2 3/4), (A C)

(multiple-value 3
(maplist (lambda (tail)
(values tail
(reverse tail)
(list (first tail) (second tail))))
'(a b c d e)))
=>
((A B C D E) (B C D E) (C D E) (D E) (E))
((E D C B A) (E D C B) (E D C) (E D) (E))
((A B) (B C) (C D) (D E) (E NIL))

API
---

First of all, in the way of packages there's the
MULTIPLE-VALUE-VARIANTS package, which is also nicknamed
MULTIPLE-VALUE-VARIANT, MV-VARIANTS and MV-VARIANT. The primary
exported symbol is the MULTIPLE-VALUE macro. Explicitly (:import-from
#:multiple-value-variants #:multiple-value) for normal usage. Don't (:use)!

The MULTIPLE-VALUE-VARIANTS package also exports other symbols related
to creation of new multiple-value variants and querying of existing
ones (documentation pending, check package.lisp for a list of all
exported symbols). The most important of these is DEFINE, which is
normally used to define new multiple-value variants. You should
normally explicitly package-qualify this symbol.

There are 2 recurring features throughout the API:

IDENTITY generally indicates the form to evaluate (and values to
return) when an implicit (multiple-value progn) has no forms.

NTH indicates which value to test for conditionals.

The rest of the API documentation introduces the built-in
multiple-value variants.

Variant PROGN
(&key (identity '(values)))
(&body forms)

Just like PROGN, except if there are no FORMS then the IDENTITY is

Variant PROG1
()
(result &body body)

This straightforwardly expands to a MULTIPLE-VALUE-PROG1.

Variant AND
(&key identity (nth 0))
(&rest forms)

If IDENTITY is not specified, then there must be at least one FORM.

This is like normal AND, except if one of the non-last FORMS'
NTH-value is false, returns all values that were returned by that
FORM, not just the primary value.

Variant OR
(&key identity (nth 0))
(&rest forms)

If IDENTITY is not specified, then there must be at least one FORM.

This is like normal OR, except if one of the non-last FORMS'
NTH-value is true, returns all values that were returned by that
FORM, not just the primary value.

Variant COND
(&key (nth 0))
(&rest clauses)

This is just like normal COND, except:

- If a CLAUSE that has no FORMS succeeds, then all the values that
were returned by the TEST-FORM are returned, not just the primary
value;

- If no CLAUSE succeeds, then no values are returned (instead of NIL).

Variant WHEN
(&key (else '(values)) (identity '(values)))
(test &body forms)

If TEST evaluates to true, evaluate FORMS as an implicit
(multiple-value progn) with IDENTITY as the identity.

Else, evaluate ELSE.

Variant UNLESS
(&key (else '(values)) (identity '(values)))
(test &body forms)

If TEST evaluates to false, evaluate FORMS as an implicit
(multiple-value progn) with IDENTITY as the identity.

Else, evaluate ELSE.

Variant CASE () (keyform &body cases)
Variant CCASE () (keyplace &body cases)
Variant ECASE () (keyform &body cases)

Variant TYPECASE () (keyform &body cases)
Variant CTYPECASE () (keyplace &body cases)
Variant ETYPECASE () (keyform &body cases)

These are like their normal counterparts, except the FORMS in each
case is an implicit (multiple-value progn), and if no case matches in
CASE or TYPECASE, then no values are returned (instead of NIL).

Variant MAPCAR (multiple-values-count) (function &rest+ lists)
Variant MAPCAN (multiple-values-count) (function &rest+ lists)
Variant MAPLIST (multiple-values-count) (function &rest+ lists)
Variant MAPCON (multiple-values-count) (function &rest+ lists)

These are just like the normal variants, except they can accumulate
multiple results at the same time. This is especially useful to
"triage" values (ex: split the elements of a list into 2 lists
according to some criteria), and to accumulate multiple "layers" of
values in one pass for macroexpansions, as an alternative to repeated
mapping (sometimes with some readability problems due to reduced
"correlation").

MULTIPLE-VALUES-COUNT is not evaluated, and must be a non-negative
integer indicating the number of results (values) to accumulate and
return. FUNCTION would normally return that many values. If FUNCTION
returns less than MULTIPLE-VALUES-COUNT values, then the remaining
values are NIL. If FUNCTION returns more than MULTIPLE-VALUES-COUNT
values, then the excess values are ignored.

This library is in the Public Domain.
See the UNLICENSE file for details.

```

Next: , Previous: , Up: Top   [Contents][Index]

## 2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

### 2.1 multiple-value-variants

Author

Public Domain

Description

Gives access to multiple-value variants of operators through one macro: MULTIPLE-VALUE. There are built-in variants for some standard operators; it’s easy to create your own variants for other operators. The multiple-value mapping operators are especially useful.

Version

1.0.1

Dependencies
• map-bind
• positional-lambda
• enhanced-multiple-value-bind
Source
Components

Next: , Previous: , Up: Top   [Contents][Index]

## 3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

### 3.1 Lisp

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.1 multiple-value-variants.asd

Location

multiple-value-variants.asd

Systems

multiple-value-variants (system)

#### 3.1.2 multiple-value-variants/package.lisp

Parent

multiple-value-variants (system)

Location

package.lisp

Packages

#### 3.1.3 multiple-value-variants/info.lisp

Dependency

package.lisp (file)

Parent

multiple-value-variants (system)

Location

info.lisp

Exported Definitions
Internal Definitions

#### 3.1.4 multiple-value-variants/definitions.lisp

Dependency

info.lisp (file)

Parent

multiple-value-variants (system)

Location

definitions.lisp

Internal Definitions

#### 3.1.5 multiple-value-variants/main.lisp

Dependency

definitions.lisp (file)

Parent

multiple-value-variants (system)

Location

main.lisp

Exported Definitions

multiple-value (macro)

Next: , Previous: , Up: Top   [Contents][Index]

## 4 Packages

Packages are listed by definition order.

Previous: , Up: Packages   [Contents][Index]

### 4.1 multiple-value-variants

Source

package.lisp (file)

Nicknames
• multiple-value-variant
• mv-variant
• mv-variants
Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Next: , Previous: , Up: Definitions   [Contents][Index]

### 5.1 Exported definitions

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.1 Macros

Macro: define NAME OPTIONS-LAMBDA-LIST FORM-LAMBDA-LIST &body BODY
Package
Source

info.lisp (file)

Macro: multiple-value OPTIONS &body FORM
Package
Source

main.lisp (file)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.2 Functions

Function: ensure NAME FORM-LAMBDA-LIST OPTIONS-LAMBDA-LIST EXPANDER &rest KEYS &key CLASS &allow-other-keys
Package
Source

info.lisp (file)

Function: expand OPTIONS FORM &optional ENV
Package
Source

info.lisp (file)

Function: locate NAME &key ERRORP
Package
Source

info.lisp (file)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.3 Generic functions

Generic Function: atom-options-transformer OBJECT
Package
Methods
Method: atom-options-transformer (STANDARD-INFO standard-info)

Source

info.lisp (file)

Generic Function: chain CONDITION
Package
Methods
Method: chain (CONDITION not-found-chain)
Source

info.lisp (file)

Generic Function: expander OBJECT
Package
Source

info.lisp (file)

Methods
Method: expander (STANDARD-INFO standard-info)

Generic Function: form CONDITION
Package
Methods
Method: form (CONDITION not-found-chain)
Source

info.lisp (file)

Generic Function: form-lambda-list OBJECT
Package
Source

info.lisp (file)

Methods
Method: form-lambda-list (STANDARD-INFO standard-info)

Generic Function: name OBJECT
Package
Source

info.lisp (file)

Methods
Method: name (CONDITION not-found)
Method: name (STANDARD-INFO standard-info)

Generic Function: options-lambda-list OBJECT
Package
Source

info.lisp (file)

Methods
Method: options-lambda-list (STANDARD-INFO standard-info)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.4 Conditions

Condition: not-found ()
Package
Source

info.lisp (file)

Direct superclasses

error (condition)

Direct methods

name (method)

Direct slots
Slot: %name
Initargs

:name

name (generic function)

Condition: not-found-chain ()
Package
Source

info.lisp (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: %form
Initargs

:form

form (generic function)

Slot: %chain
Initargs

:chain

chain (generic function)

Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.5 Classes

Class: info ()
Package
Source

info.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

standard-info (class)

Class: standard-info ()
Package
Source

info.lisp (file)

Direct superclasses

info (class)

Direct methods
Direct slots
Slot: %name
Type

symbol

Initargs

:name

name (generic function)

Slot: %options-lambda-list
Type

list

Initargs

:options-lambda-list

options-lambda-list (generic function)

Slot: %form-lambda-list
Type

list

Initargs

:form-lambda-list

form-lambda-list (generic function)

Slot: %expander
Type

(or function symbol)

Initargs

:expander

expander (generic function)

Slot: %atom-options-transformer
Type

(or function symbol)

Initargs

:atom-options-transformer

Initform

(function list)

atom-options-transformer (generic function)

Previous: , Up: Definitions   [Contents][Index]

### 5.2 Internal definitions

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.1 Special variables

Special Variable: *infos*
Package
Source

info.lisp (file)

Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.2 Functions

Function: %canonicalize OPTIONS FORM &optional ENV
Package
Source

info.lisp (file)

Function: %canonicalize-options OPTIONS INFO
Package
Source

info.lisp (file)

Function: %caselike OPERATOR KEYFORM CASES &optional OTHERWISEP
Package
Source

definitions.lisp (file)

Function: %catching-values FUNCTION VALUES-FORM
Package
Source

definitions.lisp (file)

Function: %check-expected-operator ACTUAL EXPECTED
Package
Source

info.lisp (file)

Function: %expand-multiple-value-mapper MAPPER ACCUMULATOR-MAKER MULTIPLE-VALUES-COUNT FUNCTION LISTS
Package
Source

definitions.lisp (file)

Function: %extract-&environment MACRO-LAMBDA-LIST
Package
Source

info.lisp (file)

Function: %extract-&whole LAMBDA-LIST
Package
Source

info.lisp (file)

Function: %extract-&whole-&environment MACRO-LAMBDA-LIST
Package
Source

info.lisp (file)

Function: %handling-identity NAME IDENTITY IDENTITYP FORMS FUNCTION
Package
Source

definitions.lisp (file)

Function: (setf %locate) NEW NAME &key ERRORP
Package
Source

info.lisp (file)

Function: %locate-expand FORM ENV &aux CHAIN INITIAL-FORM
Package
Source

info.lisp (file)

Function: %make-expander NAME OPTIONS-LAMBDA-LIST FORM-LAMBDA-LIST BODY
Package
Source

info.lisp (file)

Function: %make-gensym-generator &optional DEFAULT-BASE
Package
Source

definitions.lisp (file)

Function: %make-list-accumulator ()
Package
Source

definitions.lisp (file)

Function: %make-nconc-accumulator ()
Package
Source

definitions.lisp (file)

Function: %recursively FORMS FUNCTION &key LAST
Package
Source

definitions.lisp (file)

Function: %remove-keys KEYS PLIST
Package
Source

info.lisp (file)

Previous: , Up: Top   [Contents][Index]

## Appendix A Indexes

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.1 Concepts

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.2 Functions

Jump to: %   (   A   C   D   E   F   G   L   M   N   O
Jump to: %   (   A   C   D   E   F   G   L   M   N   O

Next: , Previous: , Up: Indexes   [Contents][Index]