New branch for lexbind, losing all history.

This initial patch is based on 2002-06-27T22:39:10Z!storm@cua.dk of the original
lexbind branch.

5 files changed, 125 insertions, 19 deletions

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 0f746187212..46d242fcfba 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -248,7 +248,7 @@ Programming Types
 * Macro Type::          A method of expanding an expression into another
                           expression, more fundamental but less pretty.
 * Primitive Function Type::     A function written in C, callable from Lisp.
-* Byte-Code Type::      A function written in Lisp, then compiled.
+* Funvec Type::         A vector type callable as a function.
 * Autoload Type::       A type used for automatically loading seldom-used
                           functions.
 
@@ -463,10 +463,11 @@ Functions
 * Inline Functions::        Defining functions that the compiler
                               will open code.
 * Declaring Functions::     Telling the compiler that a function is defined.
+* Function Currying::       Making wrapper functions that pre-specify
+                              some arguments.
 * Function Safety::         Determining whether a function is safe to call.
 * Related Topics::          Cross-references to specific Lisp primitives
-                              that have a special bearing on how
-                              functions work.
+                              that have a special bearing on how functions work.
 
 Lambda Expressions
 
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 37e8726592a..7e8ac09b44e 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -22,7 +22,9 @@ define them.
 * Function Cells::        Accessing or setting the function definition
                             of a symbol.
 * Obsolete Functions::    Declaring functions obsolete.
-* Inline Functions::      Defining functions that the compiler will open code.
+* Inline Functions::      Defining functions that the compiler will open code.
+* Function Currying::     Making wrapper functions that pre-specify
+                            some arguments.
 * Declaring Functions::   Telling the compiler that a function is defined.
 * Function Safety::       Determining whether a function is safe to call.
 * Related Topics::        Cross-references to specific Lisp primitives
@@ -111,7 +113,25 @@ editors; for Lisp programs, the distinction is normally unimportant.
 
 @item byte-code function
 A @dfn{byte-code function} is a function that has been compiled by the
-byte compiler.  @xref{Byte-Code Type}.
+byte compiler.  A byte-code function is actually a special case of a
+@dfn{funvec} object (see below).
+
+@item function vector
+A @dfn{function vector}, or @dfn{funvec} is a vector-like object whose
+purpose is to define special kinds of functions.  @xref{Funvec Type}.
+
+The exact meaning of the vector elements is determined by the type of
+funvec: the most common use is byte-code functions, which have a
+list---the argument list---as the first element.  Further types of
+funvec object are:
+
+@table @code
+@item curry
+A curried function.  Remaining arguments in the funvec are function to
+call, and arguments to prepend to user arguments at the time of the
+call; @xref{Function Currying}.
+@end table
+
 @end table
 
 @defun functionp object
@@ -152,6 +172,11 @@ function.  For example:
 @end example
 @end defun
 
+@defun funvecp object
+@code{funvecp} returns @code{t} if @var{object} is a function vector
+object (including byte-code objects), and @code{nil} otherwise.
+@end defun
+
 @defun subr-arity subr
 This function provides information about the argument list of a
 primitive, @var{subr}.  The returned value is a pair
@@ -1277,6 +1302,49 @@ do for macros.  (@xref{Argument Evaluation}.)
 Inline functions can be used and open-coded later on in the same file,
 following the definition, just like macros.
 
