The multiple-value-variants Reference Manual

Table of Contents

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.4 "Will Decker" on Wed Jun 20 12:18:59 2018 GMT+0.


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

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.


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

Jean-Philippe Paradis <hexstream@gmail.com>

License

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
Source

multiple-value-variants.asd (file)

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)


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

3.1.2 multiple-value-variants/package.lisp

Parent

multiple-value-variants (system)

Location

package.lisp

Packages

multiple-value-variants


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

3.1.3 multiple-value-variants/info.lisp

Dependency

package.lisp (file)

Parent

multiple-value-variants (system)

Location

info.lisp

Exported Definitions
Internal Definitions

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

3.1.4 multiple-value-variants/definitions.lisp

Dependency

info.lisp (file)

Parent

multiple-value-variants (system)

Location

definitions.lisp

Internal Definitions

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

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
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

multiple-value-variants

Source

info.lisp (file)

Macro: multiple-value OPTIONS &body FORM
Package

multiple-value-variants

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

multiple-value-variants

Source

info.lisp (file)

Function: expand OPTIONS FORM &optional ENV
Package

multiple-value-variants

Source

info.lisp (file)

Function: locate NAME &key ERRORP
Package

multiple-value-variants

Source

info.lisp (file)


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

5.1.3 Generic functions

Generic Function: atom-options-transformer OBJECT
Package

multiple-value-variants

Methods
Method: atom-options-transformer (STANDARD-INFO standard-info)

automatically generated reader method

Source

info.lisp (file)

Generic Function: chain CONDITION
Package

multiple-value-variants

Methods
Method: chain (CONDITION not-found-chain)
Source

info.lisp (file)

Generic Function: expander OBJECT
Package

multiple-value-variants

Source

info.lisp (file)

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

automatically generated reader method

Generic Function: form CONDITION
Package

multiple-value-variants

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

info.lisp (file)

Generic Function: form-lambda-list OBJECT
Package

multiple-value-variants

Source

info.lisp (file)

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

automatically generated reader method

Generic Function: name OBJECT
Package

multiple-value-variants

Source

info.lisp (file)

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

automatically generated reader method

Generic Function: options-lambda-list OBJECT
Package

multiple-value-variants

Source

info.lisp (file)

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

automatically generated reader method


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

5.1.4 Conditions

Condition: not-found ()
Package

multiple-value-variants

Source

info.lisp (file)

Direct superclasses

error (condition)

Direct methods

name (method)

Direct slots
Slot: %name
Initargs

:name

Readers

name (generic function)

Condition: not-found-chain ()
Package

multiple-value-variants

Source

