@group
while (CONSP (args))
@{
- val = Feval (XCAR (args));
+ val = eval_sub (XCAR (args));
if (!NILP (val))
break;
args = XCDR (args);
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 Lisp form.
+For examples of the last two forms, see @code{widen} and
+@code{narrow-to-region} in @file{editfns.c}.
@item doc
This is the documentation string. It uses C comment syntax rather
``protect'' a variable from garbage collection---to inform the garbage
collector that it must look in that variable and regard its contents
as an accessible object. GC protection is necessary whenever you call
-@code{Feval} or anything that can directly or indirectly call
-@code{Feval}. At such a time, any Lisp object that this function may
-refer to again must be protected somehow.
+@code{eval_sub} (or @code{Feval}) either directly or indirectly.
+At such a time, any Lisp object that this function may refer to again
+must be protected somehow.
It suffices to ensure that at least one pointer to each object is
GC-protected; that way, the object cannot be recycled, so all pointers
to it remain valid. Thus, a particular local variable can do without
protection if it is certain that the object it points to will be
-preserved by some other pointer (such as another local variable which
-has a @code{GCPRO})@footnote{Formerly, strings were a special
-exception; in older Emacs versions, every local variable that might
-point to a string needed a @code{GCPRO}.}. Otherwise, the local
-variable needs a @code{GCPRO}.
+preserved by some other pointer (such as another local variable that
+has a @code{GCPRO}).
+@ignore
+@footnote{Formerly, strings were a special exception; in older Emacs
+versions, every local variable that might point to a string needed a
+@code{GCPRO}.}.
+@end ignore
+Otherwise, the local variable needs a @code{GCPRO}.
The macro @code{GCPRO1} protects just one local variable. If you
want to protect two variables, use @code{GCPRO2} instead; repeating
read-only (on certain operating systems) as a result of dumping Emacs.
@xref{Pure Storage}.
+@c FIXME is this still true? I don't think so...
Do not use static variables within functions---place all static
variables at top level in the file. This is necessary because Emacs on
some operating systems defines the keyword @code{static} as a null
this:
@example
-defsubr (&@var{subr-structure-name});
+defsubr (&@var{sname});
@end example
@noindent
-Here @var{subr-structure-name} is the name you used as the third
-argument to @code{DEFUN}.
+Here @var{sname} is the name you used as the third argument to @code{DEFUN}.
If you add a new primitive to a file that already has Lisp primitives
defined in it, find the function (near the end of the file) named
defined with @code{DEFVAR_BOOL} are automatically added to the list
@code{byte-boolean-vars} used by the byte compiler.
+@cindex defining customization variables in C
+ If you want to make a Lisp variables that is defined in C behave
+like one declared with @code{defcustom}, add an appropriate entry to
+@file{cus-start.el}.
+
@cindex @code{staticpro}, protection from GC
If you define a file-scope C variable of type @code{Lisp_Object},
you must protect it from garbage-collection by calling @code{staticpro}
@smallexample
@group
DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
- Scoordinates_in_window_p, 2, 2,
- "xSpecify coordinate pair: \nXExpression which evals to window: ",
- "Return non-nil if COORDINATES is in WINDOW.\n\
-COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
-...
+ Scoordinates_in_window_p, 2, 2, 0,
+ doc: /* Return non-nil if COORDINATES are in WINDOW.
+ ...
@end group
@group
-If they are on the border between WINDOW and its right sibling,\n\
- `vertical-line' is returned.")
- (coordinates, window)
- register Lisp_Object coordinates, window;
+ or `right-margin' is returned. */)
+ (register Lisp_Object coordinates, Lisp_Object window)
@{
+ struct window *w;
+ struct frame *f;
int x, y;
+ Lisp_Object lx, ly;
@end group
@group
- CHECK_LIVE_WINDOW (window, 0);
- CHECK_CONS (coordinates, 1);
- x = XINT (Fcar (coordinates));
- y = XINT (Fcdr (coordinates));
+ CHECK_LIVE_WINDOW (window);
+ w = XWINDOW (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);
@end group
@group
- switch (coordinates_in_window (XWINDOW (window), &x, &y))
+ switch (coordinates_in_window (w, x, y))
@{
- case 0: /* NOT in window at all. */
+ case ON_NOTHING: /* NOT in window at all. */
return Qnil;
@end group
-@group
- case 1: /* In text part of window. */
- return Fcons (make_number (x), make_number (y));
-@end group
+ ...
@group
- case 2: /* In mode line of window. */
+ case ON_MODE_LINE: /* In mode line of window. */
return Qmode_line;
@end group
+ ...
+
@group
- case 3: /* On right border of window. */
- return Qvertical_line;
+ case ON_SCROLL_BAR: /* On scroll-bar of window. */
+ /* Historically we are supposed to return nil in this case. */
+ return Qnil;
@end group
@group
functions.
If you define a function which is side-effect free, update the code
-in @file{byte-opt.el} which binds @code{side-effect-free-fns} and
+in @file{byte-opt.el} that binds @code{side-effect-free-fns} and
@code{side-effect-and-error-free-fns} so that the compiler optimizer
knows about it.
@section Object Internals
@cindex object internals
+@c FIXME Is this still true? Does --with-wide-int affect anything?
GNU Emacs Lisp manipulates many different types of data. The actual
data are stored in a heap and the only access that programs have to it
is through pointers. Each pointer is 32 bits wide on 32-bit machines,
@cindex internals, of buffer
@cindex buffer internals
- Two structures are used to represent buffers in C. The
-@code{buffer_text} structure contains fields describing the text of a
-buffer; the @code{buffer} structure holds other fields. In the case
-of indirect buffers, two or more @code{buffer} structures reference
-the same @code{buffer_text} structure.
+ Two structures (see @file{buffer.h}) are used to represent buffers
+in C. The @code{buffer_text} structure contains fields describing the
+text of a buffer; the @code{buffer} structure holds other fields. In
+the case of indirect buffers, two or more @code{buffer} structures
+reference the same @code{buffer_text} structure.
Here are some of the fields in @code{struct buffer_text}:
Some of the fields of @code{struct buffer} are:
@table @code
-@item next
-Points to the next buffer, in the chain of all buffers (including
+@item header
+A @code{struct vectorlike_header} structure where @code{header.next}
+points to the next buffer, in the chain of all buffers (including
killed buffers). This chain is used only for garbage collection, in
order to collect killed buffers properly. Note that vectors, and most
kinds of objects allocated as vectors, are all on one chain, but
and @code{overlays_after} is sorted in order of increasing beginning
position.
+@c FIXME? the following are now all Lisp_Object BUFFER_INTERNAL_FIELD (foo).
+
@item name
A Lisp string that names the buffer. It is guaranteed to be unique.
@xref{Buffer Names}.
@item undo_list
@itemx backed_up
@itemx auto_save_file_name
+@itemx auto_save_file_format
@itemx read_only
@itemx file_format
@itemx file_truename
@itemx truncate_lines
@itemx word_wrap
@itemx ctl_arrow
+@itemx bidi_display_reordering
+@itemx bidi_paragraph_direction
@itemx selective_display
@itemx selective_display_ellipses
@itemx overwrite_mode
@itemx abbrev_mode
-@itemx display_table
@itemx mark_active
@itemx enable_multibyte_characters
@itemx buffer_file_coding_system
-@itemx auto_save_file_format
@itemx cache_long_line_scans
@itemx point_before_scroll
@itemx left_fringe_width
@cindex internals, of window
@cindex window internals
- Windows have the following accessible fields:
+ The fields of a window (for a complete list, see the definition of
+@code{struct window} in @file{window.h}) include:
@table @code
@item frame
These fields contain the window's leftmost child and its topmost child
respectively. @code{hchild} is used if the window is subdivided
horizontally by child windows, and @code{vchild} if it is subdivided
-vertically.
+vertically. In a live window, only one of @code{hchild}, @code{vchild},
+and @code{buffer} (q.v.) is non-@code{nil}.
@item next
@itemx prev
@item vertical_scroll_bar
This window's vertical scroll bar.
-@item left_margin_width
-@itemx right_margin_width
+@item left_margin_cols
+@itemx right_margin_cols
The widths of the left and right margins in this window. A value of
-@code{nil} means to use the buffer's value of @code{left-margin-width}
-or @code{right-margin-width}.
+@code{nil} means no margin.
+
+@item left_fringe_width
+@itemx right_fringe_width
+The widths of the left and right fringes in this window. A value of
+@code{nil} or @code{t} means use the values of the frame.
+
+@item fringes_outside_margins
+A non-@code{nil} value means the fringes outside the display margins;
+othersize they are between the margin and the text.
@item window_end_pos
This is computed as @code{z} minus the buffer position of the last glyph
@item window_end_valid
This field is set to a non-@code{nil} value if @code{window_end_pos} is truly
-valid. This is @code{nil} if nontrivial redisplay is preempted since in that
+valid. This is @code{nil} if nontrivial redisplay is pre-empted, since in that
case the display that @code{window_end_pos} was computed for did not get
onto the screen.
A structure describing where the cursor of this window physically is.
@item phys_cursor_type
-The type of cursor that was last displayed on this window.
+@c FIXME What is this?
+@c itemx phys_cursor_ascent
+@itemx phys_cursor_height
+@itemx phys_cursor_width
+The type, height, and width of the cursor that was last displayed on
+this window.
@item phys_cursor_on_p
This field is non-zero if the cursor is physically on.
@item cursor_off_p
-Non-zero means the cursor in this window is logically on.
+Non-zero means the cursor in this window is logically off. This is
+used for blinking the cursor.
@item last_cursor_off_p
This field contains the value of @code{cursor_off_p} as of the time of
@item base_line_pos
The position in the buffer for which the line number is known, or
-@code{nil} meaning none is known.
+@code{nil} meaning none is known. If it is a buffer, don't display
+the line number as long as the window shows that buffer.
@item region_showing
If the region (or part of it) is highlighted in this window, this field
if column numbers are not being displayed.
@item current_matrix
-A glyph matrix describing the current display of this window.
-
-@item desired_matrix
-A glyph matrix describing the desired display of this window.
+@itemx desired_matrix
+Glyph matrices describing the current and desired display of this window.
@end table
@node Process Internals
@cindex internals, of process
@cindex process internals
- The fields of a process are:
+ The fields of a process (for a complete list, see the definition of
+@code{struct Lisp_Process} in @file{process.h}) include:
@table @code
@item name
process is running or @code{t} if the process is stopped.
@item filter
-A function used to accept output from the process instead of a buffer,
-or @code{nil}.
+If non-@code{nil}, a function used to accept output from the process
+instead of a buffer.
@item sentinel
-A function called whenever the process receives a signal, or @code{nil}.
+If non-@code{nil}, a function called whenever the state of the process
+changes.
@item buffer
The associated buffer of the process.
@item pid
An integer, the operating system's process @acronym{ID}.
+Pseudo-processes such as network or serial connections use a value of 0.
@item childp
-A flag, non-@code{nil} if this is really a child process.
-It is @code{nil} for a network or serial connection.
+A flag, @code{t} if this is really a child process. For a network or
+serial connection, it is a plist based on the arguments to
+@code{make-network-process} or @code{make-serial-process}.
@item mark
A marker indicating the position of the end of the last output from this
If this is non-zero, killing Emacs while this process is still running
does not ask for confirmation about killing the process.
-@item raw_status_low
-@itemx raw_status_high
-These two fields record 16 bits each of the process status returned by
-the @code{wait} system call.
+@item raw_status
+The raw process status, as returned by the @code{wait} system call.
@item status
The process status, as @code{process-status} should return it.
@item outfd
The file descriptor for output to the process.
-@item subtty
-The file descriptor for the terminal that the subprocess is using. (On
-some systems, there is no need to record this, so the value is
-@code{nil}.)
-
@item tty_name
The name of the terminal that the subprocess is using,
or @code{nil} if it is using pipes.
@item encoding_buf
A working buffer for encoding.
-@item encoding_carryover
-Size of carryover in encoding.
-
@item inherit_coding_system_flag
Flag to set @code{coding-system} of the process buffer from the
coding system used to decode process output.
@item type
Symbol indicating the type of process: @code{real}, @code{network},
-@code{serial}
+@code{serial}.
@end table
+
+@c FIXME Mention src/globals.h somewhere in this file?