Mercurial > emacs
changeset 6451:8240c0b1d695
Initial revision
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Mon, 21 Mar 1994 07:49:21 +0000 |
| parents | 1b17fc16d5c5 |
| children | 8c7032348e93 |
| files | lispref/elisp.texi lispref/internals.texi lispref/maps.texi lispref/modes.texi |
| diffstat | 4 files changed, 3207 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/elisp.texi Mon Mar 21 07:49:21 1994 +0000 @@ -0,0 +1,903 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename elisp +@smallbook +@settitle GNU Emacs Lisp Reference Manual +@c %**end of header + +@ifinfo +This version is the edition 2.3 of the GNU Emacs Lisp +Reference Manual. It corresponds to Emacs Version 19.23. +@c Please REMEMBER to update edition number in *four* places in this file +@c and also in *one* place in intro.texi + +Published by the Free Software Foundation +675 Massachusetts Avenue +Cambridge, MA 02139 USA + +Copyright (C) 1990, 1991, 1992, 1993, 1994 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. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +@end ignore +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. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and 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 the section entitled ``GNU General Public License'' may be +included in a translation approved by the Free Software Foundation +instead of in the original English. +@end ifinfo + +@c Combine indices. +@synindex cp fn +@syncodeindex vr fn +@syncodeindex ky fn +@syncodeindex pg fn +@syncodeindex tp fn + +@setchapternewpage odd +@finalout + +@titlepage +@title GNU Emacs Lisp Reference Manual +@subtitle GNU Emacs Version 19 +@subtitle for Unix Users +@c The edition number appears in several places in this file +@c and also in the file intro.texi. +@subtitle Second Edition, June 1993 +@subtitle Revision 2.3, April 1994 + +@author by Bil Lewis, Dan LaLiberte, Richard Stallman +@author and the GNU Manual Group +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. + +@sp 2 +Second Edition @* +Revised for Emacs Version 19.23,@* +April 1994.@* +@sp 2 +ISBN 1-882114-40-X + +@sp 2 +Published by the Free Software Foundation @* +675 Massachusetts Avenue @* +Cambridge, MA 02139 USA + +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 also that the +section entitled ``GNU General Public License'' is included +exactly as in the original, and 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 the section entitled ``GNU General Public License'' may be +included in a translation approved by the Free Software Foundation +instead of in the original English. + +Cover art by Etienne Suvasa. +@end titlepage +@page + +@node Top, Copying, (dir), (dir) + +@ifinfo +This Info file contains edition 2.3 of the GNU Emacs Lisp +Reference Manual, corresponding to GNU Emacs version 19.23. +@end ifinfo + +@menu +* Copying:: Conditions for copying and changing GNU Emacs. +* Introduction:: Introduction and conventions used. + +* Types of Lisp Object:: Data types in Emacs Lisp. +* Numbers:: Numbers and arithmetic functions. +* Strings and Characters:: Strings, and functions that work on them. +* Lists:: Lists, cons cells, and related functions. +* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. + Certain functions act on any kind of sequence. + The description of vectors is here as well. +* Symbols:: Symbols represent names, uniquely. + +* Evaluation:: How Lisp expressions are evaluated. +* Control Structures:: Conditionals, loops, nonlocal exits. +* Variables:: Using symbols in programs to stand for values. +* Functions:: A function is a Lisp program + that can be invoked from other functions. +* Macros:: Macros are a way to extend the Lisp language. + +* Loading:: Reading files of Lisp code into Lisp. +* Byte Compilation:: Compilation makes programs run faster. +* Debugging:: Tools and tips for debugging Lisp programs. + +* Streams:: Converting Lisp objects to text and back. +* Minibuffers:: Using the minibuffer to read input. +* Command Loop:: How the editor command loop works, + and how you can call its subroutines. +* Keymaps:: Defining the bindings from keys to commands. +* Modes:: Defining major and minor modes. +* Documentation:: Writing and using documentation strings. + +* Files:: Accessing files. +* Backups and Auto-Saving:: Controlling how backups and auto-save + files are made. +* Buffers:: Creating and using buffer objects. +* Windows:: Manipulating windows and displaying buffers. +* Frames:: Making multiple X windows. +* Positions:: Buffer positions and motion functions. +* Markers:: Markers represent positions and update + automatically when the text is changed. + +* Text:: Examining and changing text in buffers. +* Searching and Matching:: Searching buffers for strings or regexps. +* Syntax Tables:: The syntax table controls word and list parsing. +* Abbrevs:: How Abbrev mode works, and its data structures. + +* Processes:: Running and communicating with subprocesses. +* System Interface:: Getting the user id, system type, environment + variables, and other such things. +* Display:: Parameters controlling screen usage. + The bell. Waiting for input. +* Calendar:: Customizing the calendar and diary. + +Appendices + +* Tips:: Advice for writing Lisp programs. +* GNU Emacs Internals:: Building and dumping Emacs; + internal data structures. +* Standard Errors:: List of all error symbols. +* Standard Buffer-Local Variables:: List of variables local in all buffers. +* Standard Keymaps:: List of standard keymaps. +* Standard Hooks:: List of standard hook variables. + +* Antinews:: Information about Emacs 18. + +* Index:: Index including concepts, functions, variables, + and other terms. + + --- The Detailed Node Listing --- + +Here are other nodes that are inferiors of those already listed, +mentioned here so you can get to them in one step: + +Introduction + +* Caveats:: Flaws and a request for help. +* Lisp History:: Emacs Lisp is descended from Maclisp. +* Conventions:: How the manual is formatted. +* Acknowledgements:: The authors, editors, and sponsors of this manual. + +Conventions + +* Some Terms:: Explanation of terms we use in this manual. +* nil and t:: How the symbols @code{nil} and @code{t} are used. +* Evaluation Notation:: The format we use for examples of evaluation. +* Printing Notation:: The format we use for examples that print output. +* Error Messages:: The format we use for examples of errors. +* Buffer Text Notation:: The format we use for buffer contents in examples. +* Format of Descriptions:: Notation for describing functions, variables, etc. + +Format of Descriptions + +* A Sample Function Description:: +* A Sample Variable Description:: + +Lisp Data Types + +* Printed Representation:: How Lisp objects are represented as text. +* Comments:: Comments and their formatting conventions. +* Programming Types:: Types found in all Lisp systems. +* Editing Types:: Types specific to Emacs. +* Type Predicates:: Tests related to types. +* Equality Predicates:: Tests of equality between any two objects. + +Programming Types + +* Integer Type:: Numbers without fractional parts. +* Floating Point Type:: Numbers with fractional parts and with a large range. +* Character Type:: The representation of letters, numbers and + control characters. +* Sequence Type:: Both lists and arrays are classified as sequences. +* List Type:: Lists gave Lisp its name (not to mention reputation). +* Array Type:: Arrays include strings and vectors. +* String Type:: An (efficient) array of characters. +* Vector Type:: One-dimensional arrays. +* Symbol Type:: A multi-use object that refers to a function, + variable, property list, or itself. +* Lisp Function Type:: A piece of executable code you can call from elsewhere. +* Lisp Macro Type:: A method of expanding an expression into another + expression, more fundamental but less pretty. +* Primitive Function Type:: A function written in C, callable from Lisp. +* Byte-Code Type:: A function written in Lisp, then compiled. +* Autoload Type:: A type used for automatically loading seldom-used + functions. + +List Type + +* Dotted Pair Notation:: An alternative syntax for lists. +* Association List Type:: A specially constructed list. + +Editing Types + +* Buffer Type:: The basic object of editing. +* Window Type:: What makes buffers visible. +* Window Configuration Type::Save what the screen looks like. +* Marker Type:: A position in a buffer. +* Process Type:: A process running on the underlying OS. +* Stream Type:: Receive or send characters. +* Keymap Type:: What function a keystroke invokes. +* Syntax Table Type:: What a character means. + +Numbers + +* Integer Basics:: Representation and range of integers. +* Float Basics:: Representation and range of floating point. +* Predicates on Numbers:: Testing for numbers. +* Comparison of Numbers:: Equality and inequality predicates. +* Arithmetic Operations:: How to add, subtract, multiply and divide. +* Bitwise Operations:: Logical and, or, not, shifting. +* Numeric Conversions:: Converting float to integer and vice versa. +* Transcendental Functions:: Trig, exponential and logarithmic functions. +* Random Numbers:: Obtaining random integers, predictable or not. + +Strings and Characters + +* String Basics:: Basic properties of strings and characters. +* Predicates for Strings:: Testing whether an object is a string or char. +* Creating Strings:: Functions to allocate new strings. +* Text Comparison:: Comparing characters or strings. +* String Conversion:: Converting characters or strings and vice versa. +* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}. +* Character Case:: Case conversion functions. + +Lists + +* Cons Cells:: How lists are made out of cons cells. +* Lists as Boxes:: Graphical notation to explain lists. +* List-related Predicates:: Is this object a list? Comparing two lists. +* List Elements:: Extracting the pieces of a list. +* Building Lists:: Creating list structure. +* Modifying Lists:: Storing new pieces into an existing list. +* Sets And Lists:: A list can represent a finite mathematical set. +* Association Lists:: A list can represent a finite relation or mapping. + +Modifying Existing List Structure + +* Setcar:: Replacing an element in a list. +* Setcdr:: Replacing part of the list backbone. + This can be used to remove or add elements. +* Rearrangement:: Reordering the elements in a list; combining lists. + +Sequences, Arrays, and Vectors + +* Sequence Functions:: Functions that accept any kind of sequence. +* Arrays:: Characteristics of arrays in Emacs Lisp. +* Array Functions:: Functions specifically for arrays. +* Vectors:: Functions specifically for vectors. + +Symbols + +* Symbol Components:: Symbols have names, values, function definitions + and property lists. +* Definitions:: A definition says how a symbol will be used. +* Creating Symbols:: How symbols are kept unique. +* Property Lists:: Each symbol has a property list + for recording miscellaneous information. + +Evaluation + +* Intro Eval:: Evaluation in the scheme of things. +* Eval:: How to invoke the Lisp interpreter explicitly. +* Forms:: How various sorts of objects are evaluated. +* Quoting:: Avoiding evaluation (to put constants in + the program). + +Kinds of Forms + +* Self-Evaluating Forms:: Forms that evaluate to themselves. +* Symbol Forms:: Symbols evaluate as variables. +* Classifying Lists:: How to distinguish various sorts of list forms. +* Function Forms:: Forms that call functions. +* Macro Forms:: Forms that call macros. +* Special Forms:: ``Special forms'' are idiosyncratic primitives, + most of them extremely important. +* Autoloading:: Functions set up to load files + containing their real definitions. + +Control Structures + +* Sequencing:: Evaluation in textual order. +* Conditionals:: @code{if}, @code{cond}. +* Combining Conditions:: @code{and}, @code{or}, @code{not}. +* Iteration:: @code{while} loops. +* Nonlocal Exits:: Jumping out of a sequence. + +Nonlocal Exits + +* Catch and Throw:: Nonlocal exits for the program's own purposes. +* Examples of Catch:: Showing how such nonlocal exits can be written. +* Errors:: How errors are signaled and handled. +* Cleanups:: Arranging to run a cleanup form if an + error happens. + +Errors + +* Signaling Errors:: How to report an error. +* Processing of Errors:: What Emacs does when you report an error. +* Handling Errors:: How you can trap errors and continue execution. +* Error Names:: How errors are classified for trapping them. + +Variables + +* Global Variables:: Variable values that exist permanently, everywhere. +* Constant Variables:: Certain "variables" have values that never change. +* Local Variables:: Variable values that exist only temporarily. +* Void Variables:: Symbols that lack values. +* Defining Variables:: A definition says a symbol is used as a variable. +* Accessing Variables:: Examining values of variables whose names + are known only at run time. +* Setting Variables:: Storing new values in variables. +* Variable Scoping:: How Lisp chooses among local and global values. +* Buffer-Local Variables:: Variable values in effect only in one buffer. + +Scoping Rules for Variable Bindings + +* Scope:: Scope means where in the program a value + is visible. Comparison with other languages. +* Extent:: Extent means how long in time a value exists. +* Impl of Scope:: Two ways to implement dynamic scoping. +* Using Scoping:: How to use dynamic scoping carefully and + avoid problems. + +Buffer-Local Variables + +* Intro to Buffer-Local:: Introduction and concepts. +* Creating Buffer-Local:: Creating and destroying buffer-local bindings. +* Default Value:: The default value is seen in buffers + that don't have their own local values. + +Functions + +* What Is a Function:: Lisp functions vs primitives; terminology. +* Lambda Expressions:: How functions are expressed as Lisp objects. +* Function Names:: A symbol can serve as the name of a function. +* Defining Functions:: Lisp expressions for defining functions. +* Calling Functions:: How to use an existing function. +* Mapping Functions:: Applying a function to each element of a list, etc. +* Anonymous Functions:: Lambda-expressions are functions with no names. +* Function Cells:: Accessing or setting the function definition + of a symbol. +* Related Topics:: Cross-references to specific Lisp primitives + that have a special bearing on how + functions work. + +Lambda Expressions + +* Lambda Components:: The parts of a lambda expression. +* Simple Lambda:: A simple example. +* Argument List:: Details and special features of argument lists. +* Function Documentation:: How to put documentation in a function. + +Macros + +* Simple Macro:: A basic example. +* Expansion:: How, when and why macros are expanded. +* Compiling Macros:: How macros are expanded by the compiler. +* Defining Macros:: How to write a macro definition. +* Backquote:: Easier construction of list structure. +* Problems with Macros:: Don't evaluate the macro arguments too many times. + Don't hide the user's variables. + +Loading + +* How Programs Do Loading:: The @code{load} function and others. +* Autoload:: Setting up a function to autoload. +* Features:: Loading a library if it isn't already loaded. +* Repeated Loading:: Precautions about loading a file twice. + +Byte Compilation + +* Compilation Functions:: Byte compilation functions. +* Disassembly:: Disassembling byte-code; how to read byte-code. + +Debugging Lisp Programs + +* Debugger:: How the Emacs Lisp debugger is implemented. +* Syntax Errors:: How to find syntax errors. +* Compilation Errors:: How to find errors that show up in + byte compilation. +* Edebug:: A source-level Emacs Lisp debugger. + +The Lisp Debugger + +* Error Debugging:: Entering the debugger when an error happens. +* Function Debugging:: Entering it when a certain function is called. +* Explicit Debug:: Entering it at a certain point in the program. +* Using Debugger:: What the debugger does; what you see while in it. +* Debugger Commands:: Commands used while in the debugger. +* Invoking the Debugger:: How to call the function @code{debug}. +* Internals of Debugger:: Subroutines of the debugger, and global variables. + +Debugging Invalid Lisp Syntax + +* Excess Open:: How to find a spurious open paren or missing close. +* Excess Close:: How to find a spurious close paren or missing open. + +Reading and Printing Lisp Objects + +* Streams Intro:: Overview of streams, reading and printing. +* Input Streams:: Various data types that can be used as + input streams. +* Input Functions:: Functions to read Lisp objects from text. +* Output Streams:: Various data types that can be used as + output streams. +* Output Functions:: Functions to print Lisp objects as text. + +Minibuffers + +* Intro to Minibuffers:: Basic information about minibuffers. +* Text from Minibuffer:: How to read a straight text string. +* Object from Minibuffer:: How to read a Lisp object or expression. +* Completion:: How to invoke and customize completion. +* Yes-or-No Queries:: Asking a question with a simple answer. +* Minibuffer Misc:: Various customization hooks and variables. + +Completion + +* Basic Completion:: Low-level functions for completing strings. + (These are too low level to use the minibuffer.) +* Minibuffer Completion:: Invoking the minibuffer with completion. +* Completion Commands:: Minibuffer commands that do completion. +* High-Level Completion:: Convenient special cases of completion + (reading buffer name, file name, etc.) +* Reading File Names:: Using completion to read file names. +* Programmed Completion:: Finding the completions for a given file name. + +Command Loop + +* Command Overview:: How the command loop reads commands. +* Defining Commands:: Specifying how a function should read arguments. +* Interactive Call:: Calling a command, so that it will read arguments. +* Command Loop Info:: Variables set by the command loop for you to examine. +* Input Events:: What input looks like when you read it. +* Reading Input:: How to read input events from the keyboard or mouse. +* Waiting:: Waiting for user input or elapsed time. +* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. +* Prefix Command Arguments:: How the commands to set prefix args work. +* Recursive Editing:: Entering a recursive edit, + and why you usually shouldn't. +* Disabling Commands:: How the command loop handles disabled commands. +* Command History:: How the command history is set up, and how accessed. +* Keyboard Macros:: How keyboard macros are implemented. + +Defining Commands + +* Using Interactive:: General rules for @code{interactive}. +* Interactive Codes:: The standard letter-codes for reading arguments + in various ways. +* Interactive Examples:: Examples of how to read interactive arguments. + +Keymaps + +* Keymap Terminology:: Definitions of terms pertaining to keymaps. +* Format of Keymaps:: What a keymap looks like as a Lisp object. +* Creating Keymaps:: Functions to create and copy keymaps. +* Inheritance and Keymaps:: How one keymap can inherit the bindings + of another keymap. +* Prefix Keys:: Defining a key with a keymap as its definition. +* Menu Keymaps:: A keymap can define a menu for X windows + or for use from the terminal. +* Active Keymaps:: Each buffer has a local keymap + to override the standard (global) bindings. + Each minor mode can also override them. +* Key Lookup:: How extracting elements from keymaps works. +* Functions for Key Lookup:: How to request key lookup. +* Changing Key Bindings:: Redefining a key in a keymap. +* Key Binding Commands:: Interactive interfaces for redefining keys. +* Scanning Keymaps:: Looking through all keymaps, for printing help. + +Major and Minor Modes + +* Major Modes:: Defining major modes. +* Minor Modes:: Defining minor modes. +* Mode Line Format:: Customizing the text that appears in the mode line. +* Hooks:: How to use hooks; how to write code that + provides hooks. + +Major Modes + +* Major Mode Conventions:: Coding conventions for keymaps, etc. +* Example Major Modes:: Text mode and Lisp modes. +* Auto Major Mode:: How Emacs chooses the major mode automatically. +* Mode Help:: Finding out how to use a mode. + +Minor Modes + +* Minor Mode Conventions:: Tips for writing a minor mode. +* Keymaps and Minor Modes:: How a minor mode can have its own keymap. + +Mode Line Format + +* Mode Line Data:: The data structure that controls the mode line. +* Mode Line Variables:: Variables used in that data structure. +* %-Constructs:: Putting information into a mode line. + +Documentation + +* Documentation Basics:: Good style for doc strings. + Where to put them. How Emacs stores them. +* Accessing Documentation:: How Lisp programs can access doc strings. +* Keys in Documentation:: Substituting current key bindings. +* Describing Characters:: Making printable descriptions of + non-printing characters and key sequences. +* Help Functions:: Subroutines used by Emacs help facilities. + +Files + +* Visiting Files:: Reading files into Emacs buffers for editing. +* Saving Buffers:: Writing changed buffers back into files. +* Reading from Files:: Reading files into other buffers. +* Writing to Files:: Writing new files from parts of buffers. +* File Locks:: Locking and unlocking files, to prevent + simultaneous editing by two people. +* Information about Files:: Testing existence, accessibility, size of files. +* Contents of Directories:: Getting a list of the files in a directory. +* Changing File Attributes:: Renaming files, changing protection, etc. +* File Names:: Decomposing and expanding file names. + +Visiting Files + +* Visiting Functions:: The usual interface functions for visiting. +* Subroutines of Visiting:: Lower-level subroutines that they use. + +Information about Files + +* Testing Accessibility:: Is a given file readable? Writable? +* Kinds of Files:: Is it a directory? A link? +* File Attributes:: How large is it? Any other names? Etc. + +File Names + +* File Name Components:: The directory part of a file name, and the rest. +* Directory Names:: A directory's name as a directory + is different from its name as a file. +* Relative File Names:: Some file names are relative to a + current directory. +* File Name Expansion:: Converting relative file names to absolute ones. +* Unique File Names:: Generating names for temporary files. +* File Name Completion:: Finding the completions for a given file name. + +Backups and Auto-Saving + +* Backup Files:: How backup files are made; how their names + are chosen. +* Auto-Saving:: How auto-save files are made; how their + names are chosen. +* Reverting:: @code{revert-buffer}, and how to customize + what it does. + +Backup Files + +* Making Backups:: How Emacs makes backup files, and when. +* Rename or Copy:: Two alternatives: renaming the old file + or copying it. +* Numbered Backups:: Keeping multiple backups for each source file. +* Backup Names:: How backup file names are computed; customization. + +Buffers + +* Buffer Basics:: What is a buffer? +* Buffer Names:: Accessing and changing buffer names. +* Buffer File Name:: The buffer file name indicates which file + is visited. +* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. +* Modification Time:: Determining whether the visited file was changed + ``behind Emacs's back''. +* Read Only Buffers:: Modifying text is not allowed in a + read-only buffer. +* The Buffer List:: How to look at all the existing buffers. +* Creating Buffers:: Functions that create buffers. +* Killing Buffers:: Buffers exist until explicitly killed. +* Current Buffer:: Designating a buffer as current + so primitives will access its contents. + +Windows + +* Basic Windows:: Basic information on using windows. +* Splitting Windows:: Splitting one window into two windows. +* Deleting Windows:: Deleting a window gives its space to other windows. +* Selecting Windows:: The selected window is the one that you edit in. +* Cyclic Window Ordering:: Moving around the existing windows. +* Buffers and Windows:: Each window displays the contents of a buffer. +* Displaying Buffers:: Higher-lever functions for displaying a buffer + and choosing a window for it. +* Window Point:: Each window has its own location of point. +* Window Start:: The display-start position controls which text + is on-screen in the window. +* Vertical Scrolling:: Moving text up and down in the window. +* Horizontal Scrolling:: Moving text sideways on the window. +* Size of Window:: Accessing the size of a window. +* Resizing Windows:: Changing the size of a window. +* Window Configurations:: Saving and restoring the state of the screen. + +Positions + +* Point:: The special position where editing takes place. +* Motion:: Changing point. +* Excursions:: Temporary motion and buffer changes. +* Narrowing:: Restricting editing to a portion of the buffer. + +Motion + +* Character Motion:: Moving in terms of characters. +* Word Motion:: Moving in terms of words. +* Buffer End Motion:: Moving to the beginning or end of the buffer. +* Text Lines:: Moving in terms of lines of text. +* Screen Lines:: Moving in terms of lines as displayed. +* Vertical Motion:: Implementation of @code{next-line} and + @code{previous-line}. +* List Motion:: Moving by parsing lists and sexps. +* Skipping Characters:: Skipping characters belonging to a certain set. + +Markers + +* Overview of Markers:: The components of a marker, and how it relocates. +* Predicates on Markers:: Testing whether an object is a marker. +* Creating Markers:: Making empty markers or markers at certain places. +* Information from Markers:: Finding the marker's buffer or character + position. +* Changing Markers:: Moving the marker to a new buffer or position. +* The Mark:: How ``the mark'' is implemented with a marker. +* The Region:: How to access ``the region''. + +Text + +* Near Point:: Examining text in the vicinity of point. +* Buffer Contents:: Examining text in a general fashion. +* Insertion:: Adding new text to a buffer. +* Commands for Insertion:: User-level commands to insert text. +* Deletion:: Removing text from a buffer. +* User-Level Deletion:: User-level commands to delete text. +* The Kill Ring:: Where removed text sometimes is saved for + later use. +* Undo:: Undoing changes to the text of a buffer. +* Auto Filling:: How auto-fill mode is implemented to break lines. +* Filling:: Functions for explicit filling. +* Sorting:: Functions for sorting parts of the buffer. +* Indentation:: Functions to insert or adjust indentation. +* Columns:: Computing horizontal positions, and using them. +* Case Changes:: Case conversion of parts of the buffer. +* Substitution:: Replacing a given character wherever it appears. +* Underlining:: Inserting or deleting underlining-by-overstrike. +* Registers:: How registers are implemented. Accessing + the text or position stored in a register. + +The Kill Ring + +* Kill Ring Concepts:: What text looks like in the kill ring. +* Kill Functions:: Functions that kill text. +* Yank Commands:: Commands that access the kill ring. +* Low Level Kill Ring:: Functions and variables for kill ring access. +* Internals of Kill Ring:: Variables that hold kill-ring data. + +Indentation + +* Primitive Indent:: Functions used to count and insert indentation. +* Mode-Specific Indent:: Customize indentation for different modes. +* Region Indent:: Indent all the lines in a region. +* Relative Indent:: Indent the current line based on previous lines. +* Indent Tabs:: Adjustable, typewriter-like tab stops. +* Motion by Indent:: Move to first non-blank character. + +Searching and Matching + +* String Search:: Search for an exact match. +* Regular Expressions:: Describing classes of strings. +* Regexp Search:: Searching for a match for a regexp. +* Match Data:: Finding out which part of the text matched + various parts of a regexp, after regexp search. +* Saving Match Data:: Saving and restoring this information. +* Standard Regexps:: Useful regexps for finding sentences, pages,... +* Searching and Case:: Case-independent or case-significant searching. + +Regular Expressions + +* Syntax of Regexps:: Rules for writing regular expressions. +* Regexp Example:: Illustrates regular expression syntax. + +Syntax Tables + +* Syntax Descriptors:: How characters are classified. +* Syntax Table Functions:: How to create, examine and alter syntax tables. +* Parsing Expressions:: Parsing balanced expressions + using the syntax table. +* Standard Syntax Tables:: Syntax tables used by various major modes. +* Syntax Table Internals:: How syntax table information is stored. + +Syntax Descriptors + +* Syntax Class Table:: Table of syntax classes. +* Syntax Flags:: Additional flags each character can have. + +Abbrevs And Abbrev Expansion + +* Abbrev Mode:: Setting up Emacs for abbreviation. +* Tables: Abbrev Tables. Creating and working with abbrev tables. +* Defining Abbrevs:: Specifying abbreviations and their expansions. +* Files: Abbrev Files. Saving abbrevs in files. +* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. +* Standard Abbrev Tables:: Abbrev tables used by various major modes. + +Processes + +* Subprocess Creation:: Functions that start subprocesses. +* Synchronous Processes:: Details of using synchronous subprocesses. +* Asynchronous Processes:: Starting up an asynchronous subprocess. +* Deleting Processes:: Eliminating an asynchronous subprocess. +* Process Information:: Accessing run-status and other attributes. +* Input to Processes:: Sending input to an asynchronous subprocess. +* Signals to Processes:: Stopping, continuing or interrupting + an asynchronous subprocess. +* Output from Processes:: Collecting output from an asynchronous subprocess. +* Sentinels:: Sentinels run when process run-status changes. +* TCP:: Opening network connections. + +Receiving Output from Processes + +* Process Buffers:: If no filter, output is put in a buffer. +* Filter Functions:: Filter functions accept output from the process. +* Accepting Output:: How to wait until process output arrives. + +Operating System Interface + +* Starting Up:: Customizing Emacs start-up processing. +* Getting Out:: How exiting works (permanent or temporary). +* System Environment:: Distinguish the name and kind of system. +* Terminal Input:: Recording terminal input for debugging. +* Terminal Output:: Recording terminal output for debugging. +* Flow Control:: How to turn output flow control on or off. +* Batch Mode:: Running Emacs without terminal interaction. + +Starting Up Emacs + +* Start-up Summary:: Sequence of actions Emacs performs at start-up. +* Init File:: Details on reading the init file (@file{.emacs}). +* Terminal-Specific:: How the terminal-specific Lisp file is read. +* Command Line Arguments:: How command line arguments are processed, + and how you can customize them. + +Getting out of Emacs + +* Killing Emacs:: Exiting Emacs irreversibly. +* Suspending Emacs:: Exiting Emacs reversibly. + +Emacs Display + +* Refresh Screen:: Clearing the screen and redrawing everything on it. +* 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:: How Emacs shows the matching open parenthesis. +* Usual Display:: How control characters are displayed. +* Beeping:: Audible signal to the user. +* Window Systems:: Which window system is being used. + +GNU Emacs Internals + +* Building Emacs:: How to preload Lisp libraries into Emacs. +* Pure Storage:: A kludge to make preloaded Lisp functions sharable. +* Garbage Collection:: Reclaiming space for Lisp objects no longer used. +* Object Internals:: Data formats of buffers, windows, processes. +* Writing Emacs Primitives:: Writing C code for Emacs. + +Object Internals + +* Buffer Internals:: Components of a buffer structure. +* Window Internals:: Components of a window structure. +* Process Internals:: Components of a process structure. +@end menu + +@include intro.texi +@include objects.texi +@include numbers.texi +@include strings.texi + +@include lists.texi +@include sequences.texi +@include symbols.texi +@include eval.texi + +@include control.texi +@include variables.texi +@include functions.texi +@include macros.texi + +@include loading.texi +@include compile.texi +@include debugging.texi +@include streams.texi + +@include minibuf.texi +@include commands.texi +@include keymaps.texi +@include modes.texi + +@include help.texi +@include files.texi +@include backups.texi +@include buffers.texi + +@include windows.texi +@include frames.texi +@include positions.texi +@include markers.texi +@include text.texi + +@include searching.texi +@include syntax.texi +@include abbrevs.texi + +@include processes.texi +@include os.texi +@include display.texi +@include calendar.texi + +@c MOVE to Emacs Manual: include misc-modes.texi + +@c appendices + +@c REMOVE this: include non-hacker.texi + +@include tips.texi +@include internals.texi +@include errors.texi +@include locals.texi +@include maps.texi +@include hooks.texi +@include anti.texi + +@include index.texi + +@c Print the tables of contents +@summarycontents +@contents +@c That's all + +@bye + + +These words prevent "local variables" above from confusing Emacs.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/internals.texi Mon Mar 21 07:49:21 1994 +0000 @@ -0,0 +1,807 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/internals +@node GNU Emacs Internals, Standard Errors, Tips, Top +@comment node-name, next, previous, up +@appendix GNU Emacs Internals + +This chapter describes how the runnable Emacs executable is dumped with +the preloaded Lisp libraries in it, how storage is allocated, and some +internal aspects of GNU Emacs that may be of interest to C programmers. + +@menu +* Building Emacs:: How to preload Lisp libraries into Emacs. +* Pure Storage:: A kludge to make preloaded Lisp functions sharable. +* Garbage Collection:: Reclaiming space for Lisp objects no longer used. +* Writing Emacs Primitives:: Writing C code for Emacs. +* Object Internals:: Data formats of buffers, windows, processes. +@end menu + +@node Building Emacs, Pure Storage, GNU Emacs Internals, GNU Emacs Internals +@appendixsec Building Emacs +@cindex building Emacs +@pindex temacs + + This section explains the steps involved in building the Emacs +executable. You don't have to know this material to build and install +Emacs, since the makefiles do all these things automatically. This +information is pertinent to Emacs maintenance. + + Compilation of the C source files in the @file{src} directory +produces an executable file called @file{temacs}, also called a +@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O +routines, but not the editing commands. + +@cindex @file{loadup.el} + The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create +the real runnable Emacs executable. These arguments direct +@file{temacs} to evaluate the Lisp files specified in the file +@file{loadup.el}. These files set up the normal Emacs editing +environment, resulting in an Emacs which is still impure but no longer +bare. + + It takes a substantial time to load the standard Lisp files. Luckily, +you don't have to do this each time you run Emacs; @file{temacs} can +dump out an executable program called @file{emacs} which has these files +preloaded. @file{emacs} starts more quickly because it does not need to +load the files. This is the Emacs executable that is normally +installed. + + To create @file{emacs}, use the command @samp{temacs -batch -l loadup +dump}. The purpose of @samp{-batch} here is to prevent @file{temacs} +from trying to initialize any of its data on the terminal; this ensures +that the tables of terminal information are empty in the dumped Emacs. +The argument @samp{dump} tells @file{loadup.el} to dump a new executable +named @file{emacs}. + + Some operating systems don't support dumping. On those systems, you +must start Emacs with the @samp{temacs -l loadup} command each time you +use it. This takes a long time, but since you need to start Emacs once +a day at most---or once a week if you never log out---the extra time is +not too severe a problem. + +@cindex @file{site-load.el} + You can specify additional files to preload by writing a library named +@file{site-load.el} which loads them. You may need to increase the +value of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the +additional files. (Try adding increments of 20000 until it is big +enough.) However, the advantage of preloading additional files +decreases as machines get faster. On modern machines, it is usually not +advisable. + +@cindex @file{site-init.el} + You can specify other things to be done in Lisp just before dumping by +putting them in a library named @file{site-init.el}. However, if these +things might alter the behavior that users expect from an ordinary +unmodified Emacs, it is better to do them in @file{default.el}, so that +users can override them if they wish. @xref{Start-up Summary}. + + Before @file{emacs} is dumped, the documentation strings for primitive +and preloaded functions (and variables) need to be found in the file +where they are stored. This is done by calling +@code{Snarf-documentation} (@pxref{Accessing Documentation}). These +strings were moved out of @file{emacs} to make it smaller. +@xref{Documentation Basics}. + +@defun dump-emacs to-file from-file +@cindex unexec + This function dumps the current state of Emacs into an executable file +@var{to-file}. It takes symbols from @var{from-file} (this is normally +the executable file @file{temacs}). + +If you use this function in an Emacs that was already dumped, you must +set @code{command-line-processed} to @code{nil} first for good results. +@xref{Command Line Arguments}. +@end defun + +@deffn Command 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. + +@example +@group +(emacs-version) + @result{} "GNU Emacs 19.22.1 of Fri Feb 27 1994 \ +on slug (berkeley-unix)" +@end group +@end example + +Called interactively, the function prints the same information in the +echo area. +@end deffn + +@defvar emacs-build-time + The value of this variable is the time at which Emacs was built at the +local site. + +@example +@group +emacs-build-time + @result{} "Fri Feb 27 14:55:57 1994" +@end group +@end example +@end defvar + +@defvar emacs-version +The value of this variable is the version of Emacs being run. It is a +string such as @code{"19.22.1"}. +@end defvar + +@node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals +@appendixsec Pure Storage +@cindex pure storage + + There are two types of storage in GNU Emacs Lisp for user-created Lisp +objects: @dfn{normal storage} and @dfn{pure storage}. Normal storage is +where all the new data which is created during an Emacs session is kept; +see the following section for information on normal storage. Pure +storage is used for certain data in the preloaded standard Lisp files: +data that should never change during actual use of Emacs. + + Pure storage is allocated only while @file{temacs} is loading the +standard preloaded Lisp libraries. In the file @file{emacs}, it is +marked as read-only (on operating systems which permit this), so that +the memory space can be shared by all the Emacs jobs running on the +machine at once. Pure storage is not expandable; a fixed amount is +allocated when Emacs is compiled, and if that is not sufficient for the +preloaded libraries, @file{temacs} crashes. If that happens, you will +have to increase the compilation parameter @code{PURESIZE} in the file +@file{src/puresize.h}. This normally won't happen unless you try to +preload additional libraries or add features to the standard ones. + +@defun purecopy object + This function makes a copy of @var{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; it is +called only in the file @file{emacs/lisp/loaddefs.el}. +@end defun + +@defvar 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 available---if it were not, +we would preallocate less. +@end defvar + +@defvar purify-flag + This variable determines whether @code{defun} should make a copy of the +function definition in pure storage. If it is non-@code{nil}, then the +function definition is copied into pure storage. + + This flag is @code{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 @code{nil} when Emacs is saved out +as @file{emacs}. The flag is set and reset in the C sources. + + You should not change this flag in a running Emacs. +@end defvar + +@node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals +@appendixsec Garbage Collection +@cindex garbage collector + +@cindex memory allocation + When a program creates a list or the user defines a new function (such +as by loading a library), then that data is placed in normal storage. +If normal storage runs low, then Emacs asks the operating system to +allocate more memory in blocks of 1k bytes. Each block is used for one +type of Lisp object, so symbols, cons cells, markers, etc.@: are +segregated in distinct blocks in memory. (Vectors, buffers and certain +other editing types, which are fairly large, are allocated in individual +blocks, one per object, while strings are packed into blocks of 8k +bytes.) + + It is quite common to use some storage for a while, then release it +by, for example, killing a buffer or deleting the last pointer to an +object. Emacs provides a @dfn{garbage collector} to reclaim this +abandoned storage. (This name is traditional, but ``garbage recycler'' +might be a more intuitive metaphor for this facility.) + + The garbage collector operates by scanning all the objects that have +been allocated and marking those that are still accessible to Lisp +programs. To begin with, all the symbols, their values and associated +function definitions, and any data presently on the stack, are +accessible. Any objects which can be reached indirectly through other +accessible objects are also accessible. + + When this is finished, all inaccessible objects are garbage. No +matter what the Lisp program or the user does, it is impossible to refer +to them, since there is no longer a way to reach them. Their +space might as well be reused, since no one will notice. That is what +the garbage collector arranges to do. + +@cindex free list + Unused cons cells are chained together onto a @dfn{free list} for +future allocation; likewise for symbols and markers. The accessible +strings are compacted so they are contiguous in memory; then the rest of +the space formerly occupied by strings is made available to the string +creation functions. Vectors, buffers, windows and other large objects +are individually allocated and freed using @code{malloc}. + +@cindex CL note---allocate more storage +@quotation +@b{Common Lisp note:} unlike other Lisps, GNU Emacs Lisp does not +call the garbage collector when the free list is empty. Instead, it +simply requests the operating system to allocate more storage, and +processing continues until @code{gc-cons-threshold} bytes have been +used. + +This means that you can make sure that the garbage collector will not +run during a certain portion of a Lisp program by calling the garbage +collector explicitly just before it (provided that portion of the +program does not use so much space as to force a second garbage +collection). +@end quotation + +@deffn Command garbage-collect + This command runs a garbage collection, and returns information on +the amount of space in use. (Garbage collection can also occur +spontaneously if you use more than @code{gc-cons-threshold} bytes of +Lisp data since the previous garbage collection.) + + @code{garbage-collect} returns a list containing the following +information: + +@smallexample +@group +((@var{used-conses} . @var{free-conses}) + (@var{used-syms} . @var{free-syms}) + (@var{used-markers} . @var{free-markers}) + @var{used-string-chars} + @var{used-vector-slots} + (@var{used-floats} . @var{free-floats})) + +(garbage-collect) + @result{} ((3435 . 2332) (1688 . 0) + (57 . 417) 24510 3839 (4 . 1)) +@end group +@end smallexample + +Here is a table explaining each element: + +@table @var +@item used-conses +The number of cons cells in use. + +@item free-conses +The number of cons cells for which space has been obtained from the +operating system, but that are not currently being used. + +@item used-syms +The number of symbols in use. + +@item free-syms +The number of symbols for which space has been obtained from the +operating system, but that are not currently being used. + +@item used-markers +The number of markers in use. + +@item free-markers +The number of markers for which space has been obtained from the +operating system, but that are not currently being used. + +@item used-string-chars +The total size of all strings, in characters. + +@item used-vector-slots +The total number of elements of existing vectors. + +@item used-floats +@c Emacs 19 feature +The number of floats in use. + +@item free-floats +@c Emacs 19 feature +The number of floats for which space has been obtained from the +operating system, but that are not currently being used. +@end table +@end deffn + +@defopt gc-cons-threshold + The value of this variable is the number of bytes of storage that must +be allocated for Lisp objects after one garbage collection in order to +request another garbage collection. A cons cell counts as eight bytes, +a string as one byte per character plus a few bytes of overhead, and so +on. (Space allocated to the contents of buffers does not count.) Note +that the new garbage collection does not happen immediately when the +threshold is exhausted, but only the next time the Lisp evaluator is +called. + + The initial threshold value is 100,000. If you specify a larger +value, garbage collection will happen less often. This reduces the +amount of time spent garbage collecting, but increases total memory use. +You may want to do this when running a program which creates lots of +Lisp data. + + You can make collections more frequent by specifying a smaller value, +down to 10,000. A value less than 10,000 will remain in effect only +until the subsequent garbage collection, at which time +@code{garbage-collect} will set the threshold back to 10,000. +@end defopt + +@c Emacs 19 feature +@defun memory-limit +This function returns the address of the last byte Emacs has allocated, +divided by 1024. We divide the value by 1024 to make sure it fits in a +Lisp integer. + +You can use this to get a general idea of how your actions affect the +memory usage. +@end defun + +@node Writing Emacs Primitives, Object Internals, Garbage Collection, GNU Emacs Internals +@appendixsec Writing Emacs Primitives +@cindex primitive function internals + + Lisp primitives are Lisp functions implemented in C. The details of +interfacing the C function so that Lisp can call it are handled by a few +C macros. The only way to really understand how to write new C code is +to read the source, but we can explain some things here. + + An example of a special form is the definition of @code{or}, from +@file{eval.c}. (An ordinary function would have the same general +appearance.) + +@cindex garbage collection protection +@smallexample +@group +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\ +@end group +@group +If all args return NIL, return NIL.") + (args) + Lisp_Object args; +@{ + register Lisp_Object val; + Lisp_Object args_left; + struct gcpro gcpro1; +@end group + +@group + if (NULL(args)) + return Qnil; + + args_left = args; + GCPRO1 (args_left); +@end group + +@group + do + @{ + val = Feval (Fcar (args_left)); + if (!NULL (val)) + break; + args_left = Fcdr (args_left); + @} + while (!NULL(args_left)); +@end group + +@group + UNGCPRO; + return val; +@} +@end group +@end smallexample + + Let's start with a precise explanation of the arguments to the +@code{DEFUN} macro. Here are the general names for them: + +@example +DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) +@end example + +@table @var +@item lname +This is the name of the Lisp symbol to define with this +function; in the example above, it is @code{or}. + +@item fname +This 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, @samp{F} prepended to the Lisp name, with all dashes +(@samp{-}) in the Lisp name changed to underscores. Thus, to call this +function from C code, call @code{For}. Remember that the arguments must +be of type @code{Lisp_Object}; various macros and functions for creating +values of type @code{Lisp_Object} are declared in the file +@file{lisp.h}. + +@item sname +This is a C variable name to use for a structure that holds the data for +the subr object that represents the function in Lisp. This structure +conveys the Lisp symbol name to the initialization routine that will +create the symbol and store the subr object as its definition. By +convention, this name is always @var{fname} with @samp{F} replaced with +@samp{S}. + +@item min +This is the minimum number of arguments that the function requires. For +@code{or}, no arguments are required. + +@item max +This is the maximum number of arguments that the function accepts. +Alternatively, it can be @code{UNEVALLED}, indicating a special form +that receives unevaluated arguments. A function with the equivalent of +an @code{&rest} argument would have @code{MANY} in this position. Both +@code{UNEVALLED} and @code{MANY} are macros. This argument must be one +of these macros or a number at least as large as @var{min}. It may not +be greater than six. + +@item interactive +This is an interactive specification, a string such as might be used as +the argument of @code{interactive} in a Lisp function. In the case of +@code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be +called interactively. A value of @code{""} indicates an interactive +function taking no arguments. + +@item doc +This is the documentation string. It is written just like a +documentation string for a function defined in Lisp, except you must +write @samp{\n\} at the end of each line. In particular, the first line +should be a single sentence. +@end table + + After the call to the @code{DEFUN} macro, you must write the list +of argument names that every C function must have, followed by +ordinary C declarations for them. Normally, all the arguments must +be declared as @code{Lisp_Object}. If the function has no upper limit +on the number of arguments in Lisp, then in C it receives two arguments: +the number of Lisp arguments, and the address of a block containing their +values. These have types @code{int} and @w{@code{Lisp_Object *}}. + + Within the function @code{For} itself, note the use of the macros +@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``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. This 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 you intend to refer to again must be protected somehow. +@code{UNGCPRO} cancels the protection of the variables that are +protected in the current function. It is necessary to do this explicitly. + + For most data types, it suffices to know that one pointer to the +object is protected; as long as the object is not recycled, all pointers +to it remain valid. This is not so for strings, because the garbage +collector can move them. When a string is moved, any pointers to it +that the garbage collector does not know about will not be properly +relocated. Therefore, all pointers to strings must be protected across +any point where garbage collection may be possible. + + The macro @code{GCPRO1} protects just one local variable. If you +want to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} +will not work. There are also @code{GCPRO3} and @code{GCPRO4}. + + In addition to using these macros, you must declare the local +variables such as @code{gcpro1} which they implicitly use. If you +protect two variables, with @code{GCPRO2}, you must declare +@code{gcpro1} and @code{gcpro2}, as it uses them both. Alas, we can't +explain all the tricky details here. + + Defining the C function is not enough; you must also create the +Lisp symbol for the primitive and store a suitable subr object +in its function cell. This is done by adding code to an initialization +routine. The code looks like this: + +@example +defsubr (&@var{subr-structure-name}); +@end example + +@noindent +@var{subr-structure-name} is the name you used as the third argument to +@code{DEFUN}. + + If you are adding a primitive to a file that already has Lisp +primitives defined in it, find the function (near the end of the file) +named @code{syms_of_@var{something}}, and add that function call to it. +If the file doesn't have this function, or if you create a new file, add +to it a @code{syms_of_@var{filename}} (e.g., @code{syms_of_myfile}). +Then find the spot in @file{emacs.c} where all of these functions are +called, and add a call to @code{syms_of_@var{filename}} there. + + This function @code{syms_of_@var{filename}} is also the place to +define any C variables which are to be visible as Lisp variables. +@code{DEFVAR_LISP} is used to make a C variable of type +@code{Lisp_Object} visible in Lisp. @code{DEFVAR_INT} is used to make a +C variable of type @code{int} visible in Lisp with a value that is an +integer. + + 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. + +@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 POSITIONS is in WINDOW.\n\ + \(POSITIONS is a list, (SCREEN-X SCREEN-Y)\)\n\ +@end group +@group + 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; +@end group + +@group + if (!CONSP (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); +@end group +@group + 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); +@end group +@group + if (XINT (ycoord) == (screen_height - 1)) + return Qnil; +@end group +@group + if ((XINT (ycoord) < XINT (XWINDOW (window)->top)) + || (XINT (ycoord) >= (XINT (XWINDOW (window)->top) + + XINT (XWINDOW (window)->height)) - 1)) + @{ + return Qnil; + @} +@end group +@group + XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top); + return (Fcons (xcoord, Fcons (ycoord, Qnil))); +@} +@end group +@end smallexample + + Note that you cannot directly call functions defined in Lisp as, for +example, the primitive function @code{Fcons} is called above. You must +create the appropriate Lisp form, protect everything from garbage +collection, and @code{Feval} the form, as was done in @code{For} above. + + @file{eval.c} is a very good file to look through for examples; +@file{lisp.h} contains the definitions for some important macros and +functions. + +@node Object Internals, , Writing Emacs Primitives, GNU Emacs Internals +@appendixsec Object Internals +@cindex object internals + + 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. 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 +address 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 (@pxref{Type Predicates}). +@cindex type checking internals + +@menu +* Buffer Internals:: Components of a buffer structure. +* Window Internals:: Components of a window structure. +* Process Internals:: Components of a process structure. +@end menu + +@node Buffer Internals, Window Internals, Object Internals, Object Internals +@appendixsubsec Buffer Internals +@cindex internals, of buffer +@cindex buffer internals + + Buffers contain fields not directly accessible by the Lisp programmer. +We describe them here, naming them by the names used in the C code. +Many are accessible indirectly in Lisp programs via Lisp primitives. + +@table @code +@item name +The buffer name is a string which names the buffer. It is guaranteed to +be unique. @xref{Buffer Names}. + +@item save_modified +This field contains the time when the buffer was last saved, as an integer. +@xref{Buffer Modification}. + +@item modtime +This field contains the 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 time of the +file. @xref{Buffer Modification}. + +@item auto_save_modified +This field contains the time when the buffer was last auto-saved. + +@item last_window_start +This field contains the @code{window-start} position in the buffer as of +the last time the buffer was displayed in a window. + +@item undodata +This field points to the buffer's undo stack. @xref{Undo}. + +@item syntax_table_v +This field contains the syntax table for the buffer. @xref{Syntax Tables}. + +@item downcase_table +This field contains the conversion table for converting text to lower case. +@xref{Case Table}. + +@item upcase_table +This field contains the conversion table for converting text to upper case. +@xref{Case Table}. + +@item case_canon_table +This field contains the conversion table for canonicalizing text for +case-folding search. @xref{Case Table}. + +@item case_eqv_table +This field contains the equivalence table for case-folding search. +@xref{Case Table}. + +@item display_table +This field contains the buffer's display table, or @code{nil} if it doesn't +have one. @xref{Display Tables}. + +@item 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. @xref{Markers}. + +@item backed_up +This field is a flag which tells whether a backup file has been made +for the visited file of this buffer. + +@item mark +This field contains the mark for the buffer. The mark is a marker, +hence it is also included on the list @code{markers}. @xref{The Mark}. + +@item local_var_alist +This field contains the association list containing all of the variables +local in this buffer, and their values. The function +@code{buffer-local-variables} returns a copy of this list. +@xref{Buffer-Local Variables}. + +@item mode_line_format +This field contains a Lisp object which controls how to display the mode +line for this buffer. @xref{Mode Line Format}. +@end table + +@node Window Internals, Process Internals, Buffer Internals, Object Internals +@appendixsubsec Window Internals +@cindex internals, of window +@cindex window internals + + Windows have the following accessible fields: + +@table @code +@item frame + The frame that this window is on. + +@item mini_p + Non-@code{nil} if this window is a minibuffer window. + +@item height + The height of the window, measured in lines. + +@item width + The width of the window, measured in columns. + +@item buffer + The buffer which the window is displaying. This may change often during +the life of the window. + +@item dedicated + Non-@code{nil} if this window is dedicated to its buffer. + +@item start + The position in the buffer which is the first character to be displayed +in the window. + +@item pointm +@cindex window point internals + This is the value of point in the current buffer when this window is +selected; when it is not selected, it retains its previous value. + +@item left + This is the left-hand edge of the window, measured in columns. (The +leftmost column on the screen is @w{column 0}.) + +@item top + This is the top edge of the window, measured in lines. (The top line on +the screen is @w{line 0}.) + +@item next + This is the window that is the next in the chain of siblings. + +@item prev + This is the window that is the previous in the chain of siblings. + +@item force_start + This is a flag which, if non-@code{nil}, says that the window has been +scrolled explicitly by the Lisp program. At the next redisplay, if +point is off the screen, instead of scrolling the window to show the +text around point, point will be moved to a location that is on the +screen. + +@item hscroll + This is the number of columns that the display in the window is scrolled +horizontally to the left. Normally, this is 0. + +@item use_time + This is the last time that the window was selected. The function +@code{get-lru-window} uses this field. + +@item display_table + The window's display table, or @code{nil} if none is specified for it. +@end table + +@node Process Internals, , Window Internals, Object Internals +@appendixsubsec Process Internals +@cindex internals, of process +@cindex process internals + + The fields of a process are: + +@table @code +@item name +A string, the name of the process. + +@item command +A list containing the command arguments that were used to start this +process. + +@item filter +A function used to accept output from the process instead of a buffer, +or @code{nil}. + +@item sentinel +A function called whenever the process receives a signal, or @code{nil}. + +@item buffer +The associated buffer of the process. + +@item pid +An integer, the Unix process @sc{id}. + +@item childp +A flag, non-@code{nil} if this is really a child process. +It is @code{nil} for a network connection. + +@item flags +A symbol indicating the state of the process. Possible values include +@code{run}, @code{stop}, @code{closed}, etc. + +@item reason +An integer, the Unix signal number that the process received that +caused the process to terminate or stop. If the process has exited, +then this is the exit code it specified. + +@item mark +A marker indicating the position of end of last output from this process +inserted into the buffer. This is usually the end of the buffer. + +@item kill_without_query +A flag, non-@code{nil} meaning this process should not cause +confirmation to be needed if Emacs is killed. +@end table
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/maps.texi Mon Mar 21 07:49:21 1994 +0000 @@ -0,0 +1,133 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/maps +@node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top +@appendix Standard Keymaps + +The following symbols are used as the names for various keymaps. +Some of these exist when Emacs is first started, others are +only loaded when their respective mode is used. This is not +an exhaustive list. + +Almost all of these maps are used as local maps. Indeed, of the modes +that presently exist, only Vip mode and Terminal mode ever change the +global keymap. + +@table @code +@item Buffer-menu-mode-map +@vindex Buffer-menu-mode-map +A full keymap used by Buffer Menu mode. + +@item c-mode-map +@vindex c-mode-map +A sparse keymap used in C mode as a local map. + +@item command-history-map +@vindex command-history-map +A full keymap used by Command History mode. + +@item ctl-x-4-map +A sparse keymap for subcommands of the prefix @kbd{C-x 4}. + +@item ctl-x-map +A full keymap for @kbd{C-x} commands. + +@item debugger-mode-map +@vindex debugger-mode-map +A full keymap used by Debugger mode. + +@item dired-mode-map +@vindex dired-mode-map +A full keymap for @code{dired-mode} buffers. + +@item doctor-mode-map +@vindex doctor-mode-map +A sparse keymap used by Doctor mode. + +@item edit-abbrevs-map +@vindex edit-abbrevs-map +A sparse keymap used in @code{edit-abbrevs}. + +@item edit-tab-stops-map +@vindex edit-tab-stops-map +A sparse keymap used in @code{edit-tab-stops}. + +@item electric-buffer-menu-mode-map +@vindex electric-buffer-menu-mode-map +A full keymap used by Electric Buffer Menu mode. + +@item electric-history-map +@vindex electric-history-map +A full keymap used by Electric Command History mode. + +@item emacs-lisp-mode-map +@vindex emacs-lisp-mode-map +A sparse keymap used in Emacs Lisp mode. + +@item function-key-map +@vindex function-key-map +The keymap for translating keypad and function keys.@* +If there are none, then it contains an empty sparse keymap. + +@item fundamental-mode-map +@vindex fundamental-mode-map +The local keymap for Fundamental mode.@* +It is empty and should not be changed. + +@item Helper-help-map +@vindex Helper-help-map +A full keymap used by the help utility package.@* +It has the same keymap in its value cell and in its function +cell. + +@item Info-edit-map +@vindex Info-edit-map +A sparse keymap used by the @kbd{e} command of Info. + +@item Info-mode-map +@vindex Info-mode-map +A sparse keymap containing Info commands. + +@item isearch-mode-map +A keymap that defines the characters you can type within incremental +search. + +@item key-translation-map +@vindex key-translation-map +Another keymap for translating keys. This one overrides ordinary key +bindings. + +@item lisp-interaction-mode-map +@vindex lisp-interaction-mode-map +A sparse keymap used in Lisp mode. + +@item lisp-mode-map +@vindex lisp-mode-map +A sparse keymap used in Lisp mode. + +@item mode-specific-map +The keymap for characters following @kbd{C-c}. Note, this is in the +global map. This map is not actually mode specific: its name was chosen +to be informative for the user in @kbd{C-h b} (@code{display-bindings}), +where it describes the main use of the @kbd{C-c} prefix key. + +@item occur-mode-map +@vindex occur-mode-map +A local keymap used in Occur mode. + +@item query-replace-map +A local keymap used for responses in @code{query-replace} and related +commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions +that use this map do not support prefix keys; they look up one event at a +time. + +@item text-mode-map +@vindex text-mode-map +A sparse keymap used by Text mode. + +@item view-mode-map +@vindex view-mode-map +A full keymap used by View mode. +@end table
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/modes.texi Mon Mar 21 07:49:21 1994 +0000 @@ -0,0 +1,1364 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/modes +@node Modes, Documentation, Keymaps, Top +@chapter Major and Minor Modes +@cindex mode + + A @dfn{mode} is a set of definitions that customize Emacs and can be +turned on and off while you edit. There are two varieties of modes: +@dfn{major modes}, which are mutually exclusive and used for editing +particular kinds of text, and @dfn{minor modes}, which provide features +that users can enable individually. + + This chapter describes how to write both major and minor modes, how to +indicate them in the mode line, and how they run hooks supplied by the +user. For related topics such as keymaps and syntax tables, see +@ref{Keymaps}, and @ref{Syntax Tables}. + +@menu +* Major Modes:: Defining major modes. +* Minor Modes:: Defining minor modes. +* Mode Line Format:: Customizing the text that appears in the mode line. +* Hooks:: How to use hooks; how to write code that provides hooks. +@end menu + +@node Major Modes +@section Major Modes +@cindex major mode +@cindex Fundamental mode + + Major modes specialize Emacs for editing particular kinds of text. +Each buffer has only one major mode at a time. + + The least specialized major mode is called @dfn{Fundamental mode}. +This mode has no mode-specific definitions or variable settings, so each +Emacs command behaves in its default manner, and each option is in its +default state. All other major modes redefine various keys and options. +For example, Lisp Interaction mode provides special key bindings for +@key{LFD} (@code{eval-print-last-sexp}), @key{TAB} +(@code{lisp-indent-line}), and other keys. + + When you need to write several editing commands to help you perform a +specialized editing task, creating a new major mode is usually a good +idea. In practice, writing a major mode is easy (in contrast to +writing a minor mode, which is often difficult). + + If the new mode is similar to an old one, it is often unwise to modify +the old one to serve two purposes, since it may become harder to use and +maintain. Instead, copy and rename an existing major mode definition +and alter the copy---or define a @dfn{derived mode} (@pxref{Derived +Modes}). For example, Rmail Edit mode, which is in +@file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to +Text mode except that it provides three additional commands. Its +definition is distinct from that of Text mode, but was derived from it. + + Rmail Edit mode is an example of a case where one piece of text is put +temporarily into a different major mode so it can be edited in a +different way (with ordinary Emacs commands rather than Rmail). In such +cases, the temporary major mode usually has a command to switch back to +the buffer's usual mode (Rmail mode, in this case). You might be +tempted to present the temporary redefinitions inside a recursive edit +and restore the usual ones when the user exits; but this is a bad idea +because it constrains the user's options when it is done in more than +one buffer: recursive edits must be exited most-recently-entered first. +Using alternative major modes avoids this limitation. @xref{Recursive +Editing}. + + The standard GNU Emacs Lisp library directory contains the code for +several major modes, in files including @file{text-mode.el}, +@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and +@file{rmail.el}. You can look at these libraries to see how modes are +written. Text mode is perhaps the simplest major mode aside from +Fundamental mode. Rmail mode is a complicated and specialized mode. + +@menu +* Major Mode Conventions:: Coding conventions for keymaps, etc. +* Example Major Modes:: Text mode and Lisp modes. +* Auto Major Mode:: How Emacs chooses the major mode automatically. +* Mode Help:: Finding out how to use a mode. +* Derived Modes:: Defining a new major mode based on another major + mode. +@end menu + +@node Major Mode Conventions +@subsection Major Mode Conventions + + The code for existing major modes follows various coding conventions, +including conventions for local keymap and syntax table initialization, +global names, and hooks. Please follow these conventions when you +define a new major mode: + +@itemize @bullet +@item +Define a command whose name ends in @samp{-mode}, with no arguments, +that switches to the new mode in the current buffer. This command +should set up the keymap, syntax table, and local variables in an +existing buffer without changing the buffer's text. + +@item +Write a documentation string for this command which describes the +special commands available in this mode. @kbd{C-h m} +(@code{describe-mode}) in your mode will display this string. + +The documentation string may include the special documentation +substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and +@samp{\<@var{keymap}>}, that enable the documentation to adapt +automatically to the user's own key bindings. @xref{Keys in +Documentation}. + +@item +The major mode command should start by calling +@code{kill-all-local-variables}. This is what gets rid of the local +variables of the major mode previously in effect. + +@item +The major mode command should set the variable @code{major-mode} to the +major mode command symbol. This is how @code{describe-mode} discovers +which documentation to print. + +@item +The major mode command should set the variable @code{mode-name} to the +``pretty'' name of the mode, as a string. This appears in the mode +line. + +@item +@cindex functions in modes +Since all global names are in the same name space, all the global +variables, constants, and functions that are part of the mode should +have names that start with the major mode name (or with an abbreviation +of it if the name is long). @xref{Style Tips}. + +@item +@cindex keymaps in modes +The major mode should usually have its own keymap, which is used as the +local keymap in all buffers in that mode. The major mode function +should call @code{use-local-map} to install this local map. +@xref{Active Keymaps}, for more information. + +This keymap should be kept in a global variable named +@code{@var{modename}-mode-map}. Normally the library that defines the +mode sets this variable. Use @code{defvar} to set the variable, so that +it is not reinitialized if it already has a value. (Such +reinitialization could discard customizations made by the user.) + +@item +@cindex syntax tables in modes +The mode may have its own syntax table or may share one with other +related modes. If it has its own syntax table, it should store this in +a variable named @code{@var{modename}-mode-syntax-table}. The reasons +for this are the same as for using a keymap variable. @xref{Syntax +Tables}. + +@item +@cindex abbrev tables in modes +The mode may have its own abbrev table or may share one with other +related modes. If it has its own abbrev table, it should store this in +a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev +Tables}. + +@item +@cindex buffer-local variables in modes +To make a buffer-local binding for an Emacs customization variable, use +@code{make-local-variable} in the major mode command, not +@code{make-variable-buffer-local}. The latter function would make the +variable local to every buffer in which it is subsequently set, which +would affect buffers that do not use this mode. It is undesirable for a +mode to have such global effects. @xref{Buffer-Local Variables}. + +It's ok to use @code{make-variable-buffer-local}, if you wish, for a +variable used only within a single Lisp package. + +@item +@cindex mode hook +@cindex major mode hook +Each major mode should have a @dfn{mode hook} named +@code{@var{modename}-mode-hook}. The major mode command should run that +hook, with @code{run-hooks}, as the very last thing it +does. @xref{Hooks}. + +@item +The major mode command may also run the hooks of some more basic modes. +For example, @code{indented-text-mode} runs @code{text-mode-hook} as +well as @code{indented-text-mode-hook}. It may run these other hooks +immediately before the mode's own hook (that is, after everything else), +or it may run them earlier. + +@item +If something special should be done if the user switches a buffer from +this mode to any other major mode, the mode can set a local value for +@code{change-major-mode-hook}. + +@item +If this mode is appropriate only for specially-prepared text, then the +major mode command symbol should have a property named @code{mode-class} +with value @code{special}, put on as follows: + +@cindex @code{mode-class} property +@cindex @code{special} +@example +(put 'funny-mode 'mode-class 'special) +@end example + +@noindent +This tells Emacs that new buffers created while the current buffer has +Funny mode should not inherit Funny mode. Modes such as Dired, Rmail, +and Buffer List use this feature. + +@item +If you want to make the new mode the default for files with certain +recognizable names, add an element to @code{auto-mode-alist} to select +the mode for those file names. If you define the mode command to +autoload, you should add this element in the same file that calls +@code{autoload}. Otherwise, it is sufficient to add the element in the +file that contains the mode definition. @xref{Auto Major Mode}. + +@item +@cindex @file{.emacs} customization +In the documentation, you should provide a sample @code{autoload} form +and an example of how to add to @code{auto-mode-alist}, that users can +include in their @file{.emacs} files. + +@item +@cindex mode loading +The top level forms in the file defining the mode should be written so +that they may be evaluated more than once without adverse consequences. +Even if you never load the file more than once, someone else will. +@end itemize + +@defvar change-major-mode-hook +This normal hook is run by @code{kill-all-local-variables} before it +does anything else. This gives major modes a way to arrange for +something special to be done if the user switches to a different major +mode. For best results, make this variable buffer-local, so that it +will disappear after doing its job and will not interfere with the +subsequent major mode. +@end defvar + +@node Example Major Modes +@subsection Major Mode Examples + + Text mode is perhaps the simplest mode besides Fundamental mode. +Here are excerpts from @file{text-mode.el} that illustrate many of +the conventions listed above: + +@smallexample +@group +;; @r{Create mode-specific tables.} +(defvar text-mode-syntax-table nil + "Syntax table used while in text mode.") +@end group + +@group +(if text-mode-syntax-table + () ; @r{Do not change the table if it is already set up.} + (setq text-mode-syntax-table (make-syntax-table)) + (modify-syntax-entry ?\" ". " text-mode-syntax-table) + (modify-syntax-entry ?\\ ". " text-mode-syntax-table) + (modify-syntax-entry ?' "w " text-mode-syntax-table)) +@end group + +@group +(defvar text-mode-abbrev-table nil + "Abbrev table used while in text mode.") +(define-abbrev-table 'text-mode-abbrev-table ()) +@end group + +@group +(defvar text-mode-map nil) ; @r{Create a mode-specific keymap.} + +(if text-mode-map + () ; @r{Do not change the keymap if it is already set up.} + (setq text-mode-map (make-sparse-keymap)) + (define-key text-mode-map "\t" 'tab-to-tab-stop) + (define-key text-mode-map "\es" 'center-line) + (define-key text-mode-map "\eS" 'center-paragraph)) +@end group +@end smallexample + + Here is the complete major mode function definition for Text mode: + +@smallexample +@group +(defun text-mode () + "Major mode for editing text intended for humans to read. + Special commands: \\@{text-mode-map@} +@end group +@group +Turning on text-mode runs the hook `text-mode-hook'." + (interactive) + (kill-all-local-variables) +@end group +@group + (use-local-map text-mode-map) ; @r{This provides the local keymap.} + (setq mode-name "Text") ; @r{This name goes into the mode line.} + (setq major-mode 'text-mode) ; @r{This is how @code{describe-mode}} + ; @r{finds the doc string to print.} + (setq local-abbrev-table text-mode-abbrev-table) + (set-syntax-table text-mode-syntax-table) + (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} + ; @r{customize the mode with a hook.} +@end group +@end smallexample + +@cindex @file{lisp-mode.el} + The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp +Interaction mode) have more features than Text mode and the code is +correspondingly more complicated. Here are excerpts from +@file{lisp-mode.el} that illustrate how these modes are written. + +@cindex syntax table example +@smallexample +@group +;; @r{Create mode-specific table variables.} +(defvar lisp-mode-syntax-table nil "") +(defvar emacs-lisp-mode-syntax-table nil "") +(defvar lisp-mode-abbrev-table nil "") +@end group + +@group +(if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table} + ; @r{if it is already set.} + (let ((i 0)) + (setq emacs-lisp-mode-syntax-table (make-syntax-table)) +@end group + +@group + ;; @r{Set syntax of chars up to 0 to class of chars that are} + ;; @r{part of symbol names but not words.} + ;; @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)} + (while (< i ?0) + (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table) + (setq i (1+ i))) + @dots{} +@end group +@group + ;; @r{Set the syntax for other characters.} + (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table) + (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table) + @dots{} +@end group +@group + (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table) + (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table) + @dots{})) +;; @r{Create an abbrev table for lisp-mode.} +(define-abbrev-table 'lisp-mode-abbrev-table ()) +@end group +@end smallexample + + Much code is shared among the three Lisp modes. The following +function sets various variables; it is called by each of the major Lisp +mode functions: + +@smallexample +@group +(defun lisp-mode-variables (lisp-syntax) + ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,} + ;; @r{and @code{t} in the other two Lisp modes.} + (cond (lisp-syntax + (if (not lisp-mode-syntax-table) + ;; @r{The Emacs Lisp mode syntax table always exists, but} + ;; @r{the Lisp Mode syntax table is created the first time a} + ;; @r{mode that needs it is called. This is to save space.} +@end group +@group + (progn (setq lisp-mode-syntax-table + (copy-syntax-table emacs-lisp-mode-syntax-table)) + ;; @r{Change some entries for Lisp mode.} + (modify-syntax-entry ?\| "\" " + lisp-mode-syntax-table) + (modify-syntax-entry ?\[ "_ " + lisp-mode-syntax-table) + (modify-syntax-entry ?\] "_ " + lisp-mode-syntax-table))) +@end group +@group + (set-syntax-table lisp-mode-syntax-table))) + (setq local-abbrev-table lisp-mode-abbrev-table) + @dots{}) +@end group +@end smallexample + + Functions such as @code{forward-paragraph} use the value of the +@code{paragraph-start} variable. Since Lisp code is different from +ordinary text, the @code{paragraph-start} variable needs to be set +specially to handle Lisp. Also, comments are indented in a special +fashion in Lisp and the Lisp modes need their own mode-specific +@code{comment-indent-function}. The code to set these variables is the +rest of @code{lisp-mode-variables}. + +@smallexample +@group + (make-local-variable 'paragraph-start) + (setq paragraph-start (concat "^$\\|" page-delimiter)) + @dots{} +@end group +@group + (make-local-variable 'comment-indent-function) + (setq comment-indent-function 'lisp-comment-indent)) +@end group +@end smallexample + + Each of the different Lisp modes has a slightly different keymap. For +example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other +Lisp modes do not. However, all Lisp modes have some commands in +common. The following function adds these common commands to a given +keymap. + +@smallexample +@group +(defun lisp-mode-commands (map) + (define-key map "\e\C-q" 'indent-sexp) + (define-key map "\177" 'backward-delete-char-untabify) + (define-key map "\t" 'lisp-indent-line)) +@end group +@end smallexample + + Here is an example of using @code{lisp-mode-commands} to initialize a +keymap, as part of the code for Emacs Lisp mode. First we declare a +variable with @code{defvar} to hold the mode-specific keymap. When this +@code{defvar} executes, it sets the variable to @code{nil} if it was +void. Then we set up the keymap if the variable is @code{nil}. + + This code avoids changing the keymap or the variable if it is already +set up. This lets the user customize the keymap if he or she so +wishes. + +@smallexample +@group +(defvar emacs-lisp-mode-map () "") +(if emacs-lisp-mode-map + () + (setq emacs-lisp-mode-map (make-sparse-keymap)) + (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun) + (lisp-mode-commands emacs-lisp-mode-map)) +@end group +@end smallexample + + Finally, here is the complete major mode function definition for +Emacs Lisp mode. + +@smallexample +@group +(defun emacs-lisp-mode () + "Major mode for editing Lisp code to run in Emacs. +Commands: +Delete converts tabs to spaces as it moves back. +Blank lines separate paragraphs. Semicolons start comments. +\\@{emacs-lisp-mode-map@} +@end group +@group +Entry to this mode runs the hook `emacs-lisp-mode-hook'." + (interactive) + (kill-all-local-variables) + (use-local-map emacs-lisp-mode-map) ; @r{This provides the local keymap.} + (set-syntax-table emacs-lisp-mode-syntax-table) +@end group +@group + (setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}} + ; @r{finds out what to describe.} + (setq mode-name "Emacs-Lisp") ; @r{This goes into the mode line.} + (lisp-mode-variables nil) ; @r{This define various variables.} + (run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a} + ; @r{hook to customize the mode.} +@end group +@end smallexample + +@node Auto Major Mode +@subsection How Emacs Chooses a Major Mode + + Based on information in the file name or in the file itself, Emacs +automatically selects a major mode for the new buffer when a file is +visited. + +@deffn Command fundamental-mode + Fundamental mode is a major mode that is not specialized for anything +in particular. Other major modes are defined in effect by comparison +with this one---their definitions say what to change, starting from +Fundamental mode. The @code{fundamental-mode} function does @emph{not} +run any hooks; you're not supposed to customize it. (If you want Emacs +to behave differently in Fundamental mode, change the @emph{global} +state of Emacs.) +@end deffn + +@deffn Command normal-mode &optional find-file + This function establishes the proper major mode and local variable +bindings for the current buffer. First it calls @code{set-auto-mode}, +then it runs @code{hack-local-variables} to parse, and bind or +evaluate as appropriate, any local variables. + + If the @var{find-file} argument to @code{normal-mode} is +non-@code{nil}, @code{normal-mode} assumes that the @code{find-file} +function is calling it. In this case, it may process a local variables +list at the end of the file. The variable @code{enable-local-variables} +controls whether to do so. + + If you run @code{normal-mode} interactively, the argument +@var{find-file} is normally @code{nil}. In this case, +@code{normal-mode} unconditionally processes any local variables list. +@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs +Manual}, for the syntax of the local variables section of a file. + +@cindex file mode specification error + @code{normal-mode} uses @code{condition-case} around the call to the +major mode function, so errors are caught and reported as a @samp{File +mode specification error}, followed by the original error message. +@end deffn + +@defopt enable-local-variables +This variable controls processing of local variables lists in files +being visited. A value of @code{t} means process the local variables +lists unconditionally; @code{nil} means ignore them; anything else means +ask the user what to do for each file. The default value is @code{t}. +@end defopt + +@defopt enable-local-eval +This variable controls processing of @samp{Eval:} in local variables +lists in files being visited. A value of @code{t} means process them +unconditionally; @code{nil} means ignore them; anything else means ask +the user what to do for each file. The default value is @code{maybe}. +@end defopt + +@defun set-auto-mode +@cindex visited file mode + This function selects the major mode that is appropriate for the +current buffer. It may base its decision on the value of the @w{@samp{-*-}} +line, on the visited file name (using @code{auto-mode-alist}), or on the +value of a local variable). However, this function does not look for +the @samp{mode:} local variable near the end of a file; the +@code{hack-local-variables} function does that. @xref{Choosing Modes, , +How Major Modes are Chosen, emacs, The GNU Emacs Manual}. +@end defun + +@defopt default-major-mode + This variable holds the default major mode for new buffers. The +standard value is @code{fundamental-mode}. + + If the value of @code{default-major-mode} is @code{nil}, Emacs uses +the (previously) current buffer's major mode for the major mode of a new +buffer. However, if the major mode symbol has a @code{mode-class} +property with value @code{special}, then it is not used for new buffers; +Fundamental mode is used instead. The modes that have this property are +those such as Dired and Rmail that are useful only with text that has +been specially prepared. +@end defopt + +@defvar initial-major-mode +@cindex @samp{*scratch*} +The value of this variable determines the major mode of the initial +@samp{*scratch*} buffer. The value should be a symbol that is a major +mode command name. The default value is @code{lisp-interaction-mode}. +@end defvar + +@defvar auto-mode-alist +This variable contains an association list of file name patterns +(regular expressions; @pxref{Regular Expressions}) and corresponding +major mode functions. Usually, the file name patterns test for +suffixes, such as @samp{.el} and @samp{.c}, but this need not be the +case. An ordinary element of the alist looks like @code{(@var{regexp} . +@var{mode-function})}. + +For example, + +@smallexample +@group +(("^/tmp/fol/" . text-mode) + ("\\.texinfo$" . texinfo-mode) + ("\\.texi$" . texinfo-mode) +@end group +@group + ("\\.el$" . emacs-lisp-mode) + ("\\.c$" . c-mode) + ("\\.h$" . c-mode) + @dots{}) +@end group +@end smallexample + +When you visit a file whose expanded file name (@pxref{File Name +Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the +corresponding @var{mode-function}. This feature enables Emacs to select +the proper major mode for most files. + +If an element of @code{auto-mode-alist} has the form @code{(@var{regexp} +@var{function} t)}, then after calling @var{function}, Emacs searches +@code{auto-mode-alist} again for a match against the portion of the file +name that did not match before. + +This match-again feature is useful for uncompression packages: an entry +of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file +and then put the uncompressed file in the proper mode according to the +name sans @samp{.gz}. + +Here is an example of how to prepend several pattern pairs to +@code{auto-mode-alist}. (You might use this sort of expression in your +@file{.emacs} file.) + +@smallexample +@group +(setq auto-mode-alist + (append + ;; @r{Filename starts with a dot.} + '(("/\\.[^/]*$" . fundamental-mode) + ;; @r{Filename has no dot.} + ("[^\\./]*$" . fundamental-mode) + ("\\.C$" . c++-mode)) + auto-mode-alist)) +@end group +@end smallexample +@end defvar + +@defvar interpreter-mode-alist +This variable specifes major modes to use for scripts that specify a +command interpreter in an @samp{!#} line. Its value is a list of +elements of the form @code{(@var{interpreter} . @var{mode})}; for +example, @code{("perl" . perl-mode)} is one element present by default. +The element says to use mode @var{mode} if the file specifies +@var{interpreter}. + +This variable is applicable only when the file name doesn't indicate +which major mode to use. +@end defvar + +@defun hack-local-variables &optional force + This function parses, and binds or evaluates as appropriate, any local +variables for the current buffer. + + The handling of @code{enable-local-variables} documented for +@code{normal-mode} actually takes place here. The argument @var{force} +reflects the argument @var{find-file} given to @code{normal-mode}. +@end defun + +@node Mode Help +@subsection Getting Help about a Major Mode +@cindex mode help +@cindex help for major mode +@cindex documentation for major mode + + The @code{describe-mode} function is used to provide information +about major modes. It is normally called with @kbd{C-h m}. The +@code{describe-mode} function uses the value of @code{major-mode}, +which is why every major mode function needs to set the +@code{major-mode} variable. + +@deffn Command describe-mode +This function displays the documentation of the current major mode. + +The @code{describe-mode} function calls the @code{documentation} +function using the value of @code{major-mode} as an argument. Thus, it +displays the documentation string of the major mode function. +(@xref{Accessing Documentation}.) +@end deffn + +@defvar major-mode +This variable holds the symbol for the current buffer's major mode. +This symbol should have a function definition which is the command to +switch to that major mode. The @code{describe-mode} function uses the +documentation string of this symbol as the documentation of the major +mode. +@end defvar + +@node Derived Modes +@subsection Defining Derived Modes + + It's often useful to define a new major mode in terms of an existing +one. An easy way to do this is to use @code{define-derived-mode}. + +@defmac define-derived-mode variant parent name doc body@dots{} +This construct defines @var{variant} as a major mode command, using +@var{name} as the string form of the mode which. + +The definition of the command is to call the function @var{parent}, then +override certain aspects of that parent mode: + +@itemize @bullet +@item +The new mode has its own keymap, named @code{@var{variant}-map}. +@code{define-derived-mode} initializes this map to inherit from +@code{@var{parent}-map}, if it is not already set. + +@item +The new mode has its own syntax table, taken from the variable +@code{@var{variant}-syntax-table}. +@code{define-derived-mode} initializes this variable by copying +@code{@var{parent}-syntax-table}, if it is not already set. + +@item +The new mode has its own abbrev table, taken from the variable +@code{@var{variant}-abbrev-table}. +@code{define-derived-mode} initializes this variable by copying +@code{@var{parent}-abbrev-table}, if it is not already set. + +@item +The new mode has its own mode hook, @code{@var{variant}-hook}, +which it runs in standard fashion as the very last thing that it does. +(The new mode also runs the mode hook of @var{parent} as part +of calling @var{parent}.) +@end itemize + +In addition, you can specify how to override other aspects of +@var{parent-mode} with @var{body}. The command @var{variant} +evaluates the forms in @var{body} after setting up all its usual +overrides, just before running @code{@var{variant}-hook}. + +The argument @var{docstring} specifies the documentation string for the +new mode. If you omit @var{docstring}, @code{define-derived-mode} +generates a documentation string. + +Here is a hypothetical example: + +@example +(define-derived-mode hypertext-mode + text-mode "Hypertext" + "Major mode for hypertext. +\\@{hypertext-mode-map@}" + (setq case-fold-search nil)) + +(define-key hypertext-mode-map + [down-mouse-3] 'do-hyper-link) +@end example +@end defmac + +@node Minor Modes +@section Minor Modes +@cindex minor mode + + A @dfn{minor mode} provides features that users may enable or disable +independently of the choice of major mode. Minor modes can be enabled +individually or in combination. Minor modes would be better named +``Generally available, optional feature modes'' except that such a name is +unwieldy. + + A minor mode is not usually a modification of single major mode. For +example, Auto Fill mode may be used in any major mode that permits text +insertion. To be general, a minor mode must be effectively independent +of the things major modes do. + + A minor mode is often much more difficult to implement than a major +mode. One reason is that you should be able to activate and deactivate +minor modes in any order. + +and restore the environment of the major mode to the state it was in +before the minor mode was activated. + + Often the biggest problem in implementing a minor mode is finding a +way to insert the necessary hook into the rest of Emacs. Minor mode +keymaps make this easier in Emacs 19 than it used to be. + +@menu +* Minor Mode Conventions:: Tips for writing a minor mode. +* Keymaps and Minor Modes:: How a minor mode can have its own keymap. +@end menu + +@node Minor Mode Conventions +@subsection Conventions for Writing Minor Modes +@cindex minor mode conventions +@cindex conventions for writing minor modes + + There are conventions for writing minor modes just as there are for +major modes. Several of the major mode conventions apply to minor +modes as well: those regarding the name of the mode initialization +function, the names of global symbols, and the use of keymaps and +other tables. + + In addition, there are several conventions that are specific to +minor modes. + +@itemize @bullet +@item +@cindex mode variable +Make a variable whose name ends in @samp{-mode} to represent the minor +mode. Its value should enable or disable the mode (@code{nil} to +disable; anything else to enable.) We call this the @dfn{mode +variable}. + +This variable is used in conjunction with the @code{minor-mode-alist} to +display the minor mode name in the mode line. It can also enable +or disable a minor mode keymap. Individual commands or hooks can also +check the variable's value. + +If you want the minor mode to be enabled separately in each buffer, +make the variable buffer-local. + +@item +Define a command whose name is the same as the mode variable. +Its job is to enable and disable the mode by setting the variable. + +The command should accept one optional argument. If the argument is +@code{nil}, it should toggle the mode (turn it on if it is off, and off +if it is on). Otherwise, it should turn the mode on if the argument is +a positive integer, a symbol other than @code{nil} or @code{-}, or a +list whose @sc{car} is such an integer or symbol; it should turn the +mode off otherwise. + +Here is an example taken from the definition of @code{overwrite-mode}. +It shows the use of @code{overwrite-mode} as a variable which enables or +disables the mode's behavior. + +@smallexample +@group +(setq overwrite-mode + (if (null arg) (not overwrite-mode) + (> (prefix-numeric-value arg) 0))) +@end group +@end smallexample + +@item +Add an element to @code{minor-mode-alist} for each minor mode +(@pxref{Mode Line Variables}). This element should be a list of the +following form: + +@smallexample +(@var{mode-variable} @var{string}) +@end smallexample + +Here @var{mode-variable} is the variable that controls enablement of the +minor mode, and @var{string} is a short string, starting with a space, +to represent the mode in the mode line. These strings must be short so +that there is room for several of them at once. + +When you add an element to @code{minor-mode-alist}, use @code{assq} to +check for an existing element, to avoid duplication. For example: + +@smallexample +@group +(or (assq 'leif-mode minor-mode-alist) + (setq minor-mode-alist + (cons '(leif-mode " Leif") minor-mode-alist))) +@end group +@end smallexample +@end itemize + +@node Keymaps and Minor Modes +@subsection Keymaps and Minor Modes + +As of Emacs version 19, each minor mode can have its own keymap which is +active when the mode is enabled. @xref{Active Keymaps}. To set up a +keymap for a minor mode, add an element to the alist +@code{minor-mode-map-alist}. + +@cindex @code{self-insert-command}, minor modes +One use of minor mode keymaps is to modify the behavior of certain +self-inserting characters so that they do something else as well as +self-insert. In general, this is the only way to do that, since the +facilities for customizing @code{self-insert-command} are limited to +special cases (designed for abbrevs and Auto Fill mode). (Do not try +substituting your own definition of @code{self-insert-command} for the +standard one. The editor command loop handles this function specially.) + +@defvar minor-mode-map-alist +This variable is an alist of elements that look like this: + +@example +(@var{variable} . @var{keymap}) +@end example + +@noindent +where @var{variable} is the variable which indicates whether the minor +mode is enabled, and @var{keymap} is the keymap. The keymap +@var{keymap} is active whenever @var{variable} has a non-@code{nil} +value. + +Note that elements of @code{minor-mode-map-alist} do not have the same +structure as elements of @code{minor-mode-alist}. The map must be the +@sc{cdr} of the element; a list with the map as the second element will +not do. + +What's more, the keymap itself must appear in the @sc{cdr}. It does not +work to store a variable in the @sc{cdr} and make the map the value of +that variable. + +When more than one minor mode keymap is active, their order of priority +is the order of @code{minor-mode-map-alist}. But you should design +minor modes so that they don't interfere with each other. If you do +this properly, the order will not matter. +@end defvar + +@node Mode Line Format +@section Mode Line Format +@cindex mode line + + Each Emacs window (aside from minibuffer windows) includes a mode line +which displays status information about the buffer displayed in the +window. The mode line contains information about the buffer such as its +name, associated file, depth of recursive editing, and the major and +minor modes of the buffer. + + This section describes how the contents of the mode line are +controlled. It is in the chapter on modes because much of the +information displayed in the mode line relates to the enabled major and +minor modes. + + @code{mode-line-format} is a buffer-local variable that holds a +template used to display the mode line of the current buffer. All +windows for the same buffer use the same @code{mode-line-format} and the +mode lines will appear the same (except for scrolling percentages and +line numbers). + + The mode line of a window is normally updated whenever a different +buffer is shown in the window, or when the buffer's modified-status +changes from @code{nil} to @code{t} or vice-versa. If you modify any of +the variables referenced by @code{mode-line-format}, you may want to +force an update of the mode line so as to display the new information. + +@c Emacs 19 feature +@defun force-mode-line-update +Force redisplay of the current buffer's mode line. +@end defun + + The mode line is usually displayed in inverse video; see +@code{mode-line-inverse-video} in @ref{Inverse Video}. + +@menu +* Mode Line Data:: The data structure that controls the mode line. +* Mode Line Variables:: Variables used in that data structure. +* %-Constructs:: Putting information into a mode line. +@end menu + +@node Mode Line Data +@subsection The Data Structure of the Mode Line +@cindex mode line construct + + The mode line contents are controlled by a data structure of lists, +strings, symbols and numbers kept in the buffer-local variable +@code{mode-line-format}. The data structure is called a @dfn{mode line +construct}, and it is built in recursive fashion out of simpler mode line +constructs. + +@defvar mode-line-format +The value of this variable is a mode line construct with overall +responsibility for the mode line format. The value of this variable +controls which other variables are used to form the mode line text, and +where they appear. +@end defvar + + A mode line construct may be as simple as a fixed string of text, but +it usually specifies how to use other variables to construct the text. +Many of these variables are themselves defined to have mode line +constructs as their values. + + The default value of @code{mode-line-format} incorporates the values +of variables such as @code{mode-name} and @code{minor-mode-alist}. +Because of this, very few modes need to alter @code{mode-line-format}. +For most purposes, it is sufficient to alter the variables referenced by +@code{mode-line-format}. + + A mode line construct may be a list, cons cell, symbol, or string. If +the value is a list, each element may be a list, a cons cell, a symbol, +or a string. + +@table @code +@cindex percent symbol in mode line +@item @var{string} +A string as a mode line construct is displayed verbatim in the mode line +except for @dfn{@code{%}-constructs}. Decimal digits after the @code{%} +specify the field width for space filling on the right (i.e., the data +is left justified). @xref{%-Constructs}. + +@item @var{symbol} +A symbol as a mode line construct stands for its value. The value of +@var{symbol} is used in place of @var{symbol} unless @var{symbol} is +@code{t} or @code{nil}, or is void, in which case @var{symbol} is +ignored. + +There is one exception: if the value of @var{symbol} is a string, it is +processed verbatim in that the @code{%}-constructs are not recognized. + +@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{}) +A list whose first element is a string or list, means to concatenate all +the elements. This is the most common form of mode line construct. + +@item (@var{symbol} @var{then} @var{else}) +A list whose first element is a symbol is a conditional. Its meaning +depends on the value of @var{symbol}. If the value is non-@code{nil}, +the second element of the list (@var{then}) is processed recursively as +a mode line element. But if the value of @var{symbol} is @code{nil}, +the third element of the list (if there is one) is processed +recursively. + +@item (@var{width} @var{rest}@dots{}) +A list whose first element is an integer specifies truncation or +padding of the results of @var{rest}. The remaining elements +@var{rest} are processed recursively as mode line constructs and +concatenated together. Then the result is space filled (if +@var{width} is positive) or truncated (to @minus{}@var{width} columns, +if @var{width} is negative) on the right. + +For example, the usual way to show what percentage of a buffer is above +the top of the window is to use a list like this: @code{(-3 . "%p")}. +@end table + + If you do alter @code{mode-line-format} itself, the new value should +use all the same variables that are used by the default value, rather +than duplicating their contents or displaying the information in another +fashion. This way, customizations made by the user, by libraries (such +as @code{display-time}) and by major modes via changes to those +variables remain effective. + +@cindex Shell mode @code{mode-line-format} + Here is an example of a @code{mode-line-format} that might be +useful for @code{shell-mode} since it contains the hostname and default +directory. + +@example +@group +(setq mode-line-format + (list "" + 'mode-line-modified + "%b--" +@end group + (getenv "HOST") ; @r{One element is not constant.} + ":" + 'default-directory + " " + 'global-mode-string + " %[(" 'mode-name + 'minor-mode-alist + "%n" + 'mode-line-process + ")%]----" +@group + (line-number-mode "L%l--") + '(-3 . "%p") + "-%-")) +@end group +@end example + +@node Mode Line Variables +@subsection Variables Used in the Mode Line + + This section describes variables incorporated by the +standard value of @code{mode-line-format} into the text of the mode +line. There is nothing inherently special about these variables; any +other variables could have the same effects on the mode line if +@code{mode-line-format} were changed to use them. + +@defvar mode-line-modified + This variable holds the value of the mode-line construct that displays +whether the current buffer is modified. + + The default value of @code{mode-line-modified} is +@code{("--%1*%1*-")}. This means that the mode line displays +@samp{--**-} if the buffer is modified, @samp{-----} if the buffer is +not modified, and @samp{--%%-} if the buffer is read only. + +Changing this variable does not force an update of the mode line. +@end defvar + +@defvar mode-line-buffer-identification + This variable identifies the buffer being displayed in the window. +Its default value is @samp{Emacs: %17b}, which means that it displays +@samp{Emacs:} followed by the buffer name. You may want to change this +in modes such as Rmail that do not behave like a ``normal'' Emacs. +@end defvar + +@defvar global-mode-string +This variable holds a mode line spec that appears in the mode line by +default, just after the buffer name. The command @code{display-time} +sets @code{global-mode-string} to refer to the variable +@code{display-time-string}, which holds a string containing the time and +load information. + +The @samp{%M} construct substitutes the value of +@code{global-mode-string}, but this is obsolete, since the variable is +included directly in the mode line. +@end defvar + +@defvar mode-name + This buffer-local variable holds the ``pretty'' name of the current +buffer's major mode. Each major mode should set this variable so that the +mode name will appear in the mode line. +@end defvar + +@defvar minor-mode-alist + This variable holds an association list whose elements specify how the +mode line should indicate that a minor mode is active. Each element of +the @code{minor-mode-alist} should be a two-element list: + +@example +(@var{minor-mode-variable} @var{mode-line-string}) +@end example + +More generally, @var{mode-line-string} can be any mode line spec. It +appears in the mode line when the value of @var{minor-mode-variable} is +non-@code{nil}, and not otherwise. These strings should begin with +spaces so that they don't run together. Conventionally, the +@var{minor-mode-variable} for a specific mode is set to a non-@code{nil} +value when that minor mode is activated. + +The default value of @code{minor-mode-alist} is: + +@example +@group +minor-mode-alist +@result{} ((abbrev-mode " Abbrev") + (overwrite-mode " Ovwrt") + (auto-fill-function " Fill") + (defining-kbd-macro " Def")) +@end group +@end example + +@noindent +(In earlier Emacs versions, @code{auto-fill-function} was called +@code{auto-fill-hook}.) + + @code{minor-mode-alist} is not buffer-local. The variables mentioned +in the alist should be buffer-local if the minor mode can be enabled +separately in each buffer. +@end defvar + +@defvar mode-line-process +This buffer-local variable contains the mode line information on process +status in modes used for communicating with subprocesses. It is +displayed immediately following the major mode name, with no intervening +space. For example, its value in the @samp{*shell*} buffer is +@code{(":@: %s")}, which allows the shell to display its status along +with the major mode as: @samp{(Shell:@: run)}. Normally this variable +is @code{nil}. +@end defvar + +@defvar default-mode-line-format + This variable holds the default @code{mode-line-format} for buffers +that do not override it. This is the same as @code{(default-value +'mode-line-format)}. + + The default value of @code{default-mode-line-format} is: + +@example +@group +("" + mode-line-modified + mode-line-buffer-identification + " " + global-mode-string + " %[(" + mode-name +@end group +@group + minor-mode-alist + "%n" + mode-line-process + ")%]----" + (-3 . "%p") + "-%-") +@end group +@end example +@end defvar + +@node %-Constructs +@subsection @code{%}-Constructs in the Mode Line + + The following table lists the recognized @code{%}-constructs and what +they mean. + +@table @code +@item %b +The current buffer name, obtained with the @code{buffer-name} function. +@xref{Buffer Names}. + +@item %f +The visited file name, obtained with the @code{buffer-file-name} +function. @xref{Buffer File Name}. + +@item %* +@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* +@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* +@samp{-} otherwise. @xref{Buffer Modification}. + +@item %+ +@samp{*} if the buffer is modified, and otherwise @samp{-}. + +@item %s +The status of the subprocess belonging to the current buffer, obtained with +@code{process-status}. @xref{Process Information}. + +@item %p +The percent of the buffer above the @strong{top} of window, or +@samp{Top}, @samp{Bottom} or @samp{All}. + +@item %P +The percentage of the buffer text that is above the @strong{bottom} of +the window (which includes the text visible in the window, as well as +the text above the top), plus @samp{Top} if the top of the buffer is +visible on screen; or @samp{Bottom} or @samp{All}. + +@item %n +@samp{Narrow} when narrowing is in effect; nothing otherwise (see +@code{narrow-to-region} in @ref{Narrowing}). + +@item %[ +An indication of the depth of recursive editing levels (not counting +minibuffer levels): one @samp{[} for each editing level. +@xref{Recursive Editing}. + +@item %] +One @samp{]} for each recursive editing level (not counting minibuffer +levels). + +@item %% +The character @samp{%}---this is how to include a literal @samp{%} in a +string in which @code{%}-constructs are allowed. + +@item %- +Dashes sufficient to fill the remainder of the mode line. +@end table + +The following two @code{%}-constructs are still supported, but they are +obsolete, since you can get the same results with the variables +@code{mode-name} and @code{global-mode-string}. + +@table @code +@item %m +The value of @code{mode-name}. + +@item %M +The value of @code{global-mode-string}. Currently, only +@code{display-time} modifies the value of @code{global-mode-string}. +@end table + +@node Hooks +@section Hooks +@cindex hooks + + A @dfn{hook} is a variable where you can store a function or functions +to be called on a particular occasion by an existing program. Emacs +provides hooks for the sake of customization. Most often, hooks are set +up in the @file{.emacs} file, but Lisp programs can set them also. +@xref{Standard Hooks}, for a list of standard hook variables. + + Most of the hooks in Emacs are @dfn{normal hooks}. These variables +contain lists of functions to be called with no arguments. The reason +most hooks are normal hooks is so that you can use them in a uniform +way. You can always tell when a hook is a normal hook, because its +name ends in @samp{-hook}. + + The recommended way to add a hook function to a normal hook is by +calling @code{add-hook} (see below). The hook functions may be any of +the valid kinds of functions that @code{funcall} accepts (@pxref{What Is +a Function}). Most normal hook variables are initially void; +@code{add-hook} knows how to deal with this. + + As for abnormal hooks, those whose names end in @samp{-function} have +a value which is a single function. Those whose names end in +@samp{-hooks} have a value which is a list of functions. Any hook which +is abnormal is abnormal because a normal hook won't do the job; either +the functions are called with arguments, or their values are meaningful. +The name shows you that the hook is abnormal and that you should look at +its documentation string to see how to use it properly. + + Most major modes run hooks as the last step of initialization. This +makes it easy for a user to customize the behavior of the mode, by +overriding the local variable assignments already made by the mode. But +hooks are used in other contexts too. For example, the hook +@code{suspend-hook} runs just before Emacs suspends itself +(@pxref{Suspending Emacs}). + + Here's an expression you can put in your @file{.emacs} file to turn on +Auto Fill mode when in Lisp Interaction mode: + +@example +(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) +@end example + + The next example shows how to use a hook to customize the way Emacs +formats C code. (People often have strong personal preferences for one +format or another.) Here the hook function is an anonymous lambda +expression. + +@cindex lambda expression in hook +@example +@group +(add-hook 'c-mode-hook + (function (lambda () + (setq c-indent-level 4 + c-argdecl-indent 0 + c-label-offset -4 +@end group +@group + c-continued-statement-indent 0 + c-brace-offset 0 + comment-column 40)))) + +(setq c++-mode-hook c-mode-hook) +@end group +@end example + + Finally, here is an example of how to use the Text mode hook to +provide a customized mode line for buffers in Text mode, displaying the +default directory in addition to the standard components of the +mode line. (This may cause the mode line to run out of space if you +have very long file names or display the time and load.) + +@example +@group +(add-hook 'text-mode-hook + (function (lambda () + (setq mode-line-format + '(mode-line-modified + "Emacs: %14b" + " " +@end group + default-directory + " " + global-mode-string + "%[(" + mode-name + minor-mode-alist +@group + "%n" + mode-line-process + ") %]---" + (-3 . "%p") + "-%-"))))) +@end group +@end example + + At the appropriate time, Emacs uses the @code{run-hooks} function to +run particular hooks. This function calls the hook functions you have +added with @code{add-hooks}. + +@defun run-hooks &rest hookvar +This function takes one or more hook variable names as arguments, and +runs each hook in turn. Each @var{hookvar} argument should be a symbol +that is a hook variable. These arguments are processed in the order +specified. + +If a hook variable has a non-@code{nil} value, that value may be a +function or a list of functions. If the value is a function (either a +lambda expression or a symbol with a function definition), it is +called. If it is a list, the elements are called, in order. +The hook functions are called with no arguments. + +For example, here's how @code{emacs-lisp-hooks} runs its mode hook: + +@example +(run-hooks 'emacs-lisp-mode-hook) +@end example +@end defun + +@defun add-hook hook function &optional append +This function is the handy way to add function @var{function} to hook +variable @var{hook}. For example, + +@example +(add-hook 'text-mode-hook 'my-text-hook-function) +@end example + +@noindent +adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. + +It is best to design your hook functions so that the order in which they +are executed does not matter. Any dependence on the order is ``asking +for trouble.'' However, the order is predictable: normally, +@var{function} goes at the front of the hook list, so it will be +executed first (barring another @code{add-hook} call). + +If the optional argument @var{append} is non-@code{nil}, the new hook +function goes at the end of the hook list and will be executed last. +@end defun + +@defun remove-hook hook function +This function removes @var{function} from the hook variable @var{hook}. +@end defun