info.lisp (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: %form
Initargs

:form

Readers

form (generic function)

Slot: %chain
Initargs

:chain

Readers

chain (generic function)


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

5.1.5 Classes

Class: info ()
Package

multiple-value-variants

Source

info.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

standard-info (class)

Class: standard-info ()
Package

multiple-value-variants

Source

info.lisp (file)

Direct superclasses

info (class)

Direct methods
Direct slots
Slot: %name
Type

symbol

Initargs

:name

Readers

name (generic function)

Slot: %options-lambda-list
Type

list

Initargs

:options-lambda-list

Readers

options-lambda-list (generic function)

Slot: %form-lambda-list
Type

list

Initargs

:form-lambda-list

Readers

form-lambda-list (generic function)

Slot: %expander
Type

(or function symbol)

Initargs

:expander

Readers

expander (generic function)

Slot: %atom-options-transformer
Type

(or function symbol)

Initargs

:atom-options-transformer

Initform

(function list)

Readers

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

multiple-value-variants

Source

info.lisp (file)


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

5.2.2 Functions

Function: %canonicalize OPTIONS FORM &optional ENV
Package

multiple-value-variants

Source

info.lisp (file)

Function: %canonicalize-options OPTIONS INFO
Package

multiple-value-variants

Source

info.lisp (file)

Function: %caselike OPERATOR KEYFORM CASES &optional OTHERWISEP
Package

multiple-value-variants

Source

definitions.lisp (file)

Function: %catching-values FUNCTION VALUES-FORM
Package

multiple-value-variants

Source

definitions.lisp (file)

Function: %check-expected-operator ACTUAL EXPECTED
Package

multiple-value-variants

Source

info.lisp (file)

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

multiple-value-variants

Source

definitions.lisp (file)

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

multiple-value-variants

Source

info.lisp (file)

Function: %extract-&whole LAMBDA-LIST
Package

multiple-value-variants

Source

info.lisp (file)

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

multiple-value-variants

Source

info.lisp (file)

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

multiple-value-variants

Source

definitions.lisp (file)

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

multiple-value-variants

Source

info.lisp (file)

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

multiple-value-variants

Source

info.lisp (file)

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

multiple-value-variants

Source

info.lisp (file)

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

multiple-value-variants

Source

definitions.lisp (file)

Function: %make-list-accumulator ()
Package

multiple-value-variants

Source

definitions.lisp (file)

Function: %make-nconc-accumulator ()
Package

multiple-value-variants

Source

definitions.lisp (file)

Function: %recursively FORMS FUNCTION &key LAST
Package

multiple-value-variants

Source

definitions.lisp (file)

Function: %remove-keys KEYS PLIST
Package

multiple-value-variants

Source

info.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   M  
Index Entry  Section

F
File, Lisp, multiple-value-variants.asd: The multiple-value-variants<dot>asd file
File, Lisp, multiple-value-variants/definitions.lisp: The multiple-value-variants/definitions<dot>lisp file
File, Lisp, multiple-value-variants/info.lisp: The multiple-value-variants/info<dot>lisp file
File, Lisp, multiple-value-variants/main.lisp: The multiple-value-variants/main<dot>lisp file
File, Lisp, multiple-value-variants/package.lisp: The multiple-value-variants/package<dot>lisp file

L
Lisp File, multiple-value-variants.asd: The multiple-value-variants<dot>asd file
Lisp File, multiple-value-variants/definitions.lisp: The multiple-value-variants/definitions<dot>lisp file
Lisp File, multiple-value-variants/info.lisp: The multiple-value-variants/info<dot>lisp file
Lisp File, multiple-value-variants/main.lisp: The multiple-value-variants/main<dot>lisp file
Lisp File, multiple-value-variants/package.lisp: The multiple-value-variants/package<dot>lisp file

M
multiple-value-variants.asd: The multiple-value-variants<dot>asd file
multiple-value-variants/definitions.lisp: The multiple-value-variants/definitions<dot>lisp file
multiple-value-variants/info.lisp: The multiple-value-variants/info<dot>lisp file
multiple-value-variants/main.lisp: The multiple-value-variants/main<dot>lisp file
multiple-value-variants/package.lisp: The multiple-value-variants/package<dot>lisp file

Jump to:   F   L   M  

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

A.2 Functions

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

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

(
(setf %locate): Internal functions

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

C
chain: Exported generic functions
chain: Exported generic functions

D
define: Exported macros

E
ensure: Exported functions
expand: Exported functions
expander: Exported generic functions
expander: Exported generic functions

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

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

L
locate: Exported functions

M
Macro, define: Exported macros
Macro, multiple-value: Exported macros
Method, atom-options-transformer: Exported generic functions
Method, chain: Exported generic functions
Method, expander: Exported generic functions
Method, form: Exported generic functions
Method, form-lambda-list: Exported generic functions
Method, name: Exported generic functions
Method, name: Exported generic functions
Method, options-lambda-list: Exported generic functions
multiple-value: Exported macros

N
name: Exported generic functions
name: Exported generic functions
name: Exported generic functions

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

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

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

A.3 Variables

Jump to:   %   *  
S  
Index Entry  Section

%
%atom-options-transformer: Exported classes
%chain: Exported conditions
%expander: Exported classes
%form: Exported conditions
%form-lambda-list: Exported classes
%name: Exported conditions
%name: Exported classes
%options-lambda-list: Exported classes

*
*infos*: Internal special variables

S
Slot, %atom-options-transformer: Exported classes
Slot, %chain: Exported conditions
Slot, %expander: Exported classes
Slot, %form: Exported conditions
Slot, %form-lambda-list: Exported classes
Slot, %name: Exported conditions
Slot, %name: Exported classes
Slot, %options-lambda-list: Exported classes
Special Variable, *infos*: Internal special variables

Jump to:   %   *  
S  

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

A.4 Data types

Jump to:   C   I   M   N   P   S  
Index Entry  Section

C
Class, info: Exported classes
Class, standard-info: Exported classes
Condition, not-found: Exported conditions
Condition, not-found-chain: Exported conditions

I
info: Exported classes

M
multiple-value-variants: The multiple-value-variants system
multiple-value-variants: The multiple-value-variants package

N
not-found: Exported conditions
not-found-chain: Exported conditions

P
Package, multiple-value-variants: The multiple-value-variants package

S
standard-info: Exported classes
System, multiple-value-variants: The multiple-value-variants system

Jump to:   C   I   M   N   P   S