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 4.0 beta 2 "William Riker" on Mon Aug 15 05:26:11 2022 GMT+0.

Table of Contents


1 Introduction

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


multiple-value-variants 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.


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
evaluated instead.


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.


2 Systems

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


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

2.1 multiple-value-variants

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.

Author

Jean-Philippe Paradis <hexstream@gmail.com>

License

Public Domain

Version

1.0.1

Dependencies
  • map-bind (system).
  • positional-lambda (system).
  • enhanced-multiple-value-bind (system).
Source

multiple-value-variants.asd.

Child Components

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


3.1.1 multiple-value-variants/multiple-value-variants.asd

Source

multiple-value-variants.asd.

Parent Component

multiple-value-variants (system).

ASDF Systems

multiple-value-variants.


3.1.2 multiple-value-variants/package.lisp

Source

multiple-value-variants.asd.

Parent Component

multiple-value-variants (system).

Packages

multiple-value-variants.


3.1.3 multiple-value-variants/info.lisp

Dependency

package.lisp (file).

Source

multiple-value-variants.asd.

Parent Component

multiple-value-variants (system).

Public Interface
Internals

3.1.4 multiple-value-variants/definitions.lisp

Dependency

info.lisp (file).

Source

multiple-value-variants.asd.

Parent Component

multiple-value-variants (system).

Internals

3.1.5 multiple-value-variants/main.lisp

Dependency

definitions.lisp (file).

Source

multiple-value-variants.asd.

Parent Component

multiple-value-variants (system).

Public Interface

multiple-value (macro).


4 Packages

Packages are listed by definition order.


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

4.1 multiple-value-variants

Source

package.lisp.

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

common-lisp.

Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


5.1.1 Macros

Macro: define (name options-lambda-list form-lambda-list &body body)
Package

multiple-value-variants.

Source

info.lisp.

Macro: multiple-value (options &body form)
Package

multiple-value-variants.

Source

main.lisp.


5.1.2 Ordinary functions

Function: ensure (name form-lambda-list options-lambda-list expander &rest keys &key class &allow-other-keys)
Package

multiple-value-variants.

Source

info.lisp.

Function: expand (options form &optional env)
Package

multiple-value-variants.

Source

info.lisp.

Function: locate (name &key errorp)
Package

multiple-value-variants.

Source

info.lisp.


5.1.3 Generic functions

Generic Reader: atom-options-transformer (object)
Package

multiple-value-variants.

Methods
Reader Method: atom-options-transformer ((standard-info standard-info))

automatically generated reader method

Source

info.lisp.

Target Slot

%atom-options-transformer.

Generic Reader: chain (condition)
Package

multiple-value-variants.

Methods
Reader Method: chain ((condition not-found-chain))
Source

info.lisp.

Target Slot

%chain.

Generic Reader: expander (object)
Package

multiple-value-variants.

Source

info.lisp.

Methods
Reader Method: expander ((standard-info standard-info))

automatically generated reader method

Target Slot

%expander.

Generic Reader: form (condition)
Package

multiple-value-variants.

Methods
Reader Method: form ((condition not-found-chain))
Source

info.lisp.

Target Slot

%form.

Generic Reader: form-lambda-list (object)
Package

multiple-value-variants.

Source

info.lisp.

Methods
Reader Method: form-lambda-list ((standard-info standard-info))

automatically generated reader method

Target Slot

%form-lambda-list.

Generic Reader: name (object)
Package

multiple-value-variants.

Source

info.lisp.

Methods
Reader Method: name ((condition not-found))
Target Slot

%name.

Reader Method: name ((standard-info standard-info))

automatically generated reader method

Target Slot

%name.

Generic Reader: options-lambda-list (object)
Package

multiple-value-variants.

Source

info.lisp.

Methods
Reader Method: options-lambda-list ((standard-info standard-info))

automatically generated reader method

Target Slot

%options-lambda-list.


5.1.4 Standalone methods

Method: print-object ((info standard-info) stream)
Source

info.lisp.


5.1.5 Conditions

Condition: not-found
Package

multiple-value-variants.

Source

info.lisp.

Direct superclasses

error.

Direct methods

name.

Direct slots
Slot: %name
Initargs

:name

Readers

name.

Writers

This slot is read-only.

Condition: not-found-chain
Package

multiple-value-variants.

Source

info.lisp.

Direct superclasses

error.

Direct methods
Direct slots
Slot: %form
Initargs

:form

Readers

form.

Writers

This slot is read-only.

Slot: %chain
Initargs

:chain

Readers

chain.

Writers

This slot is read-only.


Previous: , Up: Public Interface   [Contents][Index]

5.1.6 Classes

Class: info
Package

multiple-value-variants.

Source

info.lisp.

Direct subclasses

standard-info.

Class: standard-info
Package

multiple-value-variants.

Source

info.lisp.

Direct superclasses

info.

Direct methods
Direct slots
Slot: %name
Type

symbol

Initargs

:name

Readers

name.

Writers

This slot is read-only.

Slot: %options-lambda-list
Type

list

Initargs

:options-lambda-list

Readers

options-lambda-list.

Writers

This slot is read-only.

Slot: %form-lambda-list
Type

list

Initargs

:form-lambda-list

Readers

form-lambda-list.

Writers

This slot is read-only.

Slot: %expander
Type

(or function symbol)

Initargs

:expander

Readers

expander.

Writers

This slot is read-only.

Slot: %atom-options-transformer
Type

(or function symbol)

Initform

(function list)

Initargs

