procyberian/emacs
1
0
Fork 0
Code Issues Pull requests 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
Show stats 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
@group
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
doc: /* Eval args until one of them yields non-nil, then return
that value.
doc: /* Eval args until one of them yields non-nil,
then return that value.
The remaining args are not evalled at all.
If all args return nil, return nil.
@end group
@ -729,7 +729,7 @@ less than 8.
This is an interactive specification, a string such as might be used
as the argument of @code{interactive} in a Lisp function
(@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
function that should receive no arguments when called interactively.
If the value begins with a @samp{"(}, the string is evaluated as a
@ -737,11 +737,11 @@ Lisp form. For example:
@example
@group
DEFUN ("foo", Ffoo, Sfoo, 0, UNEVALLED, 0
DEFUN ("foo", Ffoo, Sfoo, 0, 3,
"(list (read-char-by-name \"Insert character: \")\
(prefix-numeric-value current-prefix-arg)\
t))",
doc: /* @dots{} */)
t)",
doc: /* @dots{} */)
@end group
@end example
@ -771,8 +771,8 @@ this:
@example
@group
DEFUN ("bar", Fbar, Sbar, 0, UNEVALLED, 0
doc: /* @dots{} */
attributes: @var{attr1} @var{attr2} @dots{})
doc: /* @dots{} */
attributes: @var{attr1} @var{attr2} @dots{})
@end group
@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
each argument must be of type @code{Lisp_Object}. (Various macros and
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
the number of Lisp arguments, it must have exactly two C arguments:
the first is the number of Lisp arguments, and the second is the
address of a block containing their values. These have types
@code{int} and @w{@code{Lisp_Object *}} respectively. Since
@code{Lisp_Object} can hold any Lisp object of 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}).
in the file @file{lisp.h}.) If the primitive is a special form, it
must accept a Lisp list containing its unevaluated Lisp arguments as a
single argument of type @code{Lisp_Object}. If the primitive has no
upper limit on the number of evaluated Lisp arguments, it must have
exactly two C arguments: the first is the number of Lisp arguments,
and the second is the address of a block containing their values.
These have types @code{ptrdiff_t} and @w{@code{Lisp_Object *}},
respectively. Since @code{Lisp_Object} can hold any Lisp object of
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 garbage collection protection
@ -906,9 +909,9 @@ of macros and functions to manipulate Lisp objects.
@smallexample
@group
DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
Scoordinates_in_window_p, 2, 2, 0,
doc: /* Return non-nil if COORDINATES are in WINDOW.
...
Scoordinates_in_window_p, 2, 2, 0,
doc: /* Return non-nil if COORDINATES are in WINDOW.
@dots{}
@end group
@group
or `right-margin' is returned. */)
@ -921,16 +924,15 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
@end group
@group
CHECK_LIVE_WINDOW (window);
w = XWINDOW (window);
w = decode_live_window (window);
f = XFRAME (w->frame);
CHECK_CONS (coordinates);
lx = Fcar (coordinates);
ly = Fcdr (coordinates);
CHECK_NUMBER_OR_FLOAT (lx);
CHECK_NUMBER_OR_FLOAT (ly);
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);
CHECK_NUMBER (lx);
CHECK_NUMBER (ly);
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);
@end group
@group
@ -940,14 +942,14 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
return Qnil;
@end group
...
@dots{}
@group
case ON_MODE_LINE: /* In mode line of window. */
return Qmode_line;
@end group
...
@dots{}
@group
case ON_SCROLL_BAR: /* On scroll-bar of window. */
@ -957,7 +959,7 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
@group
default:
abort ();
emacs_abort ();
@}
@}
@end group