masscollaborationlabs/emacs
2
0
Fork 0
mirror of https://github.com/masscollaborationlabs/emacs.git synced 2025-07-11 14:40:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Clarify & update (elisp) Writing Emacs Primitives

Browse source 
* doc/lispref/internals.texi (Writing Emacs Primitives): Update some
of the sample code listings, fixing argument lists and parentheses.
Replace ... with @dots{}.  Describe UNEVALLED special forms as
taking a single argument. (bug#36392)
This commit is contained in:
Basil L. Contovounesios 2019-06-26 22:13:34 +01:00
parent 7648c125df
commit 8b775c30ad
1 changed files with 31 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

60
doc/lispref/internals.texi
View file

@ -654,8 +654,8 @@ appearance.)
@smallexample @smallexample
@group @group
DEFUN ("or", For, Sor, 0, UNEVALLED, 0, DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
doc: /* Eval args until one of them yields non-nil, then return doc: /* Eval args until one of them yields non-nil,
that value. then return that value.
The remaining args are not evalled at all. The remaining args are not evalled at all.
If all args return nil, return nil. If all args return nil, return nil.
@end group @end group
@ -729,7 +729,7 @@ less than 8.
This is an interactive specification, a string such as might be used This is an interactive specification, a string such as might be used
as the argument of @code{interactive} in a Lisp function as the argument of @code{interactive} in a Lisp function
(@pxref{Using Interactive}). In the case (@pxref{Using Interactive}). In the case
of @code{or}, it is 0 (a null pointer), indicating that @code{or} of @code{or}, it is @code{0} (a null pointer), indicating that @code{or}
cannot be called interactively. A value of @code{""} indicates a cannot be called interactively. A value of @code{""} indicates a
function that should receive no arguments when called interactively. function that should receive no arguments when called interactively.
If the value begins with a @samp{"(}, the string is evaluated as a If the value begins with a @samp{"(}, the string is evaluated as a
@ -737,11 +737,11 @@ Lisp form. For example:
@example @example
@group @group
DEFUN ("foo", Ffoo, Sfoo, 0, UNEVALLED, 0 DEFUN ("foo", Ffoo, Sfoo, 0, 3,
"(list (read-char-by-name \"Insert character: \")\ "(list (read-char-by-name \"Insert character: \")\
(prefix-numeric-value current-prefix-arg)\ (prefix-numeric-value current-prefix-arg)\
t))", t)",
doc: /* @dots{} */) doc: /* @dots{} */)
@end group @end group
@end example @end example
@ -771,8 +771,8 @@ this:
@example @example
@group @group
DEFUN ("bar", Fbar, Sbar, 0, UNEVALLED, 0 DEFUN ("bar", Fbar, Sbar, 0, UNEVALLED, 0
doc: /* @dots{} */ doc: /* @dots{} */
attributes: @var{attr1} @var{attr2} @dots{}) attributes: @var{attr1} @var{attr2} @dots{})
@end group @end group
@end example @end example
@ -808,15 +808,18 @@ arguments. If the primitive accepts a fixed maximum number of Lisp
arguments, there must be one C argument for each Lisp argument, and arguments, there must be one C argument for each Lisp argument, and
each argument must be of type @code{Lisp_Object}. (Various macros and each argument must be of type @code{Lisp_Object}. (Various macros and
functions for creating values of type @code{Lisp_Object} are declared functions for creating values of type @code{Lisp_Object} are declared
in the file @file{lisp.h}.) If the primitive has no upper limit on in the file @file{lisp.h}.) If the primitive is a special form, it
the number of Lisp arguments, it must have exactly two C arguments: must accept a Lisp list containing its unevaluated Lisp arguments as a
the first is the number of Lisp arguments, and the second is the single argument of type @code{Lisp_Object}. If the primitive has no
address of a block containing their values. These have types upper limit on the number of evaluated Lisp arguments, it must have
@code{int} and @w{@code{Lisp_Object *}} respectively. Since exactly two C arguments: the first is the number of Lisp arguments,
@code{Lisp_Object} can hold any Lisp object of any data type, you and the second is the address of a block containing their values.
can determine the actual data type only at run time; so if you want These have types @code{ptrdiff_t} and @w{@code{Lisp_Object *}},
a primitive to accept only a certain type of argument, you must check respectively. Since @code{Lisp_Object} can hold any Lisp object of
the type explicitly using a suitable predicate (@pxref{Type Predicates}). any data type, you can determine the actual data type only at run
time; so if you want a primitive to accept only a certain type of
argument, you must check the type explicitly using a suitable
predicate (@pxref{Type Predicates}).
@cindex type checking internals @cindex type checking internals
@cindex garbage collection protection @cindex garbage collection protection
@ -906,9 +909,9 @@ of macros and functions to manipulate Lisp objects.
@smallexample @smallexample
@group @group
DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
Scoordinates_in_window_p, 2, 2, 0, Scoordinates_in_window_p, 2, 2, 0,
doc: /* Return non-nil if COORDINATES are in WINDOW. doc: /* Return non-nil if COORDINATES are in WINDOW.
... @dots{}
@end group @end group
@group @group
or `right-margin' is returned. */) or `right-margin' is returned. */)
@ -921,16 +924,15 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
@end group @end group
@group @group
CHECK_LIVE_WINDOW (window); w = decode_live_window (window);
w = XWINDOW (window);
f = XFRAME (w->frame); f = XFRAME (w->frame);
CHECK_CONS (coordinates); CHECK_CONS (coordinates);
lx = Fcar (coordinates); lx = Fcar (coordinates);
ly = Fcdr (coordinates); ly = Fcdr (coordinates);
CHECK_NUMBER_OR_FLOAT (lx); CHECK_NUMBER (lx);
CHECK_NUMBER_OR_FLOAT (ly); CHECK_NUMBER (ly);
x = FRAME_PIXEL_X_FROM_CANON_X (f, lx) + FRAME_INTERNAL_BORDER_WIDTH(f); x = FRAME_PIXEL_X_FROM_CANON_X (f, lx) + FRAME_INTERNAL_BORDER_WIDTH (f);
y = FRAME_PIXEL_Y_FROM_CANON_Y (f, ly) + FRAME_INTERNAL_BORDER_WIDTH(f); y = FRAME_PIXEL_Y_FROM_CANON_Y (f, ly) + FRAME_INTERNAL_BORDER_WIDTH (f);
@end group @end group
@group @group
@ -940,14 +942,14 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
return Qnil; return Qnil;
@end group @end group
... @dots{}
@group @group
case ON_MODE_LINE: /* In mode line of window. */ case ON_MODE_LINE: /* In mode line of window. */
return Qmode_line; return Qmode_line;
@end group @end group
... @dots{}
@group @group
case ON_SCROLL_BAR: /* On scroll-bar of window. */ case ON_SCROLL_BAR: /* On scroll-bar of window. */
@ -957,7 +959,7 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
@group @group
default: default:
abort (); emacs_abort ();
@} @}
@} @}
@end group @end group