+@node Function Currying
+@section Function Currying
+@cindex function currying
+@cindex currying
+@cindex partial-application
+
+Function currying is a way to make a new function that calls an
+existing function with a partially pre-determined argument list.
+
+@defun curry function &rest args
+Return a function-like object that will append any arguments it is
+called with to @var{args}, and call @var{function} with the resulting
+list of arguments.
+
+For example, @code{(curry 'concat "The ")} returns a function that
+concatenates @code{"The "} and its arguments.  Calling this function
+on @code{"end"} returns @code{"The end"}:
+
+@example
+(funcall (curry 'concat "The ") "end")
+     @result{} "The end"
+@end example
+
+The @dfn{curried function} is useful as an argument to @code{mapcar}:
+
+@example
+(mapcar (curry 'concat "The ") '("big" "red" "balloon"))
+     @result{} ("The big" "The red" "The balloon")
+@end example
+@end defun
+
+Function currying may be implemented in any Lisp by constructing a
+@code{lambda} expression, for instance:
+
+@example
+(defun curry (function &rest args)
+  `(lambda (&rest call-args)
+      (apply #',function ,@@args call-args)))
+@end example
+
+However in Emacs Lisp, a special curried function object is used for
+efficiency.  @xref{Funvec Type}.
+
 @node Declaring Functions
 @section Telling the Compiler that a Function is Defined
 @cindex function declaration
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 5c3ac13cdaf..1a72fdf671c 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -157,7 +157,7 @@ latter are unique to Emacs Lisp.
 * Macro Type::          A method of expanding an expression into another
                           expression, more fundamental but less pretty.
 * Primitive Function Type::     A function written in C, callable from Lisp.
-* Byte-Code Type::      A function written in Lisp, then compiled.
+* Funvec Type::         A vector type callable as a function.
 * Autoload Type::       A type used for automatically loading seldom-used
                         functions.
 @end menu
@@ -1315,18 +1315,55 @@ with the name of the subroutine.
 @end group
 @end example
 
-@node Byte-Code Type
-@subsection Byte-Code Function Type
+@node Funvec Type
+@subsection ``Function Vector' Type
+@cindex function vector
+@cindex funvec
 
-The byte compiler produces @dfn{byte-code function objects}.
-Internally, a byte-code function object is much like a vector; however,
-the evaluator handles this data type specially when it appears as a
-function to be called.  @xref{Byte Compilation}, for information about
-the byte compiler.
+A @dfn{function vector}, or @dfn{funvec} is a vector-like object whose
+purpose is to define special kinds of functions.  You can examine or
+modify the contents of a funvec like a normal vector, using the
+@code{aref} and @code{aset} functions.
 
-The printed representation and read syntax for a byte-code function
-object is like that for a vector, with an additional @samp{#} before the
-opening @samp{[}.
+The behavior of a funvec when called is dependent on the kind of
+funvec it is, and that is determined by its first element (a
+zero-length funvec will signal an error if called):
+
+@table @asis
+@item A list
+A funvec with a list as its first element is a byte-compiled function,
+produced by the byte compiler; such funvecs are known as
+@dfn{byte-code function objects}.  @xref{Byte Compilation}, for
+information about the byte compiler.
+
+@item The symbol @code{curry}
+A funvec with @code{curry} as its first element is a ``curried function''.
+
+The second element in such a funvec is the function which is
+being curried, and the remaining elements are a list of arguments.
+
+Calling such a funvec operates by calling the embedded function with
+an argument list composed of the arguments in the funvec followed by
+the arguments the funvec was called with.  @xref{Function Currying}.
+@end table
+
+The printed representation and read syntax for a funvec object is like
+that for a vector, with an additional @samp{#} before the opening
+@samp{[}.
+
+@defun funvecp object
+@code{funvecp} returns @code{t} if @var{object} is a function vector
+object (including byte-code objects), and @code{nil} otherwise.
+@end defun
+
+@defun funvec kind &rest params
+@code{funvec} returns a new function vector containing @var{kind} and
+@var{params}.  @var{kind} determines the type of funvec; it should be
+one of the choices listed in the table above.
+
+Typically you should use the @code{make-byte-code} function to create
+byte-code objects, though they are a type of funvec.
+@end defun
 
 @node Autoload Type
 @subsection Autoload Type
@@ -1773,7 +1810,7 @@ with references to further information.
 @xref{Buffer Basics, bufferp}.
 
 @item byte-code-function-p
-@xref{Byte-Code Type, byte-code-function-p}.
+@xref{Funvec Type, byte-code-function-p}.
 
 @item case-table-p
 @xref{Case Tables, case-table-p}.
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index a0590c3d282..052d83eacd7 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -268,7 +268,7 @@ Programming Types
 * Macro Type::          A method of expanding an expression into another
                           expression, more fundamental but less pretty.
 * Primitive Function Type::     A function written in C, callable from Lisp.
-* Byte-Code Type::      A function written in Lisp, then compiled.
+* Funvec Type::         A vector type callable as a function.
 * Autoload Type::       A type used for automatically loading seldom-used
                           functions.
 
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index ad4c74611a8..d6358f3ecfc 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -267,7 +267,7 @@ Programming Types
 * Macro Type::          A method of expanding an expression into another
                           expression, more fundamental but less pretty.
 * Primitive Function Type::     A function written in C, callable from Lisp.
-* Byte-Code Type::      A function written in Lisp, then compiled.
+* Funvec Type::         A vector type callable as a function.
 * Autoload Type::       A type used for automatically loading seldom-used
                           functions.