1 This is ../info/internals.info, produced by makeinfo version 4.0 from
2 internals/internals.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Internals: (internals). XEmacs Internals Manual.
9 Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
10 Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
11 Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
13 Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
17 Permission is granted to copy and distribute modified versions of
18 this manual under the conditions for verbatim copying, provided that the
19 entire resulting derived work is distributed under the terms of a
20 permission notice identical to this one.
22 Permission is granted to copy and distribute translations of this
23 manual into another language, under the above conditions for modified
24 versions, except that this permission notice may be stated in a
25 translation approved by the Foundation.
27 Permission is granted to copy and distribute modified versions of
28 this manual under the conditions for verbatim copying, provided also
29 that the section entitled "GNU General Public License" is included
30 exactly as in the original, and provided that the entire resulting
31 derived work is distributed under the terms of a permission notice
32 identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that the section entitled "GNU General Public License"
37 may be included in a translation approved by the Free Software
38 Foundation instead of in the original English.
41 File: internals.info, Node: Introduction to Events, Next: Main Loop, Prev: Events and the Event Loop, Up: Events and the Event Loop
43 Introduction to Events
44 ======================
46 An event is an object that encapsulates information about an
47 interesting occurrence in the operating system. Events are generated
48 either by user action, direct (e.g. typing on the keyboard or moving
49 the mouse) or indirect (moving another window, thereby generating an
50 expose event on an Emacs frame), or as a result of some other typically
51 asynchronous action happening, such as output from a subprocess being
52 ready or a timer expiring. Events come into the system in an
53 asynchronous fashion (typically through a callback being called) and
54 are converted into a synchronous event queue (first-in, first-out) in a
55 process that we will call "collection".
57 Note that each application has its own event queue. (It is
58 immaterial whether the collection process directly puts the events in
59 the proper application's queue, or puts them into a single system
60 queue, which is later split up.)
62 The most basic level of event collection is done by the operating
63 system or window system. Typically, XEmacs does its own event
64 collection as well. Often there are multiple layers of collection in
65 XEmacs, with events from various sources being collected into a queue,
66 which is then combined with other sources to go into another queue
67 (i.e. a second level of collection), with perhaps another level on top
70 XEmacs has its own types of events (called "Emacs events"), which
71 provides an abstract layer on top of the system-dependent nature of the
72 most basic events that are received. Part of the complex nature of the
73 XEmacs event collection process involves converting from the
74 operating-system events into the proper Emacs events--there may not be
75 a one-to-one correspondence.
77 Emacs events are documented in `events.h'; I'll discuss them later.
80 File: internals.info, Node: Main Loop, Next: Specifics of the Event Gathering Mechanism, Prev: Introduction to Events, Up: Events and the Event Loop
85 The "command loop" is the top-level loop that the editor is always
86 running. It loops endlessly, calling `next-event' to retrieve an event
87 and `dispatch-event' to execute it. `dispatch-event' does the
88 appropriate thing with non-user events (process, timeout, magic, eval,
89 mouse motion); this involves calling a Lisp handler function, redrawing
90 a newly-exposed part of a frame, reading subprocess output, etc. For
91 user events, `dispatch-event' looks up the event in relevant keymaps or
92 menubars; when a full key sequence or menubar selection is reached, the
93 appropriate function is executed. `dispatch-event' may have to keep
94 state across calls; this is done in the "command-builder" structure
95 associated with each console (remember, there's usually only one
96 console), and the engine that looks up keystrokes and constructs full
97 key sequences is called the "command builder". This is documented
100 The guts of the command loop are in `command_loop_1()'. This
101 function doesn't catch errors, though--that's the job of
102 `command_loop_2()', which is a condition-case (i.e. error-trapping)
103 wrapper around `command_loop_1()'. `command_loop_1()' never returns,
104 but may get thrown out of.
106 When an error occurs, `cmd_error()' is called, which usually invokes
107 the Lisp error handler in `command-error'; however, a default error
108 handler is provided if `command-error' is `nil' (e.g. during startup).
109 The purpose of the error handler is simply to display the error message
110 and do associated cleanup; it does not need to throw anywhere. When
111 the error handler finishes, the condition-case in `command_loop_2()'
112 will finish and `command_loop_2()' will reinvoke `command_loop_1()'.
114 `command_loop_2()' is invoked from three places: from
115 `initial_command_loop()' (called from `main()' at the end of internal
116 initialization), from the Lisp function `recursive-edit', and from
117 `call_command_loop()'.
119 `call_command_loop()' is called when a macro is started and when the
120 minibuffer is entered; normal termination of the macro or minibuffer
121 causes a throw out of the recursive command loop. (To
122 `execute-kbd-macro' for macros and `exit' for minibuffers. Note also
123 that the low-level minibuffer-entering function,
124 `read-minibuffer-internal', provides its own error handling and does
125 not need `command_loop_2()''s error encapsulation; so it tells
126 `call_command_loop()' to invoke `command_loop_1()' directly.)
128 Note that both read-minibuffer-internal and recursive-edit set up a
129 catch for `exit'; this is why `abort-recursive-edit', which throws to
130 this catch, exits out of either one.
132 `initial_command_loop()', called from `main()', sets up a catch for
133 `top-level' when invoking `command_loop_2()', allowing functions to
134 throw all the way to the top level if they really need to. Before
135 invoking `command_loop_2()', `initial_command_loop()' calls
136 `top_level_1()', which handles all of the startup stuff (creating the
137 initial frame, handling the command-line options, loading the user's
138 `.emacs' file, etc.). The function that actually does this is in Lisp
139 and is pointed to by the variable `top-level'; normally this function is
140 `normal-top-level'. `top_level_1()' is just an error-handling wrapper
141 similar to `command_loop_2()'. Note also that `initial_command_loop()'
142 sets up a catch for `top-level' when invoking `top_level_1()', just
143 like when it invokes `command_loop_2()'.
146 File: internals.info, Node: Specifics of the Event Gathering Mechanism, Next: Specifics About the Emacs Event, Prev: Main Loop, Up: Events and the Event Loop
148 Specifics of the Event Gathering Mechanism
149 ==========================================
151 Here is an approximate diagram of the collection processes at work
152 in XEmacs, under TTY's (TTY's are simpler than X so we'll look at this
155 asynch. asynch. asynch. asynch. [Collectors in
156 kbd events kbd events process process the OS]
159 | | | | SIGINT, [signal handlers
160 | | | | SIGQUIT, in XEmacs]
162 file file file file SIGALRM
163 desc. desc. desc. desc. |
164 (TTY) (TTY) (pipe) (pipe) |
165 | | | | fake timeouts
173 ------>-----------<----------------<----------------
176 | [collected using select() in emacs_tty_next_event()
177 | and converted to the appropriate Emacs event]
180 V (above this line is TTY-specific)
181 Emacs -----------------------------------------------
182 event (below this line is the generic event mechanism)
185 was there if not, call
186 a SIGINT? emacs_tty_next_event()
193 | [collected in event_stream_next_event();
194 | SIGINT is converted using maybe_read_quit_event()]
199 \---->------>----- maybe_kbd_translate() ---->---\
203 command event queue |
205 (contains events that were event queue, call
206 read earlier but not processed, event_stream_next_event()
207 typically when waiting in a |
208 sit-for, sleep-for, etc. for |
209 a particular event to be received) |
213 ---->------------------------------------<----
216 | next_event_internal()]
218 unread- unread- event from |
219 command- command- keyboard else, call
220 events event macro next_event_internal()
225 --------->----------------------<------------
227 | [collected in `next-event', which may loop
228 | more than once if the event it gets is on
229 | a dead frame, device, etc.]
233 feed into top-level event loop,
234 which repeatedly calls `next-event'
235 and then dispatches the event
236 using `dispatch-event'
238 Notice the separation between TTY-specific and generic event
239 mechanism. When using the Xt-based event loop, the TTY-specific stuff
240 is replaced but the rest stays the same.
242 It's also important to realize that only one different kind of
243 system-specific event loop can be operating at a time, and must be able
244 to receive all kinds of events simultaneously. For the two existing
245 event loops (implemented in `event-tty.c' and `event-Xt.c',
246 respectively), the TTY event loop _only_ handles TTY consoles, while
247 the Xt event loop handles _both_ TTY and X consoles. This situation is
248 different from all of the output handlers, where you simply have one
251 Here's the Xt Event Loop Diagram (notice that below a certain point,
252 it's the same as the above diagram):
254 asynch. asynch. asynch. asynch. [Collectors in
255 kbd kbd process process the OS]
256 events events output output
258 | | | | asynch. asynch. [Collectors in the
259 | | | | X X OS and X Window System]
260 | | | | events events
263 | | | | | | SIGINT, [signal handlers
264 | | | | | | SIGQUIT, in XEmacs]
265 | | | | | | SIGWINCH,
269 | | | | | | | timeouts
274 file file file file file file file |
275 desc. desc. desc. desc. desc. desc. desc. |
276 (TTY) (TTY) (pipe) (pipe) (socket) (socket) (pipe) |
281 --->----------------------------------------<---------<------
283 | | |[collected using select() in
284 | | | _XtWaitForSomething(), called
285 | | | from XtAppProcessEvent(), called
286 | | | in emacs_Xt_next_event();
287 | | | dispatched to various callbacks]
290 emacs_Xt_ p_s_callback(), | [popup_selection_callback]
291 event_handler() x_u_v_s_callback(),| [x_update_vertical_scrollbar_
292 | x_u_h_s_callback(),| callback]
293 | search_callback() | [x_update_horizontal_scrollbar_
297 enqueue_Xt_ signal_special_ |
298 dispatch_event() Xt_user_event() |
310 dispatch Xt_what_callback()
317 ---->-----------<--------
320 | [collected and converted as appropriate in
321 | emacs_Xt_next_event()]
324 V (above this line is Xt-specific)
325 Emacs ------------------------------------------------
326 event (below this line is the generic event mechanism)
329 was there if not, call
330 a SIGINT? emacs_Xt_next_event()
337 | [collected in event_stream_next_event();
338 | SIGINT is converted using maybe_read_quit_event()]
343 \---->------>----- maybe_kbd_translate() -->-----\
347 command event queue |
349 (contains events that were event queue, call
350 read earlier but not processed, event_stream_next_event()
351 typically when waiting in a |
352 sit-for, sleep-for, etc. for |
353 a particular event to be received) |
357 ---->----------------------------------<------
360 | next_event_internal()]
362 unread- unread- event from |
363 command- command- keyboard else, call
364 events event macro next_event_internal()
369 --------->----------------------<------------
371 | [collected in `next-event', which may loop
372 | more than once if the event it gets is on
373 | a dead frame, device, etc.]
377 feed into top-level event loop,
378 which repeatedly calls `next-event'
379 and then dispatches the event
380 using `dispatch-event'
383 File: internals.info, Node: Specifics About the Emacs Event, Next: The Event Stream Callback Routines, Prev: Specifics of the Event Gathering Mechanism, Up: Events and the Event Loop
385 Specifics About the Emacs Event
386 ===============================
389 File: internals.info, Node: The Event Stream Callback Routines, Next: Other Event Loop Functions, Prev: Specifics About the Emacs Event, Up: Events and the Event Loop
391 The Event Stream Callback Routines
392 ==================================
395 File: internals.info, Node: Other Event Loop Functions, Next: Converting Events, Prev: The Event Stream Callback Routines, Up: Events and the Event Loop
397 Other Event Loop Functions
398 ==========================
400 `detect_input_pending()' and `input-pending-p' look for input by
401 calling `event_stream->event_pending_p' and looking in
402 `[V]unread-command-event' and the `command_event_queue' (they do not
403 check for an executing keyboard macro, though).
405 `discard-input' cancels any command events pending (and any keyboard
406 macros currently executing), and puts the others onto the
407 `command_event_queue'. There is a comment about a "race condition",
408 which is not a good sign.
410 `next-command-event' and `read-char' are higher-level interfaces to
411 `next-event'. `next-command-event' gets the next "command" event (i.e.
412 keypress, mouse event, menu selection, or scrollbar action), calling
413 `dispatch-event' on any others. `read-char' calls `next-command-event'
414 and uses `event_to_character()' to return the character equivalent.
415 With the right kind of input method support, it is possible for
416 (read-char) to return a Kanji character.
419 File: internals.info, Node: Converting Events, Next: Dispatching Events; The Command Builder, Prev: Other Event Loop Functions, Up: Events and the Event Loop
424 `character_to_event()', `event_to_character()',
425 `event-to-character', and `character-to-event' convert between
426 characters and keypress events corresponding to the characters. If the
427 event was not a keypress, `event_to_character()' returns -1 and
428 `event-to-character' returns `nil'. These functions convert between
429 character representation and the split-up event representation (keysym
433 File: internals.info, Node: Dispatching Events; The Command Builder, Prev: Converting Events, Up: Events and the Event Loop
435 Dispatching Events; The Command Builder
436 =======================================
441 File: internals.info, Node: Evaluation; Stack Frames; Bindings, Next: Symbols and Variables, Prev: Events and the Event Loop, Up: Top
443 Evaluation; Stack Frames; Bindings
444 **********************************
449 * Dynamic Binding; The specbinding Stack; Unwind-Protects::
450 * Simple Special Forms::
454 File: internals.info, Node: Evaluation, Next: Dynamic Binding; The specbinding Stack; Unwind-Protects, Prev: Evaluation; Stack Frames; Bindings, Up: Evaluation; Stack Frames; Bindings
459 `Feval()' evaluates the form (a Lisp object) that is passed to it.
460 Note that evaluation is only non-trivial for two types of objects:
461 symbols and conses. A symbol is evaluated simply by calling
462 `symbol-value' on it and returning the value.
464 Evaluating a cons means calling a function. First, `eval' checks to
465 see if garbage-collection is necessary, and calls `garbage_collect_1()'
466 if so. It then increases the evaluation depth by 1 (`lisp_eval_depth',
467 which is always less than `max_lisp_eval_depth') and adds an element to
468 the linked list of `struct backtrace''s (`backtrace_list'). Each such
469 structure contains a pointer to the function being called plus a list
470 of the function's arguments. Originally these values are stored
471 unevalled, and as they are evaluated, the backtrace structure is
472 updated. Garbage collection pays attention to the objects pointed to
473 in the backtrace structures (garbage collection might happen while a
474 function is being called or while an argument is being evaluated, and
475 there could easily be no other references to the arguments in the
476 argument list; once an argument is evaluated, however, the unevalled
477 version is not needed by eval, and so the backtrace structure is
480 At this point, the function to be called is determined by looking at
481 the car of the cons (if this is a symbol, its function definition is
482 retrieved and the process repeated). The function should then consist
483 of either a `Lisp_Subr' (built-in function written in C), a
484 `Lisp_Compiled_Function' object, or a cons whose car is one of the
485 symbols `autoload', `macro' or `lambda'.
487 If the function is a `Lisp_Subr', the lisp object points to a
488 `struct Lisp_Subr' (created by `DEFUN()'), which contains a pointer to
489 the C function, a minimum and maximum number of arguments (or possibly
490 the special constants `MANY' or `UNEVALLED'), a pointer to the symbol
491 referring to that subr, and a couple of other things. If the subr
492 wants its arguments `UNEVALLED', they are passed raw as a list.
493 Otherwise, an array of evaluated arguments is created and put into the
494 backtrace structure, and either passed whole (`MANY') or each argument
495 is passed as a C argument.
497 If the function is a `Lisp_Compiled_Function',
498 `funcall_compiled_function()' is called. If the function is a lambda
499 list, `funcall_lambda()' is called. If the function is a macro, [.....
500 fill in] is done. If the function is an autoload, `do_autoload()' is
501 called to load the definition and then eval starts over [explain this
504 When `Feval()' exits, the evaluation depth is reduced by one, the
505 debugger is called if appropriate, and the current backtrace structure
506 is removed from the list.
508 Both `funcall_compiled_function()' and `funcall_lambda()' need to go
509 through the list of formal parameters to the function and bind them to
510 the actual arguments, checking for `&rest' and `&optional' symbols in
511 the formal parameters and making sure the number of actual arguments is
512 correct. `funcall_compiled_function()' can do this a little more
513 efficiently, since the formal parameter list can be checked for sanity
514 when the compiled function object is created.
516 `funcall_lambda()' simply calls `Fprogn' to execute the code in the
519 `funcall_compiled_function()' calls the real byte-code interpreter
520 `execute_optimized_program()' on the byte-code instructions, which are
521 converted into an internal form for faster execution.
523 When a compiled function is executed for the first time by
524 `funcall_compiled_function()', or during the dump phase of building
525 XEmacs, the byte-code instructions are converted from a `Lisp_String'
526 (which is inefficient to access, especially in the presence of MULE)
527 into a `Lisp_Opaque' object containing an array of unsigned char, which
528 can be directly executed by the byte-code interpreter. At this time
529 the byte code is also analyzed for validity and transformed into a more
530 optimized form, so that `execute_optimized_program()' can really fly.
532 Here are some of the optimizations performed by the internal
533 byte-code transformer:
534 1. References to the `constants' array are checked for out-of-range
535 indices, so that the byte interpreter doesn't have to.
537 2. References to the `constants' array that will be used as a Lisp
538 variable are checked for being correct non-constant (i.e. not `t',
539 `nil', or `keywordp') symbols, so that the byte interpreter
542 3. The maximum number of variable bindings in the byte-code is
543 pre-computed, so that space on the `specpdl' stack can be
544 pre-reserved once for the whole function execution.
546 4. All byte-code jumps are relative to the current program counter
547 instead of the start of the program, thereby saving a register.
549 5. One-byte relative jumps are converted from the byte-code form of
550 unsigned chars offset by 127 to machine-friendly signed chars.
552 Of course, this transformation of the `instructions' should not be
553 visible to the user, so `Fcompiled_function_instructions()' needs to
554 know how to convert the optimized opaque object back into a Lisp string
555 that is identical to the original string from the `.elc' file.
556 (Actually, the resulting string may (rarely) contain slightly
557 different, yet equivalent, byte code.)
559 `Ffuncall()' implements Lisp `funcall'. `(funcall fun x1 x2 x3
560 ...)' is equivalent to `(eval (list fun (quote x1) (quote x2) (quote
561 x3) ...))'. `Ffuncall()' contains its own code to do the evaluation,
562 however, and is very similar to `Feval()'.
564 From the performance point of view, it is worth knowing that most of
565 the time in Lisp evaluation is spent executing `Lisp_Subr' and
566 `Lisp_Compiled_Function' objects via `Ffuncall()' (not `Feval()').
568 `Fapply()' implements Lisp `apply', which is very similar to
569 `funcall' except that if the last argument is a list, the result is the
570 same as if each of the arguments in the list had been passed separately.
571 `Fapply()' does some business to expand the last argument if it's a
572 list, then calls `Ffuncall()' to do the work.
574 `apply1()', `call0()', `call1()', `call2()', and `call3()' call a
575 function, passing it the argument(s) given (the arguments are given as
576 separate C arguments rather than being passed as an array). `apply1()'
577 uses `Fapply()' while the others use `Ffuncall()' to do the real work.
580 File: internals.info, Node: Dynamic Binding; The specbinding Stack; Unwind-Protects, Next: Simple Special Forms, Prev: Evaluation, Up: Evaluation; Stack Frames; Bindings
582 Dynamic Binding; The specbinding Stack; Unwind-Protects
583 =======================================================
588 Lisp_Object old_value;
589 Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */
592 `struct specbinding' is used for local-variable bindings and
593 unwind-protects. `specpdl' holds an array of `struct specbinding''s,
594 `specpdl_ptr' points to the beginning of the free bindings in the
595 array, `specpdl_size' specifies the total number of binding slots in
596 the array, and `max_specpdl_size' specifies the maximum number of
597 bindings the array can be expanded to hold. `grow_specpdl()' increases
598 the size of the `specpdl' array, multiplying its size by 2 but never
599 exceeding `max_specpdl_size' (except that if this number is less than
600 400, it is first set to 400).
602 `specbind()' binds a symbol to a value and is used for local
603 variables and `let' forms. The symbol and its old value (which might
604 be `Qunbound', indicating no prior value) are recorded in the specpdl
605 array, and `specpdl_size' is increased by 1.
607 `record_unwind_protect()' implements an "unwind-protect", which,
608 when placed around a section of code, ensures that some specified
609 cleanup routine will be executed even if the code exits abnormally
610 (e.g. through a `throw' or quit). `record_unwind_protect()' simply
611 adds a new specbinding to the `specpdl' array and stores the
612 appropriate information in it. The cleanup routine can either be a C
613 function, which is stored in the `func' field, or a `progn' form, which
614 is stored in the `old_value' field.
616 `unbind_to()' removes specbindings from the `specpdl' array until
617 the specified position is reached. Each specbinding can be one of
620 1. an unwind-protect with a C cleanup function (`func' is not 0, and
621 `old_value' holds an argument to be passed to the function);
623 2. an unwind-protect with a Lisp form (`func' is 0, `symbol' is
624 `nil', and `old_value' holds the form to be executed with
627 3. a local-variable binding (`func' is 0, `symbol' is not `nil', and
628 `old_value' holds the old value, which is stored as the symbol's
632 File: internals.info, Node: Simple Special Forms, Next: Catch and Throw, Prev: Dynamic Binding; The specbinding Stack; Unwind-Protects, Up: Evaluation; Stack Frames; Bindings
637 `or', `and', `if', `cond', `progn', `prog1', `prog2', `setq',
638 `quote', `function', `let*', `let', `while'
640 All of these are very simple and work as expected, calling `Feval()'
641 or `Fprogn()' as necessary and (in the case of `let' and `let*') using
642 `specbind()' to create bindings and `unbind_to()' to undo the bindings
645 Note that, with the exception of `Fprogn', these functions are
646 typically called in real life only in interpreted code, since the byte
647 compiler knows how to convert calls to these functions directly into
651 File: internals.info, Node: Catch and Throw, Prev: Simple Special Forms, Up: Evaluation; Stack Frames; Bindings
660 struct catchtag *next;
663 struct backtrace *backlist;
668 `catch' is a Lisp function that places a catch around a body of
669 code. A catch is a means of non-local exit from the code. When a catch
670 is created, a tag is specified, and executing a `throw' to this tag
671 will exit from the body of code caught with this tag, and its value will
672 be the value given in the call to `throw'. If there is no such call,
673 the code will be executed normally.
675 Information pertaining to a catch is held in a `struct catchtag',
676 which is placed at the head of a linked list pointed to by `catchlist'.
677 `internal_catch()' is passed a C function to call (`Fprogn()' when
678 Lisp `catch' is called) and arguments to give it, and places a catch
679 around the function. Each `struct catchtag' is held in the stack frame
680 of the `internal_catch()' instance that created the catch.
682 `internal_catch()' is fairly straightforward. It stores into the
683 `struct catchtag' the tag name and the current values of
684 `backtrace_list', `lisp_eval_depth', `gcprolist', and the offset into
685 the `specpdl' array, sets a jump point with `_setjmp()' (storing the
686 jump point into the `struct catchtag'), and calls the function.
687 Control will return to `internal_catch()' either when the function
688 exits normally or through a `_longjmp()' to this jump point. In the
689 latter case, `throw' will store the value to be returned into the
690 `struct catchtag' before jumping. When it's done, `internal_catch()'
691 removes the `struct catchtag' from the catchlist and returns the proper
694 `Fthrow()' goes up through the catchlist until it finds one with a
695 matching tag. It then calls `unbind_catch()' to restore everything to
696 what it was when the appropriate catch was set, stores the return value
697 in the `struct catchtag', and jumps (with `_longjmp()') to its jump
700 `unbind_catch()' removes all catches from the catchlist until it
701 finds the correct one. Some of the catches might have been placed for
702 error-trapping, and if so, the appropriate entries on the handlerlist
703 must be removed (see "errors"). `unbind_catch()' also restores the
704 values of `gcprolist', `backtrace_list', and `lisp_eval', and calls
705 `unbind_to()' to undo any specbindings created since the catch.
708 File: internals.info, Node: Symbols and Variables, Next: Buffers and Textual Representation, Prev: Evaluation; Stack Frames; Bindings, Up: Top
710 Symbols and Variables
711 *********************
715 * Introduction to Symbols::
720 File: internals.info, Node: Introduction to Symbols, Next: Obarrays, Prev: Symbols and Variables, Up: Symbols and Variables
722 Introduction to Symbols
723 =======================
725 A symbol is basically just an object with four fields: a name (a
726 string), a value (some Lisp object), a function (some Lisp object), and
727 a property list (usually a list of alternating keyword/value pairs).
728 What makes symbols special is that there is usually only one symbol with
729 a given name, and the symbol is referred to by name. This makes a
730 symbol a convenient way of calling up data by name, i.e. of implementing
731 variables. (The variable's value is stored in the "value slot".)
732 Similarly, functions are referenced by name, and the definition of the
733 function is stored in a symbol's "function slot". This means that
734 there can be a distinct function and variable with the same name. The
735 property list is used as a more general mechanism of associating
736 additional values with particular names, and once again the namespace is
737 independent of the function and variable namespaces.
740 File: internals.info, Node: Obarrays, Next: Symbol Values, Prev: Introduction to Symbols, Up: Symbols and Variables
745 The identity of symbols with their names is accomplished through a
746 structure called an obarray, which is just a poorly-implemented hash
747 table mapping from strings to symbols whose name is that string. (I say
748 "poorly implemented" because an obarray appears in Lisp as a vector
749 with some hidden fields rather than as its own opaque type. This is an
750 Emacs Lisp artifact that should be fixed.)
752 Obarrays are implemented as a vector of some fixed size (which should
753 be a prime for best results), where each "bucket" of the vector
754 contains one or more symbols, threaded through a hidden `next' field in
755 the symbol. Lookup of a symbol in an obarray, and adding a symbol to
756 an obarray, is accomplished through standard hash-table techniques.
758 The standard Lisp function for working with symbols and obarrays is
759 `intern'. This looks up a symbol in an obarray given its name; if it's
760 not found, a new symbol is automatically created with the specified
761 name, added to the obarray, and returned. This is what happens when the
762 Lisp reader encounters a symbol (or more precisely, encounters the name
763 of a symbol) in some text that it is reading. There is a standard
764 obarray called `obarray' that is used for this purpose, although the
765 Lisp programmer is free to create his own obarrays and `intern' symbols
768 Note that, once a symbol is in an obarray, it stays there until
769 something is done about it, and the standard obarray `obarray' always
770 stays around, so once you use any particular variable name, a
771 corresponding symbol will stay around in `obarray' until you exit
774 Note that `obarray' itself is a variable, and as such there is a
775 symbol in `obarray' whose name is `"obarray"' and which contains
776 `obarray' as its value.
778 Note also that this call to `intern' occurs only when in the Lisp
779 reader, not when the code is executed (at which point the symbol is
780 already around, stored as such in the definition of the function).
782 You can create your own obarray using `make-vector' (this is
783 horrible but is an artifact) and intern symbols into that obarray.
784 Doing that will result in two or more symbols with the same name.
785 However, at most one of these symbols is in the standard `obarray': You
786 cannot have two symbols of the same name in any particular obarray.
787 Note that you cannot add a symbol to an obarray in any fashion other
788 than using `intern': i.e. you can't take an existing symbol and put it
789 in an existing obarray. Nor can you change the name of an existing
790 symbol. (Since obarrays are vectors, you can violate the consistency of
791 things by storing directly into the vector, but let's ignore that
794 Usually symbols are created by `intern', but if you really want, you
795 can explicitly create a symbol using `make-symbol', giving it some
796 name. The resulting symbol is not in any obarray (i.e. it is
797 "uninterned"), and you can't add it to any obarray. Therefore its
798 primary purpose is as a symbol to use in macros to avoid namespace
799 pollution. It can also be used as a carrier of information, but cons
800 cells could probably be used just as well.
802 You can also use `intern-soft' to look up a symbol but not create a
803 new one, and `unintern' to remove a symbol from an obarray. This
804 returns the removed symbol. (Remember: You can't put the symbol back
805 into any obarray.) Finally, `mapatoms' maps over all of the symbols in
809 File: internals.info, Node: Symbol Values, Prev: Obarrays, Up: Symbols and Variables
814 The value field of a symbol normally contains a Lisp object.
815 However, a symbol can be "unbound", meaning that it logically has no
816 value. This is internally indicated by storing a special Lisp object,
817 called "the unbound marker" and stored in the global variable
818 `Qunbound'. The unbound marker is of a special Lisp object type called
819 "symbol-value-magic". It is impossible for the Lisp programmer to
820 directly create or access any object of this type.
822 *You must not let any "symbol-value-magic" object escape to the Lisp
823 level.* Printing any of these objects will cause the message `INTERNAL
824 EMACS BUG' to appear as part of the print representation. (You may see
825 this normally when you call `debug_print()' from the debugger on a Lisp
826 object.) If you let one of these objects escape to the Lisp level, you
827 will violate a number of assumptions contained in the C code and make
828 the unbound marker not function right.
830 When a symbol is created, its value field (and function field) are
831 set to `Qunbound'. The Lisp programmer can restore these conditions
832 later using `makunbound' or `fmakunbound', and can query to see whether
833 the value of function fields are "bound" (i.e. have a value other than
834 `Qunbound') using `boundp' and `fboundp'. The fields are set to a
835 normal Lisp object using `set' (or `setq') and `fset'.
837 Other symbol-value-magic objects are used as special markers to
838 indicate variables that have non-normal properties. This includes any
839 variables that are tied into C variables (setting the variable magically
840 sets some global variable in the C code, and likewise for retrieving the
841 variable's value), variables that magically tie into slots in the
842 current buffer, variables that are buffer-local, etc. The
843 symbol-value-magic object is stored in the value cell in place of a
844 normal object, and the code to retrieve a symbol's value (i.e.
845 `symbol-value') knows how to do special things with them. This means
846 that you should not just fetch the value cell directly if you want a
849 The exact workings of this are rather complex and involved and are
850 well-documented in comments in `buffer.c', `symbols.c', and `lisp.h'.
853 File: internals.info, Node: Buffers and Textual Representation, Next: MULE Character Sets and Encodings, Prev: Symbols and Variables, Up: Top
855 Buffers and Textual Representation
856 **********************************
860 * Introduction to Buffers:: A buffer holds a block of text such as a file.
861 * The Text in a Buffer:: Representation of the text in a buffer.
862 * Buffer Lists:: Keeping track of all buffers.
863 * Markers and Extents:: Tagging locations within a buffer.
864 * Bufbytes and Emchars:: Representation of individual characters.
865 * The Buffer Object:: The Lisp object corresponding to a buffer.
868 File: internals.info, Node: Introduction to Buffers, Next: The Text in a Buffer, Prev: Buffers and Textual Representation, Up: Buffers and Textual Representation
870 Introduction to Buffers
871 =======================
873 A buffer is logically just a Lisp object that holds some text. In
874 this, it is like a string, but a buffer is optimized for frequent
875 insertion and deletion, while a string is not. Furthermore:
877 1. Buffers are "permanent" objects, i.e. once you create them, they
878 remain around, and need to be explicitly deleted before they go
881 2. Each buffer has a unique name, which is a string. Buffers are
882 normally referred to by name. In this respect, they are like
885 3. Buffers have a default insertion position, called "point".
886 Inserting text (unless you explicitly give a position) goes at
887 point, and moves point forward past the text. This is what is
888 going on when you type text into Emacs.
890 4. Buffers have lots of extra properties associated with them.
892 5. Buffers can be "displayed". What this means is that there exist a
893 number of "windows", which are objects that correspond to some
894 visible section of your display, and each window has an associated
895 buffer, and the current contents of the buffer are shown in that
896 section of the display. The redisplay mechanism (which takes care
897 of doing this) knows how to look at the text of a buffer and come
898 up with some reasonable way of displaying this. Many of the
899 properties of a buffer control how the buffer's text is displayed.
901 6. One buffer is distinguished and called the "current buffer". It is
902 stored in the variable `current_buffer'. Buffer operations operate
903 on this buffer by default. When you are typing text into a
904 buffer, the buffer you are typing into is always `current_buffer'.
905 Switching to a different window changes the current buffer. Note
906 that Lisp code can temporarily change the current buffer using
907 `set-buffer' (often enclosed in a `save-excursion' so that the
908 former current buffer gets restored when the code is finished).
909 However, calling `set-buffer' will NOT cause a permanent change in
910 the current buffer. The reason for this is that the top-level
911 event loop sets `current_buffer' to the buffer of the selected
912 window, each time it finishes executing a user command.
914 Make sure you understand the distinction between "current buffer"
915 and "buffer of the selected window", and the distinction between
916 "point" of the current buffer and "window-point" of the selected
917 window. (This latter distinction is explained in detail in the section
projects / chise / xemacs-chise.git / blob