Mercurial > emacs
view lispref/elisp.texi @ 72440:a978bbf5830a
*** empty log message ***
| author | Eli Zaretskii <eliz@gnu.org> |
|---|---|
| date | Fri, 18 Aug 2006 12:07:38 +0000 |
| parents | db3e2c7ec185 |
| children | e01c5850129b 858cb33ae39d |
line wrap: on
line source
\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename elisp @settitle GNU Emacs Lisp Reference Manual @c %**end of header @c Version of the manual and of Emacs. @c Please remember to update the edition number in README as well. @set VERSION 2.9 @set EMACSVER 22.0.50 @dircategory Emacs @direntry * Elisp: (elisp). The Emacs Lisp Reference Manual. @end direntry @c So that anyone making the printed manual gets the version we have @c tuned to avoid bad line breaks, etc. @smallbook @c per rms and peterb, use 10pt fonts for the main text, mostly to @c save on paper cost. Also, do not declare @setchapternewpage odd, @c for the same reason. Do this inside @tex for now, so the @c last-released makeinfo does not complain. @tex @fonttextsize 10 \global\hbadness=6000 % don't worry about not-too-underfull boxes @end tex @c Combine indices. @synindex cp fn @syncodeindex vr fn @syncodeindex ky fn @syncodeindex pg fn @c We use the "type index" to index new functions and variables. @c @syncodeindex tp fn @copying This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version @value{EMACSVER}. Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License,'' with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License.'' (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.'' @end quotation @end copying @titlepage @title GNU Emacs Lisp Reference Manual @subtitle For Emacs Version @value{EMACSVER} @subtitle Revision @value{VERSION}, January 2002 @author by Bil Lewis, Dan LaLiberte, Richard Stallman @author and the GNU Manual Group @page @vskip 0pt plus 1filll @insertcopying @sp 1 Published by the Free Software Foundation @* 51 Franklin St, Fifth Floor @* Boston, MA 02110-1301 @* USA @* ISBN 1-882114-73-6 @sp 1 Cover art by Etienne Suvasa. @end titlepage @c Print the tables of contents @summarycontents @contents @ifnottex @node Top, Introduction, (dir), (dir) @top Emacs Lisp This Info file contains edition @value{VERSION} of the GNU Emacs Lisp Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. @end ifnottex @menu * Introduction:: Introduction and conventions used. * Lisp Data Types:: Data types of objects 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. * Hash Tables:: Very fast lookup-tables. * 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. * Customization:: Writing customization declarations. * Loading:: Reading files of Lisp code into Lisp. * Byte Compilation:: Compilation makes programs run faster. * Advising Functions:: Adding to the definition of a function. * Debugging:: Tools and tips for debugging Lisp programs. * Read and Print:: 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 system-level 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. * Non-ASCII Characters:: Non-ASCII text in buffers and strings. * 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. * Display:: Features for controlling the screen display. * System Interface:: Getting the user id, system type, environment variables, and other such things. Appendices * Antinews:: Info for users downgrading to Emacs 21. * GNU Free Documentation License:: The license for this documentation * GPL:: Conditions for copying and changing GNU Emacs. * Tips:: Advice and coding conventions for Emacs Lisp. * GNU Emacs Internals:: Building and dumping Emacs; internal data structures. * Standard Errors:: List of all error symbols. * Standard Buffer-Local Variables:: List of variables buffer-local in all buffers. * Standard Keymaps:: List of standard keymaps. * Standard Hooks:: List of standard hook variables. * Index:: Index including concepts, functions, variables, and other terms. @ignore * New Symbols:: New functions and variables in Emacs @value{EMACSVER}. @end ignore 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. * Version Info:: Which Emacs version is running? * 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. * Circular Objects:: Read syntax for circular structure. * 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. * Symbol Type:: A multi-use object that refers to a function, variable, property list, or itself. * Sequence Type:: Both lists and arrays are classified as sequences. * Cons Cell Type:: Cons cells, and lists (which are made from cons cells). * Array Type:: Arrays include strings and vectors. * String Type:: An (efficient) array of characters. * Vector Type:: One-dimensional arrays. * Char-Table Type:: One-dimensional sparse arrays indexed by characters. * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. * Hash Table Type:: Super-fast lookup tables. * Function Type:: A piece of executable code you can call from elsewhere. * 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. Cons Cell and List Types * Box Diagrams:: Drawing pictures of lists. * Dotted Pair Notation:: An alternative syntax for lists. * Association List Type:: A specially constructed list. Editing Types * Buffer Type:: The basic object of editing. * Marker Type:: A position in a buffer. * Window Type:: What makes buffers visible. * Frame Type:: Windows subdivide frames. * Window Configuration Type::Save what the screen looks like. * Frame Configuration Type::Recording the status of all frames. * Process Type:: A process running on the underlying OS. * Stream Type:: Receive or send characters. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. 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. * Numeric Conversions:: Converting float to integer and vice versa. * Arithmetic Operations:: How to add, subtract, multiply and divide. * Rounding Operations:: Explicitly rounding floating point numbers. * Bitwise Operations:: Logical and, or, not, shifting. * Math 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. * Modifying Strings:: Altering the contents of an existing string. * Text Comparison:: Comparing characters or strings. * String Conversion:: Converting characters or strings and vice versa. * Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. * Case Conversion:: Case conversion functions. * Case Tables:: Customizing case conversion. Lists * Cons Cells:: How lists are made out of cons cells. * 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. * Rings:: Managing a fixed-size ring of objects. 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. * Vector Functions:: Functions specifically for vectors. * Char-Tables:: How to work with char-tables. * Bool-Vectors:: How to work with bool-vectors. Hash Tables * Creating Hash:: Functions to create hash tables. * Hash Access:: Reading and writing the hash table contents. * Defining Hash:: Defining new comparison methods * Other Hash:: Miscellaneous. 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. * Forms:: How various sorts of objects are evaluated. * Quoting:: Avoiding evaluation (to put constants in the program). * Eval:: How to invoke the Lisp interpreter explicitly. 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 Indirection:: When a symbol appears as the car of a list, we find the real function via the symbol. * 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}, @code{when}, @code{unless}. * 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 Symbols:: 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. * Tips for Defining:: Things you should think about when you define 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. * Frame-Local Variables:: Variable values in effect only in one frame. * Future Local Variables:: New kinds of local values we might add some day. * File Local Variables:: Handling local variable lists in files. * Variable Aliases:: Variables that are aliases for other variables. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. 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 buffer-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. * Obsolete Functions:: Declaring functions obsolete. * Inline Functions:: Defining functions that the compiler will open code. * Function Safety:: Determining whether a function is safe to call. * 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. * Indenting Macros:: Specifying how to indent macro calls. Writing Customization Definitions * Common Keywords:: Common keyword arguments for all kinds of customization declarations. * Group Definitions:: Writing customization group definitions. * Variable Definitions:: Declaring user options. * Customization Types:: Specifying the type of a user option. Loading * How Programs Do Loading:: The @code{load} function and others. * Load Suffixes:: Details about the suffixes that @code{load} tries. * Library Search:: Finding a library to load. * Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. * Autoload:: Setting up a function to autoload. * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. * Where Defined:: Finding which file defined a certain symbol. * Unloading:: How to "unload" a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. Byte Compilation * Speed of Byte-Code:: An example of speedup from byte compilation. * Compilation Functions:: Byte compilation functions. * Docs and Compilation:: Dynamic loading of documentation strings. * Dynamic Loading:: Dynamic loading of individual functions. * Eval During Compile:: Code to be evaluated when you compile. * Compiler Errors:: Handling compiler error messages. * Byte-Code Objects:: The data type used for byte-compiled functions. * Disassembly:: Disassembling byte-code; how to read byte-code. Advising Emacs Lisp Functions * Simple Advice:: A simple example to explain the basics of advice. * Defining Advice:: Detailed description of @code{defadvice}. * Around-Advice:: Wrapping advice around a function's definition. * Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. * Activation of Advice:: Advice doesn't do anything until you activate it. * Enabling Advice:: You can enable or disable each piece of advice. * Preactivation:: Preactivation is a way of speeding up the loading of compiled advice. * Argument Access in Advice:: How advice can access the function's arguments. * Advising Primitives:: Accessing arguments when advising a primitive. * Combined Definition:: How advice is implemented. Debugging Lisp Programs * Debugger:: How the Emacs Lisp debugger is implemented. * Edebug:: A source-level Emacs Lisp debugger. * Syntax Errors:: How to find syntax errors. * Test Coverage:: Ensuring you have tested all branches in your code. * Compilation Errors:: How to find errors that show up in byte compilation. The Lisp Debugger * Error Debugging:: Entering the debugger when an error happens. * Infinite Loops:: Stopping and debugging a program that doesn't exit. * 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. Edebug * Using Edebug:: Introduction to use of Edebug. * Instrumenting:: You must instrument your code in order to debug it with Edebug. * Edebug Execution Modes:: Execution modes, stopping more or less often. * Jumping:: Commands to jump to a specified place. * Edebug Misc:: Miscellaneous commands. * Breaks:: Setting breakpoints to make the program stop. * Trapping Errors:: Trapping errors with Edebug. * Edebug Views:: Views inside and outside of Edebug. * Edebug Eval:: Evaluating expressions within Edebug. * Eval List:: Expressions whose values are displayed each time you enter Edebug. * Printing in Edebug:: Customization of printing. * Trace Buffer:: How to produce trace output in a buffer. * Coverage Testing:: How to test evaluation coverage. * The Outside Context:: Data that Edebug saves and restores. * Edebug and Macros:: Specifying how to handle macro calls. * Edebug Options:: Option variables for customizing Edebug. 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. * Output Variables:: Variables that control what the printing functions do. 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. * Minibuffer History:: Recording previous minibuffer inputs so the user can reuse them. * Initial Input:: Specifying initial contents for the minibuffer. * Completion:: How to invoke and customize completion. * Yes-or-No Queries:: Asking a question with a simple answer. * Multiple Queries:: Asking a series of similar questions. * Reading a Password:: Reading a password from the terminal. * Minibuffer Commands:: Commands used as key bindings in minibuffers. * Minibuffer Contents:: How such commands access the minibuffer text. * Minibuffer Windows:: Operating on the special minibuffer windows. * Recursive Mini:: Whether recursive entry to minibuffer is allowed. * 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. * Adjusting Point:: Adjustment of point after a command. * Input Events:: What input looks like when you read it. * Reading Input:: How to read input events from the keyboard or mouse. * Special Events:: Events processed immediately and individually. * 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 * Key Sequences:: Key sequences as Lisp objects. * Keymap Basics:: Basic concepts of 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. * 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. * Remapping Commands:: Bindings that translate one command to another. * Key Binding Commands:: Interactive interfaces for redefining keys. * Scanning Keymaps:: Looking through all keymaps, for printing help. * Menu Keymaps:: A keymap can define a menu for X or for use from the terminal. Major and Minor Modes * Hooks:: How to use hooks; how to write code that provides hooks. * Major Modes:: Defining major modes. * Minor Modes:: Defining minor modes. * Mode Line Format:: Customizing the text that appears in the mode line. * Imenu:: How a mode can provide a menu of definitions in the buffer. * Font Lock Mode:: How modes can highlight text according to syntax. * Desktop Save Mode:: How modes can have buffer state saved between Emacs sessions. Major Modes * Major Mode Basics:: * 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. * Generic Modes:: Defining a simple major mode that supports comment syntax and Font Lock mode. * Mode Hooks:: Hooks run at the end of major mode functions. Minor Modes * Minor Mode Conventions:: Tips for writing a minor mode. * Keymaps and Minor Modes:: How a minor mode can have its own keymap. * Defining Minor Modes:: A convenient facility for defining minor modes. Mode Line Format * Mode Line Basics:: * 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. * Properties in Mode:: Using text properties in the mode line. * Header Lines:: Like a mode line, but at the top. * Emulating Mode Line:: Formatting text as the mode line would. 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. * Changing Files:: Renaming files, changing protection, etc. * File Names:: Decomposing and expanding file names. * Contents of Directories:: Getting a list of the files in a directory. * Create/Delete Dirs:: Creating and Deleting Directories. * Magic File Names:: Defining "magic" special handling for certain file names. * Format Conversion:: Conversion to and from various file formats. 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 symbolic link? * Truenames:: Eliminating symbolic links from a file name. * 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. * Relative File Names:: Some file names are relative to a current directory. * Directory Names:: A directory's name as a directory is different from its name as a file. * 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. * Standard File Names:: If your package uses a fixed file name, how to handle various operating systems simply. 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? * Current Buffer:: Designating a buffer as current so primitives will access its contents. * 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. * Indirect Buffers:: An indirect buffer shares text with some other buffer. * Buffer Gap:: The gap in the buffer. 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. * Choosing Window:: How to choose a window for displaying a buffer. * 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. * Textual Scrolling:: Moving text up and down through the window. * Vertical Scrolling:: Moving the contents up and down on the window. * Horizontal Scrolling:: Moving the contents sideways on the window. * Size of Window:: Accessing the size of a window. * Resizing Windows:: Changing the size of a window. * Coordinates and Windows:: Converting coordinates to windows. * Window Configurations:: Saving and restoring the state of the screen. * Window Hooks:: Hooks for scrolling, window size changes, redisplay going past a certain point, or window configuration changes. Frames * Creating Frames:: Creating additional frames. * Multiple Displays:: Creating frames on other X displays. * Frame Parameters:: Controlling frame size, position, font, etc. * Frame Titles:: Automatic updating of frame titles. * Deleting Frames:: Frames last until explicitly deleted. * Finding All Frames:: How to examine all existing frames. * Frames and Windows:: A frame contains windows; display of text always works through windows. * Minibuffers and Frames:: How a frame finds the minibuffer to use. * Input Focus:: Specifying the selected frame. * Visibility of Frames:: Frames may be visible or invisible, or icons. * Raising and Lowering:: Raising a frame makes it hide other X windows; lowering it puts it underneath the others. * Frame Configurations:: Saving the state of all frames. * Mouse Tracking:: Getting events that say when the mouse moves. * Mouse Position:: Asking where the mouse is, or moving it. * Pop-Up Menus:: Displaying a menu for the user to select from. * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections::Transferring text to and from other windows. * Color Names:: Getting the definitions of color names. * Text Terminal Colors:: Defining colors for text-only terminals. * Resources:: Getting resource values from the server. * Display Feature Testing:: Determining the features of a terminal. 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. * 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. * Marker Insertion Types:: Two ways a marker can relocate when you insert where it points. * Moving 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. * Comparing Text:: Comparing substrings of buffers. * 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. * Maintaining Undo:: How to enable and disable undo information. How to control how much information is kept. * Filling:: Functions for explicit filling. * Margins:: How to specify margins for filling commands. * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context. * Auto Filling:: How auto-fill mode is implemented to break lines. * Sorting:: Functions for sorting parts of the buffer. * Columns:: Computing horizontal positions, and using them. * Indentation:: Functions to insert or adjust indentation. * Case Changes:: Case conversion of parts of the buffer. * Text Properties:: Assigning Lisp property lists to text characters. * Substitution:: Replacing a given character wherever it appears. * Transposition:: Swapping two portions of a buffer. * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Base 64:: Conversion to or from base 64 encoding. * MD5 Checksum:: Compute the MD5 "message digest"/"checksum". * Atomic Changes:: Installing several buffer changes "atomically". * Change Hooks:: Supplying functions to be run when text is changed. The Kill Ring * Kill Ring Concepts:: What text looks like in the kill ring. * Kill Functions:: Functions that kill text. * Yanking:: How yanking is done. * 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. Text Properties * Examining Properties:: Looking at the properties of one character. * Changing Properties:: Setting the properties of a range of text. * Property Search:: Searching for where a property changes value. * Special Properties:: Particular properties with special meanings. * Format Properties:: Properties for representing formatting of text. * Sticky Properties:: How inserted text gets properties from neighboring text. * Saving Properties:: Saving text properties in files, and reading them back. * Lazy Properties:: Computing text properties in a lazy fashion only when text is examined. * Clickable Text:: Using text properties to make regions of text do something when you click on them. * Links and Mouse-1:: How to make @key{Mouse-1} follow a link. * Fields:: The @code{field} property defines fields within the buffer. * Not Intervals:: Why text properties do not use Lisp-visible text intervals. Non-ASCII Characters * Text Representations:: Unibyte and multibyte representations * Converting Representations:: Converting unibyte to multibyte and vice versa. * Selecting a Representation:: Treating a byte sequence as unibyte or multi. * Character Codes:: How unibyte and multibyte relate to codes of individual characters. * Character Sets:: The space of possible characters codes is divided into various character sets. * Chars and Bytes:: More information about multibyte encodings. * Splitting Characters:: Converting a character to its byte sequence. * Scanning Charsets:: Which character sets are used in a buffer? * Translation of Characters:: Translation tables are used for conversion. * Coding Systems:: Coding systems are conversions for saving files. * Input Methods:: Input methods allow users to enter various non-ASCII characters without special keyboards. * Locales:: Interacting with the POSIX locale. Searching and Matching * String Search:: Search for an exact match. * Searching and Case:: Case-independent or case-significant searching. * Regular Expressions:: Describing classes of strings. * Regexp Search:: Searching for a match for a regexp. * POSIX Regexps:: Searching POSIX-style for the longest match. * Match Data:: Finding out which part of the text matched, after a string or regexp search. * Search and Replace:: Commands that loop, searching and replacing. * Standard Regexps:: Useful regexps for finding sentences, pages,... Regular Expressions * Syntax of Regexps:: Rules for writing regular expressions. * Regexp Example:: Illustrates regular expression syntax. * Regexp Functions:: Functions for operating on regular expressions. Syntax Tables * Syntax Basics:: Basic concepts of syntax tables. * Syntax Descriptors:: How characters are classified. * Syntax Table Functions:: How to create, examine and alter syntax tables. * Syntax Properties:: Overriding syntax with text properties. * Motion and Syntax:: Moving over characters with certain syntaxes. * 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. * Categories:: Another way of classifying character syntax. 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. * Abbrev Tables:: Creating and working with abbrev tables. * Defining Abbrevs:: Specifying abbreviations and their expansions. * Abbrev Files:: Saving abbrevs in files. * Abbrev Expansion:: Controlling expansion; expansion subroutines. * Standard Abbrev Tables:: Abbrev tables used by various major modes. Processes * Subprocess Creation:: Functions that start subprocesses. * Shell Arguments:: Quoting an argument to pass it to a shell. * 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. * Query Before Exit:: Whether to query if exiting will kill a process. * Transaction Queues:: Transaction-based communication with subprocesses. * Network:: Opening network connections. * Network Servers:: Network servers let Emacs accept net connections. * Datagrams:: UDP network connections. * Low-Level Network:: Lower-level but more general function to create connections and servers. * Misc Network:: Additional relevant functions for network connections. * Byte Packing:: Using bindat to pack and unpack binary data. Receiving Output from Processes * Process Buffers:: If no filter, output is put in a buffer. * Filter Functions:: Filter functions accept output from the process. * Decoding Output:: Filters can get unibyte or multibyte strings. * Accepting Output:: How to wait until process output arrives. Emacs Display * Refresh Screen:: Clearing the screen and redrawing everything on it. * Forcing Redisplay:: Forcing redisplay. * Truncation:: Folding or wrapping long text lines. * The Echo Area:: Displaying messages at the bottom of the screen. * Warnings:: Displaying warning messages for the user. * Invisible Text:: Hiding part of the buffer text. * Selective Display:: Hiding part of the buffer text (the old way). * Temporary Displays:: Displays that go away automatically. * Overlays:: Use overlays to highlight parts of the buffer. * Width:: How wide a character or string is on the screen. * Line Height:: Controlling the height of lines. * Faces:: A face defines a graphics style for text characters: font, colors, etc. * Fringes:: Controlling window fringes. * Scroll Bars:: Controlling vertical scroll bars. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. * Abstract Display:: Emacs' Widget for Object Collections. * Blinking:: How Emacs shows the matching open parenthesis. * Usual Display:: The usual conventions for displaying nonprinting chars. * Display Tables:: How to specify other conventions. * Beeping:: Audible signal to the user. * Window Systems:: Which window system is being used. 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. * User Identification:: Finding the name and user id of the user. * Time of Day:: Getting the current time. * Time Conversion:: Converting a time from numeric form to a string, or to calendrical data (or vice versa). * Time Parsing:: Converting a time from numeric form to text and vice versa. * Processor Run Time:: Getting the run time used by Emacs. * Time Calculations:: Adding, subtracting, comparing times, etc. * Timers:: Setting a timer to call a function at a certain time. * Terminal Input:: Accessing and recordingo terminal input. * Terminal Output:: Controlling and recording terminal output. * Sound Output:: Playing sounds on the computer's speaker. * X11 Keysyms:: Operating on key symbols for X Windows * Batch Mode:: Running Emacs without terminal interaction. * Session Management:: Saving and restoring state with X Session Management. Starting Up Emacs * Startup 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. Tips and Conventions * Coding Conventions:: Conventions for clean and robust programs. * Key Binding Conventions:: Which keys should be bound by which programs. * Programming Tips:: Making Emacs code fit smoothly in Emacs. * Compilation Tips:: Making compiled code run fast. * Warning Tips:: Turning off compiler warnings. * Documentation Tips:: Writing readable documentation strings. * Comment Tips:: Conventions for writing comments. * Library Headers:: Standard headers for library packages. 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. * Memory Usage:: Info about total size of Lisp objects made so far. * Writing Emacs Primitives:: Writing C code for Emacs. * Object Internals:: Data formats of buffers, windows, processes. 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 hash.texi @include symbols.texi @include eval.texi @include control.texi @include variables.texi @include functions.texi @include macros.texi @include customize.texi @include loading.texi @include compile.texi @include advice.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 nonascii.texi @include searching.texi @include syntax.texi @include abbrevs.texi @include processes.texi @include display.texi @include os.texi @c MOVE to Emacs Manual: include misc-modes.texi @c appendices @c REMOVE this: include non-hacker.texi @include anti.texi @include doclicense.texi @include gpl.texi @include tips.texi @include internals.texi @include errors.texi @include locals.texi @include maps.texi @include hooks.texi @include index.texi @ignore @node New Symbols, , Index, Top @unnumbered New Symbols Since the Previous Edition @printindex tp @end ignore @bye These words prevent "local variables" above from confusing Emacs. @ignore arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34 @end ignore