:atom-options-transformer

Readers

atom-options-transformer.

Writers

This slot is read-only.


5.2 Internals


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

5.2.1 Special variables

Special Variable: *infos*
Package

multiple-value-variants.

Source

info.lisp.


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

5.2.2 Ordinary functions

Function: %canonicalize (options form &optional env)
Package

multiple-value-variants.

Source

info.lisp.

Function: %canonicalize-options (options info)
Package

multiple-value-variants.

Source

info.lisp.

Function: %caselike (operator keyform cases &optional otherwisep)
Package

multiple-value-variants.

Source

definitions.lisp.

Function: %catching-values (function values-form)
Package

multiple-value-variants.

Source

definitions.lisp.

Function: %check-expected-operator (actual expected)
Package

multiple-value-variants.

Source

info.lisp.

Function: %expand-multiple-value-mapper (mapper accumulator-maker multiple-values-count function lists)
Package

multiple-value-variants.

Source

definitions.lisp.

Function: %extract-&environment (macro-lambda-list)
Package

multiple-value-variants.

Source

info.lisp.

Function: %extract-&whole (lambda-list)
Package

multiple-value-variants.

Source

info.lisp.

Function: %extract-&whole-&environment (macro-lambda-list)
Package

multiple-value-variants.

Source

info.lisp.

Function: %handling-identity (name identity identityp forms function)
Package

multiple-value-variants.

Source

definitions.lisp.

Function: (setf %locate) (name &key errorp)
Package

multiple-value-variants.

Source

info.lisp.

Function: %locate-expand (form env)
Package

multiple-value-variants.

Source

info.lisp.

Function: %make-expander (name options-lambda-list form-lambda-list body)
Package

multiple-value-variants.

Source

info.lisp.

Function: %make-gensym-generator (&optional default-base)
Package

multiple-value-variants.

Source

definitions.lisp.

Function: %make-list-accumulator ()
Package

multiple-value-variants.

Source

definitions.lisp.

Function: %make-nconc-accumulator ()
Package

multiple-value-variants.

Source

definitions.lisp.

Function: %recursively (forms function &key last)
Package

multiple-value-variants.

Source

definitions.lisp.

Function: %remove-keys (keys plist)
Package

multiple-value-variants.

Source

info.lisp.


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   P  
Index Entry  Section

%
%canonicalize: Private ordinary functions
%canonicalize-options: Private ordinary functions
%caselike: Private ordinary functions
%catching-values: Private ordinary functions
%check-expected-operator: Private ordinary functions
%expand-multiple-value-mapper: Private ordinary functions
%extract-&environment: Private ordinary functions
%extract-&whole: Private ordinary functions
%extract-&whole-&environment: Private ordinary functions
%handling-identity: Private ordinary functions
%locate-expand: Private ordinary functions
%make-expander: Private ordinary functions
%make-gensym-generator: Private ordinary functions
%make-list-accumulator: Private ordinary functions
%make-nconc-accumulator: Private ordinary functions
%recursively: Private ordinary functions
%remove-keys: Private ordinary functions

(
(setf %locate): Private ordinary functions

A
atom-options-transformer: Public generic functions
atom-options-transformer: Public generic functions

C
chain: Public generic functions
chain: Public generic functions

D
define: Public macros

E
ensure: Public ordinary functions
expand: Public ordinary functions
expander: Public generic functions
expander: Public generic functions

F
form: Public generic functions
form: Public generic functions
form-lambda-list: Public generic functions
form-lambda-list: Public generic functions
Function, %canonicalize: Private ordinary functions
Function, %canonicalize-options: Private ordinary functions
Function, %caselike: Private ordinary functions
Function, %catching-values: Private ordinary functions
Function, %check-expected-operator: Private ordinary functions
Function, %expand-multiple-value-mapper: Private ordinary functions
Function, %extract-&environment: Private ordinary functions
Function, %extract-&whole: Private ordinary functions
Function, %extract-&whole-&environment: Private ordinary functions
Function, %handling-identity: Private ordinary functions
Function, %locate-expand: Private ordinary functions
Function, %make-expander: Private ordinary functions
Function, %make-gensym-generator: Private ordinary functions
Function, %make-list-accumulator: Private ordinary functions
Function, %make-nconc-accumulator: Private ordinary functions
Function, %recursively: Private ordinary functions
Function, %remove-keys: Private ordinary functions
Function, (setf %locate): Private ordinary functions
Function, ensure: Public ordinary functions
Function, expand: Public ordinary functions
Function, locate: Public ordinary functions

G
Generic Function, atom-options-transformer: Public generic functions
Generic Function, chain: Public generic functions
Generic Function, expander: Public generic functions
Generic Function, form: Public generic functions
Generic Function, form-lambda-list: Public generic functions
Generic Function, name: Public generic functions
Generic Function, options-lambda-list: Public generic functions

L
locate: Public ordinary functions

M
Macro, define: Public macros
Macro, multiple-value: Public macros
Method, atom-options-transformer: Public generic functions
Method, chain: Public generic functions
Method, expander: Public generic functions
Method, form: Public generic functions
Method, form-lambda-list: Public generic functions
Method, name: Public generic functions
Method, name: Public generic functions
Method, options-lambda-list: Public generic functions
Method, print-object: Public standalone methods
multiple-value: Public macros

N
name: Public generic functions
name: Public generic functions
name: Public generic functions

O
options-lambda-list: Public generic functions
options-lambda-list: Public generic functions

P
print-object: Public standalone methods

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