OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / info / elisp.i01 < prev next >

Wrap

GNU Info File | 1993-06-14 | 50.8 KB | 1,097 lines

This is Info file elisp, produced by Makeinfo-1.47 from the input file elisp.texi. This file documents GNU Emacs Lisp. This is edition 1.03 of the GNU Emacs Lisp Reference Manual, for Emacs Version 18. Published by the Free Software Foundation, 675 Massachusetts Avenue, Cambridge, MA 02139 USA Copyright (C) 1990 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. File: elisp, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) This Info file contains edition 1.03 of the GNU Emacs Lisp Reference Manual. * Menu: * License:: 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. * 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. * Emacs Display:: Parameters controlling screen usage. The bell. Waiting for input. 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. * 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 `nil' and `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 * Number Type:: Primarily integers. * 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 its 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. * 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 * Number Basics:: Representation and range of numbers. * 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. * Random Numbers:: Obtaining random integers, predictable or not. Strings and Characters * Intro to Strings:: 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:: `format': Emacs's analog of `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:: `if', `cond'. * Combining Conditions:: `and', `or', `not'. * Iteration:: `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 `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. 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 `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 input 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.) * Programmed Completion:: Finding the completions for a given file name. * 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. * Lisp Symbol Completion:: Completing the name of a symbol. 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. * Keyboard Input:: How your program can read characters from the keyboard. * Quitting:: How `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 `interactive'. * Interactive Codes:: The standard letter-codes for reading arguments in various ways. * Interactive Examples:: Examples of how to read interactive arguments. Keymaps * Keymap Terms:: Definitions of terms pertaining to keymaps. * Creating Keymaps:: Functions to create and copy keymaps. * Key Lookup:: How extracting elements from keymaps works. * Functions for Key Lookup:: How to request key lookup. * Prefix Keys:: Defining a key with a keymap as its definition. * Global and Local Keymaps:: Each buffer has a local keymap to override the standard (global) bindings. * 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. * Limits of Minor Modes:: Minor modes are of limited generality. 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:: `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 "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 `next-line' and `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 * Data in Kill Ring:: What text looks like in the kill ring. * Kill Functions:: Functions that kill text. * Yank Commands:: Commands that access the kill ring. * Kill Ring Internals:: 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. * VMS Subprocesses:: VMS has completely different subprocess features. * 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 (`.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. * Screen Attributes:: How big is the Emacs screen. * Truncation:: Folding or wrapping long text lines. * The Echo Area:: Where messages are displayed. * Selective Display:: Hiding part of the buffer text. * Overlay Arrow:: Display of an arrow to indicate position. * Temporary Displays:: Displays that go away automatically. * Waiting:: Forcing display update and waiting for user. * Blinking:: How Emacs shows the matching open parenthesis. * Control Char 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. File: elisp, Node: License, Next: Introduction, Prev: Top, Up: Top GNU Emacs General Public License ******************************** (Clarified 11 Feb 1988) The license agreements of most software companies keep you at the mercy of those companies. By contrast, our general public license is intended to give everyone the right to share GNU Emacs. To make sure that you get the rights we want you to have, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. Hence this license agreement. Specifically, we want to make sure that you have the right to give away copies of Emacs, that you receive source code or else can get it if you want it, that you can change Emacs or use pieces of it in new free programs, and that you know you can do these things. To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of Emacs, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. Also, for our own protection, we must make certain that everyone finds out that there is no warranty for GNU Emacs. If Emacs is modified by someone else and passed on, we want its recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation. Therefore we (Richard Stallman and the Free Software Foundation, Inc.) make the following terms which say what you must do to be allowed to distribute or change GNU Emacs. Copying Policies ================ 1. You may copy and distribute verbatim copies of GNU Emacs source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each file a valid copyright notice "Copyright (C) 1988 Free Software Foundation, Inc." (or with whatever year is appropriate); keep intact the notices on all files that refer to this License Agreement and to the absence of any warranty; and give any other recipients of the GNU Emacs program a copy of this License Agreement along with the program. You may charge a distribution fee for the physical act of transferring a copy. 2. You may modify your copy or copies of GNU Emacs source code or any portion of it, and copy and distribute such modifications under the terms of Paragraph 1 above, provided that you also do the following: * cause the modified files to carry prominent notices stating who last changed such files and the date of any change; and * cause the whole of any work that you distribute or publish, that in whole or in part contains or is a derivative of GNU Emacs or any part thereof, to be licensed at no charge to all third parties on terms identical to those contained in this License Agreement (except that you may choose to grant more extensive warranty protection to some or all third parties, at your option). * if the modified program serves as a text editor, cause it, when started running in the simplest and usual way, to print an announcement including a valid copyright notice "Copyright (C) 1988 Free Software Foundation, Inc." (or with the year that is appropriate), saying that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License Agreement. * You may charge a distribution fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. Mere aggregation of another unrelated program with this program (or its derivative) on a volume of a storage or distribution medium does not bring the other program under the scope of these terms. 3. You may copy and distribute GNU Emacs (or a portion or derivative of it, under Paragraph 2) in object code or executable form under the terms of Paragraphs 1 and 2 above provided that you also do one of the following: * accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Paragraphs 1 and 2 above; or, * accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal shipping charge) a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 above; or, * accompany it with the information you received as to where the corresponding source code may be obtained. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.) For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it need not include source code for modules which are standard libraries that accompany the operating system on which the executable file runs. 4. You may not copy, sublicense, distribute or transfer GNU Emacs except as expressly provided under this License Agreement. Any attempt otherwise to copy, sublicense, distribute or transfer GNU Emacs is void and your rights to use GNU Emacs under this License agreement shall be automatically terminated. However, parties who have received computer software programs from you with this License Agreement will not have their licenses terminated so long as such parties remain in full compliance. 5. If you wish to incorporate parts of GNU Emacs into other free programs whose distribution conditions are different, write to the Free Software Foundation. We have not yet worked out a simple rule that can be stated here, but we will often permit this. We will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software. Your comments and suggestions about our licensing policies and our software are welcome! Please contact the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139. NO WARRANTY =========== BECAUSE GNU EMACS IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC, RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU EMACS "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE GNU EMACS PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY MODIFY AND REDISTRIBUTE GNU EMACS AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. File: elisp, Node: Introduction, Next: Types of Lisp Object, Prev: License, Up: Top Introduction ************ Most of the GNU Emacs text editor is written in the programming language called Emacs Lisp. You can write new code in Emacs Lisp and install it as an extension to the editor. However, Emacs Lisp is more than a mere "extension language"; it is a full computer programming language in its own right. You can use it as you would any other programming language. Because Emacs Lisp is designed for use in an editor, it has special features for scanning and parsing text as well as features for handling files, buffers, displays, subprocesses, and so on. Emacs Lisp is closely integrated with the editing facilities; thus, editing commands are functions that can also conveniently be called from Lisp programs, and parameters for customization are ordinary Lisp variables. This manual describes Emacs Lisp, presuming considerable familiarity with the use of Emacs for editing. (See `The GNU Emacs Manual', for this basic information.) Generally speaking, the earlier chapters describe features of Emacs Lisp that have counterparts in many programming languages, and later chapters describe features that are peculiar to Emacs Lisp or relate specifically to editing. This is edition 1.02. * Menu: * 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. File: elisp, Node: Caveats, Next: Lisp History, Prev: Introduction, Up: Introduction Caveats ======= This manual has gone through numerous drafts. It is nearly complete but not flawless. There are a few sections which are not included, either because we consider them secondary (such as most of the individual modes) or because they are yet to be written. Because we are not able to deal with them completely, we have left out several parts intentionally. This includes most references to VMS and all information relating to X Windows and Sunview. The functions for using X Windows will in any case be entirely different in version 19. (The Free Software Foundation expends no effort on support for Sunview, since we believe users should use free X Windows rather than proprietary window systems.) The manual should be fully correct in what it does cover, and it is therefore open to criticism on anything it says--from specific examples and descriptive text, to the ordering of chapters and sections. If something is confusing, or you find that you have to look at the sources or experiment to learn something not covered in the manual, then perhaps the manual should be fixed. Please let us know. As you use this manual, we ask that you send corrections as soon as you find them. If you think of a simple, real life example for a function or group of functions, please make an effort to write it up and send it in. Please reference any comments to the node name and function or variable name, as appropriate. Please mail comments and corrections to `lisp-manual-bugs@prep.ai.mit.edu'. --Bil Lewis, Dan LaLiberte, Richard Stallman File: elisp, Node: Lisp History, Next: Conventions, Prev: Caveats, Up: Introduction Lisp History ============ Lisp (LISt Processing language) was first developed in the late 1950s at the Massachusetts Institute of Technology for research in artificial intelligence. The great power of the Lisp language makes it superior for other purposes as well, such as writing editing commands. Dozens of Lisp implementations have been built over the years, each with its own idiosyncrasies. Many of them were inspired by Maclisp, which was written in the 1960's at MIT's Project MAC. Eventually the implementors of the descendents of Maclisp came together and developed a standard for Lisp systems, called Common Lisp. GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common Lisp. If you know Common Lisp, you will notice many similarities. However, many of the features of Common Lisp have been omitted or simplified in order to reduce the memory requirements of GNU Emacs. Sometimes the simplifications are so drastic that a Common Lisp user might be very confused. We will occasionally point out how GNU Emacs Lisp differs from Common Lisp. If you don't know Common Lisp, don't worry about it; this manual is self-contained. File: elisp, Node: Conventions, Next: Acknowledgements, Prev: Lisp History, Up: Introduction Conventions =========== This section explains the notational conventions that are used in this manual. You may want to skip this section and refer back to it later. * Menu: * Some Terms:: Explanation of terms we use in this manual. * nil and t:: How the symbols `nil' and `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. File: elisp, Node: Some Terms, Next: nil and t, Prev: Conventions, Up: Conventions Some Terms ---------- Throughout this manual, the phrases "the Lisp reader" and "the Lisp printer" are used to refer to those routines in Lisp that convert textual representations of Lisp objects into actual objects, and vice versa. *Note Printed Representation::, for more details. You, the person reading this manual, are assumed to be "the programmer" and are addressed as "you". "The user" is the person who uses the code that you write. Examples of Lisp code appear in this font or form: `(list 1 2 3)'. Names that represent arguments or metasyntactic variables appear in this font or form: FIRST-NUMBER. File: elisp, Node: nil and t, Next: Evaluation Notation, Prev: Some Terms, Up: Conventions `nil' and `t' ------------- In Lisp, the symbol `nil' is overloaded with three meanings: it is a symbol with the name `nil'; it is the logical truth value FALSE; and it is the empty list--the list of zero elements. When used as a variable, `nil' always has the value `nil'. As far as the Lisp reader is concerned, `()' and `nil' are identical: they stand for the same object, the symbol `nil'. The different ways of writing the symbol are intended entirely for human readers. After the Lisp reader has read either `()' or `nil', there is no way to determine which representation was actually written by the programmer. In this manual, we use `()' when we wish to emphasize that it means the empty list, and we use `nil' when we wish to emphasize that it means the truth value FALSE. That is a good convention to use in Lisp programs also. (cons 'foo ()) ; Emphasize the empty list (not nil) ; Emphasize the truth value FALSE In context where a truth value is expected, any non-`nil' value is considered to be TRUE. However, `t' is the preferred way to represent the truth value TRUE. When you need to choose a value which represents TRUE, and there is no other basis for choosing, use `t'. The symbol `t' always has value `t'. In Emacs Lisp, `nil' and `t' are special symbols that always evaluate to themselves. This is so that you do not need to quote them to use them as constants in a program. An attempt to change their values results in a `setting-constant' error. *Note Accessing Variables::. File: elisp, Node: Evaluation Notation, Next: Printing Notation, Prev: nil and t, Up: Conventions Evaluation Notation ------------------- When you evaluate a piece of Lisp code, it produces a result. In the examples in this manual, this is indicated with `=>': (car '(1 2)) => 1 You can read this as "`(car '(1 2))' evaluates to 1". When a form is a macro call, it expands into a new form for Lisp to evaluate. We show the result of the expansion with `==>'. We may or may not show the actual result of the evaluation of the expanded form. (third '(a b c)) ==> (car (cdr (cdr '(a b c)))) => c Sometimes to help describe one form we show another form which produces identical results. The exact equivalence of two forms is indicated with `=='. (make-sparse-keymap) == (list 'keymap)