Mercurial > hg > xemacs-beta

comparison man/lispref/eval.texi @ 5252:378a34562cbe

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix style, documentation for rounding functions and multiple values. src/ChangeLog addition: 2010-08-30 Aidan Kehoe <kehoea@parhasard.net> * floatfns.c (ceiling_one_mundane_arg, floor_one_mundane_arg) (round_one_mundane_arg, truncate_one_mundane_arg): INTEGERP is always available, no need to wrap calls to it with #ifdef HAVE_BIGNUM. (Fceiling, Ffloor, Fround, Ftruncate, Ffceiling, Fffloor) (Ffround, Fftruncate): Correct some code formatting here. * doprnt.c (emacs_doprnt_1): Remove some needless #ifdef WITH_NUMBER_TYPES, now number.h is always #included. man/ChangeLog addition: 2010-08-30 Aidan Kehoe <kehoea@parhasard.net> * lispref/eval.texi (Evaluation, Multiple values): Document our implementation of multiple values; point the reader to the CLTL or the Hyperspec for details of exactly when values are discarded. * lispref/numbers.texi (Numeric Conversions): Document the optional DIVISOR arguments to the rounding functions, and document that they all return multiple values. (Rounding Operations): Ditto. * cl.texi (Multiple Values): Document that we've moved the multiple values implementation to core code, and cross-reference to the Lispref. (Numerical Functions): The various rounding functions are now identical to the built-in rounding functions, with the exception that they return lists, not multiple values; document this.
author Aidan Kehoe <kehoea@parhasard.net>
date Mon, 30 Aug 2010 15:23:42 +0100
parents 755ae5b97edb
children 62b9ef1ed4ac
comparison
equal deleted inserted replaced
5251:b0ba3598beb1 5252:378a34562cbe
22 @menu 22 @menu
23 * Intro Eval:: Evaluation in the scheme of things. 23 * Intro Eval:: Evaluation in the scheme of things.
24 * Eval:: How to invoke the Lisp interpreter explicitly. 24 * Eval:: How to invoke the Lisp interpreter explicitly.
25 * Forms:: How various sorts of objects are evaluated. 25 * Forms:: How various sorts of objects are evaluated.
26 * Quoting:: Avoiding evaluation (to put constants in the program). 26 * Quoting:: Avoiding evaluation (to put constants in the program).
27 * Multiple values:: Functions may return more than one result.
27 @end menu 28 @end menu
28 29
29 @node Intro Eval 30 @node Intro Eval
30 @section Introduction to Evaluation 31 @section Introduction to Evaluation
31 32
706 707
707 Other quoting constructs include @code{function} (@pxref{Anonymous 708 Other quoting constructs include @code{function} (@pxref{Anonymous
708 Functions}), which causes an anonymous lambda expression written in Lisp 709 Functions}), which causes an anonymous lambda expression written in Lisp
709 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote 710 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
710 only part of a list, while computing and substituting other parts. 711 only part of a list, while computing and substituting other parts.
712
713 @node Multiple values
714 @section Multiple values
715 @cindex multiple values
716
717 @noindent
718 Under XEmacs, expressions can return zero or more results, using the
719 @code{values} and @code{values-list} functions. Results other than the
720 first are typically discarded, but special operators are provided to
721 access them.
722
723 @defun values arguments@dots{}
724 This function returns @var{arguments} as multiple values. Callers will
725 always receive the first element of @var{arguments}, but must use
726 various special operators, described below, to access other elements of
727 @var{arguments}.
728
729 The idiom @code{(values (function-call argument))}, with one
730 argument, is the normal mechanism to avoid passing multiple values to
731 the calling form where that is not desired.
732
733 XEmacs implements the Common Lisp specification when it comes to the
734 exact details of when to discard and when to preserve multiple values;
735 see Common Lisp the Language or the Common Lisp hyperspec for more
736 details. The most important thing to keep in mind is when multiple
737 values are passed as an argument to a function, all but the first are
738 discarded.
739 @end defun
740
741 @defun values-list argument
742 This function returns the elements of the lst @var{argument} as multiple
743 values.
744 @end defun
745
746 @defspec multiple-value-bind (var@dots{}) values-form forms@dots{}
747 This special operator evaluates @var{values-form}, which may return
748 multiple values. It then binds the @var{var}s to these respective values,
749 as if by @code{let}, and then executes the body @var{forms}.
750 If there are more @var{var}s than values, the extra @var{var}s
751 are bound to @code{nil}. If there are fewer @var{var}s than
752 values, the excess values are ignored.
753 @end defspec
754
755 @defspec multiple-value-setq (var@dots{}) form
756 This special operator evaluates @var{form}, which may return multiple
757 values. It then sets the @var{var}s to these respective values, as if by
758 @code{setq}. Extra @var{var}s or values are treated the same as
759 in @code{multiple-value-bind}.
760 @end defspec
761
762 @defspec multiple-value-call function forms@dots{}
763 This special operator evaluates function, discarding any multiple
764 values. It then evaluates @var{forms}, preserving any multiple values,
765 and calls @var{function} as a function with the results. Conceptually, this
766 function is a version of @code{apply'}that by-passes the multiple values
767 infrastructure, treating multiple values as intercalated lists.
768 @end defspec
769
770 @defspec multiple-value-list form
771 This special operator evaluates @var{form} and returns a list of the
772 multiple values given by it.
773 @end defspec
774
775 @defspec multiple-value-prog1 first body@dots{}
776 This special operator evaluates the form @var{first}, then the
777 forms @var{body}. It returns the value given by @var{first}, preserving
778 any multiple values. This is identical to @code{prog1}, except that
779 @code{prog1} always discards multiple values.
780 @end defspec
781
782 @defspec nth-value n form
783 This special operator evaluates @var{form} and returns the @var{n}th
784 value it gave. @var{n} must be an integer of value zero or more.
785 If @var{form} gave insufficient multiple values, @code{nth-value}
786 returns @code{nil}.
787 @end defspec
788
789 @defvar multiple-values-limit
790 This constant describes the exclusive upper bound on the number of
791 multiple values that @code{values} accepts and that
792 @code{multiple-value-bind}, etc. will consume.
793 @end defvar
794
795 To take full advantage of multiple values, Emacs Lisp code must have
796 been compiled by XEmacs 21.5 or later, which is not yet true of the
797 XEmacs packages. Matched @code{values} and @code{multiple-value-bind}
798 calls will work in code included in the XEmacs packages when run on
799 21.5, though the following incantation may be necessary at the start of
800 your file, until appropriate code is included in XEmacs 21.4:
801
802 @example
803 (eval-when-compile (when (eq 'list (symbol-function 'values))
804 (define-compiler-macro values (&rest args)
805 (cons 'list args))
806 (define-compiler-macro values-list (list) list)))
807 @end example
808
809 Such code cannot, unfortunately, rely on XEmacs to discard multiple
810 values where that is appropriate.