|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T l
Length: 52024 (0xcb38)
Types: TextFile
Names: »lispref-18«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-18«
Info file: lispref, -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo
This file documents GNU Emacs Lisp.
This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.
Please read this document for review purposes.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1989 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
▶1f◀
File: lispref Node: Terminal Output, Prev: Terminal Input, Up: Operating System Interface, Next: Flow Control
Terminal Output
===============
The terminal output functions send or keep track of output sent from
the computer to the terminal. The `baud-rate' variable tells you what
Emacs think is the output baud rate of the terminal.
* Function: baud-rate
This function returns the output baud rate of the terminal.
(note: In version 18, baud-rate is a function, but in version
19, it is a variable.)
(baud-rate)
=> 9600
If you are running across a network, and different parts of the
network work at different baud rates, the value returned by Emacs
may be different from the value used by your local terminal. This
can be a problem with the network.
* Function: send-string-to-terminal STRING
This function sends STRING to the terminal without alteration.
Control characters in STRING will have terminal-dependent effects.
Typically, this function is used to define defining function keys
on terminals that have down-loadable function key definitions.
The example below might define function key 4 to move forward
four characters (`C-u C-f').
(send-string-to-terminal "\eF4\^U\^F")
=> nil
* Command: open-termscript FILENAME
After this function is called, Emacs copies all terminal output
characters to FILENAME as well to the terminal. It returns `nil'.
This function is normally only called interactively to debug Emacs
output.
Seealso `open-dribble-file' in *Note Terminal Input::.
(open-termscript "../junk/termscript")
=> nil
▶1f◀
File: lispref Node: Flow Control, Prev: Terminal Output, Up: Operating System Interface
Flow Control
============
This section attempts to answer the question ``Why does Emacs choose
to use flow-control characters in its command character set?'' For a
second view on this issue, please read the comments on flow control in
the `emacs/INSTALL' file from the distribution; for help with termcaps
and DEC terminal concentrators, see `emacs/etc/TERMS'.
At one time, most terminals did not need flow control. This meant
that the choice of `C-s' and `C-q' as command characters was reasonable.
Emacs, for economy of keystrokes and portability, chose to use the
control characters in the ASCII character set, and tried to make the
assignments mnemonic (thus, `S' for search and `Q' for quote).
(There are other (albeit less common in practice) ways to do flow
control, not using `C-s' and `C-q', that preserve transparency of the
character stream; these ways are not discussed here.)
After Emacs's precedent was established, it was too hard to undo:
Emacs' use of `C-s' and `C-q' predates their use by terminals and
front-ends for flow control. Note also that their use for flow control
is not an official standard. Interestingly, on the model 33 teletype
with a paper tape punch (which is very old), `C-s' and `C-q' were used
for the host to turn the punch on and off!
So which usage is `right', Emacs's or that of some terminal and
front-end manufacturers? This is a rhetorical (or religious) question;
it has no simple answer.
GNU Emacs (version 18.48 and later) provides several options for
coping with terminals or front-ends that insist on using flow control
characters. Listed in estimated order of preference, these options are
as follows:
1.
Have Emacs run in CBREAK mode with the kernel handling flow
control. Issue `(set-input-mode nil t)' from `.emacs'. After
doing this, it will be necessary to find other keys to bind to the
commands `isearch-forward' and `quoted-insert'. The traditional
nominees are `C-^' and `C-\'. There are two ways to get this
effect:
1a.
Use the `keyboard-translate-table' to cause `C-^' and `C-\'
to be received by Emacs as though `C-s' and `C-q' were typed.
Emacs (except at its very lowest level) never knows that the
characters typed were anything but `C-s' and `C-q', so the use
of these keys inside `isearch-forward' still works---typing
`C-^' while incremental searching will move the cursor to the
next match, etc. Here's some code for this:
(setq keyboard-translate-table (make-string 128 0))
(let ((i 0))
(while (< i 128)
(aset keyboard-translate-table i i)
(setq i (1+ i))))
(aset keyboard-translate-table ?\^\\ ?\^s)
(aset keyboard-translate-table ?\^^ ?\^q)
))
1b.
Simply rebind the keys `C-^' and `C-\' to `isearch-forward'
and `quoted-insert'. To get continued searches inside isearch
it is also necessary to set `search-repeat-char' to `C-^', as
well.
2.
Don't use CBREAK mode, but cause `C-s' and `C-q' to be bound to a
null command. The problem with this solution is that the flow
control characters were probably sent because whatever sent them is
falling behind on the characters being sent to it. The characters
that find their way to the terminal screen will not in general be
those that are intended. Also, it will be be necessary to find
other keys to bind to `isearch-forward' and `quoted-insert'; see 1a
and 1b above.
Here is a suitable null command:
(defun noop ()
"Do nothing; return nil."
(interactive))
3.
Don't use CBREAK mode, and unset the `C-s' and `C-Q' keys with
the `global-unset-key' function. This is similar to 2 above,
except that the flow control characters will probably cause beeps
or visible bells.
Note that if the terminal is the source of the flow control
characters and kernel flow control handling is enabled, you
probably will not have to to send padding characters as specified
in a termcap or terminfo entry. In this case, it may be possible
to customize a termcap entry to provide better Emacs performance on
the assumption that flow control is in use. This effect can also
be simulated by announcing (with `stty' or its equivalent) that the
terminal is running at a very slow speed, provided the terminal is
not directly wired to the host.
▶1f◀
File: lispref Node: Emacs Display, Prev: Operating System Interface, Up: Top, Next: Tips and Standards
Emacs Display
*************
This chapter describes a number of features related to the display that
Emacs presents to the user.
* Menu:
* Window Systems:: Which window system is being used
* Screen Attributes:: How big is the Emacs screen
* Truncation:: Folding or wrapping long text lines
* The Echo Area:: Where messages are displayed
* Selective Display:: Hiding part of the buffer text
* Overlay Arrow:: Display of an arrow to indicate position
* Temporary Displays:: Displays that go away automatically
* Waiting:: Forcing display update and waiting for user
* Blinking:: Bouncing the cursor
* Displaying Control Characters:: How control characters are displayed
* Command: redraw-display
This function clears the screen and redraws what is supposed to
appear on it.
▶1f◀
File: lispref Node: Window Systems, Prev: Emacs Display, Up: Emacs Display, Next: Screen Attributes
Window Systems
==============
Emacs works with several window systems, most notably, X.
* Variable: window-setup-hook
The value of the `window-setup-hook' variable is either `nil' or
that of a function that Emacs calls after loading your `.emacs'
file, the default initialization file (if any), after loading
terminal-specific lisp code, and after calling `term-setup-hook'.
`window-setup-hook' is called with no arguments.
* Variable: window-system
This global variable tells Emacs what window system it is running
under. Its value should be a symbol such as `x' (if Emacs is
running under X) or `nil' (if Emacs is running on an ordinary
terminal).
* Variable: window-system-version
This variable will be either 10 or 11 when using the X window
system.
▶1f◀
File: lispref Node: Screen Attributes, Prev: Window Systems, Up: Emacs Display, Next: Truncation
Screen Attributes
=================
The screen attribute functions describe and define the characteristics
of your terminal.
* Function: screen-height
This function returns number of lines on the screen that are
available for display.
(screen-height)
=> 50
* Function: set-screen-height LINES &optional NOT-ACTUAL-SIZE
This function declares that the terminal can display LINES lines.
The sizes of existing windows will be altered proportionally to
fit.
If NOT-ACTUAL-SIZE is non-`nil', then Emacs should use LINES for
display, but it will still know about the actual size of the
screen. Knowing the correct actual size may be necessary for
correct cursor positioning.
If LINES is different from what it was previously, Emacs will
redisplay the screen using the new size.
It returns `nil'.
* Function: screen-width
This function returns number of columns on the screen that are
available for display.
(screen-width)
=> 80
* Function: set-screen-width COLUMNS &optional NOT-ACTUAL-SIZE
This function declares that the terminal can display COLUMNS
columns.
NOT-ACTUAL-SIZE is the same as in `set-screen-height'.
If COLUMNS is different from what it was previously, Emacs will
redisplay the screen using the new size.
It returns `nil'.
* Variable: no-redraw-on-reenter
This global variable determines whether Emacs should redraw the
entire screen after it has been suspended and resumed. `t' means
do, `nil' means don't. This is useful if the terminal can remember
and restore the Emacs screen.
* Variable: inverse-video
This global variable determines whether Emacs will use inverse
video for all text on the screen. `t' means do, `nil' means don't.
* User Option: mode-line-inverse-video
This variable determines how the mode line will be displayed. If
it is non-`nil', then the mode line will use inverse video (or
another suitable display mode). Otherwise the mode line will be in
normal display, just like the rest of the screen.
▶1f◀
File: lispref Node: Truncation, Prev: Screen Attributes, Up: Emacs Display, Next: The Echo Area
Truncation
==========
When a line of text extends beyond the right edge of a window, the
line can either be truncated or continued on the next line. When a line
is trucated, this is shown with a `$' in the right most column of the
window. When a line is continued or `wrapped' onto the next line, this
is shown with a `\' on the right most column of the window. Lines that
continue onto the next line are called "continuation" lines. (Note that
wrapped lines are not filled. Filling has nothing to do with truncation
and continuation. *Note Auto Filling::.)
* User Option: truncate-lines
This per-buffer-local variable controls how Emacs displays lines
that extend beyond the right edge of the window. If it is
non-`nil', then Emacs will not display continuation lines; but
rather each line of text will take exactly one screen line and a
dollar sign will be shown at the edge of any line that extends to
or beyond the edge of the window.
This variable is overridden by the variable
`truncate-partial-width-windows' if that variable is non-`nil' and
the window in question is not the full width of the screen.
* Variable: default-truncate-lines
This variable is the default value for `truncate-lines' in
buffers that do not override it.
* User Option: truncate-partial-width-windows
This variable determines how lines that are too wide to fit on
the screen are displayed in side-by-side windows (*Note Splitting
Windows::). If it is non-`nil', then wide lines will be truncated
(with a `$' at the end of the line), otherwise they will be wrapped
(with a `\' at the end of the line).
▶1f◀
File: lispref Node: The Echo Area, Prev: Truncation, Up: Emacs Display, Next: Selective Display
The Echo Area
=============
The minibuffer is *not* the "echo area", despite the fact that they
occupy the same physical space on the screen. The echo area is where
messages from Emacs are displayed, using the `message' primitive or
something similar. The `GNU Emacs Manual' specifies the rules for how
conflicts between use of the echo area and the minibuffer are resolved
(*Note The Minibuffer: (emacs)Minibuffer.).
* Function: message STRING &rest ARGUMENTS
This function prints a one-line message in the echo area. STRING
is similar to a C language `printf' control string. See `format'
in *Note Conversion of Characters and Strings:: for the details on
the conversion specifications. It returns the constructed string.
(message "Minibuffer depth is %d." (minibuffer-depth))
-| "Minibuffer depth is 0."
---------- Echo Area ----------
Minibuffer depth is 0.
---------- Echo Area ----------
* Variable: cursor-in-echo-area
This global variable controls where the cursor will be placed
when a message is displayed in the echo area. If it is non-`nil',
then do put the cursor there.
▶1f◀
File: lispref Node: Selective Display, Prev: The Echo Area, Up: Emacs Display, Next: Overlay Arrow
Selective Display
=================
Selective display causes specially marked lines not to appear, or
indented lines not to appear. Outline mode uses selective display.
In first variant, the user inserts strings that Emacs recognizes as
marking a heading, such as an `*' and `**', or `@chapter' and
`@section'; in the other variant, the user inserts indentation.
Selective display works by replacing the newline (^j) following a
heading pattern or indentation with a RET (i.e., a ^m). As far as Emacs
is concerned, the line following a ^m is invisible.
You can customize the criterion for distinguishing heading lines by
setting the variable `outline-regexp'. *Note Format of Outlines:
(emacs)Outline Format.
On its own, selective display does not effect editing commands; for
example, `C-f' (`forward-char' will move point into invisible space.
However, the replacement of newline characters with carriage return
characters affects some editing commands, such as the vertical movement
commands that use the newline character to locate the ends of lines.
This means that a `next-line' command will skip invisible lines. Also,
most modes that use selective display provide mode-specific editing
commands, such as `outline-forward-same-level'.
When you write a selectively displayed buffer into a file, all the
^m's are replaced by their original newlines. This means that when you
next read in the file, it looks OK, with nothing invisible. Selective
display is an effect that is only seen in Emacs.
* Variable: selective-display
This buffer-local variable enables selective display. This means
that lines, or portions of lines, may be made invisible.
* If the value of `selective-display' is `t', then any portion
of a line that follows a ^m will not be displayed.
* If the value of `selective-display' is a positive integer,
then lines that start with whitespace in more than
`selective-display' columns will not be displayed.
When some portion of a buffer is invisible, the vertical movement
commands operate as if that portion did not exist, allowing a
single `next-line' command to skip a hundred lines. Character
movement commands (such as `forward-char') will not skip the
invisible portion however, and it is possible, if tricky, to insert
or delete parts of an invisible portion.
In the examples below, what is shown is the *display* of the
buffer `foo', which changes with the value of `selective-display'.
The *contents* of the buffer does not change.
(setq selective-display nil)
=> nil
---------- Buffer: foo ----------
1 on this column
2on this column
3n this column
3n this column
2on this column
1 on this column
---------- Buffer: foo ----------
(setq selective-display-ellipses t)
=> t
(setq selective-display 2)
=> 2
---------- Buffer: foo ----------
1 on this column
2on this column ...
2on this column
1 on this column
---------- Buffer: foo ----------
(setq selective-display-ellipses nil)
=> nil
---------- Buffer: foo ----------
1 on this column
2on this column
2on this column
1 on this column
---------- Buffer: foo ----------
* Variable: selective-display-ellipses
This buffer-local variable means display `...' on the previous
line when a line is made invisible due to `selective-display' being
non-`nil'.
▶1f◀
File: lispref Node: Overlay Arrow, Prev: Selective Display, Up: Emacs Display, Next: Temporary Displays
Overlay Arrow
=============
The "overlay arrow" is useful for directing the user's attention to a
particular line in a buffer. For example, in a debugger mode, the
overlay arrow might point to the current line of code about to be
executed.
* Variable: overlay-arrow-string
The string to display as an arrow.
* Variable: overlay-arrow-position
Marker for where to display `overlay-arrow-string' on top of the
buffer text. This must be a marker at the beginning of some line.
The overlay string will only display over text on that line up to
the end of line.
The overlay string will only be displayed in the buffer which this
marker points into.
▶1f◀
File: lispref Node: Temporary Displays, Prev: Overlay Arrow, Up: Emacs Display, Next: Waiting
Temporary Displays
==================
Temporary displays are used by help commands.
* Variable: temp-buffer-show-hook
The value of the `temp-buffer-show-hook' variable is either
`nil' or is called as a function to display a help buffer. This
variable is used by `with-output-to-temp-buffer'.
* Special form: with-output-to-temp-buffer BUFFER-NAME FORMS...
This function arranges that output generated by evaluating FORMS
will be inserted into the buffer named BUFFER-NAME. The buffer is
then popped into some window for viewing. The buffer is displayed
but not selected.
The buffer is named by the string BUFFER-NAME, and it need not
exist. BUFFER-NAME must be a string, not a buffer. The buffer is
erased initially (with no questions asked), and it is marked as
unmodified after `with-output-to-temp-buffer' exits.
`with-output-to-temp-buffer' first binds `standard-output' to the
buffer, then it evaluates the forms in FORMS. With
`standard-output' rebound, any output directed there will naturally
be inserted into the buffer.
The value of the last form in FORMS is returned.
---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------
(with-output-to-temp-buffer "foo"
(print 20)
(print standard-output))
=> #<buffer foo>
---------- Buffer: foo ----------
20
#<buffer foo>
---------- Buffer: foo ----------
* Function: momentary-string-display STRING POSITION &optional CHAR MESSAGE
This function momentarily displays STRING in the current buffer
at POSITION (which is a character offset from the beginning of the
buffer). The display remains until the next character is typed.
If the next character the user types is CHAR, then Emacs ignores
it. Otherwise it is then the first character in the next input.
Thus, typing CHAR will simply remove the string from the display,
while typing say, `C-f' will remove the string from the display and
move the point forward. CHAR is SPC by default.
Note that the result of `momentary-string-display' is the character
typed rather than `t' if that character is not CHAR.
If MESSAGE is non-`nil', it is displayed in the echo area. If it
is `nil', then instructions to type CHAR are displayed there, e.g.,
`Type RET to continue editing'.
In the example, the point in `foo' is located at the beginning of
the second line.
---------- Buffer: foo ----------
This is the contents of foo.
-!-This is the contents of foo.
---------- Buffer: foo ----------
(momentary-string-display
"******* Important Message! *******" (point) ?\r
"Type RET when done reading")
=> t
---------- Buffer: foo ----------
This is the contents of foo.
******* Important Message! *******This is the contents of foo.
---------- Buffer: foo ----------
---------- Echo Area ----------
Type RET when done reading
One disadvantage of using this function is minor confusion in how
to undo.
▶1f◀
File: lispref Node: Waiting, Prev: Temporary Displays, Up: Emacs Display, Next: Blinking
Waiting for Elapsed Time or Input
=================================
The waiting commands are designed to make Emacs wait for a certain
amount of time to pass to until there is input. For example, you may
wish to pause in the middle of a computation to allow the user time to
view the display. `sit-for' performs a pause with an update of screen,
while `sleep-for' performs a pause without updating the screen.
* Function: sit-for SECONDS
This function performs redisplay (if there is no pending input
from the user), then waits SECONDS seconds, or until input is
available. The result is `t' if `sit-for' waited the full time
with no input arriving (see `input-pending-p' in *Note Keyboard
Input::). Otherwise, `nil' is returned.
Redisplay is always preempted if input arrives, and does not happen
at all if input is available before it starts. Thus there is no
way to force an update if there is pending input. But if there is
no input pending, you can force an update with no delay by using
`(sit-for 0)'.
You use `sit-for' to give the user time to read messages that you
display.
* Function: sleep-for SECONDS
This function simply pauses, without updating the display, for
SECONDS seconds. It pays no attention to available input. It
returns `nil'.
You use `sleep-for' to guarantee a delay.
▶1f◀
File: lispref Node: Blinking, Prev: Waiting, Up: Emacs Display, Next: Displaying Control Characters
Blinking
========
These are the internals of the mechanism by which Emacs shows a
matching open parenthesis.
* Variable: blink-paren-hook
The value of this variable should be a function (of no arguments)
to be called whenever a char with close parenthesis syntax is
inserted. The value of `blink-paren-hook' may be `nil', in which
case nothing is done.
Note: In version 18, this function is named
`blink-paren-hook'; but since `blink-paren-hook' is not called
by the `run-hooks' function, it is being re-named
`blink-paren-function' in Version 19.
* Variable: blink-matching-paren
Non-`nil' means show matching open-paren when close-paren is
inserted.
* Function: blink-matching-open
Move cursor momentarily to the beginning of the sexp before point.
(defun interactive-blink-matching-open ()
"Move cursor momentarily to the beginning of the sexp before point."
(interactive)
(let ((blink-matching-paren t))
(blink-matching-open)))
▶1f◀
File: lispref Node: Displaying Control Characters, Prev: Blinking, Up: Emacs Display
Displaying Control Characters
=============================
* User Option: ctl-arrow
This buffer-local variable controls how control characters are
displayed. If it is non-`nil', then they are displayed as an
uparrow followed by the character: `^A'. If it is `nil', then they
are displayed as a backslash followed by three octal digits,
`\001'.
* Variable: default-ctl-arrow
The value of this variable is the default value for `ctl-arrow'
in buffers that do not override it. This is the same as
`(default-value 'ctl-arrow)'.
▶1f◀
File: lispref Node: Tips and Standards, Prev: Emacs Display, Up: Top, Next: GNU Emacs Internals
Tips and Standards for Emacs Lisp programs
******************************************
Here are some tips for avoiding common errors in writing Lisp code for
other people to use:
* Since all global names are in the same name space, you should take
care to prefix the names of all global variables, constants, and
functions with the major mode name (or with an abbreviation of it
if the name is long). This helps avoid name conflicts.
This recommendation applies even to names for traditional Lisp
primitives that are not primitives in Emacs Lisp---even to `cadr'!
Believe it or not, there is more than one plausible way to define
`cadr'. Play it safe; append your name prefix to produce a name
like `foo-cadr' or `mylib-cadr' instead.
If one prefix is insufficient, your package may use two or three
alternative common words, so long as they make sense.
* Please do not define `C-c LETTER' as a key. These sequences are
reserved for users; they are the *only* sequences reserved for
users, so we cannot do without them.
Everything in Emacs that used to define such sequences has been
changed, which was a lot of work. Abandoning this convention would
waste that work, and hurt the users.
* It is a bad idea to define aliases for the Emacs primitives. Use
the standard names instead.
* Every command, function or variable intended for users to know
about should have a documention string.
* The first line of the documentation string should consist of one or
two complete sentences which stand on their own as a summary. In
particular, start with a capital letter and end with a period.
A doc string can have additional lines which expand on the details
of how to use the function or variable. The additional lines
should be made up of complete sentences also, but they may be
filled if that looks good.
* *Do not* indent subsequent lines of doc string so that their text
is lined up with the text of the first line. This looks nice in
the source code, but looks bad when users view the documentation.
Remember that the indentation before the starting doublequote is
not part of the string!
* A variable's doc string should start with `*' if the variable is
one that users would want to set interactively often. If the value
is a long list, or a function, or the variable would only be set in
init files, then don't start the doc string with `*'.
* In documentation strings, don't write key sequences directly.
Instead, use the `\\[...]' construct to stand for them. For
example, instead of writing `C-f', write `\\[forward-char]'. When
the doc string is printed, Emacs will replace it with whatever key
runs `forward-char'. This will usually be `C-f', but if the user
has moved key bindings, it will be the correct key for that user.
In doc strings for a major mode, do the same thing. However, you
will want to refer to the key bindings of that mode's local map,
rather than global ones. Therefore, use the construct `\\<...>'
once in the doc string to specify which key map to use. Do this
before the first use of `\\[...]'. The text inside the `\\<...>'
should be the name of the variable containing the local keymap for
that major mode.
* Don't use `next-line' or `previous-line' in programs; nearly
always, `forward-line' is more convenient as well as more
predictable and robust.
* Don't use functions that set the mark in your Lisp code (unless you
are writing a command to set the mark). The mark is for the user
to use, and messing it up is incorrect.
In particular, don't use these functions:
* `beginning-of-buffer', `end-of-buffer'
* `replace-string', `replace-regexp'
If you just want to move point, or just replace a certain string,
without any of the other features intended for interactive users,
you can replace these with one or two lines of simple Lisp code.
* The recommended way to print a message in the echo area is with the
`message' function, not `princ'.
* When you encounter an error condition, call the function `error'.
This function does not return.
Do not use `message', `throw', `sleep-for', or `beep' to report
errors.
* Indent each function with `C-M-q' (`indent-sexp') using the default
indentation parameters. Or `M-C-\' (`indent-region').
* Avoid using recursive edits. Instead, do what the Rmail `w'
command does: use a new local keymap which contains one command
defined to switch back to the old local keymap. Or do what the
`edit-options' command does: switch to another buffer and let the
user switch back at will.
* Please put a copyright notice on the file if you give copies to
anyone. Use the same lines that appear at the top of the Lisp
files in Emacs itself. If you have not signed papers to assign the
copyright to the Foundation, then place your name in the copyright
notice in place of the Foundation's name.
▶1f◀
File: lispref Node: GNU Emacs Internals, Prev: Tips and Standards, Up: Top, Next: Standard Errors
GNU Emacs Internals
*******************
This chapter describes many internal aspects of GNU Emacs that may only
be of interest to programmers.
* Menu:
* Building Emacs::
* Object Internals::
* Writing Emacs Primitives
* Garbage Collection::
* Pure Storage::
▶1f◀
File: lispref Node: Building Emacs, Prev: GNU Emacs Internals, Up: GNU Emacs Internals, Next: Pure Storage
Building Emacs
==============
To build Emacs, you first compile the C sources. This produces a
program called `temacs', also called a "Bare impure Emacs". This
version of Emacs contains the Emacs Lisp interpreter and IO routines,
but not the editing commands.
To create a working Emacs editor, you give the command `temacs -l
loadup'. This causes `temacs' to evaluate the Lisp files named in the
`loadup.el' file. These create the normal Emacs editing environment.
It takes long time for `temacs' to evaluate the Lisp files. However,
you can create a version of Emacs that starts more quickly by "dumping"
a complete Emacs to an executable called `xemacs'. This version starts
more quickly because the Lisp code does not have be evaluated again.
This is what is you usually do when you build an Emacs. Renamed
`emacs', the `xemacs' executable is what most people use for Emacs. To
produce it, give the command `temacs -l loadup dump'.
The `xemacs' executable will automatically load a user's `.emacs'
file, or the default site initialization file. This means that you can
change the environment produced by a dumped Emacs without rebuilding
Emacs; or you can produce a version of Emacs that suits you and is not
the same as all the other instances of Emacs.
On some systems, dumping does not work. Then, you can start Emacs
with the `temacs -l loadup' command. This takes a long time, but since
you need to start Emacs once a day at most---and once a week or less
frequently if you never log out---the extra time is not much of a
problem.
* Function: dump-emacs TO-FILE FROM-FILE
This function dumps the current state of Emacs into an executable
file TO-FILE. It takes symbols from FROM-FILE (this is normally
the executable file `temacs'). See `Snarf-documentation' in *Note
Documentation Strings::.
* Function: emacs-version
This function returns a string describing the version of Emacs
that is running. It is useful to include this string in bug
reports.
(emacs-version)
=> "GNU Emacs 18.36.1 of Fri Feb 27 1987 on slug (berkeley-unix)"
* Variable: emacs-build-time
The value of this global variable is the time at which Emacs was
built at the local site.
emacs-build-time
=> "Fri Feb 27 14:55:57 1987"
* Variable: emacs-version
The value of this variable is the version of Emacs being run. It
is a string, e.g. `"18.36.1"'.
▶1f◀
File: lispref Node: Pure Storage, Prev: Building Emacs, Up: GNU Emacs Internals, Next: Garbage Collection
Pure Storage
============
There are two types of storage in GNU Emacs Lisp for user-created Lisp
objects: "normal storage" and "pure storage". Normal storage is where
all the new data which is created by any session with Emacs is kept.
When a program conses up a list or the user defines a new function (or
loads a library), then that is placed in normal storage.
If normal storage runs low, then Emacs requests the operating system
to allocate more memory in blocks of 1k bytes. Each block is allocated
for one type only, meaning that symbols, conses, vectors, etc. are
segregated in distinct blocks in memory.
After a certain amount of storage has been allocated (determined by
the variable `gc-cons-threshold'), the garbage collector is called to
collect all storage which has been used and abandoned.
Pure storage is unique in that it is not expandable, it will not be
collected by the garbage collector, and it is also sharable---meaning
that if two people are running Emacs, the operating system may choose to
let them share the exact same memory for all the sharable portions of
Emacs.
In essence, pure storage is used when initially building Emacs from
the sources, loading all of the normal files which everyone will want.
Normal storage is used during sessions with Emacs.
There is a finite amount of space allocated to pure storage, and this
amount is based upon the number of functions there are that are normally
loaded when building Emacs. If you load more functions into pure
storage, you should increase this value. The amount of pure storage
allocated to Emacs is set in the `emacs/src/config.h' file.
* Function: purecopy OBJECT
This function makes a copy of OBJECT in pure storage and returns
it. It copies strings by simply making a new string with the same
characters in pure storage. It recursively copies the contents of
vectors and cons cells.
It does not make copies of symbols, or any other objects, but
just returns them unchanged. It signals an error if asked to copy
markers.
This function is used only while Emacs is being built and dumped,
and appears only in the `emacs/lisp/loaddefs.el' file, among the
Lisp sources.
* Variable: pure-bytes-used
The value of this variable is the number of bytes of pure storage
allocated so far. Typically, in a dumped Emacs, this number is
very close to the total amount of pure storage that exists.
* Variable: purify-flag
This variable determines whether `defun' should make a copy of
the function definition in pure storage. If it is non-`nil', then
the function definition is copied into pure storage.
This flag is `t' while loading all of the basic functions for
building Emacs initially (allowing those functions to be sharable
and non-collectible). It is set to `nil' when Emacs is saved out
as `xemacs'. The flag is set and reset in the C sources.
You should not change this flag in a running Emacs.
▶1f◀
File: lispref Node: Garbage Collection, Prev: Pure Storage, Up: GNU Emacs Internals, Next: Writing Emacs Primitives
Garbage Collection
==================
All functions which build new structures (be they lists, strings,
buffers, etc.) require storage space for those structures. It is quite
common to use some storage for a while, and then release it, for
example, by killing a buffer or by deleting the last pointer to an
object. Emacs provides a "garbage collector" to reclaim this abandoned
storage. (`Garbage recycler' might be a more intuitive metaphor for
this function.)
The garbage collector operates by scanning all the objects which are
accessible to the user and marking those that are in use. This scan
includes all the symbols, their values and associated function
definitions, and any data presently on the stack. Any objects which are
accessible through objects that are in use are also marked as being in
use. Everything else is not in use and is therefore garbage.
Unused cons cells are simply strung together onto a "free list" for
future allocation. Strings are first ``compacted'', and then all unused
string space is made available to the string creation functions.
Common Lisp Note: Unlike other Lisps, the garbage collector is not
called when storage is exhausted. Instead, GNU Emacs Lisp simply
requests the Operating System to allocate more storage, and
processing continues until `gc-cons-threshold' bytes have been
used.
This means that you can run the garbage collector and then be sure
that you won't need another garbage collection until another
`gc-cons-threshold' bytes have been used.
* Command: garbage-collect
This function reclaims storage used by Lisp objects that are no
longer needed. It returns information on the amount of space in
use. Garbage collection happens automatically if you use more than
`gc-cons-threshold' bytes of Lisp data since the previous garbage
collection. You can also request it explicitly by calling this
function.
`garbage-collect' returns a list containing the following
information:
((USED-CONSES . FREE-CONSES)
(USED-SYMS . FREE-SYMS)
(USED-MARKERS . FREE-MARKERS)
USED-STRING-CHARS
USED-VECTOR-SLOTS)
(garbage-collect)
=> ((3435 . 2332) (1688 . 0) (57 . 417) 24510 3839)
Here is a table explaining each element:
USED-CONSES
The number of cons cells in use.
FREE-CONSES
The number of cons cells for which space has been obtained
from the operating system, but that are not currently being
used.
USED-SYMS
The number of symbols in use.
FREE-SYMS
The number of symbols for which space has been obtained from
the operating system, but that are not currently being used.
USED-MARKERS
The number of markers in use.
FREE-MARKERS
The number of markers for which space has been obtained from
the operating system, but that are not currently being used.
USED-STRING-CHARS
The total size of all strings, in characters.
USED-VECTOR-SLOTS
The total number of elements of existing vectors.
* User Option: gc-cons-threshold
The value of this variable is the number of bytes of storage that
may be used after one garbage collection before another one is
automatically called. Storage is ``used'' by "consing" (a cons
cell is eight bytes), creating strings (one byte per character plus
a few bytes of overhead), adding text to a buffer, etc.
The initial value is 100,000.
This variable may be set to a value above 100,000 to reduce the
frequency of garbage collections. You can make collections more
frequent by setting a smaller value, down to 10,000. Setting it to
a value less than 10,000 will only have effect until the subsequent
garbage collection, at which time `garbage-collect' will set it
back to 10,000.
▶1f◀
File: lispref Node: Writing Emacs Primitives, Prev: Garbage Collection, Up: GNU Emacs Internals, Next: Object Internals
Writing Emacs Primitives
========================
Certain functions, and all special forms, are written in C. A
convenient interface is provided via a set of macros. The only way to
really understand how to write new C code is to read the source;
however, some information will be provided here.
An example of a special form (an ordinary function would have the same
general appearance) is the definition of `or', from `eval.c'.
/* NOTE!!! Every function that can call EVAL must protect its args
and temporaries from garbage collection while it needs them.
The definition of `For' shows what you have to do. */
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
"Eval args until one of them yields non-NIL, then return that value.\n\
The remaining args are not evalled at all.\n\
If all args return NIL, return NIL.")
(args)
Lisp_Object args;
{
register Lisp_Object val;
Lisp_Object args_left;
struct gcpro gcpro1;
if (NULL(args))
return Qnil;
args_left = args;
GCPRO1 (args_left);
do
{
val = Feval (Fcar (args_left));
if (!NULL (val))
break;
args_left = Fcdr (args_left);
}
while (!NULL(args_left));
UNGCPRO;
return val;
}
Here is a precise explanation of the arguments to the `DEFUN' macro:
1. The first argument is the name of the function in Lisp; it will be
named `or'.
2. The second argument is the C function name for this function. This
is the name that is used in C code for calling the function. The
name is, by convention, `F' prepended to the Lisp name, with all
dashes (`-') in the Lisp name changed to underscores. Thus, if
your C code wishes to call this function, it will call `For'.
Remember that the arguments must be of type `Lisp_Object'; various
macros and functions for creating `Lisp_Object' are provided in the
file `lisp.h'.
3. The third argument is the name of the C variable representing the
Lisp primitive that this function codes. This name is by
convention `S' prepended to the name, in the same manner that the
function name is created.
4. The fourth argument is the minimum number of arguments that must be
provided; i.e., the number of required arguments. In this case, no
arguments are required.
5. The fifth argument is the maximum number of arguments that can be
provided. Alternative, it can be `UNEVALLED', indicating a special
form that receives unevaluated arguments. A function with the
equivalent of an `&rest' argument would have `MANY' in this
position. Both `UNEVALLED' and `MANY' are macros. This argument
must be one of these macros or a number at least as large as the
fourth argument.
6. The sixth argument is an interactive specification exactly like the
one provided in Lisp. In this case it is 0 (a null pointer),
indicating that this function cannot be called interactively. A
value of `""' indicates an interactive function not taking
arguments.
7. The last argument is the documentation string. It is written just
like a documentation string for a function defined in Lisp, except
you must write `\n\' at the end of each line. In particular, the
first line should be a single sentence.
Also, you must provide a list of arguments, and declare their types
(always `Lisp_objects').
If you are modifying a file that already has Lisp primitives defined
in it, find the function near the end of the file named
`syms-of-SOMETHING', and add a line of the form
defsubr (&Sname);
If the file doesn't have this function, or you have created a new
file, add a `syms_of_FILENAME' (e.g., `syms_of_eval'), and find the spot
in `emacs.c' where all of these functions are called. Add a call to
your symbol initialization function there. This makes all the
subroutines (primitives) available from Lisp.
Here is another function, with more complicated arguments. This comes
from the code for the X window system, and it demonstrates the use of
macros and functions to manipulate Lisp objects.
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 POSITIONS (a list, (SCREEN-X SCREEN-Y)) is in WINDOW.\n\
Returned value is list of positions expressed\n\
relative to window upper left corner.")
(coordinate, window)
register Lisp_Object coordinate, window;
{
register Lisp_Object xcoord, ycoord;
if (!LISTP (coordinate)) wrong_type_argument (Qlistp, coordinate);
CHECK_WINDOW (window, 2);
xcoord = Fcar (coordinate);
ycoord = Fcar (Fcdr (coordinate));
CHECK_NUMBER (xcoord, 0);
CHECK_NUMBER (ycoord, 1);
if ((XINT (xcoord) < XINT (XWINDOW (window)->left)) ||
(XINT (xcoord) >= (XINT (XWINDOW (window)->left) +
XINT (XWINDOW (window)->width))))
{
return Qnil;
}
XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left);
if (XINT (ycoord) == (screen_height - 1))
return Qnil;
if ((XINT (ycoord) < XINT (XWINDOW (window)->top)) ||
(XINT (ycoord) >= (XINT (XWINDOW (window)->top) +
XINT (XWINDOW (window)->height)) - 1))
{
return Qnil;
}
XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top);
return (Fcons (xcoord, Fcons (ycoord, Qnil)));
}
There are similar equivalents for `defconst' and `defvar', as well as
a few others that have no equivalent in the Lisp interpreter.
Note that you cannot directly call functions defined in Lisp as, for
example, the primitive function `Fcons' is called above. You must
create the appropriate Lisp form, protect everything from garbage
collection, and `Feval' the form, as was done in `For' above.
`eval.c' is a very good file to look through for examples; `lisp.h'
contains the definitions for some important macros and functions.
▶1f◀
File: lispref Node: Object Internals, Prev: Writing Emacs Primitives, Up: GNU Emacs Internals
Object Internals
================
GNU Emacs Lisp manipulates many different types of data. The actual
data is stored in a heap and the only access that programs have to the
data is through pointers. Pointers are thirty-two bits wide in most
implementations. Depending on the operating system and type of machine
for which you compile Emacs, twenty-four to twenty-six bits are used to
indicate the object, and the remaining six to eight bits are used for a
tag that identifies the object's type.
Because all access to data is through tagged pointers, it is always
possible to determine the type of any object. This allows variables to
be untyped, and the values assigned to them to be changed without regard
to type. Function arguments also can be of any type; if you want a
function to accept only a certain type of argument, you must check the
type explicitly using a suitable predicate (*Note Type Predicates::).
* Menu:
* Buffer Internals::
* Window Internals::
* Process Internals::
Emacs has more than twenty types of tags; here is the list, from
`emacs/src/lisp.h': integer, symbol, marker, string, vector of Lisp
objects, cons, byte-compiled function, editor buffer, built-in function,
internal value return by subroutines of read, forwarding pointer to an
int variable, boolean forwarding pointer to an int variable, object
describing a connection to a subprocess, forwarding pointer to a
Lisp_Object variable, Pointer to a vector-like object describing a
display screen, Lisp_Internal_Stream, Lisp_Buffer_Local_Value,
Lisp_Some_Buffer_Local_Value, Lisp_Buffer_Objfwd, Lisp_Void, Window used
for Emacs display, Lisp_Window_Configuration.
▶1f◀
File: lispref Node: Buffer Internals, Prev: Object Internals, Up: Object Internals, Next: Window Internals
Buffer Internals
----------------
Buffers have a set fields which are not directly accessible by the
Lisp programmer. But there are often functions which can access and
change their values even though the names given to them are not usable
by the programmer in any way.
The fields are (as of Emacs 18):
`name'
The buffer name is a string which names the buffer. It is
guaranteed to be unique. *Note Buffer Names::.
`save_modified'
This field contains the time when the buffer was last saved. *Note
Buffer Modification::.
`modtime'
This field contains modification time of the visited file. It is
set when the file is written or read. Every time the buffer is
written to the file, this field is compared to the modification of
the file. *Note Buffer Modification::.
`auto_save_modified'
This field contains the time when the buffer was last auto-saved.
`last_window_start'
This field contains the position in the buffer at which the display
started the last time the buffer was displayed in a window.
`undodata'
This field contains records which tell Emacs how it can undo the
last set of changes to the buffer. *Note Undo::.
`syntax_table_v'
This field contains the syntax table for the buffer. *Note Syntax
Tables::.
`markers'
This field contains the chain of all markers that point into the
buffer. At each deletion or motion of the buffer gap, all of these
markers must be checked and perhaps updated. *Note Markers::.
`backed_up'
This field is a flag which tells if the visited file has been
backed up.
`mark'
This field contains the mark for the buffer. The mark is a marker,
hence it is also included on the list `markers'.
`local_var_alist'
This field contains the association list containing all of the
local fields and their associated values. A copy of this list is
returned by the function `buffer-local-variables'.
`mode_line_format'
*Note Mode Line Format::.
▶1f◀