diff options
| author | Glenn Morris <rgm@gnu.org> | 2007-09-06 04:15:52 +0000 |
|---|---|---|
| committer | Glenn Morris <rgm@gnu.org> | 2007-09-06 04:15:52 +0000 |
| commit | f69340d750ef530bcc3497243ab3be3187f8ce6e (patch) | |
| tree | 32d480fa1c1da99112a15d803c52dcd45bc2613a /lispref | |
| parent | d7625e640a60b2f60613b63b639df61f149c9daf (diff) | |
| download | emacs-f69340d750ef530bcc3497243ab3be3187f8ce6e.tar.gz | |
Move to ../doc/lispref
Diffstat (limited to 'lispref')
72 files changed, 0 insertions, 83466 deletions
diff --git a/lispref/.arch-inventory b/lispref/.arch-inventory deleted file mode 100644 index 2f5e6b9eea0..00000000000 --- a/lispref/.arch-inventory +++ /dev/null @@ -1,4 +0,0 @@ -# Generated files -precious ^(config\.status|config\.cache)$ - -# arch-tag: dde817a2-94ff-4c6e-838c-bb5b33e7f0df diff --git a/lispref/.gitignore b/lispref/.gitignore deleted file mode 100644 index a149258f6dd..00000000000 --- a/lispref/.gitignore +++ /dev/null @@ -1,17 +0,0 @@ -texput.log -elisp.?? -elisp.??? -configure -config.log -config.cache -config.status -Makefile -makefile -index.texi -elisp -elisp-? -elisp-?? -vol1.* -vol2.* -elisp1* -elisp2* diff --git a/lispref/ChangeLog b/lispref/ChangeLog deleted file mode 100644 index c9932f5f1fb..00000000000 --- a/lispref/ChangeLog +++ /dev/null @@ -1,6280 +0,0 @@ -2007-08-29 Glenn Morris <rgm@gnu.org> - - * elisp.texi (EMACSVER): Increase to 23.0.50. - -2007-08-29 Dan Nicolaescu <dann@ics.uci.edu> - - * frames.texi (Basic Parameters): Add display-environment-variable - and term-environment-variable. - -2007-08-28 Juri Linkov <juri@jurta.org> - - * display.texi (Image Formats, Other Image Types): Add SVG. - -2007-08-28 Juri Linkov <juri@jurta.org> - - * display.texi (Images): Move formats-related text to new node - "Image Formats". - (Image Formats): New node. - -2007-08-25 Richard Stallman <rms@gnu.org> - - * display.texi (Images): Delete redundant @findex. - -2007-08-16 Richard Stallman <rms@gnu.org> - - * processes.texi (Asynchronous Processes): Clarify - doc of start-file-process. - -2007-08-08 Martin Rudalics <rudalics@gmx.at> - - * modes.texi (Example Major Modes): Fix typo. - -2007-08-08 Glenn Morris <rgm@gnu.org> - - * intro.texi (nil and t): Do not use `iff' in documentation. - - * tips.texi (Documentation Tips): Recommend against `iff'. - -2007-08-07 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Image Cache): Document image-refresh. - -2007-08-06 Martin Rudalics <rudalics@gmx.at> - - * windows.texi (Size of Window): Document window-full-width-p. - -2007-07-25 Glenn Morris <rgm@gnu.org> - - * gpl.texi (GPL): Replace license with GPLv3. - - * Relicense all FSF files to GPLv3 or later. - -2007-07-24 Michael Albinus <michael.albinus@gmx.de> - - * processes.texi (Synchronous Processes): Add - `process-file-shell-command', - (Asynchronous Processes): Mention restricted use of - `process-filter' and `process-sentinel' in - `start-file-process'. Add `start-file-process-shell-command'. - -2007-07-17 Michael Albinus <michael.albinus@gmx.de> - - * files.texi (Magic File Names): Introduce optional parameter - IDENTIFICATION for `file-remote-p'. - -2007-07-16 Richard Stallman <rms@gnu.org> - - * display.texi (Defining Faces): Fix previous change. - -2007-07-14 Richard Stallman <rms@gnu.org> - - * control.texi (Handling Errors): Document `debug' in handler list. - -2007-07-10 Richard Stallman <rms@gnu.org> - - * display.texi (Defining Faces): Explain C-M-x feature for defface. - -2007-07-09 Richard Stallman <rms@gnu.org> - - * files.texi (Magic File Names): Rewrite previous change. - -2007-07-08 Michael Albinus <michael.albinus@gmx.de> - - * files.texi (Magic File Names): Introduce optional parameter - CONNECTED for `file-remote-p'. - -2007-07-07 Michael Albinus <michael.albinus@gmx.de> - - * processes.texi (Asynchronous Processes): - * files.texi (Magic File Names): Add `start-file-process'. - -2007-06-27 Richard Stallman <rms@gnu.org> - - * files.texi (Format Conversion Piecemeal): Clarify - `after-insert-file-functions' calling convention. - -2007-06-27 Michael Albinus <michael.albinus@gmx.de> - - * files.texi (Magic File Names): Remove `dired-call-process'. Add - `process-file'. - -2007-06-27 Kenichi Handa <handa@m17n.org> - - * text.texi (Special Properties): Fix description about - `compostion' property. - -2007-06-26 Kenichi Handa <handa@m17n.org> - - * nonascii.texi (Default Coding Systems): Document about the - return value `undecided'. - -2007-06-25 David Kastrup <dak@gnu.org> - - * keymaps.texi (Active Keymaps): Document new POSITION argument of - `current-active-maps'. - -2007-06-24 Karl Berry <karl@gnu.org> - - * elisp.texi, vol1.texi, vol2.texi: new Back-Cover Text. - -2007-06-15 Juanma Barranquero <lekktu@gmail.com> - - * display.texi (Overlay Arrow): Doc fix. - -2007-06-14 Karl Berry <karl@tug.org> - - * anti.texi (Antinews): Typo. - -2007-06-14 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Image Cache): Document image-refresh. - -2007-06-12 Karl Berry <karl@gnu.org> - - * vol1.texi, vol2.texi, two-volume-cross-refs.txt: Update. - * two-volume.make: New file. - * .cvsignore: Ignore two-volume files. - -2007-06-12 Tom Tromey <tromey@redhat.com> - - * os.texi (Init File): Document user-emacs-directory. - -2007-06-03 Nick Roberts <nickrob@snap.net.nz> - - * commands.texi (Click Events): Describe width and height when - object is nil. - -2007-05-30 Nick Roberts <nickrob@snap.net.nz> - - * commands.texi (Click Events): Layout more logically. Describe - width and height. - (Drag Events, Motion Events): Update to new format for position. - -2007-06-02 Richard Stallman <rms@gnu.org> - - * frames.texi (Color Parameters): Add xref to (emacs)Standard Faces. - -2007-06-02 Chong Yidong <cyd@stupidchicken.com> - - * Version 22.1 released. - -2007-06-01 Stefan Monnier <monnier@iro.umontreal.ca> - - * text.texi (Special Properties): Correct meaning of fontified face. - -2007-05-30 Richard Stallman <rms@gnu.org> - - * text.texi (Special Properties): Add link to Adjusting Point. - -2007-05-12 Richard Stallman <rms@gnu.org> - - * text.texi (Margins): indent-to-left-margin is not the default. - (Mode-Specific Indent): For indent-line-function, the default - is indent-relative. - - * modes.texi (Example Major Modes): Explain last line of text-mode - is redundant. - -2007-05-10 Richard Stallman <rms@gnu.org> - - * keymaps.texi (Scanning Keymaps): Update where-is-internal example. - - * help.texi (Keys in Documentation): Add reference to - Documentation Tips. - - * files.texi (Format Conversion): TO-FN gets three arguments. - - * modes.texi (Auto Major Mode): Document file-start-mode-alist. - -2007-05-10 Thien-Thi Nguyen <ttn@gnuvola.org> - - * elisp.texi (Top): Remove "Saving Properties" from detailed menu. - * files.texi (Format Conversion): Expand intro; add menu. - (Format Conversion Overview, Format Conversion Round-Trip) - (Format Conversion Piecemeal): New nodes/subsections. - * hooks.texi: Xref "Format Conversion" , not "Saving Properties". - * text.texi (Text Properties): Remove "Saving Properties" from menu. - (Saving Properties): Delete node/subsection. - -2007-05-07 Karl Berry <karl@gnu.org> - - * elisp.texi (EMACSVER): Back to 22. - -2007-05-06 Richard Stallman <rms@gnu.org> - - * processes.texi (Accepting Output): Revert most of previous change. - -2007-05-05 Richard Stallman <rms@gnu.org> - - * processes.texi (Accepting Output): accept-process-output - uses microseconds, not milliseconds. But that arg is obsolete. - -2007-05-04 Karl Berry <karl@tug.org> - - * elisp.texi (EMACSVER) [smallbook]: 22.1, not 22. - -2007-05-04 Eli Zaretskii <eliz@gnu.org> - - * tips.texi (Documentation Tips): Rearrange items to place the - more important ones first. Add an index entry for hyperlinks. - -2007-05-03 Karl Berry <karl@gnu.org> - - * elisp.texi (\urlcolor, \linkcolor) [smallbook]: \Black for printing. - (EMACSVER) [smallbook]: 22 for printed version. - - * control.texi (Signaling Errors) <signal>: texinfo.tex is fixed, - so restore anchor to normal position after defun. Found by Kevin Ryde. - -2007-04-26 Glenn Morris <rgm@gnu.org> - - * elisp.texi (EMACSVER): Increase to 22.1.50. - -2007-04-28 Karl Berry <karl@gnu.org> - - * elisp.texi: Improve line breaks on copyright page, - similar layout to emacs manual, 8.5x11 by default. - -2007-04-24 Richard Stallman <rms@gnu.org> - - * text.texi (Special Properties): Add xref to Overlay Properties. - - * display.texi (Overlay Properties): Add xref to Special Properties. - -2007-04-22 Richard Stallman <rms@gnu.org> - - * keymaps.texi (Extended Menu Items): Move the info about - format with cached keyboard binding. - -2007-04-21 Richard Stallman <rms@gnu.org> - - * text.texi (Special Properties): Clarify previous change. - - * files.texi (File Name Expansion): Clarify previous change. - - * display.texi (Attribute Functions): Fix example for - face-attribute-relative-p. - -2007-04-19 Kenichi Handa <handa@m17n.org> - - * text.texi (Special Properties): Document composition property. - -2007-04-19 Glenn Morris <rgm@gnu.org> - - * files.texi (File Name Expansion): Mention "superroot". - -2007-04-15 Chong Yidong <cyd@stupidchicken.com> - - * frames.texi (Multiple Displays): Add note about "multi-monitor" - setups. - (Display Feature Testing): Note that display refers to all - physical monitors for multi-monitor setups. - -2007-04-14 Richard Stallman <rms@gnu.org> - - * lists.texi (Sets And Lists): Clarify `delete' examples. - Remove spurious xref to same node. - Clarify xref for add-to-list. - -2007-04-12 Nick Roberts <nickrob@snap.net.nz> - - * keymaps.texi (Format of Keymaps): Remove spurious ")" from - value of lisp-mode-map. - -2007-04-11 Karl Berry <karl@gnu.org> - - * anti.texi (Antinews): - * display.texi (Overlay Properties, Defining Images): - * processes.texi (Synchronous Processes, Sentinels): - * syntax.texi (Syntax Table Internals): - * searching.texi (Regexp Special): - * nonascii.texi (Default Coding Systems): - * text.texi (Special Properties): - * minibuf.texi (Basic Completion): Wording to improve breaks in - 8.5x11 format. - * elisp.texi (smallbook): New @set to more easily switch between - smallbook and 8.5x11. - -2007-04-11 Richard Stallman <rms@gnu.org> - - * text.texi (Lazy Properties): Minor fix. - -2007-04-08 Karl Berry <karl@gnu.org> - - * symbols.texi (Plists and Alists): Period after "vs" in index entries. - * macros.texi (Backquote): Downcase Backquote in index entries for - consistency. - -2007-04-08 Richard Stallman <rms@gnu.org> - - * text.texi (Adaptive Fill): Just describe default, - don't show it (since it contains non-ASCII chars). - -2007-04-07 Karl Berry <karl@gnu.org> - - * text.texi (Adaptive Fill) [@iftex]: Omit binary characters in - adaptive-fill-regexp's value, since they are not in the standard - TeX fonts. - -2007-04-07 Guanpeng Xu <herberteuler@hotmail.com> - - * display.texi (Defining Faces): Fix example. - -2007-04-07 Karl Berry <karl@gnu.org> - - * display.texi (Button Buffer Commands): Improve page break. - -2007-04-07 Richard Stallman <rms@gnu.org> - - * advice.texi (Activation of Advice): Remove redundant index entry. - - * backups.texi: Improve index entries. Remove redundant ones. - - * compile.texi (Byte Compilation): Improve index entry. - - * hash.texi (Creating Hash): Improve index entry. - - * symbols.texi (Definitions): Improve index entry. - - * edebug.texi: Improve index entries. Remove redundant/useless ones. - - * maps.texi (Standard Keymaps): Remove useless index entry. - - * help.texi (Documentation Basics): Remove redundant index entries. - - * customize.texi: Improve index entries. - Remove redundant/useless ones. - - * locals.texi (Standard Buffer-Local Variables): Clarify intro text. - - * streams.texi (Output Variables): Improve index entry. - - * abbrevs.texi (Abbrevs): Remove useless index entry. - - * macros.texi (Expansion): Remove useless index entry. - - * text.texi: Improve index entries. Remove redundant/useless ones. - (Text Properties, Examining Properties) - (Special Properties): Use "property category" instead of "category" - to refer to the `category' property. - - * positions.texi: Improve index entries. Remove useless one. - - * lists.texi: Improve index entries. Remove redundant/useless ones. - - * os.texi: Improve index entries. - (Timers): Fix previous change. - - * buffers.texi: Improve index entries. - (Modification Time): Get rid of term "obsolete buffer". - - * debugging.texi: Improve index entries. - (Test Coverage): Add xref to other test coverage ftr. - - * eval.texi: Improve index entry. Remove redundant ones. - - * numbers.texi: Improve index entries. Remove redundant/useless ones. - - * files.texi: Improve index entries. Remove redundant/useless ones. - - * objects.texi: Improve index entries. - - * processes.texi: Improve index entries. - - * modes.texi: Improve index entry. Remove redundant one. - - * nonascii.texi: Improve index entries. - - * internals.texi: Improve index entries. - - * syntax.texi: Improve index entries. - - * keymaps.texi (Active Keymaps): Improve index entries. - - * commands.texi: Improve index entries. Remove redundant/useless ones. - - * frames.texi: Improve index entries. Remove redundant/useless ones. - - * markers.texi: Improve index entries. Remove redundant ones. - - * tips.texi: Improve index entries. - - * loading.texi (Unloading): Improve index entry. - - * variables.texi: Improve index entries. Remove redundant one. - - * sequences.texi: Improve index entry. - - * display.texi: Improve index entries. Remove redundant ones. - - * windows.texi: Improve index entries. - - * searching.texi: Improve index entries. Remove redundant one. - - * strings.texi (Case Tables): Improve last change. - -2007-04-04 Chong Yidong <cyd@stupidchicken.com> - - * strings.texi (Case Tables): Document with-case-table and - ascii-case-table. - -2007-04-03 Karl Berry <karl@gnu.org> - - * processes.texi (Network): Reword to improve page break. - -2007-04-03 Eli Zaretskii <eliz@gnu.org> - - * functions.texi (Inline Functions): Describe more disadvantages - of defsubst, and make advice against it stronger. - -2007-04-02 Karl Berry <karl@gnu.org> - - * backups.texi (Backup Names): Avoid widow words. - * modes.texi (Example Major Modes): Align last comment. - -2007-04-01 Chong Yidong <cyd@stupidchicken.com> - - * keymaps.texi (Remapping Commands): Document new arg to - command-remapping. - -2007-04-01 Karl Berry <karl@gnu.org> - - * processes.texi (Low-Level Network): Typo. - * loading.texi (Hooks for Loading): Avoid double "the". - * keymaps.texi (Key Sequences): No double "and". - (Changing Key Bindings): Shorten to improve line break. - -2007-03-31 Glenn Morris <rgm@gnu.org> - - * os.texi (Timers): Fix description of run-at-time TIME formats. - -2007-03-31 Richard Stallman <rms@gnu.org> - - * display.texi (Invisible Text): Correct buffer-invisibility-spec - regarding ellipsis. - -2007-03-31 Eli Zaretskii <eliz@gnu.org> - - * intro.texi (nil and t): - * symbols.texi (Plists and Alists): - * variables.texi (Variable Aliases, Constant Variables): - * functions.texi (Defining Functions): - * advice.texi (Advising Primitives): - * debugging.texi (Syntax Errors, Compilation Errors): - * minibuf.texi (Minibuffer Windows): - * commands.texi (Adjusting Point): - * modes.texi (Syntactic Font Lock, Faces for Font Lock) - (Auto Major Mode, Major Mode Conventions): - * help.texi (Describing Characters): - * files.texi (Create/Delete Dirs, Information about Files) - (File Locks, Writing to Files, Reading from Files) - (Saving Buffers): - * windows.texi (Resizing Windows, Cyclic Window Ordering): - * frames.texi (Finding All Frames): - * positions.texi (Buffer End, Motion): - * markers.texi (The Region): - * text.texi (Deletion, Near Point): - * display.texi (Displaying Messages, Truncation): - * os.texi (Processor Run Time): - * tips.texi (Key Binding Conventions, Programming Tips) - (Warning Tips, Documentation Tips, Comment Tips): - * internals.texi (Memory Usage): Improve indexing. - - * variables.texi (Frame-Local Variables): - * functions.texi (Argument List): - * loading.texi (Library Search): - * streams.texi (Output Variables): - * keymaps.texi (Translation Keymaps, Searching Keymaps): - * searching.texi (Replacing Match, Search and Replace): - * processes.texi (Byte Packing, Decoding Output) - (Accepting Output, Network Servers, Shell Arguments): - * display.texi (Abstract Display, Image Cache, Scroll Bars): - * windows.texi (Window Point, Window Start): - * frames.texi (Management Parameters, Frame Parameters, Frame Titles): - * commands.texi (Reading Input, Keyboard Events): - * minibuf.texi (Reading File Names, Minibuffer Completion) - (Recursive Mini): - * positions.texi (List Motion): - * hash.texi (Hash Tables, Creating Hash, Defining Hash): - * numbers.texi (Arithmetic Operations, Math Functions) - (Predicates on Numbers, Comparison of Numbers): - (Numeric Conversions): - * locals.texi (Standard Buffer-Local Variables): - * maps.texi (Standard Keymaps): - * os.texi (User Identification, System Environment, Recording Input) - (X11 Keysyms): - * nonascii.texi (Non-ASCII Characters, Splitting Characters): - * backups.texi (Backups and Auto-Saving): - * customize.texi (Customization, Group Definitions) - (Variable Definitions): - * compile.texi (Byte Compilation): Improve index entries. - -2007-03-31 Karl Berry <karl@gnu.org> - - * macros.texi (Defining Macros): Avoid widow syllable. - -2007-03-31 Eli Zaretskii <eliz@gnu.org> - - * elisp.texi (Top): Postscript -> PostScript. - - * display.texi (Images, Postscript Images): Postscript -> PostScript. - -2007-03-31 Markus Triska <markus.triska@gmx.at> - - * internals.texi (Writing Emacs Primitives): Untabify `For'. - -2007-03-30 Karl Berry <karl@gnu.org> - - * lists.texi (List-related Predicates): Remove spurious @need. - (Setcdr): Use @smallexample to improve page break. - (Association Lists) <assoc>: Reword to improve page break. - - * strings.texi (String Conversion): Insert blank line to improve - page break. - - * numbers.texi (Random Numbers): Use @minus{}. - (Math Functions): Use @minus{}. - - * intro.texi (Acknowledgements): Avoid line breaks before middle - initials. - -2007-03-24 Eli Zaretskii <eliz@gnu.org> - - * errors.texi (Standard Errors): Add an index entry. - -2007-03-19 Richard Stallman <rms@gnu.org> - - * os.texi (Recording Input): recent-keys now gives 300 keys. - -2007-03-12 Glenn Morris <rgm@gnu.org> - - * os.texi: Replace "daylight savings" with "daylight saving" - throughout. - -2007-03-05 Richard Stallman <rms@gnu.org> - - * variables.texi (File Local Variables): Update - enable-local-variables values. - -2007-03-04 Richard Stallman <rms@gnu.org> - - * syntax.texi (Control Parsing): Minor clarification. - - * strings.texi (Formatting Strings): Clarify width, precision, flags. - - * sequences.texi (Sequence Functions): Move string-bytes away, - add xref. - - * nonascii.texi (Text Representations): Move string-bytes here. - - * modes.texi (Major Mode Conventions): Fundamental mode is exception. - - * minibuf.texi (Basic Completion): Minor clarification. - - * markers.texi (The Mark): Clarify existence vs activation of mark. - Other cleanup. - - * display.texi (Finding Overlays): Write better example. - - * compile.texi (Eval During Compile): Clarify putting macros - in eval-when-compile. - -2007-02-25 Vinicius Jose Latorre <viniciusjl@ig.com.br> - - * loading.texi (How Programs Do Loading): Fix anchor position at - load-read-function definition doc. (tiny change) - -2007-02-21 Kim F. Storm <storm@cua.dk> - - * strings.texi (Text Comparison): Mention that assoc-string - converts symbols to strings before testing. - -2007-02-17 Kim F. Storm <storm@cua.dk> - - * processes.texi (Bindat Spec): Vector types can have optional - element type. - (Bindat Examples): Fix example. Add vector with element type. - -2007-02-16 Andreas Schwab <schwab@suse.de> - - * strings.texi (Formatting Strings): Document '+' flag. - -2007-02-15 Juanma Barranquero <lekktu@gmail.com> - - * strings.texi (Modifying Strings): Clarify that `clear-string' - always converts the string to unibyte. - -2007-02-14 Kim F. Storm <storm@cua.dk> - - * display.texi (Glyphs): Add make-glyph-code, glyph-char, glyph-face. - Rewrite glyph code description to refer to these functions. - Remove details of encoding face number and char into integer code. - -2007-02-03 Alan Mackenzie <acm@muc.de> - - * loading.texi (Hooks for Loading): Make the description of - `eval-after-load' more detailed, and amend the description of - after-load-alist, in accordance with changes from 2006-05. - -2007-02-03 Chong Yidong <cyd@stupidchicken.com> - - * modes.texi (Defining Minor Modes): Document that a :require - keyword or similar may be required to make saved customization - variables work. - -2007-02-03 Eli Zaretskii <eliz@gnu.org> - - * elisp.texi (Top): Make the detailed menu headers compliant with - Texinfo guidelines and with what texnfo-upd.el expects. Add - comments to prevent people from inadvertently modifying the key - parts needed by `texinfo-multiple-files-update'. - -2007-02-02 Eli Zaretskii <eliz@gnu.org> - - * elisp.texi (Top): Update the top-level menus. - - * syntax.texi (Categories): Add index entries. - -2007-02-01 Juanma Barranquero <lekktu@gmail.com> - - * display.texi (Attribute Functions): Fix name and description of - the UNDERLINE arg of `set-face-underline-p'. - -2007-01-29 Eli Zaretskii <eliz@gnu.org> - - * elisp.texi (Top): Add "Standard Errors", "Standard Buffer-Local - Variables", and "Standard Keymaps" to the detailed menu. - - * variables.texi (Future Local Variables): Add index entry. - -2007-01-28 Richard Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Clarify the tip about macros - that define a function or a variable. - - * files.texi (File Attributes): UID and GID can be floats. - (Magic File Names): Explain why deferring all operations to - the standard handler does not work. - -2007-01-23 Martin Rudalics <rudalics@gmx.at> - - * backups.texi (Reverting): Use "buffer" instead of "file" - when talking about major and minor modes. - -2007-01-21 Richard Stallman <rms@gnu.org> - - * help.texi (Documentation): Add xref to Documentation Tips. - -2007-01-14 Juanma Barranquero <lekktu@gmail.com> - - * tips.texi (Coding Conventions): Fix typos. - -2007-01-05 Richard Stallman <rms@gnu.org> - - * modes.texi (Defining Minor Modes): Fix previous change. - -2007-01-03 Richard Stallman <rms@gnu.org> - - * customize.texi (Variable Definitions, Customization Types): - Don't use * in doc string for defcustom. - -2007-01-02 Richard Stallman <rms@gnu.org> - - * variables.texi (Variable Aliases): Clarify that aliases vars - always have the same value. - - * processes.texi (Bindat Spec): Fix Texinfo usage. - - * modes.texi (Defining Minor Modes): Explain effect of command - defined with define-global-minor-mode on new buffers. - -2006-12-30 Kim F. Storm <storm@cua.dk> - - * keymaps.texi (Tool Bar): Describe `grow-only' value of - `auto-resize-tool-bars'. - -2006-12-30 Richard Stallman <rms@gnu.org> - - * keymaps.texi (Active Keymaps): Fix previous change. - -2006-12-30 Nick Roberts <nickrob@snap.net.nz> - - * keymaps.texi (Active Keymaps): Make xref to lookup-key. - -2006-12-30 Kim F. Storm <storm@cua.dk> - - * processes.texi (Bindat Spec): Clarify using field names in - length specifications. - -2006-12-29 Kim F. Storm <storm@cua.dk> - - * processes.texi (Bindat Spec): Explain eval forms and lengths better. - Add count and index variables for eval forms in repeat blocks. - -2006-12-24 Richard Stallman <rms@gnu.org> - - * customize.texi (Variable Definitions): Document - new name custom-add-frequent-value. - -2006-12-19 Kim F. Storm <storm@cua.dk> - - * commands.texi (Misc Events): User signals now result in sigusr1 - and sigusr2 events which are handled through special-event-map. - (Special Events): User signals and drag-n-drop are special. - -2006-12-17 Richard Stallman <rms@gnu.org> - - * loading.texi (Named Features): Explain subfeatures better. - - * customize.texi: Use "option" only for user options. - For the keyword values inside defcustom etc, say "keywords". - For :options value's elements, say "elements". - :group should not be omitted. - - * syntax.texi (Parsing Expressions): Split up node. - (Motion via Parsing, Position Parse, Parser State) - (Low-Level Parsing, Control Parsing): New subnodes. - (Parser State): Document syntax-ppss-toplevel-pos. - - * positions.texi (List Motion): Punctuation fix. - - * files.texi (File Name Completion): Document PREDICATE arg - to file-name-completion. - -2006-12-16 Eli Zaretskii <eliz@gnu.org> - - * internals.texi (Building Emacs, Writing Emacs Primitives): - Add index entries. - -2006-12-11 Richard Stallman <rms@gnu.org> - - * modes.texi (Font Lock Basics): Explain how nil for font-lock-defaults - affects face menu. Explain how to make it non-nil without enabling - any fontification. - -2006-12-10 Chong Yidong <cyd@stupidchicken.com> - - * modes.texi (Font Lock Basics): Document nil value of - font-lock-defaults. - -2006-12-10 Glenn Morris <rgm@gnu.org> - - * abbrevs.texi (Defining Abbrevs): Mention `define-abbrev' 'force - value for system-flag argument. Abbrev tables may not be empty - when major modes are loaded. - -2006-12-08 Juanma Barranquero <lekktu@gmail.com> - - * makefile.w32-in (maintainer-clean): Partially revert last - change; delete "elisp-?" and "elisp-??" instead of "elisp-*" - to protect elisp-covers.texi. - -2006-12-07 Juanma Barranquero <lekktu@gmail.com> - - * makefile.w32-in (maintainer-clean): Depend on `distclean'. - Don't remove elisp* info files; they are already deleted by the - `clean' and `distclean' targets, and they are in the $(infodir) - directory, not the current one. - -2006-12-04 Kim F. Storm <storm@cua.dk> - - * commands.texi (Misc Events): Update signal events. - (Event Examples): Add signal example. - -2006-11-29 Richard Stallman <rms@gnu.org> - - * frames.texi (Visibility of Frames): Explain visible windows - can be covered by others. Add xref for raise-frame. - -2006-11-28 Richard Stallman <rms@gnu.org> - - * searching.texi (Regexp Special): Update when ^ is special. - -2006-11-27 Eli Zaretskii <eliz@gnu.org> - - * customize.texi (Customization, Common Keywords) - (Group Definitions, Variable Definitions, Composite Types) - (Type Keywords, Customization Types): Add index entries for - various customization keywords. - -2006-11-23 Stefan Monnier <monnier@iro.umontreal.ca> - - * modes.texi (Multiline Font Lock): Rephrase some parts for clarity. - -2006-11-10 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> - - * frames.texi (Window System Selections): Remove clipboard from - description of selection-coding-system. - -2006-11-06 Richard Stallman <rms@gnu.org> - - * lists.texi (List Variables): Document COMPARE-FN. - - * keymaps.texi: Avoid use of "binding" to mean a relation; - use it only to refer to the meaning associated with a key. - (Keymaps): Change menu node description. - - * elisp.texi (Top): Change menu node description. - - * display.texi (Managing Overlays): Document overlay-recenter. - -2006-10-29 Chong Yidong <cyd@stupidchicken.com> - - * Makefile.in: Use relative paths to avoid advertising filesystem - contents during compilation. - -2006-10-23 Kim F. Storm <storm@cua.dk> - - * commands.texi (Event Input Misc): Update unread-command-events. - -2006-10-23 Nick Roberts <nickrob@snap.net.nz> - - * lists.texi (Sets And Lists): Fix typos. - -2006-10-18 Juanma Barranquero <lekktu@gmail.com> - - * control.texi (Processing of Errors): Use @var for an argument, - not @code. - -2006-10-16 Richard Stallman <rms@gnu.org> - - * edebug.texi (Edebug Recursive Edit): Minor cleanup. - - * keymaps.texi (Format of Keymaps): Show all the keymap element - patterns that result from menu items. - (Key Lookup): Minor cleanups. - - * modes.texi (Precalculated Fontification): Don't say that - not setting font-lock-defaults avoids loading font-lock. - - * help.texi (Documentation): Move xref to Emacs Manual here. - (Documentation Basics): From here. - Also doc emacs-lisp-docstring-fill-column. - - * elisp.texi: Update version and ISBN. - - * commands.texi (Interactive Call): Clarify KEYS arg to - call-interactively is a vector. - (Command Loop Info): Delete anchor in this-command-keys. - Add anchor in this-command-keys-vector. - (Recursive Editing): Document how recursive-edit - handles the current buffer. - -2006-10-13 Chong Yidong <cyd@stupidchicken.com> - - * frames.texi (Frame Titles): %c and %l are ignored in - frame-title-format. - -2006-10-11 Richard Stallman <rms@gnu.org> - - * keymaps.texi (Key Sequences): Clarify use of kbd. - -2006-10-10 Kim F. Storm <storm@cua.dk> - - * lists.texi (Sets And Lists): Add memql. - -2006-10-03 Richard Stallman <rms@gnu.org> - - * searching.texi (Char Classes): Document :multibyte: and :unibyte:. - Clarify :ascii: and :nonascii:. - -2006-09-29 Juri Linkov <juri@jurta.org> - - * modes.texi (%-Constructs): Reorder coding systems in the - documentation of %z to the real order displayed in the modeline. - -2006-09-25 Richard Stallman <rms@gnu.org> - - * os.texi (Timers): Describe timer-max-repeats. - -2006-09-25 Chong Yidong <cyd@stupidchicken.com> - - * os.texi (Timers): Mention with-local-quit. - -2006-09-24 Richard Stallman <rms@gnu.org> - - * searching.texi (Searching and Matching): Mention property search. - - * commands.texi (Command Loop Info): Explain how read-event affects - this-command-keys. - -2006-09-20 Richard Stallman <rms@gnu.org> - - * os.texi (Timers): Clarify about REPEAT when timer is delayed. - - * windows.texi (Window Start): Minor cleanups. - -2006-09-20 Kim F. Storm <storm@cua.dk> - - * windows.texi (Window Start): pos-visible-in-window-p allows - specifying t for position to mean "end of window". - Add window-line-height. - - * anti.texi (Antinews): Mention window-line-height. - -2006-09-19 David Kastrup <dak@gnu.org> - - * keymaps.texi (Searching Keymaps): Small clarification. - -2006-09-18 Richard Stallman <rms@gnu.org> - - * keymaps.texi (Creating Keymaps): Explain that keymap prompt strings - cause keyboard menus. - (Menu Keymaps): Likewise. - (Defining Menus, Keyboard Menus): Clarify. - - * text.texi (Fields): Clarify explanation of constrain-to-field. - -2006-09-16 Eli Zaretskii <eliz@gnu.org> - - * variables.texi (Tips for Defining): Fix a typo. - -2006-09-15 Richard Stallman <rms@gnu.org> - - * keymaps.texi (Remapping Commands, Searching Keymaps) - (Active Keymaps): Clean up previous change. - -2006-09-15 Jay Belanger <belanger@truman.edu> - - * gpl.texi: Replace "Library Public License" by "Lesser Public - License" throughout. - -2006-09-15 David Kastrup <dak@gnu.org> - - * keymaps.texi (Active Keymaps): Adapt description to use - `get-char-property' instead `get-text-property'. Explain how - mouse events change this. Explain the new optional argument of - `key-binding' and its mouse-dependent lookup. - (Searching Keymaps): Adapt description similarly. - (Remapping Commands): Explain the new optional argument of - `command-remapping'. - -2006-09-14 Richard Stallman <rms@gnu.org> - - * keymaps.texi (Searching Keymaps): Clarification. - (Active Keymaps): Refer to Searching Keymaps instead of duplication. - -2006-09-13 Richard Stallman <rms@gnu.org> - - * objects.texi (Character Type): Node split. - Add xref to Describing Characters. - (Basic Char Syntax, General Escape Syntax) - (Ctl-Char Syntax, Meta-Char Syntax): New subnodes. - -2006-09-11 Richard Stallman <rms@gnu.org> - - * display.texi (Display Table Format): Wording clarification. - (Glyphs): Clarifications. - -2006-09-10 Chong Yidong <cyd@stupidchicken.com> - - * keymaps.texi (Active Keymaps): Mention that key-binding checks - local maps. - -2006-09-10 Kim F. Storm <storm@cua.dk> - - * display.texi (Forcing Redisplay): Document return value of - function redisplay. - -2006-09-09 Richard Stallman <rms@gnu.org> - - * windows.texi (Window Hooks): Explain limits of - window-scroll-functions. - - * display.texi (Fringe Indicators): Update for last change in - indicate-buffer-boundaries. - -2006-09-08 Richard Stallman <rms@gnu.org> - - * processes.texi (Bindat Spec): Suggest names ending in -bindat-spec. - -2006-09-06 Kim F. Storm <storm@cua.dk> - - * frames.texi (Display Feature Testing): display-mm-dimensions-alist. - - * windows.texi (Window Start): Update pos-visible-in-window-p. - -2006-09-04 Richard Stallman <rms@gnu.org> - - * processes.texi (Accepting Output): Explain SECONDS=0 for - accept-process-output. - - * os.texi (Idle Timers): Explain why timer functions should not - loop until (input-pending-p). - -2006-09-02 Eli Zaretskii <eliz@gnu.org> - - * makefile.w32-in (usermanualdir): New variable. - (elisp.dvi): Use it. - -2006-09-01 Eli Zaretskii <eliz@gnu.org> - - * buffers.texi (Buffer Modification): Fix last change. - -2006-09-01 Chong Yidong <cyd@stupidchicken.com> - - * buffers.texi (Buffer Modification): Document - buffer-chars-modified-tick. - -2006-08-31 Richard Stallman <rms@gnu.org> - - * modes.texi (Syntactic Font Lock): Mention specific faces once again. - -2006-08-31 Richard Bielawski <RBielawski@moneygram.com> (tiny change) - - * modes.texi (Syntactic Font Lock): - Mention font-lock-syntactic-face-function - instead of specific faces. - -2006-08-29 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Images): Add xrref to display-images-p. - -2006-08-28 Kenichi Handa <handa@m17n.org> - - * nonascii.texi (Lisp and Coding Systems): Fix description of - detect-coding-region. - -2006-08-27 Michael Olson <mwolson@gnu.org> - - * processes.texi (Transaction Queues): Remove stray quote - character. - -2006-08-25 Richard Stallman <rms@gnu.org> - - * os.texi (Idle Timers): run-with-idle-timer allows Lisp time value. - Add xref. - -2006-08-24 Chong Yidong <cyd@stupidchicken.com> - - * os.texi (Timers): Avoid waiting inside timers. - -2006-08-21 Lute Kamstra <lute@gnu.org> - - * Makefile.in: Use ../man/texinfo.tex to build elisp.dvi. - -2006-08-20 Richard Stallman <rms@gnu.org> - - * os.texi (Idle Timers): New node, split out from Timers. - Document current-idle-time. - * commands.texi (Reading One Event): Update xref. - * elisp.texi (Top): Update subnode menu. - -2006-08-16 Richard Stallman <rms@gnu.org> - - * keymaps.texi (Extended Menu Items): Show format of cached - bindings in extended menu items. - - * customize.texi (Variable Definitions): Explain when the - standard value expression is evaluated. - -2006-08-15 Chong Yidong <cyd@stupidchicken.com> - - * commands.texi (Reading One Event): Explain idleness in - `read-event'. - -2006-08-12 Chong Yidong <cyd@stupidchicken.com> - - * text.texi (Near Point): Say "cursor" not "terminal cursor". - (Commands for Insertion): Removed split-line since it's not - relevant for Lisp programming. - (Yank Commands): Rewrite introduction. - (Undo): Clarify. - (Maintaining Undo): Clarify. Document undo-ask-before-discard. - (Filling): Remove redundant comment. Clarify return value of - current-justification. - (Margins): Minor clarifications. - (Adaptive Fill): Update default value of adaptive-fill-regexp. - (Sorting): Update definition of sort-lines. - (Columns): Clarify behavior of sort-columns. - (Indent Tabs): Link to Tab Stops in Emacs manual. - (Special Properties): Clarify. - (Clickable Text): Mention Buttons package. - -2006-08-12 Kevin Ryde <user42@zip.com.au> - - * os.texi (Time Parsing): Add %z to description of - format-time-string, as per docstring. Add cross reference to - glibc manual for strftime. - -2006-08-08 Richard Stallman <rms@gnu.org> - - * modes.texi: Clean up wording in previous change. - -2006-08-07 Chong Yidong <cyd@stupidchicken.com> - - * modes.texi (Hooks): Clarify. - (Major Mode Basics): Mention define-derived-mode explicitly. - (Major Mode Conventions): Rebinding RET is OK for some modes. - Mention change-major-mode-hook and after-change-major-mode-hook. - (Example Major Modes): Moved to end of Modes section. - (Mode Line Basics): Clarify. - (Mode Line Data): Mention help-echo and local-map in strings. - Explain reason for treatment of non-risky variables. - (Properties in Mode): Clarify. - (Faces for Font Lock): Add font-lock-negation-char-face. - -2006-08-04 Eli Zaretskii <eliz@gnu.org> - - * strings.texi (Formatting Strings): Warn against arbitrary - strings as first arg to `format'. - -2006-07-31 Thien-Thi Nguyen <ttn@gnu.org> - - * text.texi (Clickable Text): Mention `help-echo' text property. - Update intro, examples and associated explanations. - -2006-07-31 Richard Stallman <rms@gnu.org> - - * commands.texi: Update xrefs. - (Event Mod): New node, cut out from old Translating Input. - - * maps.texi: Update xrefs. - - * keymaps.texi (Translation Keymaps): New node. - Update xrefs from Translating Input to Translation Keymaps. - - * elisp.texi (Top): Update subnode menu. - - * display.texi (Face Functions): Fix explanations of FRAME=t or nil. - - * os.texi (System Interface): Fix menu descriptions of some nodes. - (Translating Input): Node deleted. - -2006-07-31 Nick Roberts <nickrob@snap.net.nz> - - * modes.texi (Minor Mode Conventions): Update xref for add-to-list. - - * lists.texi (Sets And Lists): Likewise. - -2006-07-30 Thien-Thi Nguyen <ttn@gnu.org> - - * text.texi (Fields): Mention POS - requirement when narrowing is in effect. - -2006-07-28 Richard Stallman <rms@gnu.org> - - * display.texi (Face Attributes): Simplify wording. - (Attribute Functions): Clarify meaning of new-frame default - attribute settings. - - * customize.texi (Common Keywords): Document how to use - :package-version in a package not in Emacs. - -2006-07-28 Kim F. Storm <storm@cua.dk> - - * commands.texi (Reading One Event): Fix last change. - -2006-07-26 Chong Yidong <cyd@stupidchicken.com> - - * commands.texi (Reading One Event): Document SECONDS argument for - read-event, read-char, and read-char-exclusive. - -2006-07-25 Stefan Monnier <monnier@iro.umontreal.ca> - - * modes.texi (Multiline Font Lock): Can't use jit-lock-defer-multiline - to ensure correct identification. - -2006-07-24 Richard Stallman <rms@gnu.org> - - * text.texi (Clickable Text): Clarify. - - * sequences.texi (Vector Functions): Delete duplicate xref. - - * objects.texi (Function Type): Clarify. - - * modes.texi (Keymaps and Minor Modes): List punct chars for minor - modes. - - * lists.texi (List Variables): New node. - Material moved from other nodes. - - * variables.texi (Setting Variables): add-to-list and - add-to-ordered-list moved to List Variables node. - -2006-07-23 Thien-Thi Nguyen <ttn@gnu.org> - - * text.texi (Links and Mouse-1): - For mouse-on-link-p, expand on arg POS. - -2006-07-21 Kim F. Storm <storm@cua.dk> - - * display.texi (Forcing Redisplay): Don't mention systems which - don't support sub-second timers for redisplay-preemption-period. - - * os.texi (Terminal Output): Clarify text vs graphical terminal. - -2006-07-21 Eli Zaretskii <eliz@gnu.org> - - * frames.texi (Input Focus): Document that focus-follows-mouse has - no effect on MS-Windows. - -2006-07-18 Richard Stallman <rms@gnu.org> - - * display.texi (Forcing Redisplay): Cleanups in previous change. - - * processes.texi (Low-Level Network): Make menu more convenient. - -2006-07-18 Kim F. Storm <storm@cua.dk> - - * display.texi (Forcing Redisplay): redisplay-preemption-period - only used on window systems. Add xref to Terminal Output. - - * os.texi (Terminal Output): baud-rate only controls preemption on - non-window systems. Add xref to Forcing Redisplay. - - * processes.texi (Low-Level Network): Rename node "Make Network" - to "Network Processes". - -2006-07-18 Karl Berry <karl@gnu.org> - - * variables.texi, functions.texi, customize.texi, loading.texi: - * edebug.texi, minibuf.texi: Fix page breaks through chapter 20. - -2006-07-17 Chong Yidong <cyd@stupidchicken.com> - - * commands.texi (Waiting): Document batch-mode sit-for behavior. - -2006-07-17 Richard Stallman <rms@gnu.org> - - * eval.texi, elisp.texi, text.texi: Use real doublequote inside menus. - Put period and comma inside quotes. - - * loading.texi, markers.texi: Use real doublequote inside menus. - - * windows.texi: Put point and comma inside quotes. - (Textual Scrolling): Use @samp for error message. - - * variables.texi, tips.texi, syntax.texi, symbols.texi: - * strings.texi, streams.texi, processes.texi, os.texi: - * objects.texi, numbers.texi, modes.texi, minibuf.texi: - * lists.texi, keymaps.texi, intro.texi, hash.texi, internals.texi: - * gpl.texi, functions.texi, files.texi, frames.texi, doclicense.texi: - * display.texi, control.texi, commands.texi, buffers.texi, anti.texi: - Put point and comma inside quotes. - - * control.texi (Processing of Errors): Add command-error-function. - - * variables.texi (File Local Variables): Clarify that - file local variables make buffer-local bindings. - - * modes.texi (Syntactic Font Lock): Give default for - font-lock-syntax-table. - -2006-07-17 Nick Roberts <nickrob@snap.net.nz> - - * text.texi (Special Properties): Clean up previous change. - -2006-07-16 Karl Berry <karl@gnu.org> - - * objects.texi, numbers.texi, strings.texi, lists.texi, hash.texi: - * control.texi: Fix bad page breaks through chapter 10 (control). - - * anti.texi (Antinews): Reorder face-attribute fns to avoid - underfull hbox. - -2006-07-15 Nick Roberts <nickrob@snap.net.nz> - - * text.texi (Special Properties): Describe fontified text property - in relation to a character (not text). - -2006-07-15 Kim F. Storm <storm@cua.dk> - - * maps.texi (Standard Keymaps): Add xref for minibuffer maps. - Add apropos-mode-map, custom-mode-map, esc-map, global-map, - grep-mode-map, help-map, help-mode-map, kmacro-map, and tool-bar-map. - - * anti.texi (Antinews): Mention redisplay function. - The kbd macro existed, but was not documented, before 22.x. - Function pos-visible-in-window-p is not new in 22.x, just enhanced. - -2006-07-14 Nick Roberts <nickrob@snap.net.nz> - - * display.texi (Displaying Messages): Add anchor. - - * frames.texi (Dialog Boxes): Use it. - -2006-07-12 Richard Stallman <rms@gnu.org> - - * objects.texi (Frame Type): Explain nature of frames better. - - * frames.texi (Frames): Explain nature of frames better. - -2006-07-12 Ken Manheimer <ken.manheimer@gmail.com> - - * tips.texi (Coding Conventions): Explain why use cl at compile time. - -2006-07-12 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> - - * frames.texi (Window System Selections): Mention scrap support for Mac. - Default value of x-select-enable-clipboard is t on Mac. - - * os.texi (Getting Out): Suspending is not allowed on Mac, either. - -2006-07-11 Kim F. Storm <storm@cua.dk> - - * display.texi (Forcing Redisplay): Add `redisplay' function. - Don't mention (sit-for -1) -- use (redisplay t) instead. - - * commands.texi (Waiting): (sit-for -1) is no longer special. - (sit-for 0) is equivalent to (redisplay). - Iconifying/deiconifying no longer makes sit-for return. - -2006-07-10 Nick Roberts <nickrob@snap.net.nz> - - * display.texi (Buttons): Fix typo. - - * index.texi, elisp.texi (New Symbols): Comment node out. - -2006-07-09 Richard Stallman <rms@gnu.org> - - * display.texi (Truncation): Clean up previous change. - -2006-07-08 Richard Stallman <rms@gnu.org> - - * commands.texi (Interactive Call): Use 3 as prefix in example - for execute-extended-command. - - * display.texi (Attribute Functions): Move paragraph about - compatibility with Emacs < 21. - -2006-07-09 Kim F. Storm <storm@cua.dk> - - * display.texi (Refresh Screen): Clarify force-window-update. - (Truncation): "Normally" indicated by fringe arrows. - -2006-07-08 Eli Zaretskii <eliz@gnu.org> - - * windows.texi (Textual Scrolling, Resizing Windows): - * variables.texi (Constant Variables): - * text.texi (Buffer Contents, Deletion, Changing Properties) - (Property Search, Special Properties, Sticky Properties) - (Links and Mouse-1, Fields, Change Hooks): - * syntax.texi (Syntax Table Functions, Parsing Expressions) - (Categories): - * symbols.texi (Other Plists): - * streams.texi (Output Variables): - * processes.texi (Input to Processes, Query Before Exit): - * positions.texi (Word Motion, Text Lines, List Motion): - * os.texi (Init File, System Environment, Sound Output) - (Session Management): - * nonascii.texi (Text Representations, Character Sets) - (Chars and Bytes, Locales): - * modes.texi (Defining Minor Modes, Header Lines): - * minibuf.texi (Minibuffer Contents): - * markers.texi (Information from Markers): - * lists.texi (List Elements, Building Lists, Association Lists): - * keymaps.texi (Tool Bar): - * hash.texi (Creating Hash, Hash Access, Defining Hash, Other Hash): - * functions.texi (What Is a Function, Mapping Functions): - * frames.texi (Creating Frames, Parameter Access, Pointer Shape) - (Color Names, Text Terminal Colors, Display Feature Testing): - * files.texi (Visiting Functions, File Name Components) - (Unique File Names, Contents of Directories): - * display.texi (Forcing Redisplay, Displaying Messages) - (Temporary Displays, Font Selection, Auto Faces) - (Font Lookup, Fringe Indicators, Display Margins) - (Image Descriptors, Showing Images, Image Cache, Button Types) - (Making Buttons, Manipulating Buttons, Button Buffer Commands) - (Display Table Format, Glyphs): - * control.texi (Iteration): - * commands.texi (Command Loop Info, Adjusting Point): - * backups.texi (Making Backups, Auto-Saving): - Remove @tindex entries. - -2006-07-07 Kim F. Storm <storm@cua.dk> - - * display.texi (Fringe Cursors): Fix typo. - (Customizing Bitmaps): Fix define-fringe-bitmap entry. - (Overlay Arrow): Default is overlay-arrow fringe indicator. - -2006-07-05 Richard Stallman <rms@gnu.org> - - * text.texi (Buffer Contents): Add example of text props - in result of buffer-substring. - (Text Properties): Explain better about use of specific property names. - (Property Search): Some cleanups; reorder some functions. - - * keymaps.texi (Changing Key Bindings): Cleanup. - Add xref to Key Binding Conventions. - - * display.texi (Attribute Functions): Add examples for - face-attribute-relative-p. - - * tips.texi (Coding Conventions): Cleanup last change. - -2006-07-05 Karl Berry <karl@gnu.org> - - * elisp.texi: Use @fonttextsize 10pt, a la emacs.texi. - Remove @setchapternewpage odd. - Result is 1013 pages, down from 1100. - - * anti.texi, customize.texi, display.texi, internals.texi: - * minibuf.texi, modes.texi, tips.texi: - Fix overfull/underfull boxes. - -2006-07-05 Thien-Thi Nguyen <ttn@gnu.org> - - * edebug.texi (Instrumenting): - Add Edebug-specific findex for eval-buffer. - * loading.texi (Loading): - Replace eval-current-buffer with eval-buffer. - -2006-06-30 Nick Roberts <nickrob@snap.net.nz> - - * locals.texi (Standard Buffer-Local Variables): Update the list - of variables. - -2006-06-26 Nick Roberts <nickrob@snap.net.nz> - - * files.texi (File Name Completion): Point user to the node - "Reading File Names". - -2006-06-24 Eli Zaretskii <eliz@gnu.org> - - * files.texi (Contents of Directories): Document case-insensitive - behavior on respective filesystems. - - * objects.texi (Character Type): Document that Emacs signals an - error for unsupported Unicode characters specified as \uNNNN. - -2006-06-19 Richard Stallman <rms@gnu.org> - - * processes.texi (Bindat Spec): Clarify previous change. - -2006-06-16 Richard Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Better explain conventions - for definition constructs. - - * text.texi (Special Properties): String value of `read-only' - serves as the error message. - - * objects.texi (Character Type): Clarify prev. change. - (Non-ASCII in Strings): Mention \u and \U. - - * commands.texi (Using Interactive): Explain problem of - markers, etc., in command-history. - -2006-06-14 Kim F. Storm <storm@cua.dk> - - * commands.texi (Waiting): Negative arg to sit-for forces - redisplay even if input is pending. - - * display.texi (Forcing Redisplay): Use (sit-for -1) to force a - redisplay. Remove incorrect example of binding redisplay-dont-pause - around (sit-for 0). - -2006-06-13 Richard Stallman <rms@gnu.org> - - * display.texi (Forcing Redisplay): Clarify previous change. - -2006-06-13 Romain Francoise <romain@orebokech.com> - - * display.texi (Forcing Redisplay): Fix typo. - -2006-06-13 Kim F. Storm <storm@cua.dk> - - * display.texi (Forcing Redisplay): Add redisplay-preemption-period. - -2006-06-10 Luc Teirlinck <teirllm@auburn.edu> - - * tips.texi (Coding Conventions): Add `@end itemize'. - -2006-06-10 Richard Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Explain use of coding systems - to ensure one decoding for strings. - -2006-06-09 Aidan Kehoe <kehoea@parhasard.net> - - * objects.texi (Character Type): Describe the \uABCD and \U00ABCDEF - syntax. - -2006-06-07 Eli Zaretskii <eliz@gnu.org> - - * display.texi (Font Selection): Remove description of - clear-face-cache. - - * compile.texi (Eval During Compile): Fix a typo. Add index - entries for possible uses of eval-when-compile. - -2006-06-04 Thien-Thi Nguyen <ttn@gnu.org> - - * display.texi (Abstract Display): Fix typo. - -2006-06-03 Eli Zaretskii <eliz@gnu.org> - - * minibuf.texi (Minibuffer History) <history-add-new-input>: - Reword variable's description. - -2006-06-01 Richard Stallman <rms@gnu.org> - - * windows.texi (Splitting Windows): Clarify splitting nonselected - window. - -2006-05-31 Juri Linkov <juri@jurta.org> - - * minibuf.texi (Minibuffer History): Add history-add-new-input. - -2006-05-30 Richard Stallman <rms@gnu.org> - - * display.texi (Line Height): Fix errors in description of - default line height and line-height properyty. - - * nonascii.texi (Default Coding Systems): Further clarification. - -2006-05-29 Luc Teirlinck <teirllm@auburn.edu> - - * internals.texi (Pure Storage): Mention that an overflow in pure - space causes a memory leak. - (Garbage Collection): If there was an overflow in pure space, - `garbage-collect' returns nil. - -2006-05-30 Eli Zaretskii <eliz@gnu.org> - - * nonascii.texi (Default Coding Systems): Fix it some more. - -2006-05-29 Eli Zaretskii <eliz@gnu.org> - - * nonascii.texi (Default Coding Systems): Fix last change. - -2006-05-29 Kenichi Handa <handa@m17n.org> - - * nonascii.texi (find-operation-coding-system): Describe the new - argument format (FILENAME . BUFFER). - -2006-05-28 Richard Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Better explain reasons not to - advise other packages or use `eval-after-load'. - -2006-05-29 Kim F. Storm <storm@cua.dk> - - * processes.texi (Bindat Functions): Rename `pos' and `raw-data' to - `bindat-idx' and `bindat-raw' for clarity. - -2006-05-27 Thien-Thi Nguyen <ttn@gnu.org> - - * processes.texi (Bindat Spec): Expand on `repeat' handler. - - * display.texi (Display): Add "Abstract Display" to menu. - (Abstract Display, Abstract Display Functions) - (Abstract Display Example): New nodes. - * elisp.texi (Top): Add "Abstract Display" to menu. - -2006-05-27 Chong Yidong <cyd@stupidchicken.com> - - * keymaps.texi (Key Sequences): Link to input events definition. - (Format of Keymaps): Delete material duplicated in Keymap Basics. - - * files.texi (Changing Files): Document updated argument list for - copy-file. - -2006-05-27 Thien-Thi Nguyen <ttn@gnu.org> - - * processes.texi (Bindat Functions): Explain term "total length". - Use it in bindat-length and bindat-pack descriptions. - -2006-05-26 Eli Zaretskii <eliz@gnu.org> - - * tips.texi (Coding Conventions): Advise against using - eval-after-load in packages. Add an index entry. - -2006-05-25 Juri Linkov <juri@jurta.org> - - * minibuf.texi (Text from Minibuffer): Undocument keep-all. - - * modes.texi (%-Constructs): Add %e, %z, %Z. - -2006-05-25 Richard Stallman <rms@gnu.org> - - * elisp.texi (Top): Update subnode menu. - - * keymaps.texi (Keymap Basics): New node, split out of Key Sequences. - (Keymaps): Update menu. - -2006-05-25 Chong Yidong <cyd@stupidchicken.com> - - * keymaps.texi (Key Sequences): Some clarifications. - -2006-05-25 Thien-Thi Nguyen <ttn@gnu.org> - - * processes.texi (Bindat Functions): Say "unibyte string" - explicitly for bindat-unpack and bindat-pack descriptions. - (Bindat Examples): Don't call `string-make-unibyte' in example. - -2006-05-25 Chong Yidong <cyd@stupidchicken.com> - - * keymaps.texi (Key Sequences): Renamed from Keymap Terminology. - Explain string and vector representations of key sequences - - * keymaps.texi (Changing Key Bindings): - * commands.texi (Interactive Codes, Interactive Codes): - * help.texi (Describing Characters): Refer to it. - -2006-05-23 Luc Teirlinck <teirllm@auburn.edu> - - * frames.texi (Pointer Shape): @end table -> @end defvar. - -2006-05-22 Richard Stallman <rms@gnu.org> - - * elisp.texi (Top): Update subnode menus. - - * frames.texi (Pointer Shape): Node renamed from Pointer Shapes. - Contents rewritten; material from old Pointer Shape node moved here. - - * display.texi (Pointer Shape): Node deleted. - (Image Descriptors): Minor cleanup. - -2006-05-21 Richard Stallman <rms@gnu.org> - - * syntax.texi (Parsing Expressions): Update info on which STATE - elements are ignored. - -2006-05-19 Luc Teirlinck <teirllm@auburn.edu> - - * hooks.texi (Standard Hooks): Correct typo. - - * gpl.texi (GPL): ifinfo -> ifnottex. - -2006-05-19 Michael Ernst <mernst@alum.mit.edu> (tiny change) - - * searching.texi (Simple Match Data): Warn about match data being - set anew by every search. - -2006-05-17 Richard Stallman <rms@gnu.org> - - * minibuf.texi (Minibuffer History): Clarify. - - * searching.texi (Regexp Special): Clarify nested regexp warning. - -2006-05-16 Kim F. Storm <storm@cua.dk> - - * minibuf.texi (Minibuffer History): Update add-to-history. - -2006-05-15 Oliver Scholz <epameinondas@gmx.de> (tiny change) - - * nonascii.texi (Explicit Encoding): Fix - typo (encoding<->decoding). - -2006-05-14 Richard Stallman <rms@gnu.org> - - * buffers.texi (Creating Buffers): Cleanup. - - * files.texi (Visiting Functions): Rewrite in find-file-noselect. - -2006-05-13 Eli Zaretskii <eliz@gnu.org> - - * buffers.texi (Current Buffer): Document that with-temp-buffer - disables undo. - - * os.texi (Terminal-Specific): More accurate description of how - Emacs searches for the terminal-specific libraries. - -2006-05-12 Eli Zaretskii <eliz@gnu.org> - - * hooks.texi (Standard Hooks) [iftex]: Convert @xref's to - emacs-xtra to @inforef's. - - * text.texi (Undo): Document that undo is turned off in buffers - whose names begin with a space. - - * buffers.texi (Buffer Names): Add index entries for buffers whose - names begin with a space. - (Creating Buffers): Document that undo is turned off in buffers - whose names begin with a space. - - * files.texi (Visiting Functions, Reading from Files) - (Saving Buffers): Mention code and EOL conversions by file I/O - primitives and subroutines. - - * nonascii.texi (Lisp and Coding Systems): Document - coding-system-eol-type. Add index entries for eol conversion. - - * display.texi (Defining Faces): Mention `mac', and add an xref to - where window-system is described. - -2006-05-10 Richard Stallman <rms@gnu.org> - - * internals.texi (Writing Emacs Primitives): Clarify GCPRO rules. - -2006-05-10 Reiner Steib <Reiner.Steib@gmx.de> - - * variables.texi (File Local Variables): Recommend to quote lambda - expressions in safe-local-variable property. - -2006-05-09 Richard Stallman <rms@gnu.org> - - * variables.texi (File Local Variables): Document - safe-local-eval-forms and safe-local-eval-function. - -2006-05-07 Kim F. Storm <storm@cua.dk> - - * minibuf.texi (Minibuffer History): Remove keep-dups arg - from add-to-history. - -2006-05-07 Romain Francoise <romain@orebokech.com> - - * commands.texi (Event Input Misc): - * compile.texi (Eval During Compile): - * internals.texi (Buffer Internals): - * minibuf.texi (Initial Input): - * nonascii.texi (Scanning Charsets): - * numbers.texi (Comparison of Numbers): - * windows.texi (Textual Scrolling, Vertical Scrolling): - Fix various typos. - -2006-05-06 Eli Zaretskii <eliz@gnu.org> - - * hooks.texi (Standard Hooks): Replace inforef to emacs-xtra by - conditional xref's to either emacs or emacs-xtra, depending on - @iftex/@ifnottex. - - * minibuf.texi (Minibuffer History): Document add-to-history. - -2006-05-05 Eli Zaretskii <eliz@gnu.org> - - * internals.texi (Pure Storage): Mention the pure overflow message - at startup. - -2006-05-05 Johan Bockg,Ae(Brd <bojohan@dd.chalmers.se> - - * keymaps.texi (Active Keymaps): Fix pseudo-Lisp syntax. - (Searching Keymaps): Fix pseudo-Lisp description of keymap - search. - -2006-05-01 Richard Stallman <rms@gnu.org> - - * intro.texi (nil and t): Clarify. - - * variables.texi (File Local Variables): Suggest using booleanp. - -2006-05-01 Juanma Barranquero <lekktu@gmail.com> - - * objects.texi (Type Predicates): Fix typos. - -2006-05-01 Stefan Monnier <monnier@iro.umontreal.ca> - - * intro.texi (nil and t): Add booleanp. - - * objects.texi (Type Predicates): Add links for booleanp and - string-or-null-p. - -2006-04-29 Richard Stallman <rms@gnu.org> - - * modes.texi (Multiline Font Lock): Rename from - Multi line Font Lock Elements. Much clarification. - (Font Lock Multiline, Region to Fontify): Much clarification. - -2006-04-29 Stefan Monnier <monnier@iro.umontreal.ca> - - * variables.texi (File Local Variables): Remove the special case t for - safe-local-variable. - -2006-04-26 Richard Stallman <rms@gnu.org> - - * syntax.texi (Parsing Expressions): Minor cleanup. - -2006-04-18 Richard Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Explain when the package's - prefix should appear later on (not at the start of the name). - - * searching.texi (String Search): Clarify effect of NOERROR. - - * modes.texi (Imenu): Clarify what special items do. - - * hooks.texi (Standard Hooks): Delete text about old hook names. - -2006-04-17 Romain Francoise <romain@orebokech.com> - - * variables.texi (Local Variables): Update the default value of - `max-specpdl-size'. - -2006-04-15 Michael Olson <mwolson@gnu.org> - - * processes.texi (Transaction Queues): Mention the new optional - `delay-question' argument for `tq-enqueue'. - -2006-04-13 Bill Wohler <wohler@newt.com> - - * customize.texi (Common Keywords): Use dotted notation for - :package-version value. Specify its values. Improve documentation - for customize-package-emacs-version-alist. - -2006-04-12 Bill Wohler <wohler@newt.com> - - * customize.texi (Common Keywords): Move description of - customize-package-emacs-version-alist to @defvar. - -2006-04-10 Bill Wohler <wohler@newt.com> - - * customize.texi (Common Keywords): Add :package-version. - -2006-04-10 Kim F. Storm <storm@cua.dk> - - * text.texi (Buffer Contents): Add NOPROPS arg to - filter-buffer-substring. - -2006-04-08 Kevin Ryde <user42@zip.com.au> - - * os.texi (Command-Line Arguments): Update xref to emacs manual - "Command Arguments" -> "Emacs Invocation", per change there. - -2006-04-08 Thien-Thi Nguyen <ttn@gnu.org> - - * display.texi (Other Display Specs): Arrange a @code{DOTTED-LIST} to - be on one line to help makeinfo not render two spaces after the dot. - -2006-04-07 Reiner Steib <Reiner.Steib@gmx.de> - - * strings.texi (Predicates for Strings): Add string-or-null-p. - -2006-03-28 Kim F. Storm <storm@cua.dk> - - * processes.texi (Accepting Output): Remove obsolete (and incorrect) - remarks about systems that don't support fractional seconds. - -2006-03-25 Karl Berry <karl@gnu.org> - - * elisp.texi: Use @copyright{} instead of (C), and do not indent - the year list. - -2006-03-21 Nick Roberts <nickrob@snap.net.nz> - - * display.texi (Fringe Indicators): Fix typos. - -2006-03-19 Luc Teirlinck <teirllm@auburn.edu> - - * tips.texi (Documentation Tips): One can now also write `program' - in front of a quoted symbol in a docstring to prevent making a - hyperlink. - -2006-03-19 Alan Mackenzie <acm@muc.de> - - * text.texi (Special Properties): Clarify `fontified' property. - -2006-03-16 Richard Stallman <rms@gnu.org> - - * display.texi (Defining Images): Minor cleanup. - -2006-03-16 Bill Wohler <wohler@newt.com> - - * display.texi (Defining Images): In image-load-path-for-library, - prefer user's images. - -2006-03-15 Stefan Monnier <monnier@iro.umontreal.ca> - - * modes.texi (Region to Fontify): Remove font-lock-lines-before. - -2006-03-15 Bill Wohler <wohler@newt.com> - - * display.texi (Defining Images): Fix example in - image-load-path-for-library by not recommending that one binds - image-load-path. Just defvar it to placate compiler and only use - it if previously defined. - -2006-03-14 Bill Wohler <wohler@newt.com> - - * display.texi (Defining Images): In image-load-path-for-library, - always return list of directories. Update example. - -2006-03-14 Alan Mackenzie <acm@muc.de> - - * modes.texi: New node, "Region to Fontify" (for Font Lock). - This describes font-lock-extend-region-function. - ("Other Font Lock Variables"): Move "font-lock-lines-before" to - the new node "Region to Fontify". - -2006-03-13 Richard Stallman <rms@gnu.org> - - * display.texi (Invisible Text): The impossible position is - now before the invisible text, not after. - (Defining Images): Clean up last change. - -2006-03-11 Bill Wohler <wohler@newt.com> - - * display.texi (Defining Images): Add image-load-path-for-library. - -2006-03-11 Luc Teirlinck <teirllm@auburn.edu> - - * text.texi (Adaptive Fill): Fix Texinfo usage. - - * strings.texi (Creating Strings): Fix Texinfo usage. - - * searching.texi (Regexp Special): Use @samp for regular - expressions that are not in Lisp syntax. - -2006-03-08 Luc Teirlinck <teirllm@auburn.edu> - - * searching.texi (Regexp Special): Put remark between parentheses - to avoid misreading. - -2006-03-07 Luc Teirlinck <teirllm@auburn.edu> - - * searching.texi (Syntax of Regexps): More accurately describe - which characters are special in which situations. - (Regexp Special): Recommend _not_ to quote `]' or `-' when they - are not special. Describe in detail when `[' and `]' are special. - (Regexp Backslash): Plenty of regexps with unbalanced square - brackets are valid, so reword that statement. - -2006-03-02 Kim F. Storm <storm@cua.dk> - - * keymaps.texi (Tool Bar): Add tool-bar-border. - -2006-02-28 Luc Teirlinck <teirllm@auburn.edu> - - * loading.texi (Load Suffixes): Rephrase last paragraph. Fix typos. - -2006-02-27 Luc Teirlinck <teirllm@auburn.edu> - - * elisp.texi (Top): Include "Load Suffixes" in the detailed menu. - - * files.texi (Locating Files): Suggest additional values for the - SUFFIXES arg of `locate-file'. Update pxref. - - * loading.texi (Loading): Include new node "Load Suffixes" in menu. - (How Programs Do Loading): Discuss the effects of Auto Compression - mode on `load'. - (Load Suffixes): New node. - (Library Search): Delete description of `load-suffixes'; it was - moved to "Load Suffixes". - (Autoload, Named Features): Mention `load-suffixes'. - -2006-02-21 Giorgos Keramidas <keramida@ceid.upatras.gr> (tiny change) - - * display.texi (Fringe Indicators, Fringe Cursors): Fix typos. - - * windows.texi (Window Tree): Fix typo. - -2006-02-20 Kim F. Storm <storm@cua.dk> - - * display.texi (Fringe Indicators): New section. - Move indicate-empty-lines, indicate-buffer-boundaries, and - default-indicate-buffer-boundaries here. - Add fringe-indicator-alist and default-fringes-indicator-alist. - Add list of logical fringe indicator symbols. - Update list of standard bitmap names. - (Fringe Cursors): New section. - Move overflow-newline-into-fringe here. - Add fringe-cursor-alist and default-fringes-cursor-alist. - Add list of fringe cursor symbols. - -2006-02-20 Juanma Barranquero <lekktu@gmail.com> - - * commands.texi (Using Interactive): Fix reference to node - "Minibuffers". - -2006-02-19 Richard M. Stallman <rms@gnu.org> - - * minibuf.texi (High-Level Completion): - Add xref to read-input-method-name. - - * files.texi (Relative File Names): Move file-relative-name here. - (File Name Expansion): From here. Minor clarifications. - - * commands.texi (Using Interactive): Add xrefs about reading input. - Clarify remarks about that moving point and mark. - Put string case before list case. - -2006-02-16 Johan Bockg,Ae(Brd <bojohan@dd.chalmers.se> - - * display.texi (Other Display Specs, Image Descriptors): - Revert erroneous changes. The previous description of - image-descriptors as `(image . PROPS)' was correct. - -2006-02-14 Richard M. Stallman <rms@gnu.org> - - * variables.texi (File Local Variables): Clarifications. - -2006-02-14 Juanma Barranquero <lekktu@gmail.com> - - * variables.texi (File Local Variables): Use @code for a cons - cell, not @var. - -2006-02-13 Chong Yidong <cyd@stupidchicken.com> - - * variables.texi (File Local Variables): Document new file local - variable behavior. - -2006-02-10 Kim F. Storm <storm@cua.dk> - - * eval.texi (Function Indirection): Add NOERROR to indirect-function. - -2006-02-08 Juanma Barranquero <lekktu@gmail.com> - - * modes.texi (%-Constructs): Remove obsolete info about - `global-mode-string'. - -2006-02-07 Richard M. Stallman <rms@gnu.org> - - * commands.texi (Prefix Command Arguments): Minor cleanup. - - * display.texi: "Graphical display", not window system. - - * functions.texi (What Is a Function): Fix xref. - - * keymaps.texi (Key Lookup): Clarify wrt commands vs other functions. - (Changing Key Bindings): Clarify when remapping is better than - substitute-key-definition. - -2006-02-02 Richard M. Stallman <rms@gnu.org> - - * minibuf.texi (Basic Completion): Completion alists are risky. - - * keymaps.texi (Active Keymaps): Clarifications. - (Searching Keymaps): New node. - (Keymaps): Update menu. - - * frames.texi (Layout Parameters): Minor clarification. - (Drag and Drop): New node. - (Frames): Update menu. - -2006-01-29 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Other Display Specs, Image Descriptors): - Image description is a list, not a cons cell. - -2006-01-28 Luc Teirlinck <teirllm@auburn.edu> - - * lists.texi (Cons Cells): Minor correction (the cdr of a dotted - list is not necessarily a list). - -2006-01-27 Eli Zaretskii <eliz@gnu.org> - - * frames.texi (Layout Parameters): border-width and - internal-border-width belong to the frame, not the window. - -2006-01-19 Richard M. Stallman <rms@gnu.org> - - * nonascii.texi (Translation of Characters): Search cmds use - translation-table-for-input. Automatically made local. - - * markers.texi (Overview of Markers): Count insertion type - as one of a marker's attributes. - - * keymaps.texi (Controlling Active Maps): New node, split out of - Active Keymaps. - (Keymaps): Menu updated. - (Active Keymaps): Give pseudocode to explain how the active - maps are searched. current-active-maps and key-binding moved here. - (Functions for Key Lookup): current-active-maps and key-binding moved. - Clarifications. - (Searching the Keymaps): New subnode. - - * elisp.texi (Top): Menu clarification. - - * display.texi (Other Display Specs): Delete duplicate entry for - just a string as display spec. Move text about recursive display - specs on such a string. - - * commands.texi (Key Sequence Input): Clarify. - Move num-nonmacro-input-events out. - (Reading One Event): num-nonmacro-input-events moved here. - -2006-01-14 Nick Roberts <nickrob@snap.net.nz> - - * advice.texi (Simple Advice): Update example to fit argument - change in previous-line. - -2006-01-05 Richard M. Stallman <rms@gnu.org> - - * markers.texi (The Mark): Fix in `mark'. - -2006-01-04 Richard M. Stallman <rms@gnu.org> - - * processes.texi (Misc Network, Make Network): Minor cleanups. - -2006-01-04 Kim F. Storm <storm@cua.dk> - - * processes.texi (Make Network): Add IPv6 addresses and handling. - (Network Feature Testing): Mention (:family ipv6). - (Misc Network): Add IPv6 formats to format-network-address. - -2005-12-30 Richard M. Stallman <rms@gnu.org> - - * text.texi (Changing Properties): - Don't use return value of set-text-properties. - -2005-12-29 Luc Teirlinck <teirllm@auburn.edu> - - * modes.texi (Mode Line Format): Correct typo in menu. - -2005-12-29 Richard M. Stallman <rms@gnu.org> - - * modes.texi (Mode Line Top): New node. - (Mode Line Data): Some text moved to new node. - Explain the data structure more concretely. - (Mode Line Basics): Clarifications. - (Mode Line Variables): Clarify intro paragraph. - (%-Constructs): Clarify intro paragraph. - (Mode Line Format): Update menu. - -2005-12-28 Luc Teirlinck <teirllm@auburn.edu> - - * minibuf.texi (Basic Completion): Update lazy-completion-table - examples for removal of ARGS argument. - -2005-12-23 Richard M. Stallman <rms@gnu.org> - - * text.texi (Undo): Restore some explanation from the version - that was deleted. - -2005-12-23 Eli Zaretskii <eliz@gnu.org> - - * text.texi (Undo): Remove duplicate descriptions of `apply - funname' and `apply delta' elements of the undo list. - -2005-12-20 Richard M. Stallman <rms@gnu.org> - - * help.texi (Help Functions): Update documentation of `apropos'. - -2005-12-20 Luc Teirlinck <teirllm@auburn.edu> - - * customize.texi (Type Keywords): Delete xref to "Text help-echo", - because it is confusing. If the :help-echo keyword is a function, - it is not directly used as the :help-echo overlay property, as the - xref seems to suggest (it does not take the appropriate args). - -2005-12-19 Luc Teirlinck <teirllm@auburn.edu> - - * customize.texi (Common Keywords): Fix Texinfo usage. - (Group Definitions, Variable Definitions): Update for new - conventions for using `*' in docstrings. - - * tips.texi (Documentation Tips): Update for new conventions for - using `*' in docstrings. - -2005-12-16 Richard M. Stallman <rms@gnu.org> - - * minibuf.texi (Minibuffer Contents): Minor cleanup. - -2005-12-16 Juri Linkov <juri@jurta.org> - - * minibuf.texi (Minibuffer Contents): Add minibuffer-completion-contents. - -2005-12-14 Romain Francoise <romain@orebokech.com> - - * modes.texi (Customizing Keywords): Rename `append' to `how'. - Fix typo. - -2005-12-11 Juri Linkov <juri@jurta.org> - - * minibuf.texi (Completion Commands): Add mention of read-file-name - for filename completion keymaps. - (Reading File Names): Add mention of filename completion keymaps - for read-file-name and xref to `Completion Commands'. - -2005-12-10 Richard M. Stallman <rms@gnu.org> - - * customize.texi (Common Keywords): State caveats for use of :tag. - -2005-12-08 Richard M. Stallman <rms@gnu.org> - - * minibuf.texi (Intro to Minibuffers): Replace list of local maps - with xrefs and better explanation. - (Completion Commands): Add the filename completion maps. - - * objects.texi (Character Type): Clarify that \s is not space - if a dash follows. - -2005-12-05 Richard M. Stallman <rms@gnu.org> - - * windows.texi (Resizing Windows): Delete preserve-before args. - -2005-12-05 Stefan Monnier <monnier@iro.umontreal.ca> - - * keymaps.texi (Format of Keymaps): Remove mention of a quirk - in full keymaps, since the quirk has been fixed. - -2005-12-03 Eli Zaretskii <eliz@gnu.org> - - * hooks.texi (Standard Hooks): Add index entries. Mention - `compilation-finish-functions'. - -2005-11-27 Richard M. Stallman <rms@gnu.org> - - * windows.texi (Resizing Windows): Add adjust-window-trailing-edge. - -2005-11-21 Juri Linkov <juri@jurta.org> - - * customize.texi (Common Keywords): Update links types - custom-manual and url-link. Add link types emacs-library-link, - file-link, function-link, variable-link, custom-group-link. - -2005-11-20 Chong Yidong <cyd@stupidchicken.com> - - * display.texi: Revert 2005-11-20 change. - -2005-11-20 Thien-Thi Nguyen <ttn@gnu.org> - - * processes.texi (Bindat Functions): - Say "third" to refer to zero-based index "2". - -2005-11-18 Luc Teirlinck <teirllm@auburn.edu> - - * loading.texi (Library Search): Update the default value of - `load-suffixes'. - -2005-11-17 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Attribute Functions): Mention :ignore-defface. - -2005-11-16 Stefan Monnier <monnier@iro.umontreal.ca> - - * modes.texi (Minor Mode Conventions): Use custom-set-minor-mode. - (Minor Mode Conventions): Mention the use of a hook. - -2005-11-06 Richard M. Stallman <rms@gnu.org> - - * files.texi (Magic File Names): find-file-name-handler checks the - `operations' property of the handler. - -2005-11-03 Richard M. Stallman <rms@gnu.org> - - * variables.texi (Frame-Local Variables): Small clarification. - -2005-10-29 Chong Yidong <cyd@stupidchicken.com> - - * os.texi (Init File): Document ~/.emacs.d/init.el. - -2005-10-29 Richard M. Stallman <rms@gnu.org> - - * internals.texi (Garbage Collection): Document memory-full. - -2005-10-28 Bill Wohler <wohler@newt.com> - - * tips.texi (Documentation Tips): Help mode now creates hyperlinks - for URLs. - -2005-10-28 Richard M. Stallman <rms@gnu.org> - - * minibuf.texi (Completion Commands): Clean up prev change. - -2005-10-26 Kevin Ryde <user42@zip.com.au> - - * compile.texi (Eval During Compile): Explain recommended uses - of eval-when-compile and eval-and-compile. - -2005-10-27 Masatake YAMATO <jet@gyve.org> - - * minibuf.texi (Completion Commands): - Write about new optional argument for `display-completion-list'. - -2005-10-23 Richard M. Stallman <rms@gnu.org> - - * display.texi (Overlay Arrow): Clarify about local bindings of - overlay-arrow-position. - -2005-10-22 Eli Zaretskii <eliz@gnu.org> - - * internals.texi (Building Emacs): Fix last change. - -2005-10-22 Richard M. Stallman <rms@gnu.org> - - * internals.texi (Building Emacs): Document eval-at-startup. - -2005-10-21 Richard M. Stallman <rms@gnu.org> - - * loading.texi (Where Defined): load-history contains abs file names. - symbol-file returns abs file names. - -2005-10-19 Kim F. Storm <storm@cua.dk> - - * display.texi (Showing Images): Add max-image-size integer value. - -2005-10-18 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Showing Images): Document max-image-size. - -2005-10-17 Richard M. Stallman <rms@gnu.org> - - * commands.texi (Quitting): Minor clarification. - - * processes.texi (Sentinels): Clarify about output and quitting. - (Filter Functions): Mention with-local-quit. - -2005-10-17 Juri Linkov <juri@jurta.org> - - * buffers.texi (Current Buffer): - * commands.texi (Event Input Misc): - * compile.texi (Eval During Compile, Compiler Errors): - * customize.texi (Group Definitions): - * display.texi (Progress, Defining Faces): - * files.texi (Writing to Files): - * modes.texi (Mode Hooks, Defining Minor Modes): - * streams.texi (Output Functions): - * syntax.texi (Syntax Table Functions): - * text.texi (Change Hooks): - Replace `...' with `@dots{}' in `@defmac' and `@defspec'. - - * commands.texi (Quitting): Replace arg `forms' with `body' in - `with-local-quit'. - - * positions.texi (Excursions): Replace arg `forms' with `body' in - `save-excursion'. - -2005-10-08 Kim F. Storm <storm@cua.dk> - - * windows.texi (Window Tree): Rename window-split-tree to window-tree. - Rename manual section accordingly. - -2005-10-04 Kim F. Storm <storm@cua.dk> - - * windows.texi (Window Split Tree): New section describing - new function window-split-tree function. - -2005-10-03 Nick Roberts <nickrob@snap.net.nz> - - * display.texi (Fringe Size/Pos): Simplify and add detail. - -2005-09-30 Romain Francoise <romain@orebokech.com> - - * minibuf.texi (High-Level Completion): Explain that the prompt - given to `read-buffer' should end with a colon and a space. - Update usage examples. - -2005-09-29 Juri Linkov <juri@jurta.org> - - * display.texi (Displaying Messages): Rename argument name - `string' to `format-string' in functions `message', `message-box', - `message-or-box'. - -2005-09-26 Chong Yidong <cyd@stupidchicken.com> - - * errors.texi (Standard Errors): Correct xrefs. - -2005-09-18 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Defining Images): Update documentation for - `image-load-path'. - -2005-09-17 Richard M. Stallman <rms@gnu.org> - - * display.texi (Defining Images): Clean up previous change. - -2005-09-16 Romain Francoise <romain@orebokech.com> - - * elisp.texi: Specify GFDL version 1.2. - - * doclicense.texi (GNU Free Documentation License): Update to - version 1.2. - -2005-09-15 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Defining Images): Document `image-load-path'. - -2005-09-15 Richard M. Stallman <rms@gnu.org> - - * objects.texi (Printed Representation): Minor cleanup. - (Box Diagrams): Minor fix. - (Cons Cell Type): Move (...) index item here. - (Box Diagrams): From here. - (Array Type): Minor fix. - (Type Predicates): Delete index "predicates". - (Hash Table Type): Clarify xref. - (Dotted Pair Notation): Minor fix. - -2005-09-10 Chong Yidong <cyd@stupidchicken.com> - - * files.texi (Saving Buffers): Fix typo. - -2005-09-08 Richard M. Stallman <rms@gnu.org> - - * tips.texi (Programming Tips): Correct the "default" prompt spec. - -2005-09-08 Chong Yidong <cyd@stupidchicken.com> - - * locals.texi (Standard Buffer-Local Variables): Don't include - mode variables for minor modes. - Fix xrefs for buffer-display-count, buffer-display-table, - buffer-offer-save, buffer-saved-size, cache-long-line-scans, - enable-multibyte-characters, fill-column, header-line-format, - left-fringe-width, left-margin, and right-fringe-width. - - * hooks.texi (Standard Hooks): All hooks should conform to the - standard naming convention now. - Fix xref for `echo-area-clear-hook'. - - * display.texi (Usual Display): Note that indicate-empty-lines and - tab-width are buffer-local. - - * files.texi (Saving Buffers): Add xref to `Killing Buffers'. - - * modes.texi (Mode Help): Note that major-mode is buffer-local. - - * nonascii.texi (Encoding and I/O): Note that - buffer-file-coding-system is buffer-local. - - * positions.texi (List Motion): Note that defun-prompt-regexp is - buffer-local. - - * text.texi (Auto Filling): Note that auto-fill-function is - buffer-local. - (Undo): Note that buffer-undo-list is buffer-local. - - * windows.texi (Buffers and Windows): Document - buffer-display-count. - -2005-09-06 Richard M. Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Sometimes it is ok to put the - package prefix elsewhere than at the start of the name. - -2005-09-03 Richard M. Stallman <rms@gnu.org> - - * tips.texi (Programming Tips): Add conventions for minibuffer - questions and prompts. - -2005-09-03 Joshua Varner <jlvarner@gmail.com> (tiny change) - - * intro.texi (nil and t): Minor cleanup. - Delete spurious mention of keyword symbols. - (Evaluation Notation): Add index entry. - (A Sample Function Description): Minor cleanup. - (A Sample Variable Description): Not all vars can be set. - -2005-09-03 Thien-Thi Nguyen <ttn@gnu.org> - - * text.texi (Buffer Contents): Use "\n" in examples' result strings. - - (Insertion): Document precise type of `insert-char' arg COUNT. - -2005-09-02 Stefan Monnier <monnier@iro.umontreal.ca> - - * modes.texi (Other Font Lock Variables): Sync the default of - font-lock-lines-before. - -2005-08-31 Michael Albinus <michael.albinus@gmx.de> - - * files.texi (Magic File Names): Add `make-auto-save-file-name'. - -2005-08-29 Richard M. Stallman <rms@gnu.org> - - * elisp.texi (Top): Update subnode menu. - - * searching.texi (Searching and Matching): Move node. - Rearrange contents and add overall explanation. - (Searching and Case): Move node. - (Searching and Matching): Update menu. - -2005-08-27 Eli Zaretskii <eliz@gnu.org> - - * os.texi (Startup Summary): Fix the description of the initial - startup message display. - -2005-08-25 Richard M. Stallman <rms@gnu.org> - - * searching.texi (Search and Replace): Add replace-regexp-in-string. - -2005-08-25 Emilio C. Lopes <eclig@gmx.net> - - * display.texi (Finding Overlays): Fix `find-overlay-prop' in - `next-overlay-change' example. - -2005-08-22 Juri Linkov <juri@jurta.org> - - * display.texi (Attribute Functions): Add set-face-inverse-video-p. - Fix invert-face. Fix args of face-background. - - * display.texi (Standard Faces): Delete node. - (Faces): Add xref to `(emacs)Standard Faces'. - (Displaying Faces): Fix xref to `Standard Faces'. - - * modes.texi (Mode Line Data): Fix xref to Standard Faces. - -2005-08-20 Alan Mackenzie <acm@muc.de> - - * buffers.texi (The Buffer List): Clarify the manipulation of the - buffer list. - -2005-08-14 Richard M. Stallman <rms@gnu.org> - - * modes.texi (Auto Major Mode): interpreter-mode-alist key is not - a regexp. - -2005-08-11 Richard M. Stallman <rms@gnu.org> - - * elisp.texi (Top): Update subnode lists. - - * display.texi (Inverse Video): Node deleted. - - * tips.texi (Key Binding Conventions, Programming Tips, Warning Tips): - New nodes split out of Coding Conventions. - - * searching.texi (Regular Expressions): Document re-builder. - - * os.texi (Time Parsing): New node split out of Time Conversion. - - * processes.texi (Misc Network, Network Feature Testing) - (Network Options, Make Network): New nodes split out of - Low-Level Network. - -2005-08-09 Richard M. Stallman <rms@gnu.org> - - * frames.texi (Geometry): New node, split from Size and Position. - (Frame Parameters): Refer to Geometry. - - * buffers.texi (The Buffer List): Fix xrefs. - - * windows.texi (Splitting Windows): Fix xref. - - * frames.texi (Layout Parameters): Add xref. - - * display.texi (Line Height, Scroll Bars): Fix xrefs. - - * keymaps.texi (Menu Bar): Fix xref. - - * locals.texi (Standard Buffer-Local Variables): Fix xref. - - * modes.texi (%-Constructs): Fix xref. - - * frames.texi (Window Frame Parameters): Node split up. - (Basic Parameters, Position Parameters, Size Parameters) - (Layout Parameters, Buffer Parameters, Management Parameters) - (Cursor Parameters, Color Parameters): New subnodes. - -2005-08-09 Luc Teirlinck <teirllm@auburn.edu> - - * positions.texi (Screen Lines): Update xref for previous change - in minibuf.texi. - - * minibuf.texi (Intro to Minibuffers): Update pxref for previous - change in minibuf.texi. - -2005-08-09 Richard M. Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Minor cleanup. - - * modes.texi (Defining Minor Modes): Explain when init-value - can be non-nil. - - * elisp.texi (Top): Update submenu for Minibuffer. - - * minibuf.texi (Minibuffer Misc): Node split up. - (Minibuffer Commands, Minibuffer Windows, Minibuffer Contents) - (Recursive Mini): New nodes split out from Minibuffer Misc. - (Minibuffer Misc): Document max-mini-window-height. - - * hash.texi (Defining Hash): Delete stray paren in example. - - * display.texi (Echo Area Customization): Don't define - max-mini-window-height here; xref instead. - - * commands.texi (Event Input Misc): Update while-no-input. - - * advice.texi (Advising Functions): Explain when to use advice - and when to use a hook. - -2005-07-30 Eli Zaretskii <eliz@gnu.org> - - * makefile.w32-in (info): Don't run install-info. - ($(infodir)/dir): New target, produced by running install-info. - -2005-07-27 Luc Teirlinck <teirllm@auburn.edu> - - * modes.texi (Defining Minor Modes): The keyword for the initial - value is :init-value, not :initial-value. - -2005-07-23 Eli Zaretskii <eliz@gnu.org> - - * loading.texi (Autoload): Make the `doctor' example be consistent - with what's in current loaddefs.el. Describe the "fn" magic in - the usage portion of the doc string. - -2005-07-22 Richard M. Stallman <rms@gnu.org> - - * internals.texi (Garbage Collection): Clarify previous change. - -2005-07-21 Stefan Monnier <monnier@iro.umontreal.ca> - - * internals.texi (Garbage Collection): Add gc-cons-percentage. - -2005-07-18 Juri Linkov <juri@jurta.org> - - * commands.texi (Accessing Events): - * frames.texi (Text Terminal Colors, Resources): - * markers.texi (The Mark): - * modes.texi (Defining Minor Modes): - Delete duplicate duplicate words. - -2005-07-16 Richard M. Stallman <rms@gnu.org> - - * display.texi (Managing Overlays): Clarify make-overlay - args for insertion types. - -2005-07-13 Luc Teirlinck <teirllm@auburn.edu> - - * customize.texi (Variable Definitions): - Add `custom-initialize-safe-set' and `custom-initialize-safe-default'. - `standard-value' is a list too. - (Defining New Types): Use @key{RET} instead of @key{ret}. - -2005-07-13 Francis Litterio <franl@world.std.com> (tiny change) - - * os.texi (Translating Input): Fix typo. - -2005-07-08 Richard M. Stallman <rms@gnu.org> - - * README: Update edition number and size estimate. - - * elisp.texi (VERSION): Set to 2.9. - -2005-07-07 Richard M. Stallman <rms@gnu.org> - - * book-spine.texinfo: Update Emacs version. - - * display.texi (Inverse Video): Delete mode-line-inverse-video. - -2005-07-06 Richard M. Stallman <rms@gnu.org> - - * searching.texi (Regexp Search): Clarify what re-search-forward - does when the search fails. - -2005-07-05 Lute Kamstra <lute@gnu.org> - - * Update FSF's address in GPL notices. - - * doclicense.texi (GNU Free Documentation License): - * gpl.texi (GPL): - * tips.texi (Coding Conventions, Library Headers): - * vol1.texi: - * vol2.texi: Update FSF's address. - -2005-07-04 Richard M. Stallman <rms@gnu.org> - - * hooks.texi (Standard Hooks): Add occur-hook. - -2005-07-03 Luc Teirlinck <teirllm@auburn.edu> - - * display.texi (The Echo Area): Correct menu. - -2005-07-03 Richard M. Stallman <rms@gnu.org> - - * elisp.texi (Top): Update subnode menu for Display. - - * display.texi (Displaying Messages): New node, with most - of what was in The Echo Area. - (Progress): Moved under The Echo Area. - (Logging Messages): New node with new text. - (Echo Area Customization): New node, the rest of what was - in The Echo Area. Document message-truncate-lines with @defvar. - (Display): Update menu. - - * windows.texi (Textual Scrolling): Doc 3 values for - scroll-preserve-screen-position. - - * text.texi (Special Properties): Change hook functions - should bind inhibit-modification-hooks around altering buffer text. - - * keymaps.texi (Key Binding Commands): Call binding BINDING - rather than DEFINITION. - -2005-06-29 Juanma Barranquero <lekktu@gmail.com> - - * variables.texi (Defining Variables): `user-variable-p' returns t - for aliases of user options, nil for alias loops. - -2005-06-28 Richard M. Stallman <rms@gnu.org> - - * keymaps.texi (Creating Keymaps): Put make-sparse-keymap before - make-keymap. - -2005-06-27 Luc Teirlinck <teirllm@auburn.edu> - - * variables.texi (Setting Variables): Correct and clarify - description of `add-to-ordered-list'. - -2005-06-26 Richard M. Stallman <rms@gnu.org> - - * display.texi (Faces): Minor cleanup. - -2005-06-25 Luc Teirlinck <teirllm@auburn.edu> - - * display.texi (Faces): `facep' returns t for strings that are - face names. - -2005-06-25 Richard M. Stallman <rms@gnu.org> - - * objects.texi (Equality Predicates): Clarify meaning of equal. - - * windows.texi (Selecting Windows): save-selected-window - and with-selected-window save and restore the current buffer. - -2005-06-24 Richard M. Stallman <rms@gnu.org> - - * numbers.texi (Float Basics): Explain how to test for NaN, - and printing the sign of NaNs. - -2005-06-24 Eli Zaretskii <eliz@gnu.org> - - * makefile.w32-in (MAKEINFO): Use --force. - -2005-06-23 Richard M. Stallman <rms@gnu.org> - - * display.texi (Face Functions): Correct Texinfo usage. - -2005-06-23 Luc Teirlinck <teirllm@auburn.edu> - - * lists.texi (Rings): `ring-elements' now returns the elements of - RING in order. - -2005-06-23 Juanma Barranquero <lekktu@gmail.com> - - * markers.texi (The Mark): Texinfo usage fix. - -2005-06-23 Kim F. Storm <storm@cua.dk> - - * searching.texi (Entire Match Data): Remove evaporate option for - match-data. Do not mention evaporate option for set-match-data. - -2005-06-22 Glenn Morris <gmorris@ast.cam.ac.uk> - - * display.texi (Face Functions): Mention face aliases. - -2005-06-21 Richard M. Stallman <rms@gnu.org> - - * anti.texi (Antinews): Texinfo usage fix. - -2005-06-21 Karl Berry <karl@gnu.org> - - * elisp.texi: Use @copying. - - * elisp.texi: Put @summarycontents and @contents before the Top - node, instead of the end of the file, so that the contents appear - in the right place in the dvi/pdf output. - -2005-06-21 Juri Linkov <juri@jurta.org> - - * display.texi (Defining Faces): Add `customized-face'. - -2005-06-20 Kim F. Storm <storm@cua.dk> - - * variables.texi (Setting Variables): Any type of element can be - given order in add-to-ordered-list. Compare elements with eq. - - * lists.texi (Rearrangement): Sort predicate may just return non-nil. - -2005-06-20 Karl Berry <karl@gnu.org> - - * syntax.texi (Syntax Flags): Make last column very slightly wider - to avoid "generic comment" breaking on two lines and causing an - underfull box. - -2005-06-19 Luc Teirlinck <teirllm@auburn.edu> - - * lists.texi (Rings): Various minor clarifications and corrections. - -2005-06-18 Richard M. Stallman <rms@gnu.org> - - * functions.texi (Obsolete Functions): Simplify. - - * variables.texi (Variable Aliases): Simplify. - - * anti.texi, backups.texi, compile.texi, customization.texi: - * debugging.texi, display.texi, edebug.texi, errors.texi, frames.texi: - * functions.texi, help.texi, keymaps.texi, modes.texi, nonascii.texi: - * os.texi, processes.texi, searching.texi, strings.texi, text.texi: - * variables.texi: Fix formatting ugliness. - - * elisp.texi: Add links to Rings and Byte Packing. - Update version and copyright years. - - * minibuf.texi: Fix formatting ugliness. - (Completion Commands): Move keymap vars to the end - and vars completing-read binds to the top. - -2005-06-17 Luc Teirlinck <teirllm@auburn.edu> - - * processes.texi: Fix typos. - (Bindat Spec): Correct Texinfo error. - (Byte Packing): Fix ungrammatical sentence. - -2005-06-17 Thien-Thi Nguyen <ttn@gnu.org> - - * lists.texi (Rings): New node. - (Lists): Add it to menu. - - * processes.texi (Byte Packing): New node. - (Processes): Add it to menu. - -2005-06-17 Richard M. Stallman <rms@gnu.org> - - * syntax.texi (Parsing Expressions): Fix texinfo usage. - - * help.texi (Documentation Basics): Explain the xref to - Documentation Tips. - - * debugging.texi (Debugger Commands): Minor fix. - -2005-06-16 Luc Teirlinck <teirllm@auburn.edu> - - * edebug.texi (Instrumenting): Eliminate duplicate link. - (Specification List): Replace references to "below", referring to - a later node, with one @ref to that node. - - * os.texi (Timers): Timers should save and restore the match data - if they change it. - - * debugging.texi (Debugger Commands): Mention that the Lisp - debugger can not step through primitive functions. - -2005-06-16 Juanma Barranquero <lekktu@gmail.com> - - * functions.texi (Obsolete Functions): Update argument names of - `make-obsolete' and `define-obsolete-function-alias'. - - * variables.texi (Variable Aliases): Update argument names of - `defvaralias', `make-obsolete-variable' and - `define-obsolete-variable-alias'. - -2005-06-15 Kim F. Storm <storm@cua.dk> - - * searching.texi (Entire Match Data): Rephrase warnings about - evaporate arg to match-data and set-match-data. - -2005-06-14 Luc Teirlinck <teirllm@auburn.edu> - - * elisp.texi (Top): Update detailed menu. - - * edebug.texi (Edebug): Update menu. - (Instrumenting): Update xrefs. - (Edebug Execution Modes): Correct xref. - (Jumping): Clarify description of `h' command. - Eliminate redundant @ref. - (Breaks): New node. - (Breakpoints): Is now a subsubsection. - (Global Break Condition): Mention `C-x X X'. - (Edebug Views): Clarify `v' and `p'. Mention `C-x X w'. - (Trace Buffer): Clarify STRING arg of `edebug-tracing'. - (Edebug Display Update): Correct pxref. - (Edebug and Macros): New node. - (Instrumenting Macro Calls): Is now a subsubsection. - Neither arg of `def-edebug-spec' is evaluated. - (Instrumenting Macro Calls): Mention `edebug-eval-macro-args'. - (Specification Examples): Fix typo. - -2005-06-14 Lute Kamstra <lute@gnu.org> - - * debugging.texi (Function Debugging): Primitives can break on - entry too. - -2005-06-14 Kim F. Storm <storm@cua.dk> - - * variables.texi (Setting Variables): Add add-to-ordered-list. - -2005-06-13 Stefan Monnier <monnier@iro.umontreal.ca> - - * syntax.texi (Parsing Expressions): Document aux functions and vars of - syntax-ppss: syntax-ppss-flush-cache and syntax-begin-function. - -2005-06-13 Lute Kamstra <lute@gnu.org> - - * text.texi (Special Properties): Fix cross reference. - -2005-06-11 Luc Teirlinck <teirllm@auburn.edu> - - * debugging.texi (Function Debugging): Delete mention of empty - string argument to `cancel-debug-on-entry'. Delete inaccurate - description of the return value of that command. - -2005-06-11 Alan Mackenzie <acm@muc.de> - - * text.texi (Adaptive Fill): Amplify the description of - fill-context-prefix. - -2005-06-10 Luc Teirlinck <teirllm@auburn.edu> - - * syntax.texi (Parsing Expressions): Fix Texinfo error. - -2005-06-10 Stefan Monnier <monnier@iro.umontreal.ca> - - * syntax.texi (Parsing Expressions): Document syntax-ppss. - -2005-06-10 Luc Teirlinck <teirllm@auburn.edu> - - * debugging.texi (Error Debugging): Minor rewording. - (Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry' - is optional. - -2005-06-10 Lute Kamstra <lute@gnu.org> - - * elisp.texi: Use EMACSVER to refer to the current version of Emacs. - (Top): Give it a title. Correct version number. Give the - detailed node listing a more prominent header. - * intro.texi: Don't set VERSION here a second time. - Mention Emacs's version too. - * anti.texi (Antinews): Use EMACSVER to refer to the current - version of Emacs. - -2005-06-09 Kim F. Storm <storm@cua.dk> - - * searching.texi (Entire Match Data): Explain new `reseat' argument to - match-data and set-match-data. - -2005-06-08 Richard M. Stallman <rms@gnu.org> - - * searching.texi (Entire Match Data): Clarify when match-data - returns markers and when integers. - - * display.texi (Defining Faces): Explain that face name should not - end in `-face'. - - * modes.texi (Mode Line Data): Minor cleanup. - (Customizing Keywords): Node split out of Search-based Fontification. - Add example of using font-lock-add-keywords from a hook. - Clarify when MODE should be non-nil, and when nil. - -2005-06-06 Richard M. Stallman <rms@gnu.org> - - * modes.texi (Mode Line Data): Explain what happens when the car - of a list is a void symbol. - (Search-based Fontification): Explain MODE arg to - font-lock-add-keywords and warn about calls from major modes. - -2005-06-08 Juri Linkov <juri@jurta.org> - - * display.texi (Standard Faces): Add `shadow' face. - -2005-05-29 Luc Teirlinck <teirllm@auburn.edu> - - * modes.texi (Major Mode Conventions): A derived mode only needs - to put the call to the parent mode inside `delay-mode-hooks'. - -2005-05-29 Richard M. Stallman <rms@gnu.org> - - * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook is - new, and what that implies. Clarify. - - * files.texi (Locating Files): Clean up the text. - - * frames.texi (Window Frame Parameters): Document user-size. - Shorten entry for top by referring to left. - -2005-05-26 Richard M. Stallman <rms@gnu.org> - - * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook - is new, and what the implications are. Other clarifications. - -2005-05-24 Richard M. Stallman <rms@gnu.org> - - * frames.texi (Dialog Boxes): Minor fixes. - -2005-05-25 Masatake YAMATO <jet@gyve.org> - - * display.texi (Standard Faces): Write about `mode-line-highlight'. - -2005-05-24 Luc Teirlinck <teirllm@auburn.edu> - - * frames.texi (Dialog Boxes): HEADER argument to `x-popup-dialog' - is optional. - -2005-05-24 Nick Roberts <nickrob@snap.net.nz> - - * frames.texi (Dialog Boxes): Descibe new optional argument. - -2005-05-23 Lute Kamstra <lute@gnu.org> - - * modes.texi (Font Lock Basics, Syntactic Font Lock): Recommend - syntax-begin-function over font-lock-beginning-of-syntax-function. - -2005-05-21 Luc Teirlinck <teirllm@auburn.edu> - - * minibuf.texi (Reading File Names): Update description of - `read-directory-name'. - - * modes.texi (Derived Modes): Clarify :group keyword. - -2005-05-21 Eli Zaretskii <eliz@gnu.org> - - * files.texi (Locating Files): New subsection. - Describe locate-file and executable-find. - -2005-05-21 Kevin Ryde <user42@zip.com.au> - - * frames.texi (Initial Parameters): Update cross reference to - "Emacs Invocation". - -2005-05-19 Luc Teirlinck <teirllm@auburn.edu> - - * keymaps.texi (Active Keymaps): Add anchor. - - * modes.texi (Hooks): Delete confusing and unnecessary sentence. - (Major Mode Conventions): Refer to `Auto Major Mode' in more - appropriate place. - (Derived Modes): Small clarifications. - (Minor Mode Conventions, Keymaps and Minor Modes): - Replace references to nodes with references to anchors. - (Mode Line Data): Warn that `(:eval FORM)' should not load any files. - Clarify description of lists whose first element is an integer. - (Mode Line Variables): Add anchor. - (%-Constructs): Clarify description of integer after %. - (Emulating Mode Line): Describe nil value for FACE. - -2005-05-18 Luc Teirlinck <teirllm@auburn.edu> - - * modes.texi (Derived Modes): Correct references to non-existing - variable standard-syntax-table. - -2005-05-17 Lute Kamstra <lute@gnu.org> - - * modes.texi (Defining Minor Modes): Mention the mode hook. - -2005-05-15 Kim F. Storm <storm@cua.dk> - - * processes.texi (Network): Remove open-network-stream-nowait. - (Network Servers): Remove open-network-stream-server. - -2005-05-15 Luc Teirlinck <teirllm@auburn.edu> - - * elisp.texi (Top): Update detailed menu. - - * variables.texi: Reorder nodes. - (Variables): Update menu. - (File Local Variables): Do not refer to the `-*-' line as - a "local variables list". Add pxref. - -2005-05-14 Luc Teirlinck <teirllm@auburn.edu> - - * elisp.texi (Top): Update detailed menu for node changes. - - * modes.texi (Modes): Update Menu. - (Hooks): Move to beginning of chapter. - Most minor modes run mode hooks too. - `add-hook' can handle void hooks or hooks whose value is a single - function. - (Major Modes): Update Menu. - (Major Mode Basics): New node, split off from `Major Modes'. - (Major Mode Conventions): Correct xref. Explain how to handle - auto-mode-alist if the major mode command has an autoload cookie. - (Auto Major Mode): Major update. Add magic-mode-alist. - (Derived Modes): Major update. - (Mode Line Format): Update Menu. - (Mode Line Basics): New node, split off from `Mode Line Format'. - - * loading.texi (Autoload): Mention `autoload cookie' as synonym - for `magic autoload comment'. Add index entries and anchor. - -2005-05-14 Richard M. Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Explain how important it is - that just loading certain files not change Emacs behavior. - - * modes.texi (Defining Minor Modes): Define define-global-minor-mode. - -2005-05-12 Lute Kamstra <lute@gnu.org> - - * modes.texi (Generic Modes): Update. - (Major Modes): Refer to node "Generic Modes". - - * elisp.texi (Top): Update to the current structure of the manual. - * processes.texi (Processes): Add menu description. - * customize.texi (Customization): Add menu descriptions. - -2005-05-11 Thien-Thi Nguyen <ttn@gnu.org> - - * processes.texi (Signals to Processes) - (Low-Level Network): Fix typos. - -2005-05-11 Lute Kamstra <lute@gnu.org> - - * elisp.texi (Top): Add some nodes from the chapter "Major and - Minor Modes" to the detailed node listing. - -2005-05-10 Richard M. Stallman <rms@gnu.org> - - * keymaps.texi (Extended Menu Items): Menu item filter functions - can be called at any time. - -2005-05-08 Luc Teirlinck <teirllm@auburn.edu> - - * variables.texi (File Local Variables): `(hack-local-variables t)' - now also checks whether a mode is specified in the local variables - list. - -2005-05-05 Kevin Ryde <user42@zip.com.au> - - * display.texi (The Echo Area): Correct format function cross - reference. - -2005-05-05 Luc Teirlinck <teirllm@auburn.edu> - - * variables.texi (Variable Aliases): Change description of - `define-obsolete-variable-alias'. - - * functions.texi (Functions): Add "Obsolete Functions" to menu. - (Defining Functions): Add xref. - (Obsolete Functions): New node. - (Function Safety): Standardize capitalization of section title. - - * frames.texi (Pop-Up Menus): Complete description of `x-popup-menu'. - (Dialog Boxes): Complete description of `x-popup-dialog'. - -2005-05-04 Richard M. Stallman <rms@gnu.org> - - * commands.texi (Interactive Codes): Fix Texinfo usage. - Document U more clearly. - -2005-05-01 Luc Teirlinck <teirllm@auburn.edu> - - * variables.texi (Variable Aliases): `make-obsolete-variable' is a - function and not a macro. - - * frames.texi (Pop-Up Menus): Correct and clarify description of - `x-popup-menu'. - (Dialog Boxes): Clarify description of `x-popup-dialog'. - -2005-05-01 Richard M. Stallman <rms@gnu.org> - - * edebug.texi (Checking Whether to Stop): Fix previous change. - -2005-05-01 Luc Teirlinck <teirllm@auburn.edu> - - * display.texi: Fix typos and Texinfo usage. - - * edebug.texi (Checking Whether to Stop): executing-macro -> - executing-kbd-macro. - -2005-05-01 Richard M. Stallman <rms@gnu.org> - - * display.texi (Invisible Text): Correct add-to-invisibility-spec. - -2005-04-30 Richard M. Stallman <rms@gnu.org> - - * files.texi (Magic File Names): Document `operations' property. - -2005-04-29 Lute Kamstra <lute@gnu.org> - - * modes.texi (Generic Modes): New node. - (Major Modes): Add it to the menu. - (Derived Modes): Add "derived mode" to concept index. - -2005-04-28 Lute Kamstra <lute@gnu.org> - - * modes.texi (Defining Minor Modes): Fix previous change. - (Font Lock Mode): Simplify. - (Font Lock Basics): Say that font-lock-defaults is buffer-local - when set and that some parts are optional. Add cross references. - (Search-based Fontification): Say how to specify font-lock-keywords. - Add cross references. Add font-lock-multiline to index. - Move font-lock-keywords-case-fold-search here from node "Other Font - Lock Variables". Document font-lock-add-keywords and - font-lock-remove-keywords. - (Other Font Lock Variables): Move font-lock-keywords-only, - font-lock-syntax-table, font-lock-beginning-of-syntax-function, - and font-lock-syntactic-face-function to node "Syntactic Font - Lock". Move font-lock-keywords-case-fold-search to node - "Search-based Fontification". Document font-lock-inhibit-thing-lock - and font-lock-{,un}fontify-{buffer,region}-function. - (Precalculated Fontification): Remove reference to deleted variable - font-lock-core-only. - (Faces for Font Lock): Add font-lock-comment-delimiter-face. - (Syntactic Font Lock): Add intro. Move font-lock-keywords-only, - font-lock-syntax-table, font-lock-beginning-of-syntax-function, - and font-lock-syntactic-face-function here from node "Other Font - Lock Variables". Move font-lock-syntactic-keywords to "Setting - Syntax Properties". Add cross references. - (Setting Syntax Properties): New node. - Move font-lock-syntactic-keywords here from "Syntactic Font Lock". - * syntax.texi (Syntax Properties): Add cross reference. - * hooks.texi (Standard Hooks): Add Font-Lock hooks. - -2005-04-26 Richard M. Stallman <rms@gnu.org> - - * display.texi (Defining Faces): - Document `default' elements of defface spec. - - * modes.texi (Major Mode Conventions): Explain customizing ElDoc mode. - - * variables.texi (Variable Aliases): Clarify text. - -2005-04-25 Chong Yidong <cyd@stupidchicken.com> - - * windows.texi (Window Hooks): Remove reference to obsolete Lazy Lock. - -2005-04-25 Luc Teirlinck <teirllm@auburn.edu> - - * hooks.texi (Standard Hooks): Most minor modes have mode hooks too. - -2005-04-24 Eli Zaretskii <eliz@gnu.org> - - * syntax.texi (Syntax Table Internals): Elaborate documentation of - syntax-after and syntax-class. - - * files.texi (Changing Files): Fix last change's cross-reference. - (Unique File Names): Don't mention "numbers" in the documentation - of make-temp-file and make-temp-name. - -2005-04-23 Richard M. Stallman <rms@gnu.org> - - * files.texi (Changing Files): Document MUSTBENEW arg in copy-file. - -2005-04-22 Nick Roberts <nickrob@snap.net.nz> - - * windows.texi (Cyclic Window Ordering): Clarify window-list. - -2005-04-22 Nick Roberts <nickrob@snap.net.nz> - - * variables.texi (Variable Aliases): Describe make-obsolete-variable - and define-obsolete-variable-alias. - -2005-04-22 Kim F. Storm <storm@cua.dk> - - * symbols.texi (Symbol Plists): Remove safe-get, as get is now safe. - (Other Plists): Remove safe-plist-get, as plist-get is now safe. - -2005-04-21 Lute Kamstra <lute@gnu.org> - - * lists.texi (Association Lists): Document rassq-delete-all. - -2005-04-19 Richard M. Stallman <rms@gnu.org> - - * modes.texi (Search-based Fontification): Explain that - facespec is an expression to be evaluated. - -2005-04-19 Kevin Ryde <user42@zip.com.au> - - * streams.texi (Output Functions): Fix xref. - * strings.texi (String Conversion): Fix xref. - -2005-04-19 Kim F. Storm <storm@cua.dk> - - * symbols.texi (Symbol Plists): Add safe-get. - Mention that `get' may signal an error. - -2005-04-18 Nick Roberts <nickrob@snap.net.nz> - - * customize.texi (Variable Definitions): Replace tooltip-mode - example with save-place. - -2005-04-17 Richard M. Stallman <rms@gnu.org> - - * buffers.texi (Indirect Buffers): Clarify. - - * positions.texi (Positions): Clarify converting marker to integer. - - * strings.texi (String Basics): Mention string-match; clarify. - -2005-04-08 Lute Kamstra <lute@gnu.org> - - * modes.texi (Search-based Fontification): Fix cross references. - Use consistent terminology. Document anchored highlighting. - -2005-04-05 Lute Kamstra <lute@gnu.org> - - * modes.texi (Defining Minor Modes): Document :group keyword - argument and its default value. - -2005-04-03 Lute Kamstra <lute@gnu.org> - - * hooks.texi (Standard Hooks): Add some hooks. Add cross - references and/or descriptions. Delete major mode hooks; mention - them as a category instead. Rename or delete obsolete hooks. - -2005-04-02 Richard M. Stallman <rms@gnu.org> - - * nonascii.texi (Coding System Basics): Another wording cleanup. - -2005-04-01 Richard M. Stallman <rms@gnu.org> - - * nonascii.texi (Coding System Basics): Clarify previous change. - -2005-04-01 Kenichi Handa <handa@m17n.org> - - * nonascii.texi (Coding System Basics): Describe about rondtrip - identity of coding systems. - -2005-03-29 Chong Yidong <cyd@stupidchicken.com> - - * text.texi (Buffer Contents): Add filter-buffer-substring and - buffer-substring-filters. - -2005-03-26 Chong Yidong <cyd@stupidchicken.com> - - * anti.texi (Antinews): Mention `G' interactive code. - - * tips.texi (Compilation Tips): Mention benchmark.el. - -2005-03-27 Luc Teirlinck <teirllm@auburn.edu> - - * modes.texi (Other Font Lock Variables): `font-lock-fontify-block' - is now bound to M-o M-o. - - * keymaps.texi (Prefix Keys): `facemenu-keymap' is now on M-o. - -2005-03-26 Glenn Morris <gmorris@ast.cam.ac.uk> - - * calendar.texi: Delete file (and move contents to emacs-xtra.texi - in the Emacs Manual). - * Makefile.in (srcs): Remove calendar.texi. - * makefile.w32-in (srcs): Remove calendar.texi. - * display.texi (Display): Change name of next node. - * os.texi (System In): Change name of previous node. - * elisp.texi (Top): Remove Calendar references. - * vol1.texi (Top): Remove Calendar references. - * vol2.texi (Top): Remove Calendar references. - -2005-03-25 Richard M. Stallman <rms@gnu.org> - - * display.texi (Standard Faces, Fringe Bitmaps, Customizing Bitmaps): - Cleanup previous change. - -2005-03-25 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Face Attributes): Faces earlier in an :inherit - list take precedence. - (Scroll Bars): Fix description of vertical-scroll-bars. - Document frame-current-scroll-bars and window-current-scroll-bars. - - * markers.texi (The Mark): Document temporary Transient Mark mode. - - * minibuf.texi (Reading File Names): - Document read-file-name-completion-ignore-case. - - * positions.texi (Screen Lines): Document nil for width argument - to compute-motion. - -2005-03-23 Kim F. Storm <storm@cua.dk> - - * display.texi (Standard Faces): Other faces used in the fringe - implicitly inherits from the fringe face. - (Fringe Bitmaps): FACE in right-fringe and left-fringe display - properties implicitly inherits from fringe face. - (Customizing Bitmaps): Likewise for set-fringe-bitmap-face. - -2005-03-20 Chong Yidong <cyd@stupidchicken.com> - - * display.texi (Invisible Text): State default value of - line-move-ignore-invisible. - (Managing Overlays): Document remove-overlays. - (Standard Faces): Document escape-glyph face. - - * minibuf.texi (Reading File Names): Document read-file-name-function. - - * modes.texi (Other Font Lock Variables): - Document font-lock-lines-before. - - * positions.texi (Skipping Characters): skip-chars-forward allows - character classes. - -2005-03-18 Lute Kamstra <lute@gnu.org> - - * edebug.texi (Instrumenting Macro Calls): Fix another typo. - -2005-03-17 Richard M. Stallman <rms@gnu.org> - - * text.texi (Undo): Document extensible undo entries. - - * searching.texi (String Search, Regexp Search, Regexp Search): - Cleanups. - - * nonascii.texi (Character Codes): Minor fix. - - * display.texi (Display Property): Explain the significance - of having text properties that are eq. - (Other Display Specs): Explain string as display spec. - - * commands.texi (Interactive Codes): Document G option. - -2005-03-17 Chong Yidong <cyd@stupidchicken.com> - - * text.texi (Filling): Add sentence-end-without-period and - sentence-end-without-space. - (Changing Properties): Minor fix. - - * anti.texi: Total rewrite. - -2005-03-15 Lute Kamstra <lute@gnu.org> - - * edebug.texi (Instrumenting Macro Calls): Fix typos. - -2005-03-08 Kim F. Storm <storm@cua.dk> - - * display.texi (Specified Space): Property :width is support on - non-graphic terminals, :height is not. - -2005-03-07 Richard M. Stallman <rms@gnu.org> - - * display.texi (Overlay Arrow, Fringe Bitmaps, Customizing Bitmaps): - Now subnodes of Fringes. - (Overlay Arrow): Document overlay-arrow-variable-list. - (Fringe Size/Pos): New node, broken out of Fringes. - (Display): Explain clearing vs redisplay better. - (Truncation): Clarify use of bitmaps. - (The Echo Area): Clarify the uses of the echo area. - Add max-mini-window-height. - (Progress): Clarify. - (Invisible Text): Explain that main loop moves point out. - (Selective Display): Say "hidden", not "invisible". - (Managing Overlays): Move up. Describe relation to Undo here. - (Overlay Properties): Clarify intro. - (Finding Overlays): Explain return values when nothing found. - (Width): truncate-string-to-width has added arg. - (Displaying Faces): Clarify and update mode line face handling. - (Face Functions): Minor cleanup. - (Conditional Display): Merge into Other Display Specs. - (Pixel Specification, Other Display Specs): Minor cleanups. - (Images, Image Descriptors): Minor cleanups. - (GIF Images): Patents have expired. - (Showing Images): Explain default text for insert-image. - (Manipulating Button Types): Merge into Manipulating Buttons. - (Making Buttons): Explain return values. - (Button Buffer Commands): Add xref. - (Inverse Video): Update mode-line-inverse-video. - (Display Table Format): Clarify. - (Active Display Table): Give defaults for window-display-table. - - * calendar.texi (Calendar Customizing): calendar-holiday-marker - and calendar-today-marker are strings, not chars. - (Holiday Customizing): Minor fix. - - * internals.texi (Writing Emacs Primitives): Update `or' example. - Update limit on # args of subr. - - * edebug.texi (Using Edebug): Arrow is in fringe. - (Instrumenting): Arg to eval-defun works without loading edebug. - (Edebug Execution Modes): Add xref. - - * customize.texi (Common Keywords): Clarify :require. - Mention :version here. - (Variable Definitions, Group Definitions): Not here. - (Variable Definitions): Clarify symbol arg to :initialize and :set fns. - -2005-03-07 Chong Yidong <cyd@stupidchicken.com> - * nonascii.texi (Text Representations): Clarify position-bytes. - (Character Sets): Add list-charset-chars. - (Scanning Charsets): Add charset-after. - (Encoding and I/O): Minor fix. - -2005-03-06 Richard M. Stallman <rms@gnu.org> - - * windows.texi (Vertical Scrolling): Get rid of "Emacs 21". - (Resizing Windows): Likewise. - - * text.texi (Change Hooks): Get rid of "Emacs 21". - - * strings.texi (Formatting Strings): Get rid of "Emacs 21". - - * streams.texi (Output Variables): Get rid of "Emacs 21". - - * searching.texi (Regexp Special, Char Classes): Get rid of "Emacs 21". - - * os.texi (Translating Input): Replace flow-control example - with a less obsolete example that uses `keyboard-translate'. - - * objects.texi (Hash Table Type, Circular Objects): - Get rid of "Emacs 21". - - * modes.texi (Mode Line Format): Get rid of "Emacs 21". - (Mode Line Data, Properties in Mode, Header Lines): Likewise. - - * minibuf.texi (Minibuffer Misc): Get rid of "Emacs 21". - - * lists.texi (List Elements, Building Lists): Get rid of "Emacs 21". - - * keymaps.texi (Menu Separators, Tool Bar): Get rid of "Emacs 21". - (Menu Bar): Fix when menu-bar-update-hook is called. - - * hash.texi (Hash Tables): Get rid of "Emacs 21". - - * frames.texi (Text Terminal Colors): Get rid of "Emacs 21", - and make it read better. - - * files.texi (Writing to Files): Get rid of "Emacs 21". - (Unique File Names): Likewise. - - * elisp.texi: Update Emacs version to 22. - - * display.texi (Forcing Redisplay): Get rid of "Emacs 21". - (Overlay Properties, Face Attributes): Likewise. - (Managing Overlays): Fix punctuation. - (Attribute Functions): Clarify set-face-font; get rid of - info about old Emacs versions. - (Auto Faces, Font Lookup, Display Property, Images): - Get rid of "Emacs 21". - - * calendar.texi (Calendar Customizing): Get rid of "Emacs 21". - -2005-03-05 Richard M. Stallman <rms@gnu.org> - - * debugging.texi (Error Debugging): Remove stack-trace-on-error. - -2005-03-04 Lute Kamstra <lute@gnu.org> - - * debugging.texi (Error Debugging): Document stack-trace-on-error. - -2005-03-03 Lute Kamstra <lute@gnu.org> - - * edebug.texi (Instrumenting Macro Calls): Fix typo. - -2005-03-01 Lute Kamstra <lute@gnu.org> - - * debugging.texi (Debugger Commands): Update `j'. - -2005-02-28 Lute Kamstra <lute@gnu.org> - - * debugging.texi (Debugging): Fix typo. - (Error Debugging): Document eval-expression-debug-on-error. - (Function Debugging): Update example. - (Using Debugger): Mention starred stack frames. - (Debugger Commands): Document `j' and `l'. - (Invoking the Debugger): `d' and `j' exit recursive edit too. - Update the messages that the debugger displays. - (Internals of Debugger): Add cross reference. Update example. - (Excess Open): Minor improvement. - (Excess Close): Minor improvement. - -2005-02-26 Richard M. Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Clarify. - Put all the major mode key reservations together. - Mention the Mouse-1 => Mouse-2 conventions. - - * syntax.texi (Syntax Class Table): Clarify. - (Syntax Table Functions): syntax-after moved from here. - (Syntax Table Internals): syntax-after moved to here. - (Parsing Expressions): Update info on number of values - and what's meaningful in the STATE argument. - (Categories): Fix typo. - - * sequences.texi (Arrays): Cleanup. - (Char-Tables): Clarify. - - * processes.texi (Deleting Processes): Cleanups, add xref. - (Subprocess Creation): Explain nil in exec-path. Cleanup. - (Process Information): set-process-coding-system, some args optional. - (Input to Processes): Explain various types for PROCESS args. - Rename them from PROCESS-NAME to PROCESS. - (Signals to Processes): Likewise. - (Decoding Output): Cleanup. - (Query Before Exit): Clarify. - - * os.texi (Startup Summary): Correct the options; add missing ones. - (Terminal Output, Batch Mode): Clarify. - (Flow Control): Node deleted. - - * markers.texi (The Mark): Clarify. - - * macros.texi (Expansion): Cleanup. - (Indenting Macros): indent-spec allows ints, not floats. - - * keymaps.texi (Keymaps): Clarify. - (Format of Keymaps): Update lisp-mode-map example. - (Active Keymaps, Key Lookup): Clarify. - (Changing Key Bindings): Add xref to `kbd'. - (Key Binding Commands, Simple Menu Items): Clarify. - (Mouse Menus, Menu Bar): Clarify. - (Menu Example): Replace print example with menu-bar-replace-menu. - - * help.texi (Documentation Basics): Add function-documentation prop. - - * elisp.texi (Top): Don't refer to Flow Control node. - - * commands.texi (Command Overview): Improve xrefs. - (Adjusting Point): Adjusting point applies to intangible and invis. - (Key Sequence Input): Doc extra read-key-sequence args. - Likewise for read-key-sequence-vector. - - * backups.texi (Rename or Copy): Minor fix. - (Numbered Backups): For version-control, say the default. - (Auto-Saving): make-auto-save-file-name example is simplified. - - * advice.texi (Advising Functions): Don't imply one part of Emacs - should advise another part. Markup changes. - (Defining Advice): Move transitional para. - (Activation of Advice): Cleanup. - Explain if COMPILE is nil or negative. - - * abbrevs.texi (Abbrev Expansion): Clarify, fix typo. - -2005-02-24 Lute Kamstra <lute@gnu.org> - - * modes.texi (Defining Minor Modes): Explain that INIT-VALUE, - LIGHTER, and KEYMAP can be omitted when KEYWORD-ARGS are used. - -2005-02-23 Lute Kamstra <lute@gnu.org> - - * modes.texi (Defining Minor Modes): define-minor-mode can be used - to define global minor modes as well. - - * display.texi (Managing Overlays): overlay-buffer returns nil for - deleted overlays. - -2005-02-22 Kim F. Storm <storm@cua.dk> - - * minibuf.texi (Basic Completion): Allow symbols in addition to - strings in try-completion and all-completions. - -2005-02-14 Lute Kamstra <lute@gnu.org> - - * elisp.texi (Top): Remove reference to deleted node. - - * lists.texi (Lists): Remove reference to deleted node. - (Cons Cells): Fix typo. - - * loading.texi (Where Defined): Fix typo. - -2005-02-14 Richard M. Stallman <rms@gnu.org> - - * variables.texi (Creating Buffer-Local): change-major-mode-hook - is useful for discarding some minor modes. - - * symbols.texi (Symbol Components): Reorder examples. - - * streams.texi (Input Functions): State standard-input default. - (Output Variables): State standard-output default. - - * objects.texi (Printed Representation): Clarify read syntax vs print. - (Floating Point Type): Explain meaning better. - (Symbol Type): Explain uniqueness better. - (Cons Cell Type): Explain empty list sooner. CAR and CDR later. - List examples sooner. - (Box Diagrams): New subnode broken out. - Some examples moved from old Lists as Boxes node. - (Dotted Pair Notation): Clarify intro. - (Array Type): Clarify. - (Type Predicates): Add hash-table-p. - - * numbers.texi (Integer Basics): Clarify radix explanation. - (Predicates on Numbers): Minor clarification. - (Comparison of Numbers): Minor clarification. Clarify eql. - Typos in min, max. - (Math Functions): Clarify overflow in expt. - - * minibuf.texi (Text from Minibuffer): Minor clarification. - Mention arrow keys. - - * loading.texi (Autoload): defun's doc string overrides autoload's - doc string. - (Repeated Loading): Modernize "add to list" examples. - (Where Defined): Finish updating table of load-history elts. - - * lists.texi (List-related Predicates): Minor wording improvement. - (Lists as Boxes): Node deleted. - (Building Lists): Explain trivial cases of number-sequence. - - * hash.texi (Hash Tables): Add desc to menu items. - (Creating Hash): Expain "full" means "make larger", - (Hash Access): Any object can be a key. - State value of maphash. - - * functions.texi (What Is a Function): Wording cleanup. - (Function Documentation): Minor cleanup. - Explain purpose of calling convention at end of doc string. - (Function Names): Wording cleanup. - (Calling Functions): Wording cleanup. - Explain better how funcall calls the function. - (Function Cells): Delete example of saving and redefining function. - - * control.texi (Combining Conditions): Wording cleanup. - (Iteration): dolist and dotimes bind VAR locally. - (Cleanups): Xref to Atomic Changes. - - * compile.texi (Byte Compilation): Delete 19.29 info. - (Compilation Functions): Macros' difficulties don't affect defsubst. - (Docs and Compilation): Delete 19.29 info. - -2005-02-10 Richard M. Stallman <rms@gnu.org> - - * objects.texi (Symbol Type): Minor correction. - -2005-02-06 Lute Kamstra <lute@gnu.org> - - * modes.texi (Example Major Modes): Fix typos. - -2005-02-06 Richard M. Stallman <rms@gnu.org> - - * text.texi (Margins): fill-nobreak-predicate can be one function. - - * strings.texi (Modifying Strings): clear-string can make unibyte. - (Formatting Strings): format gives error if values missing. - - * positions.texi (Character Motion): Mention default arg - for forward-char. backward-char refers to forward-char. - (Word Motion): Mention default arg for forward-word. - (Buffer End Motion): Mention default arg for beginning-of-buffer. - Simplify end-of-buffer. - (Text Lines): Mention default arg for forward-line. - (List Motion): Mention default arg for beginning/end-of-defun. - (Skipping Characters): Minor fixes in explaining character-set. - - * modes.texi (Major Mode Conventions): Mention "system abbrevs". - Mode inheritance applies only when default-major-mode is nil. - Clarifications. - (Example Major Modes): Update Text mode and Lisp mode examples. - (Minor Mode Conventions): Mention define-minor-mode at top. - (Defining Minor Modes): In Hungry example, don't define C-M-DEL. - (Mode Line Format): Update mode line face display info. - (Properties in Mode): Mention effect of risky vars. - (Imenu): Define imenu-add-to-menubar. - (Font Lock Mode): Add descriptions to menu lines. - (Faces for Font Lock): Add font-lock-doc-face. - -2005-02-05 Lute Kamstra <lute@gnu.org> - - * text.texi (Maintaining Undo): Remove obsolete function. - -2005-02-05 Eli Zaretskii <eliz@gnu.org> - - * frames.texi (Color Names): Add pointer to the X docs about RGB - color specifications. Improve indexing - (Text Terminal Colors): Replace the description of RGB values by - an xref to "Color Names". - -2005-02-03 Richard M. Stallman <rms@gnu.org> - - * windows.texi (Basic Windows): Add cursor-in-non-selected-windows. - Clarify. - (Selecting Windows): Clarify save-selected-window. - (Cyclic Window Ordering): Clarify walk-windows. - (Window Point): Clarify. - (Window Start): Add comment to example. - (Resizing Windows): Add `interactive' specs in examples. - Document fit-window-to-buffer. - - * text.texi (User-Level Deletion): just-one-space takes numeric arg. - (Undo, Maintaining Undo): Clarify last change. - (Sorting): In sort-numeric-fields, explain about octal and hex. - Mention sort-numeric-base. - (Format Properties): Add xref for hard newlines. - - * frames.texi (Window Frame Parameters): Explain pixel=char on tty. - (Pop-Up Menus): Fix typo. - (Color Names): Explain all types of color names. - Explain color-values on B&W terminal. - (Text Terminal Colors): Explain "rgb values" are lists. Fix arg names. - - * files.texi (File Locks): Not supported on MS systems. - (Testing Accessibility): Clarify. - - * edebug.texi (Printing in Edebug): Fix edebug-print-circle. - (Coverage Testing): Fix typo. - - * commands.texi (Misc Events): Remove stray space. - - * buffers.texi (Buffer Names): Clarify generate-new-buffer-name. - (Modification Time): Clarify when visited-file-modtime returns 0. - (The Buffer List): Clarify bury-buffer. - (Killing Buffers): Clarify. - (Indirect Buffers): Add clone-indirect-buffer. - -2005-02-02 Matt Hodges <MPHodges@member.fsf.org> - - * edebug.texi (Printing in Edebug): Fix default value of - edebug-print-circle. - (Coverage Testing): Fix displayed frequency count data. - -2005-02-02 Luc Teirlinck <teirllm@auburn.edu> - - * text.texi (Maintaining Undo): Add `undo-outer-limit'. - -2005-02-02 Kim F. Storm <storm@cua.dk> - - * text.texi (Undo) <buffer-undo-list>: Describe `apply' elements. - -2005-01-29 Eli Zaretskii <eliz@gnu.org> - - * commands.texi (Misc Events): Describe the help-echo event. - - * text.texi (Special Properties) <help-echo>: Use `pos' - consistently in description of the help-echo property. - Use @code{nil} instead of @var{nil}. - - * display.texi (Overlay Properties): Fix the index entry for - help-echo overlay property. - - * customize.texi (Type Keywords): Uncomment the xref to the - help-echo property documentation. - -2005-01-23 Kim F. Storm <storm@cua.dk> - - * windows.texi (Window Start): Fix `pos-visible-in-window-p' - return value. Third element FULLY replaced by PARTIAL which - specifies number of invisible pixels if row is only partially visible. - (Textual Scrolling): Mention auto-window-vscroll. - (Vertical Scrolling): New defvar auto-window-vscroll. - -2005-01-16 Luc Teirlinck <teirllm@auburn.edu> - - * keymaps.texi (Changing Key Bindings): `suppress-keymap' now uses - command remapping. - -2005-01-15 Richard M. Stallman <rms@gnu.org> - - * display.texi (Defining Images): Mention DATA-P arg of create-image. - -2005-01-14 Kim F. Storm <storm@cua.dk> - - * commands.texi (Accessing Events): Add WHOLE arg to posn-at-x-y. - - * text.texi (Links and Mouse-1): Fix string and vector item. - -2005-01-13 Richard M. Stallman <rms@gnu.org> - - * keymaps.texi (Active Keymaps): Rewrite the text, and update the - descriptions of overriding-local-map and overriding-terminal-local-map. - - * text.texi (Links and Mouse-1): Clarify text. - -2005-01-13 Kim F. Storm <storm@cua.dk> - - * modes.texi (Emulating Mode Line): Update format-mode-line entry. - -2005-01-13 Francis Litterio <franl@world.std.com> (tiny change) - - * keymaps.texi (Active Keymaps): Fix overriding-local-map description. - -2005-01-12 Kim F. Storm <storm@cua.dk> - - * text.texi (Links and Mouse-1): Rename section from Enabling - Mouse-1 to Following Links. Change xrefs. - Add examples for define-button-type and define-widget. - - * display.texi (Button Properties, Button Buffer Commands): - Clarify mouse-1 and follow-link functionality. - -2005-01-12 Richard M. Stallman <rms@gnu.org> - - * text.texi (Enabling Mouse-1 to Follow Links): Redo prev. change. - - * display.texi (Beeping): Fix Texinfo usage. - - * modes.texi (Emulating Mode Line): Doc FACE arg in format-header-line. - -2005-01-11 Kim F. Storm <storm@cua.dk> - - * display.texi (Button Properties, Button Buffer Commands): - Mention mouse-1 binding. Add follow-link keyword. - - * text.texi (Text Properties): Add "Enable Mouse-1" to submenu. - (Enabling Mouse-1 to Follow Links): New subsection. - -2005-01-06 Richard M. Stallman <rms@gnu.org> - - * text.texi (Special Properties): Minor change. - - * os.texi (Timers): Clarify previous change. - - * modes.texi (Emulating Mode Line): format-mode-line requires 1 arg. - -2005-01-01 Luc Teirlinck <teirllm@auburn.edu> - - * display.texi (Face Attributes): Correct xref to renamed node. - -2005-01-01 Richard M. Stallman <rms@gnu.org> - - * display.texi (Face Attributes): Describe hex color specs. - -2004-12-31 Richard M. Stallman <rms@gnu.org> - - * os.texi (Timers): Update previous change. - -2004-12-30 Kim F. Storm <storm@cua.dk> - - * display.texi (Line Height): Total line-height is now specified - in line-height property of form (HEIGHT TOTAL). Swap (FACE . RATIO) - in cons cells. (nil . RATIO) is relative to actual line height. - Use line-height `t' instead of `0' to get minimum height. - -2004-12-29 Richard M. Stallman <rms@gnu.org> - - * os.texi (Timers): Discuss timers vs editing the buffer and undo. - -2004-12-28 Richard M. Stallman <rms@gnu.org> - - * commands.texi (Quitting): Clarify value of with-local-quit. - - * elisp.texi (Top): Fix previous change. - - * loading.texi (Loading): Fix previous change. - -2004-12-27 Richard M. Stallman <rms@gnu.org> - - * Makefile.in (MAKEINFO): Specify --force. - - * buffers.texi (Killing Buffers): Add buffer-save-without-query. - - * modes.texi (Emulating Mode Line): Document format's BUFFER arg. - - * display.texi (Line Height): Further clarify. - - * elisp.texi (Top): Update Loading submenu. - - * loading.texi (Where Defined): New node. - (Unloading): load-history moved to Where Defined. - -2004-12-21 Richard M. Stallman <rms@gnu.org> - - * commands.texi (Event Input Misc): Add while-no-input. - -2004-12-11 Richard M. Stallman <rms@gnu.org> - - * display.texi (Line Height): Rewrite text for clarity. - -2004-12-11 Kim F. Storm <storm@cua.dk> - - * display.texi (Display): Add node "Line Height" to menu. - (Line Height): New node. Move full description of line-spacing - and line-height text properties here from text.texi. - (Scroll Bars): Add vertical-scroll-bar variable. - - * frames.texi (Window Frame Parameters): Remove line-height defvar. - - * locals.texi (Standard Buffer-Local Variables): Fix xref for - line-spacing and vertical-scroll-bar. - - * text.texi (Special Properties): Just mention line-spacing and - line-height here, add xref to new "Line Height" node. - -2004-12-09 Thien-Thi Nguyen <ttn@gnu.org> - - * frames.texi (Window Frame Parameters): New @defvar for `line-spacing'. - - * locals.texi (Standard Buffer-Local Variables): - Add @xref for `line-spacing'. - -2004-12-05 Richard M. Stallman <rms@gnu.org> - - * Makefile.in (maintainer-clean): Remove the info files - in $(infodir) where they are created. - -2004-12-03 Richard M. Stallman <rms@gnu.org> - - * windows.texi (Selecting Windows): get-lru-window and - get-largest-window don't consider dedicated windows. - - * text.texi (Undo): Document undo-in-progress. - -2004-11-26 Richard M. Stallman <rms@gnu.org> - - * locals.texi (Standard Buffer-Local Variables): Undo prev change. - Remove a few vars that are not always buffer-local. - -2004-11-24 Luc Teirlinck <teirllm@auburn.edu> - - * locals.texi (Standard Buffer-Local Variables): Comment out - xref's to non-existent node `Yet to be written'. - -2004-11-24 Richard M. Stallman <rms@gnu.org> - - * processes.texi (Synchronous Processes): Grammar fix. - - * numbers.texi (Comparison of Numbers): Add eql. - - * locals.texi (Standard Buffer-Local Variables): Add many vars. - - * intro.texi (Printing Notation): Fix previous change. - - * display.texi (Customizing Bitmaps): Move indicate-buffer-boundaries - and default-indicate-buffer-boundaries from here. - (Usual Display): To here. - (Scroll Bars): Add scroll-bar-mode and scroll-bar-width. - (Usual Display): Move tab-width up. - - * customize.texi (Variable Definitions): Replace - show-paren-mode example with tooltip-mode. - (Simple Types, Composite Types, Defining New Types): - Minor cleanups. - -2004-11-21 Jesper Harder <harder@ifa.au.dk> - - * processes.texi (Synchronous Processes, Output from Processes): - Markup fix. - -2004-11-20 Richard M. Stallman <rms@gnu.org> - - * positions.texi (Skipping Characters): skip-chars-forward - now handles char classes. - - * intro.texi (Printing Notation): Avoid confusion of `print' - when explaining @print. - - * macros.texi (Argument Evaluation): Fix 1st `for' expansion example. - - * display.texi (Display Table Format): Minor fix. - - * streams.texi (Output Functions): Fix print example. - - * Makefile.in (elisp): New target. - (dist): Depend on $(infodir)/elisp, not elisp. - Copy the info files from $(infodir). - - * minibuf.texi (Text from Minibuffer): Document KEEP-ALL arg in - read-from-minibuffer. - - * searching.texi (Regexp Search): Rename that to search-spaces-regexp. - -2004-11-19 Richard M. Stallman <rms@gnu.org> - - * searching.texi (Regexp Search): Add search-whitespace-regexp. - -2004-11-19 CHENG Gao <chenggao@gmail.com> (tiny change) - - * tips.texi (Coding Conventions): Fix typo. - -2004-11-16 Richard M. Stallman <rms@gnu.org> - - * tips.texi (Coding Conventions): Separate defvar and require - methods to avoid warnings. Use require only when there are many - functions and variables from that package. - - * minibuf.texi (Minibuffer Completion): When ignoring case, - predicate must not be case-sensitive. - - * debugging.texi (Function Debugging, Explicit Debug): Clarified. - (Test Coverage): Don't talk about "splotches". Clarified. - -2004-11-16 Thien-Thi Nguyen <ttn@gnu.org> - - * frames.texi (Window Frame Parameters): Fix typo. - -2004-11-15 Kim F. Storm <storm@cua.dk> - - * symbols.texi (Other Plists): Note that plist-get may signal error. - Add safe-plist-get. - -2004-11-15 Thien-Thi Nguyen <ttn@gnu.org> - - * modes.texi (Font Lock Basics): Fix typo. - -2004-11-08 Richard M. Stallman <rms@gnu.org> - - * syntax.texi (Syntax Table Functions): Add syntax-after. - -2004-11-06 Lars Brinkhoff <lars@nocrew.org> - - * os.texi (Processor Run Time): New section documenting - get-internal-run-time. - -2004-11-06 Eli Zaretskii <eliz@gnu.org> - - * Makefile.in (install, maintainer-clean): Don't use "elisp-*" as - it nukes elisp-cover.texi. - (dist): Change elisp-[0-9] to elisp-[1-9], as there could be no - elisp-0 etc. - -2004-11-05 Luc Teirlinck <teirllm@auburn.edu> - - * commands.texi (Keyboard Macros): Document `append' return value - of `defining-kbd-macro'. - -2004-11-01 Richard M. Stallman <rms@gnu.org> - - * commands.texi (Interactive Call): Add called-interactively-p. - -2004-10-29 Simon Josefsson <jas@extundo.com> - - * minibuf.texi (Reading a Password): Revert. - -2004-10-28 Richard M. Stallman <rms@gnu.org> - - * frames.texi (Display Feature Testing): Explain about "vendor". - -2004-10-27 Richard M. Stallman <rms@gnu.org> - - * commands.texi (Interactive Codes): `N' uses numeric prefix, - not raw. Clarify `n'. - (Interactive Call): Rewrite interactive-p, focusing on when - and how to use it. - (Misc Events): Clarify previous change. - - * advice.texi (Simple Advice): Clarify what job the example does. - (Around-Advice): Clarify ad-do-it. - (Activation of Advice): An option of ad-default-compilation-action - is `never', not `nil'. - -2004-10-26 Kim F. Storm <storm@cua.dk> - - * commands.texi (Interactive Codes): Add U code letter. - -2004-10-25 Simon Josefsson <jas@extundo.com> - - * minibuf.texi (Reading a Password): Add. - -2004-10-24 Jason Rumney <jasonr@gnu.org> - - * commands.texi (Misc Events): Remove mouse-wheel. Add wheel-up - and wheel-down. - -2004-10-24 Kai Grossjohann <kai.grossjohann@gmx.net> - - * processes.texi (Synchronous Processes): Document process-file. - -2004-10-22 Kenichi Handa <handa@m17n.org> - - * text.texi (translate-region): Document that it accepts also a - char-table. - -2004-10-22 David Ponce <david@dponce.com> - - * windows.texi (Resizing Windows): Document the `preserve-before' - argument of the functions `enlarge-window' and `shrink-window'. - -2004-10-19 Jason Rumney <jasonr@gnu.org> - - * makefile.w32-in (elisp): Change order of arguments to makeinfo. - -2004-10-09 Luc Teirlinck <teirllm@auburn.edu> - - * text.texi (Filling): Add anchor for definition of - `sentence-end-double-space'. - - * searching.texi (Regexp Example): Update description of how - Emacs currently recognizes the end of a sentence. - (Standard Regexps): Update definition of the variable - `sentence-end'. Add definition of the function `sentence-end'. - -2004-10-08 Paul Pogonyshev <pogonyshev@gmx.net> - - * display.texi (Progress): New node. - -2004-10-05 Kim F. Storm <storm@cua.dk> - - * display.texi (Fringe Bitmaps): Update fringe-bitmaps-at-pos. - -2004-09-29 Kim F. Storm <storm@cua.dk> - - * display.texi (Fringe Bitmaps): Use symbols rather than numbers - to identify bitmaps. Remove -fringe-bitmap suffix for standard - fringe bitmap symbols, as they now have their own namespace. - (Customizing Bitmaps) <define-fringe-bitmap>: Clarify bit ordering - vs. pixels. Signal error if no free bitmap slots. - (Pixel Specification): Change IMAGE to @var{image}. - -2004-09-28 Richard M. Stallman <rms@gnu.org> - - * text.texi (Special Properties): Clarify line-spacing and line-height. - - * searching.texi (Regexp Search): Add looking-back. - -2004-09-25 Luc Teirlinck <teirllm@auburn.edu> - - * display.texi: Correct typos. - (Image Descriptors): Correct xref's. - -2004-09-25 Richard M. Stallman <rms@gnu.org> - - * text.texi (Special Properties): Cleanups in `cursor'. - Rewrites in `line-height' and `line-spacing'; exchange them. - - * display.texi (Fringes): Rewrite previous change. - (Fringe Bitmaps): Merge text from Display Fringe Bitmaps. Rewrite. - (Display Fringe Bitmaps): Node deleted, text moved. - (Customizing Bitmaps): Split off from Fringe Bitmaps. Rewrite. - (Scroll Bars): Clarify set-window-scroll-bars. - (Pointer Shape): Rewrite. - (Specified Space): Clarify :align-to, etc. - (Pixel Specification): Use @var. Clarify new text. - (Other Display Specs): Clarify `slice'. - (Image Descriptors): Cleanups. - (Showing Images): Cleanups. - -2004-09-24 Luc Teirlinck <teirllm@auburn.edu> - - * hooks.texi (Standard Hooks): Add `after-change-major-mode-hook'. - - * modes.texi: Various minor changes in addition to: - (Major Mode Conventions): Final call to `run-mode-hooks' should - not be inside the `delay-mode-hooks' form. - (Mode Hooks): New node. - (Hooks): Delete obsolete example. - Move definitions of `run-mode-hooks' and `delay-mode-hooks' to new - node "Mode Hooks". - -2004-09-22 Luc Teirlinck <teirllm@auburn.edu> - - * display.texi: Correct various typos. - (Display): Rename node "Pointer Shapes" to "Pointer - Shape". (There is already a node called "Pointer Shapes" in - frames.texi.) - (Images): Remove non-existent node "Image Slices" from menu. - -2004-09-23 Kim F. Storm <storm@cua.dk> - - * text.texi (Special Properties): Add `cursor', `pointer', - `line-height', and `line-spacing' properties. - - * display.texi (Display): Add 'Fringe Bitmaps' and 'Pointer - Shapes' to menu. - (Standard Faces): Doc fix for fringe face. - (Fringes): Add `overflow-newline-into-fringe' and - 'indicate-buffer-boundaries'. - (Fringe Bitmaps, Pointer Shapes): New nodes. - (Display Property): Add 'Pixel Specification' and 'Display Fringe - Bitmaps' to menu. - (Specified Space): Describe pixel width and height. - (Pixel Specification): New node. - (Other Display Specs): Add `slice' property. - (Display Fringe Bitmaps): New node. - (Images): Add 'Image Slices' to menu. - (Image Descriptors): Add `:pointer' and `:map' properties. - (Showing Images): Add slice arg to `insert-image'. Add - 'insert-sliced-image'. - -2004-09-20 Richard M. Stallman <rms@gnu.org> - - * commands.texi (Key Sequence Input): - Clarify downcasing in read-key-sequence. - -2004-09-08 Juri Linkov <juri@jurta.org> - - * minibuf.texi (Minibuffer History): Add `history-delete-duplicates'. - -2004-09-07 Luc Teirlinck <teirllm@auburn.edu> - - * locals.texi (Standard Buffer-Local Variables): Add - `buffer-auto-save-file-format'. - * internals.texi (Buffer Internals): Describe new - auto_save_file_format field of the buffer structure. - * files.texi (Format Conversion): `auto-save-file-format' has been - renamed `buffer-auto-save-file-format'. - -2004-08-27 Luc Teirlinck <teirllm@auburn.edu> - - * abbrevs.texi (Abbrev Expansion): `abbrev-start-location' can be - an integer or a marker. - (Abbrev Expansion): Replace example for `pre-abbrev-expand-hook'. - -2004-08-22 Richard M. Stallman <rms@gnu.org> - - * modes.texi (Major Mode Conventions): Discuss rebinding of - standard key bindings. - -2004-08-18 Kim F. Storm <storm@cua.dk> - - * processes.texi (Accepting Output): Add `just-this-one' arg to - `accept-process-output'. - (Output from Processes): New var `process-adaptive-read-buffering'. - -2004-08-10 Luc Teirlinck <teirllm@auburn.edu> - - * keymaps.texi: Various changes in addition to: - (Keymap Terminology): `kbd' uses same syntax as Edit Macro mode. - Give more varied examples for `kbd'. - (Creating Keymaps): Char tables have slots for all characters - without modifiers. - (Active Keymaps): `overriding-local-map' and - `overriding-terminal-local-map' also override text property and - overlay keymaps. - (Functions for Key Lookup): Mention OLP arg to `current-active-maps'. - (Scanning Keymaps): `accessible-keymaps' uses `[]' instead of `""' - to denote a prefix of no events. - `map-keymap' includes parent's bindings _recursively_. - Clarify and correct description of `where-is-internal'. - Mention BUFFER-OR-NAME arg to `describe-bindings'. - (Menu Example): For menus intended for use with the keyboard, the - menu items should be bound to characters or real function keys. - -2004-08-08 Luc Teirlinck <teirllm@auburn.edu> - - * objects.texi (Character Type): Reposition `@anchor' to prevent - double space inside sentence in Info. - - * hooks.texi (Standard Hooks): `disabled-command-hook' has been - renamed to `disabled-command-function'. - * commands.texi (Key Sequence Input): Remove unnecessary anchor. - (Command Loop Info): Replace reference to it. - (Disabling Commands): `disabled-command-hook' has been renamed to - `disabled-command-function'. - -2004-08-07 Luc Teirlinck <teirllm@auburn.edu> - - * os.texi (Translating Input): Only non-prefix bindings in - `key-translation-map' override actual key bindings. Warn about - possible indirect effect of actual key bindings on non-prefix - bindings in `key-translation-map'. - -2004-08-06 Luc Teirlinck <teirllm@auburn.edu> - - * minibuf.texi (High-Level Completion): Add anchor for definition - of `read-variable'. - - * commands.texi: Various changes in addition to: - (Using Interactive): Clarify description of `interactive-form'. - (Interactive Call): Mention default for KEYS argument to - `call-interactively'. - (Command Loop Info): Clarify description of `this-command-keys'. - Mention KEEP-RECORD argument to `clear-this-command-keys'. - Value of `last-event-frame' can be `macro'. - (Repeat Events): `double-click-fuzz' is also used to distinguish - clicks and drags. - (Classifying Events): Clarify descriptions of `event-modifiers' - `event-basic-type' and `event-convert-list'. - (Accessing Events): `posn-timestamp' takes POSITION argument. - (Quoted Character Input): Clarify description of - `read-quoted-char' and fix example. - (Quitting): Add `with-local-quit'. - (Disabling Commands): Correct and clarify descriptions of - `enable-command' and `disable-command'. - Mention what happens if `disabled-command-hook' is nil. - (Keyboard Macros): Mention LOOPFUNC arg to `execute-kbd-macro'. - Describe `executing-kbd-macro' instead of obsolete `executing-macro'. - -2004-07-24 Luc Teirlinck <teirllm@auburn.edu> - - * frames.texi: Various changes in addition to: - (Creating Frames): Expand and clarify description of `make-frame'. - (Window Frame Parameters): Either none or both of the `icon-left' - and `icon-top' parameters must be specified. Put descriptions of - `menu-bar-lines' and `toolbar-lines' closer together and change - them accordingly. - (Frame Titles): `multiple-frames' is not guaranteed to be accurate - except while processing `frame-title-format' or `icon-title-format'. - (Deleting Frames): Correct description of `delete-frame'. - Non-nil return values of `frame-live-p' are like those of `framep'. - (Frames and Windows): Mention return value of - `set-frame-selected-window'. - (Visibility of Frames): Mention `force' argument to - `make-frame-invisible'. `frame-visible-p' returns t for all - frames on text-only terminals. - (Frame Configurations): Restoring a frame configuration does not - restore deleted frames. - (Window System Selections): `x-set-selection' returns DATA. - (Resources): Add example. - (Display Feature Testing): Clarify descriptions of - `display-pixel-height', `display-pixel-width', `x-server-version' - and `x-server-vendor'. - - * windows.texi (Choosing Window): Add anchor. - * minibuf.texi (Minibuffer Misc): Add anchor. - -2004-07-23 John Paul Wallington <jpw@gnu.org> - - * macros.texi (Defining Macros): Declaration keyword for setting - Edebug spec is `debug' not `edebug'. - -2004-07-19 Luc Teirlinck <teirllm@auburn.edu> - - * windows.texi: Various small changes in addition to: - (Window Point): Mention return value of `set-window-point'. - (Window Start): `pos-visible-in-window-p' disregards horizontal - scrolling. Explain return value if PARTIALLY is non-nil. - (Vertical Scrolling): Mention PIXELS-P argument to `window-vscroll' - and `set-window-vscroll'. - (Size of Window): The argument WINDOW to `window-inside-edges', - `window-pixel-edges' and `window-inside-pixel-edges' is optional. - (Resizing Windows): Explain return value of - `shrink-window-if-larger-than-buffer'. - `window-size-fixed' automatically becomes buffer local when set. - (Window Configurations): Explain return value of - `set-window-configuration'. - - * minibuf.texi (Minibuffer Misc): Add anchor for - `minibuffer-scroll-window'. - - * positions.texi (Text Lines): Add anchor for `count-lines'. - -2004-07-17 Richard M. Stallman <rms@gnu.org> - - * display.texi (Overlay Properties): Adding `evaporate' prop - deletes empty overlay immediately. - - * abbrevs.texi (Abbrev Expansion): Clarify pre-abbrev-expand-hook, - fix example. - -2004-07-16 Jim Blandy <jimb@redhat.com> - - * searching.texi (Regexp Backslash): Document new \_< and \_> - operators. - -2004-07-16 Juanma Barranquero <lektu@terra.es> - - * display.texi (Images): Fix Texinfo usage. - -2004-07-14 Luc Teirlinck <teirllm@auburn.edu> - - * buffers.texi (Modification Time): `visited-file-modtime' now - returns a list of two integers, instead of a cons. - -2004-07-13 Luc Teirlinck <teirllm@auburn.edu> - - * windows.texi: Various changes in addition to: - (Splitting Windows): Add `split-window-keep-point'. - -2004-07-09 Richard M. Stallman <rms@gnu.org> - - * frames.texi (Input Focus): Minor fix. - -2004-07-07 Luc Teirlinck <teirllm@auburn.edu> - - * frames.texi (Input Focus): Clarify descriptions of - `select-frame-set-input-focus' and `select-frame'. - -2004-07-06 Luc Teirlinck <teirllm@auburn.edu> - - * os.texi: Various small changes in addition to: - (Killing Emacs): Expand and clarify description of - `kill-emacs-query-functions' and `kill-emacs-hook'. - (System Environment): Expand and clarify description of `getenv' - and `setenv'. - (Timers): Clarify description of `run-at-time'. - (Translating Input): Correct description of - `extra-keyboard-modifiers'. - (Flow Control): Correct description of `enable-flow-control'. - -2004-07-06 Thien-Thi Nguyen <ttn@gnu.org> - - * os.texi: Update copyright. - (Session Management): Grammar fix. - Clarify which Emacs does the restarting. - Use @samp for *scratch* buffer. - -2004-07-04 Alan Mackenzie <acm@muc.de> - - * frames.texi (Input Focus): Add documentation for - `select-frame-set-input-focus'. Replace refs to non-existent - `switch-frame' with `select-frame'. Minor corrections and tidying - up of text-only terminal stuff. - -2004-07-02 Richard M. Stallman <rms@gnu.org> - - * files.texi (Saving Buffers): Cleanup write-contents-function. - (Magic File Names): Cleanup file-remote-p. - -2004-07-02 Kai Grossjohann <kai@emptydomain.de> - - * files.texi (Magic File Names): `file-remote-p' returns an - identifier of the remote system, not just t. - -2004-07-02 David Kastrup <dak@gnu.org> - - * searching.texi (Entire Match Data): Add explanation about new - match-data behavior when @var{integers} is non-nil. - -2004-06-24 Richard M. Stallman <rms@gnu.org> - - * commands.texi (Misc Events): Describe usr1-signal, usr2-signal event. - - * customize.texi (Variable Definitions): Note about doc strings - and :set. - - * keymaps.texi (Keymap Terminology): Document `kbd'. - (Changing Key Bindings, Key Binding Commands): Use kbd in examples. - - * display.texi (Invisible Text): Setting buffer-invisibility-spec - makes it buffer-local. - - * files.texi (Saving Buffers): Correct previous change. - - * commands.texi (Accessing Events): - Clarify posn-col-row and posn-actual-col-row. - -2004-06-24 David Ponce <david.ponce@wanadoo.fr> - - * commands.texi (Accessing Events): New functions - posn-at-point and posn-at-x-y. Add example to posn-x-y. - -2004-06-23 Luc Teirlinck <teirllm@auburn.edu> - - * lists.texi, files.texi, processes.texi, macros.texi, hash.texi: - * frames.texi, buffers.texi, backups.texi, variables.texi: - * loading.texi, eval.texi, functions.texi, control.texi: - * symbols.texi, minibuf.texi: Reposition @anchor's. - - * help.texi: Various small changes in addition to the following. - (Describing Characters): Describe PREFIX argument to - `key-description'. Correct and clarify definition of - `text-char-description'. Describe NEED-VECTOR argument to - `read-kbd-macro'. - (Help Functions): Clarify definition of `apropos'. - -2004-06-23 Lars Hansen <larsh@math.ku.dk> - - * files.texi (Saving Buffers): Correct description of - `write-contents-functions'. - -2004-06-21 Juanma Barranquero <lektu@terra.es> - - * display.texi (Images): Remove redundant @vindex directives. - Rewrite `image-library-alist' doc in active voice. - -2004-06-14 Juanma Barranquero <lektu@terra.es> - - * display.texi (Images): Document new delayed library loading, - variable `image-library-alist' and (existing but undocumented) - function `image-type-available-p'. - -2004-06-05 Richard M. Stallman <rms@gnu.org> - - * minibuf.texi (Minibuffer Completion): For INITIAL arg, - refer the user to the Initial Input node. - (Text from Minibuffer): Likewise. - (Initial Input): New node. Document this feature - and say it is mostly deprecated. - -2004-05-30 Richard M. Stallman <rms@gnu.org> - - * loading.texi (Named Features): Clarify return value - and meaning of NOERROR. - - * variables.texi (File Local Variables): Minor cleanup. - -2004-05-30 Michael Albinus <michael.albinus@gmx.de> - - * files.texi (Magic File Names): Add `file-remote-p' as operation - of file name handlers. - -2004-05-29 Richard M. Stallman <rms@gnu.org> - - * modes.texi (Minor Mode Conventions): (-) has no special meaning - as arg to a minor mode command. - -2004-05-22 Richard M. Stallman <rms@gnu.org> - - * syntax.texi (Syntax Class Table): Word syntax not just for English. - - * streams.texi (Output Variables): Doc float-output-format. - - * searching.texi (Regexp Special): Nested repetition can be infloop. - - * eval.texi (Eval): Increasing max-lisp-eval-depth can cause - real stack overflow. - - * compile.texi: Minor cleanups. - -2004-05-22 Luc Teirlinck <teirllm@dms.auburn.edu> - - * lists.texi (Cons Cells): Explain dotted lists, true lists, - circular lists. - (List Elements): Explain handling of circular and dotted lists. - -2004-05-19 Thien-Thi Nguyen <ttn@gnu.org> - - * modes.texi (Search-based Fontification): Fix typo. - -2004-05-10 Juanma Barranquero <lektu@terra.es> - - * modes.texi (Mode Line Variables): Fix description of - global-mode-string, which is now after which-func-mode, not the - buffer name. - -2004-05-07 Lars Hansen <larsh@math.ku.dk> - - * modes.texi (Desktop Save Mode): Add. - (Modes): Add menu entry Desktop Save Mode. - - * hooks.texi: Add desktop-after-read-hook, - desktop-no-desktop-file-hook and desktop-save-hook. - - * locals.texi: Add desktop-save-buffer. - -2004-04-30 Jesper Harder <harder@ifa.au.dk> - - * display.texi: emacs -> Emacs. - -2004-04-27 Matthew Mundell <matt@mundell.ukfsn.org> - - * files.texi (Changing Files): Document set-file-times. - -2004-04-23 Juanma Barranquero <lektu@terra.es> - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-04-18 Jesper Harder <harder@ifa.au.dk> - - * tips.texi (Coding Conventions): defopt -> defcustom. - -2004-04-16 Luc Teirlinck <teirllm@auburn.edu> - - * sequences.texi: Various clarifications. - -2004-04-14 Luc Teirlinck <teirllm@auburn.edu> - - * buffers.texi (Read Only Buffers): Mention optional ARG to - `toggle-read-only'. - -2004-04-14 Nick Roberts <nick@nick.uklinux.net> - - * windows.texi (Selecting Windows): Note that get-lru-window - returns a full-width window if possible. - -2004-04-13 Luc Teirlinck <teirllm@auburn.edu> - - * buffers.texi: Various changes in addition to: - (Buffer File Name): Add `find-buffer-visiting'. - (Buffer Modification): Mention optional ARG to `not-modified'. - (Indirect Buffers): Mention optional CLONE argument to - `make-indirect-buffer'. - - * files.texi: Various changes in addition to: - (Visiting Functions): `find-file-hook' is now a normal hook. - (File Name Expansion): Explain difference between the way that - `expand-file-name' and `file-truename' treat `..'. - (Contents of Directories): Mention optional ID-FORMAT argument to - `directory-files-and-attributes'. - (Format Conversion): Mention new optional CONFIRM argument to - `format-write-file'. - -2004-04-12 Miles Bader <miles@gnu.org> - - * macros.texi (Expansion): Add description of `macroexpand-all'. - -2004-04-05 Jesper Harder <harder@ifa.au.dk> - - * variables.texi (Variable Aliases): Mention - cyclic-variable-indirection. - - * errors.texi (Standard Errors): Ditto. - -2004-04-04 Luc Teirlinck <teirllm@auburn.edu> - - * backups.texi: Various small changes in addition to: - (Making Backups): Mention return value of `backup-buffer'. - (Auto-Saving): Mention optional FORCE argument to - `delete-auto-save-file-if-necessary'. - (Reverting): Mention optional PRESERVE-MODES argument to - `revert-buffer'. Correct description of `revert-buffer-function'. - -2004-03-22 Juri Linkov <juri@jurta.org> - - * sequences.texi (Sequence Functions): Replace xref to `Vectors' - with `Vector Functions'. - - * text.texi (Sorting): Add missing quote. - -2004-03-14 Luc Teirlinck <teirllm@auburn.edu> - - * intro.texi (Lisp History): Replace xref to `cl' manual with - inforef. - -2004-03-12 Richard M. Stallman <rms@gnu.org> - - * intro.texi (Version Info): Add arg to emacs-version. - (Lisp History): Change xref to CL manual. - -2004-03-09 Luc Teirlinck <teirllm@auburn.edu> - - * minibuf.texi (Completion Commands): Add xref to Emacs manual - for Partial Completion mode. - -2004-03-07 Thien-Thi Nguyen <ttn@gnu.org> - - * customize.texi: Fix typo. Remove eol whitespace. - -2004-03-04 Richard M. Stallman <rms@gnu.org> - - * processes.texi: Fix typos. - - * lists.texi (Building Lists): Minor clarification. - - * hash.texi (Creating Hash): Correct the meaning of t for WEAK - in make-hash-table. - -2004-02-29 Juanma Barranquero <lektu@terra.es> - - * makefile.w32-in (clean, maintainer-clean): Use $(DEL) instead of - rm, and ignore exit code. - -2004-02-27 Dan Nicolaescu <dann@ics.uci.edu> - - * display.texi (Defining Faces): Add description for min-colors. - Update example. - -2004-02-23 Luc Teirlinck <teirllm@auburn.edu> - - * abbrevs.texi: Various corrections and clarifications in addition - to the following: - (Abbrev Tables): Delete add-abbrev (as suggested by RMS). - -2004-02-22 Matthew Mundell <matt@mundell.ukfsn.org> (tiny change) - - * calendar.texi (Holiday Customizing): Quote arg of holiday-sexp. - -2004-02-21 Luc Teirlinck <teirllm@auburn.edu> - - * text.texi: Various small changes in addition to the following: - (User-Level Deletion): Mention optional BACKWARD-ONLY argument - to delete-horizontal-space. - (Kill Functions, Yanking, Low-Level Kill Ring): Clarify and correct - description of yank-handler text property at various places. - - * frames.texi (Window System Selections): Add anchor. - - * syntax.texi (Syntax Table Functions): Clarify and correct - descriptions of make-syntax-table and copy-syntax-table. - (Motion and Syntax): Clarify SYNTAXES argument to - skip-syntax-forward. - (Parsing Expressions): Mention that the return value of - parse-partial-sexp is currently a list of ten rather than nine - elements. - (Categories): Various corrections and clarifications. - -2004-02-17 Luc Teirlinck <teirllm@auburn.edu> - - * markers.texi (Marker Insertion Types): Minor change. - - * locals.texi (Standard Buffer-Local Variables): - * commands.texi (Interactive Codes, Using Interactive): - * functions.texi (Related Topics): Fix xrefs. - -2004-02-16 Luc Teirlinck <teirllm@auburn.edu> - - * lists.texi (Sets And Lists): Update description of delete-dups. - -2004-02-16 Jesper Harder <harder@ifa.au.dk> (tiny change) - - * keymaps.texi (Tool Bar): tool-bar-item => tool-bar-button. - -2004-02-16 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> - - * frames.texi (Parameter Access): frame-parameters arg is optional. - modify-frame-parameters handles nil for FRAME. - (Window Frame Parameters): menu-bar-lines and tool-bar-lines - are all-or-nothing for certain toolkits. - Mention parameter wait-for-wm. - (Frames and Windows): In frame-first-window and frame-selected-window - the arg is optional. - (Input Focus): In redirect-frame-focus the second arg is optional. - (Window System Selections): Mention selection type CLIPBOARD. - Mention data-type UTF8_STRING. - Mention numbering of cut buffers. - (Resources): Describe x-resource-name. - -2004-02-16 Richard M. Stallman <rms@gnu.org> - - * windows.texi (Buffers and Windows): Delete false table - about all-frames. - - * syntax.texi (Parsing Expressions): Delete old caveat - about parse-sexp-ignore-comments. - - * streams.texi (Output Variables): Add print-quoted. - - * lists.texi (Building Lists): Minor cleanup. - - * hash.texi (Creating Hash): Correct and clarify doc of WEAK values. - - * display.texi (Overlays): Explain overlays use markers. - (Managing Overlays): Explain front-advance and rear-advance - in more detail. - - * loading.texi (Unloading): Document unload-feature-special-hooks. - Get rid of fns-NNN.el file. - -2004-02-16 Matthew Mundell <matt@mundell.ukfsn.org> (tiny change) - - * help.texi (Describing Characters): Fix text-char-description - example output. - - * edebug.texi (Using Edebug): Fix example. - - * debugging.texi (Internals of Debugger): Fix return value. - - * files.texi (Changing Files): Fix argname. - - * calendar.texi: Fix parens, and default values. - - * display.texi, frames.texi, internals.texi, modes.texi: Minor fixes. - * nonascii.texi, objects.texi, os.texi: Minor fixes. - * searching.texi, text.texi, tips.texi, windows.text: Minor fixes. - - * positions.texi (Text Lines): Don't add -1 in current-line. - -2004-02-16 Richard M. Stallman <rms@gnu.org> - - * compile.texi (Compiler Errors): if-boundp feature applies to cond. - -2004-02-16 Jesper Harder <harder@ifa.au.dk> (tiny change) - - * processes.texi (Low-Level Network): Fix a typo. - -2004-02-12 Kim F. Storm <storm@cua.dk> - - * display.texi (Fringes): Use consistent wording. - Note that window-fringe's window arg is optional. - (Scroll Bars): Use consistent wording. - -2004-02-11 Luc Teirlinck <teirllm@auburn.edu> - - * tips.texi (Comment Tips): Document the new conventions for - commenting out code. - -2004-02-07 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> - - * positions.texi (Text Lines): Added missing end defun. - -2004-02-07 Kim F. Storm <storm@cua.dk> - - * positions.texi (Text Lines): Add line-number-at-pos. - -2004-02-06 John Paul Wallington <jpw@gnu.org> - - * display.texi (Button Properties, Button Buffer Commands): - mouse-2 invokes button, not down-mouse-1. - -2004-02-04 Jason Rumney <jasonr@gnu.org> - - * makefile.w32-in: Sync with Makefile.in changes. - -2004-02-03 Luc Teirlinck <teirllm@auburn.edu> - - * minibuf.texi (Text from Minibuffer): Various corrections and - clarifications. - (Object from Minibuffer): Correct Lisp description of - read-minibuffer. - (Minibuffer History): Clarify description of cons values for - HISTORY arguments. - (Basic Completion): Various corrections and clarifications. Add - completion-regexp-list. - (Minibuffer Completion): Correct and clarify description of - completing-read. - (Completion Commands): Mention Partial Completion mode. Various - other minor changes. - (High-Level Completion): Various corrections and clarifications. - (Reading File Names): Ditto. - (Minibuffer Misc): Ditto. - -2004-01-26 Luc Teirlinck <teirllm@auburn.edu> - - * strings.texi (Text Comparison): assoc-string also matches - elements of alists that are strings instead of conses. - (Formatting Strings): Standardize Texinfo usage. Update index - entries. - -2004-01-20 Luc Teirlinck <teirllm@auburn.edu> - - * lists.texi (Sets And Lists): Add delete-dups. - -2004-01-15 Luc Teirlinck <teirllm@auburn.edu> - - * edebug.texi (Instrumenting Macro Calls): `declare' is not a - special form. - * macros.texi (Defining Macros): Update description of `declare', - which now is a macro. - (Wrong Time): Fix typos. - -2004-01-14 Luc Teirlinck <teirllm@auburn.edu> - - * compile.texi (Compilation Functions): Expand descriptions of - `compile-defun', `byte-compile-file', `byte-recompile-directory' - and `batch-byte-compile'. In particular, mention and describe - all optional arguments. - (Disassembly): Correct and clarify the description of `disassemble'. - -2004-01-11 Luc Teirlinck <teirllm@auburn.edu> - - * searching.texi: Various small changes in addition to the - following. - (Regexp Example): Adapt to new value of `sentence-end'. - (Regexp Functions): The PAREN argument to `regexp-opt' can be - `words'. - (Search and Replace): Add usage note for `perform-replace'. - (Entire Match Data): Mention INTEGERS and REUSE arguments to - `match-data'. - (Standard Regexps): Update for new values of `paragraph-start' - and `sentence-end'. - -2004-01-07 Luc Teirlinck <teirllm@auburn.edu> - - * files.texi (Saving Buffers): Clarify descriptions of - `write-contents-functions' and `before-save-hook'. - Make the defvar's for `before-save-hook' and `after-save-hook' - into defopt's. - -2004-01-07 Kim F. Storm <storm@cua.dk> - - * commands.texi (Click Events): Describe new image and - width/height elements of click events. - (Accessing Events): Add posn-string, posn-image, and - posn-object-width-height. Change posn-object to return either - image or string object. - -2004-01-01 Simon Josefsson <jas@extundo.com> - - * hooks.texi (Standard Hooks): Add before-save-hook. - * files.texi (Saving Buffers): Likewise. - -2004-01-03 Richard M. Stallman <rms@gnu.org> - - * frames.texi (Frames and Windows): Delete frame-root-window. - -2004-01-03 Luc Teirlinck <teirllm@auburn.edu> - - * eval.texi, hash.texi, help.texi, symbols.texi: Add anchors. - - * functions.texi: Various small changes in addition to the - following. - (What Is a Function): `functionp' returns nil for macros. Clarify - behavior of this and following functions for symbol arguments. - (Function Documentation): Add `\' in front of (fn @var{arglist}) - and explain why. - (Defining Functions): Mention DOCSTRING argument to `defalias'. - Add anchor. - (Mapping Functions): Add anchor. Unquote nil in mapcar* example. - -2004-01-01 Miles Bader <miles@gnu.org> - - * display.texi (Buttons): New section. - -2003-12-31 Andreas Schwab <schwab@suse.de> - - * numbers.texi (Math Functions): sqrt reports a domain-error - error. - (Float Basics): Use `(/ 0.0 0.0)' instead of `(sqrt -1.0)'. - -2003-12-30 Luc Teirlinck <teirllm@auburn.edu> - - * tips.texi (Documentation Tips): Update item on hyperlinks in - documentation strings. - - * errors.texi (Standard Errors): Various small corrections and - additions. - - * control.texi: Various small changes in addition to the - following. - (Signaling Errors): Provide some more details on how `signal' - constructs the error message. Add anchor to the definition of - `signal'. - (Error Symbols): Describe special treatment of `quit'. - (Cleanups): Rename BODY argument of `unwind-protect' to BODY-FORM - to emphasize that it has to be a single form. - - * buffers.texi: Add anchor. - -2003-12-29 Richard M. Stallman <rms@gnu.org> - - * windows.texi (Choosing Window): Add same-window-p, special-display-p. - (Window Configurations): Add window-configuration-frame. - - * variables.texi (Creating Buffer-Local): Add local-variable-if-set-p. - - * text.texi (Examining Properties): Add get-char-property-and-overlay. - Change arg name in get-char-property. - (Special Properties): Update handling of keymap property. - - * strings.texi (Modifying Strings): Add clear-string. - (Text Comparison): Add assoc-string and remove - assoc-ignore-case, assoc-ignore-representation. - - * os.texi (Time of Day): Add set-time-zone-rule. - - * numbers.texi (Math Functions): asin, acos, log, log10 - report domain-error errors. - - * nonascii.texi (Converting Representations): - Add multibyte-char-to-unibyte and unibyte-char-to-multibyte. - (Encoding and I/O): Add file-name-coding-system. - - * modes.texi (Search-based Fontification): Explain that - face specs are symbols with face names as values. - - * minibuf.texi (Minibuffer Misc): Add set-minibuffer-window. - - * lists.texi (Building Lists): remq moved elsewhere. - (Sets And Lists): remq moved here. - (Association Lists): Refer to assoc-string. - - * internals.texi (Garbage Collection): Add memory-use-counts. - - * frames.texi (Frames and Windows): Add set-frame-selected-window - and frame-root-window. - - * files.texi (Contents of Directories): - Add directory-files-and-attributes. - - * display.texi (Refresh Screen): Add force-window-update. - (Invisible Text): Explain about moving point out of invis text. - (Overlay Properties): Add overlay-properties. - (Managing Overlays): Add overlayp. - (GIF Images): Invalid image number displays a hollow box. - - * buffers.texi (Buffer Modification): Add restore-buffer-modified-p. - (Killing Buffers): Add buffer-live-p. - -2003-12-25 Markus Rost <rost@mathematik.uni-bielefeld.de> - - * display.texi (Fringes): Fix typo "set-buffer-window". - -2003-12-24 Luc Teirlinck <teirllm@auburn.edu> - - * display.texi, eval.texi, help.texi, internals.texi, loading.texi: - * nonascii.texi, processes.texi, tips.texi, variables.texi: - Add or change various xrefs and anchors. - - * commands.texi: Replace all occurrences of @acronym{CAR} with - @sc{car}, for consistency with the rest of the Elisp manual. - `car' and `cdr' are historically acronyms, but are no longer - widely thought of as such. - - * internals.texi (Pure Storage): Mention that `purecopy' does not - copy text properties. - (Object Internals): Now 29 bits are used (in most implementations) - to address Lisp objects. - - * variables.texi (Variables with Restricted Values): New node. - - * objects.texi (Lisp Data Types): Mention that certain variables - can only take on a restricted set of values and add an xref to - the new node "Variables with Restricted Values". - - * eval.texi (Function Indirection): Describe the errors that - `indirect-function' can signal. - (Eval): Clarify the descriptions of `eval-region' and `values'. - Describe `eval-buffer' instead of `eval-current-buffer' and - mention `eval-current-buffer' as an alias for `current-buffer'. - Correct the description and mention all optional arguments. - - * nonascii.texi: Various small changes in addition to the - following. - (Converting Representations): Clarify behavior of - `string-make-multibyte' and `string-to-multibyte' for unibyte all - ASCII arguments. - (Character Sets): Document the variable `charset-list' and adapt - the definition of the function `charset-list' accordingly. - (Translation of Characters): Clarify use of generic characters in - `make-translation-table'. Clarify and correct the description of - the use of translation tables in encoding and decoding. - (User-Chosen Coding Systems): Correct and clarify the description - of `select-safe-coding-system'. - (Default Coding Systems): Clarify description of - `file-coding-system-alist'. - -2003-11-30 Luc Teirlinck <teirllm@auburn.edu> - - * strings.texi (Text Comparison): Correctly describe when two - strings are `equal'. Combine and clarify descriptions of - `assoc-ignore-case' and `assoc-ignore-representation'. - - * objects.texi (Non-ASCII in Strings): Clarify description of - when a string is unibyte or multibyte. - (Bool-Vector Type): Update examples. - (Equality Predicates): Correctly describe when two strings are - `equal'. - -2003-11-29 Luc Teirlinck <teirllm@auburn.edu> - - * lists.texi (Building Lists): `append' no longer accepts integer - arguments. Update the description of `number-sequence' to reflect - recent changes. - (Sets And Lists): Describe `member-ignore-case' after `member'. - -2003-11-27 Kim F. Storm <storm@cua.dk> - - * commands.texi (Click Events): Click object may be an images. - Describe (dx . dy) element of click positions. - (Accessing Events): Remove duplicate posn-timestamp. - New functions posn-object and posn-object-x-y. - -2003-11-23 Kim F. Storm <storm@cua.dk> - - * commands.texi (Click Events): Describe enhancements to event - position lists, including new text-pos and (col . row) items. - Mention left-fringe and right-fringe area events. - (Accessing Events): New functions posn-area and - posn-actual-col-row. Mention posn-timestamp. Mention that - posn-point in non-text area still returns buffer position. - Clarify posn-col-row. - -2003-11-21 Lars Hansen <larsh@math.ku.dk> - - * files.texi (File Attributes): Describe new parameter ID-FORMAT. - * anti.texi (File Attributes): Describe removed parameter - ID-FORMAT. - -2003-11-20 Luc Teirlinck <teirllm@auburn.edu> - - * positions.texi (Positions): Mention that, if a marker is used as - a position, its buffer is ignored. - - * markers.texi (Overview of Markers): Mention it here too. - -2003-11-12 Luc Teirlinck <teirllm@auburn.edu> - - * numbers.texi (Numeric Conversions): Not just `floor', but also - `truncate', `ceiling' and `round' accept optional argument DIVISOR. - -2003-11-10 Luc Teirlinck <teirllm@auburn.edu> - - * markers.texi (Creating Markers): Specify insertion type of - created markers. Add xref to `Marker Insertion Types'. - Second argument to `copy-marker' is optional. - (Marker Insertion Types): Mention that most markers are created - with insertion type nil. - (The Mark): Correctly describe when `mark' signals an error. - (The Region): Correctly describe when `region-beginning' and - `region-end' signal an error. - -2003-11-08 Luc Teirlinck <teirllm@auburn.edu> - - * hash.texi (Creating Hash): Clarify description of `eql'. - `makehash' is obsolete. - (Hash Access): Add Common Lisp notes for `remhash' and `clrhash'. - - * positions.texi (Point): Change description of `buffer-end', so - that it is also correct for floating point arguments. - (List Motion): Correct argument lists of `beginning-of-defun' and - `end-of-defun'. - (Excursions): Add xref to `Marker Insertion Types'. - (Narrowing): Argument to `narrow-to-page' is optional. - -2003-11-06 Luc Teirlinck <teirllm@auburn.edu> - - * streams.texi (Output Streams): Clarify behavior of point for - marker output streams. - -2003-11-04 Luc Teirlinck <teirllm@auburn.edu> - - * variables.texi (Defining Variables): Second argument to - `defconst' is not optional. - (Setting Variables): Mention optional argument APPEND to - `add-to-list'. - (Creating Buffer-Local): Expand description of - `make-variable-buffer-local'. - (Frame-Local Variables): Expand description of - `make-variable-frame-local'. - (Variable Aliases): Correct description of optional argument - DOCSTRING to `defvaralias'. Mention return value of - `defvaralias'. - (File Local Variables): Add xref to `File variables' in Emacs - Manual. Correct description of `hack-local-variables'. Mention - `safe-local-variable' property. Mention optional second argument - to `risky-local-variable-p'. - -2003-11-03 Luc Teirlinck <teirllm@auburn.edu> - - * symbols.texi (Symbol Plists): Mention return value of `setplist'. - -2003-11-02 Jesper Harder <harder@ifa.au.dk> (tiny change) - - * lispref/anti.texi, lispref/backups.texi, lispref/commands.texi - lispref/customize.texi, lispref/display.texi, lispref/files.texi, - lispref/internals.texi, lispref/keymaps.texi, lispref/loading.texi, - lispref/modes.texi, lispref/nonascii.texi, lispref/numbers.texi, - lispref/objects.texi, lispref/os.texi, lispref/positions.texi, - lispref/processes.texi, lispref/searching.texi, - lispref/sequences.texi, lispref/streams.texi, lispref/strings.texi, - lispref/syntax.texi, lispref/text.texi: Replace @sc{foo} with - @acronym{FOO}. - -2003-10-27 Luc Teirlinck <teirllm@auburn.edu> - - * strings.texi (Creating Strings): Argument START to `substring' - can not be `nil'. Expand description of - `substring-no-properties'. Correct description of `split-string', - especially with respect to empty matches. Prevent very bad line - break in definition of `split-string-default-separators'. - (Text Comparison): `string=' and `string<' also accept symbols as - arguments. - (String Conversion): More completely describe argument BASE in - `string-to-number'. - (Formatting Strings): `%s' and `%S' in `format' do require - corresponding object. Clarify behavior of numeric prefix after - `%' in `format'. - (Case Conversion): The argument to `upcase-initials' can be a - character. - -2003-10-27 Kenichi Handa <handa@m17n.org> - - * display.texi (Fontsets): Fix texinfo usage. - -2003-10-25 Kenichi Handa <handa@m17n.org> - - * display.texi (Fontsets): Add description of the function - set-fontset-font. - -2003-10-23 Luc Teirlinck <teirllm@auburn.edu> - - * display.texi (Temporary Displays): Add xref to `Documentation - Tips'. - - * functions.texi (Function Safety): Use inforef instead of pxref - for SES. - -2003-10-23 Andreas Schwab <schwab@suse.de> - - * Makefile.in (TEX, texinputdir): Don't define. - (TEXI2DVI): Define. - (srcs): Remove $(srcdir)/index.perm and $(srcdir)/index.unperm, - add $(srcdir)/index.texi. - ($(infodir)/elisp): Remove index.texi dependency. - (elisp.dvi): Likewise. Use $(TEXI2DVI). - (index.texi): Remove target. - (dist): Don't link $(srcdir)/permute-index. - (clean): Don't remove index.texi. - - * permute-index, index.perm: Remove. - * index.texi: Rename from index.unperm. - -2003-10-22 Luc Teirlinck <teirllm@auburn.edu> - - * tips.texi (Documentation Tips): Document new behavior for face - and variable hyperlinks in Help mode. - -2003-10-21 Luc Teirlinck <teirllm@auburn.edu> - - * objects.texi (Integer Type): Update for extra bit of integer range. - (Character Type): Ditto. - -2003-10-16 Eli Zaretskii <eliz@gnu.org> - - * numbers.texi (Integer Basics): Add index entries for reading - numbers in hex, octal, and binary. - -2003-10-16 Lute Kamstra <lute@gnu.org> - - * modes.texi (Mode Line Format): Mention force-mode-line-update's - argument. - -2003-10-13 Luc Teirlinck <teirllm@auburn.edu> - - * windows.texi (Choosing Window): Fix typo. - * edebug.texi (Edebug Execution Modes): Fix typo. - -2003-10-13 Richard M. Stallman <rms@gnu.org> - - * windows.texi (Basic Windows): A window has fringe settings, - display margins and scroll-bar settings. - (Splitting Windows): Doc split-window return value. - Clean up one-window-p. - (Selecting Windows): Fix typo. - (Cyclic Window Ordering): Explain frame as ALL-FRAMES in next-window. - (Buffers and Windows): In set-window-buffer, explain effect - on fringe settings and scroll bar settings. - (Displaying Buffers): In pop-to-buffer, explain nil as buffer arg. - (Choosing Window): Use defopt for pop-up-frame-function. - For special-display-buffer-names, explain same-window and same-frame. - Clarify window-dedicated-p return value. - (Textual Scrolling): scroll-up and scroll-down can get an error. - (Horizontal Scrolling): Clarify auto-hscroll-mode. - Clarify set-window-hscroll. - (Size of Window): Don't mention tool bar in window-height. - (Coordinates and Windows): Explain what coordinates-in-window-p - returns for fringes and display margins. - (Window Configurations): Explain saving fringes, etc. - - * tips.texi (Library Headers): Clean up Documentation. - - * syntax.texi (Parsing Expressions): Clean up forward-comment - and parse-sexp-lookup-properties. - - * sequences.texi (Sequence Functions): sequencep accepts bool-vectors. - - * os.texi (System Environment): Clean up text for load-average errors. - - * modes.texi (Hooks): Don't explain local hook details at front. - Clarify run-hooks and run-hook-with-args a little. - Clean up add-hook and remove-hook. - - * edebug.texi (Edebug Execution Modes): Clarify t. - Document edebug-sit-for-seconds. - (Coverage Testing): Document C-x X = and =. - (Instrumenting Macro Calls): Fix typo. - (Specification List): Don't index the specification keywords. - -2003-10-10 Kim F. Storm <storm@cua.dk> - - * processes.texi (Network): Introduce make-network-process. - -2003-10-09 Luc Teirlinck <teirllm@auburn.edu> - - * tips.texi (Library Headers): Fix typo. - -2003-10-07 Juri Linkov <juri@jurta.org> - - * modes.texi (Imenu): Mention imenu-create-index-function's - default value. Explain submenus better. - -2003-10-07 Lute Kamstra <lute@gnu.org> - - * modes.texi (Faces for Font Lock): Fix typo. - (Hooks): Explain how buffer-local hook variables can refer to - global hook variables. - Various minor clarifications. - -2003-10-06 Lute Kamstra <lute@gnu.org> - - * tips.texi (Coding Conventions): Mention naming conventions for - hooks. - -2003-10-05 Luc Teirlinck <teirllm@auburn.edu> - - * loading.texi (Library Search): Correct default value of - load-suffixes. - (Named Features): Fix typo. - -2003-10-05 Richard M. Stallman <rms@gnu.org> - - * loading.texi (Named Features): In `provide', - say how to test for subfeatures. - (Unloading): In unload-feature, use new var name - unload-feature-special-hooks. - -2003-10-03 Lute Kamstra <lute@gnu.org> - - * modes.texi (Major Mode Conventions): Mention third way to set up - Imenu. - (Imenu): A number of small fixes. - Delete documentation of internal variable imenu--index-alist. - Document the return value format of imenu-create-index-function - functions. - -2003-09-30 Richard M. Stallman <rms@gnu.org> - - * processes.texi (Network): Say what stopped datagram connections do. - - * lists.texi (Association Lists): Clarify `assq-delete-all'. - - * display.texi (Overlay Properties): Clarify `evaporate' property. - -2003-09-29 Lute Kamstra <lute@gnu.org> - - * modes.texi (Mode Line Data): Explain when symbols in mode-line - constructs should be marked as risky. - Change cons cell into proper list. - (Mode Line Variables): Change cons cell into proper list. - -2003-09-26 Lute Kamstra <lute@gnu.org> - - * modes.texi (Mode Line Data): Document the :propertize construct. - (Mode Line Variables): Reorder the descriptions of the variables - to match their order in the default mode-line-format. - Describe the new variables mode-line-position and mode-line-modes. - Update the default values of mode-line-frame-identification, - minor-mode-alist, and default-mode-line-format. - (Properties in Mode): Mention the :propertize construct. - -2003-09-26 Richard M. Stallman <rms@gnu.org> - - * buffers.texi, commands.texi, debugging.texi, eval.texi: - * loading.texi, minibuf.texi, text.texi, variables.texi: - Avoid @strong{Note:}. - -2003-09-26 Richard M. Stallman <rms@gnu.org> - - * keymaps.texi (Remapping Commands): Fix typo. - -2003-09-23 Luc Teirlinck <teirllm@mail.auburn.edu> - - * processes.texi (Low-Level Network): Fix typo. - -2003-09-23 Kim F. Storm <storm@cua.dk> - - * processes.texi (Network, Network Servers): Fix typos. - (Low-Level Network): Add timeout value for :server keyword. - Add new option keywords to make-network-process. - Add set-network-process-options. - Explain how to test availability of network options. - -2003-09-19 Richard M. Stallman <rms@gnu.org> - - * text.texi (Motion by Indent): Arg to - backward-to-indentation and forward-to-indentation is optional. - - * strings.texi (Creating Strings): Add substring-no-properties. - - * processes.texi - (Process Information): Add list-processes arg QUERY-ONLY. - Delete process-contact from here. - Add new status values for process-status. - Add process-get, process-put, process-plist, set-process-plist. - (Synchronous Processes): Add call-process-shell-command. - (Signals to Processes): signal-process allows process objects. - (Network): Complete rewrite. - (Network Servers, Datagrams, Low-Level Network): New nodes. - - * positions.texi (Word Motion): forward-word, backward-word - arg is optional. Reword. - - * abbrevs.texi (Defining Abbrevs): Index no-self-insert. - - * variables.texi (Creating Buffer-Local): - Delete duplicate definition of buffer-local-value. - (File Local Variables): Explain about discarding text props. - -2003-09-11 Richard M. Stallman <rms@gnu.org> - - * minibuf.texi (Intro to Minibuffers): Explain that the minibuffer - changes variables that record input events. - (Minibuffer Misc): Add minibuffer-selected-window. - - * lists.texi (Building Lists): Add copy-tree. - - * display.texi (Fontsets): Add char-displayable-p. - (Scroll Bars): New node. - -2003-09-08 Lute Kamstra <lute@gnu.org> - - * modes.texi (%-Constructs): Document new `%i' and `%I' - constructs. - -2003-09-03 Peter Runestig <peter@runestig.com> - - * makefile.w32-in: New file. - -2003-08-29 Richard M. Stallman <rms@gnu.org> - - * display.texi (Overlay Properties): Clarify how priorities - affect use of the properties. - -2003-08-19 Luc Teirlinck <teirllm@mail.auburn.edu> - - * customize.texi (Type Keywords): Correct the description of - `:help-echo' in the case where `motion-doc' is a function. - -2003-08-14 John Paul Wallington <jpw@gnu.org> - - * modes.texi (Emulating Mode Line): Subsection, not section. - -2003-08-13 Richard M. Stallman <rms@gnu.org> - - * elisp.texi (Top): Update subnode lists in menu. - - * text.texi (Insertion): Add insert-buffer-substring-no-properties. - (Kill Functions): kill-region has new arg yank-handler. - (Yanking): New node. - (Yank Commands): Add yank-undo-function. - (Low-Level Kill Ring): - kill-new and kill-append have new arg yank-handler. - (Changing Properties): Add remove-list-of-text-properties. - (Atomic Changes): New node. - - * symbols.texi (Other Plists): Add lax-plist-get, lax-plist-put. - - * streams.texi (Output Variables): Add eval-expression-print-length - and eval-expression-print-level. - - * os.texi (Time Conversion): For encode-time, explain limits on year. - - * objects.texi (Character Type): Define anchor "modifier bits". - - * modes.texi (Emulating Mode Line): New node. - (Search-based Fontification): Font Lock uses font-lock-face property. - (Other Font Lock Variables): Likewise. - - * keymaps.texi (Format of Keymaps): Keymaps contain char tables, - not vectors. - (Active Keymaps): Add emulation-mode-map-alists. - (Functions for Key Lookup): key-binding has new arg no-remap. - (Remapping Commands): New node. - (Scanning Keymaps): where-is-internal has new arg no-remap. - (Tool Bar): Add tool-bar-local-item-from-menu. - Clarify when to use tool-bar-add-item-from-menu. - - * commands.texi (Interactive Call): commandp has new arg. - (Command Loop Info): Add this-original-command. - -2003-08-06 John Paul Wallington <jpw@gnu.org> - - * compile.texi (Compiler Errors): Say `@end defmac' after `@defmac'. - - * display.texi (Warning Basics): Fix typo. - (Fringes): Add closing curly bracket and fix typo. - - * elisp.texi (Top): Fix typo. - -2003-08-05 Richard M. Stallman <rms@gnu.org> - - * elisp.texi: Update lists of subnodes. - - * windows.texi (Buffers and Windows): set-window-buffer has new arg. - - * variables.texi (Local Variables): Use lc for example variable names. - - * tips.texi (Library Headers): Explain where to put -*-. - - * strings.texi (Creating Strings): Fix xref for vconcat. - - * sequences.texi (Vector Functions): - vconcat no longer allows integer args. - - * minibuf.texi (Reading File Names): read-file-name has new - arg PREDICATE. New function read-directory-name. - - * macros.texi (Defining Macros): Give definition of `declare' - (Indenting Macros): New node. - - * frames.texi (Parameter Access): Add modify-all-frames-parameters. - (Window Frame Parameters): Make separate table of parameters - that are coupled with specific face attributes. - (Deleting Frames): delete-frame-hooks renamed to - delete-frame-functions. - - * files.texi (Magic File Names): Add file-remote-p. - Clarify file-local-copy. - - * edebug.texi (Instrumenting Macro Calls): Don't define `declare' - here; instead xref Defining Macros. - - * display.texi (Warnings): New node, and subnodes. - (Fringes): New node. - - * debugging.texi (Test Coverage): New node. - - * compile.texi (Compiler Errors): Explain with-no-warnings - and other ways to suppress warnings. - - * commands.texi (Interactive Call): Minor clarification. - - * buffers.texi (Buffer File Name): set-visited-file-name - renames the buffer too. - - * abbrevs.texi (Abbrev Tables): Add copy-abbrev-table. - -2003-07-24 Markus Rost <rost@math.ohio-state.edu> - - * abbrevs.texi (Abbrev Expansion): Use \s syntax in example. - -2003-07-22 Markus Rost <rost@math.ohio-state.edu> - - * internals.texi (Garbage Collection): Fix previous change. - -2003-07-22 Richard M. Stallman <rms@gnu.org> - - * files.texi (Truenames): Add LIMIT arg to file-chase-links. - - * display.texi (Width): Use \s syntax in example. - (Font Selection): Add face-font-rescale-alist. - - * modes.texi (Imenu): Add xref to Emacs Manual node on Imenu. - Remove spurious indent in example. - - * lists.texi (Building Lists): Add number-sequence. - - * internals.texi (Garbage Collection): Add gcs-done, gc-elapsed. - - * functions.texi (Function Documentation): Explain how to - show calling convention explicitly in the doc string. - - * windows.texi (Selecting Windows): save-selected-window saves - selected window of each frame. - (Window Configurations): Minor change. - - * syntax.texi (Syntax Table Functions): Use \s syntax in examples. - - * streams.texi (Output Variables): Add print-continuous-numbering - and print-number-table. - - * processes.texi (Decoding Output): New node. - - * os.texi (Time Conversion): decode-time arg is optional. - - * objects.texi (Character Type): Don't use space as example for \. - Make list of char names and \-sequences correspond. - Explain that \s is not used in strings. `\ ' needs space after. - - * nonascii.texi (Converting Representations): Add string-to-multibyte. - (Translation of Characters): Add translation-table-for-input. - (Default Coding Systems): Add auto-coding-functions. - (Explicit Encoding): Add decode-coding-inserted-region. - (Locales): Add locale-info. - - * minibuf.texi (Basic Completion): Describe test-completion. - Collections can be lists of strings. - Clean up lazy-completion-table. - (Programmed Completion): Mention test-completion. - Clarify why lambda expressions are not accepted. - (Minibuffer Misc): Describe minibufferp. - -2003-07-14 Richard M. Stallman <rms@gnu.org> - - * buffers.texi (Killing Buffers): kill-buffer-hook is perm local. - - * windows.texi (Selecting Windows): New arg to select-window. - (Selecting Windows): Add with-selected-window. - (Size of Window): Add window-inside-edges, etc. - - * internals.texi (Garbage Collection): Add post-gc-hook. - - * processes.texi (Subprocess Creation): Add exec-suffixes. - - * keymaps.texi (Functions for Key Lookup): Add current-active-maps. - (Scanning Keymaps): Add map-keymaps. - (Defining Menus): Add keymap-prompt. - - * numbers.texi (Integer Basics): Add most-positive-fixnum, - most-negative-fixnum. - - * compile.texi (Byte Compilation): Explain no-byte-compile - (Compiler Errors): New node. - - * os.texi (User Identification): user-uid, user-real-uid - can return float. - - * modes.texi (Major Mode Conventions): Explain about run-mode-hooks - and about derived modes. - (Minor Modes): Add minor-mode-list. - (Defining Minor Modes): Keyword args for define-minor-mode. - (Search-based Fontification): Explain managing other properties. - (Other Font Lock Variables): Add font-lock-extra-managed-props. - (Faces for Font Lock): Add font-locl-preprocessor-face. - (Hooks): Add run-mode-hooks and delay-mode-hooks. - - * variables.texi (Creating Buffer-Local): Add buffer-local-value. - (Variable Aliases): Clarify defvaralias. - - * loading.texi (Library Search): Add load-suffixes. - - * minibuf.texi (Basic Completion): Add lazy-completion-table. - (Programmed Completion): Add dynamic-completion-table. - - * files.texi (Changing Files): copy-file allows dir as NEWNAME. - (Magic File Names): Specify precedence order of handlers. - - * commands.texi (Command Overview): Emacs server runs pre-command-hook - and post-command-hook. - (Waiting): New calling convention for sit-for. - - * text.texi (Special Properties): local-map and keymap properties - apply based on their stickiness. - -2003-07-07 Richard M. Stallman <rms@gnu.org> - - * modes.texi (Minor Mode Conventions): Specify only some kinds - of list values as args to minor modes. - - * files.texi (File Name Expansion): Warn about iterative use - of substitute-in-file-name. - - * advice.texi (Activation of Advice): Clean up previous change. - -2003-07-06 Markus Rost <rost@math.ohio-state.edu> - - * advice.texi (Activation of Advice): Note that ad-start-advice is - turned on by default. - -2003-06-30 Richard M. Stallman <rms@gnu.org> - - * text.texi (Buffer Contents): Document current-word. - (Change Hooks): Not called for *Messages*. - - * functions.texi (Defining Functions): Explain about redefining - primitives. - (Function Safety): Renamed. Minor changes. - Comment out the detailed criteria for what is safe. - -2003-06-22 Andreas Schwab <schwab@suse.de> - - * objects.texi (Symbol Type): Fix description of examples. - -2003-06-16 Andreas Schwab <schwab@suse.de> - - * hash.texi (Creating Hash): Fix description of :weakness. - -2003-06-13 Kai Gro,A_(Bjohann <kai.grossjohann@gmx.net> - - * files.texi (Changing Files): copy-file copies file modes, too. - -2003-05-28 Richard M. Stallman <rms@gnu.org> - - * strings.texi (Creating Strings): Clarify split-string. - -2003-05-22 Stephen J. Turnbull <stephen@xemacs.org> - - * strings.texi (Creating Strings): Update split-string specification - and examples. - -2003-05-19 Richard M. Stallman <rms@gnu.org> - - * elisp.texi: Correct invariant section names. - -2003-04-20 Richard M. Stallman <rms@gnu.org> - - * os.texi (Timers): Explain about timers and quitting. - -2003-04-19 Richard M. Stallman <rms@gnu.org> - - * internals.texi (Writing Emacs Primitives): Strings are - no longer special for GCPROs. Mention GCPRO5, GCPRO6. - Explain GCPRO convention for varargs function args. - -2003-04-16 Richard M. Stallman <rms@gnu.org> - - * minibuf.texi (Minibuffer Misc): Document fn minibuffer-message. - -2003-04-08 Richard M. Stallman <rms@gnu.org> - - * files.texi (Kinds of Files): Correct return value of file-symlink-p. - -2003-02-13 Kim F. Storm <storm@cua.dk> - - * objects.texi (Character Type): New \s escape for space. - -2003-01-31 Joe Buehler <jhpb@draco.hekimian.com> - - * os.texi (System Environment): Added cygwin system-type. - -2003-01-25 Richard M. Stallman <rms@gnu.org> - - * keymaps.texi: Document that a symbol can act as a keymap. - -2003-01-13 Richard M. Stallman <rms@gnu.org> - - * text.texi (Changing Properties): Say string indices are origin-0. - - * positions.texi (Screen Lines) <compute-motion>: - Correct order of elts in return value. - - * keymaps.texi (Changing Key Bindings) <define-key>: Mention - how to define a default binding. - -2002-12-07 Markus Rost <rost@math.ohio-state.edu> - - * loading.texi (Unloading): Fix recent change for load-history. - - * customize.texi (Simple Types): Clarify description of custom - type 'number. Describe new custom type 'float. - -2002-12-04 Markus Rost <rost@math.ohio-state.edu> - - * variables.texi (File Local Variables): Fix typo. - -2002-10-23 Kai Gro,A_(Bjohann <kai.grossjohann@uni-duisburg.de> - - From Michael Albinus <Michael.Albinus@alcatel.de>. - - * README: Target for Info file is `make info'. - - * files.texi (File Name Components): Fixed typos in - `file-name-sans-extension'. - (Magic File Names): Complete list of operations for magic file - name handlers. - -2002-09-16 Jonathan Yavner <jyavner@engineer.com> - - * variables.texi (File Local Variables): New function - risky-local-variable-p. - -2002-09-15 Jonathan Yavner <jyavner@engineer.com> - - * functions.texi (Function safety): New node about unsafep. - -2002-08-05 Per Abrahamsen <abraham@dina.kvl.dk> - - * customize.texi (Splicing into Lists): Fixed example. - Reported by Fabrice Bauzac <fabrice.bauzac@wanadoo.fr> - -2002-06-17 Juanma Barranquero <lektu@terra.es> - - * frames.texi (Display Feature Testing): Fix typo. - -2002-06-12 Andreas Schwab <schwab@suse.de> - - * frames.texi (Initial Parameters, Resources): Fix references to - the Emacs manual. - -2002-05-13 Kim F. Storm <storm@cua.dk> - - * variables.texi (Intro to Buffer-Local): Updated warning and - example relating to changing buffer inside let. - -2002-03-10 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> - - * os.texi (Session Management): New node about X Session management. - -2002-01-18 Eli Zaretskii <eliz@is.elta.co.il> - - * elisp.texi (VERSION): Set to 2.9. Update the version of Emacs - to which the manual corresponds, and the copyright years. - - * Makefile.in (VERSION): Set to 2.9. - -2001-11-29 Eli Zaretskii <eliz@is.elta.co.il> - - * elisp.texi: Change the category in @dircategory to "Emacs", to - make it consistent with info/dir. - -2001-11-25 Miles Bader <miles@gnu.org> - - * text.texi (Fields): Describe new `limit' arg in - field-beginning/field-end. - -2001-11-17 Eli Zaretskii <eliz@is.elta.co.il> - - * permute-index: Don't depend on csh-specific features. Replace - the interpreter name with /bin/sh. - - * two-volume-cross-refs.txt: New file. - * two.el: New file. - * spellfile: New file. - -2001-11-16 Eli Zaretskii <eliz@is.elta.co.il> - - * permute-index: New file. - - * vol1.texi, vol2.texi: Renamed from elisp-vol1.texi and - elisp-vol2.texi, respectively, to avoid file-name clashes in DOS - 8+3 restricted namespace. - - * Makefile.in (infodir): Define relative to $(srcdir). - ($(infodir)/elisp): Don't chdir into $(srcdir), but add it to the - include directories list via -I switch to makeinfo. - (index.texi): Use cp if both hard and symbolic links fail. - -2001-11-10 Eli Zaretskii <eliz@is.elta.co.il> - - * Makefile.in (distclean): Add. - - The following changes make ELisp manual part of the Emacs - distribution: - - * Makefile.in: Add Copyright notice. - (prefix): Remove. - (infodir): Change value to "../info". - (VPATH): New variable. - (MAKE): Don't define. - (texmacrodir): Don't define. - (texinputdir): Append the existing value of TEXINPUTS. - ($(infodir)/elisp): Instead of just "elisp". Reformat the - command to be compatible with man/Makefile.in, and to put the - output into ../info. - (info): Add target. - (installall): Target removed. - -2001-10-31 Pavel Jan,Am(Bk <Pavel@Janik.cz> - - * tips.texi (Coding Conventions): Fix typo. - -2001-10-23 Gerd Moellmann <gerd@gnu.org> - - * Makefile.in (srcs): Add gpl.texi and doclicense.texi. - -2001-10-22 Eli Zaretskii <eliz@is.elta.co.il> - - * files.texi (File Name Components): Update the description of - file-name-sans-extension and file-name-extension, as they now - ignore leading dots. - -2001-10-20 Gerd Moellmann <gerd@gnu.org> - - * (Version 21.1 released.) - -2001-10-19 Miles Bader <miles@gnu.org> - - * positions.texi (Text Lines): Describe behavior of - `beginning-of-line'/`end-of-line' in the presence of field properties. - -2001-10-17 Gerd Moellmann <gerd@gnu.org> - - * Makefile.in (VERSION): Set to 2.8. - (manual): Use `manual-21'. - - * elisp.texi (VERSION): Add and use it where the version - number was used. Set it to 2.8. - - * intro.texi: Likewise. - -2001-10-13 Eli Zaretskii <eliz@is.elta.co.il> - - * files.texi (File Name Completion): Document the significance of - a trailing slash in elements of completion-ignored-extensions. - -2001-10-06 Miles Bader <miles@gnu.org> - - * variables.texi (Variable Aliases): It's `@defmac', not `@defmacro'. - -2001-10-04 Gerd Moellmann <gerd@gnu.org> - - * variables.texi (Variable Aliases): New node. - -2001-10-04 Gerd Moellmann <gerd@gnu.org> - - * Branch for 21.1. - -2001-10-02 Miles Bader <miles@gnu.org> - - * minibuf.texi (Minibuffer Misc): Add entries for - `minibuffer-contents', `minibuffer-contents-no-properties', and - `delete-minibuffer-contents'. - Correct description for `minibuffer-prompt-end'. - - * text.texi (Property Search): Correct descriptions of - `next-char-property-change' and `previous-char-property-change'. - Add entries for `next-single-char-property-change' and - `previous-single-char-property-change'. - Make operand names a bit more consistent. - -2001-09-30 Eli Zaretskii <eliz@is.elta.co.il> - - * frames.texi (Finding All Frames): Document that next-frame and - previous-frame are local to current terminal. - -2001-09-26 Eli Zaretskii <eliz@is.elta.co.il> - - * keymaps.texi (Creating Keymaps): Fix the description of the - result of make-keymap. - -2001-09-23 Eli Zaretskii <eliz@is.elta.co.il> - - * display.texi (Font Lookup, Attribute Functions) - (Image Descriptors): Add cross-references to the definition of - selected frame. - - * buffers.texi (The Buffer List): Add cross-references to the - definition of selected frame. - - * frames.texi (Input Focus): Clarify which frame is _the_ selected - frame at any given time. - (Multiple Displays, Size and Position): Add a cross-reference to - the definition of the selected frame. - -2001-09-08 Eli Zaretskii <eliz@is.elta.co.il> - - * strings.texi (String Conversion) <string-to-number>: Document - that a float is returned for integers that are too large. - - * frames.texi (Mouse Position): Document mouse-position-function. - (Display Feature Testing): Document display-images-p. - (Window Frame Parameters): Document the cursor-type variable. - - * numbers.texi (Integer Basics): Document CL style read syntax for - integers in bases other than 10. - - * positions.texi (List Motion): Document - open-paren-in-column-0-is-defun-start. - - * lists.texi (Sets And Lists): Document member-ignore-case. - - * internals.texi (Garbage Collection): Document the used and free - strings report. - (Memory Usage): Document strings-consed. - - * os.texi (Time of Day): Document float-time. - (Recording Input): Document that clear-this-command-keys clears - the vector to be returned by recent-keys. - - * keymaps.texi (Scanning Keymaps) <where-is-internal>: The - argument keymap can be a list. - - * nonascii.texi (User-Chosen Coding Systems) - <select-safe-coding-system>: Document the new argument - accept-default-p and the variable - select-safe-coding-system-accept-default-p. Tell what happens if - buffer-file-coding-system is undecided. - (Default Coding Systems): Document auto-coding-regexp-alist. - - * display.texi (The Echo Area) <message>: Document - message-truncate-lines. - (Glyphs): Document that the glyph table is unused on windowed - displays. - - * help.texi (Describing Characters) <single-key-description>: - Document the new argument no-angles. - (Accessing Documentation) <documentation-property>: Document that - a non-string property is evaluated. - <documentation>: Document that the function-documentation property - is looked for. - - * windows.texi (Selecting Windows): Document some-window. - - * text.texi (MD5 Checksum): New node, documents the md5 primitive. - - * hooks.texi (Standard Hooks): Add kbd-macro-termination-hook and - apropos-mode-hook. - - * commands.texi (Using Interactive): Document interactive-form. - (Keyboard Macros): Document kbd-macro-termination-hook. - (Command Loop Info): Document that clear-this-command-keys clears - the vector to be returned by recent-keys. - -2001-09-04 Werner LEMBERG <wl@gnu.org> - - * Makefile.in (srcdir, texinputdir): New variables. - (srcs, index.texi, install): Use $(srcdir). - (.PHONY): Remove elisp.dvi. - (elisp): Use -I switch for makeinfo. - (elisp.dvi): Use $(srcdir) and $(texinputdir). - (installall, dist): Use $(srcdir). - Fix path to texinfo.tex. - (maintainer-clean): Add elisp.dvi and elisp.oaux. - -2001-08-30 Gerd Moellmann <gerd@gnu.org> - - * display.texi (Conditional Display): Adjust to API change. - - * configure: New file. - -2001-07-30 Gerd Moellmann <gerd@gnu.org> - - * commands.texi (Repeat Events): Add description of - double-click-fuzz. - -2001-05-08 Stefan Monnier <monnier@cs.yale.edu> - - * syntax.texi (Syntax Class Table): Add the missing designator for - comment and string fences. - (Syntax Properties): Add a xref to syntax table internals. - (Syntax Table Internals): Document string-to-syntax. - -2001-05-07 Gerd Moellmann <gerd@gnu.org> - - * Makefile.in (install): Use install-info command line options - like in Emacs' Makefile.in. - -2000-12-09 Miles Bader <miles@gnu.org> - - * windows.texi (Window Start): Update documentation for - `pos-visible-in-window-p'. - -2000-11-12 Stefan Monnier <monnier@cs.yale.edu> - - * lists.texi (Building Lists): Add footnote to explain how to add - to the end of a list. - -2000-10-25 Gerd Moellmann <gerd@gnu.org> - - * files.texi (Visiting Functions): Typos. - -2000-10-25 Kenichi Handa <handa@etl.go.jp> - - * files.texi (Visiting Functions): Return value of - find-file-noselect may be a list of buffers if wildcards are used. - -2000-10-24 Miles Bader <miles@lsi.nec.co.jp> - - * display.texi (Defining Faces): Document `graphic' display type - in face specs. - -2000-10-18 Kai Grossjohann <Kai.Grossjohann@CS.Uni-Dortmund.DE> - - * hooks.texi (Standard Hooks): Replace obsolete - `after-make-frame-hook' with `after-make-frame-functions'. - - * frames.texi (Creating Frames): Ditto. - - * variables.texi (Future Local Variables): Ditto. - -2000-10-16 Gerd Moellmann <gerd@gnu.org> - - * display.texi (Other Image Types): Add description of :foreground - and :background properties of mono PBM images. - -2000-08-17 Werner LEMBERG <wl@gnu.org> - - * .cvsignore: New file. - -2000-01-05 Gerd Moellmann <gerd@gnu.org> - - * tindex.pl: New script. - -1999-12-03 Dave Love <fx@gnu.org> - - * Makefile.in (MAKEINFO): New parameter. - -1999-09-17 Richard Stallman <rms@gnu.org> - - * Makefile.in (srcs): Add hash.texi. - (VERSION): Update to 20.6. - -1999-09-13 Richard Stallman <rms@gnu.org> - - * Makefile.in (index.texi): If cannot make a symlink, make a hard link. - -1998-08-29 Karl Heuer <kwzh@gnu.org> - - * configure.in: New file. - * Makefile.in: Renamed from Makefile. - (prefix, infodir): Use value obtained from configure. - (emacslibdir): Obsolete variable deleted. - (dist): Distribute configure.in, configure, Makefile.in. - -1998-06-12 Richard Stallman <rms@psilocin.ai.mit.edu> - - * Makefile (INSTALL_INFO): New variable. - (install): Run install-info. - -1998-05-09 Richard Stallman <rms@psilocin.ai.mit.edu> - - * Makefile (elisp.dvi): Add missing backslash. - -1998-05-02 Richard Stallman <rms@psilocin.gnu.org> - - * Makefile (elisp.dvi): Don't depend on texindex or on elisp.tps. - Run texindex without `./'. Always run texindex on elisp.tp. - (elisp.tps): Target deleted. - -1998-04-05 Richard Stallman <rms@psilocin.gnu.org> - - * Makefile (srcs): Add nonascii.texi and customize.texi. - (dist): Start by deleting `temp'. - -1998-02-17 Richard Stallman <rms@psilocin.gnu.org> - - * Makefile (makeinfo, texindex): Targets deleted. - (makeinfo.o, texindex.o): Targets deleted. - (clean, dist): Don't do anything with them or with getopt*. - -1998-01-30 Richard Stallman <rms@psilocin.gnu.org> - - * Makefile (SHELL): Defined. - -1998-01-27 Richard Stallman <rms@psilocin.gnu.org> - - * Makefile (elisp.tps): New target. - (elisp.dvi): Depend on elisp.tps. - -Wed Apr 3 15:24:25 1996 Karl Heuer <kwzh@gnu.ai.mit.edu> - - * README: Update phone number. - - * Makefile (elisp): Make this be the default target. - Depend on makeinfo.c instead of makeinfo. - (install): Don't depend on elisp.dvi, since we don't install that. - Use mkinstalldirs. - (dist): Add mkinstalldirs. - -Mon Jun 19 14:35:26 1995 Richard Stallman <rms@mole.gnu.ai.mit.edu> - - * Makefile (VERSION): Update version number. - (maintainer-clean): Renamed from realclean. - -Wed Jun 7 17:04:59 1995 Karl Heuer <kwzh@nutrimat.gnu.ai.mit.edu> - - * Makefile (realclean): New target. - (elisp): Remove any old elisp-* files first. - -Tue Nov 23 19:59:40 1993 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) - - * Makefile (VERSION): New variable. - (dist): Make packaged directory name `elisp-manual-19-$(VERSION)'. - Compressed file suffix should be `.gz', not `.z'. - -Mon Nov 22 15:06:19 1993 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (elisp): Depend on makeinfo. - -Fri Nov 19 02:29:33 1993 Noah Friedman (friedman@gnu.ai.mit.edu) - - * Makefile (srcs): Add anti.texi. - -Fri May 28 18:04:53 1993 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (infodir, prefix): New vars. - (install): Use infodir. - (emacsinfodir): Deleted. - -Thu May 27 02:11:25 1993 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (srcs): Add calendar.texi. - - * Makefile (dist): Copy texindex.c and makeinfo.c. - Limit elisp-* files to those with one or two digits. - -Sun May 16 17:58:21 1993 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Changed to use Gzip instead of compress. - -Fri Apr 23 01:05:23 1993 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * loading.texi (Unloading): define-function changed back to - defalias. It may not stay this way, but at least it's - consistent with the known-good version of the code patch. - -Fri Mar 26 21:14:54 1993 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) - - * modes.texi (Hooks): Document new optional arg of add-hook. - -Wed Mar 17 08:48:24 1993 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * variables.texi: Document nil initial value of buffer-local variables. - - * tips.texi: Add new section on standard library headers. - -Sat Feb 27 18:00:25 1993 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (srcs): Add frame.texi to the list of sources. - -Tue Feb 23 10:50:25 1993 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Don't bother excluding autosave files; they'll - never make it into the temp directory anyway, and the hash marks - in the name are problematic for make and the Bourne shell. - (srcs): - -Fri Feb 12 16:54:38 1993 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Don't include backup files or autosave files in - the distribution tar file. - -Tue Nov 26 21:10:34 1991 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (srcs): Added index.perm. - (elisp.dvi): Remove erroneous shell comment. - Expect output of permute-index in permuted.fns. - Save old elisp.aux in elisp.oaux. - (clean): Added index.texi to be deleted. - -Sat Aug 11 17:39:10 1990 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * Makefile (elisp.dvi, index.texi): Use shell if instead of ifdef. - -Tue Jun 26 09:57:26 1990 David Lawrence (tale@geech) - - * files.texi: Noted that completion-ignored-extensions is ignored - when making *Completions*. - -Fri Jun 8 16:44:44 EDT 1990 Jay Fenlason (hack@ai.mit.edu) - - * Makefile make dist now depends on elisp.dvi, since it tries - to include it in the dist file. - -Wed Mar 28 22:57:35 1990 Jim Kingdon (kingdon@mole.ai.mit.edu) - - * functions.texinfo (Mapping Functions): Add missing quote - -Mon Jun 19 18:09:24 1989 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * texinfo.tex (frenchspacing): Use decimal codes for char to be set. - (defunargs): Turn off \hyphenchar of \sl font temporarily. - -Wed May 10 18:01:17 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * @result{}, @expansion{}, @print{}, @quiv{}, @point{}, - and @error{} are the terms now being used. The files in the - directory have been changed to reflect this. - - * All instances of @indentedresultt{} have been changed to - ` @result{}', using 5 spaces at the begining of the line. - -Mon Apr 24 21:02:55 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * @result{}, @expandsto{}, @prints{}, @quiv{}, @error{}, and the - experimental @indentedresult{}, @indentedexpandsto{} are part of - the texinfo.tex in this directory. These TeX macros are not - stable yet. - -Mon Apr 17 18:56:50 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * texinfo.tex: Temporarily added - \let\result=\dblarrow - \def\error{{\it ERROR} \longdblarrow} - We need to do this better soon. - -Tue Apr 11 12:23:28 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * Applied Karl Berry's patches to *.texinfo files, but not to - texinfo.tex; those diffs are in `berry-texinfo-tex-diffs'. (Karl's - new title page format is also not applied, since it requires - texinfo.tex changes.) - - * Cleaned up `Makefile' and defined the `emacslibdir' directory - for the Project GNU development environment. - -;; Local Variables: -;; coding: iso-2022-7bit -;; add-log-time-zone-rule: t -;; End: - - Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, - 2005, 2006, 2007 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3, or (at your option) - any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - Boston, MA 02110-1301, USA. - -;;; arch-tag: 985ae0ce-df29-475b-b3f8-4bbcbf6f7fda diff --git a/lispref/Makefile.in b/lispref/Makefile.in deleted file mode 100644 index 1a34d60a0d8..00000000000 --- a/lispref/Makefile.in +++ /dev/null @@ -1,144 +0,0 @@ -# Makefile for the GNU Emacs Lisp Reference Manual. - -# Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, -# 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 3, or (at your option) -# any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs; see the file COPYING. If not, write to -# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -# Boston, MA 02110-1301, USA. - -# Standard configure variables. -srcdir = @srcdir@ - -# Tell make where to find source files; this is needed for the makefiles. -VPATH=@srcdir@ - -infodir = ../info -usermanualdir = $(srcdir)/../man - -TEXI2DVI = texi2dvi -SHELL = /bin/sh -INSTALL_INFO = install-info -MAKEINFO = makeinfo --force - -# The name of the manual: -VERSION=2.9 -manual = elisp-manual-21-$(VERSION) - -# List of all the texinfo files in the manual: - -srcs = \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/back.texi \ - $(srcdir)/backups.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/compile.texi \ - $(srcdir)/control.texi \ - $(srcdir)/customize.texi \ - $(srcdir)/debugging.texi \ - $(srcdir)/display.texi \ - $(srcdir)/edebug.texi \ - $(srcdir)/elisp.texi \ - $(srcdir)/errors.texi \ - $(srcdir)/eval.texi \ - $(srcdir)/files.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/functions.texi \ - $(srcdir)/hash.texi \ - $(srcdir)/help.texi \ - $(srcdir)/hooks.texi \ - $(srcdir)/internals.texi \ - $(srcdir)/intro.texi \ - $(srcdir)/keymaps.texi \ - $(srcdir)/lists.texi \ - $(srcdir)/loading.texi \ - $(srcdir)/locals.texi \ - $(srcdir)/macros.texi \ - $(srcdir)/maps.texi \ - $(srcdir)/markers.texi \ - $(srcdir)/minibuf.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/nonascii.texi \ - $(srcdir)/numbers.texi \ - $(srcdir)/objects.texi \ - $(srcdir)/os.texi \ - $(srcdir)/positions.texi \ - $(srcdir)/processes.texi \ - $(srcdir)/searching.texi \ - $(srcdir)/sequences.texi \ - $(srcdir)/streams.texi \ - $(srcdir)/strings.texi \ - $(srcdir)/symbols.texi \ - $(srcdir)/syntax.texi \ - $(srcdir)/text.texi \ - $(srcdir)/tips.texi \ - $(srcdir)/variables.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/index.texi \ - $(srcdir)/gpl.texi \ - $(srcdir)/doclicense.texi - - -.PHONY: clean - -# The info file is named `elisp'. -info: $(infodir)/elisp - -$(infodir)/elisp: $(srcs) - cd $(srcdir); $(MAKEINFO) -I. -I$(infodir) elisp.texi -o $(infodir)/elisp - -elisp.dvi: $(srcs) - $(TEXI2DVI) -I $(srcdir) -I $(usermanualdir) $(srcdir)/elisp.texi - -# This is for use in a separate distro of the Emacs Lisp manual. -install: elisp - $(srcdir)/mkinstalldirs $(infodir) - cp elisp elisp-[1-9] elisp-[1-9][0-9] $(infodir) - ${INSTALL_INFO} --info-dir=${infodir} ${infodir}/elisp - -# This is for use in a separate distro of the Emacs Lisp manual. -elisp: $(srcs) - $(MAKEINFO) -I. -I$(srcdir) $(srcdir)/elisp.texi - -clean: - rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ - *.vr *.vrs *.pg *.pgs *.ky *.kys - rm -f make.out core - -distclean: clean - -maintainer-clean: clean - rm -f elisp.dvi elisp.oaux - cd $(infodir); rm -f elisp elisp-[1-9] elisp-[1-9][0-9] - -dist: $(infodir)/elisp elisp.dvi - -rm -rf temp - -mkdir temp - -mkdir temp/$(manual) - -ln $(srcdir)/README $(srcdir)/configure.in $(srcdir)/configure \ - $(srcdir)/Makefile.in $(srcs) \ - $(srcdir)/../man/texinfo.tex \ - elisp.dvi elisp.aux elisp.??s \ - $(infodir)/elisp $(infodir)/elisp-[1-9] $(infodir)/elisp-[1-9][0-9] \ - temp/$(manual) - -(cd temp/$(manual); rm -f mkinstalldirs) - cp $(srcdir)/mkinstalldirs temp/$(manual) - (cd temp/$(manual); rm -f *~) - (cd temp; tar chf - $(manual)) | gzip > $(manual).tar.gz - -rm -rf temp diff --git a/lispref/README b/lispref/README deleted file mode 100644 index c5d4c8acc77..00000000000 --- a/lispref/README +++ /dev/null @@ -1,72 +0,0 @@ -Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007 - Free Software Foundation, Inc. -See the end of the file for license conditions. - - -README for Edition 2.9 of the Emacs Lisp Reference Manual. - -* This directory contains the texinfo source files for the Reference -Manual, make-permuted-index, and the latest version of texinfo.tex, -which handles forms that cannot be handled by the older versions of -texinfo.tex. - -* Report Lisp Manual bugs to bug-lisp-manual@gnu.org. We don't read -these bug reports until it's time for a new edition. To report other -Emacs bugs, use bug-gnu-emacs@gnu.org. To ask questions, use the -newsgroup gnu.emacs.help. - -* The Emacs Lisp Reference Manual is quite large. It totals around -1100 pages in smallbook format; the info files total over -2.5 megabytes. - -* You can format this manual either for Info or for printing hardcopy -using TeX. - -* You can buy nicely printed copies from the Free Software Foundation. -For info, send mail to gnu@gnu.org or phone 617-542-5942. Buying a -manual from the Free Software Foundation helps support our GNU -development work. - -** This distribution contains a Makefile that you can use with GNU Make. -Otherwise, here are detailed instructions: - -** HARDCOPY: A copy of the version of `texinfo.tex' that formats this -manual is included in this distribution. - -The master file for formatting this manual for Tex is called -`elisp.texi'. It contains @include commands to include all the -chapters that make up the manual. In addition, `elisp.texi' has -the title page in a new format designed by Karl Berry, using the -@titlespec command. - -To create a DVI file with a sorted index, execute the following -commands in the shell: - -% ./configure -% make index.texi -% make elisp.dvi - -*** To create a DVI file with a permuted index, you may experiment -with `make-permuted-index'. - -** To make an Info file, you need to install Texinfo, then run -`./configure' and `make info'. To install the Info files, run -`make install'. - - -This file is part of GNU Emacs. - -GNU Emacs is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 3, or (at your option) -any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs; see the file COPYING. If not, write to the -Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -Boston, MA 02110-1301, USA. diff --git a/lispref/abbrevs.texi b/lispref/abbrevs.texi deleted file mode 100644 index 46e7c3739c4..00000000000 --- a/lispref/abbrevs.texi +++ /dev/null @@ -1,411 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/abbrevs -@node Abbrevs, Processes, Syntax Tables, Top -@chapter Abbrevs and Abbrev Expansion -@cindex abbrev -@c @cindex abbrev table Redundant with "abbrev". - - An abbreviation or @dfn{abbrev} is a string of characters that may be -expanded to a longer string. The user can insert the abbrev string and -find it replaced automatically with the expansion of the abbrev. This -saves typing. - - The set of abbrevs currently in effect is recorded in an @dfn{abbrev -table}. Each buffer has a local abbrev table, but normally all buffers -in the same major mode share one abbrev table. There is also a global -abbrev table. Normally both are used. - - An abbrev table is represented as an obarray containing a symbol for -each abbreviation. The symbol's name is the abbreviation; its value -is the expansion; its function definition is the hook function to do -the expansion (@pxref{Defining Abbrevs}); its property list cell -typically contains the use count, the number of times the abbreviation -has been expanded. Alternatively, the use count is on the -@code{count} property and the system-abbrev flag is on the -@code{system-type} property. Abbrevs with a non-@code{nil} -@code{system-type} property are called ``system'' abbrevs. They are -usually defined by modes or packages, instead of by the user, and are -treated specially in certain respects. - -Because the symbols used for abbrevs are not interned in the usual -obarray, they will never appear as the result of reading a Lisp -expression; in fact, normally they are never used except by the code -that handles abbrevs. Therefore, it is safe to use them in an -extremely nonstandard way. @xref{Creating Symbols}. - - For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev -Mode, emacs, The GNU Emacs Manual}. - -@menu -* 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. -@end menu - -@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs -@comment node-name, next, previous, up -@section Setting Up Abbrev Mode - - Abbrev mode is a minor mode controlled by the value of the variable -@code{abbrev-mode}. - -@defvar abbrev-mode -A non-@code{nil} value of this variable turns on the automatic expansion -of abbrevs when their abbreviations are inserted into a buffer. -If the value is @code{nil}, abbrevs may be defined, but they are not -expanded automatically. - -This variable automatically becomes buffer-local when set in any fashion. -@end defvar - -@defvar default-abbrev-mode -This is the value of @code{abbrev-mode} for buffers that do not override it. -This is the same as @code{(default-value 'abbrev-mode)}. -@end defvar - -@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs -@section Abbrev Tables - - This section describes how to create and manipulate abbrev tables. - -@defun make-abbrev-table -This function creates and returns a new, empty abbrev table---an obarray -containing no symbols. It is a vector filled with zeros. -@end defun - -@defun clear-abbrev-table table -This function undefines all the abbrevs in abbrev table @var{table}, -leaving it empty. It always returns @code{nil}. -@end defun - -@defun copy-abbrev-table table -This function returns a copy of abbrev table @var{table}---a new -abbrev table that contains the same abbrev definitions. The only -difference between @var{table} and the returned copy is that this -function sets the property lists of all copied abbrevs to 0. -@end defun - -@defun define-abbrev-table tabname definitions -This function defines @var{tabname} (a symbol) as an abbrev table -name, i.e., as a variable whose value is an abbrev table. It defines -abbrevs in the table according to @var{definitions}, a list of -elements of the form @code{(@var{abbrevname} @var{expansion} -@var{hook} @var{usecount} @var{system-flag})}. If an element of -@var{definitions} has length less than five, omitted elements default -to @code{nil}. A value of @code{nil} for @var{usecount} is equivalent -to zero. The return value is always @code{nil}. - -If this function is called more than once for the same @var{tabname}, -subsequent calls add the definitions in @var{definitions} to -@var{tabname}, rather than overriding the entire original contents. -(A subsequent call only overrides abbrevs explicitly redefined or -undefined in @var{definitions}.) -@end defun - -@defvar abbrev-table-name-list -This is a list of symbols whose values are abbrev tables. -@code{define-abbrev-table} adds the new abbrev table name to this list. -@end defvar - -@defun insert-abbrev-table-description name &optional human -This function inserts before point a description of the abbrev table -named @var{name}. The argument @var{name} is a symbol whose value is an -abbrev table. The return value is always @code{nil}. - -If @var{human} is non-@code{nil}, the description is human-oriented. -System abbrevs are listed and identified as such. Otherwise the -description is a Lisp expression---a call to @code{define-abbrev-table} -that would define @var{name} as it is currently defined, but without -the system abbrevs. (The mode or package using @var{name} is supposed -to add these to @var{name} separately.) -@end defun - -@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs -@comment node-name, next, previous, up -@section Defining Abbrevs - @code{define-abbrev} is the low-level basic function for defining an -abbrev in a specified abbrev table. When major modes predefine standard -abbrevs, they should call @code{define-abbrev} and specify @code{t} for -@var{system-flag}. Be aware that any saved non-``system'' abbrevs are -restored at startup, i.e. before some major modes are loaded. Major modes -should therefore not assume that when they are first loaded their abbrev -tables are empty. - -@defun define-abbrev table name expansion &optional hook count system-flag -This function defines an abbrev named @var{name}, in @var{table}, to -expand to @var{expansion} and call @var{hook}. The return value is -@var{name}. - -The value of @var{count}, if specified, initializes the abbrev's -usage-count. If @var{count} is not specified or @code{nil}, the use -count is initialized to zero. - -The argument @var{name} should be a string. The argument -@var{expansion} is normally the desired expansion (a string), or -@code{nil} to undefine the abbrev. If it is anything but a string or -@code{nil}, then the abbreviation ``expands'' solely by running -@var{hook}. - -The argument @var{hook} is a function or @code{nil}. If @var{hook} is -non-@code{nil}, then it is called with no arguments after the abbrev is -replaced with @var{expansion}; point is located at the end of -@var{expansion} when @var{hook} is called. - -@cindex @code{no-self-insert} property -If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert} -property is non-@code{nil}, @var{hook} can explicitly control whether -to insert the self-inserting input character that triggered the -expansion. If @var{hook} returns non-@code{nil} in this case, that -inhibits insertion of the character. By contrast, if @var{hook} -returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as -if expansion had not really occurred. - -If @var{system-flag} is non-@code{nil}, that marks the abbrev as a -``system'' abbrev with the @code{system-type} property. Unless -@var{system-flag} has the value @code{force}, a ``system'' abbrev will -not overwrite an existing definition for a non-``system'' abbrev of the -same name. - -Normally the function @code{define-abbrev} sets the variable -@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev. -(This is so that some commands will offer to save the abbrevs.) It -does not do this for a ``system'' abbrev, since those won't be saved -anyway. -@end defun - -@defopt only-global-abbrevs -If this variable is non-@code{nil}, it means that the user plans to use -global abbrevs only. This tells the commands that define mode-specific -abbrevs to define global ones instead. This variable does not alter the -behavior of the functions in this section; it is examined by their -callers. -@end defopt - -@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs -@section Saving Abbrevs in Files - - A file of saved abbrev definitions is actually a file of Lisp code. -The abbrevs are saved in the form of a Lisp program to define the same -abbrev tables with the same contents. Therefore, you can load the file -with @code{load} (@pxref{How Programs Do Loading}). However, the -function @code{quietly-read-abbrev-file} is provided as a more -convenient interface. - - User-level facilities such as @code{save-some-buffers} can save -abbrevs in a file automatically, under the control of variables -described here. - -@defopt abbrev-file-name -This is the default file name for reading and saving abbrevs. -@end defopt - -@defun quietly-read-abbrev-file &optional filename -This function reads abbrev definitions from a file named @var{filename}, -previously written with @code{write-abbrev-file}. If @var{filename} is -omitted or @code{nil}, the file specified in @code{abbrev-file-name} is -used. @code{save-abbrevs} is set to @code{t} so that changes will be -saved. - -This function does not display any messages. It returns @code{nil}. -@end defun - -@defopt save-abbrevs -A non-@code{nil} value for @code{save-abbrevs} means that Emacs should -offer the user to save abbrevs when files are saved. If the value is -@code{silently}, Emacs saves the abbrevs without asking the user. -@code{abbrev-file-name} specifies the file to save the abbrevs in. -@end defopt - -@defvar abbrevs-changed -This variable is set non-@code{nil} by defining or altering any -abbrevs (except ``system'' abbrevs). This serves as a flag for -various Emacs commands to offer to save your abbrevs. -@end defvar - -@deffn Command write-abbrev-file &optional filename -Save all abbrev definitions (except ``system'' abbrevs), for all abbrev -tables listed in @code{abbrev-table-name-list}, in the file -@var{filename}, in the form of a Lisp program that when loaded will -define the same abbrevs. If @var{filename} is @code{nil} or omitted, -@code{abbrev-file-name} is used. This function returns @code{nil}. -@end deffn - -@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs -@comment node-name, next, previous, up -@section Looking Up and Expanding Abbreviations - - Abbrevs are usually expanded by certain interactive commands, -including @code{self-insert-command}. This section describes the -subroutines used in writing such commands, as well as the variables they -use for communication. - -@defun abbrev-symbol abbrev &optional table -This function returns the symbol representing the abbrev named -@var{abbrev}. The value returned is @code{nil} if that abbrev is not -defined. The optional second argument @var{table} is the abbrev table -to look it up in. If @var{table} is @code{nil}, this function tries -first the current buffer's local abbrev table, and second the global -abbrev table. -@end defun - -@defun abbrev-expansion abbrev &optional table -This function returns the string that @var{abbrev} would expand into (as -defined by the abbrev tables used for the current buffer). If -@var{abbrev} is not a valid abbrev, the function returns @code{nil}. -The optional argument @var{table} specifies the abbrev table to use, -as in @code{abbrev-symbol}. -@end defun - -@deffn Command expand-abbrev -This command expands the abbrev before point, if any. If point does not -follow an abbrev, this command does nothing. The command returns the -abbrev symbol if it did expansion, @code{nil} otherwise. - -If the abbrev symbol has a hook function which is a symbol whose -@code{no-self-insert} property is non-@code{nil}, and if the hook -function returns @code{nil} as its value, then @code{expand-abbrev} -returns @code{nil} even though expansion did occur. -@end deffn - -@deffn Command abbrev-prefix-mark &optional arg -This command marks the current location of point as the beginning of -an abbrev. The next call to @code{expand-abbrev} will use the text -from here to point (where it is then) as the abbrev to expand, rather -than using the previous word as usual. - -First, this command expands any abbrev before point, unless @var{arg} -is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.) -Then it inserts a hyphen before point, to indicate the start of the -next abbrev to be expanded. The actual expansion removes the hyphen. -@end deffn - -@defopt abbrev-all-caps -When this is set non-@code{nil}, an abbrev entered entirely in upper -case is expanded using all upper case. Otherwise, an abbrev entered -entirely in upper case is expanded by capitalizing each word of the -expansion. -@end defopt - -@defvar abbrev-start-location -The value of this variable is a buffer position (an integer or a marker) -for @code{expand-abbrev} to use as the start of the next abbrev to be -expanded. The value can also be @code{nil}, which means to use the -word before point instead. @code{abbrev-start-location} is set to -@code{nil} each time @code{expand-abbrev} is called. This variable is -also set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar abbrev-start-location-buffer -The value of this variable is the buffer for which -@code{abbrev-start-location} has been set. Trying to expand an abbrev -in any other buffer clears @code{abbrev-start-location}. This variable -is set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar last-abbrev -This is the @code{abbrev-symbol} of the most recent abbrev expanded. This -information is left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding -Abbrevs, emacs, The GNU Emacs Manual}). -@end defvar - -@defvar last-abbrev-location -This is the location of the most recent abbrev expanded. This contains -information left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command. -@end defvar - -@defvar last-abbrev-text -This is the exact expansion text of the most recent abbrev expanded, -after case conversion (if any). Its value is @code{nil} if the abbrev -has already been unexpanded. This contains information left by -@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. -@end defvar - -@c Emacs 19 feature -@defvar pre-abbrev-expand-hook -This is a normal hook whose functions are executed, in sequence, just -before any expansion of an abbrev. @xref{Hooks}. Since it is a normal -hook, the hook functions receive no arguments. However, they can find -the abbrev to be expanded by looking in the buffer before point. -Running the hook is the first thing that @code{expand-abbrev} does, and -so a hook function can be used to change the current abbrev table before -abbrev lookup happens. (Although you have to do this carefully. See -the example below.) -@end defvar - - The following sample code shows a simple use of -@code{pre-abbrev-expand-hook}. It assumes that @code{foo-mode} is a -mode for editing certain files in which lines that start with @samp{#} -are comments. You want to use Text mode abbrevs for those lines. The -regular local abbrev table, @code{foo-mode-abbrev-table} is -appropriate for all other lines. Then you can put the following code -in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the -definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. - -@smallexample -(defun foo-mode-pre-abbrev-expand () - (when (save-excursion (forward-line 0) (eq (char-after) ?#)) - (let ((local-abbrev-table text-mode-abbrev-table) - ;; Avoid infinite loop. - (pre-abbrev-expand-hook nil)) - (expand-abbrev)) - ;; We have already called `expand-abbrev' in this hook. - ;; Hence we want the "actual" call following this hook to be a no-op. - (setq abbrev-start-location (point-max) - abbrev-start-location-buffer (current-buffer)))) - -(add-hook 'foo-mode-hook - #'(lambda () - (add-hook 'pre-abbrev-expand-hook - 'foo-mode-pre-abbrev-expand - nil t))) -@end smallexample - -Note that @code{foo-mode-pre-abbrev-expand} just returns @code{nil} -without doing anything for lines not starting with @samp{#}. Hence -abbrevs expand normally using @code{foo-mode-abbrev-table} as local -abbrev table for such lines. - -@node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs -@comment node-name, next, previous, up -@section Standard Abbrev Tables - - Here we list the variables that hold the abbrev tables for the -preloaded major modes of Emacs. - -@defvar global-abbrev-table -This is the abbrev table for mode-independent abbrevs. The abbrevs -defined in it apply to all buffers. Each buffer may also have a local -abbrev table, whose abbrev definitions take precedence over those in the -global table. -@end defvar - -@defvar local-abbrev-table -The value of this buffer-local variable is the (mode-specific) -abbreviation table of the current buffer. -@end defvar - -@defvar fundamental-mode-abbrev-table -This is the local abbrev table used in Fundamental mode; in other words, -it is the local abbrev table in all buffers in Fundamental mode. -@end defvar - -@defvar text-mode-abbrev-table -This is the local abbrev table used in Text mode. -@end defvar - -@defvar lisp-mode-abbrev-table -This is the local abbrev table used in Lisp mode and Emacs Lisp mode. -@end defvar - -@ignore - arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec -@end ignore diff --git a/lispref/advice.texi b/lispref/advice.texi deleted file mode 100644 index 4d580f9846d..00000000000 --- a/lispref/advice.texi +++ /dev/null @@ -1,773 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/advising -@node Advising Functions, Debugging, Byte Compilation, Top -@chapter Advising Emacs Lisp Functions -@cindex advising functions - - The @dfn{advice} feature lets you add to the existing definition of -a function, by @dfn{advising the function}. This is a cleaner method -for a library to customize functions defined within Emacs---cleaner -than redefining the whole function. - -@cindex piece of advice - Each function can have multiple @dfn{pieces of advice}, separately -defined. Each defined piece of advice can be @dfn{enabled} or -@dfn{disabled} explicitly. All the enabled pieces of advice for any given -function actually take effect when you @dfn{activate} advice for that -function, or when you define or redefine the function. Note that -enabling a piece of advice and activating advice for a function -are not the same thing. - - @strong{Usage Note:} Advice is useful for altering the behavior of -existing calls to an existing function. If you want the new behavior -for new calls, or for key bindings, you should define a new function -(or a new command) which uses the existing function. - - @strong{Usage note:} Advising a function can cause confusion in -debugging, since people who debug calls to the original function may -not notice that it has been modified with advice. Therefore, if you -have the possibility to change the code of that function (or ask -someone to do so) to run a hook, please solve the problem that way. -Advice should be reserved for the cases where you cannot get the -function changed. - - In particular, this means that a file in Emacs should not put advice -on a function in Emacs. There are currently a few exceptions to this -convention, but we aim to correct them. - -@menu -* 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. -@end menu - -@node Simple Advice -@section A Simple Advice Example - - The command @code{next-line} moves point down vertically one or more -lines; it is the standard binding of @kbd{C-n}. When used on the last -line of the buffer, this command inserts a newline to create a line to -move to if @code{next-line-add-newlines} is non-@code{nil} (its default -is @code{nil}.) - - Suppose you wanted to add a similar feature to @code{previous-line}, -which would insert a new line at the beginning of the buffer for the -command to move to (when @code{next-line-add-newlines} is -non-@code{nil}). How could you do this? - - You could do it by redefining the whole function, but that is not -modular. The advice feature provides a cleaner alternative: you can -effectively add your code to the existing function definition, without -actually changing or even seeing that definition. Here is how to do -this: - -@example -(defadvice previous-line (before next-line-at-end - (&optional arg try-vscroll)) - "Insert an empty line when moving up from the top line." - (if (and next-line-add-newlines (= arg 1) - (save-excursion (beginning-of-line) (bobp))) - (progn - (beginning-of-line) - (newline)))) -@end example - - This expression defines a @dfn{piece of advice} for the function -@code{previous-line}. This piece of advice is named -@code{next-line-at-end}, and the symbol @code{before} says that it is -@dfn{before-advice} which should run before the regular definition of -@code{previous-line}. @code{(&optional arg try-vscroll)} specifies -how the advice code can refer to the function's arguments. - - When this piece of advice runs, it creates an additional line, in the -situation where that is appropriate, but does not move point to that -line. This is the correct way to write the advice, because the normal -definition will run afterward and will move back to the newly inserted -line. - - Defining the advice doesn't immediately change the function -@code{previous-line}. That happens when you @dfn{activate} the advice, -like this: - -@example -(ad-activate 'previous-line) -@end example - -@noindent -This is what actually begins to use the advice that has been defined so -far for the function @code{previous-line}. Henceforth, whenever that -function is run, whether invoked by the user with @kbd{C-p} or -@kbd{M-x}, or called from Lisp, it runs the advice first, and its -regular definition second. - - This example illustrates before-advice, which is one @dfn{class} of -advice: it runs before the function's base definition. There are two -other advice classes: @dfn{after-advice}, which runs after the base -definition, and @dfn{around-advice}, which lets you specify an -expression to wrap around the invocation of the base definition. - -@node Defining Advice -@section Defining Advice -@cindex defining advice -@cindex advice, defining - - To define a piece of advice, use the macro @code{defadvice}. A call -to @code{defadvice} has the following syntax, which is based on the -syntax of @code{defun} and @code{defmacro}, but adds more: - -@findex defadvice -@example -(defadvice @var{function} (@var{class} @var{name} - @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]} - @var{flags}...) - @r{[}@var{documentation-string}@r{]} - @r{[}@var{interactive-form}@r{]} - @var{body-forms}...) -@end example - -@noindent -Here, @var{function} is the name of the function (or macro or special -form) to be advised. From now on, we will write just ``function'' when -describing the entity being advised, but this always includes macros and -special forms. - - In place of the argument list in an ordinary definition, an advice -definition calls for several different pieces of information. - -@cindex class of advice -@cindex before-advice -@cindex after-advice -@cindex around-advice -@var{class} specifies the @dfn{class} of the advice---one of @code{before}, -@code{after}, or @code{around}. Before-advice runs before the function -itself; after-advice runs after the function itself; around-advice is -wrapped around the execution of the function itself. After-advice and -around-advice can override the return value by setting -@code{ad-return-value}. - -@defvar ad-return-value -While advice is executing, after the function's original definition has -been executed, this variable holds its return value, which will -ultimately be returned to the caller after finishing all the advice. -After-advice and around-advice can arrange to return some other value -by storing it in this variable. -@end defvar - -The argument @var{name} is the name of the advice, a non-@code{nil} -symbol. The advice name uniquely identifies one piece of advice, within all -the pieces of advice in a particular class for a particular -@var{function}. The name allows you to refer to the piece of -advice---to redefine it, or to enable or disable it. - -The optional @var{position} specifies where, in the current list of -advice of the specified @var{class}, this new advice should be placed. -It should be either @code{first}, @code{last} or a number that specifies -a zero-based position (@code{first} is equivalent to 0). If no position -is specified, the default is @code{first}. Position values outside the -range of existing positions in this class are mapped to the beginning or -the end of the range, whichever is closer. The @var{position} value is -ignored when redefining an existing piece of advice. - -The optional @var{arglist} can be used to define the argument list for -the sake of advice. This becomes the argument list of the combined -definition that is generated in order to run the advice (@pxref{Combined -Definition}). Therefore, the advice expressions can use the argument -variables in this list to access argument values. - -The argument list used in advice need not be the same as the argument -list used in the original function, but must be compatible with it, so -that it can handle the ways the function is actually called. If two -pieces of advice for a function both specify an argument list, they must -specify the same argument list. - -@xref{Argument Access in Advice}, for more information about argument -lists and advice, and a more flexible way for advice to access the -arguments. - -The remaining elements, @var{flags}, are symbols that specify further -information about how to use this piece of advice. Here are the valid -symbols and their meanings: - -@table @code -@item activate -Activate the advice for @var{function} now. Changes in a function's -advice always take effect the next time you activate advice for the -function; this flag says to do so, for @var{function}, immediately after -defining this piece of advice. - -@cindex forward advice -This flag has no immediate effect if @var{function} itself is not defined yet (a -situation known as @dfn{forward advice}), because it is impossible to -activate an undefined function's advice. However, defining -@var{function} will automatically activate its advice. - -@item protect -Protect this piece of advice against non-local exits and errors in -preceding code and advice. Protecting advice places it as a cleanup in -an @code{unwind-protect} form, so that it will execute even if the -previous code gets an error or uses @code{throw}. @xref{Cleanups}. - -@item compile -Compile the combined definition that is used to run the advice. This -flag is ignored unless @code{activate} is also specified. -@xref{Combined Definition}. - -@item disable -Initially disable this piece of advice, so that it will not be used -unless subsequently explicitly enabled. @xref{Enabling Advice}. - -@item preactivate -Activate advice for @var{function} when this @code{defadvice} is -compiled or macroexpanded. This generates a compiled advised definition -according to the current advice state, which will be used during -activation if appropriate. @xref{Preactivation}. - -This is useful only if this @code{defadvice} is byte-compiled. -@end table - -The optional @var{documentation-string} serves to document this piece of -advice. When advice is active for @var{function}, the documentation for -@var{function} (as returned by @code{documentation}) combines the -documentation strings of all the advice for @var{function} with the -documentation string of its original function definition. - -The optional @var{interactive-form} form can be supplied to change the -interactive behavior of the original function. If more than one piece -of advice has an @var{interactive-form}, then the first one (the one -with the smallest position) found among all the advice takes precedence. - -The possibly empty list of @var{body-forms} specifies the body of the -advice. The body of an advice can access or change the arguments, the -return value, the binding environment, and perform any other kind of -side effect. - -@strong{Warning:} When you advise a macro, keep in mind that macros are -expanded when a program is compiled, not when a compiled program is run. -All subroutines used by the advice need to be available when the byte -compiler expands the macro. - -@deffn Command ad-unadvise function -This command deletes the advice from @var{function}. -@end deffn - -@deffn Command ad-unadvise-all -This command deletes all pieces of advice from all functions. -@end deffn - -@node Around-Advice -@section Around-Advice - - Around-advice lets you ``wrap'' a Lisp expression ``around'' the -original function definition. You specify where the original function -definition should go by means of the special symbol @code{ad-do-it}. -Where this symbol occurs inside the around-advice body, it is replaced -with a @code{progn} containing the forms of the surrounded code. Here -is an example: - -@example -(defadvice foo (around foo-around) - "Ignore case in `foo'." - (let ((case-fold-search t)) - ad-do-it)) -@end example - -@noindent -Its effect is to make sure that case is ignored in -searches when the original definition of @code{foo} is run. - -@defvar ad-do-it -This is not really a variable, rather a place-holder that looks like a -variable. You use it in around-advice to specify the place to run the -function's original definition and other ``earlier'' around-advice. -@end defvar - -If the around-advice does not use @code{ad-do-it}, then it does not run -the original function definition. This provides a way to override the -original definition completely. (It also overrides lower-positioned -pieces of around-advice). - -If the around-advice uses @code{ad-do-it} more than once, the original -definition is run at each place. In this way, around-advice can execute -the original definition (and lower-positioned pieces of around-advice) -several times. Another way to do that is by using @code{ad-do-it} -inside of a loop. - -@node Computed Advice -@section Computed Advice - -The macro @code{defadvice} resembles @code{defun} in that the code for -the advice, and all other information about it, are explicitly stated in -the source code. You can also create advice whose details are computed, -using the function @code{ad-add-advice}. - -@defun ad-add-advice function advice class position -Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to -@var{function} in class @var{class}. The argument @var{advice} has -this form: - -@example -(@var{name} @var{protected} @var{enabled} @var{definition}) -@end example - -Here @var{protected} and @var{enabled} are flags, and @var{definition} -is the expression that says what the advice should do. If @var{enabled} -is @code{nil}, this piece of advice is initially disabled -(@pxref{Enabling Advice}). - -If @var{function} already has one or more pieces of advice in the -specified @var{class}, then @var{position} specifies where in the list -to put the new piece of advice. The value of @var{position} can either -be @code{first}, @code{last}, or a number (counting from 0 at the -beginning of the list). Numbers outside the range are mapped to the -beginning or the end of the range, whichever is closer. The -@var{position} value is ignored when redefining an existing piece of -advice. - -If @var{function} already has a piece of @var{advice} with the same -name, then the position argument is ignored and the old advice is -replaced with the new one. -@end defun - -@node Activation of Advice -@section Activation of Advice -@cindex activating advice -@cindex advice, activating - -By default, advice does not take effect when you define it---only when -you @dfn{activate} advice for the function that was advised. However, -the advice will be activated automatically if you define or redefine -the function later. You can request the activation of advice for a -function when you define the advice, by specifying the @code{activate} -flag in the @code{defadvice}. But normally you activate the advice -for a function by calling the function @code{ad-activate} or one of -the other activation commands listed below. - -Separating the activation of advice from the act of defining it permits -you to add several pieces of advice to one function efficiently, without -redefining the function over and over as each advice is added. More -importantly, it permits defining advice for a function before that -function is actually defined. - -When a function's advice is first activated, the function's original -definition is saved, and all enabled pieces of advice for that function -are combined with the original definition to make a new definition. -(Pieces of advice that are currently disabled are not used; see -@ref{Enabling Advice}.) This definition is installed, and optionally -byte-compiled as well, depending on conditions described below. - -In all of the commands to activate advice, if @var{compile} is -@code{t} (or anything but @code{nil} or a negative number), the -command also compiles the combined definition which implements the -advice. If it is @code{nil} or a negative number, what happens -depends on @code{ad-default-compilation-action} as described below. - -@deffn Command ad-activate function &optional compile -This command activates all the advice defined for @var{function}. -@end deffn - - Activating advice does nothing if @var{function}'s advice is already -active. But if there is new advice, added since the previous time you -activated advice for @var{function}, it activates the new advice. - -@deffn Command ad-deactivate function -This command deactivates the advice for @var{function}. -@cindex deactivating advice -@c @cindex advice, deactivating "advice, activating" is just above -@end deffn - -@deffn Command ad-update function &optional compile -This command activates the advice for @var{function} -if its advice is already activated. This is useful -if you change the advice. -@end deffn - -@deffn Command ad-activate-all &optional compile -This command activates the advice for all functions. -@end deffn - -@deffn Command ad-deactivate-all -This command deactivates the advice for all functions. -@end deffn - -@deffn Command ad-update-all &optional compile -This command activates the advice for all functions -whose advice is already activated. This is useful -if you change the advice of some functions. -@end deffn - -@deffn Command ad-activate-regexp regexp &optional compile -This command activates all pieces of advice whose names match -@var{regexp}. More precisely, it activates all advice for any function -which has at least one piece of advice that matches @var{regexp}. -@end deffn - -@deffn Command ad-deactivate-regexp regexp -This command deactivates all pieces of advice whose names match -@var{regexp}. More precisely, it deactivates all advice for any -function which has at least one piece of advice that matches -@var{regexp}. -@end deffn - -@deffn Command ad-update-regexp regexp &optional compile -This command activates pieces of advice whose names match @var{regexp}, -but only those for functions whose advice is already activated. -@cindex reactivating advice - -Reactivating a function's advice is useful for putting into effect all -the changes that have been made in its advice (including enabling and -disabling specific pieces of advice; @pxref{Enabling Advice}) since the -last time it was activated. -@end deffn - -@deffn Command ad-start-advice -Turn on automatic advice activation when a function is defined or -redefined. This is the default mode. -@end deffn - -@deffn Command ad-stop-advice -Turn off automatic advice activation when a function is defined or -redefined. -@end deffn - -@defopt ad-default-compilation-action -This variable controls whether to compile the combined definition -that results from activating advice for a function. - -A value of @code{always} specifies to compile unconditionally. -A value of @code{never} specifies never compile the advice. - -A value of @code{maybe} specifies to compile if the byte-compiler is -already loaded. A value of @code{like-original} specifies to compile -the advice if the original definition of the advised function is -compiled or a built-in function. - -This variable takes effect only if the @var{compile} argument of -@code{ad-activate} (or any of the above functions) did not force -compilation. -@end defopt - - If the advised definition was constructed during ``preactivation'' -(@pxref{Preactivation}), then that definition must already be compiled, -because it was constructed during byte-compilation of the file that -contained the @code{defadvice} with the @code{preactivate} flag. - -@node Enabling Advice -@section Enabling and Disabling Advice -@cindex enabling advice -@cindex advice, enabling and disabling -@cindex disabling advice - - Each piece of advice has a flag that says whether it is enabled or -not. By enabling or disabling a piece of advice, you can turn it on -and off without having to undefine and redefine it. For example, here is -how to disable a particular piece of advice named @code{my-advice} for -the function @code{foo}: - -@example -(ad-disable-advice 'foo 'before 'my-advice) -@end example - - This function by itself only changes the enable flag for a piece of -advice. To make the change take effect in the advised definition, you -must activate the advice for @code{foo} again: - -@example -(ad-activate 'foo) -@end example - -@deffn Command ad-disable-advice function class name -This command disables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - -@deffn Command ad-enable-advice function class name -This command enables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - - You can also disable many pieces of advice at once, for various -functions, using a regular expression. As always, the changes take real -effect only when you next reactivate advice for the functions in -question. - -@deffn Command ad-disable-regexp regexp -This command disables all pieces of advice whose names match -@var{regexp}, in all classes, on all functions. -@end deffn - -@deffn Command ad-enable-regexp regexp -This command enables all pieces of advice whose names match -@var{regexp}, in all classes, on all functions. -@end deffn - -@node Preactivation -@section Preactivation -@cindex preactivating advice -@cindex advice, preactivating - - Constructing a combined definition to execute advice is moderately -expensive. When a library advises many functions, this can make loading -the library slow. In that case, you can use @dfn{preactivation} to -construct suitable combined definitions in advance. - - To use preactivation, specify the @code{preactivate} flag when you -define the advice with @code{defadvice}. This @code{defadvice} call -creates a combined definition which embodies this piece of advice -(whether enabled or not) plus any other currently enabled advice for the -same function, and the function's own definition. If the -@code{defadvice} is compiled, that compiles the combined definition -also. - - When the function's advice is subsequently activated, if the enabled -advice for the function matches what was used to make this combined -definition, then the existing combined definition is used, thus avoiding -the need to construct one. Thus, preactivation never causes wrong -results---but it may fail to do any good, if the enabled advice at the -time of activation doesn't match what was used for preactivation. - - Here are some symptoms that can indicate that a preactivation did not -work properly, because of a mismatch. - -@itemize @bullet -@item -Activation of the advised -function takes longer than usual. -@item -The byte-compiler gets -loaded while an advised function gets activated. -@item -@code{byte-compile} is included in the value of @code{features} even -though you did not ever explicitly use the byte-compiler. -@end itemize - -Compiled preactivated advice works properly even if the function itself -is not defined until later; however, the function needs to be defined -when you @emph{compile} the preactivated advice. - -There is no elegant way to find out why preactivated advice is not being -used. What you can do is to trace the function -@code{ad-cache-id-verification-code} (with the function -@code{trace-function-background}) before the advised function's advice -is activated. After activation, check the value returned by -@code{ad-cache-id-verification-code} for that function: @code{verified} -means that the preactivated advice was used, while other values give -some information about why they were considered inappropriate. - - @strong{Warning:} There is one known case that can make preactivation -fail, in that a preconstructed combined definition is used even though -it fails to match the current state of advice. This can happen when two -packages define different pieces of advice with the same name, in the -same class, for the same function. But you should avoid that anyway. - -@node Argument Access in Advice -@section Argument Access in Advice - - The simplest way to access the arguments of an advised function in the -body of a piece of advice is to use the same names that the function -definition uses. To do this, you need to know the names of the argument -variables of the original function. - - While this simple method is sufficient in many cases, it has a -disadvantage: it is not robust, because it hard-codes the argument names -into the advice. If the definition of the original function changes, -the advice might break. - - Another method is to specify an argument list in the advice itself. -This avoids the need to know the original function definition's argument -names, but it has a limitation: all the advice on any particular -function must use the same argument list, because the argument list -actually used for all the advice comes from the first piece of advice -for that function. - - A more robust method is to use macros that are translated into the -proper access forms at activation time, i.e., when constructing the -advised definition. Access macros access actual arguments by position -regardless of how these actual arguments get distributed onto the -argument variables of a function. This is robust because in Emacs Lisp -the meaning of an argument is strictly determined by its position in the -argument list. - -@defmac ad-get-arg position -This returns the actual argument that was supplied at @var{position}. -@end defmac - -@defmac ad-get-args position -This returns the list of actual arguments supplied starting at -@var{position}. -@end defmac - -@defmac ad-set-arg position value -This sets the value of the actual argument at @var{position} to -@var{value} -@end defmac - -@defmac ad-set-args position value-list -This sets the list of actual arguments starting at @var{position} to -@var{value-list}. -@end defmac - - Now an example. Suppose the function @code{foo} is defined as - -@example -(defun foo (x y &optional z &rest r) ...) -@end example - -@noindent -and is then called with - -@example -(foo 0 1 2 3 4 5 6) -@end example - -@noindent -which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is -@code{(3 4 5 6)} within the body of @code{foo}. Here is what -@code{ad-get-arg} and @code{ad-get-args} return in this case: - -@example -(ad-get-arg 0) @result{} 0 -(ad-get-arg 1) @result{} 1 -(ad-get-arg 2) @result{} 2 -(ad-get-arg 3) @result{} 3 -(ad-get-args 2) @result{} (2 3 4 5 6) -(ad-get-args 4) @result{} (4 5 6) -@end example - - Setting arguments also makes sense in this example: - -@example -(ad-set-arg 5 "five") -@end example - -@noindent -has the effect of changing the sixth argument to @code{"five"}. If this -happens in advice executed before the body of @code{foo} is run, then -@var{r} will be @code{(3 4 "five" 6)} within that body. - - Here is an example of setting a tail of the argument list: - -@example -(ad-set-args 0 '(5 4 3 2 1 0)) -@end example - -@noindent -If this happens in advice executed before the body of @code{foo} is run, -then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} -will be 3, and @var{r} will be @code{(2 1 0)} inside the body of -@code{foo}. - - These argument constructs are not really implemented as Lisp macros. -Instead they are implemented specially by the advice mechanism. - -@node Advising Primitives -@section Advising Primitives -@cindex advising primitives - - Advising a primitive function (also called a ``subr'') is risky. -Some primitive functions are used by the advice mechanism; advising -them could cause an infinite recursion. Also, many primitive -functions are called directly from C code. Calls to the primitive -from Lisp code will take note of the advice, but calls from C code -will ignore the advice. - -When the advice facility constructs the combined definition, it needs -to know the argument list of the original function. This is not -always possible for primitive functions. When advice cannot determine -the argument list, it uses @code{(&rest ad-subr-args)}, which always -works but is inefficient because it constructs a list of the argument -values. You can use @code{ad-define-subr-args} to declare the proper -argument names for a primitive function: - -@defun ad-define-subr-args function arglist -This function specifies that @var{arglist} should be used as the -argument list for function @var{function}. -@end defun - -For example, - -@example -(ad-define-subr-args 'fset '(sym newdef)) -@end example - -@noindent -specifies the argument list for the function @code{fset}. - -@node Combined Definition -@section The Combined Definition - - Suppose that a function has @var{n} pieces of before-advice -(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of -around-advice and @var{k} pieces of after-advice. Assuming no piece -of advice is protected, the combined definition produced to implement -the advice for a function looks like this: - -@example -(lambda @var{arglist} - @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} - (let (ad-return-value) - @r{before-0-body-form}... - .... - @r{before-@var{n}@minus{}1-body-form}... - @r{around-0-body-form}... - @r{around-1-body-form}... - .... - @r{around-@var{m}@minus{}1-body-form}... - (setq ad-return-value - @r{apply original definition to @var{arglist}}) - @r{end-of-around-@var{m}@minus{}1-body-form}... - .... - @r{end-of-around-1-body-form}... - @r{end-of-around-0-body-form}... - @r{after-0-body-form}... - .... - @r{after-@var{k}@minus{}1-body-form}... - ad-return-value)) -@end example - -Macros are redefined as macros, which means adding @code{macro} to -the beginning of the combined definition. - -The interactive form is present if the original function or some piece -of advice specifies one. When an interactive primitive function is -advised, advice uses a special method: it calls the primitive with -@code{call-interactively} so that it will read its own arguments. -In this case, the advice cannot access the arguments. - -The body forms of the various advice in each class are assembled -according to their specified order. The forms of around-advice @var{l} -are included in one of the forms of around-advice @var{l} @minus{} 1. - -The innermost part of the around advice onion is - -@display -apply original definition to @var{arglist} -@end display - -@noindent -whose form depends on the type of the original function. The variable -@code{ad-return-value} is set to whatever this returns. The variable is -visible to all pieces of advice, which can access and modify it before -it is actually returned from the advised function. - -The semantic structure of advised functions that contain protected -pieces of advice is the same. The only difference is that -@code{unwind-protect} forms ensure that the protected advice gets -executed even if some previous piece of advice had an error or a -non-local exit. If any around-advice is protected, then the whole -around-advice onion is protected as a result. - -@ignore - arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f -@end ignore diff --git a/lispref/anti.texi b/lispref/anti.texi deleted file mode 100644 index 1ec0c5ef327..00000000000 --- a/lispref/anti.texi +++ /dev/null @@ -1,453 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2002, 2003, 2004, 2005, -@c 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. - -@c This node must have no pointers. - -@node Antinews, GNU Free Documentation License, System Interface, Top -@appendix Emacs 21 Antinews - -For those users who live backwards in time, here is information about -downgrading to Emacs version 21.4. We hope you will enjoy the greater -simplicity that results from the absence of many Emacs @value{EMACSVER} -features. - -@section Old Lisp Features in Emacs 21 - -@itemize @bullet -@item -Many unnecessary features of redisplay have been eliminated. (The -earlier major release, Emacs 20, will have a completely rewritten -redisplay engine, which will be even simpler.) - -@itemize @minus -@item -The function @code{redisplay} has been removed. To update the display -without delay, call @code{(sit-for 0)}. Since it is generally -considered wasteful to update the display if there are any pending -input events, no replacement for @code{(redisplay t)} is provided. - -@item -The function @code{force-window-update} has been removed. It -shouldn't be needed, since changes in window contents are detected -automatically. In case they aren't, call @code{redraw-display} to -redraw everything. - -@item -Point no longer moves out from underneath invisible text at the end of -each command. This allows the user to detect invisible text by moving -the cursor around---if the cursor gets stuck, there is something -invisible in the way. If you really want cursor motion to ignore the -text, try marking it as intangible. - -@item -Support for image maps and image slices has been removed. Emacs was -always meant for editing text, anyway. - -@item -The mode line now accepts all text properties, as well as -@code{:propertize} and @code{:eval} forms, regardless of the -@code{risky-local-variable} property. - -@item -The @code{line-height} and @code{line-spacing} properties no longer -have any meaning for newline characters. Such properties wouldn't -make sense, since newlines are not really characters; they just tell -you where to break a line. - -@item -Considerable simplifications have been made to the display -specification @code{(space . @var{props})}, which is used for -displaying a space of specified width and height. Pixel-based -specifications and Lisp expressions are no longer accepted. - -@item -Many features associated with the fringe areas have been removed, to -encourage people to concentrate on the main editing area (the fringe -will be completely removed in Emacs 20.) Arbitrary bitmaps can no -longer be displayed in the fringe; an overlay arrow can still be -displayed, but there can only be one overlay arrow at a time (any more -would be confusing.) The fringe widths cannot be adjusted, and -individual windows cannot have their own fringe settings. A mouse -click on the fringe no longer generates a special event. - -@item -Individual windows cannot have their own scroll-bar settings. - -@item -You can no longer use @samp{default} in a @code{defface} to specify -defaults for subsequent faces. - -@item -The function @code{display-supports-face-attributes-p} has been -removed. In @code{defface} specifications, the @code{supports} -predicate is no longer supported. - -@item -The functions @code{merge-face-attribute} and -@code{face-attribute-relative-p} have been removed. - -@item -The priority of faces in a list supplied by the @code{:inherit} face -attribute has been reversed. We like to make changes like this once -in a while, to keep Emacs Lisp programmers on their toes. - -@item -The @code{min-colors} face attribute, used for tailoring faces to -limited-color displays, does not exist. If in doubt, use colors like -``white'' and ``black,'' which ought to be defined everywhere. - -@item -The @code{tty-color-mode} frame parameter does not exist. You should -just trust the terminal capabilities database. -@end itemize - -@item -Several simplifications have been made to mouse support: - -@itemize @minus -@item -Clicking @kbd{mouse-1} won't follow links, as that is alien to the -spirit of Emacs. Therefore, the @code{follow-link} property doesn't -have any special meaning, and the function @code{mouse-on-link-p} has -been removed. - -@item -The variable @code{void-text-area-pointer} has been removed, so the -mouse pointer shape remains unchanged when moving between valid text -areas and void text areas. The @code{pointer} image and text -properties are no longer supported. - -@item -Mouse events will no longer specify the timestamp, the object clicked, -equivalent buffer positions (for marginal or fringe areas), glyph -coordinates, or relative pixel coordinates. -@end itemize - -@item -Simplifications have also been made to the way Emacs handles keymaps -and key sequences: - -@itemize @minus -@item -The @code{kbd} macro is now obsolete and is no longer documented. -It isn't that difficult to write key sequences using the string and -vector representations, and we want to encourage users to learn. - -@item -Emacs no longer supports key remapping. You can do pretty much the -same thing with @code{substitute-key-definition}, or by advising the -relevant command. - -@item -The @code{keymap} text and overlay property is now overridden by minor -mode keymaps, and will not work at the ends of text properties and -overlays. - -@item -The functions @code{map-keymap}, @code{keymap-prompt}, and -@code{current-active-maps} have been removed. -@end itemize - -@item -Process support has been pared down to a functional minimum. The -functions @code{call-process-shell-command} and @code{process-file} -have been deleted. Processes no longer maintain property lists, and -they won't ask any questions when the user tries to exit Emacs (which -would simply be rude.) The function @code{signal-process} won't -accept a process object, only the process id; determining the process -id from a process object is left as an exercise to the programmer. - -@item -Networking has also been simplified: @code{make-network-process} and -its various associated function have all been replaced with a single -easy-to-use function, @code{open-network-stream}, which can't use UDP, -can't act as a server, and can't set up non-blocking connections. -Also, deleting a network process with @code{delete-process} won't call -the sentinel. - -@item -Many programming shortcuts have been deleted, to provide you with the -enjoyment of ``rolling your own.'' The macros @code{while-no-input}, -@code{with-local-quit}, and @code{with-selected-window}, along with -@code{dynamic-completion-table} and @code{lazy-completion-table} no -longer exist. Also, there are no built-in progress reporters; -with Emacs, you can take progress for granted. - -@item -Variable aliases are no longer supported. Aliases are for functions, -not for variables. - -@item -The variables @code{most-positive-fixnum} and -@code{most-negative-fixnum} do not exist. On 32 bit machines, the -most positive integer is probably 134217727, and the most negative -integer is probably -134217728. - -@item -The functions @code{eql} and @code{macroexpand-all} are no longer -available. However, you can find similar functions in the @code{cl} -package. - -@item -The list returned by @code{split-string} won't include null substrings -for separators at the beginning or end of a string. If you want to -check for such separators, do it separately. - -@item -The function @code{assoc-string} has been removed. Use -@code{assoc-ignore-case} or @code{assoc-ignore-representation} (which -are no longer obsolete.) - -@item -The escape sequence @samp{\s} is always interpreted as a super -modifier, never a space. - -@item -The variable @code{buffer-save-without-query} has been removed, to -prevent Emacs from sneakily saving buffers. Also, the hook -@code{before-save-hook} has been removed, so if you want something to -be done before saving, advise or redefine @code{basic-save-buffer}. - -@item -The variable @code{buffer-auto-save-file-format} has been renamed to -@code{auto-save-file-format}, and is no longer a permanent local. - -@item -The function @code{visited-file-modtime} now returns a cons, instead -of a list of two integers. The primitive @code{set-file-times} has -been eliminated. - -@item -The function @code{file-remote-p} is no longer available. - -@item -When determining the filename extension, a leading dot in a filename -is no longer ignored. Thus, @file{.emacs} is considered to have -extension @file{emacs}, rather than being extensionless. - -@item -Emacs looks for special file handlers in a more efficient manner: it -will choose the first matching handler in -@code{file-name-handler-alist}, rather than trying to figure out which -provides the closest match. - -@item -The @code{predicate} argument for @code{read-file-name} has been -removed, and so have the variables @code{read-file-name-function} and -@code{read-file-name-completion-ignore-case}. The function -@code{read-directory-name} has also been removed. - -@item -The functions @code{all-completions} and @code{try-completion} will no -longer accept lists of strings or hash tables (it will still accept -alists, obarrays, and functions.) In addition, the function -@code{test-completion} is no longer available. - -@item -The @samp{G} interactive code character is no longer supported. -Use @samp{F} instead. - -@item -Arbitrary Lisp functions can no longer be recorded into -@code{buffer-undo-list}. As a consequence, @code{yank-undo-function} -is obsolete, and has been removed. - -@item -Emacs will never complain about commands that accumulate too much undo -information, so you no longer have to worry about binding -@code{buffer-undo-list} to @code{t} for such commands (though you may -want to do that anyway, to avoid taking up unnecessary memory space.) - -@item -Atomic change groups are no longer supported. - -@item -The list returned by @code{(match-data t)} no longer records the -buffer as a final element. - -@item -The function @code{looking-back} has been removed, so we no longer -have the benefit of hindsight. - -@item -The variable @code{search-spaces-regexp} does not exist. Spaces -always stand for themselves in regular expression searches. - -@item -The functions @code{skip-chars-forward} and @code{skip-chars-backward} -no longer accepts character classes such as @samp{[:alpha:]}. All -characters are created equal. - -@item -The @code{yank-handler} text property no longer has any meaning. -Also, @code{yank-excluded-properties}, @code{insert-for-yank}, and -@code{insert-buffer-substring-as-yank} have all been removed. - -@item -The variable @code{char-property-alias-alist} has been deleted. -Aliases are for functions, not for properties. - -@item -The function @code{get-char-property-and-overlay} has been deleted. -If you want the properties at a point, find the text properties at the -point; then, find the overlays at the point, and find the properties -on those overlays. - -@item -Font Lock mode only manages @code{face} properties; you can't use -font-lock keywords to specify arbitrary text properties for it to -manage. After all, it is called Font Lock mode, not Arbitrary -Properties Lock mode. - -@item -The arguments to @code{remove-overlays} are no longer optional. - -@item -In @code{replace-match}, the replacement text now inherits properties -from the surrounding text. - -@item -The variable @code{mode-line-format} no longer supports the @code{:propertize}, -@code{%i}, and @code{%I} constructs. The function -@code{format-mode-line} has been removed. - -@item -The functions @code{window-inside-edges} and @code{window-body-height} -have been removed. You should do the relevant calculations yourself, -starting with @code{window-width} and @code{window-height}. - -@item -The functions @code{window-pixel-edges} and -@code{window-inside-pixel-edges} have been removed. We prefer to -think in terms of lines and columns, not pixel coordinates. (Sometime -in the distant past, we will do away with graphical terminals -entirely, in favor of text terminals.) For similar reasons, the -functions @code{posn-at-point}, @code{posn-at-x-y}, and -@code{window-line-height} have been removed, and -@code{pos-visible-in-window-p} no longer worries about partially -visible rows. - -@item -The macro @code{save-selected-window} only saves the selected window -of the selected frame, so don't try selecting windows in other frames. - -@item -The function @code{minibufferp} is no longer available. - -@item -The function @code{modify-all-frames-parameters} has been removed (we -always suspected the name was ungrammatical, anyway.) - -@item -The @code{line-spacing} variable no longer accepts float values. - -@item -The function @code{tool-bar-local-item-from-menu} has been deleted. -If you need to make an entry in the tool bar, you can still use -@code{tool-bar-add-item-from-menu}, but that modifies the binding in -the source keymap instead of copying it into the local keymap. - -@item -When determining the major mode, the file name takes precedence over -the interpreter magic line. The variable @code{magic-mode-alist}, -which associates certain buffer beginnings with major modes, has been -eliminated. - -@item -The hook @code{after-change-major-mode-hook} is not defined, and -neither are @code{run-mode-hooks} and @code{delay-mode-hooks}. - -@item -The variable @code{minor-mode-list} has been removed. - -@item -@code{define-derived-mode} will copy abbrevs from the parent mode's -abbrev table, instead of creating a new, empty abbrev table. - -@item -There are no ``system'' abbrevs. When the user saves into the abbrevs -file, all abbrevs are saved. - -@item -The Warnings facility has been removed. Just use @code{error}. - -@item -Several hook variables have been renamed to flout the Emacs naming -conventions. We feel that consistency is boring, and having -non-standard hook names encourages users to check the documentation -before using a hook. For instance, the normal hook -@code{find-file-hook} has been renamed to @code{find-file-hooks}, and -the abnormal hook @code{delete-frame-functions} has been renamed to -@code{delete-frame-hook}. - -@item -The function @code{symbol-file} does not exist. If you want to know -which file defined a function or variable, try grepping for it. - -@item -The variable @code{load-history} records function definitions just -like variable definitions, instead of indicating which functions were -previously autoloaded. - -@item -There is a new variable, @code{recursive-load-depth-limit}, which -specifies how many times files can recursively load themselves; it is -50 by default, and @code{nil} means infinity. Previously, Emacs signaled an -error after just 3 recursive loads, which was boring. - -@item -Byte-compiler warnings and error messages will leave out the line and -character positions, in order to exercise your debugging skills. -Also, there is no @code{with-no-warnings} macro---instead of -suppressing compiler warnings, fix your code to avoid them! - -@item -The function @code{unsafep} has been removed. - -@item -File local variables can now specify a string with text properties. -Since arbitrary Lisp expressions can be embedded in text properties, -this can provide you with a great deal of flexibility and power. On -the other hand, @code{safe-local-eval-forms} and the -@code{safe-local-eval-function} function property have no special -meaning. - -@item -You can no longer use @code{char-displayable-p} to test if Emacs can -display a certain character. - -@item -The function @code{string-to-multibyte} is no longer available. - -@item -The @code{translation-table-for-input} translation table has been -removed. Also, translation hash tables are no longer available, so we -don't need the functions @code{lookup-character} and -@code{lookup-integer}. - -@item -The @code{table} argument to @code{translate-region} can no longer be -a char-table; it has to be a string. - -@item -The variable @code{auto-coding-functions} and the two functions -@code{merge-coding-systems} and @code{decode-coding-inserted-region} -have been deleted. The coding system property -@code{mime-text-unsuitable} no longer has any special meaning. - -@item -If pure storage overflows while dumping, Emacs won't tell you how much -additional pure storage it needs. Try adding in increments of 20000, -until you have enough. - -@item -The variables @code{gc-elapsed}, @code{gcs-done}, and -@code{post-gc-hook} have been garbage-collected. -@end itemize - -@ignore - arch-tag: 1d0ef137-2bad-430e-ae8e-d820d569b5a6 -@end ignore diff --git a/lispref/back.texi b/lispref/back.texi deleted file mode 100644 index 19559eab9c1..00000000000 --- a/lispref/back.texi +++ /dev/null @@ -1,42 +0,0 @@ -\input /home/gd/gnu/doc/texinfo.tex @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@c %**start of header -@setfilename back-cover -@settitle GNU Emacs Lisp Reference Manual -@c %**end of header -. -@sp 7 -@center @titlefont {GNU Emacs Lisp} -@sp 1 - -@quotation - 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. 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. -@end quotation - -@hfil -@bye - -@ignore - arch-tag: ac7694c8-1f02-4b42-9531-33ba13b179e1 -@end ignore diff --git a/lispref/backups.texi b/lispref/backups.texi deleted file mode 100644 index 44795557f15..00000000000 --- a/lispref/backups.texi +++ /dev/null @@ -1,756 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/backups -@node Backups and Auto-Saving, Buffers, Files, Top -@chapter Backups and Auto-Saving -@cindex backups and auto-saving - - Backup files and auto-save files are two methods by which Emacs tries -to protect the user from the consequences of crashes or of the user's -own errors. Auto-saving preserves the text from earlier in the current -editing session; backup files preserve file contents prior to the -current session. - -@menu -* 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. -@end menu - -@node Backup Files -@section Backup Files -@cindex backup file - - A @dfn{backup file} is a copy of the old contents of a file you are -editing. Emacs makes a backup file the first time you save a buffer -into its visited file. Thus, normally, the backup file contains the -contents of the file as it was before the current editing session. -The contents of the backup file normally remain unchanged once it -exists. - - Backups are usually made by renaming the visited file to a new name. -Optionally, you can specify that backup files should be made by copying -the visited file. This choice makes a difference for files with -multiple names; it also can affect whether the edited file remains owned -by the original owner or becomes owned by the user editing it. - - By default, Emacs makes a single backup file for each file edited. -You can alternatively request numbered backups; then each new backup -file gets a new name. You can delete old numbered backups when you -don't want them any more, or Emacs can delete them automatically. - -@menu -* 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. -@end menu - -@node Making Backups -@subsection Making Backup Files - -@defun backup-buffer - This function makes a backup of the file visited by the current -buffer, if appropriate. It is called by @code{save-buffer} before -saving the buffer the first time. - -If a backup was made by renaming, the return value is a cons cell of -the form (@var{modes} . @var{backupname}), where @var{modes} are the -mode bits of the original file, as returned by @code{file-modes} -(@pxref{File Attributes,, Other Information about Files}), and -@var{backupname} is the name of the backup. In all other cases, that -is, if a backup was made by copying or if no backup was made, this -function returns @code{nil}. -@end defun - -@defvar buffer-backed-up - This buffer-local variable says whether this buffer's file has -been backed up on account of this buffer. If it is non-@code{nil}, -the backup file has been written. Otherwise, the file should be backed -up when it is next saved (if backups are enabled). This is a -permanent local; @code{kill-all-local-variables} does not alter@tie{}it. -@end defvar - -@defopt make-backup-files -This variable determines whether or not to make backup files. If it -is non-@code{nil}, then Emacs creates a backup of each file when it is -saved for the first time---provided that @code{backup-inhibited} -is @code{nil} (see below). - -The following example shows how to change the @code{make-backup-files} -variable only in the Rmail buffers and not elsewhere. Setting it -@code{nil} stops Emacs from making backups of these files, which may -save disk space. (You would put this code in your init file.) - -@smallexample -@group -(add-hook 'rmail-mode-hook - (function (lambda () - (make-local-variable - 'make-backup-files) - (setq make-backup-files nil)))) -@end group -@end smallexample -@end defopt - -@defvar backup-enable-predicate -This variable's value is a function to be called on certain occasions to -decide whether a file should have backup files. The function receives -one argument, an absolute file name to consider. If the function returns -@code{nil}, backups are disabled for that file. Otherwise, the other -variables in this section say whether and how to make backups. - -@findex normal-backup-enable-predicate -The default value is @code{normal-backup-enable-predicate}, which checks -for files in @code{temporary-file-directory} and -@code{small-temporary-file-directory}. -@end defvar - -@defvar backup-inhibited -If this variable is non-@code{nil}, backups are inhibited. It records -the result of testing @code{backup-enable-predicate} on the visited file -name. It can also coherently be used by other mechanisms that inhibit -backups based on which file is visited. For example, VC sets this -variable non-@code{nil} to prevent making backups for files managed -with a version control system. - -This is a permanent local, so that changing the major mode does not lose -its value. Major modes should not set this variable---they should set -@code{make-backup-files} instead. -@end defvar - -@defvar backup-directory-alist -This variable's value is an alist of filename patterns and backup -directory names. Each element looks like -@smallexample -(@var{regexp} . @var{directory}) -@end smallexample - -@noindent -Backups of files with names matching @var{regexp} will be made in -@var{directory}. @var{directory} may be relative or absolute. If it is -absolute, so that all matching files are backed up into the same -directory, the file names in this directory will be the full name of the -file backed up with all directory separators changed to @samp{!} to -prevent clashes. This will not work correctly if your filesystem -truncates the resulting name. - -For the common case of all backups going into one directory, the alist -should contain a single element pairing @samp{"."} with the appropriate -directory name. - -If this variable is @code{nil}, or it fails to match a filename, the -backup is made in the original file's directory. - -On MS-DOS filesystems without long names this variable is always -ignored. -@end defvar - -@defvar make-backup-file-name-function -This variable's value is a function to use for making backups instead -of the default @code{make-backup-file-name}. A value of @code{nil} -gives the default @code{make-backup-file-name} behavior. -@xref{Backup Names,, Naming Backup Files}. - -This could be buffer-local to do something special for specific -files. If you define it, you may need to change -@code{backup-file-name-p} and @code{file-name-sans-versions} too. -@end defvar - - -@node Rename or Copy -@subsection Backup by Renaming or by Copying? -@cindex backup files, rename or copy - - There are two ways that Emacs can make a backup file: - -@itemize @bullet -@item -Emacs can rename the original file so that it becomes a backup file, and -then write the buffer being saved into a new file. After this -procedure, any other names (i.e., hard links) of the original file now -refer to the backup file. The new file is owned by the user doing the -editing, and its group is the default for new files written by the user -in that directory. - -@item -Emacs can copy the original file into a backup file, and then overwrite -the original file with new contents. After this procedure, any other -names (i.e., hard links) of the original file continue to refer to the -current (updated) version of the file. The file's owner and group will -be unchanged. -@end itemize - - The first method, renaming, is the default. - - The variable @code{backup-by-copying}, if non-@code{nil}, says to use -the second method, which is to copy the original file and overwrite it -with the new buffer contents. The variable @code{file-precious-flag}, -if non-@code{nil}, also has this effect (as a sideline of its main -significance). @xref{Saving Buffers}. - -@defopt backup-by-copying -If this variable is non-@code{nil}, Emacs always makes backup files by -copying. -@end defopt - - The following three variables, when non-@code{nil}, cause the second -method to be used in certain special cases. They have no effect on the -treatment of files that don't fall into the special cases. - -@defopt backup-by-copying-when-linked -If this variable is non-@code{nil}, Emacs makes backups by copying for -files with multiple names (hard links). - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defopt - -@defopt backup-by-copying-when-mismatch -If this variable is non-@code{nil}, Emacs makes backups by copying in cases -where renaming would change either the owner or the group of the file. - -The value has no effect when renaming would not alter the owner or -group of the file; that is, for files which are owned by the user and -whose group matches the default for a new file created there by the -user. - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defopt - -@defopt backup-by-copying-when-privileged-mismatch -This variable, if non-@code{nil}, specifies the same behavior as -@code{backup-by-copying-when-mismatch}, but only for certain user-id -values: namely, those less than or equal to a certain number. You set -this variable to that number. - -Thus, if you set @code{backup-by-copying-when-privileged-mismatch} -to 0, backup by copying is done for the superuser only, -when necessary to prevent a change in the owner of the file. - -The default is 200. -@end defopt - -@node Numbered Backups -@subsection Making and Deleting Numbered Backup Files - - If a file's name is @file{foo}, the names of its numbered backup -versions are @file{foo.~@var{v}~}, for various integers @var{v}, like -this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{}, -@file{foo.~259~}, and so on. - -@defopt version-control -This variable controls whether to make a single non-numbered backup -file or multiple numbered backups. - -@table @asis -@item @code{nil} -Make numbered backups if the visited file already has numbered backups; -otherwise, do not. This is the default. - -@item @code{never} -Do not make numbered backups. - -@item @var{anything else} -Make numbered backups. -@end table -@end defopt - - The use of numbered backups ultimately leads to a large number of -backup versions, which must then be deleted. Emacs can do this -automatically or it can ask the user whether to delete them. - -@defopt kept-new-versions -The value of this variable is the number of newest versions to keep -when a new numbered backup is made. The newly made backup is included -in the count. The default value is@tie{}2. -@end defopt - -@defopt kept-old-versions -The value of this variable is the number of oldest versions to keep -when a new numbered backup is made. The default value is@tie{}2. -@end defopt - - If there are backups numbered 1, 2, 3, 5, and 7, and both of these -variables have the value 2, then the backups numbered 1 and 2 are kept -as old versions and those numbered 5 and 7 are kept as new versions; -backup version 3 is excess. The function @code{find-backup-file-name} -(@pxref{Backup Names}) is responsible for determining which backup -versions to delete, but does not delete them itself. - -@defopt delete-old-versions -If this variable is @code{t}, then saving a file deletes excess -backup versions silently. If it is @code{nil}, that means -to ask for confirmation before deleting excess backups. -Otherwise, they are not deleted at all. -@end defopt - -@defopt dired-kept-versions -This variable specifies how many of the newest backup versions to keep -in the Dired command @kbd{.} (@code{dired-clean-directory}). That's the -same thing @code{kept-new-versions} specifies when you make a new backup -file. The default is@tie{}2. -@end defopt - -@node Backup Names -@subsection Naming Backup Files - - The functions in this section are documented mainly because you can -customize the naming conventions for backup files by redefining them. -If you change one, you probably need to change the rest. - -@defun backup-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -possible name for a backup file. It just checks the name, not whether -a file with the name @var{filename} exists. - -@smallexample -@group -(backup-file-name-p "foo") - @result{} nil -@end group -@group -(backup-file-name-p "foo~") - @result{} 3 -@end group -@end smallexample - -The standard definition of this function is as follows: - -@smallexample -@group -(defun backup-file-name-p (file) - "Return non-nil if FILE is a backup file \ -name (numeric or not)..." - (string-match "~\\'" file)) -@end group -@end smallexample - -@noindent -Thus, the function returns a non-@code{nil} value if the file name ends -with a @samp{~}. (We use a backslash to split the documentation -string's first line into two lines in the text, but produce just one -line in the string itself.) - -This simple expression is placed in a separate function to make it easy -to redefine for customization. -@end defun - -@defun make-backup-file-name filename -This function returns a string that is the name to use for a -non-numbered backup file for file @var{filename}. On Unix, this is just -@var{filename} with a tilde appended. - -The standard definition of this function, on most operating systems, is -as follows: - -@smallexample -@group -(defun make-backup-file-name (file) - "Create the non-numeric backup file name for FILE..." - (concat file "~")) -@end group -@end smallexample - -You can change the backup-file naming convention by redefining this -function. The following example redefines @code{make-backup-file-name} -to prepend a @samp{.} in addition to appending a tilde: - -@smallexample -@group -(defun make-backup-file-name (filename) - (expand-file-name - (concat "." (file-name-nondirectory filename) "~") - (file-name-directory filename))) -@end group - -@group -(make-backup-file-name "backups.texi") - @result{} ".backups.texi~" -@end group -@end smallexample - -Some parts of Emacs, including some Dired commands, assume that backup -file names end with @samp{~}. If you do not follow that convention, it -will not cause serious problems, but these commands may give -less-than-desirable results. -@end defun - -@defun find-backup-file-name filename -This function computes the file name for a new backup file for -@var{filename}. It may also propose certain existing backup files for -deletion. @code{find-backup-file-name} returns a list whose @sc{car} is -the name for the new backup file and whose @sc{cdr} is a list of backup -files whose deletion is proposed. The value can also be @code{nil}, -which means not to make a backup. - -Two variables, @code{kept-old-versions} and @code{kept-new-versions}, -determine which backup versions should be kept. This function keeps -those versions by excluding them from the @sc{cdr} of the value. -@xref{Numbered Backups}. - -In this example, the value says that @file{~rms/foo.~5~} is the name -to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess'' -version that the caller should consider deleting now. - -@smallexample -@group -(find-backup-file-name "~rms/foo") - @result{} ("~rms/foo.~5~" "~rms/foo.~3~") -@end group -@end smallexample -@end defun - -@c Emacs 19 feature -@defun file-newest-backup filename -This function returns the name of the most recent backup file for -@var{filename}, or @code{nil} if that file has no backup files. - -Some file comparison commands use this function so that they can -automatically compare a file with its most recent backup. -@end defun - -@node Auto-Saving -@section Auto-Saving -@c @cindex auto-saving Lots of symbols starting with auto-save here. - - Emacs periodically saves all files that you are visiting; this is -called @dfn{auto-saving}. Auto-saving prevents you from losing more -than a limited amount of work if the system crashes. By default, -auto-saves happen every 300 keystrokes, or after around 30 seconds of -idle time. @xref{Auto Save, Auto Save, Auto-Saving: Protection Against -Disasters, emacs, The GNU Emacs Manual}, for information on auto-save -for users. Here we describe the functions used to implement auto-saving -and the variables that control them. - -@defvar buffer-auto-save-file-name -This buffer-local variable is the name of the file used for -auto-saving the current buffer. It is @code{nil} if the buffer -should not be auto-saved. - -@example -@group -buffer-auto-save-file-name - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@end example -@end defvar - -@deffn Command auto-save-mode arg -When used interactively without an argument, this command is a toggle -switch: it turns on auto-saving of the current buffer if it is off, and -vice versa. With an argument @var{arg}, the command turns auto-saving -on if the value of @var{arg} is @code{t}, a nonempty list, or a positive -integer. Otherwise, it turns auto-saving off. -@end deffn - -@defun auto-save-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -string that could be the name of an auto-save file. It assumes -the usual naming convention for auto-save files: a name that -begins and ends with hash marks (@samp{#}) is a possible auto-save file -name. The argument @var{filename} should not contain a directory part. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@group -(auto-save-file-name-p "#backups.texi#") - @result{} 0 -@end group -@group -(auto-save-file-name-p "backups.texi") - @result{} nil -@end group -@end example - -The standard definition of this function is as follows: - -@example -@group -(defun auto-save-file-name-p (filename) - "Return non-nil if FILENAME can be yielded by..." - (string-match "^#.*#$" filename)) -@end group -@end example - -This function exists so that you can customize it if you wish to -change the naming convention for auto-save files. If you redefine it, -be sure to redefine the function @code{make-auto-save-file-name} -correspondingly. -@end defun - -@defun make-auto-save-file-name -This function returns the file name to use for auto-saving the current -buffer. This is just the file name with hash marks (@samp{#}) prepended -and appended to it. This function does not look at the variable -@code{auto-save-visited-file-name} (described below); callers of this -function should check that variable first. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@end example - -Here is a simplified version of the standard definition of this -function: - -@example -@group -(defun make-auto-save-file-name () - "Return file name to use for auto-saves \ -of current buffer.." - (if buffer-file-name -@end group -@group - (concat - (file-name-directory buffer-file-name) - "#" - (file-name-nondirectory buffer-file-name) - "#") - (expand-file-name - (concat "#%" (buffer-name) "#")))) -@end group -@end example - -This exists as a separate function so that you can redefine it to -customize the naming convention for auto-save files. Be sure to -change @code{auto-save-file-name-p} in a corresponding way. -@end defun - -@defopt auto-save-visited-file-name -If this variable is non-@code{nil}, Emacs auto-saves buffers in -the files they are visiting. That is, the auto-save is done in the same -file that you are editing. Normally, this variable is @code{nil}, so -auto-save files have distinct names that are created by -@code{make-auto-save-file-name}. - -When you change the value of this variable, the new value does not take -effect in an existing buffer until the next time auto-save mode is -reenabled in it. If auto-save mode is already enabled, auto-saves -continue to go in the same file name until @code{auto-save-mode} is -called again. -@end defopt - -@defun recent-auto-save-p -This function returns @code{t} if the current buffer has been -auto-saved since the last time it was read in or saved. -@end defun - -@defun set-buffer-auto-saved -This function marks the current buffer as auto-saved. The buffer will -not be auto-saved again until the buffer text is changed again. The -function returns @code{nil}. -@end defun - -@defopt auto-save-interval -The value of this variable specifies how often to do auto-saving, in -terms of number of input events. Each time this many additional input -events are read, Emacs does auto-saving for all buffers in which that is -enabled. Setting this to zero disables autosaving based on the -number of characters typed. -@end defopt - -@defopt auto-save-timeout -The value of this variable is the number of seconds of idle time that -should cause auto-saving. Each time the user pauses for this long, -Emacs does auto-saving for all buffers in which that is enabled. (If -the current buffer is large, the specified timeout is multiplied by a -factor that increases as the size increases; for a million-byte -buffer, the factor is almost 4.) - -If the value is zero or @code{nil}, then auto-saving is not done as a -result of idleness, only after a certain number of input events as -specified by @code{auto-save-interval}. -@end defopt - -@defvar auto-save-hook -This normal hook is run whenever an auto-save is about to happen. -@end defvar - -@defopt auto-save-default -If this variable is non-@code{nil}, buffers that are visiting files -have auto-saving enabled by default. Otherwise, they do not. -@end defopt - -@deffn Command do-auto-save &optional no-message current-only -This function auto-saves all buffers that need to be auto-saved. It -saves all buffers for which auto-saving is enabled and that have been -changed since the previous auto-save. - -If any buffers are auto-saved, @code{do-auto-save} normally displays a -message saying @samp{Auto-saving...} in the echo area while -auto-saving is going on. However, if @var{no-message} is -non-@code{nil}, the message is inhibited. - -If @var{current-only} is non-@code{nil}, only the current buffer -is auto-saved. -@end deffn - -@defun delete-auto-save-file-if-necessary &optional force -This function deletes the current buffer's auto-save file if -@code{delete-auto-save-files} is non-@code{nil}. It is called every -time a buffer is saved. - -Unless @var{force} is non-@code{nil}, this function only deletes the -file if it was written by the current Emacs session since the last -true save. -@end defun - -@defopt delete-auto-save-files -This variable is used by the function -@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil}, -Emacs deletes auto-save files when a true save is done (in the visited -file). This saves disk space and unclutters your directory. -@end defopt - -@defun rename-auto-save-file -This function adjusts the current buffer's auto-save file name if the -visited file name has changed. It also renames an existing auto-save -file, if it was made in the current Emacs session. If the visited -file name has not changed, this function does nothing. -@end defun - -@defvar buffer-saved-size -The value of this buffer-local variable is the length of the current -buffer, when it was last read in, saved, or auto-saved. This is -used to detect a substantial decrease in size, and turn off auto-saving -in response. - -If it is @minus{}1, that means auto-saving is temporarily shut off in -this buffer due to a substantial decrease in size. Explicitly saving -the buffer stores a positive value in this variable, thus reenabling -auto-saving. Turning auto-save mode off or on also updates this -variable, so that the substantial decrease in size is forgotten. -@end defvar - -@defvar auto-save-list-file-name -This variable (if non-@code{nil}) specifies a file for recording the -names of all the auto-save files. Each time Emacs does auto-saving, it -writes two lines into this file for each buffer that has auto-saving -enabled. The first line gives the name of the visited file (it's empty -if the buffer has none), and the second gives the name of the auto-save -file. - -When Emacs exits normally, it deletes this file; if Emacs crashes, you -can look in the file to find all the auto-save files that might contain -work that was otherwise lost. The @code{recover-session} command uses -this file to find them. - -The default name for this file specifies your home directory and starts -with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the -host name. -@end defvar - -@defvar auto-save-list-file-prefix -After Emacs reads your init file, it initializes -@code{auto-save-list-file-name} (if you have not already set it -non-@code{nil}) based on this prefix, adding the host name and process -ID. If you set this to @code{nil} in your init file, then Emacs does -not initialize @code{auto-save-list-file-name}. -@end defvar - -@node Reverting -@section Reverting - - If you have made extensive changes to a file and then change your mind -about them, you can get rid of them by reading in the previous version -of the file with the @code{revert-buffer} command. @xref{Reverting, , -Reverting a Buffer, emacs, The GNU Emacs Manual}. - -@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes -This command replaces the buffer text with the text of the visited -file on disk. This action undoes all changes since the file was visited -or saved. - -By default, if the latest auto-save file is more recent than the visited -file, and the argument @var{ignore-auto} is @code{nil}, -@code{revert-buffer} asks the user whether to use that auto-save -instead. When you invoke this command interactively, @var{ignore-auto} -is @code{t} if there is no numeric prefix argument; thus, the -interactive default is not to check the auto-save file. - -Normally, @code{revert-buffer} asks for confirmation before it changes -the buffer; but if the argument @var{noconfirm} is non-@code{nil}, -@code{revert-buffer} does not ask for confirmation. - -Normally, this command reinitializes the buffer's major and minor modes -using @code{normal-mode}. But if @var{preserve-modes} is -non-@code{nil}, the modes remain unchanged. - -Reverting tries to preserve marker positions in the buffer by using the -replacement feature of @code{insert-file-contents}. If the buffer -contents and the file contents are identical before the revert -operation, reverting preserves all the markers. If they are not -identical, reverting does change the buffer; in that case, it preserves -the markers in the unchanged text (if any) at the beginning and end of -the buffer. Preserving any additional markers would be problematical. -@end deffn - -You can customize how @code{revert-buffer} does its work by setting -the variables described in the rest of this section. - -@defopt revert-without-query -This variable holds a list of files that should be reverted without -query. The value is a list of regular expressions. If the visited file -name matches one of these regular expressions, and the file has changed -on disk but the buffer is not modified, then @code{revert-buffer} -reverts the file without asking the user for confirmation. -@end defopt - - Some major modes customize @code{revert-buffer} by making -buffer-local bindings for these variables: - -@defvar revert-buffer-function -@anchor{Definition of revert-buffer-function} -The value of this variable is the function to use to revert this -buffer. If non-@code{nil}, it should be a function with two optional -arguments to do the work of reverting. The two optional arguments, -@var{ignore-auto} and @var{noconfirm}, are the arguments that -@code{revert-buffer} received. If the value is @code{nil}, reverting -works the usual way. - -Modes such as Dired mode, in which the text being edited does not -consist of a file's contents but can be regenerated in some other -fashion, can give this variable a buffer-local value that is a function to -regenerate the contents. -@end defvar - -@defvar revert-buffer-insert-file-contents-function -The value of this variable, if non-@code{nil}, specifies the function to use to -insert the updated contents when reverting this buffer. The function -receives two arguments: first the file name to use; second, @code{t} if -the user has asked to read the auto-save file. - -The reason for a mode to set this variable instead of -@code{revert-buffer-function} is to avoid duplicating or replacing the -rest of what @code{revert-buffer} does: asking for confirmation, -clearing the undo list, deciding the proper major mode, and running the -hooks listed below. -@end defvar - -@defvar before-revert-hook -This normal hook is run by @code{revert-buffer} before -inserting the modified contents---but only if -@code{revert-buffer-function} is @code{nil}. -@end defvar - -@defvar after-revert-hook -This normal hook is run by @code{revert-buffer} after inserting -the modified contents---but only if @code{revert-buffer-function} is -@code{nil}. -@end defvar - -@ignore - arch-tag: 295a6321-e5ab-46d5-aef5-0bb4f447a67f -@end ignore diff --git a/lispref/book-spine.texinfo b/lispref/book-spine.texinfo deleted file mode 100644 index 7355c4530ae..00000000000 --- a/lispref/book-spine.texinfo +++ /dev/null @@ -1,29 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename book-spine -@settitle book-spine -@c %**end of header - -@c need dot in text so first space command works! -. -@sp 7 - -@center @titlefont{GNU Emacs Lisp Reference Manual} -@sp 5 -@center GNU -@center Emacs Version 22.1 -@center for Unix Users -@sp 5 - -@center by -@center Bil Lewis, -@center Dan LaLiberte, -@center and the -@center GNU Manual Group -@sp 5 -@center Free Software Foundation -@bye - -@ignore - arch-tag: 4466c7ca-e549-4119-948c-6eed34e1ff87 -@end ignore diff --git a/lispref/buffers.texi b/lispref/buffers.texi deleted file mode 100644 index e9cafb69fb5..00000000000 --- a/lispref/buffers.texi +++ /dev/null @@ -1,1165 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/buffers -@node Buffers, Windows, Backups and Auto-Saving, Top -@chapter Buffers -@cindex buffer - - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. While several buffers may -exist at one time, only one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. - -@menu -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that 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. -@end menu - -@node Buffer Basics -@comment node-name, next, previous, up -@section Buffer Basics - -@ifnottex - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. Although several buffers -normally exist, only one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. -@end ifnottex - - Buffers in Emacs editing are objects that have distinct names and hold -text that can be edited. Buffers appear to Lisp programs as a special -data type. You can think of the contents of a buffer as a string that -you can extend; insertions and deletions may occur in any part of the -buffer. @xref{Text}. - - A Lisp buffer object contains numerous pieces of information. Some of -this information is directly accessible to the programmer through -variables, while other information is accessible only through -special-purpose functions. For example, the visited file name is -directly accessible through a variable, while the value of point is -accessible only through a primitive function. - - Buffer-specific information that is directly accessible is stored in -@dfn{buffer-local} variable bindings, which are variable values that are -effective only in a particular buffer. This feature allows each buffer -to override the values of certain variables. Most major modes override -variables such as @code{fill-column} or @code{comment-column} in this -way. For more information about buffer-local variables and functions -related to them, see @ref{Buffer-Local Variables}. - - For functions and variables related to visiting files in buffers, see -@ref{Visiting Files} and @ref{Saving Buffers}. For functions and -variables related to the display of buffers in windows, see -@ref{Buffers and Windows}. - -@defun bufferp object -This function returns @code{t} if @var{object} is a buffer, -@code{nil} otherwise. -@end defun - -@node Current Buffer -@section The Current Buffer -@cindex selecting a buffer -@cindex changing to another buffer -@cindex current buffer - - There are, in general, many buffers in an Emacs session. At any time, -one of them is designated as the @dfn{current buffer}. This is the -buffer in which most editing takes place, because most of the primitives -for examining or changing text in a buffer operate implicitly on the -current buffer (@pxref{Text}). Normally the buffer that is displayed on -the screen in the selected window is the current buffer, but this is not -always so: a Lisp program can temporarily designate any buffer as -current in order to operate on its contents, without changing what is -displayed on the screen. - - The way to designate a current buffer in a Lisp program is by calling -@code{set-buffer}. The specified buffer remains current until a new one -is designated. - - When an editing command returns to the editor command loop, the -command loop designates the buffer displayed in the selected window as -current, to prevent confusion: the buffer that the cursor is in when -Emacs reads a command is the buffer that the command will apply to. -(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to -switch visibly to a different buffer so that the user can edit it. For -that, you must use the functions described in @ref{Displaying Buffers}. - - @strong{Warning:} Lisp functions that change to a different current buffer -should not depend on the command loop to set it back afterwards. -Editing commands written in Emacs Lisp can be called from other programs -as well as from the command loop; it is convenient for the caller if -the subroutine does not change which buffer is current (unless, of -course, that is the subroutine's purpose). Therefore, you should -normally use @code{set-buffer} within a @code{save-current-buffer} or -@code{save-excursion} (@pxref{Excursions}) form that will restore the -current buffer when your function is done. Here is an example, the -code for the command @code{append-to-buffer} (with the documentation -string abridged): - -@example -@group -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -@dots{}" - (interactive "BAppend to buffer: \nr") - (let ((oldbuf (current-buffer))) - (save-current-buffer - (set-buffer (get-buffer-create buffer)) - (insert-buffer-substring oldbuf start end)))) -@end group -@end example - -@noindent -This function binds a local variable to record the current buffer, and -then @code{save-current-buffer} arranges to make it current again. -Next, @code{set-buffer} makes the specified buffer current. Finally, -@code{insert-buffer-substring} copies the string from the original -current buffer to the specified (and now current) buffer. - - If the buffer appended to happens to be displayed in some window, -the next redisplay will show how its text has changed. Otherwise, you -will not see the change immediately on the screen. The buffer becomes -current temporarily during the execution of the command, but this does -not cause it to be displayed. - - If you make local bindings (with @code{let} or function arguments) for -a variable that may also have buffer-local bindings, make sure that the -same buffer is current at the beginning and at the end of the local -binding's scope. Otherwise you might bind it in one buffer and unbind -it in another! There are two ways to do this. In simple cases, you may -see that nothing ever changes the current buffer within the scope of the -binding. Otherwise, use @code{save-current-buffer} or -@code{save-excursion} to make sure that the buffer current at the -beginning is current again whenever the variable is unbound. - - Do not rely on using @code{set-buffer} to change the current buffer -back, because that won't do the job if a quit happens while the wrong -buffer is current. Here is what @emph{not} to do: - -@example -@group -(let (buffer-read-only - (obuf (current-buffer))) - (set-buffer @dots{}) - @dots{} - (set-buffer obuf)) -@end group -@end example - -@noindent -Using @code{save-current-buffer}, as shown here, handles quitting, -errors, and @code{throw}, as well as ordinary evaluation. - -@example -@group -(let (buffer-read-only) - (save-current-buffer - (set-buffer @dots{}) - @dots{})) -@end group -@end example - -@defun current-buffer -This function returns the current buffer. - -@example -@group -(current-buffer) - @result{} #<buffer buffers.texi> -@end group -@end example -@end defun - -@defun set-buffer buffer-or-name -This function makes @var{buffer-or-name} the current buffer. This does -not display the buffer in any window, so the user cannot necessarily see -the buffer. But Lisp programs will now operate on it. - -This function returns the buffer identified by @var{buffer-or-name}. -An error is signaled if @var{buffer-or-name} does not identify an -existing buffer. -@end defun - -@defspec save-current-buffer body@dots{} -The @code{save-current-buffer} special form saves the identity of the -current buffer, evaluates the @var{body} forms, and finally restores -that buffer as current. The return value is the value of the last -form in @var{body}. The current buffer is restored even in case of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). - -If the buffer that used to be current has been killed by the time of -exit from @code{save-current-buffer}, then it is not made current again, -of course. Instead, whichever buffer was current just before exit -remains current. -@end defspec - -@defmac with-current-buffer buffer-or-name body@dots{} -The @code{with-current-buffer} macro saves the identity of the current -buffer, makes @var{buffer-or-name} current, evaluates the @var{body} -forms, and finally restores the buffer. The return value is the value -of the last form in @var{body}. The current buffer is restored even -in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal -Exits}). - -An error is signaled if @var{buffer-or-name} does not identify an -existing buffer. -@end defmac - -@defmac with-temp-buffer body@dots{} -@anchor{Definition of with-temp-buffer} -The @code{with-temp-buffer} macro evaluates the @var{body} forms -with a temporary buffer as the current buffer. It saves the identity of -the current buffer, creates a temporary buffer and makes it current, -evaluates the @var{body} forms, and finally restores the previous -current buffer while killing the temporary buffer. By default, undo -information (@pxref{Undo}) is not recorded in the buffer created by -this macro (but @var{body} can enable that, if needed). - -The return value is the value of the last form in @var{body}. You can -return the contents of the temporary buffer by using -@code{(buffer-string)} as the last form. - -The current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -See also @code{with-temp-file} in @ref{Definition of with-temp-file,, -Writing to Files}. -@end defmac - -@node Buffer Names -@section Buffer Names -@cindex buffer names - - Each buffer has a unique name, which is a string. Many of the -functions that work on buffers accept either a buffer or a buffer name -as an argument. Any argument called @var{buffer-or-name} is of this -sort, and an error is signaled if it is neither a string nor a buffer. -Any argument called @var{buffer} must be an actual buffer -object, not a name. - -@cindex hidden buffers -@cindex buffers without undo information - Buffers that are ephemeral and generally uninteresting to the user -have names starting with a space, so that the @code{list-buffers} and -@code{buffer-menu} commands don't mention them (but if such a buffer -visits a file, it @strong{is} mentioned). A name starting with -space also initially disables recording undo information; see -@ref{Undo}. - -@defun buffer-name &optional buffer -This function returns the name of @var{buffer} as a string. If -@var{buffer} is not supplied, it defaults to the current buffer. - -If @code{buffer-name} returns @code{nil}, it means that @var{buffer} -has been killed. @xref{Killing Buffers}. - -@example -@group -(buffer-name) - @result{} "buffers.texi" -@end group - -@group -(setq foo (get-buffer "temp")) - @result{} #<buffer temp> -@end group -@group -(kill-buffer foo) - @result{} nil -@end group -@group -(buffer-name foo) - @result{} nil -@end group -@group -foo - @result{} #<killed buffer> -@end group -@end example -@end defun - -@deffn Command rename-buffer newname &optional unique -This function renames the current buffer to @var{newname}. An error -is signaled if @var{newname} is not a string. - -@c Emacs 19 feature -Ordinarily, @code{rename-buffer} signals an error if @var{newname} is -already in use. However, if @var{unique} is non-@code{nil}, it modifies -@var{newname} to make a name that is not in use. Interactively, you can -make @var{unique} non-@code{nil} with a numeric prefix argument. -(This is how the command @code{rename-uniquely} is implemented.) - -This function returns the name actually given to the buffer. -@end deffn - -@defun get-buffer buffer-or-name -This function returns the buffer specified by @var{buffer-or-name}. -If @var{buffer-or-name} is a string and there is no buffer with that -name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it -is returned as given; that is not very useful, so the argument is usually -a name. For example: - -@example -@group -(setq b (get-buffer "lewis")) - @result{} #<buffer lewis> -@end group -@group -(get-buffer b) - @result{} #<buffer lewis> -@end group -@group -(get-buffer "Frazzle-nots") - @result{} nil -@end group -@end example - -See also the function @code{get-buffer-create} in @ref{Creating Buffers}. -@end defun - -@c Emacs 19 feature -@defun generate-new-buffer-name starting-name &optional ignore -This function returns a name that would be unique for a new buffer---but -does not create the buffer. It starts with @var{starting-name}, and -produces a name not currently in use for any buffer by appending a -number inside of @samp{<@dots{}>}. It starts at 2 and keeps -incrementing the number until it is not the name of an existing buffer. - -If the optional second argument @var{ignore} is non-@code{nil}, it -should be a string, a potential buffer name. It means to consider -that potential buffer acceptable, if it is tried, even it is the name -of an existing buffer (which would normally be rejected). Thus, if -buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and -@samp{foo<4>} exist, - -@example -(generate-new-buffer-name "foo") - @result{} "foo<5>" -(generate-new-buffer-name "foo" "foo<3>") - @result{} "foo<3>" -(generate-new-buffer-name "foo" "foo<6>") - @result{} "foo<5>" -@end example - -See the related function @code{generate-new-buffer} in @ref{Creating -Buffers}. -@end defun - -@node Buffer File Name -@section Buffer File Name -@cindex visited file -@cindex buffer file name -@cindex file name of buffer - - The @dfn{buffer file name} is the name of the file that is visited in -that buffer. When a buffer is not visiting a file, its buffer file name -is @code{nil}. Most of the time, the buffer name is the same as the -nondirectory part of the buffer file name, but the buffer file name and -the buffer name are distinct and can be set independently. -@xref{Visiting Files}. - -@defun buffer-file-name &optional buffer -This function returns the absolute file name of the file that -@var{buffer} is visiting. If @var{buffer} is not visiting any file, -@code{buffer-file-name} returns @code{nil}. If @var{buffer} is not -supplied, it defaults to the current buffer. - -@example -@group -(buffer-file-name (other-buffer)) - @result{} "/usr/user/lewis/manual/files.texi" -@end group -@end example -@end defun - -@defvar buffer-file-name -This buffer-local variable contains the name of the file being visited -in the current buffer, or @code{nil} if it is not visiting a file. It -is a permanent local variable, unaffected by -@code{kill-all-local-variables}. - -@example -@group -buffer-file-name - @result{} "/usr/user/lewis/manual/buffers.texi" -@end group -@end example - -It is risky to change this variable's value without doing various other -things. Normally it is better to use @code{set-visited-file-name} (see -below); some of the things done there, such as changing the buffer name, -are not strictly necessary, but others are essential to avoid confusing -Emacs. -@end defvar - -@defvar buffer-file-truename -This buffer-local variable holds the abbreviated truename of the file -visited in the current buffer, or @code{nil} if no file is visited. -It is a permanent local, unaffected by -@code{kill-all-local-variables}. @xref{Truenames}, and -@ref{Definition of abbreviate-file-name}. -@end defvar - -@defvar buffer-file-number -This buffer-local variable holds the file number and directory device -number of the file visited in the current buffer, or @code{nil} if no -file or a nonexistent file is visited. It is a permanent local, -unaffected by @code{kill-all-local-variables}. - -The value is normally a list of the form @code{(@var{filenum} -@var{devnum})}. This pair of numbers uniquely identifies the file among -all files accessible on the system. See the function -@code{file-attributes}, in @ref{File Attributes}, for more information -about them. - -If @code{buffer-file-name} is the name of a symbolic link, then both -numbers refer to the recursive target. -@end defvar - -@defun get-file-buffer filename -This function returns the buffer visiting file @var{filename}. If -there is no such buffer, it returns @code{nil}. The argument -@var{filename}, which must be a string, is expanded (@pxref{File Name -Expansion}), then compared against the visited file names of all live -buffers. Note that the buffer's @code{buffer-file-name} must match -the expansion of @var{filename} exactly. This function will not -recognize other names for the same file. - -@example -@group -(get-file-buffer "buffers.texi") - @result{} #<buffer buffers.texi> -@end group -@end example - -In unusual circumstances, there can be more than one buffer visiting -the same file name. In such cases, this function returns the first -such buffer in the buffer list. -@end defun - -@defun find-buffer-visiting filename &optional predicate -This is like @code{get-file-buffer}, except that it can return any -buffer visiting the file @emph{possibly under a different name}. That -is, the buffer's @code{buffer-file-name} does not need to match the -expansion of @var{filename} exactly, it only needs to refer to the -same file. If @var{predicate} is non-@code{nil}, it should be a -function of one argument, a buffer visiting @var{filename}. The -buffer is only considered a suitable return value if @var{predicate} -returns non-@code{nil}. If it can not find a suitable buffer to -return, @code{find-buffer-visiting} returns @code{nil}. -@end defun - -@deffn Command set-visited-file-name filename &optional no-query along-with-file -If @var{filename} is a non-empty string, this function changes the -name of the file visited in the current buffer to @var{filename}. (If the -buffer had no visited file, this gives it one.) The @emph{next time} -the buffer is saved it will go in the newly-specified file. - -This command marks the buffer as modified, since it does not (as far -as Emacs knows) match the contents of @var{filename}, even if it -matched the former visited file. It also renames the buffer to -correspond to the new file name, unless the new name is already in -use. - -If @var{filename} is @code{nil} or the empty string, that stands for -``no visited file.'' In this case, @code{set-visited-file-name} marks -the buffer as having no visited file, without changing the buffer's -modified flag. - -Normally, this function asks the user for confirmation if there -already is a buffer visiting @var{filename}. If @var{no-query} is -non-@code{nil}, that prevents asking this question. If there already -is a buffer visiting @var{filename}, and the user confirms or -@var{query} is non-@code{nil}, this function makes the new buffer name -unique by appending a number inside of @samp{<@dots{}>} to @var{filename}. - -If @var{along-with-file} is non-@code{nil}, that means to assume that -the former visited file has been renamed to @var{filename}. In this -case, the command does not change the buffer's modified flag, nor the -buffer's recorded last file modification time as reported by -@code{visited-file-modtime} (@pxref{Modification Time}). If -@var{along-with-file} is @code{nil}, this function clears the recorded -last file modification time, after which @code{visited-file-modtime} -returns zero. - -@c Wordy to avoid overfull hbox. --rjc 16mar92 -When the function @code{set-visited-file-name} is called interactively, it -prompts for @var{filename} in the minibuffer. -@end deffn - -@defvar list-buffers-directory -This buffer-local variable specifies a string to display in a buffer -listing where the visited file name would go, for buffers that don't -have a visited file name. Dired buffers use this variable. -@end defvar - -@node Buffer Modification -@section Buffer Modification -@cindex buffer modification -@cindex modification flag (of buffer) - - Emacs keeps a flag called the @dfn{modified flag} for each buffer, to -record whether you have changed the text of the buffer. This flag is -set to @code{t} whenever you alter the contents of the buffer, and -cleared to @code{nil} when you save it. Thus, the flag shows whether -there are unsaved changes. The flag value is normally shown in the mode -line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving -Buffers}) and auto-saving (@pxref{Auto-Saving}). - - Some Lisp programs set the flag explicitly. For example, the function -@code{set-visited-file-name} sets the flag to @code{t}, because the text -does not match the newly-visited file, even if it is unchanged from the -file formerly visited. - - The functions that modify the contents of buffers are described in -@ref{Text}. - -@defun buffer-modified-p &optional buffer -This function returns @code{t} if the buffer @var{buffer} has been modified -since it was last read in from a file or saved, or @code{nil} -otherwise. If @var{buffer} is not supplied, the current buffer -is tested. -@end defun - -@defun set-buffer-modified-p flag -This function marks the current buffer as modified if @var{flag} is -non-@code{nil}, or as unmodified if the flag is @code{nil}. - -Another effect of calling this function is to cause unconditional -redisplay of the mode line for the current buffer. In fact, the -function @code{force-mode-line-update} works by doing this: - -@example -@group -(set-buffer-modified-p (buffer-modified-p)) -@end group -@end example -@end defun - -@defun restore-buffer-modified-p flag -Like @code{set-buffer-modified-p}, but does not force redisplay -of mode lines. -@end defun - -@deffn Command not-modified &optional arg -This command marks the current buffer as unmodified, and not needing -to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as -modified, so that it will be saved at the next suitable occasion. -Interactively, @var{arg} is the prefix argument. - -Don't use this function in programs, since it prints a message in the -echo area; use @code{set-buffer-modified-p} (above) instead. -@end deffn - -@defun buffer-modified-tick &optional buffer -This function returns @var{buffer}'s modification-count. This is a -counter that increments every time the buffer is modified. If -@var{buffer} is @code{nil} (or omitted), the current buffer is used. -The counter can wrap around occasionally. -@end defun - -@defun buffer-chars-modified-tick &optional buffer -This function returns @var{buffer}'s character-change modification-count. -Changes to text properties leave this counter unchanged; however, each -time text is inserted or removed from the buffer, the counter is reset -to the value that would be returned @code{buffer-modified-tick}. -By comparing the values returned by two @code{buffer-chars-modified-tick} -calls, you can tell whether a character change occurred in that buffer -in between the calls. If @var{buffer} is @code{nil} (or omitted), the -current buffer is used. -@end defun - -@node Modification Time -@comment node-name, next, previous, up -@section Buffer Modification Time -@cindex comparing file modification time -@cindex modification time of buffer - - Suppose that you visit a file and make changes in its buffer, and -meanwhile the file itself is changed on disk. At this point, saving the -buffer would overwrite the changes in the file. Occasionally this may -be what you want, but usually it would lose valuable information. Emacs -therefore checks the file's modification time using the functions -described below before saving the file. (@xref{File Attributes}, -for how to examine a file's modification time.) - -@defun verify-visited-file-modtime buffer -This function compares what @var{buffer} has recorded for the -modification time of its visited file against the actual modification -time of the file as recorded by the operating system. The two should be -the same unless some other process has written the file since Emacs -visited or saved it. - -The function returns @code{t} if the last actual modification time and -Emacs's recorded modification time are the same, @code{nil} otherwise. -It also returns @code{t} if the buffer has no recorded last -modification time, that is if @code{visited-file-modtime} would return -zero. - -It always returns @code{t} for buffers that are not visiting a file, -even if @code{visited-file-modtime} returns a non-zero value. For -instance, it always returns @code{t} for dired buffers. It returns -@code{t} for buffers that are visiting a file that does not exist and -never existed, but @code{nil} for file-visiting buffers whose file has -been deleted. -@end defun - -@defun clear-visited-file-modtime -This function clears out the record of the last modification time of -the file being visited by the current buffer. As a result, the next -attempt to save this buffer will not complain of a discrepancy in -file modification times. - -This function is called in @code{set-visited-file-name} and other -exceptional places where the usual test to avoid overwriting a changed -file should not be done. -@end defun - -@c Emacs 19 feature -@defun visited-file-modtime -This function returns the current buffer's recorded last file -modification time, as a list of the form @code{(@var{high} @var{low})}. -(This is the same format that @code{file-attributes} uses to return -time values; see @ref{File Attributes}.) - -If the buffer has no recorded last modification time, this function -returns zero. This case occurs, for instance, if the buffer is not -visiting a file or if the time has been explicitly cleared by -@code{clear-visited-file-modtime}. Note, however, that -@code{visited-file-modtime} returns a list for some non-file buffers -too. For instance, in a Dired buffer listing a directory, it returns -the last modification time of that directory, as recorded by Dired. - -For a new buffer visiting a not yet existing file, @var{high} is -@minus{}1 and @var{low} is 65535, that is, -@ifnottex -@w{2**16 - 1.} -@end ifnottex -@tex -@math{2^{16}-1}. -@end tex -@end defun - -@c Emacs 19 feature -@defun set-visited-file-modtime &optional time -This function updates the buffer's record of the last modification time -of the visited file, to the value specified by @var{time} if @var{time} -is not @code{nil}, and otherwise to the last modification time of the -visited file. - -If @var{time} is neither @code{nil} nor zero, it should have the form -@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in -either case containing two integers, each of which holds 16 bits of the -time. - -This function is useful if the buffer was not read from the file -normally, or if the file itself has been changed for some known benign -reason. -@end defun - -@defun ask-user-about-supersession-threat filename -This function is used to ask a user how to proceed after an attempt to -modify an buffer visiting file @var{filename} when the file is newer -than the buffer text. Emacs detects this because the modification -time of the file on disk is newer than the last save-time of the -buffer. This means some other program has probably altered the file. - -@kindex file-supersession -Depending on the user's answer, the function may return normally, in -which case the modification of the buffer proceeds, or it may signal a -@code{file-supersession} error with data @code{(@var{filename})}, in which -case the proposed buffer modification is not allowed. - -This function is called automatically by Emacs on the proper -occasions. It exists so you can customize Emacs by redefining it. -See the file @file{userlock.el} for the standard definition. - -See also the file locking mechanism in @ref{File Locks}. -@end defun - -@node Read Only Buffers -@section Read-Only Buffers -@cindex read-only buffer -@cindex buffer, read-only - - If a buffer is @dfn{read-only}, then you cannot change its contents, -although you may change your view of the contents by scrolling and -narrowing. - - Read-only buffers are used in two kinds of situations: - -@itemize @bullet -@item -A buffer visiting a write-protected file is normally read-only. - -Here, the purpose is to inform the user that editing the buffer with the -aim of saving it in the file may be futile or undesirable. The user who -wants to change the buffer text despite this can do so after clearing -the read-only flag with @kbd{C-x C-q}. - -@item -Modes such as Dired and Rmail make buffers read-only when altering the -contents with the usual editing commands would probably be a mistake. - -The special commands of these modes bind @code{buffer-read-only} to -@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to -@code{t} around the places where they themselves change the text. -@end itemize - -@defvar buffer-read-only -This buffer-local variable specifies whether the buffer is read-only. -The buffer is read-only if this variable is non-@code{nil}. -@end defvar - -@defvar inhibit-read-only -If this variable is non-@code{nil}, then read-only buffers and, -depending on the actual value, some or all read-only characters may be -modified. Read-only characters in a buffer are those that have -non-@code{nil} @code{read-only} properties (either text properties or -overlay properties). @xref{Special Properties}, for more information -about text properties. @xref{Overlays}, for more information about -overlays and their properties. - -If @code{inhibit-read-only} is @code{t}, all @code{read-only} character -properties have no effect. If @code{inhibit-read-only} is a list, then -@code{read-only} character properties have no effect if they are members -of the list (comparison is done with @code{eq}). -@end defvar - -@deffn Command toggle-read-only &optional arg -This command toggles whether the current buffer is read-only. It is -intended for interactive use; do not use it in programs. At any given -point in a program, you should know whether you want the read-only flag -on or off; so you can set @code{buffer-read-only} explicitly to the -proper value, @code{t} or @code{nil}. - -If @var{arg} is non-@code{nil}, it should be a raw prefix argument. -@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if -the numeric value of that prefix argument is positive and to -@code{nil} otherwise. @xref{Prefix Command Arguments}. -@end deffn - -@defun barf-if-buffer-read-only -This function signals a @code{buffer-read-only} error if the current -buffer is read-only. @xref{Using Interactive}, for another way to -signal an error if the current buffer is read-only. -@end defun - -@node The Buffer List -@section The Buffer List -@cindex buffer list - - The @dfn{buffer list} is a list of all live buffers. The order of -the buffers in the list is based primarily on how recently each buffer -has been displayed in a window. Several functions, notably -@code{other-buffer}, use this ordering. A buffer list displayed for -the user also follows this order. - - Creating a buffer adds it to the end of the buffer list, and killing -a buffer removes it. Buffers move to the front of the list when they -are selected for display in a window (@pxref{Displaying Buffers}), and -to the end when they are buried (see @code{bury-buffer}, below). -There are no functions available to the Lisp programmer which directly -manipulate the buffer list. - - In addition to the fundamental Emacs buffer list, each frame has its -own version of the buffer list, in which the buffers that have been -selected in that frame come first, starting with the buffers most -recently selected @emph{in that frame}. (This order is recorded in -@var{frame}'s @code{buffer-list} frame parameter; see @ref{Buffer -Parameters}.) The buffers that were never selected in @var{frame} come -afterward, ordered according to the fundamental Emacs buffer list. - -@defun buffer-list &optional frame -This function returns the buffer list, including all buffers, even those -whose names begin with a space. The elements are actual buffers, not -their names. - -If @var{frame} is a frame, this returns @var{frame}'s buffer list. If -@var{frame} is @code{nil}, the fundamental Emacs buffer list is used: -all the buffers appear in order of most recent selection, regardless of -which frames they were selected in. - -@example -@group -(buffer-list) - @result{} (#<buffer buffers.texi> - #<buffer *Minibuf-1*> #<buffer buffer.c> - #<buffer *Help*> #<buffer TAGS>) -@end group - -@group -;; @r{Note that the name of the minibuffer} -;; @r{begins with a space!} -(mapcar (function buffer-name) (buffer-list)) - @result{} ("buffers.texi" " *Minibuf-1*" - "buffer.c" "*Help*" "TAGS") -@end group -@end example -@end defun - - The list that @code{buffer-list} returns is constructed specifically -by @code{buffer-list}; it is not an internal Emacs data structure, and -modifying it has no effect on the order of buffers. If you want to -change the order of buffers in the frame-independent buffer list, here -is an easy way: - -@example -(defun reorder-buffer-list (new-list) - (while new-list - (bury-buffer (car new-list)) - (setq new-list (cdr new-list)))) -@end example - - With this method, you can specify any order for the list, but there is -no danger of losing a buffer or adding something that is not a valid -live buffer. - - To change the order or value of a frame's buffer list, set the frame's -@code{buffer-list} frame parameter with @code{modify-frame-parameters} -(@pxref{Parameter Access}). - -@defun other-buffer &optional buffer visible-ok frame -This function returns the first buffer in the buffer list other than -@var{buffer}. Usually this is the buffer selected most recently (in -frame @var{frame} or else the currently selected frame, @pxref{Input -Focus}), aside from @var{buffer}. Buffers whose names start with a -space are not considered at all. - -If @var{buffer} is not supplied (or if it is not a buffer), then -@code{other-buffer} returns the first buffer in the selected frame's -buffer list that is not now visible in any window in a visible frame. - -If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, -then @code{other-buffer} uses that predicate to decide which buffers to -consider. It calls the predicate once for each buffer, and if the value -is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. - -@c Emacs 19 feature -If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning -a buffer visible in any window on any visible frame, except as a last -resort. If @var{visible-ok} is non-@code{nil}, then it does not matter -whether a buffer is displayed somewhere or not. - -If no suitable buffer exists, the buffer @samp{*scratch*} is returned -(and created, if necessary). -@end defun - -@deffn Command bury-buffer &optional buffer-or-name -This function puts @var{buffer-or-name} at the end of the buffer list, -without changing the order of any of the other buffers on the list. -This buffer therefore becomes the least desirable candidate for -@code{other-buffer} to return. The argument can be either a buffer -itself or the name of one. - -@code{bury-buffer} operates on each frame's @code{buffer-list} parameter -as well as the frame-independent Emacs buffer list; therefore, the -buffer that you bury will come last in the value of @code{(buffer-list -@var{frame})} and in the value of @code{(buffer-list nil)}. - -If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the -current buffer. In addition, if the buffer is displayed in the selected -window, this switches to some other buffer (obtained using -@code{other-buffer}) in the selected window. But if the buffer is -displayed in some other window, it remains displayed there. - -To replace a buffer in all the windows that display it, use -@code{replace-buffer-in-windows}. @xref{Buffers and Windows}. -@end deffn - -@node Creating Buffers -@section Creating Buffers -@cindex creating buffers -@cindex buffers, creating - - This section describes the two primitives for creating buffers. -@code{get-buffer-create} creates a buffer if it finds no existing buffer -with the specified name; @code{generate-new-buffer} always creates a new -buffer and gives it a unique name. - - Other functions you can use to create buffers include -@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and -@code{create-file-buffer} (@pxref{Visiting Files}). Starting a -subprocess can also create a buffer (@pxref{Processes}). - -@defun get-buffer-create name -This function returns a buffer named @var{name}. It returns a live -buffer with that name, if one exists; otherwise, it creates a new -buffer. The buffer does not become the current buffer---this function -does not change which buffer is current. - -If @var{name} is a buffer instead of a string, it is returned, even if -it is dead. An error is signaled if @var{name} is neither a string -nor a buffer. - -@example -@group -(get-buffer-create "foo") - @result{} #<buffer foo> -@end group -@end example - -The major mode for a newly created buffer is set to Fundamental mode. -(The variable @code{default-major-mode} is handled at a higher level; -see @ref{Auto Major Mode}.) If the name begins with a space, the -buffer initially disables undo information recording (@pxref{Undo}). -@end defun - -@defun generate-new-buffer name -This function returns a newly created, empty buffer, but does not make -it current. If there is no buffer named @var{name}, then that is the -name of the new buffer. If that name is in use, this function adds -suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an -integer. It tries successive integers starting with 2 until it finds an -available name. - -An error is signaled if @var{name} is not a string. - -@example -@group -(generate-new-buffer "bar") - @result{} #<buffer bar> -@end group -@group -(generate-new-buffer "bar") - @result{} #<buffer bar<2>> -@end group -@group -(generate-new-buffer "bar") - @result{} #<buffer bar<3>> -@end group -@end example - -The major mode for the new buffer is set to Fundamental mode. The -variable @code{default-major-mode} is handled at a higher level. -@xref{Auto Major Mode}. - -See the related function @code{generate-new-buffer-name} in @ref{Buffer -Names}. -@end defun - -@node Killing Buffers -@section Killing Buffers -@cindex killing buffers -@cindex buffers, killing - - @dfn{Killing a buffer} makes its name unknown to Emacs and makes the -memory space it occupied available for other use. - - The buffer object for the buffer that has been killed remains in -existence as long as anything refers to it, but it is specially marked -so that you cannot make it current or display it. Killed buffers retain -their identity, however; if you kill two distinct buffers, they remain -distinct according to @code{eq} although both are dead. - - If you kill a buffer that is current or displayed in a window, Emacs -automatically selects or displays some other buffer instead. This means -that killing a buffer can in general change the current buffer. -Therefore, when you kill a buffer, you should also take the precautions -associated with changing the current buffer (unless you happen to know -that the buffer being killed isn't current). @xref{Current Buffer}. - - If you kill a buffer that is the base buffer of one or more indirect -buffers, the indirect buffers are automatically killed as well. - - The @code{buffer-name} of a killed buffer is @code{nil}. You can use -this feature to test whether a buffer has been killed: - -@example -@group -(defun buffer-killed-p (buffer) - "Return t if BUFFER is killed." - (not (buffer-name buffer))) -@end group -@end example - -@deffn Command kill-buffer buffer-or-name -This function kills the buffer @var{buffer-or-name}, freeing all its -memory for other uses or to be returned to the operating system. If -@var{buffer-or-name} is @code{nil}, it kills the current buffer. - -Any processes that have this buffer as the @code{process-buffer} are -sent the @code{SIGHUP} signal, which normally causes them to terminate. -(The basic meaning of @code{SIGHUP} is that a dialup line has been -disconnected.) @xref{Signals to Processes}. - -If the buffer is visiting a file and contains unsaved changes, -@code{kill-buffer} asks the user to confirm before the buffer is killed. -It does this even if not called interactively. To prevent the request -for confirmation, clear the modified flag before calling -@code{kill-buffer}. @xref{Buffer Modification}. - -Killing a buffer that is already dead has no effect. - -This function returns @code{t} if it actually killed the buffer. It -returns @code{nil} if the user refuses to confirm or if -@var{buffer-or-name} was already dead. - -@smallexample -(kill-buffer "foo.unchanged") - @result{} t -(kill-buffer "foo.changed") - ----------- Buffer: Minibuffer ---------- -Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} ----------- Buffer: Minibuffer ---------- - - @result{} t -@end smallexample -@end deffn - -@defvar kill-buffer-query-functions -After confirming unsaved changes, @code{kill-buffer} calls the functions -in the list @code{kill-buffer-query-functions}, in order of appearance, -with no arguments. The buffer being killed is the current buffer when -they are called. The idea of this feature is that these functions will -ask for confirmation from the user. If any of them returns @code{nil}, -@code{kill-buffer} spares the buffer's life. -@end defvar - -@defvar kill-buffer-hook -This is a normal hook run by @code{kill-buffer} after asking all the -questions it is going to ask, just before actually killing the buffer. -The buffer to be killed is current when the hook functions run. -@xref{Hooks}. This variable is a permanent local, so its local binding -is not cleared by changing major modes. -@end defvar - -@defvar buffer-offer-save -This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the -second optional argument to that function is @code{t}) to offer to -save that buffer, just as they offer to save file-visiting buffers. -@xref{Definition of save-some-buffers}. The variable -@code{buffer-offer-save} automatically becomes buffer-local when set -for any reason. @xref{Buffer-Local Variables}. -@end defvar - -@defvar buffer-save-without-query -This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} to save -this buffer (if it's modified) without asking the user. The variable -automatically becomes buffer-local when set for any reason. -@end defvar - -@defun buffer-live-p object -This function returns @code{t} if @var{object} is a buffer which has -not been killed, @code{nil} otherwise. -@end defun - -@node Indirect Buffers -@section Indirect Buffers -@cindex indirect buffers -@cindex base buffer - - An @dfn{indirect buffer} shares the text of some other buffer, which -is called the @dfn{base buffer} of the indirect buffer. In some ways it -is the analogue, for buffers, of a symbolic link among files. The base -buffer may not itself be an indirect buffer. - - The text of the indirect buffer is always identical to the text of its -base buffer; changes made by editing either one are visible immediately -in the other. This includes the text properties as well as the characters -themselves. - - In all other respects, the indirect buffer and its base buffer are -completely separate. They have different names, independent values of -point, independent narrowing, independent markers and overlays (though -inserting or deleting text in either buffer relocates the markers and -overlays for both), independent major modes, and independent -buffer-local variable bindings. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually saves the base -buffer. - - Killing an indirect buffer has no effect on its base buffer. Killing -the base buffer effectively kills the indirect buffer in that it cannot -ever again be the current buffer. - -@deffn Command make-indirect-buffer base-buffer name &optional clone -This creates and returns an indirect buffer named @var{name} whose -base buffer is @var{base-buffer}. The argument @var{base-buffer} may -be a live buffer or the name (a string) of an existing buffer. If -@var{name} is the name of an existing buffer, an error is signaled. - -If @var{clone} is non-@code{nil}, then the indirect buffer originally -shares the ``state'' of @var{base-buffer} such as major mode, minor -modes, buffer local variables and so on. If @var{clone} is omitted -or @code{nil} the indirect buffer's state is set to the default state -for new buffers. - -If @var{base-buffer} is an indirect buffer, its base buffer is used as -the base for the new buffer. If, in addition, @var{clone} is -non-@code{nil}, the initial state is copied from the actual base -buffer, not from @var{base-buffer}. -@end deffn - -@defun clone-indirect-buffer newname display-flag &optional norecord -This function creates and returns a new indirect buffer that shares -the current buffer's base buffer and copies the rest of the current -buffer's attributes. (If the current buffer is not indirect, it is -used as the base buffer.) - -If @var{display-flag} is non-@code{nil}, that means to display the new -buffer by calling @code{pop-to-buffer}. If @var{norecord} is -non-@code{nil}, that means not to put the new buffer to the front of -the buffer list. -@end defun - -@defun buffer-base-buffer &optional buffer -This function returns the base buffer of @var{buffer}, which defaults -to the current buffer. If @var{buffer} is not indirect, the value is -@code{nil}. Otherwise, the value is another buffer, which is never an -indirect buffer. -@end defun - -@node Buffer Gap -@section The Buffer Gap - - Emacs buffers are implemented using an invisible @dfn{gap} to make -insertion and deletion faster. Insertion works by filling in part of -the gap, and deletion adds to the gap. Of course, this means that the -gap must first be moved to the locus of the insertion or deletion. -Emacs moves the gap only when you try to insert or delete. This is why -your first editing command in one part of a large buffer, after -previously editing in another far-away part, sometimes involves a -noticeable delay. - - This mechanism works invisibly, and Lisp code should never be affected -by the gap's current location, but these functions are available for -getting information about the gap status. - -@defun gap-position -This function returns the current gap position in the current buffer. -@end defun - -@defun gap-size -This function returns the current gap size of the current buffer. -@end defun - -@ignore - arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c -@end ignore diff --git a/lispref/commands.texi b/lispref/commands.texi deleted file mode 100644 index fabe38f9428..00000000000 --- a/lispref/commands.texi +++ /dev/null @@ -1,3290 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/commands -@node Command Loop, Keymaps, Minibuffers, Top -@chapter Command Loop -@cindex editor command loop -@cindex command loop - - When you run Emacs, it enters the @dfn{editor command loop} almost -immediately. This loop reads key sequences, executes their definitions, -and displays the results. In this chapter, we describe how these things -are done, and the subroutines that allow Lisp programs to do them. - -@menu -* 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. -@end menu - -@node Command Overview -@section Command Loop Overview - - The first thing the command loop must do is read a key sequence, which -is a sequence of events that translates into a command. It does this by -calling the function @code{read-key-sequence}. Your Lisp code can also -call this function (@pxref{Key Sequence Input}). Lisp programs can also -do input at a lower level with @code{read-event} (@pxref{Reading One -Event}) or discard pending input with @code{discard-input} -(@pxref{Event Input Misc}). - - The key sequence is translated into a command through the currently -active keymaps. @xref{Key Lookup}, for information on how this is done. -The result should be a keyboard macro or an interactively callable -function. If the key is @kbd{M-x}, then it reads the name of another -command, which it then calls. This is done by the command -@code{execute-extended-command} (@pxref{Interactive Call}). - - To execute a command requires first reading the arguments for it. -This is done by calling @code{command-execute} (@pxref{Interactive -Call}). For commands written in Lisp, the @code{interactive} -specification says how to read the arguments. This may use the prefix -argument (@pxref{Prefix Command Arguments}) or may read with prompting -in the minibuffer (@pxref{Minibuffers}). For example, the command -@code{find-file} has an @code{interactive} specification which says to -read a file name using the minibuffer. The command's function body does -not use the minibuffer; if you call this command from Lisp code as a -function, you must supply the file name string as an ordinary Lisp -function argument. - - If the command is a string or vector (i.e., a keyboard macro) then -@code{execute-kbd-macro} is used to execute it. You can call this -function yourself (@pxref{Keyboard Macros}). - - To terminate the execution of a running command, type @kbd{C-g}. This -character causes @dfn{quitting} (@pxref{Quitting}). - -@defvar pre-command-hook -The editor command loop runs this normal hook before each command. At -that time, @code{this-command} contains the command that is about to -run, and @code{last-command} describes the previous command. -@xref{Command Loop Info}. -@end defvar - -@defvar post-command-hook -The editor command loop runs this normal hook after each command -(including commands terminated prematurely by quitting or by errors), -and also when the command loop is first entered. At that time, -@code{this-command} refers to the command that just ran, and -@code{last-command} refers to the command before that. -@end defvar - - Quitting is suppressed while running @code{pre-command-hook} and -@code{post-command-hook}. If an error happens while executing one of -these hooks, it terminates execution of the hook, and clears the hook -variable to @code{nil} so as to prevent an infinite loop of errors. - - A request coming into the Emacs server (@pxref{Emacs Server,,, -emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard -command does. - -@node Defining Commands -@section Defining Commands -@cindex defining commands -@cindex commands, defining -@cindex functions, making them interactive -@cindex interactive function - - A Lisp function becomes a command when its body contains, at top -level, a form that calls the special form @code{interactive}. This -form does nothing when actually executed, but its presence serves as a -flag to indicate that interactive calling is permitted. Its argument -controls the reading of arguments for an interactive call. - -@menu -* 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. -@end menu - -@node Using Interactive -@subsection Using @code{interactive} -@cindex arguments, interactive entry - - This section describes how to write the @code{interactive} form that -makes a Lisp function an interactively-callable command, and how to -examine a command's @code{interactive} form. - -@defspec interactive arg-descriptor -This special form declares that the function in which it appears is a -command, and that it may therefore be called interactively (via -@kbd{M-x} or by entering a key sequence bound to it). The argument -@var{arg-descriptor} declares how to compute the arguments to the -command when the command is called interactively. - -A command may be called from Lisp programs like any other function, but -then the caller supplies the arguments and @var{arg-descriptor} has no -effect. - -The @code{interactive} form has its effect because the command loop -(actually, its subroutine @code{call-interactively}) scans through the -function definition looking for it, before calling the function. Once -the function is called, all its body forms including the -@code{interactive} form are executed, but at this time -@code{interactive} simply returns @code{nil} without even evaluating its -argument. -@end defspec - -There are three possibilities for the argument @var{arg-descriptor}: - -@itemize @bullet -@item -It may be omitted or @code{nil}; then the command is called with no -arguments. This leads quickly to an error if the command requires one -or more arguments. - -@item -It may be a string; then its contents should consist of a code character -followed by a prompt (which some code characters use and some ignore). -The prompt ends either with the end of the string or with a newline. -Here is a simple example: - -@smallexample -(interactive "bFrobnicate buffer: ") -@end smallexample - -@noindent -The code letter @samp{b} says to read the name of an existing buffer, -with completion. The buffer name is the sole argument passed to the -command. The rest of the string is a prompt. - -If there is a newline character in the string, it terminates the prompt. -If the string does not end there, then the rest of the string should -contain another code character and prompt, specifying another argument. -You can specify any number of arguments in this way. - -@c Emacs 19 feature -The prompt string can use @samp{%} to include previous argument values -(starting with the first argument) in the prompt. This is done using -@code{format} (@pxref{Formatting Strings}). For example, here is how -you could read the name of an existing buffer followed by a new name to -give to that buffer: - -@smallexample -@group -(interactive "bBuffer to rename: \nsRename buffer %s to: ") -@end group -@end smallexample - -@cindex @samp{*} in @code{interactive} -@cindex read-only buffers in interactive -If the first character in the string is @samp{*}, then an error is -signaled if the buffer is read-only. - -@cindex @samp{@@} in @code{interactive} -@c Emacs 19 feature -If the first character in the string is @samp{@@}, and if the key -sequence used to invoke the command includes any mouse events, then -the window associated with the first of those events is selected -before the command is run. - -You can use @samp{*} and @samp{@@} together; the order does not matter. -Actual reading of arguments is controlled by the rest of the prompt -string (starting with the first character that is not @samp{*} or -@samp{@@}). - -@item -It may be a Lisp expression that is not a string; then it should be a -form that is evaluated to get a list of arguments to pass to the -command. Usually this form will call various functions to read input -from the user, most often through the minibuffer (@pxref{Minibuffers}) -or directly from the keyboard (@pxref{Reading Input}). - -Providing point or the mark as an argument value is also common, but -if you do this @emph{and} read input (whether using the minibuffer or -not), be sure to get the integer values of point or the mark after -reading. The current buffer may be receiving subprocess output; if -subprocess output arrives while the command is waiting for input, it -could relocate point and the mark. - -Here's an example of what @emph{not} to do: - -@smallexample -(interactive - (list (region-beginning) (region-end) - (read-string "Foo: " nil 'my-history))) -@end smallexample - -@noindent -Here's how to avoid the problem, by examining point and the mark after -reading the keyboard input: - -@smallexample -(interactive - (let ((string (read-string "Foo: " nil 'my-history))) - (list (region-beginning) (region-end) string))) -@end smallexample - -@strong{Warning:} the argument values should not include any data -types that can't be printed and then read. Some facilities save -@code{command-history} in a file to be read in the subsequent -sessions; if a command's arguments contain a data type that prints -using @samp{#<@dots{}>} syntax, those facilities won't work. - -There are, however, a few exceptions: it is ok to use a limited set of -expressions such as @code{(point)}, @code{(mark)}, -@code{(region-beginning)}, and @code{(region-end)}, because Emacs -recognizes them specially and puts the expression (rather than its -value) into the command history. To see whether the expression you -wrote is one of these exceptions, run the command, then examine -@code{(car command-history)}. -@end itemize - -@cindex examining the @code{interactive} form -@defun interactive-form function -This function returns the @code{interactive} form of @var{function}. -If @var{function} is an interactively callable function -(@pxref{Interactive Call}), the value is the command's -@code{interactive} form @code{(interactive @var{spec})}, which -specifies how to compute its arguments. Otherwise, the value is -@code{nil}. If @var{function} is a symbol, its function definition is -used. -@end defun - -@node Interactive Codes -@comment node-name, next, previous, up -@subsection Code Characters for @code{interactive} -@cindex interactive code description -@cindex description for interactive codes -@cindex codes, interactive, description of -@cindex characters for interactive codes - - The code character descriptions below contain a number of key words, -defined here as follows: - -@table @b -@item Completion -@cindex interactive completion -Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name -completion because the argument is read using @code{completing-read} -(@pxref{Completion}). @kbd{?} displays a list of possible completions. - -@item Existing -Require the name of an existing object. An invalid name is not -accepted; the commands to exit the minibuffer do not exit if the current -input is not valid. - -@item Default -@cindex default argument string -A default value of some sort is used if the user enters no text in the -minibuffer. The default depends on the code character. - -@item No I/O -This code letter computes an argument without reading any input. -Therefore, it does not use a prompt string, and any prompt string you -supply is ignored. - -Even though the code letter doesn't use a prompt string, you must follow -it with a newline if it is not the last code character in the string. - -@item Prompt -A prompt immediately follows the code character. The prompt ends either -with the end of the string or with a newline. - -@item Special -This code character is meaningful only at the beginning of the -interactive string, and it does not look for a prompt or a newline. -It is a single, isolated character. -@end table - -@cindex reading interactive arguments - Here are the code character descriptions for use with @code{interactive}: - -@table @samp -@item * -Signal an error if the current buffer is read-only. Special. - -@item @@ -Select the window mentioned in the first mouse event in the key -sequence that invoked this command. Special. - -@item a -A function name (i.e., a symbol satisfying @code{fboundp}). Existing, -Completion, Prompt. - -@item b -The name of an existing buffer. By default, uses the name of the -current buffer (@pxref{Buffers}). Existing, Completion, Default, -Prompt. - -@item B -A buffer name. The buffer need not exist. By default, uses the name of -a recently used buffer other than the current buffer. Completion, -Default, Prompt. - -@item c -A character. The cursor does not move into the echo area. Prompt. - -@item C -A command name (i.e., a symbol satisfying @code{commandp}). Existing, -Completion, Prompt. - -@item d -@cindex position argument -The position of point, as an integer (@pxref{Point}). No I/O. - -@item D -A directory name. The default is the current default directory of the -current buffer, @code{default-directory} (@pxref{File Name Expansion}). -Existing, Completion, Default, Prompt. - -@item e -The first or next mouse event in the key sequence that invoked the command. -More precisely, @samp{e} gets events that are lists, so you can look at -the data in the lists. @xref{Input Events}. No I/O. - -You can use @samp{e} more than once in a single command's interactive -specification. If the key sequence that invoked the command has -@var{n} events that are lists, the @var{n}th @samp{e} provides the -@var{n}th such event. Events that are not lists, such as function keys -and @acronym{ASCII} characters, do not count where @samp{e} is concerned. - -@item f -A file name of an existing file (@pxref{File Names}). The default -directory is @code{default-directory}. Existing, Completion, Default, -Prompt. - -@item F -A file name. The file need not exist. Completion, Default, Prompt. - -@item G -A file name. The file need not exist. If the user enters just a -directory name, then the value is just that directory name, with no -file name within the directory added. Completion, Default, Prompt. - -@item i -An irrelevant argument. This code always supplies @code{nil} as -the argument's value. No I/O. - -@item k -A key sequence (@pxref{Key Sequences}). This keeps reading events -until a command (or undefined command) is found in the current key -maps. The key sequence argument is represented as a string or vector. -The cursor does not move into the echo area. Prompt. - -If @samp{k} reads a key sequence that ends with a down-event, it also -reads and discards the following up-event. You can get access to that -up-event with the @samp{U} code character. - -This kind of input is used by commands such as @code{describe-key} and -@code{global-set-key}. - -@item K -A key sequence, whose definition you intend to change. This works like -@samp{k}, except that it suppresses, for the last input event in the key -sequence, the conversions that are normally used (when necessary) to -convert an undefined key into a defined one. - -@item m -@cindex marker argument -The position of the mark, as an integer. No I/O. - -@item M -Arbitrary text, read in the minibuffer using the current buffer's input -method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU -Emacs Manual}). Prompt. - -@item n -A number, read with the minibuffer. If the input is not a number, the -user has to try again. @samp{n} never uses the prefix argument. -Prompt. - -@item N -The numeric prefix argument; but if there is no prefix argument, read -a number as with @kbd{n}. The value is always a number. @xref{Prefix -Command Arguments}. Prompt. - -@item p -@cindex numeric prefix argument usage -The numeric prefix argument. (Note that this @samp{p} is lower case.) -No I/O. - -@item P -@cindex raw prefix argument usage -The raw prefix argument. (Note that this @samp{P} is upper case.) No -I/O. - -@item r -@cindex region argument -Point and the mark, as two numeric arguments, smallest first. This is -the only code letter that specifies two successive arguments rather than -one. No I/O. - -@item s -Arbitrary text, read in the minibuffer and returned as a string -(@pxref{Text from Minibuffer}). Terminate the input with either -@kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of -these characters in the input.) Prompt. - -@item S -An interned symbol whose name is read in the minibuffer. Any whitespace -character terminates the input. (Use @kbd{C-q} to include whitespace in -the string.) Other characters that normally terminate a symbol (e.g., -parentheses and brackets) do not do so here. Prompt. - -@item U -A key sequence or @code{nil}. Can be used after a @samp{k} or -@samp{K} argument to get the up-event that was discarded (if any) -after @samp{k} or @samp{K} read a down-event. If no up-event has been -discarded, @samp{U} provides @code{nil} as the argument. No I/O. - -@item v -A variable declared to be a user option (i.e., satisfying the -predicate @code{user-variable-p}). This reads the variable using -@code{read-variable}. @xref{Definition of read-variable}. Existing, -Completion, Prompt. - -@item x -A Lisp object, specified with its read syntax, terminated with a -@kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from -Minibuffer}. Prompt. - -@item X -@cindex evaluated expression argument -A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates -the form so that its value becomes the argument for the command. -Prompt. - -@item z -A coding system name (a symbol). If the user enters null input, the -argument value is @code{nil}. @xref{Coding Systems}. Completion, -Existing, Prompt. - -@item Z -A coding system name (a symbol)---but only if this command has a prefix -argument. With no prefix argument, @samp{Z} provides @code{nil} as the -argument value. Completion, Existing, Prompt. -@end table - -@node Interactive Examples -@comment node-name, next, previous, up -@subsection Examples of Using @code{interactive} -@cindex examples of using @code{interactive} -@cindex @code{interactive}, examples of using - - Here are some examples of @code{interactive}: - -@example -@group -(defun foo1 () ; @r{@code{foo1} takes no arguments,} - (interactive) ; @r{just moves forward two words.} - (forward-word 2)) - @result{} foo1 -@end group - -@group -(defun foo2 (n) ; @r{@code{foo2} takes one argument,} - (interactive "p") ; @r{which is the numeric prefix.} - (forward-word (* 2 n))) - @result{} foo2 -@end group - -@group -(defun foo3 (n) ; @r{@code{foo3} takes one argument,} - (interactive "nCount:") ; @r{which is read with the Minibuffer.} - (forward-word (* 2 n))) - @result{} foo3 -@end group - -@group -(defun three-b (b1 b2 b3) - "Select three existing buffers. -Put them into three windows, selecting the last one." -@end group - (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") - (delete-other-windows) - (split-window (selected-window) 8) - (switch-to-buffer b1) - (other-window 1) - (split-window (selected-window) 8) - (switch-to-buffer b2) - (other-window 1) - (switch-to-buffer b3)) - @result{} three-b -@group -(three-b "*scratch*" "declarations.texi" "*mail*") - @result{} nil -@end group -@end example - -@node Interactive Call -@section Interactive Call -@cindex interactive call - - After the command loop has translated a key sequence into a command it -invokes that command using the function @code{command-execute}. If the -command is a function, @code{command-execute} calls -@code{call-interactively}, which reads the arguments and calls the -command. You can also call these functions yourself. - -@defun commandp object &optional for-call-interactively -Returns @code{t} if @var{object} is suitable for calling interactively; -that is, if @var{object} is a command. Otherwise, returns @code{nil}. - -The interactively callable objects include strings and vectors (treated -as keyboard macros), lambda expressions that contain a top-level call to -@code{interactive}, byte-code function objects made from such lambda -expressions, autoload objects that are declared as interactive -(non-@code{nil} fourth argument to @code{autoload}), and some of the -primitive functions. - -A symbol satisfies @code{commandp} if its function definition -satisfies @code{commandp}. Keys and keymaps are not commands. -Rather, they are used to look up commands (@pxref{Keymaps}). - -If @var{for-call-interactively} is non-@code{nil}, then -@code{commandp} returns @code{t} only for objects that -@code{call-interactively} could call---thus, not for keyboard macros. - -See @code{documentation} in @ref{Accessing Documentation}, for a -realistic example of using @code{commandp}. -@end defun - -@defun call-interactively command &optional record-flag keys -This function calls the interactively callable function @var{command}, -reading arguments according to its interactive calling specifications. -It returns whatever @var{command} returns. An error is signaled if -@var{command} is not a function or if it cannot be called -interactively (i.e., is not a command). Note that keyboard macros -(strings and vectors) are not accepted, even though they are -considered commands, because they are not functions. If @var{command} -is a symbol, then @code{call-interactively} uses its function definition. - -@cindex record command history -If @var{record-flag} is non-@code{nil}, then this command and its -arguments are unconditionally added to the list @code{command-history}. -Otherwise, the command is added only if it uses the minibuffer to read -an argument. @xref{Command History}. - -The argument @var{keys}, if given, should be a vector which specifies -the sequence of events to supply if the command inquires which events -were used to invoke it. If @var{keys} is omitted or @code{nil}, the -default is the return value of @code{this-command-keys-vector}. -@xref{Definition of this-command-keys-vector}. -@end defun - -@defun command-execute command &optional record-flag keys special -@cindex keyboard macro execution -This function executes @var{command}. The argument @var{command} must -satisfy the @code{commandp} predicate; i.e., it must be an interactively -callable function or a keyboard macro. - -A string or vector as @var{command} is executed with -@code{execute-kbd-macro}. A function is passed to -@code{call-interactively}, along with the optional @var{record-flag} -and @var{keys}. - -A symbol is handled by using its function definition in its place. A -symbol with an @code{autoload} definition counts as a command if it was -declared to stand for an interactively callable function. Such a -definition is handled by loading the specified library and then -rechecking the definition of the symbol. - -The argument @var{special}, if given, means to ignore the prefix -argument and not clear it. This is used for executing special events -(@pxref{Special Events}). -@end defun - -@deffn Command execute-extended-command prefix-argument -@cindex read command name -This function reads a command name from the minibuffer using -@code{completing-read} (@pxref{Completion}). Then it uses -@code{command-execute} to call the specified command. Whatever that -command returns becomes the value of @code{execute-extended-command}. - -@cindex execute with prefix argument -If the command asks for a prefix argument, it receives the value -@var{prefix-argument}. If @code{execute-extended-command} is called -interactively, the current raw prefix argument is used for -@var{prefix-argument}, and thus passed on to whatever command is run. - -@c !!! Should this be @kindex? -@cindex @kbd{M-x} -@code{execute-extended-command} is the normal definition of @kbd{M-x}, -so it uses the string @w{@samp{M-x }} as a prompt. (It would be better -to take the prompt from the events used to invoke -@code{execute-extended-command}, but that is painful to implement.) A -description of the value of the prefix argument, if any, also becomes -part of the prompt. - -@example -@group -(execute-extended-command 3) ----------- Buffer: Minibuffer ---------- -3 M-x forward-word RET ----------- Buffer: Minibuffer ---------- - @result{} t -@end group -@end example -@end deffn - -@defun interactive-p -This function returns @code{t} if the containing function (the one -whose code includes the call to @code{interactive-p}) was called in -direct response to user input. This means that it was called with the -function @code{call-interactively}, and that a keyboard macro is -not running, and that Emacs is not running in batch mode. - -If the containing function was called by Lisp evaluation (or with -@code{apply} or @code{funcall}), then it was not called interactively. -@end defun - - The most common use of @code{interactive-p} is for deciding whether -to give the user additional visual feedback (such as by printing an -informative message). For example: - -@example -@group -;; @r{Here's the usual way to use @code{interactive-p}.} -(defun foo () - (interactive) - (when (interactive-p) - (message "foo"))) - @result{} foo -@end group - -@group -;; @r{This function is just to illustrate the behavior.} -(defun bar () - (interactive) - (setq foobar (list (foo) (interactive-p)))) - @result{} bar -@end group - -@group -;; @r{Type @kbd{M-x foo}.} - @print{} foo -@end group - -@group -;; @r{Type @kbd{M-x bar}.} -;; @r{This does not display a message.} -@end group - -@group -foobar - @result{} (nil t) -@end group -@end example - - If you want to test @emph{only} whether the function was called -using @code{call-interactively}, add an optional argument -@code{print-message} which should be non-@code{nil} in an interactive -call, and use the @code{interactive} spec to make sure it is -non-@code{nil}. Here's an example: - -@example -(defun foo (&optional print-message) - (interactive "p") - (when print-message - (message "foo"))) -@end example - -@noindent -Defined in this way, the function does display the message when called -from a keyboard macro. We use @code{"p"} because the numeric prefix -argument is never @code{nil}. - -@defun called-interactively-p -This function returns @code{t} when the calling function was called -using @code{call-interactively}. - -When possible, instead of using this function, you should use the -method in the example above; that method makes it possible for a -caller to ``pretend'' that the function was called interactively. -@end defun - -@node Command Loop Info -@comment node-name, next, previous, up -@section Information from the Command Loop - -The editor command loop sets several Lisp variables to keep status -records for itself and for commands that are run. - -@defvar last-command -This variable records the name of the previous command executed by the -command loop (the one before the current command). Normally the value -is a symbol with a function definition, but this is not guaranteed. - -The value is copied from @code{this-command} when a command returns to -the command loop, except when the command has specified a prefix -argument for the following command. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Displays}. -@end defvar - -@defvar real-last-command -This variable is set up by Emacs just like @code{last-command}, -but never altered by Lisp programs. -@end defvar - -@defvar this-command -@cindex current command -This variable records the name of the command now being executed by -the editor command loop. Like @code{last-command}, it is normally a symbol -with a function definition. - -The command loop sets this variable just before running a command, and -copies its value into @code{last-command} when the command finishes -(unless the command specified a prefix argument for the following -command). - -@cindex kill command repetition -Some commands set this variable during their execution, as a flag for -whatever command runs next. In particular, the functions for killing text -set @code{this-command} to @code{kill-region} so that any kill commands -immediately following will know to append the killed text to the -previous kill. -@end defvar - -If you do not want a particular command to be recognized as the previous -command in the case where it got an error, you must code that command to -prevent this. One way is to set @code{this-command} to @code{t} at the -beginning of the command, and set @code{this-command} back to its proper -value at the end, like this: - -@example -(defun foo (args@dots{}) - (interactive @dots{}) - (let ((old-this-command this-command)) - (setq this-command t) - @r{@dots{}do the work@dots{}} - (setq this-command old-this-command))) -@end example - -@noindent -We do not bind @code{this-command} with @code{let} because that would -restore the old value in case of error---a feature of @code{let} which -in this case does precisely what we want to avoid. - -@defvar this-original-command -This has the same value as @code{this-command} except when command -remapping occurs (@pxref{Remapping Commands}). In that case, -@code{this-command} gives the command actually run (the result of -remapping), and @code{this-original-command} gives the command that -was specified to run but remapped into another command. -@end defvar - -@defun this-command-keys -This function returns a string or vector containing the key sequence -that invoked the present command, plus any previous commands that -generated the prefix argument for this command. Any events read by the -command using @code{read-event} without a timeout get tacked on to the end. - -However, if the command has called @code{read-key-sequence}, it -returns the last read key sequence. @xref{Key Sequence Input}. The -value is a string if all events in the sequence were characters that -fit in a string. @xref{Input Events}. - -@example -@group -(this-command-keys) -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} "^U^X^E" -@end group -@end example -@end defun - -@defun this-command-keys-vector -@anchor{Definition of this-command-keys-vector} -Like @code{this-command-keys}, except that it always returns the events -in a vector, so you don't need to deal with the complexities of storing -input events in a string (@pxref{Strings of Events}). -@end defun - -@defun clear-this-command-keys &optional keep-record -This function empties out the table of events for -@code{this-command-keys} to return. Unless @var{keep-record} is -non-@code{nil}, it also empties the records that the function -@code{recent-keys} (@pxref{Recording Input}) will subsequently return. -This is useful after reading a password, to prevent the password from -echoing inadvertently as part of the next command in certain cases. -@end defun - -@defvar last-nonmenu-event -This variable holds the last input event read as part of a key sequence, -not counting events resulting from mouse menus. - -One use of this variable is for telling @code{x-popup-menu} where to pop -up a menu. It is also used internally by @code{y-or-n-p} -(@pxref{Yes-or-No Queries}). -@end defvar - -@defvar last-command-event -@defvarx last-command-char -This variable is set to the last input event that was read by the -command loop as part of a command. The principal use of this variable -is in @code{self-insert-command}, which uses it to decide which -character to insert. - -@example -@group -last-command-event -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} 5 -@end group -@end example - -@noindent -The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}. - -The alias @code{last-command-char} exists for compatibility with -Emacs version 18. -@end defvar - -@c Emacs 19 feature -@defvar last-event-frame -This variable records which frame the last input event was directed to. -Usually this is the frame that was selected when the event was -generated, but if that frame has redirected input focus to another -frame, the value is the frame to which the event was redirected. -@xref{Input Focus}. - -If the last event came from a keyboard macro, the value is @code{macro}. -@end defvar - -@node Adjusting Point -@section Adjusting Point After Commands -@cindex adjusting point -@cindex invisible/intangible text, and point -@cindex @code{display} property, and point display -@cindex @code{composition} property, and point display - - It is not easy to display a value of point in the middle of a -sequence of text that has the @code{display}, @code{composition} or -@code{intangible} property, or is invisible. Therefore, after a -command finishes and returns to the command loop, if point is within -such a sequence, the command loop normally moves point to the edge of -the sequence. - - A command can inhibit this feature by setting the variable -@code{disable-point-adjustment}: - -@defvar disable-point-adjustment -If this variable is non-@code{nil} when a command returns to the -command loop, then the command loop does not check for those text -properties, and does not move point out of sequences that have them. - -The command loop sets this variable to @code{nil} before each command, -so if a command sets it, the effect applies only to that command. -@end defvar - -@defvar global-disable-point-adjustment -If you set this variable to a non-@code{nil} value, the feature of -moving point out of these sequences is completely turned off. -@end defvar - -@node Input Events -@section Input Events -@cindex events -@cindex input events - -The Emacs command loop reads a sequence of @dfn{input events} that -represent keyboard or mouse activity. The events for keyboard activity -are characters or symbols; mouse events are always lists. This section -describes the representation and meaning of input events in detail. - -@defun eventp object -This function returns non-@code{nil} if @var{object} is an input event -or event type. - -Note that any symbol might be used as an event or an event type. -@code{eventp} cannot distinguish whether a symbol is intended by Lisp -code to be used as an event. Instead, it distinguishes whether the -symbol has actually been used in an event that has been read as input in -the current Emacs session. If a symbol has not yet been so used, -@code{eventp} returns @code{nil}. -@end defun - -@menu -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Events:: Functions to extract info from events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. -@end menu - -@node Keyboard Events -@subsection Keyboard Events -@cindex keyboard events - -There are two kinds of input you can get from the keyboard: ordinary -keys, and function keys. Ordinary keys correspond to characters; the -events they generate are represented in Lisp as characters. The event -type of a character event is the character itself (an integer); see -@ref{Classifying Events}. - -@cindex modifier bits (of input character) -@cindex basic code (of input character) -An input character event consists of a @dfn{basic code} between 0 and -524287, plus any or all of these @dfn{modifier bits}: - -@table @asis -@item meta -The -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit in the character code indicates a character -typed with the meta key held down. - -@item control -The -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -bit in the character code indicates a non-@acronym{ASCII} -control character. - -@sc{ascii} control characters such as @kbd{C-a} have special basic -codes of their own, so Emacs needs no special bit to indicate them. -Thus, the code for @kbd{C-a} is just 1. - -But if you type a control combination not in @acronym{ASCII}, such as -@kbd{%} with the control key, the numeric value you get is the code -for @kbd{%} plus -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -(assuming the terminal supports non-@acronym{ASCII} -control characters). - -@item shift -The -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit in the character code indicates an @acronym{ASCII} control -character typed with the shift key held down. - -For letters, the basic code itself indicates upper versus lower case; -for digits and punctuation, the shift key selects an entirely different -character with a different basic code. In order to keep within the -@acronym{ASCII} character set whenever possible, Emacs avoids using the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit for those characters. - -However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from -@kbd{C-a}, so Emacs uses the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit in @kbd{C-A} and not in -@kbd{C-a}. - -@item hyper -The -@tex -@math{2^{24}} -@end tex -@ifnottex -2**24 -@end ifnottex -bit in the character code indicates a character -typed with the hyper key held down. - -@item super -The -@tex -@math{2^{23}} -@end tex -@ifnottex -2**23 -@end ifnottex -bit in the character code indicates a character -typed with the super key held down. - -@item alt -The -@tex -@math{2^{22}} -@end tex -@ifnottex -2**22 -@end ifnottex -bit in the character code indicates a character typed with -the alt key held down. (On some terminals, the key labeled @key{ALT} -is actually the meta key.) -@end table - - It is best to avoid mentioning specific bit numbers in your program. -To test the modifier bits of a character, use the function -@code{event-modifiers} (@pxref{Classifying Events}). When making key -bindings, you can use the read syntax for characters with modifier bits -(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with -@code{define-key}, you can use lists such as @code{(control hyper ?x)} to -specify the characters (@pxref{Changing Key Bindings}). The function -@code{event-convert-list} converts such a list into an event type -(@pxref{Classifying Events}). - -@node Function Keys -@subsection Function Keys - -@cindex function keys -Most keyboards also have @dfn{function keys}---keys that have names or -symbols that are not characters. Function keys are represented in Emacs -Lisp as symbols; the symbol's name is the function key's label, in lower -case. For example, pressing a key labeled @key{F1} places the symbol -@code{f1} in the input stream. - -The event type of a function key event is the event symbol itself. -@xref{Classifying Events}. - -Here are a few special cases in the symbol-naming convention for -function keys: - -@table @asis -@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete} -These keys correspond to common @acronym{ASCII} control characters that have -special keys on most keyboards. - -In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the -terminal can distinguish between them, Emacs conveys the distinction to -Lisp programs by representing the former as the integer 9, and the -latter as the symbol @code{tab}. - -Most of the time, it's not useful to distinguish the two. So normally -@code{function-key-map} (@pxref{Translation Keymaps}) is set up to map -@code{tab} into 9. Thus, a key binding for character code 9 (the -character @kbd{C-i}) also applies to @code{tab}. Likewise for the other -symbols in this group. The function @code{read-char} likewise converts -these events into characters. - -In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace} -converts into the character code 127 (@key{DEL}), not into code 8 -(@key{BS}). This is what most users prefer. - -@item @code{left}, @code{up}, @code{right}, @code{down} -Cursor arrow keys -@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{} -Keypad keys (to the right of the regular keyboard). -@item @code{kp-0}, @code{kp-1}, @dots{} -Keypad keys with digits. -@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} -Keypad PF keys. -@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down} -Keypad arrow keys. Emacs normally translates these into the -corresponding non-keypad keys @code{home}, @code{left}, @dots{} -@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete} -Additional keypad duplicates of keys ordinarily found elsewhere. Emacs -normally translates these into the like-named non-keypad keys. -@end table - -You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER}, -@key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to -represent them is with prefixes in the symbol name: - -@table @samp -@item A- -The alt modifier. -@item C- -The control modifier. -@item H- -The hyper modifier. -@item M- -The meta modifier. -@item S- -The shift modifier. -@item s- -The super modifier. -@end table - -Thus, the symbol for the key @key{F3} with @key{META} held down is -@code{M-f3}. When you use more than one prefix, we recommend you -write them in alphabetical order; but the order does not matter in -arguments to the key-binding lookup and modification functions. - -@node Mouse Events -@subsection Mouse Events - -Emacs supports four kinds of mouse events: click events, drag events, -button-down events, and motion events. All mouse events are represented -as lists. The @sc{car} of the list is the event type; this says which -mouse button was involved, and which modifier keys were used with it. -The event type can also distinguish double or triple button presses -(@pxref{Repeat Events}). The rest of the list elements give position -and time information. - -For key lookup, only the event type matters: two events of the same type -necessarily run the same command. The command can access the full -values of these events using the @samp{e} interactive code. -@xref{Interactive Codes}. - -A key sequence that starts with a mouse event is read using the keymaps -of the buffer in the window that the mouse was in, not the current -buffer. This does not imply that clicking in a window selects that -window or its buffer---that is entirely under the control of the command -binding of the key sequence. - -@node Click Events -@subsection Click Events -@cindex click event -@cindex mouse click event - -When the user presses a mouse button and releases it at the same -location, that generates a @dfn{click} event. All mouse click event -share the same format: - -@example -(@var{event-type} @var{position} @var{click-count}) -@end example - -@table @asis -@item @var{event-type} -This is a symbol that indicates which mouse button was used. It is -one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the -buttons are numbered left to right. - -You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, -@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift -and super, just as you would with function keys. - -This symbol also serves as the event type of the event. Key bindings -describe events by their types; thus, if there is a key binding for -@code{mouse-1}, that binding would apply to all events whose -@var{event-type} is @code{mouse-1}. - -@item @var{position} -This is the position where the mouse click occurred. The actual -format of @var{position} depends on what part of a window was clicked -on. - -For mouse click events in the text area, mode line, header line, or in -the marginal areas, @var{position} has this form: - -@example -(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} - @var{object} @var{text-pos} (@var{col} . @var{row}) - @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) -@end example - -@table @asis -@item @var{window} -This is the window in which the click occurred. - -@item @var{pos-or-area} -This is the buffer position of the character clicked on in the text -area, or if clicked outside the text area, it is the window area in -which the click occurred. It is one of the symbols @code{mode-line}, -@code{header-line}, @code{vertical-line}, @code{left-margin}, -@code{right-margin}, @code{left-fringe}, or @code{right-fringe}. - -In one special case, @var{pos-or-area} is a list containing a symbol (one -of the symbols listed above) instead of just the symbol. This happens -after the imaginary prefix keys for the event are inserted into the -input stream. @xref{Key Sequence Input}. - - -@item @var{x}, @var{y} -These are the pixel coordinates of the click, relative to -the top left corner of @var{window}, which is @code{(0 . 0)}. -For the mode or header line, @var{y} does not have meaningful data. -For the vertical line, @var{x} does not have meaningful data. - -@item @var{timestamp} -This is the time at which the event occurred, in milliseconds. - -@item @var{object} -This is the object on which the click occurred. It is either -@code{nil} if there is no string property, or it has the form -(@var{string} . @var{string-pos}) when there is a string-type text -property at the click position. - -@table @asis -@item @var{string} -This is the string on which the click occurred, including any -properties. - -@item @var{string-pos} -This is the position in the string on which the click occurred, -relevant if properties at the click need to be looked up. -@end table - -@item @var{text-pos} -For clicks on a marginal area or on a fringe, this is the buffer -position of the first visible character in the corresponding line in -the window. For other events, it is the current buffer position in -the window. - -@item @var{col}, @var{row} -These are the actual coordinates of the glyph under the @var{x}, -@var{y} position, possibly padded with default character width -glyphs if @var{x} is beyond the last glyph on the line. - -@item @var{image} -This is the image object on which the click occurred. It is either -@code{nil} if there is no image at the position clicked on, or it is -an image object as returned by @code{find-image} if click was in an image. - -@item @var{dx}, @var{dy} -These are the pixel coordinates of the click, relative to -the top left corner of @var{object}, which is @code{(0 . 0)}. If -@var{object} is @code{nil}, the coordinates are relative to the top -left corner of the character glyph clicked on. - -@item @var{width}, @var{height} -These are the pixel width and height of @var{object} or, if this is -@code{nil}, those of the character glyph clicked on. -@end table - -@sp 1 -For mouse clicks on a scroll-bar, @var{position} has this form: - -@example -(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part}) -@end example - -@table @asis -@item @var{window} -This is the window whose scroll-bar was clicked on. - -@item @var{area} -This is the scroll bar where the click occurred. It is one of the -symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}. - -@item @var{portion} -This is the distance of the click from the top or left end of -the scroll bar. - -@item @var{whole} -This is the length of the entire scroll bar. - -@item @var{timestamp} -This is the time at which the event occurred, in milliseconds. - -@item @var{part} -This is the part of the scroll-bar which was clicked on. It is one -of the symbols @code{above-handle}, @code{handle}, @code{below-handle}, -@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}. -@end table - -@item @var{click-count} -This is the number of rapid repeated presses so far of the same mouse -button. @xref{Repeat Events}. -@end table - -@node Drag Events -@subsection Drag Events -@cindex drag event -@cindex mouse drag event - -With Emacs, you can have a drag event without even changing your -clothes. A @dfn{drag event} happens every time the user presses a mouse -button and then moves the mouse to a different character position before -releasing the button. Like all mouse events, drag events are -represented in Lisp as lists. The lists record both the starting mouse -position and the final position, like this: - -@example -(@var{event-type} - (@var{window1} START-POSITION) - (@var{window2} END-POSITION)) -@end example - -For a drag event, the name of the symbol @var{event-type} contains the -prefix @samp{drag-}. For example, dragging the mouse with button 2 -held down generates a @code{drag-mouse-2} event. The second and third -elements of the event give the starting and ending position of the -drag. They have the same form as @var{position} in a click event -(@pxref{Click Events}) that is not on the scroll bar part of the -window. You can access the second element of any mouse event in the -same way, with no need to distinguish drag events from others. - -The @samp{drag-} prefix follows the modifier key prefixes such as -@samp{C-} and @samp{M-}. - -If @code{read-key-sequence} receives a drag event that has no key -binding, and the corresponding click event does have a binding, it -changes the drag event into a click event at the drag's starting -position. This means that you don't have to distinguish between click -and drag events unless you want to. - -@node Button-Down Events -@subsection Button-Down Events -@cindex button-down event - -Click and drag events happen when the user releases a mouse button. -They cannot happen earlier, because there is no way to distinguish a -click from a drag until the button is released. - -If you want to take action as soon as a button is pressed, you need to -handle @dfn{button-down} events.@footnote{Button-down is the -conservative antithesis of drag.} These occur as soon as a button is -pressed. They are represented by lists that look exactly like click -events (@pxref{Click Events}), except that the @var{event-type} symbol -name contains the prefix @samp{down-}. The @samp{down-} prefix follows -modifier key prefixes such as @samp{C-} and @samp{M-}. - -The function @code{read-key-sequence} ignores any button-down events -that don't have command bindings; therefore, the Emacs command loop -ignores them too. This means that you need not worry about defining -button-down events unless you want them to do something. The usual -reason to define a button-down event is so that you can track mouse -motion (by reading motion events) until the button is released. -@xref{Motion Events}. - -@node Repeat Events -@subsection Repeat Events -@cindex repeat events -@cindex double-click events -@cindex triple-click events -@cindex mouse events, repeated - -If you press the same mouse button more than once in quick succession -without moving the mouse, Emacs generates special @dfn{repeat} mouse -events for the second and subsequent presses. - -The most common repeat events are @dfn{double-click} events. Emacs -generates a double-click event when you click a button twice; the event -happens when you release the button (as is normal for all click -events). - -The event type of a double-click event contains the prefix -@samp{double-}. Thus, a double click on the second mouse button with -@key{meta} held down comes to the Lisp program as -@code{M-double-mouse-2}. If a double-click event has no binding, the -binding of the corresponding ordinary click event is used to execute -it. Thus, you need not pay attention to the double click feature -unless you really want to. - -When the user performs a double click, Emacs generates first an ordinary -click event, and then a double-click event. Therefore, you must design -the command binding of the double click event to assume that the -single-click command has already run. It must produce the desired -results of a double click, starting from the results of a single click. - -This is convenient, if the meaning of a double click somehow ``builds -on'' the meaning of a single click---which is recommended user interface -design practice for double clicks. - -If you click a button, then press it down again and start moving the -mouse with the button held down, then you get a @dfn{double-drag} event -when you ultimately release the button. Its event type contains -@samp{double-drag} instead of just @samp{drag}. If a double-drag event -has no binding, Emacs looks for an alternate binding as if the event -were an ordinary drag. - -Before the double-click or double-drag event, Emacs generates a -@dfn{double-down} event when the user presses the button down for the -second time. Its event type contains @samp{double-down} instead of just -@samp{down}. If a double-down event has no binding, Emacs looks for an -alternate binding as if the event were an ordinary button-down event. -If it finds no binding that way either, the double-down event is -ignored. - -To summarize, when you click a button and then press it again right -away, Emacs generates a down event and a click event for the first -click, a double-down event when you press the button again, and finally -either a double-click or a double-drag event. - -If you click a button twice and then press it again, all in quick -succession, Emacs generates a @dfn{triple-down} event, followed by -either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of -these events contain @samp{triple} instead of @samp{double}. If any -triple event has no binding, Emacs uses the binding that it would use -for the corresponding double event. - -If you click a button three or more times and then press it again, the -events for the presses beyond the third are all triple events. Emacs -does not have separate event types for quadruple, quintuple, etc.@: -events. However, you can look at the event list to find out precisely -how many times the button was pressed. - -@defun event-click-count event -This function returns the number of consecutive button presses that led -up to @var{event}. If @var{event} is a double-down, double-click or -double-drag event, the value is 2. If @var{event} is a triple event, -the value is 3 or greater. If @var{event} is an ordinary mouse event -(not a repeat event), the value is 1. -@end defun - -@defopt double-click-fuzz -To generate repeat events, successive mouse button presses must be at -approximately the same screen position. The value of -@code{double-click-fuzz} specifies the maximum number of pixels the -mouse may be moved (horizontally or vertically) between two successive -clicks to make a double-click. - -This variable is also the threshold for motion of the mouse to count -as a drag. -@end defopt - -@defopt double-click-time -To generate repeat events, the number of milliseconds between -successive button presses must be less than the value of -@code{double-click-time}. Setting @code{double-click-time} to -@code{nil} disables multi-click detection entirely. Setting it to -@code{t} removes the time limit; Emacs then detects multi-clicks by -position only. -@end defopt - -@node Motion Events -@subsection Motion Events -@cindex motion event -@cindex mouse motion events - -Emacs sometimes generates @dfn{mouse motion} events to describe motion -of the mouse without any button activity. Mouse motion events are -represented by lists that look like this: - -@example -(mouse-movement (POSITION)) -@end example - -The second element of the list describes the current position of the -mouse, just as in a click event (@pxref{Click Events}). - -The special form @code{track-mouse} enables generation of motion events -within its body. Outside of @code{track-mouse} forms, Emacs does not -generate events for mere motion of the mouse, and these events do not -appear. @xref{Mouse Tracking}. - -@node Focus Events -@subsection Focus Events -@cindex focus event - -Window systems provide general ways for the user to control which window -gets keyboard input. This choice of window is called the @dfn{focus}. -When the user does something to switch between Emacs frames, that -generates a @dfn{focus event}. The normal definition of a focus event, -in the global keymap, is to select a new frame within Emacs, as the user -would expect. @xref{Input Focus}. - -Focus events are represented in Lisp as lists that look like this: - -@example -(switch-frame @var{new-frame}) -@end example - -@noindent -where @var{new-frame} is the frame switched to. - -Most X window managers are set up so that just moving the mouse into a -window is enough to set the focus there. Emacs appears to do this, -because it changes the cursor to solid in the new frame. However, there -is no need for the Lisp program to know about the focus change until -some other kind of input arrives. So Emacs generates a focus event only -when the user actually types a keyboard key or presses a mouse button in -the new frame; just moving the mouse between frames does not generate a -focus event. - -A focus event in the middle of a key sequence would garble the -sequence. So Emacs never generates a focus event in the middle of a key -sequence. If the user changes focus in the middle of a key -sequence---that is, after a prefix key---then Emacs reorders the events -so that the focus event comes either before or after the multi-event key -sequence, and not within it. - -@node Misc Events -@subsection Miscellaneous System Events - -A few other event types represent occurrences within the system. - -@table @code -@cindex @code{delete-frame} event -@item (delete-frame (@var{frame})) -This kind of event indicates that the user gave the window manager -a command to delete a particular window, which happens to be an Emacs frame. - -The standard definition of the @code{delete-frame} event is to delete @var{frame}. - -@cindex @code{iconify-frame} event -@item (iconify-frame (@var{frame})) -This kind of event indicates that the user iconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been iconified, Emacs has no work to do. The purpose -of this event type is so that you can keep track of such events if you -want to. - -@cindex @code{make-frame-visible} event -@item (make-frame-visible (@var{frame})) -This kind of event indicates that the user deiconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been made visible, Emacs has no work to do. - -@cindex @code{wheel-up} event -@cindex @code{wheel-down} event -@item (wheel-up @var{position}) -@item (wheel-down @var{position}) -These kinds of event are generated by moving a mouse wheel. Their -usual meaning is a kind of scroll or zoom. - -The element @var{position} is a list describing the position of the -event, in the same format as used in a mouse-click event. - -This kind of event is generated only on some kinds of systems. On some -systems, @code{mouse-4} and @code{mouse-5} are used instead. For -portable code, use the variables @code{mouse-wheel-up-event} and -@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine -what event types to expect for the mouse wheel. - -@cindex @code{drag-n-drop} event -@item (drag-n-drop @var{position} @var{files}) -This kind of event is generated when a group of files is -selected in an application outside of Emacs, and then dragged and -dropped onto an Emacs frame. - -The element @var{position} is a list describing the position of the -event, in the same format as used in a mouse-click event, and -@var{files} is the list of file names that were dragged and dropped. -The usual way to handle this event is by visiting these files. - -This kind of event is generated, at present, only on some kinds of -systems. - -@cindex @code{help-echo} event -@item help-echo -This kind of event is generated when a mouse pointer moves onto a -portion of buffer text which has a @code{help-echo} text property. -The generated event has this form: - -@example -(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos}) -@end example - -@noindent -The precise meaning of the event parameters and the way these -parameters are used to display the help-echo text are described in -@ref{Text help-echo}. - -@cindex @code{sigusr1} event -@cindex @code{sigusr2} event -@cindex user signals -@item sigusr1 -@itemx sigusr2 -These events are generated when the Emacs process receives -the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no -additional data because signals do not carry additional information. - -To catch a user signal, bind the corresponding event to an interactive -command in the @code{special-event-map} (@pxref{Active Keymaps}). -The command is called with no arguments, and the specific signal event is -available in @code{last-input-event}. For example: - -@smallexample -(defun sigusr-handler () - (interactive) - (message "Caught signal %S" last-input-event)) - -(define-key special-event-map [sigusr1] 'sigusr-handler) -@end smallexample - -To test the signal handler, you can make Emacs send a signal to itself: - -@smallexample -(signal-process (emacs-pid) 'sigusr1) -@end smallexample -@end table - - If one of these events arrives in the middle of a key sequence---that -is, after a prefix key---then Emacs reorders the events so that this -event comes either before or after the multi-event key sequence, not -within it. - -@node Event Examples -@subsection Event Examples - -If the user presses and releases the left mouse button over the same -location, that generates a sequence of events like this: - -@smallexample -(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320)) -(mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180)) -@end smallexample - -While holding the control key down, the user might hold down the -second mouse button, and drag the mouse from one line to the next. -That produces two events, as shown here: - -@smallexample -(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)) -(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219) - (#<window 18 on NEWS> 3510 (0 . 28) -729648)) -@end smallexample - -While holding down the meta and shift keys, the user might press the -second mouse button on the window's mode line, and then drag the mouse -into another window. That produces a pair of events like these: - -@smallexample -(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)) -(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844) - (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3) - -453816)) -@end smallexample - -To handle a SIGUSR1 signal, define an interactive function, and -bind it to the @code{signal usr1} event sequence: - -@smallexample -(defun usr1-handler () - (interactive) - (message "Got USR1 signal")) -(global-set-key [signal usr1] 'usr1-handler) -@end smallexample - -@node Classifying Events -@subsection Classifying Events -@cindex event type - - Every event has an @dfn{event type}, which classifies the event for -key binding purposes. For a keyboard event, the event type equals the -event value; thus, the event type for a character is the character, and -the event type for a function key symbol is the symbol itself. For -events that are lists, the event type is the symbol in the @sc{car} of -the list. Thus, the event type is always a symbol or a character. - - Two events of the same type are equivalent where key bindings are -concerned; thus, they always run the same command. That does not -necessarily mean they do the same things, however, as some commands look -at the whole event to decide what to do. For example, some commands use -the location of a mouse event to decide where in the buffer to act. - - Sometimes broader classifications of events are useful. For example, -you might want to ask whether an event involved the @key{META} key, -regardless of which other key or mouse button was used. - - The functions @code{event-modifiers} and @code{event-basic-type} are -provided to get such information conveniently. - -@defun event-modifiers event -This function returns a list of the modifiers that @var{event} has. The -modifiers are symbols; they include @code{shift}, @code{control}, -@code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition, -the modifiers list of a mouse event symbol always contains one of -@code{click}, @code{drag}, and @code{down}. For double or triple -events, it also contains @code{double} or @code{triple}. - -The argument @var{event} may be an entire event object, or just an -event type. If @var{event} is a symbol that has never been used in an -event that has been read as input in the current Emacs session, then -@code{event-modifiers} can return @code{nil}, even when @var{event} -actually has modifiers. - -Here are some examples: - -@example -(event-modifiers ?a) - @result{} nil -(event-modifiers ?A) - @result{} (shift) -(event-modifiers ?\C-a) - @result{} (control) -(event-modifiers ?\C-%) - @result{} (control) -(event-modifiers ?\C-\S-a) - @result{} (control shift) -(event-modifiers 'f5) - @result{} nil -(event-modifiers 's-f5) - @result{} (super) -(event-modifiers 'M-S-f5) - @result{} (meta shift) -(event-modifiers 'mouse-1) - @result{} (click) -(event-modifiers 'down-mouse-1) - @result{} (down) -@end example - -The modifiers list for a click event explicitly contains @code{click}, -but the event symbol name itself does not contain @samp{click}. -@end defun - -@defun event-basic-type event -This function returns the key or mouse button that @var{event} -describes, with all modifiers removed. The @var{event} argument is as -in @code{event-modifiers}. For example: - -@example -(event-basic-type ?a) - @result{} 97 -(event-basic-type ?A) - @result{} 97 -(event-basic-type ?\C-a) - @result{} 97 -(event-basic-type ?\C-\S-a) - @result{} 97 -(event-basic-type 'f5) - @result{} f5 -(event-basic-type 's-f5) - @result{} f5 -(event-basic-type 'M-S-f5) - @result{} f5 -(event-basic-type 'down-mouse-1) - @result{} mouse-1 -@end example -@end defun - -@defun mouse-movement-p object -This function returns non-@code{nil} if @var{object} is a mouse movement -event. -@end defun - -@defun event-convert-list list -This function converts a list of modifier names and a basic event type -to an event type which specifies all of them. The basic event type -must be the last element of the list. For example, - -@example -(event-convert-list '(control ?a)) - @result{} 1 -(event-convert-list '(control meta ?a)) - @result{} -134217727 -(event-convert-list '(control super f1)) - @result{} C-s-f1 -@end example -@end defun - -@node Accessing Events -@subsection Accessing Events -@cindex mouse events, data in - - This section describes convenient functions for accessing the data in -a mouse button or motion event. - - These two functions return the starting or ending position of a -mouse-button event, as a list of this form: - -@example -(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} - @var{object} @var{text-pos} (@var{col} . @var{row}) - @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) -@end example - -@defun event-start event -This returns the starting position of @var{event}. - -If @var{event} is a click or button-down event, this returns the -location of the event. If @var{event} is a drag event, this returns the -drag's starting position. -@end defun - -@defun event-end event -This returns the ending position of @var{event}. - -If @var{event} is a drag event, this returns the position where the user -released the mouse button. If @var{event} is a click or button-down -event, the value is actually the starting position, which is the only -position such events have. -@end defun - -@cindex mouse position list, accessing - These functions take a position list as described above, and -return various parts of it. - -@defun posn-window position -Return the window that @var{position} is in. -@end defun - -@defun posn-area position -Return the window area recorded in @var{position}. It returns @code{nil} -when the event occurred in the text area of the window; otherwise, it -is a symbol identifying the area in which the event occurred. -@end defun - -@defun posn-point position -Return the buffer position in @var{position}. When the event occurred -in the text area of the window, in a marginal area, or on a fringe, -this is an integer specifying a buffer position. Otherwise, the value -is undefined. -@end defun - -@defun posn-x-y position -Return the pixel-based x and y coordinates in @var{position}, as a -cons cell @code{(@var{x} . @var{y})}. These coordinates are relative -to the window given by @code{posn-window}. - -This example shows how to convert these window-relative coordinates -into frame-relative coordinates: - -@example -(defun frame-relative-coordinates (position) - "Return frame-relative coordinates from POSITION." - (let* ((x-y (posn-x-y position)) - (window (posn-window position)) - (edges (window-inside-pixel-edges window))) - (cons (+ (car x-y) (car edges)) - (+ (cdr x-y) (cadr edges))))) -@end example -@end defun - -@defun posn-col-row position -Return the row and column (in units of the frame's default character -height and width) of @var{position}, as a cons cell @code{(@var{col} . -@var{row})}. These are computed from the @var{x} and @var{y} values -actually found in @var{position}. -@end defun - -@defun posn-actual-col-row position -Return the actual row and column in @var{position}, as a cons cell -@code{(@var{col} . @var{row})}. The values are the actual row number -in the window, and the actual character number in that row. It returns -@code{nil} if @var{position} does not include actual positions values. -You can use @code{posn-col-row} to get approximate values. -@end defun - -@defun posn-string position -Return the string object in @var{position}, either @code{nil}, or a -cons cell @code{(@var{string} . @var{string-pos})}. -@end defun - -@defun posn-image position -Return the image object in @var{position}, either @code{nil}, or an -image @code{(image ...)}. -@end defun - -@defun posn-object position -Return the image or string object in @var{position}, either -@code{nil}, an image @code{(image ...)}, or a cons cell -@code{(@var{string} . @var{string-pos})}. -@end defun - -@defun posn-object-x-y position -Return the pixel-based x and y coordinates relative to the upper left -corner of the object in @var{position} as a cons cell @code{(@var{dx} -. @var{dy})}. If the @var{position} is a buffer position, return the -relative position in the character at that position. -@end defun - -@defun posn-object-width-height position -Return the pixel width and height of the object in @var{position} as a -cons cell @code{(@var{width} . @var{height})}. If the @var{position} -is a buffer position, return the size of the character at that position. -@end defun - -@cindex timestamp of a mouse event -@defun posn-timestamp position -Return the timestamp in @var{position}. This is the time at which the -event occurred, in milliseconds. -@end defun - - These functions compute a position list given particular buffer -position or screen position. You can access the data in this position -list with the functions described above. - -@defun posn-at-point &optional pos window -This function returns a position list for position @var{pos} in -@var{window}. @var{pos} defaults to point in @var{window}; -@var{window} defaults to the selected window. - -@code{posn-at-point} returns @code{nil} if @var{pos} is not visible in -@var{window}. -@end defun - -@defun posn-at-x-y x y &optional frame-or-window whole -This function returns position information corresponding to pixel -coordinates @var{x} and @var{y} in a specified frame or window, -@var{frame-or-window}, which defaults to the selected window. -The coordinates @var{x} and @var{y} are relative to the -frame or window used. -If @var{whole} is @code{nil}, the coordinates are relative -to the window text area, otherwise they are relative to -the entire window area including scroll bars, margins and fringes. -@end defun - - These functions are useful for decoding scroll bar events. - -@defun scroll-bar-event-ratio event -This function returns the fractional vertical position of a scroll bar -event within the scroll bar. The value is a cons cell -@code{(@var{portion} . @var{whole})} containing two integers whose ratio -is the fractional position. -@end defun - -@defun scroll-bar-scale ratio total -This function multiplies (in effect) @var{ratio} by @var{total}, -rounding the result to an integer. The argument @var{ratio} is not a -number, but rather a pair @code{(@var{num} . @var{denom})}---typically a -value returned by @code{scroll-bar-event-ratio}. - -This function is handy for scaling a position on a scroll bar into a -buffer position. Here's how to do that: - -@example -(+ (point-min) - (scroll-bar-scale - (posn-x-y (event-start event)) - (- (point-max) (point-min)))) -@end example - -Recall that scroll bar events have two integers forming a ratio, in place -of a pair of x and y coordinates. -@end defun - -@node Strings of Events -@subsection Putting Keyboard Events in Strings -@cindex keyboard events in strings -@cindex strings with keyboard events - - In most of the places where strings are used, we conceptualize the -string as containing text characters---the same kind of characters found -in buffers or files. Occasionally Lisp programs use strings that -conceptually contain keyboard characters; for example, they may be key -sequences or keyboard macro definitions. However, storing keyboard -characters in a string is a complex matter, for reasons of historical -compatibility, and it is not always possible. - - We recommend that new programs avoid dealing with these complexities -by not storing keyboard events in strings. Here is how to do that: - -@itemize @bullet -@item -Use vectors instead of strings for key sequences, when you plan to use -them for anything other than as arguments to @code{lookup-key} and -@code{define-key}. For example, you can use -@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and -@code{this-command-keys-vector} instead of @code{this-command-keys}. - -@item -Use vectors to write key sequence constants containing meta characters, -even when passing them directly to @code{define-key}. - -@item -When you have to look at the contents of a key sequence that might be a -string, use @code{listify-key-sequence} (@pxref{Event Input Misc}) -first, to convert it to a list. -@end itemize - - The complexities stem from the modifier bits that keyboard input -characters can include. Aside from the Meta modifier, none of these -modifier bits can be included in a string, and the Meta modifier is -allowed only in special cases. - - The earliest GNU Emacs versions represented meta characters as codes -in the range of 128 to 255. At that time, the basic character codes -ranged from 0 to 127, so all keyboard character codes did fit in a -string. Many Lisp programs used @samp{\M-} in string constants to stand -for meta characters, especially in arguments to @code{define-key} and -similar functions, and key sequences and sequences of events were always -represented as strings. - - When we added support for larger basic character codes beyond 127, and -additional modifier bits, we had to change the representation of meta -characters. Now the flag that represents the Meta modifier in a -character is -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -and such numbers cannot be included in a string. - - To support programs with @samp{\M-} in string constants, there are -special rules for including certain meta characters in a string. -Here are the rules for interpreting a string as a sequence of input -characters: - -@itemize @bullet -@item -If the keyboard character value is in the range of 0 to 127, it can go -in the string unchanged. - -@item -The meta variants of those characters, with codes in the range of -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -to -@tex -@math{2^{27} + 127}, -@end tex -@ifnottex -2**27+127, -@end ifnottex -can also go in the string, but you must change their -numeric values. You must set the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit instead of the -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit, resulting in a value between 128 and 255. Only a unibyte string -can include these codes. - -@item -Non-@acronym{ASCII} characters above 256 can be included in a multibyte string. - -@item -Other keyboard character events cannot fit in a string. This includes -keyboard events in the range of 128 to 255. -@end itemize - - Functions such as @code{read-key-sequence} that construct strings of -keyboard input characters follow these rules: they construct vectors -instead of strings, when the events won't fit in a string. - - When you use the read syntax @samp{\M-} in a string, it produces a -code in the range of 128 to 255---the same code that you get if you -modify the corresponding keyboard event to put it in the string. Thus, -meta events in strings work consistently regardless of how they get into -the strings. - - However, most programs would do well to avoid these issues by -following the recommendations at the beginning of this section. - -@node Reading Input -@section Reading Input -@cindex read input -@cindex keyboard input - - The editor command loop reads key sequences using the function -@code{read-key-sequence}, which uses @code{read-event}. These and other -functions for event input are also available for use in Lisp programs. -See also @code{momentary-string-display} in @ref{Temporary Displays}, -and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for -functions and variables for controlling terminal input modes and -debugging terminal input. - - For higher-level input facilities, see @ref{Minibuffers}. - -@menu -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. -@end menu - -@node Key Sequence Input -@subsection Key Sequence Input -@cindex key sequence input - - The command loop reads input a key sequence at a time, by calling -@code{read-key-sequence}. Lisp programs can also call this function; -for example, @code{describe-key} uses it to read the key to describe. - -@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop -This function reads a key sequence and returns it as a string or -vector. It keeps reading events until it has accumulated a complete key -sequence; that is, enough to specify a non-prefix command using the -currently active keymaps. (Remember that a key sequence that starts -with a mouse event is read using the keymaps of the buffer in the -window that the mouse was in, not the current buffer.) - -If the events are all characters and all can fit in a string, then -@code{read-key-sequence} returns a string (@pxref{Strings of Events}). -Otherwise, it returns a vector, since a vector can hold all kinds of -events---characters, symbols, and lists. The elements of the string or -vector are the events in the key sequence. - -Reading a key sequence includes translating the events in various -ways. @xref{Translation Keymaps}. - -The argument @var{prompt} is either a string to be displayed in the -echo area as a prompt, or @code{nil}, meaning not to display a prompt. -The argument @var{continue-echo}, if non-@code{nil}, means to echo -this key as a continuation of the previous key. - -Normally any upper case event is converted to lower case if the -original event is undefined and the lower case equivalent is defined. -The argument @var{dont-downcase-last}, if non-@code{nil}, means do not -convert the last event to lower case. This is appropriate for reading -a key sequence to be defined. - -The argument @var{switch-frame-ok}, if non-@code{nil}, means that this -function should process a @code{switch-frame} event if the user -switches frames before typing anything. If the user switches frames -in the middle of a key sequence, or at the start of the sequence but -@var{switch-frame-ok} is @code{nil}, then the event will be put off -until after the current key sequence. - -The argument @var{command-loop}, if non-@code{nil}, means that this -key sequence is being read by something that will read commands one -after another. It should be @code{nil} if the caller will read just -one key sequence. - -In the following example, Emacs displays the prompt @samp{?} in the -echo area, and then the user types @kbd{C-x C-f}. - -@example -(read-key-sequence "?") - -@group ----------- Echo Area ---------- -?@kbd{C-x C-f} ----------- Echo Area ---------- - - @result{} "^X^F" -@end group -@end example - -The function @code{read-key-sequence} suppresses quitting: @kbd{C-g} -typed while reading with this function works like any other character, -and does not set @code{quit-flag}. @xref{Quitting}. -@end defun - -@defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop -This is like @code{read-key-sequence} except that it always -returns the key sequence as a vector, never as a string. -@xref{Strings of Events}. -@end defun - -@cindex upper case key sequence -@cindex downcasing in @code{lookup-key} -If an input character is upper-case (or has the shift modifier) and -has no key binding, but its lower-case equivalent has one, then -@code{read-key-sequence} converts the character to lower case. Note -that @code{lookup-key} does not perform case conversion in this way. - -The function @code{read-key-sequence} also transforms some mouse events. -It converts unbound drag events into click events, and discards unbound -button-down events entirely. It also reshuffles focus events and -miscellaneous window events so that they never appear in a key sequence -with any other events. - -@cindex @code{header-line} prefix key -@cindex @code{mode-line} prefix key -@cindex @code{vertical-line} prefix key -@cindex @code{horizontal-scroll-bar} prefix key -@cindex @code{vertical-scroll-bar} prefix key -@cindex @code{menu-bar} prefix key -@cindex mouse events, in special parts of frame -When mouse events occur in special parts of a window, such as a mode -line or a scroll bar, the event type shows nothing special---it is the -same symbol that would normally represent that combination of mouse -button and modifier keys. The information about the window part is kept -elsewhere in the event---in the coordinates. But -@code{read-key-sequence} translates this information into imaginary -``prefix keys,'' all of which are symbols: @code{header-line}, -@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, -@code{vertical-line}, and @code{vertical-scroll-bar}. You can define -meanings for mouse clicks in special window parts by defining key -sequences using these imaginary prefix keys. - -For example, if you call @code{read-key-sequence} and then click the -mouse on the window's mode line, you get two events, like this: - -@example -(read-key-sequence "Click on the mode line: ") - @result{} [mode-line - (mouse-1 - (#<window 6 on NEWS> mode-line - (40 . 63) 5959987))] -@end example - -@defvar num-input-keys -@c Emacs 19 feature -This variable's value is the number of key sequences processed so far in -this Emacs session. This includes key sequences read from the terminal -and key sequences read from keyboard macros being executed. -@end defvar - -@node Reading One Event -@subsection Reading One Event -@cindex reading a single event -@cindex event, reading only one - - The lowest level functions for command input are those that read a -single event. - -None of the three functions below suppresses quitting. - -@defun read-event &optional prompt inherit-input-method seconds -This function reads and returns the next event of command input, waiting -if necessary until an event is available. Events can come directly from -the user or from a keyboard macro. - -If the optional argument @var{prompt} is non-@code{nil}, it should be a -string to display in the echo area as a prompt. Otherwise, -@code{read-event} does not display any message to indicate it is waiting -for input; instead, it prompts by echoing: it displays descriptions of -the events that led to or were read by the current command. @xref{The -Echo Area}. - -If @var{inherit-input-method} is non-@code{nil}, then the current input -method (if any) is employed to make it possible to enter a -non-@acronym{ASCII} character. Otherwise, input method handling is disabled -for reading this event. - -If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} -moves the cursor temporarily to the echo area, to the end of any message -displayed there. Otherwise @code{read-event} does not move the cursor. - -If @var{seconds} is non-@code{nil}, it should be a number specifying -the maximum time to wait for input, in seconds. If no input arrives -within that time, @code{read-event} stops waiting and returns -@code{nil}. A floating-point value for @var{seconds} means to wait -for a fractional number of seconds. Some systems support only a whole -number of seconds; on these systems, @var{seconds} is rounded down. -If @var{seconds} is @code{nil}, @code{read-event} waits as long as -necessary for input to arrive. - -If @var{seconds} is @code{nil}, Emacs is considered idle while waiting -for user input to arrive. Idle timers---those created with -@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this -period. However, if @var{seconds} is non-@code{nil}, the state of -idleness remains unchanged. If Emacs is non-idle when -@code{read-event} is called, it remains non-idle throughout the -operation of @code{read-event}; if Emacs is idle (which can happen if -the call happens inside an idle timer), it remains idle. - -If @code{read-event} gets an event that is defined as a help character, -then in some cases @code{read-event} processes the event directly without -returning. @xref{Help Functions}. Certain other events, called -@dfn{special events}, are also processed directly within -@code{read-event} (@pxref{Special Events}). - -Here is what happens if you call @code{read-event} and then press the -right-arrow function key: - -@example -@group -(read-event) - @result{} right -@end group -@end example -@end defun - -@defun read-char &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the -user generates an event which is not a character (i.e. a mouse click or -function key event), @code{read-char} signals an error. The arguments -work as in @code{read-event}. - -In the first example, the user types the character @kbd{1} (@acronym{ASCII} -code 49). The second example shows a keyboard macro definition that -calls @code{read-char} from the minibuffer using @code{eval-expression}. -@code{read-char} reads the keyboard macro's very next character, which -is @kbd{1}. Then @code{eval-expression} displays its return value in -the echo area. - -@example -@group -(read-char) - @result{} 49 -@end group - -@group -;; @r{We assume here you use @kbd{M-:} to evaluate this.} -(symbol-function 'foo) - @result{} "^[:(read-char)^M1" -@end group -@group -(execute-kbd-macro 'foo) - @print{} 49 - @result{} nil -@end group -@end example -@end defun - -@defun read-char-exclusive &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the -user generates an event which is not a character, -@code{read-char-exclusive} ignores it and reads another event, until it -gets a character. The arguments work as in @code{read-event}. -@end defun - -@defvar num-nonmacro-input-events -This variable holds the total number of input events received so far -from the terminal---not counting those generated by keyboard macros. -@end defvar - -@node Event Mod -@subsection Modifying and Translating Input Events - - Emacs modifies every event it reads according to -@code{extra-keyboard-modifiers}, then translates it through -@code{keyboard-translate-table} (if applicable), before returning it -from @code{read-event}. - -@c Emacs 19 feature -@defvar extra-keyboard-modifiers -This variable lets Lisp programs ``press'' the modifier keys on the -keyboard. The value is a character. Only the modifiers of the -character matter. Each time the user types a keyboard key, it is -altered as if those modifier keys were held down. For instance, if -you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all -keyboard input characters typed during the scope of the binding will -have the control and meta modifiers applied to them. The character -@code{?\C-@@}, equivalent to the integer 0, does not count as a control -character for this purpose, but as a character with no modifiers. -Thus, setting @code{extra-keyboard-modifiers} to zero cancels any -modification. - -When using a window system, the program can ``press'' any of the -modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} -keys can be virtually pressed. - -Note that this variable applies only to events that really come from -the keyboard, and has no effect on mouse events or any other events. -@end defvar - -@defvar keyboard-translate-table -This variable is the translate table for keyboard characters. It lets -you reshuffle the keys on the keyboard without changing any command -bindings. Its value is normally a char-table, or else @code{nil}. -(It can also be a string or vector, but this is considered obsolete.) - -If @code{keyboard-translate-table} is a char-table -(@pxref{Char-Tables}), then each character read from the keyboard is -looked up in this char-table. If the value found there is -non-@code{nil}, then it is used instead of the actual input character. - -Note that this translation is the first thing that happens to a -character after it is read from the terminal. Record-keeping features -such as @code{recent-keys} and dribble files record the characters after -translation. - -Note also that this translation is done before the characters are -supplied to input methods (@pxref{Input Methods}). Use -@code{translation-table-for-input} (@pxref{Translation of Characters}), -if you want to translate characters after input methods operate. -@end defvar - -@defun keyboard-translate from to -This function modifies @code{keyboard-translate-table} to translate -character code @var{from} into character code @var{to}. It creates -the keyboard translate table if necessary. -@end defun - - Here's an example of using the @code{keyboard-translate-table} to -make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste -operations: - -@example -(keyboard-translate ?\C-x 'control-x) -(keyboard-translate ?\C-c 'control-c) -(keyboard-translate ?\C-v 'control-v) -(global-set-key [control-x] 'kill-region) -(global-set-key [control-c] 'kill-ring-save) -(global-set-key [control-v] 'yank) -@end example - -@noindent -On a graphical terminal that supports extended @acronym{ASCII} input, -you can still get the standard Emacs meanings of one of those -characters by typing it with the shift key. That makes it a different -character as far as keyboard translation is concerned, but it has the -same usual meaning. - - @xref{Translation Keymaps}, for mechanisms that translate event sequences -at the level of @code{read-key-sequence}. - -@node Invoking the Input Method -@subsection Invoking the Input Method - - The event-reading functions invoke the current input method, if any -(@pxref{Input Methods}). If the value of @code{input-method-function} -is non-@code{nil}, it should be a function; when @code{read-event} reads -a printing character (including @key{SPC}) with no modifier bits, it -calls that function, passing the character as an argument. - -@defvar input-method-function -If this is non-@code{nil}, its value specifies the current input method -function. - -@strong{Warning:} don't bind this variable with @code{let}. It is often -buffer-local, and if you bind it around reading input (which is exactly -when you @emph{would} bind it), switching buffers asynchronously while -Emacs is waiting will cause the value to be restored in the wrong -buffer. -@end defvar - - The input method function should return a list of events which should -be used as input. (If the list is @code{nil}, that means there is no -input, so @code{read-event} waits for another event.) These events are -processed before the events in @code{unread-command-events} -(@pxref{Event Input Misc}). Events -returned by the input method function are not passed to the input method -function again, even if they are printing characters with no modifier -bits. - - If the input method function calls @code{read-event} or -@code{read-key-sequence}, it should bind @code{input-method-function} to -@code{nil} first, to prevent recursion. - - The input method function is not called when reading the second and -subsequent events of a key sequence. Thus, these characters are not -subject to input method processing. The input method function should -test the values of @code{overriding-local-map} and -@code{overriding-terminal-local-map}; if either of these variables is -non-@code{nil}, the input method should put its argument into a list and -return that list with no further processing. - -@node Quoted Character Input -@subsection Quoted Character Input -@cindex quoted character input - - You can use the function @code{read-quoted-char} to ask the user to -specify a character, and allow the user to specify a control or meta -character conveniently, either literally or as an octal character code. -The command @code{quoted-insert} uses this function. - -@defun read-quoted-char &optional prompt -@cindex octal character input -@cindex control characters, reading -@cindex nonprinting characters, reading -This function is like @code{read-char}, except that if the first -character read is an octal digit (0-7), it reads any number of octal -digits (but stopping if a non-octal digit is found), and returns the -character represented by that numeric character code. If the -character that terminates the sequence of octal digits is @key{RET}, -it is discarded. Any other terminating character is used as input -after this function returns. - -Quitting is suppressed when the first character is read, so that the -user can enter a @kbd{C-g}. @xref{Quitting}. - -If @var{prompt} is supplied, it specifies a string for prompting the -user. The prompt string is always displayed in the echo area, followed -by a single @samp{-}. - -In the following example, the user types in the octal number 177 (which -is 127 in decimal). - -@example -(read-quoted-char "What character") - -@group ----------- Echo Area ---------- -What character @kbd{1 7 7}- ----------- Echo Area ---------- - - @result{} 127 -@end group -@end example -@end defun - -@need 2000 -@node Event Input Misc -@subsection Miscellaneous Event Input Features - -This section describes how to ``peek ahead'' at events without using -them up, how to check for pending input, and how to discard pending -input. See also the function @code{read-passwd} (@pxref{Reading a -Password}). - -@defvar unread-command-events -@cindex next input -@cindex peeking at input -This variable holds a list of events waiting to be read as command -input. The events are used in the order they appear in the list, and -removed one by one as they are used. - -The variable is needed because in some cases a function reads an event -and then decides not to use it. Storing the event in this variable -causes it to be processed normally, by the command loop or by the -functions to read command input. - -@cindex prefix argument unreading -For example, the function that implements numeric prefix arguments reads -any number of digits. When it finds a non-digit event, it must unread -the event so that it can be read normally by the command loop. -Likewise, incremental search uses this feature to unread events with no -special meaning in a search, because these events should exit the search -and then execute normally. - -The reliable and easy way to extract events from a key sequence so as to -put them in @code{unread-command-events} is to use -@code{listify-key-sequence} (@pxref{Strings of Events}). - -Normally you add events to the front of this list, so that the events -most recently unread will be reread first. - -Events read from this list are not normally added to the current -command's key sequence (as returned by e.g. @code{this-command-keys}), -as the events will already have been added once as they were read for -the first time. An element of the form @code{(@code{t} . @var{event})} -forces @var{event} to be added to the current command's key sequence. -@end defvar - -@defun listify-key-sequence key -This function converts the string or vector @var{key} to a list of -individual events, which you can put in @code{unread-command-events}. -@end defun - -@defvar unread-command-char -This variable holds a character to be read as command input. -A value of -1 means ``empty.'' - -This variable is mostly obsolete now that you can use -@code{unread-command-events} instead; it exists only to support programs -written for Emacs versions 18 and earlier. -@end defvar - -@defun input-pending-p -@cindex waiting for command key input -This function determines whether any command input is currently -available to be read. It returns immediately, with value @code{t} if -there is available input, @code{nil} otherwise. On rare occasions it -may return @code{t} when no input is available. -@end defun - -@defvar last-input-event -@defvarx last-input-char -This variable records the last terminal input event read, whether -as part of a command or explicitly by a Lisp program. - -In the example below, the Lisp program reads the character @kbd{1}, -@acronym{ASCII} code 49. It becomes the value of @code{last-input-event}, -while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate -this expression) remains the value of @code{last-command-event}. - -@example -@group -(progn (print (read-char)) - (print last-command-event) - last-input-event) - @print{} 49 - @print{} 5 - @result{} 49 -@end group -@end example - -The alias @code{last-input-char} exists for compatibility with -Emacs version 18. -@end defvar - -@defmac while-no-input body@dots{} -This construct runs the @var{body} forms and returns the value of the -last one---but only if no input arrives. If any input arrives during -the execution of the @var{body} forms, it aborts them (working much -like a quit). The @code{while-no-input} form returns @code{nil} if -aborted by a real quit, and returns @code{t} if aborted by arrival of -other input. - -If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil}, -arrival of input during those parts won't cause an abort until -the end of that part. - -If you want to be able to distinguish all possible values computed -by @var{body} from both kinds of abort conditions, write the code -like this: - -@example -(while-no-input - (list - (progn . @var{body}))) -@end example -@end defmac - -@defun discard-input -@cindex flushing input -@cindex discarding input -@cindex keyboard macro, terminating -This function discards the contents of the terminal input buffer and -cancels any keyboard macro that might be in the process of definition. -It returns @code{nil}. - -In the following example, the user may type a number of characters right -after starting the evaluation of the form. After the @code{sleep-for} -finishes sleeping, @code{discard-input} discards any characters typed -during the sleep. - -@example -(progn (sleep-for 2) - (discard-input)) - @result{} nil -@end example -@end defun - -@node Special Events -@section Special Events - -@cindex special events -Special events are handled at a very low level---as soon as they are -read. The @code{read-event} function processes these events itself, and -never returns them. Instead, it keeps waiting for the first event -that is not special and returns that one. - -Events that are handled in this way do not echo, they are never grouped -into key sequences, and they never appear in the value of -@code{last-command-event} or @code{(this-command-keys)}. They do not -discard a numeric argument, they cannot be unread with -@code{unread-command-events}, they may not appear in a keyboard macro, -and they are not recorded in a keyboard macro while you are defining -one. - -These events do, however, appear in @code{last-input-event} immediately -after they are read, and this is the way for the event's definition to -find the actual event. - -The events types @code{iconify-frame}, @code{make-frame-visible}, -@code{delete-frame}, @code{drag-n-drop}, and user signals like -@code{sigusr1} are normally handled in this way. The keymap which -defines how to handle special events---and which events are special---is -in the variable @code{special-event-map} (@pxref{Active Keymaps}). - -@node Waiting -@section Waiting for Elapsed Time or Input -@cindex waiting - - The wait functions are designed to wait for a certain amount of time -to pass or until there is input. For example, you may wish to pause in -the middle of a computation to allow the user time to view the display. -@code{sit-for} pauses and updates the screen, and returns immediately if -input comes in, while @code{sleep-for} pauses without updating the -screen. - -@defun sit-for seconds &optional nodisp -This function performs redisplay (provided there is no pending input -from the user), then waits @var{seconds} seconds, or until input is -available. The usual purpose of @code{sit-for} is to give the user -time to read text that you display. The value is @code{t} if -@code{sit-for} waited the full time with no input arriving -(@pxref{Event Input Misc}). Otherwise, the value is @code{nil}. - -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sit-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)}, -i.e. it requests a redisplay, without any delay, if there is no pending input. -@xref{Forcing Redisplay}. - -If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not -redisplay, but it still returns as soon as input is available (or when -the timeout elapses). - -In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be -interrupted, even by input from the standard input descriptor. It is -thus equivalent to @code{sleep-for}, which is described below. - -It is also possible to call @code{sit-for} with three arguments, -as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})}, -but that is considered obsolete. -@end defun - -@defun sleep-for seconds &optional millisec -This function simply pauses for @var{seconds} seconds without updating -the display. It pays no attention to available input. It returns -@code{nil}. - -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sleep-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The optional argument @var{millisec} specifies an additional waiting -period measured in milliseconds. This adds to the period specified by -@var{seconds}. If the system doesn't support waiting fractions of a -second, you get an error if you specify nonzero @var{millisec}. - -Use @code{sleep-for} when you wish to guarantee a delay. -@end defun - - @xref{Time of Day}, for functions to get the current time. - -@node Quitting -@section Quitting -@cindex @kbd{C-g} -@cindex quitting -@cindex interrupt Lisp functions - - Typing @kbd{C-g} while a Lisp function is running causes Emacs to -@dfn{quit} whatever it is doing. This means that control returns to the -innermost active command loop. - - Typing @kbd{C-g} while the command loop is waiting for keyboard input -does not cause a quit; it acts as an ordinary input character. In the -simplest case, you cannot tell the difference, because @kbd{C-g} -normally runs the command @code{keyboard-quit}, whose effect is to quit. -However, when @kbd{C-g} follows a prefix key, they combine to form an -undefined key. The effect is to cancel the prefix key as well as any -prefix argument. - - In the minibuffer, @kbd{C-g} has a different definition: it aborts out -of the minibuffer. This means, in effect, that it exits the minibuffer -and then quits. (Simply quitting would return to the command loop -@emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit -directly when the command reader is reading input is so that its meaning -can be redefined in the minibuffer in this way. @kbd{C-g} following a -prefix key is not redefined in the minibuffer, and it has its normal -effect of canceling the prefix key and prefix argument. This too -would not be possible if @kbd{C-g} always quit directly. - - When @kbd{C-g} does directly quit, it does so by setting the variable -@code{quit-flag} to @code{t}. Emacs checks this variable at appropriate -times and quits if it is not @code{nil}. Setting @code{quit-flag} -non-@code{nil} in any way thus causes a quit. - - At the level of C code, quitting cannot happen just anywhere; only at the -special places that check @code{quit-flag}. The reason for this is -that quitting at other places might leave an inconsistency in Emacs's -internal state. Because quitting is delayed until a safe place, quitting -cannot make Emacs crash. - - Certain functions such as @code{read-key-sequence} or -@code{read-quoted-char} prevent quitting entirely even though they wait -for input. Instead of quitting, @kbd{C-g} serves as the requested -input. In the case of @code{read-key-sequence}, this serves to bring -about the special behavior of @kbd{C-g} in the command loop. In the -case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used -to quote a @kbd{C-g}. - -@cindex preventing quitting - You can prevent quitting for a portion of a Lisp function by binding -the variable @code{inhibit-quit} to a non-@code{nil} value. Then, -although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the -usual result of this---a quit---is prevented. Eventually, -@code{inhibit-quit} will become @code{nil} again, such as when its -binding is unwound at the end of a @code{let} form. At that time, if -@code{quit-flag} is still non-@code{nil}, the requested quit happens -immediately. This behavior is ideal when you wish to make sure that -quitting does not happen within a ``critical section'' of the program. - -@cindex @code{read-quoted-char} quitting - In some functions (such as @code{read-quoted-char}), @kbd{C-g} is -handled in a special way that does not involve quitting. This is done -by reading the input with @code{inhibit-quit} bound to @code{t}, and -setting @code{quit-flag} to @code{nil} before @code{inhibit-quit} -becomes @code{nil} again. This excerpt from the definition of -@code{read-quoted-char} shows how this is done; it also shows that -normal quitting is permitted after the first character of input. - -@example -(defun read-quoted-char (&optional prompt) - "@dots{}@var{documentation}@dots{}" - (let ((message-log-max nil) done (first t) (code 0) char) - (while (not done) - (let ((inhibit-quit first) - @dots{}) - (and prompt (message "%s-" prompt)) - (setq char (read-event)) - (if inhibit-quit (setq quit-flag nil))) - @r{@dots{}set the variable @code{code}@dots{}}) - code)) -@end example - -@defvar quit-flag -If this variable is non-@code{nil}, then Emacs quits immediately, unless -@code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets -@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}. -@end defvar - -@defvar inhibit-quit -This variable determines whether Emacs should quit when @code{quit-flag} -is set to a value other than @code{nil}. If @code{inhibit-quit} is -non-@code{nil}, then @code{quit-flag} has no special effect. -@end defvar - -@defmac with-local-quit body@dots{} -This macro executes @var{body} forms in sequence, but allows quitting, at -least locally, within @var{body} even if @code{inhibit-quit} was -non-@code{nil} outside this construct. It returns the value of the -last form in @var{body}, unless exited by quitting, in which case -it returns @code{nil}. - -If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit}, -it only executes the @var{body}, and setting @code{quit-flag} causes -a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so -that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag} -triggers a special kind of local quit. This ends the execution of -@var{body} and exits the @code{with-local-quit} body with -@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit -will happen as soon as that is allowed. If @code{quit-flag} is -already non-@code{nil} at the beginning of @var{body}, the local quit -happens immediately and the body doesn't execute at all. - -This macro is mainly useful in functions that can be called from -timers, process filters, process sentinels, @code{pre-command-hook}, -@code{post-command-hook}, and other places where @code{inhibit-quit} is -normally bound to @code{t}. -@end defmac - -@deffn Command keyboard-quit -This function signals the @code{quit} condition with @code{(signal 'quit -nil)}. This is the same thing that quitting does. (See @code{signal} -in @ref{Errors}.) -@end deffn - - You can specify a character other than @kbd{C-g} to use for quitting. -See the function @code{set-input-mode} in @ref{Terminal Input}. - -@node Prefix Command Arguments -@section Prefix Command Arguments -@cindex prefix argument -@cindex raw prefix argument -@cindex numeric prefix argument - - Most Emacs commands can use a @dfn{prefix argument}, a number -specified before the command itself. (Don't confuse prefix arguments -with prefix keys.) The prefix argument is at all times represented by a -value, which may be @code{nil}, meaning there is currently no prefix -argument. Each command may use the prefix argument or ignore it. - - There are two representations of the prefix argument: @dfn{raw} and -@dfn{numeric}. The editor command loop uses the raw representation -internally, and so do the Lisp variables that store the information, but -commands can request either representation. - - Here are the possible values of a raw prefix argument: - -@itemize @bullet -@item -@code{nil}, meaning there is no prefix argument. Its numeric value is -1, but numerous commands make a distinction between @code{nil} and the -integer 1. - -@item -An integer, which stands for itself. - -@item -A list of one element, which is an integer. This form of prefix -argument results from one or a succession of @kbd{C-u}'s with no -digits. The numeric value is the integer in the list, but some -commands make a distinction between such a list and an integer alone. - -@item -The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was -typed, without following digits. The equivalent numeric value is -@minus{}1, but some commands make a distinction between the integer -@minus{}1 and the symbol @code{-}. -@end itemize - -We illustrate these possibilities by calling the following function with -various prefixes: - -@example -@group -(defun display-prefix (arg) - "Display the value of the raw prefix arg." - (interactive "P") - (message "%s" arg)) -@end group -@end example - -@noindent -Here are the results of calling @code{display-prefix} with various -raw prefix arguments: - -@example - M-x display-prefix @print{} nil - -C-u M-x display-prefix @print{} (4) - -C-u C-u M-x display-prefix @print{} (16) - -C-u 3 M-x display-prefix @print{} 3 - -M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)} - -C-u - M-x display-prefix @print{} - - -M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)} - -C-u - 7 M-x display-prefix @print{} -7 - -M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)} -@end example - - Emacs uses two variables to store the prefix argument: -@code{prefix-arg} and @code{current-prefix-arg}. Commands such as -@code{universal-argument} that set up prefix arguments for other -commands store them in @code{prefix-arg}. In contrast, -@code{current-prefix-arg} conveys the prefix argument to the current -command, so setting it has no effect on the prefix arguments for future -commands. - - Normally, commands specify which representation to use for the prefix -argument, either numeric or raw, in the @code{interactive} specification. -(@xref{Using Interactive}.) Alternatively, functions may look at the -value of the prefix argument directly in the variable -@code{current-prefix-arg}, but this is less clean. - -@defun prefix-numeric-value arg -This function returns the numeric meaning of a valid raw prefix argument -value, @var{arg}. The argument may be a symbol, a number, or a list. -If it is @code{nil}, the value 1 is returned; if it is @code{-}, the -value @minus{}1 is returned; if it is a number, that number is returned; -if it is a list, the @sc{car} of that list (which should be a number) is -returned. -@end defun - -@defvar current-prefix-arg -This variable holds the raw prefix argument for the @emph{current} -command. Commands may examine it directly, but the usual method for -accessing it is with @code{(interactive "P")}. -@end defvar - -@defvar prefix-arg -The value of this variable is the raw prefix argument for the -@emph{next} editing command. Commands such as @code{universal-argument} -that specify prefix arguments for the following command work by setting -this variable. -@end defvar - -@defvar last-prefix-arg -The raw prefix argument value used by the previous command. -@end defvar - - The following commands exist to set up prefix arguments for the -following command. Do not call them for any other reason. - -@deffn Command universal-argument -This command reads input and specifies a prefix argument for the -following command. Don't call this command yourself unless you know -what you are doing. -@end deffn - -@deffn Command digit-argument arg -This command adds to the prefix argument for the following command. The -argument @var{arg} is the raw prefix argument as it was before this -command; it is used to compute the updated prefix argument. Don't call -this command yourself unless you know what you are doing. -@end deffn - -@deffn Command negative-argument arg -This command adds to the numeric argument for the next command. The -argument @var{arg} is the raw prefix argument as it was before this -command; its value is negated to form the new prefix argument. Don't -call this command yourself unless you know what you are doing. -@end deffn - -@node Recursive Editing -@section Recursive Editing -@cindex recursive command loop -@cindex recursive editing level -@cindex command loop, recursive - - The Emacs command loop is entered automatically when Emacs starts up. -This top-level invocation of the command loop never exits; it keeps -running as long as Emacs does. Lisp programs can also invoke the -command loop. Since this makes more than one activation of the command -loop, we call it @dfn{recursive editing}. A recursive editing level has -the effect of suspending whatever command invoked it and permitting the -user to do arbitrary editing before resuming that command. - - The commands available during recursive editing are the same ones -available in the top-level editing loop and defined in the keymaps. -Only a few special commands exit the recursive editing level; the others -return to the recursive editing level when they finish. (The special -commands for exiting are always available, but they do nothing when -recursive editing is not in progress.) - - All command loops, including recursive ones, set up all-purpose error -handlers so that an error in a command run from the command loop will -not exit the loop. - -@cindex minibuffer input - Minibuffer input is a special kind of recursive editing. It has a few -special wrinkles, such as enabling display of the minibuffer and the -minibuffer window, but fewer than you might suppose. Certain keys -behave differently in the minibuffer, but that is only because of the -minibuffer's local map; if you switch windows, you get the usual Emacs -commands. - -@cindex @code{throw} example -@kindex exit -@cindex exit recursive editing -@cindex aborting - To invoke a recursive editing level, call the function -@code{recursive-edit}. This function contains the command loop; it also -contains a call to @code{catch} with tag @code{exit}, which makes it -possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a value other than @code{t}, -then @code{recursive-edit} returns normally to the function that called -it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. -Throwing a @code{t} value causes @code{recursive-edit} to quit, so that -control returns to the command loop one level up. This is called -@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). - - Most applications should not use recursive editing, except as part of -using the minibuffer. Usually it is more convenient for the user if you -change the major mode of the current buffer temporarily to a special -major mode, which should have a command to go back to the previous mode. -(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to -give the user different text to edit ``recursively,'' create and select -a new buffer in a special mode. In this mode, define a command to -complete the processing and go back to the previous buffer. (The -@kbd{m} command in Rmail does this.) - - Recursive edits are useful in debugging. You can insert a call to -@code{debug} into a function definition as a sort of breakpoint, so that -you can look around when the function gets there. @code{debug} invokes -a recursive edit but also provides the other features of the debugger. - - Recursive editing levels are also used when you type @kbd{C-r} in -@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}). - -@defun recursive-edit -@cindex suspend evaluation -This function invokes the editor command loop. It is called -automatically by the initialization of Emacs, to let the user begin -editing. When called from a Lisp program, it enters a recursive editing -level. - -If the current buffer is not the same as the selected window's buffer, -@code{recursive-edit} saves and restores the current buffer. Otherwise, -if you switch buffers, the buffer you switched to is current after -@code{recursive-edit} returns. - -In the following example, the function @code{simple-rec} first -advances point one word, then enters a recursive edit, printing out a -message in the echo area. The user can then do any editing desired, and -then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}. - -@example -(defun simple-rec () - (forward-word 1) - (message "Recursive edit in progress") - (recursive-edit) - (forward-word 1)) - @result{} simple-rec -(simple-rec) - @result{} nil -@end example -@end defun - -@deffn Command exit-recursive-edit -This function exits from the innermost recursive edit (including -minibuffer input). Its definition is effectively @code{(throw 'exit -nil)}. -@end deffn - -@deffn Command abort-recursive-edit -This function aborts the command that requested the innermost recursive -edit (including minibuffer input), by signaling @code{quit} -after exiting the recursive edit. Its definition is effectively -@code{(throw 'exit t)}. @xref{Quitting}. -@end deffn - -@deffn Command top-level -This function exits all recursive editing levels; it does not return a -value, as it jumps completely out of any computation directly back to -the main command loop. -@end deffn - -@defun recursion-depth -This function returns the current depth of recursive edits. When no -recursive edit is active, it returns 0. -@end defun - -@node Disabling Commands -@section Disabling Commands -@cindex disabled command - - @dfn{Disabling a command} marks the command as requiring user -confirmation before it can be executed. Disabling is used for commands -which might be confusing to beginning users, to prevent them from using -the commands by accident. - -@kindex disabled - The low-level mechanism for disabling a command is to put a -non-@code{nil} @code{disabled} property on the Lisp symbol for the -command. These properties are normally set up by the user's -init file (@pxref{Init File}) with Lisp expressions such as this: - -@example -(put 'upcase-region 'disabled t) -@end example - -@noindent -For a few commands, these properties are present by default (you can -remove them in your init file if you wish). - - If the value of the @code{disabled} property is a string, the message -saying the command is disabled includes that string. For example: - -@example -(put 'delete-region 'disabled - "Text deleted this way cannot be yanked back!\n") -@end example - - @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on -what happens when a disabled command is invoked interactively. -Disabling a command has no effect on calling it as a function from Lisp -programs. - -@deffn Command enable-command command -Allow @var{command} (a symbol) to be executed without special -confirmation from now on, and alter the user's init file (@pxref{Init -File}) so that this will apply to future sessions. -@end deffn - -@deffn Command disable-command command -Require special confirmation to execute @var{command} from now on, and -alter the user's init file so that this will apply to future sessions. -@end deffn - -@defvar disabled-command-function -The value of this variable should be a function. When the user -invokes a disabled command interactively, this function is called -instead of the disabled command. It can use @code{this-command-keys} -to determine what the user typed to run the command, and thus find the -command itself. - -The value may also be @code{nil}. Then all commands work normally, -even disabled ones. - -By default, the value is a function that asks the user whether to -proceed. -@end defvar - -@node Command History -@section Command History -@cindex command history -@cindex complex command -@cindex history of commands - - The command loop keeps a history of the complex commands that have -been executed, to make it convenient to repeat these commands. A -@dfn{complex command} is one for which the interactive argument reading -uses the minibuffer. This includes any @kbd{M-x} command, any -@kbd{M-:} command, and any command whose @code{interactive} -specification reads an argument from the minibuffer. Explicit use of -the minibuffer during the execution of the command itself does not cause -the command to be considered complex. - -@defvar command-history -This variable's value is a list of recent complex commands, each -represented as a form to evaluate. It continues to accumulate all -complex commands for the duration of the editing session, but when it -reaches the maximum size (@pxref{Minibuffer History}), the oldest -elements are deleted as new ones are added. - -@example -@group -command-history -@result{} ((switch-to-buffer "chistory.texi") - (describe-key "^X^[") - (visit-tags-table "~/emacs/src/") - (find-tag "repeat-complex-command")) -@end group -@end example -@end defvar - - This history list is actually a special case of minibuffer history -(@pxref{Minibuffer History}), with one special twist: the elements are -expressions rather than strings. - - There are a number of commands devoted to the editing and recall of -previous commands. The commands @code{repeat-complex-command}, and -@code{list-command-history} are described in the user manual -(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the -minibuffer, the usual minibuffer history commands are available. - -@node Keyboard Macros -@section Keyboard Macros -@cindex keyboard macros - - A @dfn{keyboard macro} is a canned sequence of input events that can -be considered a command and made the definition of a key. The Lisp -representation of a keyboard macro is a string or vector containing the -events. Don't confuse keyboard macros with Lisp macros -(@pxref{Macros}). - -@defun execute-kbd-macro kbdmacro &optional count loopfunc -This function executes @var{kbdmacro} as a sequence of events. If -@var{kbdmacro} is a string or vector, then the events in it are executed -exactly as if they had been input by the user. The sequence is -@emph{not} expected to be a single key sequence; normally a keyboard -macro definition consists of several key sequences concatenated. - -If @var{kbdmacro} is a symbol, then its function definition is used in -place of @var{kbdmacro}. If that is another symbol, this process repeats. -Eventually the result should be a string or vector. If the result is -not a symbol, string, or vector, an error is signaled. - -The argument @var{count} is a repeat count; @var{kbdmacro} is executed that -many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is -executed once. If it is 0, @var{kbdmacro} is executed over and over until it -encounters an error or a failing search. - -If @var{loopfunc} is non-@code{nil}, it is a function that is called, -without arguments, prior to each iteration of the macro. If -@var{loopfunc} returns @code{nil}, then this stops execution of the macro. - -@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}. -@end defun - -@defvar executing-kbd-macro -This variable contains the string or vector that defines the keyboard -macro that is currently executing. It is @code{nil} if no macro is -currently executing. A command can test this variable so as to behave -differently when run from an executing macro. Do not set this variable -yourself. -@end defvar - -@defvar defining-kbd-macro -This variable is non-@code{nil} if and only if a keyboard macro is -being defined. A command can test this variable so as to behave -differently while a macro is being defined. The value is -@code{append} while appending to the definition of an existing macro. -The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and -@code{end-kbd-macro} set this variable---do not set it yourself. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Displays}. -@end defvar - -@defvar last-kbd-macro -This variable is the definition of the most recently defined keyboard -macro. Its value is a string or vector, or @code{nil}. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Displays}. -@end defvar - -@defvar kbd-macro-termination-hook -This normal hook (@pxref{Standard Hooks}) is run when a keyboard -macro terminates, regardless of what caused it to terminate (reaching -the macro end or an error which ended the macro prematurely). -@end defvar - -@ignore - arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1 -@end ignore diff --git a/lispref/compile.texi b/lispref/compile.texi deleted file mode 100644 index 8f5c047fd6b..00000000000 --- a/lispref/compile.texi +++ /dev/null @@ -1,886 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/compile -@node Byte Compilation, Advising Functions, Loading, Top -@chapter Byte Compilation -@cindex byte compilation -@cindex byte-code -@cindex compilation (Emacs Lisp) - - Emacs Lisp has a @dfn{compiler} that translates functions written -in Lisp into a special representation called @dfn{byte-code} that can be -executed more efficiently. The compiler replaces Lisp function -definitions with byte-code. When a byte-code function is called, its -definition is evaluated by the @dfn{byte-code interpreter}. - - Because the byte-compiled code is evaluated by the byte-code -interpreter, instead of being executed directly by the machine's -hardware (as true compiled code is), byte-code is completely -transportable from machine to machine without recompilation. It is not, -however, as fast as true compiled code. - - Compiling a Lisp file with the Emacs byte compiler always reads the -file as multibyte text, even if Emacs was started with @samp{--unibyte}, -unless the file specifies otherwise. This is so that compilation gives -results compatible with running the same file without compilation. -@xref{Loading Non-ASCII}. - - In general, any version of Emacs can run byte-compiled code produced -by recent earlier versions of Emacs, but the reverse is not true. - -@vindex no-byte-compile - If you do not want a Lisp file to be compiled, ever, put a file-local -variable binding for @code{no-byte-compile} into it, like this: - -@example -;; -*-no-byte-compile: t; -*- -@end example - - @xref{Compilation Errors}, for how to investigate errors occurring in -byte compilation. - -@menu -* 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. -@end menu - -@node Speed of Byte-Code -@section Performance of Byte-Compiled Code - - A byte-compiled function is not as efficient as a primitive function -written in C, but runs much faster than the version written in Lisp. -Here is an example: - -@example -@group -(defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) -@result{} silly-loop -@end group - -@group -(silly-loop 100000) -@result{} ("Fri Mar 18 17:25:57 1994" - "Fri Mar 18 17:26:28 1994") ; @r{31 seconds} -@end group - -@group -(byte-compile 'silly-loop) -@result{} @r{[Compiled code not shown]} -@end group - -@group -(silly-loop 100000) -@result{} ("Fri Mar 18 17:26:52 1994" - "Fri Mar 18 17:26:58 1994") ; @r{6 seconds} -@end group -@end example - - In this example, the interpreted code required 31 seconds to run, -whereas the byte-compiled code required 6 seconds. These results are -representative, but actual results will vary greatly. - -@node Compilation Functions -@comment node-name, next, previous, up -@section The Compilation Functions -@cindex compilation functions - - You can byte-compile an individual function or macro definition with -the @code{byte-compile} function. You can compile a whole file with -@code{byte-compile-file}, or several files with -@code{byte-recompile-directory} or @code{batch-byte-compile}. - - The byte compiler produces error messages and warnings about each file -in a buffer called @samp{*Compile-Log*}. These report things in your -program that suggest a problem but are not necessarily erroneous. - -@cindex macro compilation - Be careful when writing macro calls in files that you may someday -byte-compile. Macro calls are expanded when they are compiled, so the -macros must already be defined for proper compilation. For more -details, see @ref{Compiling Macros}. If a program does not work the -same way when compiled as it does when interpreted, erroneous macro -definitions are one likely cause (@pxref{Problems with Macros}). -Inline (@code{defsubst}) functions are less troublesome; if you -compile a call to such a function before its definition is known, the -call will still work right, it will just run slower. - - Normally, compiling a file does not evaluate the file's contents or -load the file. But it does execute any @code{require} calls at top -level in the file. One way to ensure that necessary macro definitions -are available during compilation is to require the file that defines -them (@pxref{Named Features}). To avoid loading the macro definition files -when someone @emph{runs} the compiled program, write -@code{eval-when-compile} around the @code{require} calls (@pxref{Eval -During Compile}). - -@defun byte-compile symbol -This function byte-compiles the function definition of @var{symbol}, -replacing the previous definition with the compiled one. The function -definition of @var{symbol} must be the actual code for the function; -i.e., the compiler does not follow indirection to another symbol. -@code{byte-compile} returns the new, compiled definition of -@var{symbol}. - - If @var{symbol}'s definition is a byte-code function object, -@code{byte-compile} does nothing and returns @code{nil}. Lisp records -only one function definition for any symbol, and if that is already -compiled, non-compiled code is not available anywhere. So there is no -way to ``compile the same definition again.'' - -@example -@group -(defun factorial (integer) - "Compute factorial of INTEGER." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) -@result{} factorial -@end group - -@group -(byte-compile 'factorial) -@result{} -#[(integer) - "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" - [integer 1 * factorial] - 4 "Compute factorial of INTEGER."] -@end group -@end example - -@noindent -The result is a byte-code function object. The string it contains is -the actual byte-code; each character in it is an instruction or an -operand of an instruction. The vector contains all the constants, -variable names and function names used by the function, except for -certain primitives that are coded as special instructions. - -If the argument to @code{byte-compile} is a @code{lambda} expression, -it returns the corresponding compiled code, but does not store -it anywhere. -@end defun - -@deffn Command compile-defun &optional arg -This command reads the defun containing point, compiles it, and -evaluates the result. If you use this on a defun that is actually a -function definition, the effect is to install a compiled version of that -function. - -@code{compile-defun} normally displays the result of evaluation in the -echo area, but if @var{arg} is non-@code{nil}, it inserts the result -in the current buffer after the form it compiled. -@end deffn - -@deffn Command byte-compile-file filename &optional load -This function compiles a file of Lisp code named @var{filename} into a -file of byte-code. The output file's name is made by changing the -@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in -@samp{.el}, it adds @samp{.elc} to the end of @var{filename}. - -Compilation works by reading the input file one form at a time. If it -is a definition of a function or macro, the compiled function or macro -definition is written out. Other forms are batched together, then each -batch is compiled, and written so that its compiled code will be -executed when the file is read. All comments are discarded when the -input file is read. - -This command returns @code{t} if there were no errors and @code{nil} -otherwise. When called interactively, it prompts for the file name. - -If @var{load} is non-@code{nil}, this command loads the compiled file -after compiling it. Interactively, @var{load} is the prefix argument. - -@example -@group -% ls -l push* --rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el -@end group - -@group -(byte-compile-file "~/emacs/push.el") - @result{} t -@end group - -@group -% ls -l push* --rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el --rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc -@end group -@end example -@end deffn - -@deffn Command byte-recompile-directory directory &optional flag force -@cindex library compilation -This command recompiles every @samp{.el} file in @var{directory} (or -its subdirectories) that needs recompilation. A file needs -recompilation if a @samp{.elc} file exists but is older than the -@samp{.el} file. - -When a @samp{.el} file has no corresponding @samp{.elc} file, -@var{flag} says what to do. If it is @code{nil}, this command ignores -these files. If @var{flag} is 0, it compiles them. If it is neither -@code{nil} nor 0, it asks the user whether to compile each such file, -and asks about each subdirectory as well. - -Interactively, @code{byte-recompile-directory} prompts for -@var{directory} and @var{flag} is the prefix argument. - -If @var{force} is non-@code{nil}, this command recompiles every -@samp{.el} file that has a @samp{.elc} file. - -The returned value is unpredictable. -@end deffn - -@defun batch-byte-compile &optional noforce -This function runs @code{byte-compile-file} on files specified on the -command line. This function must be used only in a batch execution of -Emacs, as it kills Emacs on completion. An error in one file does not -prevent processing of subsequent files, but no output file will be -generated for it, and the Emacs process will terminate with a nonzero -status code. - -If @var{noforce} is non-@code{nil}, this function does not recompile -files that have an up-to-date @samp{.elc} file. - -@example -% emacs -batch -f batch-byte-compile *.el -@end example -@end defun - -@defun byte-code code-string data-vector max-stack -@cindex byte-code interpreter -This function actually interprets byte-code. A byte-compiled function -is actually defined with a body that calls @code{byte-code}. Don't call -this function yourself---only the byte compiler knows how to generate -valid calls to this function. - -In Emacs version 18, byte-code was always executed by way of a call to -the function @code{byte-code}. Nowadays, byte-code is usually executed -as part of a byte-code function object, and only rarely through an -explicit call to @code{byte-code}. -@end defun - -@node Docs and Compilation -@section Documentation Strings and Compilation -@cindex dynamic loading of documentation - - Functions and variables loaded from a byte-compiled file access their -documentation strings dynamically from the file whenever needed. This -saves space within Emacs, and makes loading faster because the -documentation strings themselves need not be processed while loading the -file. Actual access to the documentation strings becomes slower as a -result, but this normally is not enough to bother users. - - Dynamic access to documentation strings does have drawbacks: - -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer access the documentation strings for the functions and variables -in the file. - -@item -If you alter the compiled file (such as by compiling a new version), -then further access to documentation strings in this file will -probably give nonsense results. -@end itemize - - If your site installs Emacs following the usual procedures, these -problems will never normally occur. Installing a new version uses a new -directory with a different name; as long as the old version remains -installed, its files will remain unmodified in the places where they are -expected to be. - - However, if you have built Emacs yourself and use it from the -directory where you built it, you will experience this problem -occasionally if you edit and recompile Lisp files. When it happens, you -can cure the problem by reloading the file after recompiling it. - - You can turn off this feature at compile time by setting -@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful -mainly if you expect to change the file, and you want Emacs processes -that have already loaded it to keep working when the file changes. -You can do this globally, or for one source file by specifying a -file-local binding for the variable. One way to do that is by adding -this string to the file's first line: - -@example --*-byte-compile-dynamic-docstrings: nil;-*- -@end example - -@defvar byte-compile-dynamic-docstrings -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic loading of documentation strings. -@end defvar - -@cindex @samp{#@@@var{count}} -@cindex @samp{#$} - The dynamic documentation string feature writes compiled files that -use a special Lisp reader construct, @samp{#@@@var{count}}. This -construct skips the next @var{count} characters. It also uses the -@samp{#$} construct, which stands for ``the name of this file, as a -string.'' It is usually best not to use these constructs in Lisp source -files, since they are not designed to be clear to humans reading the -file. - -@node Dynamic Loading -@section Dynamic Loading of Individual Functions - -@cindex dynamic loading of functions -@cindex lazy loading - When you compile a file, you can optionally enable the @dfn{dynamic -function loading} feature (also known as @dfn{lazy loading}). With -dynamic function loading, loading the file doesn't fully read the -function definitions in the file. Instead, each function definition -contains a place-holder which refers to the file. The first time each -function is called, it reads the full definition from the file, to -replace the place-holder. - - The advantage of dynamic function loading is that loading the file -becomes much faster. This is a good thing for a file which contains -many separate user-callable functions, if using one of them does not -imply you will probably also use the rest. A specialized mode which -provides many keyboard commands often has that usage pattern: a user may -invoke the mode, but use only a few of the commands it provides. - - The dynamic loading feature has certain disadvantages: - -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer load the remaining function definitions not already loaded. - -@item -If you alter the compiled file (such as by compiling a new version), -then trying to load any function not already loaded will usually yield -nonsense results. -@end itemize - - These problems will never happen in normal circumstances with -installed Emacs files. But they are quite likely to happen with Lisp -files that you are changing. The easiest way to prevent these problems -is to reload the new compiled file immediately after each recompilation. - - The byte compiler uses the dynamic function loading feature if the -variable @code{byte-compile-dynamic} is non-@code{nil} at compilation -time. Do not set this variable globally, since dynamic loading is -desirable only for certain files. Instead, enable the feature for -specific source files with file-local variable bindings. For example, -you could do it by writing this text in the source file's first line: - -@example --*-byte-compile-dynamic: t;-*- -@end example - -@defvar byte-compile-dynamic -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic function loading. -@end defvar - -@defun fetch-bytecode function -If @var{function} is a byte-code function object, this immediately -finishes loading the byte code of @var{function} from its -byte-compiled file, if it is not fully loaded already. Otherwise, -it does nothing. It always returns @var{function}. -@end defun - -@node Eval During Compile -@section Evaluation During Compilation - - These features permit you to write code to be evaluated during -compilation of a program. - -@defspec eval-and-compile body@dots{} -This form marks @var{body} to be evaluated both when you compile the -containing code and when you run it (whether compiled or not). - -You can get a similar result by putting @var{body} in a separate file -and referring to that file with @code{require}. That method is -preferable when @var{body} is large. Effectively @code{require} is -automatically @code{eval-and-compile}, the package is loaded both when -compiling and executing. - -@code{autoload} is also effectively @code{eval-and-compile} too. It's -recognized when compiling, so uses of such a function don't produce -``not known to be defined'' warnings. - -Most uses of @code{eval-and-compile} are fairly sophisticated. - -If a macro has a helper function to build its result, and that macro -is used both locally and outside the package, then -@code{eval-and-compile} should be used to get the helper both when -compiling and then later when running. - -If functions are defined programmatically (with @code{fset} say), then -@code{eval-and-compile} can be used to have that done at compile-time -as well as run-time, so calls to those functions are checked (and -warnings about ``not known to be defined'' suppressed). -@end defspec - -@defspec eval-when-compile body@dots{} -This form marks @var{body} to be evaluated at compile time but not when -the compiled program is loaded. The result of evaluation by the -compiler becomes a constant which appears in the compiled program. If -you load the source file, rather than compiling it, @var{body} is -evaluated normally. - -@cindex compile-time constant -If you have a constant that needs some calculation to produce, -@code{eval-when-compile} can do that at compile-time. For example, - -@lisp -(defvar my-regexp - (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) -@end lisp - -@cindex macros, at compile time -If you're using another package, but only need macros from it (the -byte compiler will expand those), then @code{eval-when-compile} can be -used to load it for compiling, but not executing. For example, - -@lisp -(eval-when-compile - (require 'my-macro-package)) ;; only macros needed from this -@end lisp - -The same sort of thing goes for macros and @code{defsubst} functions -defined locally and only for use within the file. They are needed for -compiling the file, but in most cases they are not needed for -execution of the compiled file. For example, - -@lisp -(eval-when-compile - (unless (fboundp 'some-new-thing) - (defmacro 'some-new-thing () - (compatibility code)))) -@end lisp - -@noindent -This is often good for code that's only a fallback for compatibility -with other versions of Emacs. - -@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common -Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the -Common Lisp @samp{#.} reader macro (but not when interpreting) is closer -to what @code{eval-when-compile} does. -@end defspec - -@node Compiler Errors -@section Compiler Errors -@cindex compiler errors - - Byte compilation outputs all errors and warnings into the buffer -@samp{*Compile-Log*}. The messages include file names and line -numbers that identify the location of the problem. The usual Emacs -commands for operating on compiler diagnostics work properly on -these messages. - - However, the warnings about functions that were used but not -defined are always ``located'' at the end of the file, so these -commands won't find the places they are really used. To do that, -you must search for the function names. - - You can suppress the compiler warning for calling an undefined -function @var{func} by conditionalizing the function call on an -@code{fboundp} test, like this: - -@example -(if (fboundp '@var{func}) ...(@var{func} ...)...) -@end example - -@noindent -The call to @var{func} must be in the @var{then-form} of the -@code{if}, and @var{func} must appear quoted in the call to -@code{fboundp}. (This feature operates for @code{cond} as well.) - - Likewise, you can suppress a compiler warning for an unbound variable -@var{variable} by conditionalizing its use on a @code{boundp} test, -like this: - -@example -(if (boundp '@var{variable}) ...@var{variable}...) -@end example - -@noindent -The reference to @var{variable} must be in the @var{then-form} of the -@code{if}, and @var{variable} must appear quoted in the call to -@code{boundp}. - - You can suppress any compiler warnings using the construct -@code{with-no-warnings}: - -@c This is implemented with a defun, but conceptually it is -@c a special form. - -@defspec with-no-warnings body@dots{} -In execution, this is equivalent to @code{(progn @var{body}...)}, -but the compiler does not issue warnings for anything that occurs -inside @var{body}. - -We recommend that you use this construct around the smallest -possible piece of code. -@end defspec - -@node Byte-Code Objects -@section Byte-Code Function Objects -@cindex compiled function -@cindex byte-code function - - Byte-compiled functions have a special data type: they are -@dfn{byte-code function objects}. - - Internally, a byte-code function object is much like a vector; -however, the evaluator handles this data type specially when it appears -as a function to be called. The printed representation for a byte-code -function object is like that for a vector, with an additional @samp{#} -before the opening @samp{[}. - - A byte-code function object must have at least four elements; there is -no maximum number, but only the first six elements have any normal use. -They are: - -@table @var -@item arglist -The list of argument symbols. - -@item byte-code -The string containing the byte-code instructions. - -@item constants -The vector of Lisp objects referenced by the byte code. These include -symbols used as function names and variable names. - -@item stacksize -The maximum stack size this function needs. - -@item docstring -The documentation string (if any); otherwise, @code{nil}. The value may -be a number or a list, in case the documentation string is stored in a -file. Use the function @code{documentation} to get the real -documentation string (@pxref{Accessing Documentation}). - -@item interactive -The interactive spec (if any). This can be a string or a Lisp -expression. It is @code{nil} for a function that isn't interactive. -@end table - -Here's an example of a byte-code function object, in printed -representation. It is the definition of the command -@code{backward-sexp}. - -@example -#[(&optional arg) - "^H\204^F^@@\301^P\302^H[!\207" - [arg 1 forward-sexp] - 2 - 254435 - "p"] -@end example - - The primitive way to create a byte-code object is with -@code{make-byte-code}: - -@defun make-byte-code &rest elements -This function constructs and returns a byte-code function object -with @var{elements} as its elements. -@end defun - - You should not try to come up with the elements for a byte-code -function yourself, because if they are inconsistent, Emacs may crash -when you call the function. Always leave it to the byte compiler to -create these objects; it makes the elements consistent (we hope). - - You can access the elements of a byte-code object using @code{aref}; -you can also use @code{vconcat} to create a vector with the same -elements. - -@node Disassembly -@section Disassembled Byte-Code -@cindex disassembled byte-code - - People do not write byte-code; that job is left to the byte compiler. -But we provide a disassembler to satisfy a cat-like curiosity. The -disassembler converts the byte-compiled code into humanly readable -form. - - The byte-code interpreter is implemented as a simple stack machine. -It pushes values onto a stack of its own, then pops them off to use them -in calculations whose results are themselves pushed back on the stack. -When a byte-code function returns, it pops a value off the stack and -returns it as the value of the function. - - In addition to the stack, byte-code functions can use, bind, and set -ordinary Lisp variables, by transferring values between variables and -the stack. - -@deffn Command disassemble object &optional buffer-or-name -This command displays the disassembled code for @var{object}. In -interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, -the output goes in a buffer named @samp{*Disassemble*}. If -@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the -name of an existing buffer. Then the output goes there, at point, and -point is left before the output. - -The argument @var{object} can be a function name, a lambda expression -or a byte-code object. If it is a lambda expression, @code{disassemble} -compiles it and disassembles the resulting compiled code. -@end deffn - - Here are two examples of using the @code{disassemble} function. We -have added explanatory comments to help you relate the byte-code to the -Lisp source; these do not appear in the output of @code{disassemble}. -These examples show unoptimized byte-code. Nowadays byte-code is -usually optimized, but we did not want to rewrite these examples, since -they still serve their purpose. - -@example -@group -(defun factorial (integer) - "Compute factorial of an integer." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) - @result{} factorial -@end group - -@group -(factorial 4) - @result{} 24 -@end group - -@group -(disassemble 'factorial) - @print{} byte-code for factorial: - doc: Compute factorial of an integer. - args: (integer) -@end group - -@group -0 constant 1 ; @r{Push 1 onto stack.} - -1 varref integer ; @r{Get value of @code{integer}} - ; @r{from the environment} - ; @r{and push the value} - ; @r{onto the stack.} -@end group - -@group -2 eqlsign ; @r{Pop top two values off stack,} - ; @r{compare them,} - ; @r{and push result onto stack.} -@end group - -@group -3 goto-if-nil 10 ; @r{Pop and test top of stack;} - ; @r{if @code{nil}, go to 10,} - ; @r{else continue.} -@end group - -@group -6 constant 1 ; @r{Push 1 onto top of stack.} - -7 goto 17 ; @r{Go to 17 (in this case, 1 will be} - ; @r{returned by the function).} -@end group - -@group -10 constant * ; @r{Push symbol @code{*} onto stack.} - -11 varref integer ; @r{Push value of @code{integer} onto stack.} -@end group - -@group -12 constant factorial ; @r{Push @code{factorial} onto stack.} - -13 varref integer ; @r{Push value of @code{integer} onto stack.} - -14 sub1 ; @r{Pop @code{integer}, decrement value,} - ; @r{push new value onto stack.} -@end group - -@group - ; @r{Stack now contains:} - ; @minus{} @r{decremented value of @code{integer}} - ; @minus{} @r{@code{factorial}} - ; @minus{} @r{value of @code{integer}} - ; @minus{} @r{@code{*}} -@end group - -@group -15 call 1 ; @r{Call function @code{factorial} using} - ; @r{the first (i.e., the top) element} - ; @r{of the stack as the argument;} - ; @r{push returned value onto stack.} -@end group - -@group - ; @r{Stack now contains:} - ; @minus{} @r{result of recursive} - ; @r{call to @code{factorial}} - ; @minus{} @r{value of @code{integer}} - ; @minus{} @r{@code{*}} -@end group - -@group -16 call 2 ; @r{Using the first two} - ; @r{(i.e., the top two)} - ; @r{elements of the stack} - ; @r{as arguments,} - ; @r{call the function @code{*},} - ; @r{pushing the result onto the stack.} -@end group - -@group -17 return ; @r{Return the top element} - ; @r{of the stack.} - @result{} nil -@end group -@end example - -The @code{silly-loop} function is somewhat more complex: - -@example -@group -(defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) - @result{} silly-loop -@end group - -@group -(disassemble 'silly-loop) - @print{} byte-code for silly-loop: - doc: Return time before and after N iterations of a loop. - args: (n) - -0 constant current-time-string ; @r{Push} - ; @r{@code{current-time-string}} - ; @r{onto top of stack.} -@end group - -@group -1 call 0 ; @r{Call @code{current-time-string}} - ; @r{ with no argument,} - ; @r{ pushing result onto stack.} -@end group - -@group -2 varbind t1 ; @r{Pop stack and bind @code{t1}} - ; @r{to popped value.} -@end group - -@group -3 varref n ; @r{Get value of @code{n} from} - ; @r{the environment and push} - ; @r{the value onto the stack.} -@end group - -@group -4 sub1 ; @r{Subtract 1 from top of stack.} -@end group - -@group -5 dup ; @r{Duplicate the top of the stack;} - ; @r{i.e., copy the top of} - ; @r{the stack and push the} - ; @r{copy onto the stack.} -@end group - -@group -6 varset n ; @r{Pop the top of the stack,} - ; @r{and bind @code{n} to the value.} - - ; @r{In effect, the sequence @code{dup varset}} - ; @r{copies the top of the stack} - ; @r{into the value of @code{n}} - ; @r{without popping it.} -@end group - -@group -7 constant 0 ; @r{Push 0 onto stack.} -@end group - -@group -8 gtr ; @r{Pop top two values off stack,} - ; @r{test if @var{n} is greater than 0} - ; @r{and push result onto stack.} -@end group - -@group -9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0} - ; @r{(this exits the while loop).} - ; @r{else pop top of stack} - ; @r{and continue} -@end group - -@group -12 constant nil ; @r{Push @code{nil} onto stack} - ; @r{(this is the body of the loop).} -@end group - -@group -13 discard ; @r{Discard result of the body} - ; @r{of the loop (a while loop} - ; @r{is always evaluated for} - ; @r{its side effects).} -@end group - -@group -14 goto 3 ; @r{Jump back to beginning} - ; @r{of while loop.} -@end group - -@group -17 discard ; @r{Discard result of while loop} - ; @r{by popping top of stack.} - ; @r{This result is the value @code{nil} that} - ; @r{was not popped by the goto at 9.} -@end group - -@group -18 varref t1 ; @r{Push value of @code{t1} onto stack.} -@end group - -@group -19 constant current-time-string ; @r{Push} - ; @r{@code{current-time-string}} - ; @r{onto top of stack.} -@end group - -@group -20 call 0 ; @r{Call @code{current-time-string} again.} -@end group - -@group -21 list2 ; @r{Pop top two elements off stack,} - ; @r{create a list of them,} - ; @r{and push list onto stack.} -@end group - -@group -22 unbind 1 ; @r{Unbind @code{t1} in local environment.} - -23 return ; @r{Return value of the top of stack.} - - @result{} nil -@end group -@end example - - -@ignore - arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289 -@end ignore diff --git a/lispref/configure b/lispref/configure deleted file mode 100755 index 7f67f08dfa3..00000000000 --- a/lispref/configure +++ /dev/null @@ -1,775 +0,0 @@ -#! /bin/sh - -# Guess values for system-dependent variables and create Makefiles. -# Generated automatically using autoconf version 2.13 -# Copyright (C) 1992, 1993, 1994, 1995, 1996, 2001, 2002, 2003, 2004, -# 2005, 2006, 2007 Free Software Foundation, Inc. -# -# This configure script is free software; the Free Software Foundation -# gives unlimited permission to copy, distribute and modify it. - -# Defaults: -ac_help= -ac_default_prefix=/usr/local -# Any additions from configure.in: - -# Initialize some variables set by options. -# The variables have the same names as the options, with -# dashes changed to underlines. -build=NONE -cache_file=./config.cache -exec_prefix=NONE -host=NONE -no_create= -nonopt=NONE -no_recursion= -prefix=NONE -program_prefix=NONE -program_suffix=NONE -program_transform_name=s,x,x, -silent= -site= -srcdir= -target=NONE -verbose= -x_includes=NONE -x_libraries=NONE -bindir='${exec_prefix}/bin' -sbindir='${exec_prefix}/sbin' -libexecdir='${exec_prefix}/libexec' -datadir='${prefix}/share' -sysconfdir='${prefix}/etc' -sharedstatedir='${prefix}/com' -localstatedir='${prefix}/var' -libdir='${exec_prefix}/lib' -includedir='${prefix}/include' -oldincludedir='/usr/include' -infodir='${prefix}/info' -mandir='${prefix}/man' - -# Initialize some other variables. -subdirs= -MFLAGS= MAKEFLAGS= -SHELL=${CONFIG_SHELL-/bin/sh} -# Maximum number of lines to put in a shell here document. -ac_max_here_lines=12 - -ac_prev= -for ac_option -do - - # If the previous option needs an argument, assign it. - if test -n "$ac_prev"; then - eval "$ac_prev=\$ac_option" - ac_prev= - continue - fi - - case "$ac_option" in - -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; - *) ac_optarg= ;; - esac - - # Accept the important Cygnus configure options, so we can diagnose typos. - - case "$ac_option" in - - -bindir | --bindir | --bindi | --bind | --bin | --bi) - ac_prev=bindir ;; - -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) - bindir="$ac_optarg" ;; - - -build | --build | --buil | --bui | --bu) - ac_prev=build ;; - -build=* | --build=* | --buil=* | --bui=* | --bu=*) - build="$ac_optarg" ;; - - -cache-file | --cache-file | --cache-fil | --cache-fi \ - | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) - ac_prev=cache_file ;; - -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ - | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) - cache_file="$ac_optarg" ;; - - -datadir | --datadir | --datadi | --datad | --data | --dat | --da) - ac_prev=datadir ;; - -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ - | --da=*) - datadir="$ac_optarg" ;; - - -disable-* | --disable-*) - ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then - { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } - fi - ac_feature=`echo $ac_feature| sed 's/-/_/g'` - eval "enable_${ac_feature}=no" ;; - - -enable-* | --enable-*) - ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then - { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } - fi - ac_feature=`echo $ac_feature| sed 's/-/_/g'` - case "$ac_option" in - *=*) ;; - *) ac_optarg=yes ;; - esac - eval "enable_${ac_feature}='$ac_optarg'" ;; - - -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ - | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ - | --exec | --exe | --ex) - ac_prev=exec_prefix ;; - -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ - | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ - | --exec=* | --exe=* | --ex=*) - exec_prefix="$ac_optarg" ;; - - -gas | --gas | --ga | --g) - # Obsolete; use --with-gas. - with_gas=yes ;; - - -help | --help | --hel | --he) - # Omit some internal or obsolete options to make the list less imposing. - # This message is too long to be a string in the A/UX 3.1 sh. - cat << EOF -Usage: configure [options] [host] -Options: [defaults in brackets after descriptions] -Configuration: - --cache-file=FILE cache test results in FILE - --help print this message - --no-create do not create output files - --quiet, --silent do not print \`checking...' messages - --version print the version of autoconf that created configure -Directory and file names: - --prefix=PREFIX install architecture-independent files in PREFIX - [$ac_default_prefix] - --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX - [same as prefix] - --bindir=DIR user executables in DIR [EPREFIX/bin] - --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] - --libexecdir=DIR program executables in DIR [EPREFIX/libexec] - --datadir=DIR read-only architecture-independent data in DIR - [PREFIX/share] - --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] - --sharedstatedir=DIR modifiable architecture-independent data in DIR - [PREFIX/com] - --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] - --libdir=DIR object code libraries in DIR [EPREFIX/lib] - --includedir=DIR C header files in DIR [PREFIX/include] - --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] - --infodir=DIR info documentation in DIR [PREFIX/info] - --mandir=DIR man documentation in DIR [PREFIX/man] - --srcdir=DIR find the sources in DIR [configure dir or ..] - --program-prefix=PREFIX prepend PREFIX to installed program names - --program-suffix=SUFFIX append SUFFIX to installed program names - --program-transform-name=PROGRAM - run sed PROGRAM on installed program names -EOF - cat << EOF -Host type: - --build=BUILD configure for building on BUILD [BUILD=HOST] - --host=HOST configure for HOST [guessed] - --target=TARGET configure for TARGET [TARGET=HOST] -Features and packages: - --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) - --enable-FEATURE[=ARG] include FEATURE [ARG=yes] - --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] - --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) - --x-includes=DIR X include files are in DIR - --x-libraries=DIR X library files are in DIR -EOF - if test -n "$ac_help"; then - echo "--enable and --with options recognized:$ac_help" - fi - exit 0 ;; - - -host | --host | --hos | --ho) - ac_prev=host ;; - -host=* | --host=* | --hos=* | --ho=*) - host="$ac_optarg" ;; - - -includedir | --includedir | --includedi | --included | --include \ - | --includ | --inclu | --incl | --inc) - ac_prev=includedir ;; - -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ - | --includ=* | --inclu=* | --incl=* | --inc=*) - includedir="$ac_optarg" ;; - - -infodir | --infodir | --infodi | --infod | --info | --inf) - ac_prev=infodir ;; - -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) - infodir="$ac_optarg" ;; - - -libdir | --libdir | --libdi | --libd) - ac_prev=libdir ;; - -libdir=* | --libdir=* | --libdi=* | --libd=*) - libdir="$ac_optarg" ;; - - -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ - | --libexe | --libex | --libe) - ac_prev=libexecdir ;; - -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ - | --libexe=* | --libex=* | --libe=*) - libexecdir="$ac_optarg" ;; - - -localstatedir | --localstatedir | --localstatedi | --localstated \ - | --localstate | --localstat | --localsta | --localst \ - | --locals | --local | --loca | --loc | --lo) - ac_prev=localstatedir ;; - -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ - | --localstate=* | --localstat=* | --localsta=* | --localst=* \ - | --locals=* | --local=* | --loca=* | --loc=* | --lo=*) - localstatedir="$ac_optarg" ;; - - -mandir | --mandir | --mandi | --mand | --man | --ma | --m) - ac_prev=mandir ;; - -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) - mandir="$ac_optarg" ;; - - -nfp | --nfp | --nf) - # Obsolete; use --without-fp. - with_fp=no ;; - - -no-create | --no-create | --no-creat | --no-crea | --no-cre \ - | --no-cr | --no-c) - no_create=yes ;; - - -no-recursion | --no-recursion | --no-recursio | --no-recursi \ - | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) - no_recursion=yes ;; - - -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ - | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ - | --oldin | --oldi | --old | --ol | --o) - ac_prev=oldincludedir ;; - -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ - | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ - | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) - oldincludedir="$ac_optarg" ;; - - -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) - ac_prev=prefix ;; - -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) - prefix="$ac_optarg" ;; - - -program-prefix | --program-prefix | --program-prefi | --program-pref \ - | --program-pre | --program-pr | --program-p) - ac_prev=program_prefix ;; - -program-prefix=* | --program-prefix=* | --program-prefi=* \ - | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) - program_prefix="$ac_optarg" ;; - - -program-suffix | --program-suffix | --program-suffi | --program-suff \ - | --program-suf | --program-su | --program-s) - ac_prev=program_suffix ;; - -program-suffix=* | --program-suffix=* | --program-suffi=* \ - | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) - program_suffix="$ac_optarg" ;; - - -program-transform-name | --program-transform-name \ - | --program-transform-nam | --program-transform-na \ - | --program-transform-n | --program-transform- \ - | --program-transform | --program-transfor \ - | --program-transfo | --program-transf \ - | --program-trans | --program-tran \ - | --progr-tra | --program-tr | --program-t) - ac_prev=program_transform_name ;; - -program-transform-name=* | --program-transform-name=* \ - | --program-transform-nam=* | --program-transform-na=* \ - | --program-transform-n=* | --program-transform-=* \ - | --program-transform=* | --program-transfor=* \ - | --program-transfo=* | --program-transf=* \ - | --program-trans=* | --program-tran=* \ - | --progr-tra=* | --program-tr=* | --program-t=*) - program_transform_name="$ac_optarg" ;; - - -q | -quiet | --quiet | --quie | --qui | --qu | --q \ - | -silent | --silent | --silen | --sile | --sil) - silent=yes ;; - - -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) - ac_prev=sbindir ;; - -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ - | --sbi=* | --sb=*) - sbindir="$ac_optarg" ;; - - -sharedstatedir | --sharedstatedir | --sharedstatedi \ - | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ - | --sharedst | --shareds | --shared | --share | --shar \ - | --sha | --sh) - ac_prev=sharedstatedir ;; - -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ - | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ - | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ - | --sha=* | --sh=*) - sharedstatedir="$ac_optarg" ;; - - -site | --site | --sit) - ac_prev=site ;; - -site=* | --site=* | --sit=*) - site="$ac_optarg" ;; - - -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) - ac_prev=srcdir ;; - -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) - srcdir="$ac_optarg" ;; - - -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ - | --syscon | --sysco | --sysc | --sys | --sy) - ac_prev=sysconfdir ;; - -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ - | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) - sysconfdir="$ac_optarg" ;; - - -target | --target | --targe | --targ | --tar | --ta | --t) - ac_prev=target ;; - -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) - target="$ac_optarg" ;; - - -v | -verbose | --verbose | --verbos | --verbo | --verb) - verbose=yes ;; - - -version | --version | --versio | --versi | --vers) - echo "configure generated by autoconf version 2.13" - exit 0 ;; - - -with-* | --with-*) - ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then - { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } - fi - ac_package=`echo $ac_package| sed 's/-/_/g'` - case "$ac_option" in - *=*) ;; - *) ac_optarg=yes ;; - esac - eval "with_${ac_package}='$ac_optarg'" ;; - - -without-* | --without-*) - ac_package=`echo $ac_option|sed -e 's/-*without-//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then - { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } - fi - ac_package=`echo $ac_package| sed 's/-/_/g'` - eval "with_${ac_package}=no" ;; - - --x) - # Obsolete; use --with-x. - with_x=yes ;; - - -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ - | --x-incl | --x-inc | --x-in | --x-i) - ac_prev=x_includes ;; - -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ - | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) - x_includes="$ac_optarg" ;; - - -x-libraries | --x-libraries | --x-librarie | --x-librari \ - | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) - ac_prev=x_libraries ;; - -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ - | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) - x_libraries="$ac_optarg" ;; - - -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; } - ;; - - *) - if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then - echo "configure: warning: $ac_option: invalid host type" 1>&2 - fi - if test "x$nonopt" != xNONE; then - { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } - fi - nonopt="$ac_option" - ;; - - esac -done - -if test -n "$ac_prev"; then - { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; } -fi - -trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 - -# File descriptor usage: -# 0 standard input -# 1 file creation -# 2 errors and warnings -# 3 some systems may open it to /dev/tty -# 4 used on the Kubota Titan -# 6 checking for... messages and results -# 5 compiler messages saved in config.log -if test "$silent" = yes; then - exec 6>/dev/null -else - exec 6>&1 -fi -exec 5>./config.log - -echo "\ -This file contains any messages produced by compilers while -running configure, to aid debugging if configure makes a mistake. -" 1>&5 - -# Strip out --no-create and --no-recursion so they do not pile up. -# Also quote any args containing shell metacharacters. -ac_configure_args= -for ac_arg -do - case "$ac_arg" in - -no-create | --no-create | --no-creat | --no-crea | --no-cre \ - | --no-cr | --no-c) ;; - -no-recursion | --no-recursion | --no-recursio | --no-recursi \ - | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;; - *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*) - ac_configure_args="$ac_configure_args '$ac_arg'" ;; - *) ac_configure_args="$ac_configure_args $ac_arg" ;; - esac -done - -# NLS nuisances. -# Only set these to C if already set. These must not be set unconditionally -# because not all systems understand e.g. LANG=C (notably SCO). -# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'! -# Non-C LC_CTYPE values break the ctype check. -if test "${LANG+set}" = set; then LANG=C; export LANG; fi -if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi -if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi -if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi - -# confdefs.h avoids OS command line length limits that DEFS can exceed. -rm -rf conftest* confdefs.h -# AIX cpp loses on an empty file, so make sure it contains at least a newline. -echo > confdefs.h - -# A filename unique to this package, relative to the directory that -# configure is in, which we can look for to find out if srcdir is correct. -ac_unique_file=elisp.texi - -# Find the source files, if location was not specified. -if test -z "$srcdir"; then - ac_srcdir_defaulted=yes - # Try the directory containing this script, then its parent. - ac_prog=$0 - ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` - test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. - srcdir=$ac_confdir - if test ! -r $srcdir/$ac_unique_file; then - srcdir=.. - fi -else - ac_srcdir_defaulted=no -fi -if test ! -r $srcdir/$ac_unique_file; then - if test "$ac_srcdir_defaulted" = yes; then - { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; } - else - { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; } - fi -fi -srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'` - -# Prefer explicitly selected file to automatically selected ones. -if test -z "$CONFIG_SITE"; then - if test "x$prefix" != xNONE; then - CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" - else - CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" - fi -fi -for ac_site_file in $CONFIG_SITE; do - if test -r "$ac_site_file"; then - echo "loading site script $ac_site_file" - . "$ac_site_file" - fi -done - -if test -r "$cache_file"; then - echo "loading cache $cache_file" - . $cache_file -else - echo "creating cache $cache_file" - > $cache_file -fi - -ac_ext=c -# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. -ac_cpp='$CPP $CPPFLAGS' -ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' -ac_link='${CC-cc} -o conftest${ac_exeext} $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' -cross_compiling=$ac_cv_prog_cc_cross - -ac_exeext= -ac_objext=o -if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then - # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. - if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then - ac_n= ac_c=' -' ac_t=' ' - else - ac_n=-n ac_c= ac_t= - fi -else - ac_n= ac_c='\c' ac_t= -fi - - -trap '' 1 2 15 -cat > confcache <<\EOF -# This file is a shell script that caches the results of configure -# tests run on this system so they can be shared between configure -# scripts and configure runs. It is not useful on other systems. -# If it contains results you don't want to keep, you may remove or edit it. -# -# By default, configure uses ./config.cache as the cache file, -# creating it if it does not exist already. You can give configure -# the --cache-file=FILE option to use a different cache file; that is -# what configure does when it calls configure scripts in -# subdirectories, so they share the cache. -# Giving --cache-file=/dev/null disables caching, for debugging configure. -# config.status only pays attention to the cache file if you give it the -# --recheck option to rerun configure. -# -EOF -# The following way of writing the cache mishandles newlines in values, -# but we know of no workaround that is simple, portable, and efficient. -# So, don't put newlines in cache variables' values. -# Ultrix sh set writes to stderr and can't be redirected directly, -# and sets the high bit in the cache file unless we assign to the vars. -(set) 2>&1 | - case `(ac_space=' '; set | grep ac_space) 2>&1` in - *ac_space=\ *) - # `set' does not quote correctly, so add quotes (double-quote substitution - # turns \\\\ into \\, and sed turns \\ into \). - sed -n \ - -e "s/'/'\\\\''/g" \ - -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p" - ;; - *) - # `set' quotes correctly as required by POSIX, so do not add quotes. - sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p' - ;; - esac >> confcache -if cmp -s $cache_file confcache; then - : -else - if test -w $cache_file; then - echo "updating cache $cache_file" - cat confcache > $cache_file - else - echo "not updating unwritable cache $cache_file" - fi -fi -rm -f confcache - -trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 - -test "x$prefix" = xNONE && prefix=$ac_default_prefix -# Let make expand exec_prefix. -test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' - -# Any assignment to VPATH causes Sun make to only execute -# the first set of double-colon rules, so remove it if not needed. -# If there is a colon in the path, we need to keep it. -if test "x$srcdir" = x.; then - ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' -fi - -trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15 - -# Transform confdefs.h into DEFS. -# Protect against shell expansion while executing Makefile rules. -# Protect against Makefile macro expansion. -cat > conftest.defs <<\EOF -s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g -s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g -s%\[%\\&%g -s%\]%\\&%g -s%\$%$$%g -EOF -DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '` -rm -f conftest.defs - - -# Without the "./", some shells look in PATH for config.status. -: ${CONFIG_STATUS=./config.status} - -echo creating $CONFIG_STATUS -rm -f $CONFIG_STATUS -cat > $CONFIG_STATUS <<EOF -#! /bin/sh -# Generated automatically by configure. -# Run this file to recreate the current configuration. -# This directory was configured as follows, -# on host `(hostname || uname -n) 2>/dev/null | sed 1q`: -# -# $0 $ac_configure_args -# -# Compiler output produced by configure, useful for debugging -# configure, is in ./config.log if it exists. - -ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]" -for ac_option -do - case "\$ac_option" in - -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) - echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" - exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; - -version | --version | --versio | --versi | --vers | --ver | --ve | --v) - echo "$CONFIG_STATUS generated by autoconf version 2.13" - exit 0 ;; - -help | --help | --hel | --he | --h) - echo "\$ac_cs_usage"; exit 0 ;; - *) echo "\$ac_cs_usage"; exit 1 ;; - esac -done - -ac_given_srcdir=$srcdir - -trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15 -EOF -cat >> $CONFIG_STATUS <<EOF - -# Protect against being on the right side of a sed subst in config.status. -sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g; - s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF -$ac_vpsub -$extrasub -s%@SHELL@%$SHELL%g -s%@CFLAGS@%$CFLAGS%g -s%@CPPFLAGS@%$CPPFLAGS%g -s%@CXXFLAGS@%$CXXFLAGS%g -s%@FFLAGS@%$FFLAGS%g -s%@DEFS@%$DEFS%g -s%@LDFLAGS@%$LDFLAGS%g -s%@LIBS@%$LIBS%g -s%@exec_prefix@%$exec_prefix%g -s%@prefix@%$prefix%g -s%@program_transform_name@%$program_transform_name%g -s%@bindir@%$bindir%g -s%@sbindir@%$sbindir%g -s%@libexecdir@%$libexecdir%g -s%@datadir@%$datadir%g -s%@sysconfdir@%$sysconfdir%g -s%@sharedstatedir@%$sharedstatedir%g -s%@localstatedir@%$localstatedir%g -s%@libdir@%$libdir%g -s%@includedir@%$includedir%g -s%@oldincludedir@%$oldincludedir%g -s%@infodir@%$infodir%g -s%@mandir@%$mandir%g - -CEOF -EOF - -cat >> $CONFIG_STATUS <<\EOF - -# Split the substitutions into bite-sized pieces for seds with -# small command number limits, like on Digital OSF/1 and HP-UX. -ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script. -ac_file=1 # Number of current file. -ac_beg=1 # First line for current file. -ac_end=$ac_max_sed_cmds # Line after last line for current file. -ac_more_lines=: -ac_sed_cmds="" -while $ac_more_lines; do - if test $ac_beg -gt 1; then - sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file - else - sed "${ac_end}q" conftest.subs > conftest.s$ac_file - fi - if test ! -s conftest.s$ac_file; then - ac_more_lines=false - rm -f conftest.s$ac_file - else - if test -z "$ac_sed_cmds"; then - ac_sed_cmds="sed -f conftest.s$ac_file" - else - ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file" - fi - ac_file=`expr $ac_file + 1` - ac_beg=$ac_end - ac_end=`expr $ac_end + $ac_max_sed_cmds` - fi -done -if test -z "$ac_sed_cmds"; then - ac_sed_cmds=cat -fi -EOF - -cat >> $CONFIG_STATUS <<EOF - -CONFIG_FILES=\${CONFIG_FILES-"Makefile"} -EOF -cat >> $CONFIG_STATUS <<\EOF -for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then - # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in". - case "$ac_file" in - *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'` - ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;; - *) ac_file_in="${ac_file}.in" ;; - esac - - # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories. - - # Remove last slash and all that follows it. Not all systems have dirname. - ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` - if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then - # The file is in a subdirectory. - test ! -d "$ac_dir" && mkdir "$ac_dir" - ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`" - # A "../" for each directory in $ac_dir_suffix. - ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` - else - ac_dir_suffix= ac_dots= - fi - - case "$ac_given_srcdir" in - .) srcdir=. - if test -z "$ac_dots"; then top_srcdir=. - else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; - /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; - *) # Relative path. - srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" - top_srcdir="$ac_dots$ac_given_srcdir" ;; - esac - - - echo creating "$ac_file" - rm -f "$ac_file" - configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure." - case "$ac_file" in - *Makefile*) ac_comsub="1i\\ -# $configure_input" ;; - *) ac_comsub= ;; - esac - - ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"` - sed -e "$ac_comsub -s%@configure_input@%$configure_input%g -s%@srcdir@%$srcdir%g -s%@top_srcdir@%$top_srcdir%g -" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file -fi; done -rm -f conftest.s* - -EOF -cat >> $CONFIG_STATUS <<EOF - -EOF -cat >> $CONFIG_STATUS <<\EOF - -exit 0 -EOF -chmod +x $CONFIG_STATUS -rm -fr confdefs* $ac_clean_files -test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1 - diff --git a/lispref/configure.in b/lispref/configure.in deleted file mode 100644 index 7db2f8cab5e..00000000000 --- a/lispref/configure.in +++ /dev/null @@ -1,7 +0,0 @@ -dnl Process this file with autoconf to produce a configure script. -AC_INIT(elisp.texi) -AC_OUTPUT(Makefile) - -m4_if(dnl Do not change this comment - arch-tag: 61db4227-0d2b-4c4d-ad54-ca9a1ee518ea -)dnl diff --git a/lispref/control.texi b/lispref/control.texi deleted file mode 100644 index e99a6329f3e..00000000000 --- a/lispref/control.texi +++ /dev/null @@ -1,1291 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/control -@node Control Structures, Variables, Evaluation, Top -@chapter Control Structures -@cindex special forms for control structures -@cindex control structures - - A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}). -We control the order of execution of these forms by enclosing them in -@dfn{control structures}. Control structures are special forms which -control when, whether, or how many times to execute the forms they -contain. - - The simplest order of execution is sequential execution: first form -@var{a}, then form @var{b}, and so on. This is what happens when you -write several forms in succession in the body of a function, or at top -level in a file of Lisp code---the forms are executed in the order -written. We call this @dfn{textual order}. For example, if a function -body consists of two forms @var{a} and @var{b}, evaluation of the -function evaluates first @var{a} and then @var{b}. The result of -evaluating @var{b} becomes the value of the function. - - Explicit control structures make possible an order of execution other -than sequential. - - Emacs Lisp provides several kinds of control structure, including -other varieties of sequencing, conditionals, iteration, and (controlled) -jumps---all discussed below. The built-in control structures are -special forms since their subforms are not necessarily evaluated or not -evaluated sequentially. You can use macros to define your own control -structure constructs (@pxref{Macros}). - -@menu -* 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. -@end menu - -@node Sequencing -@section Sequencing - - Evaluating forms in the order they appear is the most common way -control passes from one form to another. In some contexts, such as in a -function body, this happens automatically. Elsewhere you must use a -control structure construct to do this: @code{progn}, the simplest -control construct of Lisp. - - A @code{progn} special form looks like this: - -@example -@group -(progn @var{a} @var{b} @var{c} @dots{}) -@end group -@end example - -@noindent -and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in -that order. These forms are called the @dfn{body} of the @code{progn} form. -The value of the last form in the body becomes the value of the entire -@code{progn}. @code{(progn)} returns @code{nil}. - -@cindex implicit @code{progn} - In the early days of Lisp, @code{progn} was the only way to execute -two or more forms in succession and use the value of the last of them. -But programmers found they often needed to use a @code{progn} in the -body of a function, where (at that time) only one form was allowed. So -the body of a function was made into an ``implicit @code{progn}'': -several forms are allowed just as in the body of an actual @code{progn}. -Many other control structures likewise contain an implicit @code{progn}. -As a result, @code{progn} is not used as much as it was many years ago. -It is needed now most often inside an @code{unwind-protect}, @code{and}, -@code{or}, or in the @var{then}-part of an @code{if}. - -@defspec progn forms@dots{} -This special form evaluates all of the @var{forms}, in textual -order, returning the result of the final form. - -@example -@group -(progn (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The third form" -@end group -@end example -@end defspec - - Two other control constructs likewise evaluate a series of forms but return -a different value: - -@defspec prog1 form1 forms@dots{} -This special form evaluates @var{form1} and all of the @var{forms}, in -textual order, returning the result of @var{form1}. - -@example -@group -(prog1 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The first form" -@end group -@end example - -Here is a way to remove the first element from a list in the variable -@code{x}, then return the value of that former element: - -@example -(prog1 (car x) (setq x (cdr x))) -@end example -@end defspec - -@defspec prog2 form1 form2 forms@dots{} -This special form evaluates @var{form1}, @var{form2}, and all of the -following @var{forms}, in textual order, returning the result of -@var{form2}. - -@example -@group -(prog2 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The second form" -@end group -@end example -@end defspec - -@node Conditionals -@section Conditionals -@cindex conditional evaluation - - Conditional control structures choose among alternatives. Emacs Lisp -has four conditional forms: @code{if}, which is much the same as in -other languages; @code{when} and @code{unless}, which are variants of -@code{if}; and @code{cond}, which is a generalized case statement. - -@defspec if condition then-form else-forms@dots{} -@code{if} chooses between the @var{then-form} and the @var{else-forms} -based on the value of @var{condition}. If the evaluated @var{condition} is -non-@code{nil}, @var{then-form} is evaluated and the result returned. -Otherwise, the @var{else-forms} are evaluated in textual order, and the -value of the last one is returned. (The @var{else} part of @code{if} is -an example of an implicit @code{progn}. @xref{Sequencing}.) - -If @var{condition} has the value @code{nil}, and no @var{else-forms} are -given, @code{if} returns @code{nil}. - -@code{if} is a special form because the branch that is not selected is -never evaluated---it is ignored. Thus, in the example below, -@code{true} is not printed because @code{print} is never called. - -@example -@group -(if nil - (print 'true) - 'very-false) -@result{} very-false -@end group -@end example -@end defspec - -@defmac when condition then-forms@dots{} -This is a variant of @code{if} where there are no @var{else-forms}, -and possibly several @var{then-forms}. In particular, - -@example -(when @var{condition} @var{a} @var{b} @var{c}) -@end example - -@noindent -is entirely equivalent to - -@example -(if @var{condition} (progn @var{a} @var{b} @var{c}) nil) -@end example -@end defmac - -@defmac unless condition forms@dots{} -This is a variant of @code{if} where there is no @var{then-form}: - -@example -(unless @var{condition} @var{a} @var{b} @var{c}) -@end example - -@noindent -is entirely equivalent to - -@example -(if @var{condition} nil - @var{a} @var{b} @var{c}) -@end example -@end defmac - -@defspec cond clause@dots{} -@code{cond} chooses among an arbitrary number of alternatives. Each -@var{clause} in the @code{cond} must be a list. The @sc{car} of this -list is the @var{condition}; the remaining elements, if any, the -@var{body-forms}. Thus, a clause looks like this: - -@example -(@var{condition} @var{body-forms}@dots{}) -@end example - -@code{cond} tries the clauses in textual order, by evaluating the -@var{condition} of each clause. If the value of @var{condition} is -non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its -@var{body-forms}, and the value of the last of @var{body-forms} becomes -the value of the @code{cond}. The remaining clauses are ignored. - -If the value of @var{condition} is @code{nil}, the clause ``fails,'' so -the @code{cond} moves on to the following clause, trying its -@var{condition}. - -If every @var{condition} evaluates to @code{nil}, so that every clause -fails, @code{cond} returns @code{nil}. - -A clause may also look like this: - -@example -(@var{condition}) -@end example - -@noindent -Then, if @var{condition} is non-@code{nil} when tested, the value of -@var{condition} becomes the value of the @code{cond} form. - -The following example has four clauses, which test for the cases where -the value of @code{x} is a number, string, buffer and symbol, -respectively: - -@example -@group -(cond ((numberp x) x) - ((stringp x) x) - ((bufferp x) - (setq temporary-hack x) ; @r{multiple body-forms} - (buffer-name x)) ; @r{in one clause} - ((symbolp x) (symbol-value x))) -@end group -@end example - -Often we want to execute the last clause whenever none of the previous -clauses was successful. To do this, we use @code{t} as the -@var{condition} of the last clause, like this: @code{(t -@var{body-forms})}. The form @code{t} evaluates to @code{t}, which is -never @code{nil}, so this clause never fails, provided the @code{cond} -gets to it at all. - -For example, - -@example -@group -(setq a 5) -(cond ((eq a 'hack) 'foo) - (t "default")) -@result{} "default" -@end group -@end example - -@noindent -This @code{cond} expression returns @code{foo} if the value of @code{a} -is @code{hack}, and returns the string @code{"default"} otherwise. -@end defspec - -Any conditional construct can be expressed with @code{cond} or with -@code{if}. Therefore, the choice between them is a matter of style. -For example: - -@example -@group -(if @var{a} @var{b} @var{c}) -@equiv{} -(cond (@var{a} @var{b}) (t @var{c})) -@end group -@end example - -@node Combining Conditions -@section Constructs for Combining Conditions - - This section describes three constructs that are often used together -with @code{if} and @code{cond} to express complicated conditions. The -constructs @code{and} and @code{or} can also be used individually as -kinds of multiple conditional constructs. - -@defun not condition -This function tests for the falsehood of @var{condition}. It returns -@code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise. -The function @code{not} is identical to @code{null}, and we recommend -using the name @code{null} if you are testing for an empty list. -@end defun - -@defspec and conditions@dots{} -The @code{and} special form tests whether all the @var{conditions} are -true. It works by evaluating the @var{conditions} one by one in the -order written. - -If any of the @var{conditions} evaluates to @code{nil}, then the result -of the @code{and} must be @code{nil} regardless of the remaining -@var{conditions}; so @code{and} returns @code{nil} right away, ignoring -the remaining @var{conditions}. - -If all the @var{conditions} turn out non-@code{nil}, then the value of -the last of them becomes the value of the @code{and} form. Just -@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate -because all the @var{conditions} turned out non-@code{nil}. (Think -about it; which one did not?) - -Here is an example. The first condition returns the integer 1, which is -not @code{nil}. Similarly, the second condition returns the integer 2, -which is not @code{nil}. The third condition is @code{nil}, so the -remaining condition is never evaluated. - -@example -@group -(and (print 1) (print 2) nil (print 3)) - @print{} 1 - @print{} 2 -@result{} nil -@end group -@end example - -Here is a more realistic example of using @code{and}: - -@example -@group -(if (and (consp foo) (eq (car foo) 'x)) - (message "foo is a list starting with x")) -@end group -@end example - -@noindent -Note that @code{(car foo)} is not executed if @code{(consp foo)} returns -@code{nil}, thus avoiding an error. - -@code{and} expressions can also be written using either @code{if} or -@code{cond}. Here's how: - -@example -@group -(and @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(if @var{arg1} (if @var{arg2} @var{arg3})) -@equiv{} -(cond (@var{arg1} (cond (@var{arg2} @var{arg3})))) -@end group -@end example -@end defspec - -@defspec or conditions@dots{} -The @code{or} special form tests whether at least one of the -@var{conditions} is true. It works by evaluating all the -@var{conditions} one by one in the order written. - -If any of the @var{conditions} evaluates to a non-@code{nil} value, then -the result of the @code{or} must be non-@code{nil}; so @code{or} returns -right away, ignoring the remaining @var{conditions}. The value it -returns is the non-@code{nil} value of the condition just evaluated. - -If all the @var{conditions} turn out @code{nil}, then the @code{or} -expression returns @code{nil}. Just @code{(or)}, with no -@var{conditions}, returns @code{nil}, appropriate because all the -@var{conditions} turned out @code{nil}. (Think about it; which one -did not?) - -For example, this expression tests whether @code{x} is either -@code{nil} or the integer zero: - -@example -(or (eq x nil) (eq x 0)) -@end example - -Like the @code{and} construct, @code{or} can be written in terms of -@code{cond}. For example: - -@example -@group -(or @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(cond (@var{arg1}) - (@var{arg2}) - (@var{arg3})) -@end group -@end example - -You could almost write @code{or} in terms of @code{if}, but not quite: - -@example -@group -(if @var{arg1} @var{arg1} - (if @var{arg2} @var{arg2} - @var{arg3})) -@end group -@end example - -@noindent -This is not completely equivalent because it can evaluate @var{arg1} or -@var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2} -@var{arg3})} never evaluates any argument more than once. -@end defspec - -@node Iteration -@section Iteration -@cindex iteration -@cindex recursion - - Iteration means executing part of a program repetitively. For -example, you might want to repeat some computation once for each element -of a list, or once for each integer from 0 to @var{n}. You can do this -in Emacs Lisp with the special form @code{while}: - -@defspec while condition forms@dots{} -@code{while} first evaluates @var{condition}. If the result is -non-@code{nil}, it evaluates @var{forms} in textual order. Then it -reevaluates @var{condition}, and if the result is non-@code{nil}, it -evaluates @var{forms} again. This process repeats until @var{condition} -evaluates to @code{nil}. - -There is no limit on the number of iterations that may occur. The loop -will continue until either @var{condition} evaluates to @code{nil} or -until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}). - -The value of a @code{while} form is always @code{nil}. - -@example -@group -(setq num 0) - @result{} 0 -@end group -@group -(while (< num 4) - (princ (format "Iteration %d." num)) - (setq num (1+ num))) - @print{} Iteration 0. - @print{} Iteration 1. - @print{} Iteration 2. - @print{} Iteration 3. - @result{} nil -@end group -@end example - -To write a ``repeat...until'' loop, which will execute something on each -iteration and then do the end-test, put the body followed by the -end-test in a @code{progn} as the first argument of @code{while}, as -shown here: - -@example -@group -(while (progn - (forward-line 1) - (not (looking-at "^$")))) -@end group -@end example - -@noindent -This moves forward one line and continues moving by lines until it -reaches an empty line. It is peculiar in that the @code{while} has no -body, just the end test (which also does the real work of moving point). -@end defspec - - The @code{dolist} and @code{dotimes} macros provide convenient ways to -write two common kinds of loops. - -@defmac dolist (var list [result]) body@dots{} -This construct executes @var{body} once for each element of -@var{list}, binding the variable @var{var} locally to hold the current -element. Then it returns the value of evaluating @var{result}, or -@code{nil} if @var{result} is omitted. For example, here is how you -could use @code{dolist} to define the @code{reverse} function: - -@example -(defun reverse (list) - (let (value) - (dolist (elt list value) - (setq value (cons elt value))))) -@end example -@end defmac - -@defmac dotimes (var count [result]) body@dots{} -This construct executes @var{body} once for each integer from 0 -(inclusive) to @var{count} (exclusive), binding the variable @var{var} -to the integer for the current iteration. Then it returns the value -of evaluating @var{result}, or @code{nil} if @var{result} is omitted. -Here is an example of using @code{dotimes} to do something 100 times: - -@example -(dotimes (i 100) - (insert "I will not obey absurd orders\n")) -@end example -@end defmac - -@node Nonlocal Exits -@section Nonlocal Exits -@cindex nonlocal exits - - A @dfn{nonlocal exit} is a transfer of control from one point in a -program to another remote point. Nonlocal exits can occur in Emacs Lisp -as a result of errors; you can also use them under explicit control. -Nonlocal exits unbind all variable bindings made by the constructs being -exited. - -@menu -* 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. -@end menu - -@node Catch and Throw -@subsection Explicit Nonlocal Exits: @code{catch} and @code{throw} - - Most control constructs affect only the flow of control within the -construct itself. The function @code{throw} is the exception to this -rule of normal program execution: it performs a nonlocal exit on -request. (There are other exceptions, but they are for error handling -only.) @code{throw} is used inside a @code{catch}, and jumps back to -that @code{catch}. For example: - -@example -@group -(defun foo-outer () - (catch 'foo - (foo-inner))) - -(defun foo-inner () - @dots{} - (if x - (throw 'foo t)) - @dots{}) -@end group -@end example - -@noindent -The @code{throw} form, if executed, transfers control straight back to -the corresponding @code{catch}, which returns immediately. The code -following the @code{throw} is not executed. The second argument of -@code{throw} is used as the return value of the @code{catch}. - - The function @code{throw} finds the matching @code{catch} based on the -first argument: it searches for a @code{catch} whose first argument is -@code{eq} to the one specified in the @code{throw}. If there is more -than one applicable @code{catch}, the innermost one takes precedence. -Thus, in the above example, the @code{throw} specifies @code{foo}, and -the @code{catch} in @code{foo-outer} specifies the same symbol, so that -@code{catch} is the applicable one (assuming there is no other matching -@code{catch} in between). - - Executing @code{throw} exits all Lisp constructs up to the matching -@code{catch}, including function calls. When binding constructs such as -@code{let} or function calls are exited in this way, the bindings are -unbound, just as they are when these constructs exit normally -(@pxref{Local Variables}). Likewise, @code{throw} restores the buffer -and position saved by @code{save-excursion} (@pxref{Excursions}), and -the narrowing status saved by @code{save-restriction} and the window -selection saved by @code{save-window-excursion} (@pxref{Window -Configurations}). It also runs any cleanups established with the -@code{unwind-protect} special form when it exits that form -(@pxref{Cleanups}). - - The @code{throw} need not appear lexically within the @code{catch} -that it jumps to. It can equally well be called from another function -called within the @code{catch}. As long as the @code{throw} takes place -chronologically after entry to the @code{catch}, and chronologically -before exit from it, it has access to that @code{catch}. This is why -@code{throw} can be used in commands such as @code{exit-recursive-edit} -that throw back to the editor command loop (@pxref{Recursive Editing}). - -@cindex CL note---only @code{throw} in Emacs -@quotation -@b{Common Lisp note:} Most other versions of Lisp, including Common Lisp, -have several ways of transferring control nonsequentially: @code{return}, -@code{return-from}, and @code{go}, for example. Emacs Lisp has only -@code{throw}. -@end quotation - -@defspec catch tag body@dots{} -@cindex tag on run time stack -@code{catch} establishes a return point for the @code{throw} function. -The return point is distinguished from other such return points by -@var{tag}, which may be any Lisp object except @code{nil}. The argument -@var{tag} is evaluated normally before the return point is established. - -With the return point in effect, @code{catch} evaluates the forms of the -@var{body} in textual order. If the forms execute normally (without -error or nonlocal exit) the value of the last body form is returned from -the @code{catch}. - -If a @code{throw} is executed during the execution of @var{body}, -specifying the same value @var{tag}, the @code{catch} form exits -immediately; the value it returns is whatever was specified as the -second argument of @code{throw}. -@end defspec - -@defun throw tag value -The purpose of @code{throw} is to return from a return point previously -established with @code{catch}. The argument @var{tag} is used to choose -among the various existing return points; it must be @code{eq} to the value -specified in the @code{catch}. If multiple return points match @var{tag}, -the innermost one is used. - -The argument @var{value} is used as the value to return from that -@code{catch}. - -@kindex no-catch -If no return point is in effect with tag @var{tag}, then a @code{no-catch} -error is signaled with data @code{(@var{tag} @var{value})}. -@end defun - -@node Examples of Catch -@subsection Examples of @code{catch} and @code{throw} - - One way to use @code{catch} and @code{throw} is to exit from a doubly -nested loop. (In most languages, this would be done with a ``go to.'') -Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} -varying from 0 to 9: - -@example -@group -(defun search-foo () - (catch 'loop - (let ((i 0)) - (while (< i 10) - (let ((j 0)) - (while (< j 10) - (if (foo i j) - (throw 'loop (list i j))) - (setq j (1+ j)))) - (setq i (1+ i)))))) -@end group -@end example - -@noindent -If @code{foo} ever returns non-@code{nil}, we stop immediately and return a -list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the -@code{catch} returns normally, and the value is @code{nil}, since that -is the result of the @code{while}. - - Here are two tricky examples, slightly different, showing two -return points at once. First, two return points with the same tag, -@code{hack}: - -@example -@group -(defun catch2 (tag) - (catch tag - (throw 'hack 'yes))) -@result{} catch2 -@end group - -@group -(catch 'hack - (print (catch2 'hack)) - 'no) -@print{} yes -@result{} no -@end group -@end example - -@noindent -Since both return points have tags that match the @code{throw}, it goes to -the inner one, the one established in @code{catch2}. Therefore, -@code{catch2} returns normally with value @code{yes}, and this value is -printed. Finally the second body form in the outer @code{catch}, which is -@code{'no}, is evaluated and returned from the outer @code{catch}. - - Now let's change the argument given to @code{catch2}: - -@example -@group -(catch 'hack - (print (catch2 'quux)) - 'no) -@result{} yes -@end group -@end example - -@noindent -We still have two return points, but this time only the outer one has -the tag @code{hack}; the inner one has the tag @code{quux} instead. -Therefore, @code{throw} makes the outer @code{catch} return the value -@code{yes}. The function @code{print} is never called, and the -body-form @code{'no} is never evaluated. - -@node Errors -@subsection Errors -@cindex errors - - When Emacs Lisp attempts to evaluate a form that, for some reason, -cannot be evaluated, it @dfn{signals} an @dfn{error}. - - When an error is signaled, Emacs's default reaction is to print an -error message and terminate execution of the current command. This is -the right thing to do in most cases, such as if you type @kbd{C-f} at -the end of the buffer. - - In complicated programs, simple termination may not be what you want. -For example, the program may have made temporary changes in data -structures, or created temporary buffers that should be deleted before -the program is finished. In such cases, you would use -@code{unwind-protect} to establish @dfn{cleanup expressions} to be -evaluated in case of error. (@xref{Cleanups}.) Occasionally, you may -wish the program to continue execution despite an error in a subroutine. -In these cases, you would use @code{condition-case} to establish -@dfn{error handlers} to recover control in case of error. - - Resist the temptation to use error handling to transfer control from -one part of the program to another; use @code{catch} and @code{throw} -instead. @xref{Catch and Throw}. - -@menu -* 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. -@end menu - -@node Signaling Errors -@subsubsection How to Signal an Error -@cindex signaling errors - - @dfn{Signaling} an error means beginning error processing. Error -processing normally aborts all or part of the running program and -returns to a point that is set up to handle the error -(@pxref{Processing of Errors}). Here we describe how to signal an -error. - - Most errors are signaled ``automatically'' within Lisp primitives -which you call for other purposes, such as if you try to take the -@sc{car} of an integer or move forward a character at the end of the -buffer. You can also signal errors explicitly with the functions -@code{error} and @code{signal}. - - Quitting, which happens when the user types @kbd{C-g}, is not -considered an error, but it is handled almost like an error. -@xref{Quitting}. - - Every error specifies an error message, one way or another. The -message should state what is wrong (``File does not exist''), not how -things ought to be (``File must exist''). The convention in Emacs -Lisp is that error messages should start with a capital letter, but -should not end with any sort of punctuation. - -@defun error format-string &rest args -This function signals an error with an error message constructed by -applying @code{format} (@pxref{Formatting Strings}) to -@var{format-string} and @var{args}. - -These examples show typical uses of @code{error}: - -@example -@group -(error "That is an error -- try something else") - @error{} That is an error -- try something else -@end group - -@group -(error "You have committed %d errors" 10) - @error{} You have committed 10 errors -@end group -@end example - -@code{error} works by calling @code{signal} with two arguments: the -error symbol @code{error}, and a list containing the string returned by -@code{format}. - -@strong{Warning:} If you want to use your own string as an error message -verbatim, don't just write @code{(error @var{string})}. If @var{string} -contains @samp{%}, it will be interpreted as a format specifier, with -undesirable results. Instead, use @code{(error "%s" @var{string})}. -@end defun - -@defun signal error-symbol data -@anchor{Definition of signal} -This function signals an error named by @var{error-symbol}. The -argument @var{data} is a list of additional Lisp objects relevant to -the circumstances of the error. - -The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol -bearing a property @code{error-conditions} whose value is a list of -condition names. This is how Emacs Lisp classifies different sorts of -errors. @xref{Error Symbols}, for a description of error symbols, -error conditions and condition names. - -If the error is not handled, the two arguments are used in printing -the error message. Normally, this error message is provided by the -@code{error-message} property of @var{error-symbol}. If @var{data} is -non-@code{nil}, this is followed by a colon and a comma separated list -of the unevaluated elements of @var{data}. For @code{error}, the -error message is the @sc{car} of @var{data} (that must be a string). -Subcategories of @code{file-error} are handled specially. - -The number and significance of the objects in @var{data} depends on -@var{error-symbol}. For example, with a @code{wrong-type-arg} error, -there should be two objects in the list: a predicate that describes the type -that was expected, and the object that failed to fit that type. - -Both @var{error-symbol} and @var{data} are available to any error -handlers that handle the error: @code{condition-case} binds a local -variable to a list of the form @code{(@var{error-symbol} .@: -@var{data})} (@pxref{Handling Errors}). - -The function @code{signal} never returns (though in older Emacs versions -it could sometimes return). - -@smallexample -@group -(signal 'wrong-number-of-arguments '(x y)) - @error{} Wrong number of arguments: x, y -@end group - -@group -(signal 'no-such-error '("My unknown error condition")) - @error{} peculiar error: "My unknown error condition" -@end group -@end smallexample -@end defun - -@cindex CL note---no continuable errors -@quotation -@b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp -concept of continuable errors. -@end quotation - -@node Processing of Errors -@subsubsection How Emacs Processes Errors - -When an error is signaled, @code{signal} searches for an active -@dfn{handler} for the error. A handler is a sequence of Lisp -expressions designated to be executed if an error happens in part of the -Lisp program. If the error has an applicable handler, the handler is -executed, and control resumes following the handler. The handler -executes in the environment of the @code{condition-case} that -established it; all functions called within that @code{condition-case} -have already been exited, and the handler cannot return to them. - -If there is no applicable handler for the error, it terminates the -current command and returns control to the editor command loop. (The -command loop has an implicit handler for all kinds of errors.) The -command loop's handler uses the error symbol and associated data to -print an error message. You can use the variable -@code{command-error-function} to control how this is done: - -@defvar command-error-function -This variable, if non-@code{nil}, specifies a function to use to -handle errors that return control to the Emacs command loop. The -function should take three arguments: @var{data}, a list of the same -form that @code{condition-case} would bind to its variable; -@var{context}, a string describing the situation in which the error -occurred, or (more often) @code{nil}; and @var{caller}, the Lisp -function which called the primitive that signaled the error. -@end defvar - -@cindex @code{debug-on-error} use -An error that has no explicit handler may call the Lisp debugger. The -debugger is enabled if the variable @code{debug-on-error} (@pxref{Error -Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs -in the environment of the error, so that you can examine values of -variables precisely as they were at the time of the error. - -@node Handling Errors -@subsubsection Writing Code to Handle Errors -@cindex error handler -@cindex handling errors - - The usual effect of signaling an error is to terminate the command -that is running and return immediately to the Emacs editor command loop. -You can arrange to trap errors occurring in a part of your program by -establishing an error handler, with the special form -@code{condition-case}. A simple example looks like this: - -@example -@group -(condition-case nil - (delete-file filename) - (error nil)) -@end group -@end example - -@noindent -This deletes the file named @var{filename}, catching any error and -returning @code{nil} if an error occurs. - - The @code{condition-case} construct is often used to trap errors that -are predictable, such as failure to open a file in a call to -@code{insert-file-contents}. It is also used to trap errors that are -totally unpredictable, such as when the program evaluates an expression -read from the user. - - The second argument of @code{condition-case} is called the -@dfn{protected form}. (In the example above, the protected form is a -call to @code{delete-file}.) The error handlers go into effect when -this form begins execution and are deactivated when this form returns. -They remain in effect for all the intervening time. In particular, they -are in effect during the execution of functions called by this form, in -their subroutines, and so on. This is a good thing, since, strictly -speaking, errors can be signaled only by Lisp primitives (including -@code{signal} and @code{error}) called by the protected form, not by the -protected form itself. - - The arguments after the protected form are handlers. Each handler -lists one or more @dfn{condition names} (which are symbols) to specify -which errors it will handle. The error symbol specified when an error -is signaled also defines a list of condition names. A handler applies -to an error if they have any condition names in common. In the example -above, there is one handler, and it specifies one condition name, -@code{error}, which covers all errors. - - The search for an applicable handler checks all the established handlers -starting with the most recently established one. Thus, if two nested -@code{condition-case} forms offer to handle the same error, the inner of -the two gets to handle it. - - If an error is handled by some @code{condition-case} form, this -ordinarily prevents the debugger from being run, even if -@code{debug-on-error} says this error should invoke the debugger. - - If you want to be able to debug errors that are caught by a -@code{condition-case}, set the variable @code{debug-on-signal} to a -non-@code{nil} value. You can also specify that a particular handler -should let the debugger run first, by writing @code{debug} among the -conditions, like this: - -@example -@group -(condition-case nil - (delete-file filename) - ((debug error) nil)) -@end group -@end example - -@noindent -The effect of @code{debug} here is only to prevent -@code{condition-case} from suppressing the call to the debugger. Any -given error will invoke the debugger only if @code{debug-on-error} and -the other usual filtering mechanisms say it should. @xref{Error Debugging}. - - Once Emacs decides that a certain handler handles the error, it -returns control to that handler. To do so, Emacs unbinds all variable -bindings made by binding constructs that are being exited, and -executes the cleanups of all @code{unwind-protect} forms that are -being exited. Once control arrives at the handler, the body of the -handler executes normally. - - After execution of the handler body, execution returns from the -@code{condition-case} form. Because the protected form is exited -completely before execution of the handler, the handler cannot resume -execution at the point of the error, nor can it examine variable -bindings that were made within the protected form. All it can do is -clean up and proceed. - - Error signaling and handling have some resemblance to @code{throw} and -@code{catch} (@pxref{Catch and Throw}), but they are entirely separate -facilities. An error cannot be caught by a @code{catch}, and a -@code{throw} cannot be handled by an error handler (though using -@code{throw} when there is no suitable @code{catch} signals an error -that can be handled). - -@defspec condition-case var protected-form handlers@dots{} -This special form establishes the error handlers @var{handlers} around -the execution of @var{protected-form}. If @var{protected-form} executes -without error, the value it returns becomes the value of the -@code{condition-case} form; in this case, the @code{condition-case} has -no effect. The @code{condition-case} form makes a difference when an -error occurs during @var{protected-form}. - -Each of the @var{handlers} is a list of the form @code{(@var{conditions} -@var{body}@dots{})}. Here @var{conditions} is an error condition name -to be handled, or a list of condition names (which can include @code{debug} -to allow the debugger to run before the handler); @var{body} is one or more -Lisp expressions to be executed when this handler handles an error. -Here are examples of handlers: - -@smallexample -@group -(error nil) - -(arith-error (message "Division by zero")) - -((arith-error file-error) - (message - "Either division by zero or failure to open a file")) -@end group -@end smallexample - -Each error that occurs has an @dfn{error symbol} that describes what -kind of error it is. The @code{error-conditions} property of this -symbol is a list of condition names (@pxref{Error Symbols}). Emacs -searches all the active @code{condition-case} forms for a handler that -specifies one or more of these condition names; the innermost matching -@code{condition-case} handles the error. Within this -@code{condition-case}, the first applicable handler handles the error. - -After executing the body of the handler, the @code{condition-case} -returns normally, using the value of the last form in the handler body -as the overall value. - -@cindex error description -The argument @var{var} is a variable. @code{condition-case} does not -bind this variable when executing the @var{protected-form}, only when it -handles an error. At that time, it binds @var{var} locally to an -@dfn{error description}, which is a list giving the particulars of the -error. The error description has the form @code{(@var{error-symbol} -. @var{data})}. The handler can refer to this list to decide what to -do. For example, if the error is for failure opening a file, the file -name is the second element of @var{data}---the third element of the -error description. - -If @var{var} is @code{nil}, that means no variable is bound. Then the -error symbol and associated data are not available to the handler. -@end defspec - -@defun error-message-string error-description -This function returns the error message string for a given error -descriptor. It is useful if you want to handle an error by printing the -usual error message for that error. @xref{Definition of signal}. -@end defun - -@cindex @code{arith-error} example -Here is an example of using @code{condition-case} to handle the error -that results from dividing by zero. The handler displays the error -message (but without a beep), then returns a very large number. - -@smallexample -@group -(defun safe-divide (dividend divisor) - (condition-case err - ;; @r{Protected form.} - (/ dividend divisor) -@end group -@group - ;; @r{The handler.} - (arith-error ; @r{Condition.} - ;; @r{Display the usual message for this error.} - (message "%s" (error-message-string err)) - 1000000))) -@result{} safe-divide -@end group - -@group -(safe-divide 5 0) - @print{} Arithmetic error: (arith-error) -@result{} 1000000 -@end group -@end smallexample - -@noindent -The handler specifies condition name @code{arith-error} so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this @code{condition-case}. Thus, - -@smallexample -@group -(safe-divide nil 3) - @error{} Wrong type argument: number-or-marker-p, nil -@end group -@end smallexample - - Here is a @code{condition-case} that catches all kinds of errors, -including those signaled with @code{error}: - -@smallexample -@group -(setq baz 34) - @result{} 34 -@end group - -@group -(condition-case err - (if (eq baz 35) - t - ;; @r{This is a call to the function @code{error}.} - (error "Rats! The variable %s was %s, not 35" 'baz baz)) - ;; @r{This is the handler; it is not a form.} - (error (princ (format "The error was: %s" err)) - 2)) -@print{} The error was: (error "Rats! The variable baz was 34, not 35") -@result{} 2 -@end group -@end smallexample - -@node Error Symbols -@subsubsection Error Symbols and Condition Names -@cindex error symbol -@cindex error name -@cindex condition name -@cindex user-defined error -@kindex error-conditions - - When you signal an error, you specify an @dfn{error symbol} to specify -the kind of error you have in mind. Each error has one and only one -error symbol to categorize it. This is the finest classification of -errors defined by the Emacs Lisp language. - - These narrow classifications are grouped into a hierarchy of wider -classes called @dfn{error conditions}, identified by @dfn{condition -names}. The narrowest such classes belong to the error symbols -themselves: each error symbol is also a condition name. There are also -condition names for more extensive classes, up to the condition name -@code{error} which takes in all kinds of errors (but not @code{quit}). -Thus, each error has one or more condition names: @code{error}, the -error symbol if that is distinct from @code{error}, and perhaps some -intermediate classifications. - - In order for a symbol to be an error symbol, it must have an -@code{error-conditions} property which gives a list of condition names. -This list defines the conditions that this kind of error belongs to. -(The error symbol itself, and the symbol @code{error}, should always be -members of this list.) Thus, the hierarchy of condition names is -defined by the @code{error-conditions} properties of the error symbols. -Because quitting is not considered an error, the value of the -@code{error-conditions} property of @code{quit} is just @code{(quit)}. - -@cindex peculiar error - In addition to the @code{error-conditions} list, the error symbol -should have an @code{error-message} property whose value is a string to -be printed when that error is signaled but not handled. If the -error symbol has no @code{error-message} property or if the -@code{error-message} property exists, but is not a string, the error -message @samp{peculiar error} is used. @xref{Definition of signal}. - - Here is how we define a new error symbol, @code{new-error}: - -@example -@group -(put 'new-error - 'error-conditions - '(error my-own-errors new-error)) -@result{} (error my-own-errors new-error) -@end group -@group -(put 'new-error 'error-message "A new error") -@result{} "A new error" -@end group -@end example - -@noindent -This error has three condition names: @code{new-error}, the narrowest -classification; @code{my-own-errors}, which we imagine is a wider -classification; and @code{error}, which is the widest of all. - - The error string should start with a capital letter but it should -not end with a period. This is for consistency with the rest of Emacs. - - Naturally, Emacs will never signal @code{new-error} on its own; only -an explicit call to @code{signal} (@pxref{Definition of signal}) in -your code can do this: - -@example -@group -(signal 'new-error '(x y)) - @error{} A new error: x, y -@end group -@end example - - This error can be handled through any of the three condition names. -This example handles @code{new-error} and any other errors in the class -@code{my-own-errors}: - -@example -@group -(condition-case foo - (bar nil t) - (my-own-errors nil)) -@end group -@end example - - The significant way that errors are classified is by their condition -names---the names used to match errors with handlers. An error symbol -serves only as a convenient way to specify the intended error message -and list of condition names. It would be cumbersome to give -@code{signal} a list of condition names rather than one error symbol. - - By contrast, using only error symbols without condition names would -seriously decrease the power of @code{condition-case}. Condition names -make it possible to categorize errors at various levels of generality -when you write an error handler. Using error symbols alone would -eliminate all but the narrowest level of classification. - - @xref{Standard Errors}, for a list of all the standard error symbols -and their conditions. - -@node Cleanups -@subsection Cleaning Up from Nonlocal Exits - - The @code{unwind-protect} construct is essential whenever you -temporarily put a data structure in an inconsistent state; it permits -you to make the data consistent again in the event of an error or -throw. (Another more specific cleanup construct that is used only for -changes in buffer contents is the atomic change group; @ref{Atomic -Changes}.) - -@defspec unwind-protect body-form cleanup-forms@dots{} -@cindex cleanup forms -@cindex protected forms -@cindex error cleanup -@cindex unwinding -@code{unwind-protect} executes @var{body-form} with a guarantee that -the @var{cleanup-forms} will be evaluated if control leaves -@var{body-form}, no matter how that happens. @var{body-form} may -complete normally, or execute a @code{throw} out of the -@code{unwind-protect}, or cause an error; in all cases, the -@var{cleanup-forms} will be evaluated. - -If @var{body-form} finishes normally, @code{unwind-protect} returns the -value of @var{body-form}, after it evaluates the @var{cleanup-forms}. -If @var{body-form} does not finish, @code{unwind-protect} does not -return any value in the normal sense. - -Only @var{body-form} is protected by the @code{unwind-protect}. If any -of the @var{cleanup-forms} themselves exits nonlocally (via a -@code{throw} or an error), @code{unwind-protect} is @emph{not} -guaranteed to evaluate the rest of them. If the failure of one of the -@var{cleanup-forms} has the potential to cause trouble, then protect -it with another @code{unwind-protect} around that form. - -The number of currently active @code{unwind-protect} forms counts, -together with the number of local variable bindings, against the limit -@code{max-specpdl-size} (@pxref{Definition of max-specpdl-size,, Local -Variables}). -@end defspec - - For example, here we make an invisible buffer for temporary use, and -make sure to kill it before finishing: - -@smallexample -@group -(save-excursion - (let ((buffer (get-buffer-create " *temp*"))) - (set-buffer buffer) - (unwind-protect - @var{body-form} - (kill-buffer buffer)))) -@end group -@end smallexample - -@noindent -You might think that we could just as well write @code{(kill-buffer -(current-buffer))} and dispense with the variable @code{buffer}. -However, the way shown above is safer, if @var{body-form} happens to -get an error after switching to a different buffer! (Alternatively, -you could write another @code{save-excursion} around @var{body-form}, -to ensure that the temporary buffer becomes current again in time to -kill it.) - - Emacs includes a standard macro called @code{with-temp-buffer} which -expands into more or less the code shown above (@pxref{Definition of -with-temp-buffer,, Current Buffer}). Several of the macros defined in -this manual use @code{unwind-protect} in this way. - -@findex ftp-login - Here is an actual example derived from an FTP package. It creates a -process (@pxref{Processes}) to try to establish a connection to a remote -machine. As the function @code{ftp-login} is highly susceptible to -numerous problems that the writer of the function cannot anticipate, it -is protected with a form that guarantees deletion of the process in the -event of failure. Otherwise, Emacs might fill up with useless -subprocesses. - -@smallexample -@group -(let ((win nil)) - (unwind-protect - (progn - (setq process (ftp-setup-buffer host file)) - (if (setq win (ftp-login process host user password)) - (message "Logged in") - (error "Ftp login failed"))) - (or win (and process (delete-process process))))) -@end group -@end smallexample - - This example has a small bug: if the user types @kbd{C-g} to -quit, and the quit happens immediately after the function -@code{ftp-setup-buffer} returns but before the variable @code{process} is -set, the process will not be killed. There is no easy way to fix this bug, -but at least it is very unlikely. - -@ignore - arch-tag: 8abc30d4-4d3a-47f9-b908-e9e971c18c6d -@end ignore diff --git a/lispref/customize.texi b/lispref/customize.texi deleted file mode 100644 index 8b1b1a9b91f..00000000000 --- a/lispref/customize.texi +++ /dev/null @@ -1,1253 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/customize -@node Customization, Loading, Macros, Top -@chapter Writing Customization Definitions - -@cindex customization definitions - This chapter describes how to declare user options for customization, -and also customization groups for classifying them. We use the term -@dfn{customization item} to include both kinds of customization -definitions---as well as face definitions (@pxref{Defining Faces}). - -@menu -* 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. -@end menu - -@node Common Keywords -@section Common Item Keywords - -@cindex customization keywords - All kinds of customization declarations (for variables and groups, and -for faces) accept keyword arguments for specifying various information. -This section describes some keywords that apply to all kinds. - - All of these keywords, except @code{:tag}, can be used more than once -in a given item. Each use of the keyword has an independent effect. -The keyword @code{:tag} is an exception because any given item can only -display one name. - -@table @code -@item :tag @var{label} -@kindex tag@r{, customization keyword} -Use @var{label}, a string, instead of the item's name, to label the -item in customization menus and buffers. @strong{Don't use a tag -which is substantially different from the item's real name; that would -cause confusion.} One legitimate case for use of @code{:tag} is to -specify a dash where normally a hyphen would be converted to a space: - -@example -(defcustom cursor-in-non-selected-windows @dots{} - :tag "Cursor In Non-selected Windows" -@end example - -@kindex group@r{, customization keyword} -@item :group @var{group} -Put this customization item in group @var{group}. When you use -@code{:group} in a @code{defgroup}, it makes the new group a subgroup of -@var{group}. - -If you use this keyword more than once, you can put a single item into -more than one group. Displaying any of those groups will show this -item. Please don't overdo this, since the result would be annoying. - -@item :link @var{link-data} -@kindex link@r{, customization keyword} -Include an external link after the documentation string for this item. -This is a sentence containing an active field which references some -other documentation. - -There are several alternatives you can use for @var{link-data}: - -@table @code -@item (custom-manual @var{info-node}) -Link to an Info node; @var{info-node} is a string which specifies the -node name, as in @code{"(emacs)Top"}. The link appears as -@samp{[Manual]} in the customization buffer and enters the built-in -Info reader on @var{info-node}. - -@item (info-link @var{info-node}) -Like @code{custom-manual} except that the link appears -in the customization buffer with the Info node name. - -@item (url-link @var{url}) -Link to a web page; @var{url} is a string which specifies the -@acronym{URL}. The link appears in the customization buffer as -@var{url} and invokes the WWW browser specified by -@code{browse-url-browser-function}. - -@item (emacs-commentary-link @var{library}) -Link to the commentary section of a library; @var{library} is a string -which specifies the library name. - -@item (emacs-library-link @var{library}) -Link to an Emacs Lisp library file; @var{library} is a string which -specifies the library name. - -@item (file-link @var{file}) -Link to a file; @var{file} is a string which specifies the name of the -file to visit with @code{find-file} when the user invokes this link. - -@item (function-link @var{function}) -Link to the documentation of a function; @var{function} is a string -which specifies the name of the function to describe with -@code{describe-function} when the user invokes this link. - -@item (variable-link @var{variable}) -Link to the documentation of a variable; @var{variable} is a string -which specifies the name of the variable to describe with -@code{describe-variable} when the user invokes this link. - -@item (custom-group-link @var{group}) -Link to another customization group. Invoking it creates a new -customization buffer for @var{group}. -@end table - -You can specify the text to use in the customization buffer by adding -@code{:tag @var{name}} after the first element of the @var{link-data}; -for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to -the Emacs manual which appears in the buffer as @samp{foo}. - -An item can have more than one external link; however, most items have -none at all. - -@item :load @var{file} -@kindex load@r{, customization keyword} -Load file @var{file} (a string) before displaying this customization -item. Loading is done with @code{load-library}, and only if the file is -not already loaded. - -@item :require @var{feature} -@kindex require@r{, customization keyword} -Execute @code{(require '@var{feature})} when your saved customizations -set the value of this item. @var{feature} should be a symbol. - -The most common reason to use @code{:require} is when a variable enables -a feature such as a minor mode, and just setting the variable won't have -any effect unless the code which implements the mode is loaded. - -@item :version @var{version} -@kindex version@r{, customization keyword} -This keyword specifies that the item was first introduced in Emacs -version @var{version}, or that its default value was changed in that -version. The value @var{version} must be a string. - -@item :package-version '(@var{package} . @var{version}) -@kindex package-version@r{, customization keyword} -This keyword specifies that the item was first introduced in -@var{package} version @var{version}, or that its meaning or default -value was changed in that version. The value of @var{package} is a -symbol and @var{version} is a string. - -This keyword takes priority over @code{:version}. - -@var{package} should be the official name of the package, such as MH-E -or Gnus. If the package @var{package} is released as part of Emacs, -@var{package} and @var{version} should appear in the value of -@code{customize-package-emacs-version-alist}. -@end table - -Packages distributed as part of Emacs that use the -@code{:package-version} keyword must also update the -@code{customize-package-emacs-version-alist} variable. - -@defvar customize-package-emacs-version-alist -This alist provides a mapping for the versions of Emacs that are -associated with versions of a package listed in the -@code{:package-version} keyword. Its elements look like this: - -@example -(@var{package} (@var{pversion} . @var{eversion})@dots{}) -@end example - -For each @var{package}, which is a symbol, there are one or more -elements that contain a package version @var{pversion} with an -associated Emacs version @var{eversion}. These versions are strings. -For example, the MH-E package updates this alist with the following: - -@smallexample -(add-to-list 'customize-package-emacs-version-alist - '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1") - ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1") - ("7.4" . "22.1") ("8.0" . "22.1"))) -@end smallexample - -The value of @var{package} needs to be unique and it needs to match -the @var{package} value appearing in the @code{:package-version} -keyword. Since the user might see the value in a error message, a good -choice is the official name of the package, such as MH-E or Gnus. -@end defvar - -@node Group Definitions -@section Defining Customization Groups -@cindex define customization group -@cindex customization groups, defining - - Each Emacs Lisp package should have one main customization group which -contains all the options, faces and other groups in the package. If the -package has a small number of options and faces, use just one group and -put everything in it. When there are more than twelve or so options and -faces, then you should structure them into subgroups, and put the -subgroups under the package's main customization group. It is OK to -put some of the options and faces in the package's main group alongside -the subgroups. - - The package's main or only group should be a member of one or more of -the standard customization groups. (To display the full list of them, -use @kbd{M-x customize}.) Choose one or more of them (but not too -many), and add your group to each of them using the @code{:group} -keyword. - - The way to declare new customization groups is with @code{defgroup}. - -@defmac defgroup group members doc [keyword value]@dots{} -Declare @var{group} as a customization group containing @var{members}. -Do not quote the symbol @var{group}. The argument @var{doc} specifies -the documentation string for the group. - -The argument @var{members} is a list specifying an initial set of -customization items to be members of the group. However, most often -@var{members} is @code{nil}, and you specify the group's members by -using the @code{:group} keyword when defining those members. - -If you want to specify group members through @var{members}, each element -should have the form @code{(@var{name} @var{widget})}. Here @var{name} -is a symbol, and @var{widget} is a widget type for editing that symbol. -Useful widgets are @code{custom-variable} for a variable, -@code{custom-face} for a face, and @code{custom-group} for a group. - -When you introduce a new group into Emacs, use the @code{:version} -keyword in the @code{defgroup}; then you need not use it for -the individual members of the group. - -In addition to the common keywords (@pxref{Common Keywords}), you can -also use this keyword in @code{defgroup}: - -@table @code -@item :prefix @var{prefix} -@kindex prefix@r{, @code{defgroup} keyword} -If the name of an item in the group starts with @var{prefix}, then the -tag for that item is constructed (by default) by omitting @var{prefix}. - -One group can have any number of prefixes. -@end table -@end defmac - - The prefix-discarding feature is currently turned off, which means -that @code{:prefix} currently has no effect. We did this because we -found that discarding the specified prefixes often led to confusing -names for options. This happened because the people who wrote the -@code{defgroup} definitions for various groups added @code{:prefix} -keywords whenever they make logical sense---that is, whenever the -variables in the library have a common prefix. - - In order to obtain good results with @code{:prefix}, it would be -necessary to check the specific effects of discarding a particular -prefix, given the specific items in a group and their names and -documentation. If the resulting text is not clear, then @code{:prefix} -should not be used in that case. - - It should be possible to recheck all the customization groups, delete -the @code{:prefix} specifications which give unclear results, and then -turn this feature back on, if someone would like to do the work. - -@node Variable Definitions -@section Defining Customization Variables -@cindex define customization options -@cindex customization variables, how to define - - Use @code{defcustom} to declare user-customizable variables. - -@defmac defcustom option standard doc [keyword value]@dots{} -This construct declares @var{option} as a customizable user option -variable. You should not quote @var{option}. The argument @var{doc} -specifies the documentation string for the variable. There is no need -to start it with a @samp{*}, because @code{defcustom} automatically -marks @var{option} as a @dfn{user option} (@pxref{Defining -Variables}). - -The argument @var{standard} is an expression that specifies the -standard value for @var{option}. Evaluating the @code{defcustom} form -evaluates @var{standard}, but does not necessarily install the -standard value. If @var{option} already has a default value, -@code{defcustom} does not change it. If the user has saved a -customization for @var{option}, @code{defcustom} installs the user's -customized value as @var{option}'s default value. If neither of those -cases applies, @code{defcustom} installs the result of evaluating -@var{standard} as the default value. - -The expression @var{standard} can be evaluated at various other times, -too---whenever the customization facility needs to know @var{option}'s -standard value. So be sure to use an expression which is harmless to -evaluate at any time. We recommend avoiding backquotes in -@var{standard}, because they are not expanded when editing the value, -so list values will appear to have the wrong structure. - -Every @code{defcustom} should specify @code{:group} at least once. - -If you specify the @code{:set} keyword, to make the variable take other -special actions when set through the customization buffer, the -variable's documentation string should tell the user specifically how -to do the same job in hand-written Lisp code. - -When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp -mode (@code{eval-defun}), a special feature of @code{eval-defun} -arranges to set the variable unconditionally, without testing whether -its value is void. (The same feature applies to @code{defvar}.) -@xref{Defining Variables}. -@end defmac - - @code{defcustom} accepts the following additional keywords: - -@table @code -@item :type @var{type} -Use @var{type} as the data type for this option. It specifies which -values are legitimate, and how to display the value. -@xref{Customization Types}, for more information. - -@item :options @var{value-list} -@kindex options@r{, @code{defcustom} keyword} -Specify the list of reasonable values for use in this -option. The user is not restricted to using only these values, but they -are offered as convenient alternatives. - -This is meaningful only for certain types, currently including -@code{hook}, @code{plist} and @code{alist}. See the definition of the -individual types for a description of how to use @code{:options}. - -@item :set @var{setfunction} -@kindex set@r{, @code{defcustom} keyword} -Specify @var{setfunction} as the way to change the value of this -option. The function @var{setfunction} should take two arguments, a -symbol (the option name) and the new value, and should do whatever is -necessary to update the value properly for this option (which may not -mean simply setting the option as a Lisp variable). The default for -@var{setfunction} is @code{set-default}. - -@item :get @var{getfunction} -@kindex get@r{, @code{defcustom} keyword} -Specify @var{getfunction} as the way to extract the value of this -option. The function @var{getfunction} should take one argument, a -symbol, and should return whatever customize should use as the -``current value'' for that symbol (which need not be the symbol's Lisp -value). The default is @code{default-value}. - -You have to really understand the workings of Custom to use -@code{:get} correctly. It is meant for values that are treated in -Custom as variables but are not actually stored in Lisp variables. It -is almost surely a mistake to specify @code{getfunction} for a value -that really is stored in a Lisp variable. - -@item :initialize @var{function} -@kindex initialize@r{, @code{defcustom} keyword} -@var{function} should be a function used to initialize the variable -when the @code{defcustom} is evaluated. It should take two arguments, -the option name (a symbol) and the value. Here are some predefined -functions meant for use in this way: - -@table @code -@item custom-initialize-set -Use the variable's @code{:set} function to initialize the variable, but -do not reinitialize it if it is already non-void. - -@item custom-initialize-default -Like @code{custom-initialize-set}, but use the function -@code{set-default} to set the variable, instead of the variable's -@code{:set} function. This is the usual choice for a variable whose -@code{:set} function enables or disables a minor mode; with this choice, -defining the variable will not call the minor mode function, but -customizing the variable will do so. - -@item custom-initialize-reset -Always use the @code{:set} function to initialize the variable. If -the variable is already non-void, reset it by calling the @code{:set} -function using the current value (returned by the @code{:get} method). -This is the default @code{:initialize} function. - -@item custom-initialize-changed -Use the @code{:set} function to initialize the variable, if it is -already set or has been customized; otherwise, just use -@code{set-default}. - -@item custom-initialize-safe-set -@itemx custom-initialize-safe-default -These functions behave like @code{custom-initialize-set} -(@code{custom-initialize-default}, respectively), but catch errors. -If an error occurs during initialization, they set the variable to -@code{nil} using @code{set-default}, and throw no error. - -These two functions are only meant for options defined in pre-loaded -files, where some variables or functions used to compute the option's -value may not yet be defined. The option normally gets updated in -@file{startup.el}, ignoring the previously computed value. Because of -this typical usage, the value which these two functions compute -normally only matters when, after startup, one unsets the option's -value and then reevaluates the defcustom. By that time, the necessary -variables and functions will be defined, so there will not be an error. -@end table - -@item :set-after @var{variables} -@kindex set-after@r{, @code{defcustom} keyword} -When setting variables according to saved customizations, make sure to -set the variables @var{variables} before this one; in other words, delay -setting this variable until after those others have been handled. Use -@code{:set-after} if setting this variable won't work properly unless -those other variables already have their intended values. -@end table - - The @code{:require} keyword is useful for an option that turns on the -operation of a certain feature. Assuming that the package is coded to -check the value of the option, you still need to arrange for the package -to be loaded. You can do that with @code{:require}. @xref{Common -Keywords}. Here is an example, from the library @file{saveplace.el}: - -@example -(defcustom save-place nil - "Non-nil means automatically save place in each file..." - :type 'boolean - :require 'saveplace - :group 'save-place) -@end example - -If a customization item has a type such as @code{hook} or -@code{alist}, which supports @code{:options}, you can add additional -values to the list from outside the @code{defcustom} declaration by -calling @code{custom-add-frequent-value}. For example, if you define a -function @code{my-lisp-mode-initialization} intended to be called from -@code{emacs-lisp-mode-hook}, you might want to add that to the list of -reasonable values for @code{emacs-lisp-mode-hook}, but not by editing -its definition. You can do it thus: - -@example -(custom-add-frequent-value 'emacs-lisp-mode-hook - 'my-lisp-mode-initialization) -@end example - -@defun custom-add-frequent-value symbol value -For the customization option @var{symbol}, add @var{value} to the -list of reasonable values. - -The precise effect of adding a value depends on the customization type -of @var{symbol}. -@end defun - -Internally, @code{defcustom} uses the symbol property -@code{standard-value} to record the expression for the standard value, -and @code{saved-value} to record the value saved by the user with the -customization buffer. Both properties are actually lists whose car is -an expression which evaluates to the value. - -@node Customization Types -@section Customization Types - -@cindex customization types - When you define a user option with @code{defcustom}, you must specify -its @dfn{customization type}. That is a Lisp object which describes (1) -which values are legitimate and (2) how to display the value in the -customization buffer for editing. - -@kindex type@r{, @code{defcustom} keyword} - You specify the customization type in @code{defcustom} with the -@code{:type} keyword. The argument of @code{:type} is evaluated, but -only once when the @code{defcustom} is executed, so it isn't useful -for the value to vary. Normally we use a quoted constant. For -example: - -@example -(defcustom diff-command "diff" - "The command to use to run diff." - :type '(string) - :group 'diff) -@end example - - In general, a customization type is a list whose first element is a -symbol, one of the customization type names defined in the following -sections. After this symbol come a number of arguments, depending on -the symbol. Between the type symbol and its arguments, you can -optionally write keyword-value pairs (@pxref{Type Keywords}). - - Some of the type symbols do not use any arguments; those are called -@dfn{simple types}. For a simple type, if you do not use any -keyword-value pairs, you can omit the parentheses around the type -symbol. For example just @code{string} as a customization type is -equivalent to @code{(string)}. - -@menu -* Simple Types:: -* Composite Types:: -* Splicing into Lists:: -* Type Keywords:: -* Defining New Types:: -@end menu - -All customization types are implemented as widgets; see @ref{Top, , -Introduction, widget, The Emacs Widget Library}, for details. - -@node Simple Types -@subsection Simple Types - - This section describes all the simple customization types. - -@table @code -@item sexp -The value may be any Lisp object that can be printed and read back. You -can use @code{sexp} as a fall-back for any option, if you don't want to -take the time to work out a more specific type to use. - -@item integer -The value must be an integer, and is represented textually -in the customization buffer. - -@item number -The value must be a number (floating point or integer), and is -represented textually in the customization buffer. - -@item float -The value must be a floating point number, and is represented -textually in the customization buffer. - -@item string -The value must be a string, and the customization buffer shows just the -contents, with no delimiting @samp{"} characters and no quoting with -@samp{\}. - -@item regexp -Like @code{string} except that the string must be a valid regular -expression. - -@item character -The value must be a character code. A character code is actually an -integer, but this type shows the value by inserting the character in the -buffer, rather than by showing the number. - -@item file -The value must be a file name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item (file :must-match t) -The value must be a file name for an existing file, and you can do -completion with @kbd{M-@key{TAB}}. - -@item directory -The value must be a directory name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item hook -The value must be a list of functions (or a single function, but that is -obsolete usage). This customization type is used for hook variables. -You can use the @code{:options} keyword in a hook variable's -@code{defcustom} to specify a list of functions recommended for use in -the hook; see @ref{Variable Definitions}. - -@item alist -The value must be a list of cons-cells, the @sc{car} of each cell -representing a key, and the @sc{cdr} of the same cell representing an -associated value. The user can add and delete key/value pairs, and -edit both the key and the value of each pair. - -You can specify the key and value types like this: - -@smallexample -(alist :key-type @var{key-type} :value-type @var{value-type}) -@end smallexample - -@noindent -where @var{key-type} and @var{value-type} are customization type -specifications. The default key type is @code{sexp}, and the default -value type is @code{sexp}. - -The user can add any key matching the specified key type, but you can -give some keys a preferential treatment by specifying them with the -@code{:options} (see @ref{Variable Definitions}). The specified keys -will always be shown in the customize buffer (together with a suitable -value), with a checkbox to include or exclude or disable the key/value -pair from the alist. The user will not be able to edit the keys -specified by the @code{:options} keyword argument. - -The argument to the @code{:options} keywords should be a list of -specifications for reasonable keys in the alist. Ordinarily, they are -simply atoms, which stand for themselves as. For example: - -@smallexample -:options '("foo" "bar" "baz") -@end smallexample - -@noindent -specifies that there are three ``known'' keys, namely @code{"foo"}, -@code{"bar"} and @code{"baz"}, which will always be shown first. - -You may want to restrict the value type for specific keys, for -example, the value associated with the @code{"bar"} key can only be an -integer. You can specify this by using a list instead of an atom in -the list. The first element will specify the key, like before, while -the second element will specify the value type. For example: - -@smallexample -:options '("foo" ("bar" integer) "baz") -@end smallexample - -Finally, you may want to change how the key is presented. By default, -the key is simply shown as a @code{const}, since the user cannot change -the special keys specified with the @code{:options} keyword. However, -you may want to use a more specialized type for presenting the key, like -@code{function-item} if you know it is a symbol with a function binding. -This is done by using a customization type specification instead of a -symbol for the key. - -@smallexample -:options '("foo" ((function-item some-function) integer) - "baz") -@end smallexample - -Many alists use lists with two elements, instead of cons cells. For -example, - -@smallexample -(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) - "Each element is a list of the form (KEY VALUE).") -@end smallexample - -@noindent -instead of - -@smallexample -(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) - "Each element is a cons-cell (KEY . VALUE).") -@end smallexample - -Because of the way lists are implemented on top of cons cells, you can -treat @code{list-alist} in the example above as a cons cell alist, where -the value type is a list with a single element containing the real -value. - -@smallexample -(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) - "Each element is a list of the form (KEY VALUE)." - :type '(alist :value-type (group integer))) -@end smallexample - -The @code{group} widget is used here instead of @code{list} only because -the formatting is better suited for the purpose. - -Similarly, you can have alists with more values associated with each -key, using variations of this trick: - -@smallexample -(defcustom person-data '(("brian" 50 t) - ("dorith" 55 nil) - ("ken" 52 t)) - "Alist of basic info about people. -Each element has the form (NAME AGE MALE-FLAG)." - :type '(alist :value-type (group integer boolean))) - -(defcustom pets '(("brian") - ("dorith" "dog" "guppy") - ("ken" "cat")) - "Alist of people's pets. -In an element (KEY . VALUE), KEY is the person's name, -and the VALUE is a list of that person's pets." - :type '(alist :value-type (repeat string))) -@end smallexample - -@item plist -The @code{plist} custom type is similar to the @code{alist} (see above), -except that the information is stored as a property list, i.e. a list of -this form: - -@smallexample -(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{}) -@end smallexample - -The default @code{:key-type} for @code{plist} is @code{symbol}, -rather than @code{sexp}. - -@item symbol -The value must be a symbol. It appears in the customization buffer as -the name of the symbol. - -@item function -The value must be either a lambda expression or a function name. When -it is a function name, you can do completion with @kbd{M-@key{TAB}}. - -@item variable -The value must be a variable name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item face -The value must be a symbol which is a face name, and you can do -completion with @kbd{M-@key{TAB}}. - -@item boolean -The value is boolean---either @code{nil} or @code{t}. Note that by -using @code{choice} and @code{const} together (see the next section), -you can specify that the value must be @code{nil} or @code{t}, but also -specify the text to describe each value in a way that fits the specific -meaning of the alternative. - -@item coding-system -The value must be a coding-system name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item color -The value must be a valid color name, and you can do completion with -@kbd{M-@key{TAB}}. A sample is provided. -@end table - -@node Composite Types -@subsection Composite Types -@cindex Composite Types (customization) - - When none of the simple types is appropriate, you can use composite -types, which build new types from other types or from specified data. -The specified types or data are called the @dfn{arguments} of the -composite type. The composite type normally looks like this: - -@example -(@var{constructor} @var{arguments}@dots{}) -@end example - -@noindent -but you can also add keyword-value pairs before the arguments, like -this: - -@example -(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{}) -@end example - - Here is a table of constructors and how to use them to write -composite types: - -@table @code -@item (cons @var{car-type} @var{cdr-type}) -The value must be a cons cell, its @sc{car} must fit @var{car-type}, and -its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string -symbol)} is a customization type which matches values such as -@code{("foo" . foo)}. - -In the customization buffer, the @sc{car} and the @sc{cdr} are -displayed and edited separately, each according to the type -that you specify for it. - -@item (list @var{element-types}@dots{}) -The value must be a list with exactly as many elements as the -@var{element-types} given; and each element must fit the -corresponding @var{element-type}. - -For example, @code{(list integer string function)} describes a list of -three elements; the first element must be an integer, the second a -string, and the third a function. - -In the customization buffer, each element is displayed and edited -separately, according to the type specified for it. - -@item (vector @var{element-types}@dots{}) -Like @code{list} except that the value must be a vector instead of a -list. The elements work the same as in @code{list}. - -@item (choice @var{alternative-types}@dots{}) -The value must fit at least one of @var{alternative-types}. -For example, @code{(choice integer string)} allows either an -integer or a string. - -In the customization buffer, the user selects an alternative -using a menu, and can then edit the value in the usual way for that -alternative. - -Normally the strings in this menu are determined automatically from the -choices; however, you can specify different strings for the menu by -including the @code{:tag} keyword in the alternatives. For example, if -an integer stands for a number of spaces, while a string is text to use -verbatim, you might write the customization type this way, - -@example -(choice (integer :tag "Number of spaces") - (string :tag "Literal text")) -@end example - -@noindent -so that the menu offers @samp{Number of spaces} and @samp{Literal text}. - -In any alternative for which @code{nil} is not a valid value, other than -a @code{const}, you should specify a valid default for that alternative -using the @code{:value} keyword. @xref{Type Keywords}. - -If some values are covered by more than one of the alternatives, -customize will choose the first alternative that the value fits. This -means you should always list the most specific types first, and the -most general last. Here's an example of proper usage: - -@example -(choice (const :tag "Off" nil) - symbol (sexp :tag "Other")) -@end example - -@noindent -This way, the special value @code{nil} is not treated like other -symbols, and symbols are not treated like other Lisp expressions. - -@item (radio @var{element-types}@dots{}) -This is similar to @code{choice}, except that the choices are displayed -using `radio buttons' rather than a menu. This has the advantage of -displaying documentation for the choices when applicable and so is often -a good choice for a choice between constant functions -(@code{function-item} customization types). - -@item (const @var{value}) -The value must be @var{value}---nothing else is allowed. - -The main use of @code{const} is inside of @code{choice}. For example, -@code{(choice integer (const nil))} allows either an integer or -@code{nil}. - -@code{:tag} is often used with @code{const}, inside of @code{choice}. -For example, - -@example -(choice (const :tag "Yes" t) - (const :tag "No" nil) - (const :tag "Ask" foo)) -@end example - -@noindent -describes a variable for which @code{t} means yes, @code{nil} means no, -and @code{foo} means ``ask.'' - -@item (other @var{value}) -This alternative can match any Lisp value, but if the user chooses this -alternative, that selects the value @var{value}. - -The main use of @code{other} is as the last element of @code{choice}. -For example, - -@example -(choice (const :tag "Yes" t) - (const :tag "No" nil) - (other :tag "Ask" foo)) -@end example - -@noindent -describes a variable for which @code{t} means yes, @code{nil} means no, -and anything else means ``ask.'' If the user chooses @samp{Ask} from -the menu of alternatives, that specifies the value @code{foo}; but any -other value (not @code{t}, @code{nil} or @code{foo}) displays as -@samp{Ask}, just like @code{foo}. - -@item (function-item @var{function}) -Like @code{const}, but used for values which are functions. This -displays the documentation string as well as the function name. -The documentation string is either the one you specify with -@code{:doc}, or @var{function}'s own documentation string. - -@item (variable-item @var{variable}) -Like @code{const}, but used for values which are variable names. This -displays the documentation string as well as the variable name. The -documentation string is either the one you specify with @code{:doc}, or -@var{variable}'s own documentation string. - -@item (set @var{types}@dots{}) -The value must be a list, and each element of the list must match one of -the @var{types} specified. - -This appears in the customization buffer as a checklist, so that each of -@var{types} may have either one corresponding element or none. It is -not possible to specify two different elements that match the same one -of @var{types}. For example, @code{(set integer symbol)} allows one -integer and/or one symbol in the list; it does not allow multiple -integers or multiple symbols. As a result, it is rare to use -nonspecific types such as @code{integer} in a @code{set}. - -Most often, the @var{types} in a @code{set} are @code{const} types, as -shown here: - -@example -(set (const :bold) (const :italic)) -@end example - -Sometimes they describe possible elements in an alist: - -@example -(set (cons :tag "Height" (const height) integer) - (cons :tag "Width" (const width) integer)) -@end example - -@noindent -That lets the user specify a height value optionally -and a width value optionally. - -@item (repeat @var{element-type}) -The value must be a list and each element of the list must fit the type -@var{element-type}. This appears in the customization buffer as a -list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding -more elements or removing elements. - -@item (restricted-sexp :match-alternatives @var{criteria}) -This is the most general composite type construct. The value may be -any Lisp object that satisfies one of @var{criteria}. @var{criteria} -should be a list, and each element should be one of these -possibilities: - -@itemize @bullet -@item -A predicate---that is, a function of one argument that has no side -effects, and returns either @code{nil} or non-@code{nil} according to -the argument. Using a predicate in the list says that objects for which -the predicate returns non-@code{nil} are acceptable. - -@item -A quoted constant---that is, @code{'@var{object}}. This sort of element -in the list says that @var{object} itself is an acceptable value. -@end itemize - -For example, - -@example -(restricted-sexp :match-alternatives - (integerp 't 'nil)) -@end example - -@noindent -allows integers, @code{t} and @code{nil} as legitimate values. - -The customization buffer shows all legitimate values using their read -syntax, and the user edits them textually. -@end table - - Here is a table of the keywords you can use in keyword-value pairs -in a composite type: - -@table @code -@item :tag @var{tag} -Use @var{tag} as the name of this alternative, for user communication -purposes. This is useful for a type that appears inside of a -@code{choice}. - -@item :match-alternatives @var{criteria} -@kindex match-alternatives@r{, customization keyword} -Use @var{criteria} to match possible values. This is used only in -@code{restricted-sexp}. - -@item :args @var{argument-list} -@kindex args@r{, customization keyword} -Use the elements of @var{argument-list} as the arguments of the type -construct. For instance, @code{(const :args (foo))} is equivalent to -@code{(const foo)}. You rarely need to write @code{:args} explicitly, -because normally the arguments are recognized automatically as -whatever follows the last keyword-value pair. -@end table - -@node Splicing into Lists -@subsection Splicing into Lists - - The @code{:inline} feature lets you splice a variable number of -elements into the middle of a list or vector. You use it in a -@code{set}, @code{choice} or @code{repeat} type which appears among the -element-types of a @code{list} or @code{vector}. - - Normally, each of the element-types in a @code{list} or @code{vector} -describes one and only one element of the list or vector. Thus, if an -element-type is a @code{repeat}, that specifies a list of unspecified -length which appears as one element. - - But when the element-type uses @code{:inline}, the value it matches is -merged directly into the containing sequence. For example, if it -matches a list with three elements, those become three elements of the -overall sequence. This is analogous to using @samp{,@@} in the backquote -construct. - - For example, to specify a list whose first element must be @code{baz} -and whose remaining arguments should be zero or more of @code{foo} and -@code{bar}, use this customization type: - -@example -(list (const baz) (set :inline t (const foo) (const bar))) -@end example - -@noindent -This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)} -and @code{(baz foo bar)}. - - When the element-type is a @code{choice}, you use @code{:inline} not -in the @code{choice} itself, but in (some of) the alternatives of the -@code{choice}. For example, to match a list which must start with a -file name, followed either by the symbol @code{t} or two strings, use -this customization type: - -@example -(list file - (choice (const t) - (list :inline t string string))) -@end example - -@noindent -If the user chooses the first alternative in the choice, then the -overall list has two elements and the second element is @code{t}. If -the user chooses the second alternative, then the overall list has three -elements and the second and third must be strings. - -@node Type Keywords -@subsection Type Keywords - -You can specify keyword-argument pairs in a customization type after the -type name symbol. Here are the keywords you can use, and their -meanings: - -@table @code -@item :value @var{default} -This is used for a type that appears as an alternative inside of -@code{choice}; it specifies the default value to use, at first, if and -when the user selects this alternative with the menu in the -customization buffer. - -Of course, if the actual value of the option fits this alternative, it -will appear showing the actual value, not @var{default}. - -If @code{nil} is not a valid value for the alternative, then it is -essential to specify a valid default with @code{:value}. - -@item :format @var{format-string} -@kindex format@r{, customization keyword} -This string will be inserted in the buffer to represent the value -corresponding to the type. The following @samp{%} escapes are available -for use in @var{format-string}: - -@table @samp -@item %[@var{button}%] -Display the text @var{button} marked as a button. The @code{:action} -attribute specifies what the button will do if the user invokes it; -its value is a function which takes two arguments---the widget which -the button appears in, and the event. - -There is no way to specify two different buttons with different -actions. - -@item %@{@var{sample}%@} -Show @var{sample} in a special face specified by @code{:sample-face}. - -@item %v -Substitute the item's value. How the value is represented depends on -the kind of item, and (for variables) on the customization type. - -@item %d -Substitute the item's documentation string. - -@item %h -Like @samp{%d}, but if the documentation string is more than one line, -add an active field to control whether to show all of it or just the -first line. - -@item %t -Substitute the tag here. You specify the tag with the @code{:tag} -keyword. - -@item %% -Display a literal @samp{%}. -@end table - -@item :action @var{action} -@kindex action@r{, customization keyword} -Perform @var{action} if the user clicks on a button. - -@item :button-face @var{face} -@kindex button-face@r{, customization keyword} -Use the face @var{face} (a face name or a list of face names) for button -text displayed with @samp{%[@dots{}%]}. - -@item :button-prefix @var{prefix} -@itemx :button-suffix @var{suffix} -@kindex button-prefix@r{, customization keyword} -@kindex button-suffix@r{, customization keyword} -These specify the text to display before and after a button. -Each can be: - -@table @asis -@item @code{nil} -No text is inserted. - -@item a string -The string is inserted literally. - -@item a symbol -The symbol's value is used. -@end table - -@item :tag @var{tag} -Use @var{tag} (a string) as the tag for the value (or part of the value) -that corresponds to this type. - -@item :doc @var{doc} -@kindex doc@r{, customization keyword} -Use @var{doc} as the documentation string for this value (or part of the -value) that corresponds to this type. In order for this to work, you -must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} -in that value. - -The usual reason to specify a documentation string for a type is to -provide more information about the meanings of alternatives inside a -@code{:choice} type or the parts of some other composite type. - -@item :help-echo @var{motion-doc} -@kindex help-echo@r{, customization keyword} -When you move to this item with @code{widget-forward} or -@code{widget-backward}, it will display the string @var{motion-doc} in -the echo area. In addition, @var{motion-doc} is used as the mouse -@code{help-echo} string and may actually be a function or form evaluated -to yield a help string. If it is a function, it is called with one -argument, the widget. - -@item :match @var{function} -@kindex match@r{, customization keyword} -Specify how to decide whether a value matches the type. The -corresponding value, @var{function}, should be a function that accepts -two arguments, a widget and a value; it should return non-@code{nil} if -the value is acceptable. - -@ignore -@item :indent @var{columns} -Indent this item by @var{columns} columns. The indentation is used for -@samp{%n}, and automatically for group names, for checklists and radio -buttons, and for editable lists. It affects the whole of the -item except for the first line. - -@item :offset @var{columns} -An integer indicating how many extra spaces to indent the subitems of -this item. By default, subitems are indented the same as their parent. - -@item :extra-offset -An integer indicating how many extra spaces to add to this item's -indentation, compared to its parent. - -@item :notify -A function called each time the item or a subitem is changed. The -function is called with two or three arguments. The first argument is -the item itself, the second argument is the item that was changed, and -the third argument is the event leading to the change, if any. - -@item :menu-tag -A tag used in the menu when the widget is used as an option in a -@code{menu-choice} widget. - -@item :menu-tag-get -A function used for finding the tag when the widget is used as an option -in a @code{menu-choice} widget. By default, the tag used will be either the -@code{:menu-tag} or @code{:tag} property if present, or the @code{princ} -representation of the @code{:value} property if not. - -@item :validate -A function which takes a widget as an argument, and return @code{nil} -if the widget's current value is valid for the widget. Otherwise, it -should return the widget containing the invalid data, and set that -widget's @code{:error} property to a string explaining the error. - -You can use the function @code{widget-children-validate} for this job; -it tests that all children of @var{widget} are valid. - -@item :tab-order -Specify the order in which widgets are traversed with -@code{widget-forward} or @code{widget-backward}. This is only partially -implemented. - -@enumerate a -@item -Widgets with tabbing order @code{-1} are ignored. - -@item -(Unimplemented) When on a widget with tabbing order @var{n}, go to the -next widget in the buffer with tabbing order @var{n+1} or @code{nil}, -whichever comes first. - -@item -When on a widget with no tabbing order specified, go to the next widget -in the buffer with a positive tabbing order, or @code{nil} -@end enumerate - -@item :parent -The parent of a nested widget (e.g., a @code{menu-choice} item or an -element of a @code{editable-list} widget). - -@item :sibling-args -This keyword is only used for members of a @code{radio-button-choice} or -@code{checklist}. The value should be a list of extra keyword -arguments, which will be used when creating the @code{radio-button} or -@code{checkbox} associated with this item. -@end ignore -@end table - -@node Defining New Types -@subsection Defining New Types - -In the previous sections we have described how to construct elaborate -type specifications for @code{defcustom}. In some cases you may want -to give such a type specification a name. The obvious case is when -you are using the same type for many user options: rather than repeat -the specification for each option, you can give the type specification -a name, and use that name each @code{defcustom}. The other case is -when a user option's value is a recursive data structure. To make it -possible for a datatype to refer to itself, it needs to have a name. - -Since custom types are implemented as widgets, the way to define a new -customize type is to define a new widget. We are not going to describe -the widget interface here in details, see @ref{Top, , Introduction, -widget, The Emacs Widget Library}, for that. Instead we are going to -demonstrate the minimal functionality needed for defining new customize -types by a simple example. - -@example -(define-widget 'binary-tree-of-string 'lazy - "A binary tree made of cons-cells and strings." - :offset 4 - :tag "Node" - :type '(choice (string :tag "Leaf" :value "") - (cons :tag "Interior" - :value ("" . "") - binary-tree-of-string - binary-tree-of-string))) - -(defcustom foo-bar "" - "Sample variable holding a binary tree of strings." - :type 'binary-tree-of-string) -@end example - -The function to define a new widget is called @code{define-widget}. The -first argument is the symbol we want to make a new widget type. The -second argument is a symbol representing an existing widget, the new -widget is going to be defined in terms of difference from the existing -widget. For the purpose of defining new customization types, the -@code{lazy} widget is perfect, because it accepts a @code{:type} keyword -argument with the same syntax as the keyword argument to -@code{defcustom} with the same name. The third argument is a -documentation string for the new widget. You will be able to see that -string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string -@key{RET}} command. - -After these mandatory arguments follow the keyword arguments. The most -important is @code{:type}, which describes the data type we want to match -with this widget. Here a @code{binary-tree-of-string} is described as -being either a string, or a cons-cell whose car and cdr are themselves -both @code{binary-tree-of-string}. Note the reference to the widget -type we are currently in the process of defining. The @code{:tag} -attribute is a string to name the widget in the user interface, and the -@code{:offset} argument is there to ensure that child nodes are -indented four spaces relative to the parent node, making the tree -structure apparent in the customization buffer. - -The @code{defcustom} shows how the new widget can be used as an ordinary -customization type. - -The reason for the name @code{lazy} is that the other composite -widgets convert their inferior widgets to internal form when the -widget is instantiated in a buffer. This conversion is recursive, so -the inferior widgets will convert @emph{their} inferior widgets. If -the data structure is itself recursive, this conversion is an infinite -recursion. The @code{lazy} widget prevents the recursion: it convert -its @code{:type} argument only when needed. - -@ignore - arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2 -@end ignore diff --git a/lispref/debugging.texi b/lispref/debugging.texi deleted file mode 100644 index a427e746b27..00000000000 --- a/lispref/debugging.texi +++ /dev/null @@ -1,834 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/debugging -@node Debugging, Read and Print, Advising Functions, Top -@chapter Debugging Lisp Programs - - There are three ways to investigate a problem in an Emacs Lisp program, -depending on what you are doing with the program when the problem appears. - -@itemize @bullet -@item -If the problem occurs when you run the program, you can use a Lisp -debugger to investigate what is happening during execution. In addition -to the ordinary debugger, Emacs comes with a source-level debugger, -Edebug. This chapter describes both of them. - -@item -If the problem is syntactic, so that Lisp cannot even read the program, -you can use the Emacs facilities for editing Lisp to localize it. - -@item -If the problem occurs when trying to compile the program with the byte -compiler, you need to know how to examine the compiler's input buffer. -@end itemize - -@menu -* 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. -@end menu - - Another useful debugging tool is the dribble file. When a dribble -file is open, Emacs copies all keyboard input characters to that file. -Afterward, you can examine the file to find out what input was used. -@xref{Terminal Input}. - - For debugging problems in terminal descriptions, the -@code{open-termscript} function can be useful. @xref{Terminal Output}. - -@node Debugger -@section The Lisp Debugger -@cindex debugger for Emacs Lisp -@cindex Lisp debugger -@cindex break - - The ordinary @dfn{Lisp debugger} provides the ability to suspend -evaluation of a form. While evaluation is suspended (a state that is -commonly known as a @dfn{break}), you may examine the run time stack, -examine the values of local or global variables, or change those values. -Since a break is a recursive edit, all the usual editing facilities of -Emacs are available; you can even run programs that will enter the -debugger recursively. @xref{Recursive Editing}. - -@menu -* 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. -@end menu - -@node Error Debugging -@subsection Entering the Debugger on an Error -@cindex error debugging -@cindex debugging errors - - The most important time to enter the debugger is when a Lisp error -happens. This allows you to investigate the immediate causes of the -error. - - However, entry to the debugger is not a normal consequence of an -error. Many commands frequently cause Lisp errors when invoked -inappropriately (such as @kbd{C-f} at the end of the buffer), and during -ordinary editing it would be very inconvenient to enter the debugger -each time this happens. So if you want errors to enter the debugger, set -the variable @code{debug-on-error} to non-@code{nil}. (The command -@code{toggle-debug-on-error} provides an easy way to do this.) - -@defopt debug-on-error -This variable determines whether the debugger is called when an error is -signaled and not handled. If @code{debug-on-error} is @code{t}, all -kinds of errors call the debugger (except those listed in -@code{debug-ignored-errors}). If it is @code{nil}, none call the -debugger. - -The value can also be a list of error conditions that should call the -debugger. For example, if you set it to the list -@code{(void-variable)}, then only errors about a variable that has no -value invoke the debugger. - -When this variable is non-@code{nil}, Emacs does not create an error -handler around process filter functions and sentinels. Therefore, -errors in these functions also invoke the debugger. @xref{Processes}. -@end defopt - -@defopt debug-ignored-errors -This variable specifies certain kinds of errors that should not enter -the debugger. Its value is a list of error condition symbols and/or -regular expressions. If the error has any of those condition symbols, -or if the error message matches any of the regular expressions, then -that error does not enter the debugger, regardless of the value of -@code{debug-on-error}. - -The normal value of this variable lists several errors that happen often -during editing but rarely result from bugs in Lisp programs. However, -``rarely'' is not ``never''; if your program fails with an error that -matches this list, you will need to change this list in order to debug -the error. The easiest way is usually to set -@code{debug-ignored-errors} to @code{nil}. -@end defopt - -@defopt eval-expression-debug-on-error -If this variable has a non-@code{nil} value, then -@code{debug-on-error} is set to @code{t} when evaluating with the -command @code{eval-expression}. If -@code{eval-expression-debug-on-error} is @code{nil}, then the value of -@code{debug-on-error} is not changed. @xref{Lisp Eval,, Evaluating -Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}. -@end defopt - -@defopt debug-on-signal -Normally, errors that are caught by @code{condition-case} never run the -debugger, even if @code{debug-on-error} is non-@code{nil}. In other -words, @code{condition-case} gets a chance to handle the error before -the debugger gets a chance. - -If you set @code{debug-on-signal} to a non-@code{nil} value, then the -debugger gets the first chance at every error; an error will invoke the -debugger regardless of any @code{condition-case}, if it fits the -criteria specified by the values of @code{debug-on-error} and -@code{debug-ignored-errors}. - -@strong{Warning:} This variable is strong medicine! Various parts of -Emacs handle errors in the normal course of affairs, and you may not -even realize that errors happen there. If you set -@code{debug-on-signal} to a non-@code{nil} value, those errors will -enter the debugger. - -@strong{Warning:} @code{debug-on-signal} has no effect when -@code{debug-on-error} is @code{nil}. -@end defopt - - To debug an error that happens during loading of the init -file, use the option @samp{--debug-init}. This binds -@code{debug-on-error} to @code{t} while loading the init file, and -bypasses the @code{condition-case} which normally catches errors in the -init file. - - If your init file sets @code{debug-on-error}, the effect may -not last past the end of loading the init file. (This is an undesirable -byproduct of the code that implements the @samp{--debug-init} command -line option.) The best way to make the init file set -@code{debug-on-error} permanently is with @code{after-init-hook}, like -this: - -@example -(add-hook 'after-init-hook - (lambda () (setq debug-on-error t))) -@end example - -@node Infinite Loops -@subsection Debugging Infinite Loops -@cindex infinite loops -@cindex loops, infinite -@cindex quitting from infinite loop -@cindex stopping an infinite loop - - When a program loops infinitely and fails to return, your first -problem is to stop the loop. On most operating systems, you can do this -with @kbd{C-g}, which causes a @dfn{quit}. - - Ordinary quitting gives no information about why the program was -looping. To get more information, you can set the variable -@code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not -considered an error, and @code{debug-on-error} has no effect on the -handling of @kbd{C-g}. Likewise, @code{debug-on-quit} has no effect on -errors. - - Once you have the debugger running in the middle of the infinite loop, -you can proceed from the debugger using the stepping commands. If you -step through the entire loop, you will probably get enough information -to solve the problem. - -@defopt debug-on-quit -This variable determines whether the debugger is called when @code{quit} -is signaled and not handled. If @code{debug-on-quit} is non-@code{nil}, -then the debugger is called whenever you quit (that is, type @kbd{C-g}). -If @code{debug-on-quit} is @code{nil}, then the debugger is not called -when you quit. @xref{Quitting}. -@end defopt - -@node Function Debugging -@subsection Entering the Debugger on a Function Call -@cindex function call debugging -@cindex debugging specific functions - - To investigate a problem that happens in the middle of a program, one -useful technique is to enter the debugger whenever a certain function is -called. You can do this to the function in which the problem occurs, -and then step through the function, or you can do this to a function -called shortly before the problem, step quickly over the call to that -function, and then step through its caller. - -@deffn Command debug-on-entry function-name -This function requests @var{function-name} to invoke the debugger each -time it is called. It works by inserting the form -@code{(implement-debug-on-entry)} into the function definition as the -first form. - -Any function or macro defined as Lisp code may be set to break on -entry, regardless of whether it is interpreted code or compiled code. -If the function is a command, it will enter the debugger when called -from Lisp and when called interactively (after the reading of the -arguments). You can also set debug-on-entry for primitive functions -(i.e., those written in C) this way, but it only takes effect when the -primitive is called from Lisp code. Debug-on-entry is not allowed for -special forms. - -When @code{debug-on-entry} is called interactively, it prompts for -@var{function-name} in the minibuffer. If the function is already set -up to invoke the debugger on entry, @code{debug-on-entry} does nothing. -@code{debug-on-entry} always returns @var{function-name}. - -@strong{Warning:} if you redefine a function after using -@code{debug-on-entry} on it, the code to enter the debugger is -discarded by the redefinition. In effect, redefining the function -cancels the break-on-entry feature for that function. - -Here's an example to illustrate use of this function: - -@example -@group -(defun fact (n) - (if (zerop n) 1 - (* n (fact (1- n))))) - @result{} fact -@end group -@group -(debug-on-entry 'fact) - @result{} fact -@end group -@group -(fact 3) -@end group - -@group ------- Buffer: *Backtrace* ------ -Debugger entered--entering a function: -* fact(3) - eval((fact 3)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ------- Buffer: *Backtrace* ------ -@end group - -@group -(symbol-function 'fact) - @result{} (lambda (n) - (debug (quote debug)) - (if (zerop n) 1 (* n (fact (1- n))))) -@end group -@end example -@end deffn - -@deffn Command cancel-debug-on-entry &optional function-name -This function undoes the effect of @code{debug-on-entry} on -@var{function-name}. When called interactively, it prompts for -@var{function-name} in the minibuffer. If @var{function-name} is -omitted or @code{nil}, it cancels break-on-entry for all functions. -Calling @code{cancel-debug-on-entry} does nothing to a function which is -not currently set up to break on entry. -@end deffn - -@node Explicit Debug -@subsection Explicit Entry to the Debugger - - You can cause the debugger to be called at a certain point in your -program by writing the expression @code{(debug)} at that point. To do -this, visit the source file, insert the text @samp{(debug)} at the -proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key -binding). @strong{Warning:} if you do this for temporary debugging -purposes, be sure to undo this insertion before you save the file! - - The place where you insert @samp{(debug)} must be a place where an -additional form can be evaluated and its value ignored. (If the value -of @code{(debug)} isn't ignored, it will alter the execution of the -program!) The most common suitable places are inside a @code{progn} or -an implicit @code{progn} (@pxref{Sequencing}). - -@node Using Debugger -@subsection Using the Debugger - - When the debugger is entered, it displays the previously selected -buffer in one window and a buffer named @samp{*Backtrace*} in another -window. The backtrace buffer contains one line for each level of Lisp -function execution currently going on. At the beginning of this buffer -is a message describing the reason that the debugger was invoked (such -as the error message and associated data, if it was invoked due to an -error). - - The backtrace buffer is read-only and uses a special major mode, -Debugger mode, in which letters are defined as debugger commands. The -usual Emacs editing commands are available; thus, you can switch windows -to examine the buffer that was being edited at the time of the error, -switch buffers, visit files, or do any other sort of editing. However, -the debugger is a recursive editing level (@pxref{Recursive Editing}) -and it is wise to go back to the backtrace buffer and exit the debugger -(with the @kbd{q} command) when you are finished with it. Exiting -the debugger gets out of the recursive edit and kills the backtrace -buffer. - -@cindex current stack frame - The backtrace buffer shows you the functions that are executing and -their argument values. It also allows you to specify a stack frame by -moving point to the line describing that frame. (A stack frame is the -place where the Lisp interpreter records information about a particular -invocation of a function.) The frame whose line point is on is -considered the @dfn{current frame}. Some of the debugger commands -operate on the current frame. If a line starts with a star, that means -that exiting that frame will call the debugger again. This is useful -for examining the return value of a function. - - If a function name is underlined, that means the debugger knows -where its source code is located. You can click @kbd{Mouse-2} on that -name, or move to it and type @key{RET}, to visit the source code. - - The debugger itself must be run byte-compiled, since it makes -assumptions about how many stack frames are used for the debugger -itself. These assumptions are false if the debugger is running -interpreted. - -@node Debugger Commands -@subsection Debugger Commands -@cindex debugger command list - - The debugger buffer (in Debugger mode) provides special commands in -addition to the usual Emacs commands. The most important use of -debugger commands is for stepping through code, so that you can see -how control flows. The debugger can step through the control -structures of an interpreted function, but cannot do so in a -byte-compiled function. If you would like to step through a -byte-compiled function, replace it with an interpreted definition of -the same function. (To do this, visit the source for the function and -type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger -to step through a primitive function. - - Here is a list of Debugger mode commands: - -@table @kbd -@item c -Exit the debugger and continue execution. When continuing is possible, -it resumes execution of the program as if the debugger had never been -entered (aside from any side-effects that you caused by changing -variable values or data structures while inside the debugger). - -Continuing is possible after entry to the debugger due to function entry -or exit, explicit invocation, or quitting. You cannot continue if the -debugger was entered because of an error. - -@item d -Continue execution, but enter the debugger the next time any Lisp -function is called. This allows you to step through the -subexpressions of an expression, seeing what values the subexpressions -compute, and what else they do. - -The stack frame made for the function call which enters the debugger in -this way will be flagged automatically so that the debugger will be -called again when the frame is exited. You can use the @kbd{u} command -to cancel this flag. - -@item b -Flag the current frame so that the debugger will be entered when the -frame is exited. Frames flagged in this way are marked with stars -in the backtrace buffer. - -@item u -Don't enter the debugger when the current frame is exited. This -cancels a @kbd{b} command on that frame. The visible effect is to -remove the star from the line in the backtrace buffer. - -@item j -Flag the current frame like @kbd{b}. Then continue execution like -@kbd{c}, but temporarily disable break-on-entry for all functions that -are set up to do so by @code{debug-on-entry}. - -@item e -Read a Lisp expression in the minibuffer, evaluate it, and print the -value in the echo area. The debugger alters certain important -variables, and the current buffer, as part of its operation; @kbd{e} -temporarily restores their values from outside the debugger, so you can -examine and change them. This makes the debugger more transparent. By -contrast, @kbd{M-:} does nothing special in the debugger; it shows you -the variable values within the debugger. - -@item R -Like @kbd{e}, but also save the result of evaluation in the -buffer @samp{*Debugger-record*}. - -@item q -Terminate the program being debugged; return to top-level Emacs -command execution. - -If the debugger was entered due to a @kbd{C-g} but you really want -to quit, and not debug, use the @kbd{q} command. - -@item r -Return a value from the debugger. The value is computed by reading an -expression with the minibuffer and evaluating it. - -The @kbd{r} command is useful when the debugger was invoked due to exit -from a Lisp call frame (as requested with @kbd{b} or by entering the -frame with @kbd{d}); then the value specified in the @kbd{r} command is -used as the value of that frame. It is also useful if you call -@code{debug} and use its return value. Otherwise, @kbd{r} has the same -effect as @kbd{c}, and the specified return value does not matter. - -You can't use @kbd{r} when the debugger was entered due to an error. - -@item l -Display a list of functions that will invoke the debugger when called. -This is a list of functions that are set to break on entry by means of -@code{debug-on-entry}. @strong{Warning:} if you redefine such a -function and thus cancel the effect of @code{debug-on-entry}, it may -erroneously show up in this list. -@end table - -@node Invoking the Debugger -@subsection Invoking the Debugger - - Here we describe in full detail the function @code{debug} that is used -to invoke the debugger. - -@defun debug &rest debugger-args -This function enters the debugger. It switches buffers to a buffer -named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second -recursive entry to the debugger, etc.), and fills it with information -about the stack of Lisp function calls. It then enters a recursive -edit, showing the backtrace buffer in Debugger mode. - -The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit -the recursive edit; then @code{debug} switches back to the previous -buffer and returns to whatever called @code{debug}. This is the only -way the function @code{debug} can return to its caller. - -The use of the @var{debugger-args} is that @code{debug} displays the -rest of its arguments at the top of the @samp{*Backtrace*} buffer, so -that the user can see them. Except as described below, this is the -@emph{only} way these arguments are used. - -However, certain values for first argument to @code{debug} have a -special significance. (Normally, these values are used only by the -internals of Emacs, and not by programmers calling @code{debug}.) Here -is a table of these special values: - -@table @code -@item lambda -@cindex @code{lambda} in debug -A first argument of @code{lambda} means @code{debug} was called -because of entry to a function when @code{debug-on-next-call} was -non-@code{nil}. The debugger displays @samp{Debugger -entered--entering a function:} as a line of text at the top of the -buffer. - -@item debug -@code{debug} as first argument means @code{debug} was called because -of entry to a function that was set to debug on entry. The debugger -displays the string @samp{Debugger entered--entering a function:}, -just as in the @code{lambda} case. It also marks the stack frame for -that function so that it will invoke the debugger when exited. - -@item t -When the first argument is @code{t}, this indicates a call to -@code{debug} due to evaluation of a function call form when -@code{debug-on-next-call} is non-@code{nil}. The debugger displays -@samp{Debugger entered--beginning evaluation of function call form:} -as the top line in the buffer. - -@item exit -When the first argument is @code{exit}, it indicates the exit of a -stack frame previously marked to invoke the debugger on exit. The -second argument given to @code{debug} in this case is the value being -returned from the frame. The debugger displays @samp{Debugger -entered--returning value:} in the top line of the buffer, followed by -the value being returned. - -@item error -@cindex @code{error} in debug -When the first argument is @code{error}, the debugger indicates that -it is being entered because an error or @code{quit} was signaled and -not handled, by displaying @samp{Debugger entered--Lisp error:} -followed by the error signaled and any arguments to @code{signal}. -For example, - -@example -@group -(let ((debug-on-error t)) - (/ 1 0)) -@end group - -@group ------- Buffer: *Backtrace* ------ -Debugger entered--Lisp error: (arith-error) - /(1 0) -... ------- Buffer: *Backtrace* ------ -@end group -@end example - -If an error was signaled, presumably the variable -@code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled, -then presumably the variable @code{debug-on-quit} is non-@code{nil}. - -@item nil -Use @code{nil} as the first of the @var{debugger-args} when you want -to enter the debugger explicitly. The rest of the @var{debugger-args} -are printed on the top line of the buffer. You can use this feature to -display messages---for example, to remind yourself of the conditions -under which @code{debug} is called. -@end table -@end defun - -@node Internals of Debugger -@subsection Internals of the Debugger - - This section describes functions and variables used internally by the -debugger. - -@defvar debugger -The value of this variable is the function to call to invoke the -debugger. Its value must be a function of any number of arguments, or, -more typically, the name of a function. This function should invoke -some kind of debugger. The default value of the variable is -@code{debug}. - -The first argument that Lisp hands to the function indicates why it -was called. The convention for arguments is detailed in the description -of @code{debug} (@pxref{Invoking the Debugger}). -@end defvar - -@deffn Command backtrace -@cindex run time stack -@cindex call stack -This function prints a trace of Lisp function calls currently active. -This is the function used by @code{debug} to fill up the -@samp{*Backtrace*} buffer. It is written in C, since it must have access -to the stack to determine which function calls are active. The return -value is always @code{nil}. - -In the following example, a Lisp expression calls @code{backtrace} -explicitly. This prints the backtrace to the stream -@code{standard-output}, which, in this case, is the buffer -@samp{backtrace-output}. - -Each line of the backtrace represents one function call. The line shows -the values of the function's arguments if they are all known; if they -are still being computed, the line says so. The arguments of special -forms are elided. - -@smallexample -@group -(with-output-to-temp-buffer "backtrace-output" - (let ((var 1)) - (save-excursion - (setq var (eval '(progn - (1+ var) - (list 'testing (backtrace)))))))) - - @result{} (testing nil) -@end group - -@group ------------ Buffer: backtrace-output ------------ - backtrace() - (list ...computing arguments...) -@end group - (progn ...) - eval((progn (1+ var) (list (quote testing) (backtrace)))) - (setq ...) - (save-excursion ...) - (let ...) - (with-output-to-temp-buffer ...) - eval((with-output-to-temp-buffer ...)) - eval-last-sexp-1(nil) -@group - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ------------ Buffer: backtrace-output ------------ -@end group -@end smallexample -@end deffn - -@ignore @c Not worth mentioning -@defopt stack-trace-on-error -@cindex stack trace -This variable controls whether Lisp automatically displays a -backtrace buffer after every error that is not handled. A quit signal -counts as an error for this variable. If it is non-@code{nil} then a -backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every -error. If it is @code{nil}, then a backtrace is not shown. - -When a backtrace is shown, that buffer is not selected. If either -@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then -a backtrace is shown in one buffer, and the debugger is popped up in -another buffer with its own backtrace. - -We consider this feature to be obsolete and superseded by the debugger -itself. -@end defopt -@end ignore - -@defvar debug-on-next-call -@cindex @code{eval}, and debugging -@cindex @code{apply}, and debugging -@cindex @code{funcall}, and debugging -If this variable is non-@code{nil}, it says to call the debugger before -the next @code{eval}, @code{apply} or @code{funcall}. Entering the -debugger sets @code{debug-on-next-call} to @code{nil}. - -The @kbd{d} command in the debugger works by setting this variable. -@end defvar - -@defun backtrace-debug level flag -This function sets the debug-on-exit flag of the stack frame @var{level} -levels down the stack, giving it the value @var{flag}. If @var{flag} is -non-@code{nil}, this will cause the debugger to be entered when that -frame later exits. Even a nonlocal exit through that frame will enter -the debugger. - -This function is used only by the debugger. -@end defun - -@defvar command-debug-status -This variable records the debugging status of the current interactive -command. Each time a command is called interactively, this variable is -bound to @code{nil}. The debugger can set this variable to leave -information for future debugger invocations during the same command -invocation. - -The advantage of using this variable rather than an ordinary global -variable is that the data will never carry over to a subsequent command -invocation. -@end defvar - -@defun backtrace-frame frame-number -The function @code{backtrace-frame} is intended for use in Lisp -debuggers. It returns information about what computation is happening -in the stack frame @var{frame-number} levels down. - -If that frame has not evaluated the arguments yet, or is a special -form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. - -If that frame has evaluated its arguments and called its function -already, the return value is @code{(t @var{function} -@var{arg-values}@dots{})}. - -In the return value, @var{function} is whatever was supplied as the -@sc{car} of the evaluated list, or a @code{lambda} expression in the -case of a macro call. If the function has a @code{&rest} argument, that -is represented as the tail of the list @var{arg-values}. - -If @var{frame-number} is out of range, @code{backtrace-frame} returns -@code{nil}. -@end defun - -@include edebug.texi - -@node Syntax Errors -@section Debugging Invalid Lisp Syntax -@cindex debugging invalid Lisp syntax - - The Lisp reader reports invalid syntax, but cannot say where the real -problem is. For example, the error ``End of file during parsing'' in -evaluating an expression indicates an excess of open parentheses (or -square brackets). The reader detects this imbalance at the end of the -file, but it cannot figure out where the close parenthesis should have -been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close -parenthesis or missing open parenthesis, but does not say where the -missing parenthesis belongs. How, then, to find what to change? - - If the problem is not simply an imbalance of parentheses, a useful -technique is to try @kbd{C-M-e} at the beginning of each defun, and see -if it goes to the place where that defun appears to end. If it does -not, there is a problem in that defun. - -@cindex unbalanced parentheses -@cindex parenthesis mismatch, debugging - However, unmatched parentheses are the most common syntax errors in -Lisp, and we can give further advice for those cases. (In addition, -just moving point through the code with Show Paren mode enabled might -find the mismatch.) - -@menu -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. -@end menu - -@node Excess Open -@subsection Excess Open Parentheses - - The first step is to find the defun that is unbalanced. If there is -an excess open parenthesis, the way to do this is to go to the end of -the file and type @kbd{C-u C-M-u}. This will move you to the -beginning of the first defun that is unbalanced. - - The next step is to determine precisely what is wrong. There is no -way to be sure of this except by studying the program, but often the -existing indentation is a clue to where the parentheses should have -been. The easiest way to use this clue is to reindent with @kbd{C-M-q} -and see what moves. @strong{But don't do this yet!} Keep reading, -first. - - Before you do this, make sure the defun has enough close parentheses. -Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest -of the file until the end. So move to the end of the defun and insert a -close parenthesis there. Don't use @kbd{C-M-e} to move there, since -that too will fail to work until the defun is balanced. - - Now you can go to the beginning of the defun and type @kbd{C-M-q}. -Usually all the lines from a certain point to the end of the function -will shift to the right. There is probably a missing close parenthesis, -or a superfluous open parenthesis, near that point. (However, don't -assume this is true; study the code to make sure.) Once you have found -the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old -indentation is probably appropriate to the intended parentheses. - - After you think you have fixed the problem, use @kbd{C-M-q} again. If -the old indentation actually fit the intended nesting of parentheses, -and you have put back those parentheses, @kbd{C-M-q} should not change -anything. - -@node Excess Close -@subsection Excess Close Parentheses - - To deal with an excess close parenthesis, first go to the beginning -of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first -unbalanced defun. - - Then find the actual matching close parenthesis by typing @kbd{C-M-f} -at the beginning of that defun. This will leave you somewhere short of -the place where the defun ought to end. It is possible that you will -find a spurious close parenthesis in that vicinity. - - If you don't see a problem at that point, the next thing to do is to -type @kbd{C-M-q} at the beginning of the defun. A range of lines will -probably shift left; if so, the missing open parenthesis or spurious -close parenthesis is probably near the first of those lines. (However, -don't assume this is true; study the code to make sure.) Once you have -found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the -old indentation is probably appropriate to the intended parentheses. - - After you think you have fixed the problem, use @kbd{C-M-q} again. If -the old indentation actually fits the intended nesting of parentheses, -and you have put back those parentheses, @kbd{C-M-q} should not change -anything. - -@node Test Coverage -@section Test Coverage -@cindex coverage testing - -@findex testcover-start -@findex testcover-mark-all -@findex testcover-next-mark - You can do coverage testing for a file of Lisp code by loading the -@code{testcover} library and using the command @kbd{M-x -testcover-start @key{RET} @var{file} @key{RET}} to instrument the -code. Then test your code by calling it one or more times. Then use -the command @kbd{M-x testcover-mark-all} to display colored highlights -on the code to show where coverage is insufficient. The command -@kbd{M-x testcover-next-mark} will move point forward to the next -highlighted spot. - - Normally, a red highlight indicates the form was never completely -evaluated; a brown highlight means it always evaluated to the same -value (meaning there has been little testing of what is done with the -result). However, the red highlight is skipped for forms that can't -possibly complete their evaluation, such as @code{error}. The brown -highlight is skipped for forms that are expected to always evaluate to -the same value, such as @code{(setq x 14)}. - - For difficult cases, you can add do-nothing macros to your code to -give advice to the test coverage tool. - -@defmac 1value form -Evaluate @var{form} and return its value, but inform coverage testing -that @var{form}'s value should always be the same. -@end defmac - -@defmac noreturn form -Evaluate @var{form}, informing coverage testing that @var{form} should -never return. If it ever does return, you get a run-time error. -@end defmac - - Edebug also has a coverage testing feature (@pxref{Coverage -Testing}). These features partly duplicate each other, and it would -be cleaner to combine them. - -@node Compilation Errors -@section Debugging Problems in Compilation -@cindex debugging byte compilation problems - - When an error happens during byte compilation, it is normally due to -invalid syntax in the program you are compiling. The compiler prints a -suitable error message in the @samp{*Compile-Log*} buffer, and then -stops. The message may state a function name in which the error was -found, or it may not. Either way, here is how to find out where in the -file the error occurred. - - What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}. -(Note that the buffer name starts with a space, so it does not show -up in @kbd{M-x list-buffers}.) This buffer contains the program being -compiled, and point shows how far the byte compiler was able to read. - - If the error was due to invalid Lisp syntax, point shows exactly where -the invalid syntax was @emph{detected}. The cause of the error is not -necessarily near by! Use the techniques in the previous section to find -the error. - - If the error was detected while compiling a form that had been read -successfully, then point is located at the end of the form. In this -case, this technique can't localize the error precisely, but can still -show you which function to check. - -@ignore - arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7 -@end ignore diff --git a/lispref/display.texi b/lispref/display.texi deleted file mode 100644 index db630ba2c51..00000000000 --- a/lispref/display.texi +++ /dev/null @@ -1,5442 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/display -@node Display, System Interface, Processes, Top -@chapter Emacs Display - - This chapter describes a number of features related to the display -that Emacs presents to the user. - -@menu -* 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. -@end menu - -@node Refresh Screen -@section Refreshing the Screen - - The function @code{redraw-frame} clears and redisplays the entire -contents of a given frame (@pxref{Frames}). This is useful if the -screen is corrupted. - -@c Emacs 19 feature -@defun redraw-frame frame -This function clears and redisplays frame @var{frame}. -@end defun - - Even more powerful is @code{redraw-display}: - -@deffn Command redraw-display -This function clears and redisplays all visible frames. -@end deffn - - This function calls for redisplay of certain windows, the next time -redisplay is done, but does not clear them first. - -@defun force-window-update &optional object -This function forces some or all windows to be updated on next redisplay. -If @var{object} is a window, it forces redisplay of that window. If -@var{object} is a buffer or buffer name, it forces redisplay of all -windows displaying that buffer. If @var{object} is @code{nil} (or -omitted), it forces redisplay of all windows. -@end defun - - Processing user input takes absolute priority over redisplay. If you -call these functions when input is available, they do nothing -immediately, but a full redisplay does happen eventually---after all the -input has been processed. - - Normally, suspending and resuming Emacs also refreshes the screen. -Some terminal emulators record separate contents for display-oriented -programs such as Emacs and for ordinary sequential display. If you are -using such a terminal, you might want to inhibit the redisplay on -resumption. - -@defvar no-redraw-on-reenter -@cindex suspend (cf. @code{no-redraw-on-reenter}) -@cindex resume (cf. @code{no-redraw-on-reenter}) -This variable controls whether Emacs redraws the entire screen after it -has been suspended and resumed. Non-@code{nil} means there is no need -to redraw, @code{nil} means redrawing is needed. The default is @code{nil}. -@end defvar - -@node Forcing Redisplay -@section Forcing Redisplay -@cindex forcing redisplay - - Emacs redisplay normally stops if input arrives, and does not happen -at all if input is available before it starts. Most of the time, this -is exactly what you want. However, you can prevent preemption by -binding @code{redisplay-dont-pause} to a non-@code{nil} value. - -@defvar redisplay-preemption-period -This variable specifies how many seconds Emacs waits between checks -for new input during redisplay. (The default is 0.1 seconds.) If -input has arrived when Emacs checks, it pre-empts redisplay and -processes the available input before trying again to redisplay. - -If this variable is @code{nil}, Emacs does not check for input during -redisplay, and redisplay cannot be preempted by input. - -This variable is only obeyed on graphical terminals. For -text terminals, see @ref{Terminal Output}. -@end defvar - -@defvar redisplay-dont-pause -If this variable is non-@code{nil}, pending input does not -prevent or halt redisplay; redisplay occurs, and finishes, -regardless of whether input is available. -@end defvar - -@defun redisplay &optional force -This function performs an immediate redisplay provided there are no -pending input events. This is equivalent to @code{(sit-for 0)}. - -If the optional argument @var{force} is non-@code{nil}, it forces an -immediate and complete redisplay even if input is available. - -Returns @code{t} if redisplay was performed, or @code{nil} otherwise. -@end defun - -@node Truncation -@section Truncation -@cindex line wrapping -@cindex line truncation -@cindex continuation lines -@cindex @samp{$} in display -@cindex @samp{\} in display - - When a line of text extends beyond the right edge of a window, Emacs -can @dfn{continue} the line (make it ``wrap'' to the next screen -line), or @dfn{truncate} the line (limit it to one screen line). The -additional screen lines used to display a long text line are called -@dfn{continuation} lines. Continuation is not the same as filling; -continuation happens on the screen only, not in the buffer contents, -and it breaks a line precisely at the right margin, not at a word -boundary. @xref{Filling}. - - On a graphical display, tiny arrow images in the window fringes -indicate truncated and continued lines (@pxref{Fringes}). On a text -terminal, a @samp{$} in the rightmost column of the window indicates -truncation; a @samp{\} on the rightmost column indicates a line that -``wraps.'' (The display table can specify alternate characters to use -for this; @pxref{Display Tables}). - -@defopt truncate-lines -This buffer-local variable controls how Emacs displays lines that extend -beyond the right edge of the window. The default is @code{nil}, which -specifies continuation. If the value is non-@code{nil}, then these -lines are truncated. - -If the variable @code{truncate-partial-width-windows} is non-@code{nil}, -then truncation is always used for side-by-side windows (within one -frame) regardless of the value of @code{truncate-lines}. -@end defopt - -@defopt default-truncate-lines -This variable is the default value for @code{truncate-lines}, for -buffers that do not have buffer-local values for it. -@end defopt - -@defopt truncate-partial-width-windows -This variable controls display of lines that extend beyond the right -edge of the window, in side-by-side windows (@pxref{Splitting Windows}). -If it is non-@code{nil}, these lines are truncated; otherwise, -@code{truncate-lines} says what to do with them. -@end defopt - - When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in -a window, that forces truncation. - - If your buffer contains @emph{very} long lines, and you use -continuation to display them, just thinking about them can make Emacs -redisplay slow. The column computation and indentation functions also -become slow. Then you might find it advisable to set -@code{cache-long-line-scans} to @code{t}. - -@defvar cache-long-line-scans -If this variable is non-@code{nil}, various indentation and motion -functions, and Emacs redisplay, cache the results of scanning the -buffer, and consult the cache to avoid rescanning regions of the buffer -unless they are modified. - -Turning on the cache slows down processing of short lines somewhat. - -This variable is automatically buffer-local in every buffer. -@end defvar - -@node The Echo Area -@section The Echo Area -@cindex error display -@cindex echo area - - The @dfn{echo area} is used for displaying error messages -(@pxref{Errors}), for messages made with the @code{message} primitive, -and for echoing keystrokes. It is not the same as the minibuffer, -despite the fact that the minibuffer appears (when active) in the same -place on the screen as the echo area. The @cite{GNU Emacs Manual} -specifies the rules for resolving conflicts between the echo area and -the minibuffer for use of that screen space (@pxref{Minibuffer,, The -Minibuffer, emacs, The GNU Emacs Manual}). - - You can write output in the echo area by using the Lisp printing -functions with @code{t} as the stream (@pxref{Output Functions}), or -explicitly. - -@menu -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. -@end menu - -@node Displaying Messages -@subsection Displaying Messages in the Echo Area -@cindex display message in echo area - - This section describes the functions for explicitly producing echo -area messages. Many other Emacs features display messages there, too. - -@defun message format-string &rest arguments -This function displays a message in the echo area. The argument -@var{format-string} is similar to a C language @code{printf} format -string. See @code{format} in @ref{Formatting Strings}, for the details -on the conversion specifications. @code{message} returns the -constructed string. - -In batch mode, @code{message} prints the message text on the standard -error stream, followed by a newline. - -If @var{format-string}, or strings among the @var{arguments}, have -@code{face} text properties, these affect the way the message is displayed. - -@c Emacs 19 feature -If @var{format-string} is @code{nil} or the empty string, -@code{message} clears the echo area; if the echo area has been -expanded automatically, this brings it back to its normal size. -If the minibuffer is active, this brings the minibuffer contents back -onto the screen immediately. - -@example -@group -(message "Minibuffer depth is %d." - (minibuffer-depth)) - @print{} Minibuffer depth is 0. -@result{} "Minibuffer depth is 0." -@end group - -@group ----------- Echo Area ---------- -Minibuffer depth is 0. ----------- Echo Area ---------- -@end group -@end example - -To automatically display a message in the echo area or in a pop-buffer, -depending on its size, use @code{display-message-or-buffer} (see below). -@end defun - -@defmac with-temp-message message &rest body -This construct displays a message in the echo area temporarily, during -the execution of @var{body}. It displays @var{message}, executes -@var{body}, then returns the value of the last body form while restoring -the previous echo area contents. -@end defmac - -@defun message-or-box format-string &rest arguments -This function displays a message like @code{message}, but may display it -in a dialog box instead of the echo area. If this function is called in -a command that was invoked using the mouse---more precisely, if -@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either -@code{nil} or a list---then it uses a dialog box or pop-up menu to -display the message. Otherwise, it uses the echo area. (This is the -same criterion that @code{y-or-n-p} uses to make a similar decision; see -@ref{Yes-or-No Queries}.) - -You can force use of the mouse or of the echo area by binding -@code{last-nonmenu-event} to a suitable value around the call. -@end defun - -@defun message-box format-string &rest arguments -@anchor{message-box} -This function displays a message like @code{message}, but uses a dialog -box (or a pop-up menu) whenever that is possible. If it is impossible -to use a dialog box or pop-up menu, because the terminal does not -support them, then @code{message-box} uses the echo area, like -@code{message}. -@end defun - -@defun display-message-or-buffer message &optional buffer-name not-this-window frame -This function displays the message @var{message}, which may be either a -string or a buffer. If it is shorter than the maximum height of the -echo area, as defined by @code{max-mini-window-height}, it is displayed -in the echo area, using @code{message}. Otherwise, -@code{display-buffer} is used to show it in a pop-up buffer. - -Returns either the string shown in the echo area, or when a pop-up -buffer is used, the window used to display it. - -If @var{message} is a string, then the optional argument -@var{buffer-name} is the name of the buffer used to display it when a -pop-up buffer is used, defaulting to @samp{*Message*}. In the case -where @var{message} is a string and displayed in the echo area, it is -not specified whether the contents are inserted into the buffer anyway. - -The optional arguments @var{not-this-window} and @var{frame} are as for -@code{display-buffer}, and only used if a buffer is displayed. -@end defun - -@defun current-message -This function returns the message currently being displayed in the -echo area, or @code{nil} if there is none. -@end defun - -@node Progress -@subsection Reporting Operation Progress -@cindex progress reporting - - When an operation can take a while to finish, you should inform the -user about the progress it makes. This way the user can estimate -remaining time and clearly see that Emacs is busy working, not hung. - - Functions listed in this section provide simple and efficient way of -reporting operation progress. Here is a working example that does -nothing useful: - -@smallexample -(let ((progress-reporter - (make-progress-reporter "Collecting mana for Emacs..." - 0 500))) - (dotimes (k 500) - (sit-for 0.01) - (progress-reporter-update progress-reporter k)) - (progress-reporter-done progress-reporter)) -@end smallexample - -@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time -This function creates and returns a @dfn{progress reporter}---an -object you will use as an argument for all other functions listed -here. The idea is to precompute as much data as possible to make -progress reporting very fast. - -When this progress reporter is subsequently used, it will display -@var{message} in the echo area, followed by progress percentage. -@var{message} is treated as a simple string. If you need it to depend -on a filename, for instance, use @code{format} before calling this -function. - -@var{min-value} and @var{max-value} arguments stand for starting and -final states of your operation. For instance, if you scan a buffer, -they should be the results of @code{point-min} and @code{point-max} -correspondingly. It is required that @var{max-value} is greater than -@var{min-value}. If you create progress reporter when some part of -the operation has already been completed, then specify -@var{current-value} argument. But normally you should omit it or set -it to @code{nil}---it will default to @var{min-value} then. - -Remaining arguments control the rate of echo area updates. Progress -reporter will wait for at least @var{min-change} more percents of the -operation to be completed before printing next message. -@var{min-time} specifies the minimum time in seconds to pass between -successive prints. It can be fractional. Depending on Emacs and -system capabilities, progress reporter may or may not respect this -last argument or do it with varying precision. Default value for -@var{min-change} is 1 (one percent), for @var{min-time}---0.2 -(seconds.) - -This function calls @code{progress-reporter-update}, so the first -message is printed immediately. -@end defun - -@defun progress-reporter-update reporter value -This function does the main work of reporting progress of your -operation. It displays the message of @var{reporter}, followed by -progress percentage determined by @var{value}. If percentage is zero, -or close enough according to the @var{min-change} and @var{min-time} -arguments, then it is omitted from the output. - -@var{reporter} must be the result of a call to -@code{make-progress-reporter}. @var{value} specifies the current -state of your operation and must be between @var{min-value} and -@var{max-value} (inclusive) as passed to -@code{make-progress-reporter}. For instance, if you scan a buffer, -then @var{value} should be the result of a call to @code{point}. - -This function respects @var{min-change} and @var{min-time} as passed -to @code{make-progress-reporter} and so does not output new messages -on every invocation. It is thus very fast and normally you should not -try to reduce the number of calls to it: resulting overhead will most -likely negate your effort. -@end defun - -@defun progress-reporter-force-update reporter value &optional new-message -This function is similar to @code{progress-reporter-update} except -that it prints a message in the echo area unconditionally. - -The first two arguments have the same meaning as for -@code{progress-reporter-update}. Optional @var{new-message} allows -you to change the message of the @var{reporter}. Since this functions -always updates the echo area, such a change will be immediately -presented to the user. -@end defun - -@defun progress-reporter-done reporter -This function should be called when the operation is finished. It -prints the message of @var{reporter} followed by word ``done'' in the -echo area. - -You should always call this function and not hope for -@code{progress-reporter-update} to print ``100%.'' Firstly, it may -never print it, there are many good reasons for this not to happen. -Secondly, ``done'' is more explicit. -@end defun - -@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} -This is a convenience macro that works the same way as @code{dotimes} -does, but also reports loop progress using the functions described -above. It allows you to save some typing. - -You can rewrite the example in the beginning of this node using -this macro this way: - -@example -(dotimes-with-progress-reporter - (k 500) - "Collecting some mana for Emacs..." - (sit-for 0.01)) -@end example -@end defmac - -@node Logging Messages -@subsection Logging Messages in @samp{*Messages*} -@cindex logging echo-area messages - - Almost all the messages displayed in the echo area are also recorded -in the @samp{*Messages*} buffer so that the user can refer back to -them. This includes all the messages that are output with -@code{message}. - -@defopt message-log-max -This variable specifies how many lines to keep in the @samp{*Messages*} -buffer. The value @code{t} means there is no limit on how many lines to -keep. The value @code{nil} disables message logging entirely. Here's -how to display a message and prevent it from being logged: - -@example -(let (message-log-max) - (message @dots{})) -@end example -@end defopt - - To make @samp{*Messages*} more convenient for the user, the logging -facility combines successive identical messages. It also combines -successive related messages for the sake of two cases: question -followed by answer, and a series of progress messages. - - A ``question followed by an answer'' means two messages like the -ones produced by @code{y-or-n-p}: the first is @samp{@var{question}}, -and the second is @samp{@var{question}...@var{answer}}. The first -message conveys no additional information beyond what's in the second, -so logging the second message discards the first from the log. - - A ``series of progress messages'' means successive messages like -those produced by @code{make-progress-reporter}. They have the form -@samp{@var{base}...@var{how-far}}, where @var{base} is the same each -time, while @var{how-far} varies. Logging each message in the series -discards the previous one, provided they are consecutive. - - The functions @code{make-progress-reporter} and @code{y-or-n-p} -don't have to do anything special to activate the message log -combination feature. It operates whenever two consecutive messages -are logged that share a common prefix ending in @samp{...}. - -@node Echo Area Customization -@subsection Echo Area Customization - - These variables control details of how the echo area works. - -@defvar cursor-in-echo-area -This variable controls where the cursor appears when a message is -displayed in the echo area. If it is non-@code{nil}, then the cursor -appears at the end of the message. Otherwise, the cursor appears at -point---not in the echo area at all. - -The value is normally @code{nil}; Lisp programs bind it to @code{t} -for brief periods of time. -@end defvar - -@defvar echo-area-clear-hook -This normal hook is run whenever the echo area is cleared---either by -@code{(message nil)} or for any other reason. -@end defvar - -@defvar echo-keystrokes -This variable determines how much time should elapse before command -characters echo. Its value must be an integer or floating point number, -which specifies the -number of seconds to wait before echoing. If the user types a prefix -key (such as @kbd{C-x}) and then delays this many seconds before -continuing, the prefix key is echoed in the echo area. (Once echoing -begins in a key sequence, all subsequent characters in the same key -sequence are echoed immediately.) - -If the value is zero, then command input is not echoed. -@end defvar - -@defvar message-truncate-lines -Normally, displaying a long message resizes the echo area to display -the entire message. But if the variable @code{message-truncate-lines} -is non-@code{nil}, the echo area does not resize, and the message is -truncated to fit it, as in Emacs 20 and before. -@end defvar - - The variable @code{max-mini-window-height}, which specifies the -maximum height for resizing minibuffer windows, also applies to the -echo area (which is really a special use of the minibuffer window. -@xref{Minibuffer Misc}. - -@node Warnings -@section Reporting Warnings -@cindex warnings - - @dfn{Warnings} are a facility for a program to inform the user of a -possible problem, but continue running. - -@menu -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize their warnings. -* Warning Options:: Variables users set to control display of warnings. -@end menu - -@node Warning Basics -@subsection Warning Basics -@cindex severity level - - Every warning has a textual message, which explains the problem for -the user, and a @dfn{severity level} which is a symbol. Here are the -possible severity levels, in order of decreasing severity, and their -meanings: - -@table @code -@item :emergency -A problem that will seriously impair Emacs operation soon -if you do not attend to it promptly. -@item :error -A report of data or circumstances that are inherently wrong. -@item :warning -A report of data or circumstances that are not inherently wrong, but -raise suspicion of a possible problem. -@item :debug -A report of information that may be useful if you are debugging. -@end table - - When your program encounters invalid input data, it can either -signal a Lisp error by calling @code{error} or @code{signal} or report -a warning with severity @code{:error}. Signaling a Lisp error is the -easiest thing to do, but it means the program cannot continue -processing. If you want to take the trouble to implement a way to -continue processing despite the bad data, then reporting a warning of -severity @code{:error} is the right way to inform the user of the -problem. For instance, the Emacs Lisp byte compiler can report an -error that way and continue compiling other functions. (If the -program signals a Lisp error and then handles it with -@code{condition-case}, the user won't see the error message; it could -show the message to the user by reporting it as a warning.) - -@cindex warning type - Each warning has a @dfn{warning type} to classify it. The type is a -list of symbols. The first symbol should be the custom group that you -use for the program's user options. For example, byte compiler -warnings use the warning type @code{(bytecomp)}. You can also -subcategorize the warnings, if you wish, by using more symbols in the -list. - -@defun display-warning type message &optional level buffer-name -This function reports a warning, using @var{message} as the message -and @var{type} as the warning type. @var{level} should be the -severity level, with @code{:warning} being the default. - -@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer -for logging the warning. By default, it is @samp{*Warnings*}. -@end defun - -@defun lwarn type level message &rest args -This function reports a warning using the value of @code{(format -@var{message} @var{args}...)} as the message. In other respects it is -equivalent to @code{display-warning}. -@end defun - -@defun warn message &rest args -This function reports a warning using the value of @code{(format -@var{message} @var{args}...)} as the message, @code{(emacs)} as the -type, and @code{:warning} as the severity level. It exists for -compatibility only; we recommend not using it, because you should -specify a specific warning type. -@end defun - -@node Warning Variables -@subsection Warning Variables - - Programs can customize how their warnings appear by binding -the variables described in this section. - -@defvar warning-levels -This list defines the meaning and severity order of the warning -severity levels. Each element defines one severity level, -and they are arranged in order of decreasing severity. - -Each element has the form @code{(@var{level} @var{string} -@var{function})}, where @var{level} is the severity level it defines. -@var{string} specifies the textual description of this level. -@var{string} should use @samp{%s} to specify where to put the warning -type information, or it can omit the @samp{%s} so as not to include -that information. - -The optional @var{function}, if non-@code{nil}, is a function to call -with no arguments, to get the user's attention. - -Normally you should not change the value of this variable. -@end defvar - -@defvar warning-prefix-function -If non-@code{nil}, the value is a function to generate prefix text for -warnings. Programs can bind the variable to a suitable function. -@code{display-warning} calls this function with the warnings buffer -current, and the function can insert text in it. That text becomes -the beginning of the warning message. - -The function is called with two arguments, the severity level and its -entry in @code{warning-levels}. It should return a list to use as the -entry (this value need not be an actual member of -@code{warning-levels}). By constructing this value, the function can -change the severity of the warning, or specify different handling for -a given severity level. - -If the variable's value is @code{nil} then there is no function -to call. -@end defvar - -@defvar warning-series -Programs can bind this variable to @code{t} to say that the next -warning should begin a series. When several warnings form a series, -that means to leave point on the first warning of the series, rather -than keep moving it for each warning so that it appears on the last one. -The series ends when the local binding is unbound and -@code{warning-series} becomes @code{nil} again. - -The value can also be a symbol with a function definition. That is -equivalent to @code{t}, except that the next warning will also call -the function with no arguments with the warnings buffer current. The -function can insert text which will serve as a header for the series -of warnings. - -Once a series has begun, the value is a marker which points to the -buffer position in the warnings buffer of the start of the series. - -The variable's normal value is @code{nil}, which means to handle -each warning separately. -@end defvar - -@defvar warning-fill-prefix -When this variable is non-@code{nil}, it specifies a fill prefix to -use for filling each warning's text. -@end defvar - -@defvar warning-type-format -This variable specifies the format for displaying the warning type -in the warning message. The result of formatting the type this way -gets included in the message under the control of the string in the -entry in @code{warning-levels}. The default value is @code{" (%s)"}. -If you bind it to @code{""} then the warning type won't appear at -all. -@end defvar - -@node Warning Options -@subsection Warning Options - - These variables are used by users to control what happens -when a Lisp program reports a warning. - -@defopt warning-minimum-level -This user option specifies the minimum severity level that should be -shown immediately to the user. The default is @code{:warning}, which -means to immediately display all warnings except @code{:debug} -warnings. -@end defopt - -@defopt warning-minimum-log-level -This user option specifies the minimum severity level that should be -logged in the warnings buffer. The default is @code{:warning}, which -means to log all warnings except @code{:debug} warnings. -@end defopt - -@defopt warning-suppress-types -This list specifies which warning types should not be displayed -immediately for the user. Each element of the list should be a list -of symbols. If its elements match the first elements in a warning -type, then that warning is not displayed immediately. -@end defopt - -@defopt warning-suppress-log-types -This list specifies which warning types should not be logged in the -warnings buffer. Each element of the list should be a list of -symbols. If it matches the first few elements in a warning type, then -that warning is not logged. -@end defopt - -@node Invisible Text -@section Invisible Text - -@cindex invisible text -You can make characters @dfn{invisible}, so that they do not appear on -the screen, with the @code{invisible} property. This can be either a -text property (@pxref{Text Properties}) or a property of an overlay -(@pxref{Overlays}). Cursor motion also partly ignores these -characters; if the command loop finds point within them, it moves -point to the other side of them. - -In the simplest case, any non-@code{nil} @code{invisible} property makes -a character invisible. This is the default case---if you don't alter -the default value of @code{buffer-invisibility-spec}, this is how the -@code{invisible} property works. You should normally use @code{t} -as the value of the @code{invisible} property if you don't plan -to set @code{buffer-invisibility-spec} yourself. - -More generally, you can use the variable @code{buffer-invisibility-spec} -to control which values of the @code{invisible} property make text -invisible. This permits you to classify the text into different subsets -in advance, by giving them different @code{invisible} values, and -subsequently make various subsets visible or invisible by changing the -value of @code{buffer-invisibility-spec}. - -Controlling visibility with @code{buffer-invisibility-spec} is -especially useful in a program to display the list of entries in a -database. It permits the implementation of convenient filtering -commands to view just a part of the entries in the database. Setting -this variable is very fast, much faster than scanning all the text in -the buffer looking for properties to change. - -@defvar buffer-invisibility-spec -This variable specifies which kinds of @code{invisible} properties -actually make a character invisible. Setting this variable makes it -buffer-local. - -@table @asis -@item @code{t} -A character is invisible if its @code{invisible} property is -non-@code{nil}. This is the default. - -@item a list -Each element of the list specifies a criterion for invisibility; if a -character's @code{invisible} property fits any one of these criteria, -the character is invisible. The list can have two kinds of elements: - -@table @code -@item @var{atom} -A character is invisible if its @code{invisible} property value -is @var{atom} or if it is a list with @var{atom} as a member. - -@item (@var{atom} . t) -A character is invisible if its @code{invisible} property value is -@var{atom} or if it is a list with @var{atom} as a member. Moreover, -a sequence of such characters displays as an ellipsis. -@end table -@end table -@end defvar - - Two functions are specifically provided for adding elements to -@code{buffer-invisibility-spec} and removing elements from it. - -@defun add-to-invisibility-spec element -This function adds the element @var{element} to -@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec} -was @code{t}, it changes to a list, @code{(t)}, so that text whose -@code{invisible} property is @code{t} remains invisible. -@end defun - -@defun remove-from-invisibility-spec element -This removes the element @var{element} from -@code{buffer-invisibility-spec}. This does nothing if @var{element} -is not in the list. -@end defun - - A convention for use of @code{buffer-invisibility-spec} is that a -major mode should use the mode's own name as an element of -@code{buffer-invisibility-spec} and as the value of the -@code{invisible} property: - -@example -;; @r{If you want to display an ellipsis:} -(add-to-invisibility-spec '(my-symbol . t)) -;; @r{If you don't want ellipsis:} -(add-to-invisibility-spec 'my-symbol) - -(overlay-put (make-overlay beginning end) - 'invisible 'my-symbol) - -;; @r{When done with the overlays:} -(remove-from-invisibility-spec '(my-symbol . t)) -;; @r{Or respectively:} -(remove-from-invisibility-spec 'my-symbol) -@end example - -@vindex line-move-ignore-invisible - Ordinarily, functions that operate on text or move point do not care -whether the text is invisible. The user-level line motion commands -explicitly ignore invisible newlines if -@code{line-move-ignore-invisible} is non-@code{nil} (the default), but -only because they are explicitly programmed to do so. - - However, if a command ends with point inside or immediately before -invisible text, the main editing loop moves point further forward or -further backward (in the same direction that the command already moved -it) until that condition is no longer true. Thus, if the command -moved point back into an invisible range, Emacs moves point back to -the beginning of that range, and then back one more character. If the -command moved point forward into an invisible range, Emacs moves point -forward up to the first visible character that follows the invisible -text. - - Incremental search can make invisible overlays visible temporarily -and/or permanently when a match includes invisible text. To enable -this, the overlay should have a non-@code{nil} -@code{isearch-open-invisible} property. The property value should be a -function to be called with the overlay as an argument. This function -should make the overlay visible permanently; it is used when the match -overlaps the overlay on exit from the search. - - During the search, such overlays are made temporarily visible by -temporarily modifying their invisible and intangible properties. If you -want this to be done differently for a certain overlay, give it an -@code{isearch-open-invisible-temporary} property which is a function. -The function is called with two arguments: the first is the overlay, and -the second is @code{nil} to make the overlay visible, or @code{t} to -make it invisible again. - -@node Selective Display -@section Selective Display -@c @cindex selective display Duplicates selective-display - - @dfn{Selective display} refers to a pair of related features for -hiding certain lines on the screen. - - The first variant, explicit selective display, is designed for use -in a Lisp program: it controls which lines are hidden by altering the -text. This kind of hiding in some ways resembles the effect of the -@code{invisible} property (@pxref{Invisible Text}), but the two -features are different and do not work the same way. - - In the second variant, the choice of lines to hide is made -automatically based on indentation. This variant is designed to be a -user-level feature. - - The way you control explicit selective display is by replacing a -newline (control-j) with a carriage return (control-m). The text that -was formerly a line following that newline is now hidden. Strictly -speaking, it is temporarily no longer a line at all, since only -newlines can separate lines; it is now part of the previous line. - - Selective display does not directly affect editing commands. For -example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly -into hidden text. However, the replacement of newline characters with -carriage return characters affects some editing commands. For -example, @code{next-line} skips hidden lines, since it searches only -for newlines. Modes that use selective display can also define -commands that take account of the newlines, or that control which -parts of the text are hidden. - - When you write a selectively displayed buffer into a file, all the -control-m's are output as newlines. This means that when you next read -in the file, it looks OK, with nothing hidden. The selective display -effect is seen only within Emacs. - -@defvar selective-display -This buffer-local variable enables selective display. This means that -lines, or portions of lines, may be made hidden. - -@itemize @bullet -@item -If the value of @code{selective-display} is @code{t}, then the character -control-m marks the start of hidden text; the control-m, and the rest -of the line following it, are not displayed. This is explicit selective -display. - -@item -If the value of @code{selective-display} is a positive integer, then -lines that start with more than that many columns of indentation are not -displayed. -@end itemize - -When some portion of a buffer is hidden, the vertical movement -commands operate as if that portion did not exist, allowing a single -@code{next-line} command to skip any number of hidden lines. -However, character movement commands (such as @code{forward-char}) do -not skip the hidden portion, and it is possible (if tricky) to insert -or delete text in an hidden portion. - -In the examples below, we show the @emph{display appearance} of the -buffer @code{foo}, which changes with the value of -@code{selective-display}. The @emph{contents} of the buffer do not -change. - -@example -@group -(setq selective-display nil) - @result{} nil - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 3n this column - 3n this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group - -@group -(setq selective-display 2) - @result{} 2 - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example -@end defvar - -@defvar selective-display-ellipses -If this buffer-local variable is non-@code{nil}, then Emacs displays -@samp{@dots{}} at the end of a line that is followed by hidden text. -This example is a continuation of the previous one. - -@example -@group -(setq selective-display-ellipses t) - @result{} t - ----------- Buffer: foo ---------- -1 on this column - 2on this column ... - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example - -You can use a display table to substitute other text for the ellipsis -(@samp{@dots{}}). @xref{Display Tables}. -@end defvar - -@node Temporary Displays -@section Temporary Displays - - Temporary displays are used by Lisp programs to put output into a -buffer and then present it to the user for perusal rather than for -editing. Many help commands use this feature. - -@defspec with-output-to-temp-buffer buffer-name forms@dots{} -This function executes @var{forms} while arranging to insert any output -they print into the buffer named @var{buffer-name}, which is first -created if necessary, and put into Help mode. Finally, the buffer is -displayed in some window, but not selected. - -If the @var{forms} do not change the major mode in the output buffer, -so that it is still Help mode at the end of their execution, then -@code{with-output-to-temp-buffer} makes this buffer read-only at the -end, and also scans it for function and variable names to make them -into clickable cross-references. @xref{Docstring hyperlinks, , Tips -for Documentation Strings}, in particular the item on hyperlinks in -documentation strings, for more details. - -The string @var{buffer-name} specifies the temporary buffer, which -need not already exist. The argument must be a string, not a buffer. -The buffer is erased initially (with no questions asked), and it is -marked as unmodified after @code{with-output-to-temp-buffer} exits. - -@code{with-output-to-temp-buffer} binds @code{standard-output} to the -temporary buffer, then it evaluates the forms in @var{forms}. Output -using the Lisp output functions within @var{forms} goes by default to -that buffer (but screen display and messages in the echo area, although -they are ``output'' in the general sense of the word, are not affected). -@xref{Output Functions}. - -Several hooks are available for customizing the behavior -of this construct; they are listed below. - -The value of the last form in @var{forms} is returned. - -@example -@group ----------- Buffer: foo ---------- - This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(with-output-to-temp-buffer "foo" - (print 20) - (print standard-output)) -@result{} #<buffer foo> - ----------- Buffer: foo ---------- -20 - -#<buffer foo> - ----------- Buffer: foo ---------- -@end group -@end example -@end defspec - -@defvar temp-buffer-show-function -If this variable is non-@code{nil}, @code{with-output-to-temp-buffer} -calls it as a function to do the job of displaying a help buffer. The -function gets one argument, which is the buffer it should display. - -It is a good idea for this function to run @code{temp-buffer-show-hook} -just as @code{with-output-to-temp-buffer} normally would, inside of -@code{save-selected-window} and with the chosen window and buffer -selected. -@end defvar - -@defvar temp-buffer-setup-hook -This normal hook is run by @code{with-output-to-temp-buffer} before -evaluating @var{body}. When the hook runs, the temporary buffer is -current. This hook is normally set up with a function to put the -buffer in Help mode. -@end defvar - -@defvar temp-buffer-show-hook -This normal hook is run by @code{with-output-to-temp-buffer} after -displaying the temporary buffer. When the hook runs, the temporary buffer -is current, and the window it was displayed in is selected. This hook -is normally set up with a function to make the buffer read only, and -find function names and variable names in it, provided the major mode -is Help mode. -@end defvar - -@defun momentary-string-display string position &optional char message -This function momentarily displays @var{string} in the current buffer at -@var{position}. It has no effect on the undo list or on the buffer's -modification status. - -The momentary display remains until the next input event. If the next -input event is @var{char}, @code{momentary-string-display} ignores it -and returns. Otherwise, that event remains buffered for subsequent use -as input. Thus, typing @var{char} will simply remove the string from -the display, while typing (say) @kbd{C-f} will remove the string from -the display and later (presumably) move point forward. The argument -@var{char} is a space by default. - -The return value of @code{momentary-string-display} is not meaningful. - -If the string @var{string} does not contain control characters, you can -do the same job in a more general way by creating (and then subsequently -deleting) an overlay with a @code{before-string} property. -@xref{Overlay Properties}. - -If @var{message} is non-@code{nil}, it is displayed in the echo area -while @var{string} is displayed in the buffer. If it is @code{nil}, a -default message says to type @var{char} to continue. - -In this example, point is initially located at the beginning of the -second line: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo. -@point{}Second line. ----------- Buffer: foo ---------- -@end group - -@group -(momentary-string-display - "**** Important Message! ****" - (point) ?\r - "Type RET when done reading") -@result{} t -@end group - -@group ----------- Buffer: foo ---------- -This is the contents of foo. -**** Important Message! ****Second line. ----------- Buffer: foo ---------- - ----------- Echo Area ---------- -Type RET when done reading ----------- Echo Area ---------- -@end group -@end example -@end defun - -@node Overlays -@section Overlays -@cindex overlays - -You can use @dfn{overlays} to alter the appearance of a buffer's text on -the screen, for the sake of presentation features. An overlay is an -object that belongs to a particular buffer, and has a specified -beginning and end. It also has properties that you can examine and set; -these affect the display of the text within the overlay. - -An overlay uses markers to record its beginning and end; thus, -editing the text of the buffer adjusts the beginning and end of each -overlay so that it stays with the text. When you create the overlay, -you can specify whether text inserted at the beginning should be -inside the overlay or outside, and likewise for the end of the overlay. - -@menu -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. -@end menu - -@node Managing Overlays -@subsection Managing Overlays - - This section describes the functions to create, delete and move -overlays, and to examine their contents. Overlay changes are not -recorded in the buffer's undo list, since the overlays are not -part of the buffer's contents. - -@defun overlayp object -This function returns @code{t} if @var{object} is an overlay. -@end defun - -@defun make-overlay start end &optional buffer front-advance rear-advance -This function creates and returns an overlay that belongs to -@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} -and @var{end} must specify buffer positions; they may be integers or -markers. If @var{buffer} is omitted, the overlay is created in the -current buffer. - -The arguments @var{front-advance} and @var{rear-advance} specify the -marker insertion type for the start of the overlay and for the end of -the overlay, respectively. @xref{Marker Insertion Types}. If they -are both @code{nil}, the default, then the overlay extends to include -any text inserted at the beginning, but not text inserted at the end. -If @var{front-advance} is non-@code{nil}, text inserted at the -beginning of the overlay is excluded from the overlay. If -@var{rear-advance} is non-@code{nil}, text inserted at the end of the -overlay is included in the overlay. -@end defun - -@defun overlay-start overlay -This function returns the position at which @var{overlay} starts, -as an integer. -@end defun - -@defun overlay-end overlay -This function returns the position at which @var{overlay} ends, -as an integer. -@end defun - -@defun overlay-buffer overlay -This function returns the buffer that @var{overlay} belongs to. It -returns @code{nil} if @var{overlay} has been deleted. -@end defun - -@defun delete-overlay overlay -This function deletes @var{overlay}. The overlay continues to exist as -a Lisp object, and its property list is unchanged, but it ceases to be -attached to the buffer it belonged to, and ceases to have any effect on -display. - -A deleted overlay is not permanently disconnected. You can give it a -position in a buffer again by calling @code{move-overlay}. -@end defun - -@defun move-overlay overlay start end &optional buffer -This function moves @var{overlay} to @var{buffer}, and places its bounds -at @var{start} and @var{end}. Both arguments @var{start} and @var{end} -must specify buffer positions; they may be integers or markers. - -If @var{buffer} is omitted, @var{overlay} stays in the same buffer it -was already associated with; if @var{overlay} was deleted, it goes into -the current buffer. - -The return value is @var{overlay}. - -This is the only valid way to change the endpoints of an overlay. Do -not try modifying the markers in the overlay by hand, as that fails to -update other vital data structures and can cause some overlays to be -``lost.'' -@end defun - -@defun remove-overlays &optional start end name value -This function removes all the overlays between @var{start} and -@var{end} whose property @var{name} has the value @var{value}. It can -move the endpoints of the overlays in the region, or split them. - -If @var{name} is omitted or @code{nil}, it means to delete all overlays in -the specified region. If @var{start} and/or @var{end} are omitted or -@code{nil}, that means the beginning and end of the buffer respectively. -Therefore, @code{(remove-overlays)} removes all the overlays in the -current buffer. -@end defun - - Here are some examples: - -@example -;; @r{Create an overlay.} -(setq foo (make-overlay 1 10)) - @result{} #<overlay from 1 to 10 in display.texi> -(overlay-start foo) - @result{} 1 -(overlay-end foo) - @result{} 10 -(overlay-buffer foo) - @result{} #<buffer display.texi> -;; @r{Give it a property we can check later.} -(overlay-put foo 'happy t) - @result{} t -;; @r{Verify the property is present.} -(overlay-get foo 'happy) - @result{} t -;; @r{Move the overlay.} -(move-overlay foo 5 20) - @result{} #<overlay from 5 to 20 in display.texi> -(overlay-start foo) - @result{} 5 -(overlay-end foo) - @result{} 20 -;; @r{Delete the overlay.} -(delete-overlay foo) - @result{} nil -;; @r{Verify it is deleted.} -foo - @result{} #<overlay in no buffer> -;; @r{A deleted overlay has no position.} -(overlay-start foo) - @result{} nil -(overlay-end foo) - @result{} nil -(overlay-buffer foo) - @result{} nil -;; @r{Undelete the overlay.} -(move-overlay foo 1 20) - @result{} #<overlay from 1 to 20 in display.texi> -;; @r{Verify the results.} -(overlay-start foo) - @result{} 1 -(overlay-end foo) - @result{} 20 -(overlay-buffer foo) - @result{} #<buffer display.texi> -;; @r{Moving and deleting the overlay does not change its properties.} -(overlay-get foo 'happy) - @result{} t -@end example - - Emacs stores the overlays of each buffer in two lists, divided -around an arbitrary ``center position.'' One list extends backwards -through the buffer from that center position, and the other extends -forwards from that center position. The center position can be anywhere -in the buffer. - -@defun overlay-recenter pos -This function recenters the overlays of the current buffer around -position @var{pos}. That makes overlay lookup faster for positions -near @var{pos}, but slower for positions far away from @var{pos}. -@end defun - - A loop that scans the buffer forwards, creating overlays, can run -faster if you do @code{(overlay-recenter (point-max))} first. - -@node Overlay Properties -@subsection Overlay Properties - - Overlay properties are like text properties in that the properties that -alter how a character is displayed can come from either source. But in -most respects they are different. @xref{Text Properties}, for comparison. - - Text properties are considered a part of the text; overlays and -their properties are specifically considered not to be part of the -text. Thus, copying text between various buffers and strings -preserves text properties, but does not try to preserve overlays. -Changing a buffer's text properties marks the buffer as modified, -while moving an overlay or changing its properties does not. Unlike -text property changes, overlay property changes are not recorded in -the buffer's undo list. - - These functions read and set the properties of an overlay: - -@defun overlay-get overlay prop -This function returns the value of property @var{prop} recorded in -@var{overlay}, if any. If @var{overlay} does not record any value for -that property, but it does have a @code{category} property which is a -symbol, that symbol's @var{prop} property is used. Otherwise, the value -is @code{nil}. -@end defun - -@defun overlay-put overlay prop value -This function sets the value of property @var{prop} recorded in -@var{overlay} to @var{value}. It returns @var{value}. -@end defun - -@defun overlay-properties overlay -This returns a copy of the property list of @var{overlay}. -@end defun - - See also the function @code{get-char-property} which checks both -overlay properties and text properties for a given character. -@xref{Examining Properties}. - - Many overlay properties have special meanings; here is a table -of them: - -@table @code -@item priority -@kindex priority @r{(overlay property)} -This property's value (which should be a nonnegative integer number) -determines the priority of the overlay. The priority matters when two -or more overlays cover the same character and both specify the same -property; the one whose @code{priority} value is larger takes priority -over the other. For the @code{face} property, the higher priority -value does not completely replace the other; instead, its face -attributes override the face attributes of the lower priority -@code{face} property. - -Currently, all overlays take priority over text properties. Please -avoid using negative priority values, as we have not yet decided just -what they should mean. - -@item window -@kindex window @r{(overlay property)} -If the @code{window} property is non-@code{nil}, then the overlay -applies only on that window. - -@item category -@kindex category @r{(overlay property)} -If an overlay has a @code{category} property, we call it the -@dfn{category} of the overlay. It should be a symbol. The properties -of the symbol serve as defaults for the properties of the overlay. - -@item face -@kindex face @r{(overlay property)} -This property controls the way text is displayed---for example, which -font and which colors. @xref{Faces}, for more information. - -In the simplest case, the value is a face name. It can also be a list; -then each element can be any of these possibilities: - -@itemize @bullet -@item -A face name (a symbol or string). - -@item -A property list of face attributes. This has the form (@var{keyword} -@var{value} @dots{}), where each @var{keyword} is a face attribute -name and @var{value} is a meaningful value for that attribute. With -this feature, you do not need to create a face each time you want to -specify a particular attribute for certain text. @xref{Face -Attributes}. - -@item -A cons cell, either of the form @code{(foreground-color . @var{color-name})} or -@code{(background-color . @var{color-name})}. These elements specify -just the foreground color or just the background color. - -@code{(foreground-color . @var{color-name})} has the same effect as -@code{(:foreground @var{color-name})}; likewise for the background. -@end itemize - -@item mouse-face -@kindex mouse-face @r{(overlay property)} -This property is used instead of @code{face} when the mouse is within -the range of the overlay. - -@item display -@kindex display @r{(overlay property)} -This property activates various features that change the -way text is displayed. For example, it can make text appear taller -or shorter, higher or lower, wider or narrower, or replaced with an image. -@xref{Display Property}. - -@item help-echo -@kindex help-echo @r{(overlay property)} -If an overlay has a @code{help-echo} property, then when you move the -mouse onto the text in the overlay, Emacs displays a help string in the -echo area, or in the tooltip window. For details see @ref{Text -help-echo}. - -@item modification-hooks -@kindex modification-hooks @r{(overlay property)} -This property's value is a list of functions to be called if any -character within the overlay is changed or if text is inserted strictly -within the overlay. - -The hook functions are called both before and after each change. -If the functions save the information they receive, and compare notes -between calls, they can determine exactly what change has been made -in the buffer text. - -When called before a change, each function receives four arguments: the -overlay, @code{nil}, and the beginning and end of the text range to be -modified. - -When called after a change, each function receives five arguments: the -overlay, @code{t}, the beginning and end of the text range just -modified, and the length of the pre-change text replaced by that range. -(For an insertion, the pre-change length is zero; for a deletion, that -length is the number of characters deleted, and the post-change -beginning and end are equal.) - -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. - -Text properties also support the @code{modification-hooks} property, -but the details are somewhat different (@pxref{Special Properties}). - -@item insert-in-front-hooks -@kindex insert-in-front-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the beginning of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item insert-behind-hooks -@kindex insert-behind-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the end of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item invisible -@kindex invisible @r{(overlay property)} -The @code{invisible} property can make the text in the overlay -invisible, which means that it does not appear on the screen. -@xref{Invisible Text}, for details. - -@item intangible -@kindex intangible @r{(overlay property)} -The @code{intangible} property on an overlay works just like the -@code{intangible} text property. @xref{Special Properties}, for details. - -@item isearch-open-invisible -This property tells incremental search how to make an invisible overlay -visible, permanently, if the final match overlaps it. @xref{Invisible -Text}. - -@item isearch-open-invisible-temporary -This property tells incremental search how to make an invisible overlay -visible, temporarily, during the search. @xref{Invisible Text}. - -@item before-string -@kindex before-string @r{(overlay property)} -This property's value is a string to add to the display at the beginning -of the overlay. The string does not appear in the buffer in any -sense---only on the screen. - -@item after-string -@kindex after-string @r{(overlay property)} -This property's value is a string to add to the display at the end of -the overlay. The string does not appear in the buffer in any -sense---only on the screen. - -@item evaporate -@kindex evaporate @r{(overlay property)} -If this property is non-@code{nil}, the overlay is deleted automatically -if it becomes empty (i.e., if its length becomes zero). If you give -an empty overlay a non-@code{nil} @code{evaporate} property, that deletes -it immediately. - -@item local-map -@cindex keymap of character (and overlays) -@kindex local-map @r{(overlay property)} -If this property is non-@code{nil}, it specifies a keymap for a portion -of the text. The property's value replaces the buffer's local map, when -the character after point is within the overlay. @xref{Active Keymaps}. - -@item keymap -@kindex keymap @r{(overlay property)} -The @code{keymap} property is similar to @code{local-map} but overrides the -buffer's local map (and the map specified by the @code{local-map} -property) rather than replacing it. -@end table - -@node Finding Overlays -@subsection Searching for Overlays - -@defun overlays-at pos -This function returns a list of all the overlays that cover the -character at position @var{pos} in the current buffer. The list is in -no particular order. An overlay contains position @var{pos} if it -begins at or before @var{pos}, and ends after @var{pos}. - -To illustrate usage, here is a Lisp function that returns a list of the -overlays that specify property @var{prop} for the character at point: - -@smallexample -(defun find-overlays-specifying (prop) - (let ((overlays (overlays-at (point))) - found) - (while overlays - (let ((overlay (car overlays))) - (if (overlay-get overlay prop) - (setq found (cons overlay found)))) - (setq overlays (cdr overlays))) - found)) -@end smallexample -@end defun - -@defun overlays-in beg end -This function returns a list of the overlays that overlap the region -@var{beg} through @var{end}. ``Overlap'' means that at least one -character is contained within the overlay and also contained within the -specified region; however, empty overlays are included in the result if -they are located at @var{beg}, or strictly between @var{beg} and @var{end}. -@end defun - -@defun next-overlay-change pos -This function returns the buffer position of the next beginning or end -of an overlay, after @var{pos}. If there is none, it returns -@code{(point-max)}. -@end defun - -@defun previous-overlay-change pos -This function returns the buffer position of the previous beginning or -end of an overlay, before @var{pos}. If there is none, it returns -@code{(point-min)}. -@end defun - - As an example, here's a simplified (and inefficient) version of the -primitive function @code{next-single-char-property-change} -(@pxref{Property Search}). It searches forward from position -@var{pos} for the next position where the value of a given property -@code{prop}, as obtained from either overlays or text properties, -changes. - -@smallexample -(defun next-single-char-property-change (position prop) - (save-excursion - (goto-char position) - (let ((propval (get-char-property (point) prop))) - (while (and (not (eobp)) - (eq (get-char-property (point) prop) propval)) - (goto-char (min (next-overlay-change (point)) - (next-single-property-change (point) prop))))) - (point))) -@end smallexample - -@node Width -@section Width - -Since not all characters have the same width, these functions let you -check the width of a character. @xref{Primitive Indent}, and -@ref{Screen Lines}, for related functions. - -@defun char-width char -This function returns the width in columns of the character @var{char}, -if it were displayed in the current buffer and the selected window. -@end defun - -@defun string-width string -This function returns the width in columns of the string @var{string}, -if it were displayed in the current buffer and the selected window. -@end defun - -@defun truncate-string-to-width string width &optional start-column padding ellipsis -This function returns the part of @var{string} that fits within -@var{width} columns, as a new string. - -If @var{string} does not reach @var{width}, then the result ends where -@var{string} ends. If one multi-column character in @var{string} -extends across the column @var{width}, that character is not included in -the result. Thus, the result can fall short of @var{width} but cannot -go beyond it. - -The optional argument @var{start-column} specifies the starting column. -If this is non-@code{nil}, then the first @var{start-column} columns of -the string are omitted from the value. If one multi-column character in -@var{string} extends across the column @var{start-column}, that -character is not included. - -The optional argument @var{padding}, if non-@code{nil}, is a padding -character added at the beginning and end of the result string, to extend -it to exactly @var{width} columns. The padding character is used at the -end of the result if it falls short of @var{width}. It is also used at -the beginning of the result if one multi-column character in -@var{string} extends across the column @var{start-column}. - -If @var{ellipsis} is non-@code{nil}, it should be a string which will -replace the end of @var{str} (including any padding) if it extends -beyond @var{end-column}, unless the display width of @var{str} is -equal to or less than the display width of @var{ellipsis}. If -@var{ellipsis} is non-@code{nil} and not a string, it stands for -@code{"..."}. - -@example -(truncate-string-to-width "\tab\t" 12 4) - @result{} "ab" -(truncate-string-to-width "\tab\t" 12 4 ?\s) - @result{} " ab " -@end example -@end defun - -@node Line Height -@section Line Height -@cindex line height - - The total height of each display line consists of the height of the -contents of the line, plus optional additional vertical line spacing -above or below the display line. - - The height of the line contents is the maximum height of any -character or image on that display line, including the final newline -if there is one. (A display line that is continued doesn't include a -final newline.) That is the default line height, if you do nothing to -specify a greater height. (In the most common case, this equals the -height of the default frame font.) - - There are several ways to explicitly specify a larger line height, -either by specifying an absolute height for the display line, or by -specifying vertical space. However, no matter what you specify, the -actual line height can never be less than the default. - -@kindex line-height @r{(text property)} - A newline can have a @code{line-height} text or overlay property -that controls the total height of the display line ending in that -newline. - - If the property value is @code{t}, the newline character has no -effect on the displayed height of the line---the visible contents -alone determine the height. This is useful for tiling small images -(or image slices) without adding blank areas between the images. - - If the property value is a list of the form @code{(@var{height} -@var{total})}, that adds extra space @emph{below} the display line. -First Emacs uses @var{height} as a height spec to control extra space -@emph{above} the line; then it adds enough space @emph{below} the line -to bring the total line height up to @var{total}. In this case, the -other ways to specify the line spacing are ignored. - - Any other kind of property value is a height spec, which translates -into a number---the specified line height. There are several ways to -write a height spec; here's how each of them translates into a number: - -@table @code -@item @var{integer} -If the height spec is a positive integer, the height value is that integer. -@item @var{float} -If the height spec is a float, @var{float}, the numeric height value -is @var{float} times the frame's default line height. -@item (@var{face} . @var{ratio}) -If the height spec is a cons of the format shown, the numeric height -is @var{ratio} times the height of face @var{face}. @var{ratio} can -be any type of number, or @code{nil} which means a ratio of 1. -If @var{face} is @code{t}, it refers to the current face. -@item (nil . @var{ratio}) -If the height spec is a cons of the format shown, the numeric height -is @var{ratio} times the height of the contents of the line. -@end table - - Thus, any valid height spec determines the height in pixels, one way -or another. If the line contents' height is less than that, Emacs -adds extra vertical space above the line to achieve the specified -total height. - - If you don't specify the @code{line-height} property, the line's -height consists of the contents' height plus the line spacing. -There are several ways to specify the line spacing for different -parts of Emacs text. - -@vindex default-line-spacing - You can specify the line spacing for all lines in a frame with the -@code{line-spacing} frame parameter (@pxref{Layout Parameters}). -However, if the variable @code{default-line-spacing} is -non-@code{nil}, it overrides the frame's @code{line-spacing} -parameter. An integer value specifies the number of pixels put below -lines on graphical displays. A floating point number specifies the -spacing relative to the frame's default line height. - -@vindex line-spacing - You can specify the line spacing for all lines in a buffer via the -buffer-local @code{line-spacing} variable. An integer value specifies -the number of pixels put below lines on graphical displays. A floating -point number specifies the spacing relative to the default frame line -height. This overrides line spacings specified for the frame. - -@kindex line-spacing @r{(text property)} - Finally, a newline can have a @code{line-spacing} text or overlay -property that overrides the default frame line spacing and the buffer -local @code{line-spacing} variable, for the display line ending in -that newline. - - One way or another, these mechanisms specify a Lisp value for the -spacing of each line. The value is a height spec, and it translates -into a Lisp value as described above. However, in this case the -numeric height value specifies the line spacing, rather than the line -height. - -@node Faces -@section Faces -@cindex faces - - A @dfn{face} is a named collection of graphical attributes: font -family, foreground color, background color, optional underlining, and -many others. Faces are used in Emacs to control the style of display of -particular parts of the text or the frame. @xref{Standard Faces,,, -emacs, The GNU Emacs Manual}, for the list of faces Emacs normally -comes with. - -@cindex face id -Each face has its own @dfn{face number}, which distinguishes faces at -low levels within Emacs. However, for most purposes, you refer to -faces in Lisp programs by the symbols that name them. - -@defun facep object -This function returns @code{t} if @var{object} is a face name string -or symbol (or if it is a vector of the kind used internally to record -face data). It returns @code{nil} otherwise. -@end defun - -Each face name is meaningful for all frames, and by default it has the -same meaning in all frames. But you can arrange to give a particular -face name a special meaning in one frame if you wish. - -@menu -* Defining Faces:: How to define a face with @code{defface}. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for a character. -* Font Selection:: Finding the best available font for a face. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -@end menu - -@node Defining Faces -@subsection Defining Faces - - The way to define a new face is with @code{defface}. This creates a -kind of customization item (@pxref{Customization}) which the user can -customize using the Customization buffer (@pxref{Easy Customization,,, -emacs, The GNU Emacs Manual}). - -@defmac defface face spec doc [keyword value]@dots{} -This declares @var{face} as a customizable face that defaults -according to @var{spec}. You should not quote the symbol @var{face}, -and it should not end in @samp{-face} (that would be redundant). The -argument @var{doc} specifies the face documentation. The keywords you -can use in @code{defface} are the same as in @code{defgroup} and -@code{defcustom} (@pxref{Common Keywords}). - -When @code{defface} executes, it defines the face according to -@var{spec}, then uses any customizations that were read from the -init file (@pxref{Init File}) to override that specification. - -When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs -Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} -overrides any customizations of the face. This way, the face reflects -exactly what the @code{defface} says. - -The purpose of @var{spec} is to specify how the face should appear on -different kinds of terminals. It should be an alist whose elements -have the form @code{(@var{display} @var{atts})}. Each element's -@sc{car}, @var{display}, specifies a class of terminals. (The first -element, if its @sc{car} is @code{default}, is special---it specifies -defaults for the remaining elements). The element's @sc{cadr}, -@var{atts}, is a list of face attributes and their values; it -specifies what the face should look like on that kind of terminal. -The possible attributes are defined in the value of -@code{custom-face-attributes}. - -The @var{display} part of an element of @var{spec} determines which -frames the element matches. If more than one element of @var{spec} -matches a given frame, the first element that matches is the one used -for that frame. There are three possibilities for @var{display}: - -@table @asis -@item @code{default} -This element of @var{spec} doesn't match any frames; instead, it -specifies defaults that apply to all frames. This kind of element, if -used, must be the first element of @var{spec}. Each of the following -elements can override any or all of these defaults. - -@item @code{t} -This element of @var{spec} matches all frames. Therefore, any -subsequent elements of @var{spec} are never used. Normally -@code{t} is used in the last (or only) element of @var{spec}. - -@item a list -If @var{display} is a list, each element should have the form -@code{(@var{characteristic} @var{value}@dots{})}. Here -@var{characteristic} specifies a way of classifying frames, and the -@var{value}s are possible classifications which @var{display} should -apply to. Here are the possible values of @var{characteristic}: - -@table @code -@item type -The kind of window system the frame uses---either @code{graphic} (any -graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console), -@code{w32} (for MS Windows 9X/NT/2K/XP), @code{mac} (for the Macintosh -display), or @code{tty} (a non-graphics-capable display). -@xref{Window Systems, window-system}. - -@item class -What kinds of colors the frame supports---either @code{color}, -@code{grayscale}, or @code{mono}. - -@item background -The kind of background---either @code{light} or @code{dark}. - -@item min-colors -An integer that represents the minimum number of colors the frame -should support. This matches a frame if its -@code{display-color-cells} value is at least the specified integer. - -@item supports -Whether or not the frame can display the face attributes given in -@var{value}@dots{} (@pxref{Face Attributes}). See the documentation -for the function @code{display-supports-face-attributes-p} for more -information on exactly how this testing is done. @xref{Display Face -Attribute Testing}. -@end table - -If an element of @var{display} specifies more than one @var{value} for a -given @var{characteristic}, any of those values is acceptable. If -@var{display} has more than one element, each element should specify a -different @var{characteristic}; then @emph{each} characteristic of the -frame must match one of the @var{value}s specified for it in -@var{display}. -@end table -@end defmac - - Here's how the standard face @code{region} is defined: - -@example -@group -(defface region - '((((class color) (min-colors 88) (background dark)) - :background "blue3") -@end group - (((class color) (min-colors 88) (background light)) - :background "lightgoldenrod2") - (((class color) (min-colors 16) (background dark)) - :background "blue3") - (((class color) (min-colors 16) (background light)) - :background "lightgoldenrod2") - (((class color) (min-colors 8)) - :background "blue" :foreground "white") - (((type tty) (class mono)) - :inverse-video t) - (t :background "gray")) -@group - "Basic face for highlighting the region." - :group 'basic-faces) -@end group -@end example - - Internally, @code{defface} uses the symbol property -@code{face-defface-spec} to record the face attributes specified in -@code{defface}, @code{saved-face} for the attributes saved by the user -with the customization buffer, @code{customized-face} for the -attributes customized by the user for the current session, but not -saved, and @code{face-documentation} for the documentation string. - -@defopt frame-background-mode -This option, if non-@code{nil}, specifies the background type to use for -interpreting face definitions. If it is @code{dark}, then Emacs treats -all frames as if they had a dark background, regardless of their actual -background colors. If it is @code{light}, then Emacs treats all frames -as if they had a light background. -@end defopt - -@node Face Attributes -@subsection Face Attributes -@cindex face attributes - - The effect of using a face is determined by a fixed set of @dfn{face -attributes}. This table lists all the face attributes, and what they -mean. You can specify more than one face for a given piece of text; -Emacs merges the attributes of all the faces to determine how to -display the text. @xref{Displaying Faces}. - - Any attribute in a face can have the value @code{unspecified}. This -means the face doesn't specify that attribute. In face merging, when -the first face fails to specify a particular attribute, that means the -next face gets a chance. However, the @code{default} face must -specify all attributes. - - Some of these font attributes are meaningful only on certain kinds of -displays---if your display cannot handle a certain attribute, the -attribute is ignored. (The attributes @code{:family}, @code{:width}, -@code{:height}, @code{:weight}, and @code{:slant} correspond to parts of -an X Logical Font Descriptor.) - -@table @code -@item :family -Font family name, or fontset name (@pxref{Fontsets}). If you specify a -font family name, the wild-card characters @samp{*} and @samp{?} are -allowed. - -@item :width -Relative proportionate width, also known as the character set width or -set width. This should be one of the symbols @code{ultra-condensed}, -@code{extra-condensed}, @code{condensed}, @code{semi-condensed}, -@code{normal}, @code{semi-expanded}, @code{expanded}, -@code{extra-expanded}, or @code{ultra-expanded}. - -@item :height -Either the font height, an integer in units of 1/10 point, a floating -point number specifying the amount by which to scale the height of any -underlying face, or a function, which is called with the old height -(from the underlying face), and should return the new height. - -@item :weight -Font weight---a symbol from this series (from most dense to most faint): -@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold}, -@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, -or @code{ultra-light}. - -On a text-only terminal, any weight greater than normal is displayed as -extra bright, and any weight less than normal is displayed as -half-bright (provided the terminal supports the feature). - -@item :slant -Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal}, -@code{reverse-italic}, or @code{reverse-oblique}. - -On a text-only terminal, slanted text is displayed as half-bright, if -the terminal supports the feature. - -@item :foreground -Foreground color, a string. The value can be a system-defined color -name, or a hexadecimal color specification of the form -@samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black, -@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is -blue, and @samp{#ffffff} is white.) - -@item :background -Background color, a string, like the foreground color. - -@item :inverse-video -Whether or not characters should be displayed in inverse video. The -value should be @code{t} (yes) or @code{nil} (no). - -@item :stipple -The background stipple, a bitmap. - -The value can be a string; that should be the name of a file containing -external-format X bitmap data. The file is found in the directories -listed in the variable @code{x-bitmap-file-path}. - -Alternatively, the value can specify the bitmap directly, with a list -of the form @code{(@var{width} @var{height} @var{data})}. Here, -@var{width} and @var{height} specify the size in pixels, and -@var{data} is a string containing the raw bits of the bitmap, row by -row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes -in the string (which should be a unibyte string for best results). -This means that each row always occupies at least one whole byte. - -If the value is @code{nil}, that means use no stipple pattern. - -Normally you do not need to set the stipple attribute, because it is -used automatically to handle certain shades of gray. - -@item :underline -Whether or not characters should be underlined, and in what color. If -the value is @code{t}, underlining uses the foreground color of the -face. If the value is a string, underlining uses that color. The -value @code{nil} means do not underline. - -@item :overline -Whether or not characters should be overlined, and in what color. -The value is used like that of @code{:underline}. - -@item :strike-through -Whether or not characters should be strike-through, and in what -color. The value is used like that of @code{:underline}. - -@item :inherit -The name of a face from which to inherit attributes, or a list of face -names. Attributes from inherited faces are merged into the face like an -underlying face would be, with higher priority than underlying faces. -If a list of faces is used, attributes from faces earlier in the list -override those from later faces. - -@item :box -Whether or not a box should be drawn around characters, its color, the -width of the box lines, and 3D appearance. -@end table - - Here are the possible values of the @code{:box} attribute, and what -they mean: - -@table @asis -@item @code{nil} -Don't draw a box. - -@item @code{t} -Draw a box with lines of width 1, in the foreground color. - -@item @var{color} -Draw a box with lines of width 1, in color @var{color}. - -@item @code{(:line-width @var{width} :color @var{color} :style @var{style})} -This way you can explicitly specify all aspects of the box. The value -@var{width} specifies the width of the lines to draw; it defaults to 1. - -The value @var{color} specifies the color to draw with. The default is -the foreground color of the face for simple boxes, and the background -color of the face for 3D boxes. - -The value @var{style} specifies whether to draw a 3D box. If it is -@code{released-button}, the box looks like a 3D button that is not being -pressed. If it is @code{pressed-button}, the box looks like a 3D button -that is being pressed. If it is @code{nil} or omitted, a plain 2D box -is used. -@end table - - In older versions of Emacs, before @code{:family}, @code{:height}, -@code{:width}, @code{:weight}, and @code{:slant} existed, these -attributes were used to specify the type face. They are now -semi-obsolete, but they still work: - -@table @code -@item :font -This attribute specifies the font name. - -@item :bold -A non-@code{nil} value specifies a bold font. - -@item :italic -A non-@code{nil} value specifies an italic font. -@end table - - For compatibility, you can still set these ``attributes,'' even -though they are not real face attributes. Here is what that does: - -@table @code -@item :font -You can specify an X font name as the ``value'' of this ``attribute''; -that sets the @code{:family}, @code{:width}, @code{:height}, -@code{:weight}, and @code{:slant} attributes according to the font name. - -If the value is a pattern with wildcards, the first font that matches -the pattern is used to set these attributes. - -@item :bold -A non-@code{nil} makes the face bold; @code{nil} makes it normal. -This actually works by setting the @code{:weight} attribute. - -@item :italic -A non-@code{nil} makes the face italic; @code{nil} makes it normal. -This actually works by setting the @code{:slant} attribute. -@end table - -@defvar x-bitmap-file-path -This variable specifies a list of directories for searching -for bitmap files, for the @code{:stipple} attribute. -@end defvar - -@defun bitmap-spec-p object -This returns @code{t} if @var{object} is a valid bitmap specification, -suitable for use with @code{:stipple} (see above). It returns -@code{nil} otherwise. -@end defun - -@node Attribute Functions -@subsection Face Attribute Functions - - This section describes the functions for accessing and modifying the -attributes of an existing face. - -@defun set-face-attribute face frame &rest arguments -This function sets one or more attributes of face @var{face} for frame -@var{frame}. The attributes you specify this way override whatever -the @code{defface} says. - -The extra arguments @var{arguments} specify the attributes to set, and -the values for them. They should consist of alternating attribute names -(such as @code{:family} or @code{:underline}) and corresponding values. -Thus, - -@example -(set-face-attribute 'foo nil - :width 'extended - :weight 'bold - :underline "red") -@end example - -@noindent -sets the attributes @code{:width}, @code{:weight} and @code{:underline} -to the corresponding values. - -If @var{frame} is @code{t}, this function sets the default attributes -for new frames. Default attribute values specified this way override -the @code{defface} for newly created frames. - -If @var{frame} is @code{nil}, this function sets the attributes for -all existing frames, and the default for new frames. -@end defun - -@defun face-attribute face attribute &optional frame inherit -This returns the value of the @var{attribute} attribute of face -@var{face} on @var{frame}. If @var{frame} is @code{nil}, -that means the selected frame (@pxref{Input Focus}). - -If @var{frame} is @code{t}, this returns whatever new-frames default -value you previously specified with @code{set-face-attribute} for the -@var{attribute} attribute of @var{face}. If you have not specified -one, it returns @code{nil}. - -If @var{inherit} is @code{nil}, only attributes directly defined by -@var{face} are considered, so the return value may be -@code{unspecified}, or a relative value. If @var{inherit} is -non-@code{nil}, @var{face}'s definition of @var{attribute} is merged -with the faces specified by its @code{:inherit} attribute; however the -return value may still be @code{unspecified} or relative. If -@var{inherit} is a face or a list of faces, then the result is further -merged with that face (or faces), until it becomes specified and -absolute. - -To ensure that the return value is always specified and absolute, use -a value of @code{default} for @var{inherit}; this will resolve any -unspecified or relative values by merging with the @code{default} face -(which is always completely specified). - -For example, - -@example -(face-attribute 'bold :weight) - @result{} bold -@end example -@end defun - -@defun face-attribute-relative-p attribute value -This function returns non-@code{nil} if @var{value}, when used as the -value of the face attribute @var{attribute}, is relative. This means -it would modify, rather than completely override, any value that comes -from a subsequent face in the face list or that is inherited from -another face. - -@code{unspecified} is a relative value for all attributes. -For @code{:height}, floating point values are also relative. - -For example: - -@example -(face-attribute-relative-p :height 2.0) - @result{} t -@end example -@end defun - -@defun merge-face-attribute attribute value1 value2 -If @var{value1} is a relative value for the face attribute -@var{attribute}, returns it merged with the underlying value -@var{value2}; otherwise, if @var{value1} is an absolute value for the -face attribute @var{attribute}, returns @var{value1} unchanged. -@end defun - - The functions above did not exist before Emacs 21. For compatibility -with older Emacs versions, you can use the following functions to set -and examine the face attributes which existed in those versions. -They use values of @code{t} and @code{nil} for @var{frame} -just like @code{set-face-attribute} and @code{face-attribute}. - -@defun set-face-foreground face color &optional frame -@defunx set-face-background face color &optional frame -These functions set the foreground (or background, respectively) color -of face @var{face} to @var{color}. The argument @var{color} should be a -string, the name of a color. - -Certain shades of gray are implemented by stipple patterns on -black-and-white screens. -@end defun - -@defun set-face-stipple face pattern &optional frame -This function sets the background stipple pattern of face @var{face} -to @var{pattern}. The argument @var{pattern} should be the name of a -stipple pattern defined by the X server, or actual bitmap data -(@pxref{Face Attributes}), or @code{nil} meaning don't use stipple. - -Normally there is no need to pay attention to stipple patterns, because -they are used automatically to handle certain shades of gray. -@end defun - -@defun set-face-font face font &optional frame -This function sets the font of face @var{face}. This actually sets -the attributes @code{:family}, @code{:width}, @code{:height}, -@code{:weight}, and @code{:slant} according to the font name -@var{font}. -@end defun - -@defun set-face-bold-p face bold-p &optional frame -This function specifies whether @var{face} should be bold. If -@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no. -This actually sets the @code{:weight} attribute. -@end defun - -@defun set-face-italic-p face italic-p &optional frame -This function specifies whether @var{face} should be italic. If -@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no. -This actually sets the @code{:slant} attribute. -@end defun - -@defun set-face-underline-p face underline &optional frame -This function sets the underline attribute of face @var{face}. -Non-@code{nil} means do underline; @code{nil} means don't. -If @var{underline} is a string, underline with that color. -@end defun - -@defun set-face-inverse-video-p face inverse-video-p &optional frame -This function sets the @code{:inverse-video} attribute of face -@var{face}. -@end defun - -@defun invert-face face &optional frame -This function swaps the foreground and background colors of face -@var{face}. -@end defun - - These functions examine the attributes of a face. If you don't -specify @var{frame}, they refer to the selected frame; @code{t} refers -to the default data for new frames. They return the symbol -@code{unspecified} if the face doesn't define any value for that -attribute. - -@defun face-foreground face &optional frame inherit -@defunx face-background face &optional frame inherit -These functions return the foreground color (or background color, -respectively) of face @var{face}, as a string. - -If @var{inherit} is @code{nil}, only a color directly defined by the face is -returned. If @var{inherit} is non-@code{nil}, any faces specified by its -@code{:inherit} attribute are considered as well, and if @var{inherit} -is a face or a list of faces, then they are also considered, until a -specified color is found. To ensure that the return value is always -specified, use a value of @code{default} for @var{inherit}. -@end defun - -@defun face-stipple face &optional frame inherit -This function returns the name of the background stipple pattern of face -@var{face}, or @code{nil} if it doesn't have one. - -If @var{inherit} is @code{nil}, only a stipple directly defined by the -face is returned. If @var{inherit} is non-@code{nil}, any faces -specified by its @code{:inherit} attribute are considered as well, and -if @var{inherit} is a face or a list of faces, then they are also -considered, until a specified stipple is found. To ensure that the -return value is always specified, use a value of @code{default} for -@var{inherit}. -@end defun - -@defun face-font face &optional frame -This function returns the name of the font of face @var{face}. -@end defun - -@defun face-bold-p face &optional frame -This function returns @code{t} if @var{face} is bold---that is, if it is -bolder than normal. It returns @code{nil} otherwise. -@end defun - -@defun face-italic-p face &optional frame -This function returns @code{t} if @var{face} is italic or oblique, -@code{nil} otherwise. -@end defun - -@defun face-underline-p face &optional frame -This function returns the @code{:underline} attribute of face @var{face}. -@end defun - -@defun face-inverse-video-p face &optional frame -This function returns the @code{:inverse-video} attribute of face @var{face}. -@end defun - -@node Displaying Faces -@subsection Displaying Faces - - Here are the ways to specify which faces to use for display of text: - -@itemize @bullet -@item -With defaults. The @code{default} face is used as the ultimate -default for all text. (In Emacs 19 and 20, the @code{default} -face is used only when no other face is specified.) - -@item -For a mode line or header line, the face @code{mode-line} or -@code{mode-line-inactive}, or @code{header-line}, is merged in just -before @code{default}. - -@item -With text properties. A character can have a @code{face} property; if -so, the faces and face attributes specified there apply. @xref{Special -Properties}. - -If the character has a @code{mouse-face} property, that is used instead -of the @code{face} property when the mouse is ``near enough'' to the -character. - -@item -With overlays. An overlay can have @code{face} and @code{mouse-face} -properties too; they apply to all the text covered by the overlay. - -@item -With a region that is active. In Transient Mark mode, the region is -highlighted with the face @code{region} (@pxref{Standard Faces,,, -emacs, The GNU Emacs Manual}). - -@item -With special glyphs. Each glyph can specify a particular face -number. @xref{Glyphs}. -@end itemize - - If these various sources together specify more than one face for a -particular character, Emacs merges the attributes of the various faces -specified. For each attribute, Emacs tries first the face of any -special glyph; then the face for region highlighting, if appropriate; -then the faces specified by overlays, followed by those specified by -text properties, then the @code{mode-line} or -@code{mode-line-inactive} or @code{header-line} face (if in a mode -line or a header line), and last the @code{default} face. - - When multiple overlays cover one character, an overlay with higher -priority overrides those with lower priority. @xref{Overlays}. - -@node Font Selection -@subsection Font Selection - - @dfn{Selecting a font} means mapping the specified face attributes for -a character to a font that is available on a particular display. The -face attributes, as determined by face merging, specify most of the -font choice, but not all. Part of the choice depends on what character -it is. - - If the face specifies a fontset name, that fontset determines a -pattern for fonts of the given charset. If the face specifies a font -family, a font pattern is constructed. - - Emacs tries to find an available font for the given face attributes -and character's registry and encoding. If there is a font that matches -exactly, it is used, of course. The hard case is when no available font -exactly fits the specification. Then Emacs looks for one that is -``close''---one attribute at a time. You can specify the order to -consider the attributes. In the case where a specified font family is -not available, you can specify a set of mappings for alternatives to -try. - -@defvar face-font-selection-order -This variable specifies the order of importance of the face attributes -@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The -value should be a list containing those four symbols, in order of -decreasing importance. - -Font selection first finds the best available matches for the first -attribute listed; then, among the fonts which are best in that way, it -searches for the best matches in the second attribute, and so on. - -The attributes @code{:weight} and @code{:width} have symbolic values in -a range centered around @code{normal}. Matches that are more extreme -(farther from @code{normal}) are somewhat preferred to matches that are -less extreme (closer to @code{normal}); this is designed to ensure that -non-normal faces contrast with normal ones, whenever possible. - -The default is @code{(:width :height :weight :slant)}, which means first -find the fonts closest to the specified @code{:width}, then---among the -fonts with that width---find a best match for the specified font height, -and so on. - -One example of a case where this variable makes a difference is when the -default font has no italic equivalent. With the default ordering, the -@code{italic} face will use a non-italic font that is similar to the -default one. But if you put @code{:slant} before @code{:height}, the -@code{italic} face will use an italic font, even if its height is not -quite right. -@end defvar - -@defvar face-font-family-alternatives -This variable lets you specify alternative font families to try, if a -given family is specified and doesn't exist. Each element should have -this form: - -@example -(@var{family} @var{alternate-families}@dots{}) -@end example - -If @var{family} is specified but not available, Emacs will try the other -families given in @var{alternate-families}, one by one, until it finds a -family that does exist. -@end defvar - -@defvar face-font-registry-alternatives -This variable lets you specify alternative font registries to try, if a -given registry is specified and doesn't exist. Each element should have -this form: - -@example -(@var{registry} @var{alternate-registries}@dots{}) -@end example - -If @var{registry} is specified but not available, Emacs will try the -other registries given in @var{alternate-registries}, one by one, -until it finds a registry that does exist. -@end defvar - - Emacs can make use of scalable fonts, but by default it does not use -them, since the use of too many or too big scalable fonts can crash -XFree86 servers. - -@defvar scalable-fonts-allowed -This variable controls which scalable fonts to use. A value of -@code{nil}, the default, means do not use scalable fonts. @code{t} -means to use any scalable font that seems appropriate for the text. - -Otherwise, the value must be a list of regular expressions. Then a -scalable font is enabled for use if its name matches any regular -expression in the list. For example, - -@example -(setq scalable-fonts-allowed '("muleindian-2$")) -@end example - -@noindent -allows the use of scalable fonts with registry @code{muleindian-2}. -@end defvar - -@defvar face-font-rescale-alist -This variable specifies scaling for certain faces. Its value should -be a list of elements of the form - -@example -(@var{fontname-regexp} . @var{scale-factor}) -@end example - -If @var{fontname-regexp} matches the font name that is about to be -used, this says to choose a larger similar font according to the -factor @var{scale-factor}. You would use this feature to normalize -the font size if certain fonts are bigger or smaller than their -nominal heights and widths would suggest. -@end defvar - -@node Face Functions -@subsection Functions for Working with Faces - - Here are additional functions for creating and working with faces. - -@defun make-face name -This function defines a new face named @var{name}, initially with all -attributes @code{nil}. It does nothing if there is already a face named -@var{name}. -@end defun - -@defun face-list -This function returns a list of all defined face names. -@end defun - -@defun copy-face old-face new-name &optional frame new-frame -This function defines a face named @var{new-name} as a copy of the existing -face named @var{old-face}. It creates the face @var{new-name} if that -doesn't already exist. - -If the optional argument @var{frame} is given, this function applies -only to that frame. Otherwise it applies to each frame individually, -copying attributes from @var{old-face} in each frame to @var{new-face} -in the same frame. - -If the optional argument @var{new-frame} is given, then @code{copy-face} -copies the attributes of @var{old-face} in @var{frame} to @var{new-name} -in @var{new-frame}. -@end defun - -@defun face-id face -This function returns the face number of face @var{face}. -@end defun - -@defun face-documentation face -This function returns the documentation string of face @var{face}, or -@code{nil} if none was specified for it. -@end defun - -@defun face-equal face1 face2 &optional frame -This returns @code{t} if the faces @var{face1} and @var{face2} have the -same attributes for display. -@end defun - -@defun face-differs-from-default-p face &optional frame -This returns non-@code{nil} if the face @var{face} displays -differently from the default face. -@end defun - -@cindex face alias -A @dfn{face alias} provides an equivalent name for a face. You can -define a face alias by giving the alias symbol the @code{face-alias} -property, with a value of the target face name. The following example -makes @code{modeline} an alias for the @code{mode-line} face. - -@example -(put 'modeline 'face-alias 'mode-line) -@end example - - -@node Auto Faces -@subsection Automatic Face Assignment -@cindex automatic face assignment -@cindex faces, automatic choice - - This hook is used for automatically assigning facesto text in the -buffer. It is part of the implementation of Jit-Lock mode, used by -Font-Lock. - -@defvar fontification-functions -This variable holds a list of functions that are called by Emacs -redisplay as needed to assign faces automatically to text in the buffer. - -The functions are called in the order listed, with one argument, a -buffer position @var{pos}. Each function should attempt to assign faces -to the text in the current buffer starting at @var{pos}. - -Each function should record the faces they assign by setting the -@code{face} property. It should also add a non-@code{nil} -@code{fontified} property for all the text it has assigned faces to. -That property tells redisplay that faces have been assigned to that text -already. - -It is probably a good idea for each function to do nothing if the -character after @var{pos} already has a non-@code{nil} @code{fontified} -property, but this is not required. If one function overrides the -assignments made by a previous one, the properties as they are -after the last function finishes are the ones that really matter. - -For efficiency, we recommend writing these functions so that they -usually assign faces to around 400 to 600 characters at each call. -@end defvar - -@node Font Lookup -@subsection Looking Up Fonts - -@defun x-list-fonts pattern &optional face frame maximum -This function returns a list of available font names that match -@var{pattern}. If the optional arguments @var{face} and @var{frame} are -specified, then the list is limited to fonts that are the same size as -@var{face} currently is on @var{frame}. - -The argument @var{pattern} should be a string, perhaps with wildcard -characters: the @samp{*} character matches any substring, and the -@samp{?} character matches any single character. Pattern matching -of font names ignores case. - -If you specify @var{face} and @var{frame}, @var{face} should be a face name -(a symbol) and @var{frame} should be a frame. - -The optional argument @var{maximum} sets a limit on how many fonts to -return. If this is non-@code{nil}, then the return value is truncated -after the first @var{maximum} matching fonts. Specifying a small value -for @var{maximum} can make this function much faster, in cases where -many fonts match the pattern. -@end defun - -@defun x-family-fonts &optional family frame -This function returns a list describing the available fonts for family -@var{family} on @var{frame}. If @var{family} is omitted or @code{nil}, -this list applies to all families, and therefore, it contains all -available fonts. Otherwise, @var{family} must be a string; it may -contain the wildcards @samp{?} and @samp{*}. - -The list describes the display that @var{frame} is on; if @var{frame} is -omitted or @code{nil}, it applies to the selected frame's display -(@pxref{Input Focus}). - -The list contains a vector of the following form for each font: - -@example -[@var{family} @var{width} @var{point-size} @var{weight} @var{slant} - @var{fixed-p} @var{full} @var{registry-and-encoding}] -@end example - -The first five elements correspond to face attributes; if you -specify these attributes for a face, it will use this font. - -The last three elements give additional information about the font. -@var{fixed-p} is non-@code{nil} if the font is fixed-pitch. -@var{full} is the full name of the font, and -@var{registry-and-encoding} is a string giving the registry and -encoding of the font. - -The result list is sorted according to the current face font sort order. -@end defun - -@defun x-font-family-list &optional frame -This function returns a list of the font families available for -@var{frame}'s display. If @var{frame} is omitted or @code{nil}, it -describes the selected frame's display (@pxref{Input Focus}). - -The value is a list of elements of this form: - -@example -(@var{family} . @var{fixed-p}) -@end example - -@noindent -Here @var{family} is a font family, and @var{fixed-p} is -non-@code{nil} if fonts of that family are fixed-pitch. -@end defun - -@defvar font-list-limit -This variable specifies maximum number of fonts to consider in font -matching. The function @code{x-family-fonts} will not return more than -that many fonts, and font selection will consider only that many fonts -when searching a matching font for face attributes. The default is -currently 100. -@end defvar - -@node Fontsets -@subsection Fontsets - - A @dfn{fontset} is a list of fonts, each assigned to a range of -character codes. An individual font cannot display the whole range of -characters that Emacs supports, but a fontset can. Fontsets have names, -just as fonts do, and you can use a fontset name in place of a font name -when you specify the ``font'' for a frame or a face. Here is -information about defining a fontset under Lisp program control. - -@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror -This function defines a new fontset according to the specification -string @var{fontset-spec}. The string should have this format: - -@smallexample -@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}} -@end smallexample - -@noindent -Whitespace characters before and after the commas are ignored. - -The first part of the string, @var{fontpattern}, should have the form of -a standard X font name, except that the last two fields should be -@samp{fontset-@var{alias}}. - -The new fontset has two names, one long and one short. The long name is -@var{fontpattern} in its entirety. The short name is -@samp{fontset-@var{alias}}. You can refer to the fontset by either -name. If a fontset with the same name already exists, an error is -signaled, unless @var{noerror} is non-@code{nil}, in which case this -function does nothing. - -If optional argument @var{style-variant-p} is non-@code{nil}, that says -to create bold, italic and bold-italic variants of the fontset as well. -These variant fontsets do not have a short name, only a long one, which -is made by altering @var{fontpattern} to indicate the bold or italic -status. - -The specification string also says which fonts to use in the fontset. -See below for the details. -@end defun - - The construct @samp{@var{charset}:@var{font}} specifies which font to -use (in this fontset) for one particular character set. Here, -@var{charset} is the name of a character set, and @var{font} is the font -to use for that character set. You can use this construct any number of -times in the specification string. - - For the remaining character sets, those that you don't specify -explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces -@samp{fontset-@var{alias}} with a value that names one character set. -For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced -with @samp{ISO8859-1}. - - In addition, when several consecutive fields are wildcards, Emacs -collapses them into a single wildcard. This is to prevent use of -auto-scaled fonts. Fonts made by scaling larger fonts are not usable -for editing, and scaling a smaller font is not useful because it is -better to use the smaller font in its own size, which Emacs does. - - Thus if @var{fontpattern} is this, - -@example --*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 -@end example - -@noindent -the font specification for @acronym{ASCII} characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-ISO8859-1 -@end example - -@noindent -and the font specification for Chinese GB2312 characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-gb2312*-* -@end example - - You may not have any Chinese font matching the above font -specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In -such a case, @samp{Fontset-@var{n}} can be specified as below: - -@smallexample -Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ - chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* -@end smallexample - -@noindent -Then, the font specifications for all but Chinese GB2312 characters have -@samp{fixed} in the @var{family} field, and the font specification for -Chinese GB2312 characters has a wild card @samp{*} in the @var{family} -field. - -@defun set-fontset-font name character fontname &optional frame -This function modifies the existing fontset @var{name} to -use the font name @var{fontname} for the character @var{character}. - -If @var{name} is @code{nil}, this function modifies the default -fontset, whose short name is @samp{fontset-default}. - -@var{character} may be a cons; @code{(@var{from} . @var{to})}, where -@var{from} and @var{to} are non-generic characters. In that case, use -@var{fontname} for all characters in the range @var{from} and @var{to} -(inclusive). - -@var{character} may be a charset. In that case, use -@var{fontname} for all character in the charsets. - -@var{fontname} may be a cons; @code{(@var{family} . @var{registry})}, -where @var{family} is a family name of a font (possibly including a -foundry name at the head), @var{registry} is a registry name of a font -(possibly including an encoding name at the tail). - -For instance, this changes the default fontset to use a font of which -registry name is @samp{JISX0208.1983} for all characters belonging to -the charset @code{japanese-jisx0208}. - -@smallexample -(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983")) -@end smallexample -@end defun - -@defun char-displayable-p char -This function returns @code{t} if Emacs ought to be able to display -@var{char}. More precisely, if the selected frame's fontset has a -font to display the character set that @var{char} belongs to. - -Fontsets can specify a font on a per-character basis; when the fontset -does that, this function's value may not be accurate. -@end defun - -@node Fringes -@section Fringes -@cindex fringes - - The @dfn{fringes} of a window are thin vertical strips down the -sides that are used for displaying bitmaps that indicate truncation, -continuation, horizontal scrolling, and the overlay arrow. - -@menu -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. -@end menu - -@node Fringe Size/Pos -@subsection Fringe Size and Position - - The following buffer-local variables control the position and width -of the window fringes. - -@defvar fringes-outside-margins -The fringes normally appear between the display margins and the window -text. If the value is non-@code{nil}, they appear outside the display -margins. @xref{Display Margins}. -@end defvar - -@defvar left-fringe-width -This variable, if non-@code{nil}, specifies the width of the left -fringe in pixels. A value of @code{nil} means to use the left fringe -width from the window's frame. -@end defvar - -@defvar right-fringe-width -This variable, if non-@code{nil}, specifies the width of the right -fringe in pixels. A value of @code{nil} means to use the right fringe -width from the window's frame. -@end defvar - - The values of these variables take effect when you display the -buffer in a window. If you change them while the buffer is visible, -you can call @code{set-window-buffer} to display it once again in the -same window, to make the changes take effect. - -@defun set-window-fringes window left &optional right outside-margins -This function sets the fringe widths of window @var{window}. -If @var{window} is @code{nil}, the selected window is used. - -The argument @var{left} specifies the width in pixels of the left -fringe, and likewise @var{right} for the right fringe. A value of -@code{nil} for either one stands for the default width. If -@var{outside-margins} is non-@code{nil}, that specifies that fringes -should appear outside of the display margins. -@end defun - -@defun window-fringes &optional window -This function returns information about the fringes of a window -@var{window}. If @var{window} is omitted or @code{nil}, the selected -window is used. The value has the form @code{(@var{left-width} -@var{right-width} @var{outside-margins})}. -@end defun - - -@node Fringe Indicators -@subsection Fringe Indicators -@cindex fringe indicators -@cindex indicators, fringe - - The @dfn{fringe indicators} are tiny icons Emacs displays in the -window fringe (on a graphic display) to indicate truncated or -continued lines, buffer boundaries, overlay arrow, etc. - -@defopt indicate-empty-lines -@cindex fringes, and empty line indication -When this is non-@code{nil}, Emacs displays a special glyph in the -fringe of each empty line at the end of the buffer, on graphical -displays. @xref{Fringes}. This variable is automatically -buffer-local in every buffer. -@end defopt - -@defvar indicate-buffer-boundaries -This buffer-local variable controls how the buffer boundaries and -window scrolling are indicated in the window fringes. - -Emacs can indicate the buffer boundaries---that is, the first and last -line in the buffer---with angle icons when they appear on the screen. -In addition, Emacs can display an up-arrow in the fringe to show -that there is text above the screen, and a down-arrow to show -there is text below the screen. - -There are three kinds of basic values: - -@table @asis -@item @code{nil} -Don't display any of these fringe icons. -@item @code{left} -Display the angle icons and arrows in the left fringe. -@item @code{right} -Display the angle icons and arrows in the right fringe. -@item any non-alist -Display the angle icons in the left fringe -and don't display the arrows. -@end table - -Otherwise the value should be an alist that specifies which fringe -indicators to display and where. Each element of the alist should -have the form @code{(@var{indicator} . @var{position})}. Here, -@var{indicator} is one of @code{top}, @code{bottom}, @code{up}, -@code{down}, and @code{t} (which covers all the icons not yet -specified), while @var{position} is one of @code{left}, @code{right} -and @code{nil}. - -For example, @code{((top . left) (t . right))} places the top angle -bitmap in left fringe, and the bottom angle bitmap as well as both -arrow bitmaps in right fringe. To show the angle bitmaps in the left -fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}. -@end defvar - -@defvar default-indicate-buffer-boundaries -The value of this variable is the default value for -@code{indicate-buffer-boundaries} in buffers that do not override it. -@end defvar - -@defvar fringe-indicator-alist -This buffer-local variable specifies the mapping from logical fringe -indicators to the actual bitmaps displayed in the window fringes. - -These symbols identify the logical fringe indicators: - -@table @asis -@item Truncation and continuation line indicators: -@code{truncation}, @code{continuation}. - -@item Buffer position indicators: -@code{up}, @code{down}, -@code{top}, @code{bottom}, -@code{top-bottom}. - -@item Empty line indicator: -@code{empty-line}. - -@item Overlay arrow indicator: -@code{overlay-arrow}. - -@item Unknown bitmap indicator: -@code{unknown}. -@end table - - The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})} -specifies the fringe bitmaps used to display a specific logical -fringe indicator. - -Here, @var{indicator} specifies the logical indicator type, and -@var{bitmaps} is list of symbols @code{(@var{left} @var{right} -[@var{left1} @var{right1}])} which specifies the actual bitmap shown -in the left or right fringe for the logical indicator. - -The @var{left} and @var{right} symbols specify the bitmaps shown in -the left and/or right fringe for the specific indicator. The -@var{left1} or @var{right1} bitmaps are used only for the `bottom' and -`top-bottom indicators when the last (only) line in has no final -newline. Alternatively, @var{bitmaps} may be a single symbol which is -used in both left and right fringes. - -When @code{fringe-indicator-alist} has a buffer-local value, and there -is no bitmap defined for a logical indicator, or the bitmap is -@code{t}, the corresponding value from the (non-local) -@code{default-fringe-indicator-alist} is used. - -To completely hide a specific indicator, set the bitmap to @code{nil}. -@end defvar - -@defvar default-fringe-indicator-alist -The value of this variable is the default value for -@code{fringe-indicator-alist} in buffers that do not override it. -@end defvar - -Standard fringe bitmaps for indicators: -@example -left-arrow right-arrow up-arrow down-arrow -left-curly-arrow right-curly-arrow -left-triangle right-triangle -top-left-angle top-right-angle -bottom-left-angle bottom-right-angle -left-bracket right-bracket -filled-rectangle hollow-rectangle -filled-square hollow-square -vertical-bar horizontal-bar -empty-line question-mark -@end example - -@node Fringe Cursors -@subsection Fringe Cursors -@cindex fringe cursors -@cindex cursor, fringe - - When a line is exactly as wide as the window, Emacs displays the -cursor in the right fringe instead of using two lines. Different -bitmaps are used to represent the cursor in the fringe depending on -the current buffer's cursor type. - -@table @asis -@item Logical cursor types: -@code{box} , @code{hollow}, @code{bar}, -@code{hbar}, @code{hollow-small}. -@end table - -The @code{hollow-small} type is used instead of @code{hollow} when the -normal @code{hollow-rectangle} bitmap is too tall to fit on a specific -display line. - -@defvar overflow-newline-into-fringe -If this is non-@code{nil}, lines exactly as wide as the window (not -counting the final newline character) are not continued. Instead, -when point is at the end of the line, the cursor appears in the right -fringe. -@end defvar - -@defvar fringe-cursor-alist -This variable specifies the mapping from logical cursor type to the -actual fringe bitmaps displayed in the right fringe. The value is an -alist where each element @code{(@var{cursor} . @var{bitmap})} specifies -the fringe bitmaps used to display a specific logical cursor type in -the fringe. Here, @var{cursor} specifies the logical cursor type and -@var{bitmap} is a symbol specifying the fringe bitmap to be displayed -for that logical cursor type. - -When @code{fringe-cursor-alist} has a buffer-local value, and there is -no bitmap defined for a cursor type, the corresponding value from the -(non-local) @code{default-fringes-indicator-alist} is used. -@end defvar - -@defvar default-fringes-cursor-alist -The value of this variable is the default value for -@code{fringe-cursor-alist} in buffers that do not override it. -@end defvar - -Standard bitmaps for displaying the cursor in right fringe: -@example -filled-rectangle hollow-rectangle filled-square hollow-square -vertical-bar horizontal-bar -@end example - - -@node Fringe Bitmaps -@subsection Fringe Bitmaps -@cindex fringe bitmaps -@cindex bitmaps, fringe - - The @dfn{fringe bitmaps} are the actual bitmaps which represent the -logical fringe indicators for truncated or continued lines, buffer -boundaries, overlay arrow, etc. Fringe bitmap symbols have their own -name space. The fringe bitmaps are shared by all frames and windows. -You can redefine the built-in fringe bitmaps, and you can define new -fringe bitmaps. - - The way to display a bitmap in the left or right fringes for a given -line in a window is by specifying the @code{display} property for one -of the characters that appears in it. Use a display specification of -the form @code{(left-fringe @var{bitmap} [@var{face}])} or -@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display -Property}). Here, @var{bitmap} is a symbol identifying the bitmap you -want, and @var{face} (which is optional) is the name of the face whose -colors should be used for displaying the bitmap, instead of the -default @code{fringe} face. @var{face} is automatically merged with -the @code{fringe} face, so normally @var{face} need only specify the -foreground color for the bitmap. - -@defun fringe-bitmaps-at-pos &optional pos window -This function returns the fringe bitmaps of the display line -containing position @var{pos} in window @var{window}. The return -value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left} -is the symbol for the fringe bitmap in the left fringe (or @code{nil} -if no bitmap), @var{right} is similar for the right fringe, and @var{ov} -is non-@code{nil} if there is an overlay arrow in the left fringe. - -The value is @code{nil} if @var{pos} is not visible in @var{window}. -If @var{window} is @code{nil}, that stands for the selected window. -If @var{pos} is @code{nil}, that stands for the value of point in -@var{window}. -@end defun - -@node Customizing Bitmaps -@subsection Customizing Fringe Bitmaps - -@defun define-fringe-bitmap bitmap bits &optional height width align -This function defines the symbol @var{bitmap} as a new fringe bitmap, -or replaces an existing bitmap with that name. - -The argument @var{bits} specifies the image to use. It should be -either a string or a vector of integers, where each element (an -integer) corresponds to one row of the bitmap. Each bit of an integer -corresponds to one pixel of the bitmap, where the low bit corresponds -to the rightmost pixel of the bitmap. - -The height is normally the length of @var{bits}. However, you -can specify a different height with non-@code{nil} @var{height}. The width -is normally 8, but you can specify a different width with non-@code{nil} -@var{width}. The width must be an integer between 1 and 16. - -The argument @var{align} specifies the positioning of the bitmap -relative to the range of rows where it is used; the default is to -center the bitmap. The allowed values are @code{top}, @code{center}, -or @code{bottom}. - -The @var{align} argument may also be a list @code{(@var{align} -@var{periodic})} where @var{align} is interpreted as described above. -If @var{periodic} is non-@code{nil}, it specifies that the rows in -@code{bits} should be repeated enough times to reach the specified -height. -@end defun - -@defun destroy-fringe-bitmap bitmap -This function destroy the fringe bitmap identified by @var{bitmap}. -If @var{bitmap} identifies a standard fringe bitmap, it actually -restores the standard definition of that bitmap, instead of -eliminating it entirely. -@end defun - -@defun set-fringe-bitmap-face bitmap &optional face -This sets the face for the fringe bitmap @var{bitmap} to @var{face}. -If @var{face} is @code{nil}, it selects the @code{fringe} face. The -bitmap's face controls the color to draw it in. - -@var{face} is merged with the @code{fringe} face, so normally -@var{face} should specify only the foreground color. -@end defun - -@node Overlay Arrow -@subsection The Overlay Arrow -@c @cindex overlay arrow Duplicates variable names - - The @dfn{overlay arrow} is useful for directing the user's attention -to a particular line in a buffer. For example, in the modes used for -interface to debuggers, the overlay arrow indicates the line of code -about to be executed. This feature has nothing to do with -@dfn{overlays} (@pxref{Overlays}). - -@defvar overlay-arrow-string -This variable holds the string to display to call attention to a -particular line, or @code{nil} if the arrow feature is not in use. -On a graphical display the contents of the string are ignored; instead a -glyph is displayed in the fringe area to the left of the display area. -@end defvar - -@defvar overlay-arrow-position -This variable holds a marker that indicates where to display the overlay -arrow. It should point at the beginning of a line. On a non-graphical -display the arrow text -appears at the beginning of that line, overlaying any text that would -otherwise appear. Since the arrow is usually short, and the line -usually begins with indentation, normally nothing significant is -overwritten. - -The overlay-arrow string is displayed in any given buffer if the value -of @code{overlay-arrow-position} in that buffer points into that -buffer. Thus, it is possible to display multiple overlay arrow strings -by creating buffer-local bindings of @code{overlay-arrow-position}. -However, it is usually cleaner to use -@code{overlay-arrow-variable-list} to achieve this result. -@c !!! overlay-arrow-position: but the overlay string may remain in the display -@c of some other buffer until an update is required. This should be fixed -@c now. Is it? -@end defvar - - You can do a similar job by creating an overlay with a -@code{before-string} property. @xref{Overlay Properties}. - - You can define multiple overlay arrows via the variable -@code{overlay-arrow-variable-list}. - -@defvar overlay-arrow-variable-list -This variable's value is a list of variables, each of which specifies -the position of an overlay arrow. The variable -@code{overlay-arrow-position} has its normal meaning because it is on -this list. -@end defvar - -Each variable on this list can have properties -@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that -specify an overlay arrow string (for text-only terminals) or fringe -bitmap (for graphical terminals) to display at the corresponding -overlay arrow position. If either property is not set, the default -@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator -is used. - -@node Scroll Bars -@section Scroll Bars -@cindex scroll bars - -Normally the frame parameter @code{vertical-scroll-bars} controls -whether the windows in the frame have vertical scroll bars, and -whether they are on the left or right. The frame parameter -@code{scroll-bar-width} specifies how wide they are (@code{nil} -meaning the default). @xref{Layout Parameters}. - -@defun frame-current-scroll-bars &optional frame -This function reports the scroll bar type settings for frame -@var{frame}. The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}, where -@var{vertical-type} is either @code{left}, @code{right}, or @code{nil} -(which means no scroll bar.) @var{horizontal-type} is meant to -specify the horizontal scroll bar type, but since they are not -implemented, it is always @code{nil}. -@end defun - -@vindex vertical-scroll-bar - You can enable or disable scroll bars for a particular buffer, -by setting the variable @code{vertical-scroll-bar}. This variable -automatically becomes buffer-local when set. The possible values are -@code{left}, @code{right}, @code{t}, which means to use the -frame's default, and @code{nil} for no scroll bar. - - You can also control this for individual windows. Call the function -@code{set-window-scroll-bars} to specify what to do for a specific window: - -@defun set-window-scroll-bars window width &optional vertical-type horizontal-type -This function sets the width and type of scroll bars for window -@var{window}. - -@var{width} specifies the scroll bar width in pixels (@code{nil} means -use the width specified for the frame). @var{vertical-type} specifies -whether to have a vertical scroll bar and, if so, where. The possible -values are @code{left}, @code{right} and @code{nil}, just like the -values of the @code{vertical-scroll-bars} frame parameter. - -The argument @var{horizontal-type} is meant to specify whether and -where to have horizontal scroll bars, but since they are not -implemented, it has no effect. If @var{window} is @code{nil}, the -selected window is used. -@end defun - -@defun window-scroll-bars &optional window -Report the width and type of scroll bars specified for @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a list of the form @code{(@var{width} -@var{cols} @var{vertical-type} @var{horizontal-type})}. The value -@var{width} is the value that was specified for the width (which may -be @code{nil}); @var{cols} is the number of columns that the scroll -bar actually occupies. - -@var{horizontal-type} is not actually meaningful. -@end defun - -If you don't specify these values for a window with -@code{set-window-scroll-bars}, the buffer-local variables -@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being -displayed control the window's vertical scroll bars. The function -@code{set-window-buffer} examines these variables. If you change them -in a buffer that is already visible in a window, you can make the -window take note of the new values by calling @code{set-window-buffer} -specifying the same buffer that is already displayed. - -@defvar scroll-bar-mode -This variable, always local in all buffers, controls whether and where -to put scroll bars in windows displaying the buffer. The possible values -are @code{nil} for no scroll bar, @code{left} to put a scroll bar on -the left, and @code{right} to put a scroll bar on the right. -@end defvar - -@defun window-current-scroll-bars &optional window -This function reports the scroll bar type for window @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike -@code{window-scroll-bars}, this reports the scroll bar type actually -used, once frame defaults and @code{scroll-bar-mode} are taken into -account. -@end defun - -@defvar scroll-bar-width -This variable, always local in all buffers, specifies the width of the -buffer's scroll bars, measured in pixels. A value of @code{nil} means -to use the value specified by the frame. -@end defvar - -@node Display Property -@section The @code{display} Property -@cindex display specification -@kindex display @r{(text property)} - - The @code{display} text property (or overlay property) is used to -insert images into text, and also control other aspects of how text -displays. The value of the @code{display} property should be a -display specification, or a list or vector containing several display -specifications. - - Some kinds of @code{display} properties specify something to display -instead of the text that has the property. In this case, ``the text'' -means all the consecutive characters that have the same Lisp object as -their @code{display} property; these characters are replaced as a -single unit. By contrast, characters that have similar but distinct -Lisp objects as their @code{display} properties are handled -separately. Here's a function that illustrates this point: - -@smallexample -(defun foo () - (goto-char (point-min)) - (dotimes (i 5) - (let ((string (concat "A"))) - (put-text-property (point) (1+ (point)) 'display string) - (forward-char 1) - (put-text-property (point) (1+ (point)) 'display string) - (forward-char 1)))) -@end smallexample - -@noindent -It gives each of the first ten characters in the buffer string -@code{"A"} as the @code{display} property, but they don't all get the -same string. The first two characters get the same string, so they -together are replaced with one @samp{A}. The next two characters get -a second string, so they together are replaced with one @samp{A}. -Likewise for each following pair of characters. Thus, the ten -characters appear as five A's. This function would have the same -results: - -@smallexample -(defun foo () - (goto-char (point-min)) - (dotimes (i 5) - (let ((string (concat "A"))) - (put-text-property (point) (2+ (point)) 'display string) - (put-text-property (point) (1+ (point)) 'display string) - (forward-char 2)))) -@end smallexample - -@noindent -This illustrates that what matters is the property value for -each character. If two consecutive characters have the same -object as the @code{display} property value, it's irrelevant -whether they got this property from a single call to -@code{put-text-property} or from two different calls. - - The rest of this section describes several kinds of -display specifications and what they mean. - -@menu -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; magnifying text; moving it - up or down on the page; adjusting the width - of spaces within text. -* Display Margins:: Displaying text or images to the side of the main text. -@end menu - -@node Specified Space -@subsection Specified Spaces -@cindex spaces, specified height or width -@cindex variable-width spaces - - To display a space of specified width and/or height, use a display -specification of the form @code{(space . @var{props})}, where -@var{props} is a property list (a list of alternating properties and -values). You can put this property on one or more consecutive -characters; a space of the specified height and width is displayed in -place of @emph{all} of those characters. These are the properties you -can use in @var{props} to specify the weight of the space: - -@table @code -@item :width @var{width} -If @var{width} is an integer or floating point number, it specifies -that the space width should be @var{width} times the normal character -width. @var{width} can also be a @dfn{pixel width} specification -(@pxref{Pixel Specification}). - -@item :relative-width @var{factor} -Specifies that the width of the stretch should be computed from the -first character in the group of consecutive characters that have the -same @code{display} property. The space width is the width of that -character, multiplied by @var{factor}. - -@item :align-to @var{hpos} -Specifies that the space should be wide enough to reach @var{hpos}. -If @var{hpos} is a number, it is measured in units of the normal -character width. @var{hpos} can also be a @dfn{pixel width} -specification (@pxref{Pixel Specification}). -@end table - - You should use one and only one of the above properties. You can -also specify the height of the space, with these properties: - -@table @code -@item :height @var{height} -Specifies the height of the space. -If @var{height} is an integer or floating point number, it specifies -that the space height should be @var{height} times the normal character -height. The @var{height} may also be a @dfn{pixel height} specification -(@pxref{Pixel Specification}). - -@item :relative-height @var{factor} -Specifies the height of the space, multiplying the ordinary height -of the text having this display specification by @var{factor}. - -@item :ascent @var{ascent} -If the value of @var{ascent} is a non-negative number no greater than -100, it specifies that @var{ascent} percent of the height of the space -should be considered as the ascent of the space---that is, the part -above the baseline. The ascent may also be specified in pixel units -with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}). - -@end table - - Don't use both @code{:height} and @code{:relative-height} together. - - The @code{:width} and @code{:align-to} properties are supported on -non-graphic terminals, but the other space properties in this section -are not. - -@node Pixel Specification -@subsection Pixel Specification for Spaces -@cindex spaces, pixel specification - - The value of the @code{:width}, @code{:align-to}, @code{:height}, -and @code{:ascent} properties can be a special kind of expression that -is evaluated during redisplay. The result of the evaluation is used -as an absolute number of pixels. - - The following expressions are supported: - -@smallexample -@group - @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form} - @var{num} ::= @var{integer} | @var{float} | @var{symbol} - @var{unit} ::= in | mm | cm | width | height -@end group -@group - @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin - | scroll-bar | text - @var{pos} ::= left | center | right - @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...) - @var{op} ::= + | - -@end group -@end smallexample - - The form @var{num} specifies a fraction of the default frame font -height or width. The form @code{(@var{num})} specifies an absolute -number of pixels. If @var{num} is a symbol, @var{symbol}, its -buffer-local variable binding is used. - - The @code{in}, @code{mm}, and @code{cm} units specify the number of -pixels per inch, millimeter, and centimeter, respectively. The -@code{width} and @code{height} units correspond to the default width -and height of the current face. An image specification @code{image} -corresponds to the width or height of the image. - - The @code{left-fringe}, @code{right-fringe}, @code{left-margin}, -@code{right-margin}, @code{scroll-bar}, and @code{text} elements -specify to the width of the corresponding area of the window. - - The @code{left}, @code{center}, and @code{right} positions can be -used with @code{:align-to} to specify a position relative to the left -edge, center, or right edge of the text area. - - Any of the above window elements (except @code{text}) can also be -used with @code{:align-to} to specify that the position is relative to -the left edge of the given area. Once the base offset for a relative -position has been set (by the first occurrence of one of these -symbols), further occurrences of these symbols are interpreted as the -width of the specified area. For example, to align to the center of -the left-margin, use - -@example -:align-to (+ left-margin (0.5 . left-margin)) -@end example - - If no specific base offset is set for alignment, it is always relative -to the left edge of the text area. For example, @samp{:align-to 0} in a -header-line aligns with the first text column in the text area. - - A value of the form @code{(@var{num} . @var{expr})} stands for the -product of the values of @var{num} and @var{expr}. For example, -@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 . -@var{image})} specifies half the width (or height) of the specified -image. - - The form @code{(+ @var{expr} ...)} adds up the value of the -expressions. The form @code{(- @var{expr} ...)} negates or subtracts -the value of the expressions. - -@node Other Display Specs -@subsection Other Display Specifications - - Here are the other sorts of display specifications that you can use -in the @code{display} text property. - -@table @code -@item @var{string} -Display @var{string} instead of the text that has this property. - -Recursive display specifications are not supported---@var{string}'s -@code{display} properties, if any, are not used. - -@item (image . @var{image-props}) -This kind of display specification is an image descriptor (@pxref{Images}). -When used as a display specification, it means to display the image -instead of the text that has the display specification. - -@item (slice @var{x} @var{y} @var{width} @var{height}) -This specification together with @code{image} specifies a @dfn{slice} -(a partial area) of the image to display. The elements @var{y} and -@var{x} specify the top left corner of the slice, within the image; -@var{width} and @var{height} specify the width and height of the -slice. Integer values are numbers of pixels. A floating point number -in the range 0.0--1.0 stands for that fraction of the width or height -of the entire image. - -@item ((margin nil) @var{string}) -A display specification of this form means to display @var{string} -instead of the text that has the display specification, at the same -position as that text. It is equivalent to using just @var{string}, -but it is done as a special case of marginal display (@pxref{Display -Margins}). - -@item (space-width @var{factor}) -This display specification affects all the space characters within the -text that has the specification. It displays all of these spaces -@var{factor} times as wide as normal. The element @var{factor} should -be an integer or float. Characters other than spaces are not affected -at all; in particular, this has no effect on tab characters. - -@item (height @var{height}) -This display specification makes the text taller or shorter. -Here are the possibilities for @var{height}: - -@table @asis -@item @code{(+ @var{n})} -This means to use a font that is @var{n} steps larger. A ``step'' is -defined by the set of available fonts---specifically, those that match -what was otherwise specified for this text, in all attributes except -height. Each size for which a suitable font is available counts as -another step. @var{n} should be an integer. - -@item @code{(- @var{n})} -This means to use a font that is @var{n} steps smaller. - -@item a number, @var{factor} -A number, @var{factor}, means to use a font that is @var{factor} times -as tall as the default font. - -@item a symbol, @var{function} -A symbol is a function to compute the height. It is called with the -current height as argument, and should return the new height to use. - -@item anything else, @var{form} -If the @var{height} value doesn't fit the previous possibilities, it is -a form. Emacs evaluates it to get the new height, with the symbol -@code{height} bound to the current specified font height. -@end table - -@item (raise @var{factor}) -This kind of display specification raises or lowers the text -it applies to, relative to the baseline of the line. - -@var{factor} must be a number, which is interpreted as a multiple of the -height of the affected text. If it is positive, that means to display -the characters raised. If it is negative, that means to display them -lower down. - -If the text also has a @code{height} display specification, that does -not affect the amount of raising or lowering, which is based on the -faces used for the text. -@end table - -@c We put all the `@code{(when ...)}' on one line to encourage -@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot -@c was at eol; the info file ended up w/ two spaces rendered after it. - You can make any display specification conditional. To do that, -package it in another list of the form -@code{(when @var{condition} . @var{spec})}. -Then the specification @var{spec} applies only when -@var{condition} evaluates to a non-@code{nil} value. During the -evaluation, @code{object} is bound to the string or buffer having the -conditional @code{display} property. @code{position} and -@code{buffer-position} are bound to the position within @code{object} -and the buffer position where the @code{display} property was found, -respectively. Both positions can be different when @code{object} is a -string. - -@node Display Margins -@subsection Displaying in the Margins -@cindex display margins -@cindex margins, display - - A buffer can have blank areas called @dfn{display margins} on the left -and on the right. Ordinary text never appears in these areas, but you -can put things into the display margins using the @code{display} -property. - - To put text in the left or right display margin of the window, use a -display specification of the form @code{(margin right-margin)} or -@code{(margin left-margin)} on it. To put an image in a display margin, -use that display specification along with the display specification for -the image. Unfortunately, there is currently no way to make -text or images in the margin mouse-sensitive. - - If you put such a display specification directly on text in the -buffer, the specified margin display appears @emph{instead of} that -buffer text itself. To put something in the margin @emph{in -association with} certain buffer text without preventing or altering -the display of that text, put a @code{before-string} property on the -text and put the display specification on the contents of the -before-string. - - Before the display margins can display anything, you must give -them a nonzero width. The usual way to do that is to set these -variables: - -@defvar left-margin-width -This variable specifies the width of the left margin. -It is buffer-local in all buffers. -@end defvar - -@defvar right-margin-width -This variable specifies the width of the right margin. -It is buffer-local in all buffers. -@end defvar - - Setting these variables does not immediately affect the window. These -variables are checked when a new buffer is displayed in the window. -Thus, you can make changes take effect by calling -@code{set-window-buffer}. - - You can also set the margin widths immediately. - -@defun set-window-margins window left &optional right -This function specifies the margin widths for window @var{window}. -The argument @var{left} controls the left margin and -@var{right} controls the right margin (default @code{0}). -@end defun - -@defun window-margins &optional window -This function returns the left and right margins of @var{window} -as a cons cell of the form @code{(@var{left} . @var{right})}. -If @var{window} is @code{nil}, the selected window is used. -@end defun - -@node Images -@section Images -@cindex images in buffers - - To display an image in an Emacs buffer, you must first create an image -descriptor, then use it as a display specifier in the @code{display} -property of text that is displayed (@pxref{Display Property}). - - Emacs is usually able to display images when it is run on a -graphical terminal. Images cannot be displayed in a text terminal, on -certain graphical terminals that lack the support for this, or if -Emacs is compiled without image support. You can use the function -@code{display-images-p} to determine if images can in principle be -displayed (@pxref{Display Feature Testing}). - -@menu -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* PostScript Images:: Special features for PostScript format. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once it is defined. -* Image Cache:: Internal mechanisms of image display. -@end menu - -@node Image Formats -@subsection Image Formats -@cindex image formats -@cindex image types - - Emacs can display a number of different image formats; some of them -are supported only if particular support libraries are installed on -your machine. In some environments, Emacs can load image -libraries on demand; if so, the variable @code{image-library-alist} -can be used to modify the set of known names for these dynamic -libraries (though it is not possible to add new image formats). - - The supported image formats include XBM, XPM (this requires the -libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring -@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the -@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff} -v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring -@code{librsvg} 2.0.0). - - You specify one of these formats with an image type symbol. The image -type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, -@code{pbm}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. - -@defvar image-types -This variable contains a list of those image type symbols that are -potentially supported in the current configuration. -@emph{Potentially} here means that Emacs knows about the image types, -not necessarily that they can be loaded (they could depend on -unavailable dynamic libraries, for example). - -To know which image types are really available, use -@code{image-type-available-p}. -@end defvar - -@defvar image-library-alist -This in an alist of image types vs external libraries needed to -display them. - -Each element is a list @code{(@var{image-type} @var{library}...)}, -where the car is a supported image format from @code{image-types}, and -the rest are strings giving alternate filenames for the corresponding -external libraries to load. - -Emacs tries to load the libraries in the order they appear on the -list; if none is loaded, the running session of Emacs won't support -the image type. @code{pbm} and @code{xbm} don't need to be listed; -they're always supported. - -This variable is ignored if the image libraries are statically linked -into Emacs. -@end defvar - -@defun image-type-available-p type -This function returns non-@code{nil} if image type @var{type} is -available, i.e., if images of this type can be loaded and displayed in -Emacs. @var{type} should be one of the types contained in -@code{image-types}. - -For image types whose support libraries are statically linked, this -function always returns @code{t}; for other image types, it returns -@code{t} if the dynamic library could be loaded, @code{nil} otherwise. -@end defun - -@node Image Descriptors -@subsection Image Descriptors -@cindex image descriptor - - An image description is a list of the form @code{(image . @var{props})}, -where @var{props} is a property list containing alternating keyword -symbols (symbols whose names start with a colon) and their values. -You can use any Lisp object as a property, but the only properties -that have any special meaning are certain symbols, all of them keywords. - - Every image descriptor must contain the property @code{:type -@var{type}} to specify the format of the image. The value of @var{type} -should be an image type symbol; for example, @code{xpm} for an image in -XPM format. - - Here is a list of other properties that are meaningful for all image -types: - -@table @code -@item :file @var{file} -The @code{:file} property says to load the image from file -@var{file}. If @var{file} is not an absolute file name, it is expanded -in @code{data-directory}. - -@item :data @var{data} -The @code{:data} property says the actual contents of the image. -Each image must use either @code{:data} or @code{:file}, but not both. -For most image types, the value of the @code{:data} property should be a -string containing the image data; we recommend using a unibyte string. - -Before using @code{:data}, look for further information in the section -below describing the specific image format. For some image types, -@code{:data} may not be supported; for some, it allows other data types; -for some, @code{:data} alone is not enough, so you need to use other -image properties along with @code{:data}. - -@item :margin @var{margin} -The @code{:margin} property specifies how many pixels to add as an -extra margin around the image. The value, @var{margin}, must be a -non-negative number, or a pair @code{(@var{x} . @var{y})} of such -numbers. If it is a pair, @var{x} specifies how many pixels to add -horizontally, and @var{y} specifies how many pixels to add vertically. -If @code{:margin} is not specified, the default is zero. - -@item :ascent @var{ascent} -The @code{:ascent} property specifies the amount of the image's -height to use for its ascent---that is, the part above the baseline. -The value, @var{ascent}, must be a number in the range 0 to 100, or -the symbol @code{center}. - -If @var{ascent} is a number, that percentage of the image's height is -used for its ascent. - -If @var{ascent} is @code{center}, the image is vertically centered -around a centerline which would be the vertical centerline of text drawn -at the position of the image, in the manner specified by the text -properties and overlays that apply to the image. - -If this property is omitted, it defaults to 50. - -@item :relief @var{relief} -The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle -around the image. The value, @var{relief}, specifies the width of the -shadow lines, in pixels. If @var{relief} is negative, shadows are drawn -so that the image appears as a pressed button; otherwise, it appears as -an unpressed button. - -@item :conversion @var{algorithm} -The @code{:conversion} property, if non-@code{nil}, specifies a -conversion algorithm that should be applied to the image before it is -displayed; the value, @var{algorithm}, specifies which algorithm. - -@table @code -@item laplace -@itemx emboss -Specifies the Laplace edge detection algorithm, which blurs out small -differences in color while highlighting larger differences. People -sometimes consider this useful for displaying the image for a -``disabled'' button. - -@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust}) -Specifies a general edge-detection algorithm. @var{matrix} must be -either a nine-element list or a nine-element vector of numbers. A pixel -at position @math{x/y} in the transformed image is computed from -original pixels around that position. @var{matrix} specifies, for each -pixel in the neighborhood of @math{x/y}, a factor with which that pixel -will influence the transformed pixel; element @math{0} specifies the -factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for -the pixel at @math{x/y-1} etc., as shown below: -@iftex -@tex -$$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr - x-1/y & x/y & x+1/y \cr - x-1/y+1& x/y+1 & x+1/y+1 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - (x-1/y-1 x/y-1 x+1/y-1 - x-1/y x/y x+1/y - x-1/y+1 x/y+1 x+1/y+1) -@end display -@end ifnottex - -The resulting pixel is computed from the color intensity of the color -resulting from summing up the RGB values of surrounding pixels, -multiplied by the specified factors, and dividing that sum by the sum -of the factors' absolute values. - -Laplace edge-detection currently uses a matrix of -@iftex -@tex -$$\pmatrix{1 & 0 & 0 \cr - 0& 0 & 0 \cr - 9 & 9 & -1 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - (1 0 0 - 0 0 0 - 9 9 -1) -@end display -@end ifnottex - -Emboss edge-detection uses a matrix of -@iftex -@tex -$$\pmatrix{ 2 & -1 & 0 \cr - -1 & 0 & 1 \cr - 0 & 1 & -2 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - ( 2 -1 0 - -1 0 1 - 0 1 -2) -@end display -@end ifnottex - -@item disabled -Specifies transforming the image so that it looks ``disabled.'' -@end table - -@item :mask @var{mask} -If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build -a clipping mask for the image, so that the background of a frame is -visible behind the image. If @var{bg} is not specified, or if @var{bg} -is @code{t}, determine the background color of the image by looking at -the four corners of the image, assuming the most frequently occurring -color from the corners is the background color of the image. Otherwise, -@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})} -specifying the color to assume for the background of the image. - -If @var{mask} is @code{nil}, remove a mask from the image, if it has -one. Images in some formats include a mask which can be removed by -specifying @code{:mask nil}. - -@item :pointer @var{shape} -This specifies the pointer shape when the mouse pointer is over this -image. @xref{Pointer Shape}, for available pointer shapes. - -@item :map @var{map} -This associates an image map of @dfn{hot spots} with this image. - -An image map is an alist where each element has the format -@code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified -as either a rectangle, a circle, or a polygon. - -A rectangle is a cons -@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))} -which specifies the pixel coordinates of the upper left and bottom right -corners of the rectangle area. - -A circle is a cons -@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))} -which specifies the center and the radius of the circle; @var{r} may -be a float or integer. - -A polygon is a cons -@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])} -where each pair in the vector describes one corner in the polygon. - -When the mouse pointer lies on a hot-spot area of an image, the -@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo} -property, that defines a tool-tip for the hot-spot, and if it contains -a @code{pointer} property, that defines the shape of the mouse cursor when -it is on the hot-spot. -@xref{Pointer Shape}, for available pointer shapes. - -When you click the mouse when the mouse pointer is over a hot-spot, an -event is composed by combining the @var{id} of the hot-spot with the -mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's -@var{id} is @code{area4}. -@end table - -@defun image-mask-p spec &optional frame -This function returns @code{t} if image @var{spec} has a mask bitmap. -@var{frame} is the frame on which the image will be displayed. -@var{frame} @code{nil} or omitted means to use the selected frame -(@pxref{Input Focus}). -@end defun - -@node XBM Images -@subsection XBM Images -@cindex XBM - - To use XBM format, specify @code{xbm} as the image type. This image -format doesn't require an external library, so images of this type are -always supported. - - Additional image properties supported for the @code{xbm} image type are: - -@table @code -@item :foreground @var{foreground} -The value, @var{foreground}, should be a string specifying the image -foreground color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 1. The default is the frame's -foreground color. - -@item :background @var{background} -The value, @var{background}, should be a string specifying the image -background color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 0. The default is the frame's -background color. -@end table - - If you specify an XBM image using data within Emacs instead of an -external file, use the following three properties: - -@table @code -@item :data @var{data} -The value, @var{data}, specifies the contents of the image. -There are three formats you can use for @var{data}: - -@itemize @bullet -@item -A vector of strings or bool-vectors, each specifying one line of the -image. Do specify @code{:height} and @code{:width}. - -@item -A string containing the same byte sequence as an XBM file would contain. -You must not specify @code{:height} and @code{:width} in this case, -because omitting them is what indicates the data has the format of an -XBM file. The file contents specify the height and width of the image. - -@item -A string or a bool-vector containing the bits of the image (plus perhaps -some extra bits at the end that will not be used). It should contain at -least @var{width} * @code{height} bits. In this case, you must specify -@code{:height} and @code{:width}, both to indicate that the string -contains just the bits rather than a whole XBM file, and to specify the -size of the image. -@end itemize - -@item :width @var{width} -The value, @var{width}, specifies the width of the image, in pixels. - -@item :height @var{height} -The value, @var{height}, specifies the height of the image, in pixels. -@end table - -@node XPM Images -@subsection XPM Images -@cindex XPM - - To use XPM format, specify @code{xpm} as the image type. The -additional image property @code{:color-symbols} is also meaningful with -the @code{xpm} image type: - -@table @code -@item :color-symbols @var{symbols} -The value, @var{symbols}, should be an alist whose elements have the -form @code{(@var{name} . @var{color})}. In each element, @var{name} is -the name of a color as it appears in the image file, and @var{color} -specifies the actual color to use for displaying that name. -@end table - -@node GIF Images -@subsection GIF Images -@cindex GIF - - For GIF images, specify image type @code{gif}. - -@table @code -@item :index @var{index} -You can use @code{:index} to specify one image from a GIF file that -contains more than one image. This property specifies use of image -number @var{index} from the file. If the GIF file doesn't contain an -image with index @var{index}, the image displays as a hollow box. -@end table - -@ignore -This could be used to implement limited support for animated GIFs. -For example, the following function displays a multi-image GIF file -at point-min in the current buffer, switching between sub-images -every 0.1 seconds. - -(defun show-anim (file max) - "Display multi-image GIF file FILE which contains MAX subimages." - (display-anim (current-buffer) file 0 max t)) - -(defun display-anim (buffer file idx max first-time) - (when (= idx max) - (setq idx 0)) - (let ((img (create-image file nil :image idx))) - (save-excursion - (set-buffer buffer) - (goto-char (point-min)) - (unless first-time (delete-char 1)) - (insert-image img)) - (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil))) -@end ignore - -@node PostScript Images -@subsection PostScript Images -@cindex postscript images - - To use PostScript for an image, specify image type @code{postscript}. -This works only if you have Ghostscript installed. You must always use -these three properties: - -@table @code -@item :pt-width @var{width} -The value, @var{width}, specifies the width of the image measured in -points (1/72 inch). @var{width} must be an integer. - -@item :pt-height @var{height} -The value, @var{height}, specifies the height of the image in points -(1/72 inch). @var{height} must be an integer. - -@item :bounding-box @var{box} -The value, @var{box}, must be a list or vector of four integers, which -specifying the bounding box of the PostScript image, analogous to the -@samp{BoundingBox} comment found in PostScript files. - -@example -%%BoundingBox: 22 171 567 738 -@end example -@end table - - Displaying PostScript images from Lisp data is not currently -implemented, but it may be implemented by the time you read this. -See the @file{etc/NEWS} file to make sure. - -@node Other Image Types -@subsection Other Image Types -@cindex PBM - - For PBM images, specify image type @code{pbm}. Color, gray-scale and -monochromatic images are supported. For mono PBM images, two additional -image properties are supported. - -@table @code -@item :foreground @var{foreground} -The value, @var{foreground}, should be a string specifying the image -foreground color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 1. The default is the frame's -foreground color. - -@item :background @var{background} -The value, @var{background}, should be a string specifying the image -background color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 0. The default is the frame's -background color. -@end table - - For JPEG images, specify image type @code{jpeg}. - - For TIFF images, specify image type @code{tiff}. - - For PNG images, specify image type @code{png}. - - For SVG images, specify image type @code{svg}. - -@node Defining Images -@subsection Defining Images - - The functions @code{create-image}, @code{defimage} and -@code{find-image} provide convenient ways to create image descriptors. - -@defun create-image file-or-data &optional type data-p &rest props -This function creates and returns an image descriptor which uses the -data in @var{file-or-data}. @var{file-or-data} can be a file name or -a string containing the image data; @var{data-p} should be @code{nil} -for the former case, non-@code{nil} for the latter case. - -The optional argument @var{type} is a symbol specifying the image type. -If @var{type} is omitted or @code{nil}, @code{create-image} tries to -determine the image type from the file's first few bytes, or else -from the file's name. - -The remaining arguments, @var{props}, specify additional image -properties---for example, - -@example -(create-image "foo.xpm" 'xpm nil :heuristic-mask t) -@end example - -The function returns @code{nil} if images of this type are not -supported. Otherwise it returns an image descriptor. -@end defun - -@defmac defimage symbol specs &optional doc -This macro defines @var{symbol} as an image name. The arguments -@var{specs} is a list which specifies how to display the image. -The third argument, @var{doc}, is an optional documentation string. - -Each argument in @var{specs} has the form of a property list, and each -one should specify at least the @code{:type} property and either the -@code{:file} or the @code{:data} property. The value of @code{:type} -should be a symbol specifying the image type, the value of -@code{:file} is the file to load the image from, and the value of -@code{:data} is a string containing the actual image data. Here is an -example: - -@example -(defimage test-image - ((:type xpm :file "~/test1.xpm") - (:type xbm :file "~/test1.xbm"))) -@end example - -@code{defimage} tests each argument, one by one, to see if it is -usable---that is, if the type is supported and the file exists. The -first usable argument is used to make an image descriptor which is -stored in @var{symbol}. - -If none of the alternatives will work, then @var{symbol} is defined -as @code{nil}. -@end defmac - -@defun find-image specs -This function provides a convenient way to find an image satisfying one -of a list of image specifications @var{specs}. - -Each specification in @var{specs} is a property list with contents -depending on image type. All specifications must at least contain the -properties @code{:type @var{type}} and either @w{@code{:file @var{file}}} -or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying -the image type, e.g.@: @code{xbm}, @var{file} is the file to load the -image from, and @var{data} is a string containing the actual image data. -The first specification in the list whose @var{type} is supported, and -@var{file} exists, is used to construct the image specification to be -returned. If no specification is satisfied, @code{nil} is returned. - -The image is looked for in @code{image-load-path}. -@end defun - -@defvar image-load-path -This variable's value is a list of locations in which to search for -image files. If an element is a string or a variable symbol whose -value is a string, the string is taken to be the name of a directory -to search. If an element is a variable symbol whose value is a list, -that is taken to be a list of directory names to search. - -The default is to search in the @file{images} subdirectory of the -directory specified by @code{data-directory}, then the directory -specified by @code{data-directory}, and finally in the directories in -@code{load-path}. Subdirectories are not automatically included in -the search, so if you put an image file in a subdirectory, you have to -supply the subdirectory name explicitly. For example, to find the -image @file{images/foo/bar.xpm} within @code{data-directory}, you -should specify the image as follows: - -@example -(defimage foo-image '((:type xpm :file "foo/bar.xpm"))) -@end example -@end defvar - -@defun image-load-path-for-library library image &optional path no-error -This function returns a suitable search path for images used by the -Lisp package @var{library}. - -The function searches for @var{image} first using @code{image-load-path}, -excluding @file{@code{data-directory}/images}, and then in -@code{load-path}, followed by a path suitable for @var{library}, which -includes @file{../../etc/images} and @file{../etc/images} relative to -the library file itself, and finally in -@file{@code{data-directory}/images}. - -Then this function returns a list of directories which contains first -the directory in which @var{image} was found, followed by the value of -@code{load-path}. If @var{path} is given, it is used instead of -@code{load-path}. - -If @var{no-error} is non-@code{nil} and a suitable path can't be -found, don't signal an error. Instead, return a list of directories as -before, except that @code{nil} appears in place of the image directory. - -Here is an example that uses a common idiom to provide compatibility -with versions of Emacs that lack the variable @code{image-load-path}: - -@example -(defvar image-load-path) ; shush compiler -(let* ((load-path (image-load-path-for-library - "mh-e" "mh-logo.xpm")) - (image-load-path (cons (car load-path) - (when (boundp 'image-load-path) - image-load-path)))) - (mh-tool-bar-folder-buttons-init)) -@end example -@end defun - -@node Showing Images -@subsection Showing Images - - You can use an image descriptor by setting up the @code{display} -property yourself, but it is easier to use the functions in this -section. - -@defun insert-image image &optional string area slice -This function inserts @var{image} in the current buffer at point. The -value @var{image} should be an image descriptor; it could be a value -returned by @code{create-image}, or the value of a symbol defined with -@code{defimage}. The argument @var{string} specifies the text to put -in the buffer to hold the image. If it is omitted or @code{nil}, -@code{insert-image} uses @code{" "} by default. - -The argument @var{area} specifies whether to put the image in a margin. -If it is @code{left-margin}, the image appears in the left margin; -@code{right-margin} specifies the right margin. If @var{area} is -@code{nil} or omitted, the image is displayed at point within the -buffer's text. - -The argument @var{slice} specifies a slice of the image to insert. If -@var{slice} is @code{nil} or omitted the whole image is inserted. -Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width} -@var{height})} which specifies the @var{x} and @var{y} positions and -@var{width} and @var{height} of the image area to insert. Integer -values are in units of pixels. A floating point number in the range -0.0--1.0 stands for that fraction of the width or height of the entire -image. - -Internally, this function inserts @var{string} in the buffer, and gives -it a @code{display} property which specifies @var{image}. @xref{Display -Property}. -@end defun - -@defun insert-sliced-image image &optional string area rows cols -This function inserts @var{image} in the current buffer at point, like -@code{insert-image}, but splits the image into @var{rows}x@var{cols} -equally sized slices. -@end defun - -@defun put-image image pos &optional string area -This function puts image @var{image} in front of @var{pos} in the -current buffer. The argument @var{pos} should be an integer or a -marker. It specifies the buffer position where the image should appear. -The argument @var{string} specifies the text that should hold the image -as an alternative to the default. - -The argument @var{image} must be an image descriptor, perhaps returned -by @code{create-image} or stored by @code{defimage}. - -The argument @var{area} specifies whether to put the image in a margin. -If it is @code{left-margin}, the image appears in the left margin; -@code{right-margin} specifies the right margin. If @var{area} is -@code{nil} or omitted, the image is displayed at point within the -buffer's text. - -Internally, this function creates an overlay, and gives it a -@code{before-string} property containing text that has a @code{display} -property whose value is the image. (Whew!) -@end defun - -@defun remove-images start end &optional buffer -This function removes images in @var{buffer} between positions -@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil}, -images are removed from the current buffer. - -This removes only images that were put into @var{buffer} the way -@code{put-image} does it, not images that were inserted with -@code{insert-image} or in other ways. -@end defun - -@defun image-size spec &optional pixels frame -This function returns the size of an image as a pair -@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image -specification. @var{pixels} non-@code{nil} means return sizes -measured in pixels, otherwise return sizes measured in canonical -character units (fractions of the width/height of the frame's default -font). @var{frame} is the frame on which the image will be displayed. -@var{frame} null or omitted means use the selected frame (@pxref{Input -Focus}). -@end defun - -@defvar max-image-size -This variable is used to define the maximum size of image that Emacs -will load. Emacs will refuse to load (and display) any image that is -larger than this limit. - -If the value is an integer, it directly specifies the maximum -image height and width, measured in pixels. If it is a floating -point number, it specifies the maximum image height and width -as a ratio to the frame height and width. If the value is -non-numeric, there is no explicit limit on the size of images. - -The purpose of this variable is to prevent unreasonably large images -from accidentally being loaded into Emacs. It only takes effect the -first time an image is loaded. Once an image is placed in the image -cache, it can always be displayed, even if the value of -@var{max-image-size} is subsequently changed (@pxref{Image Cache}). -@end defvar - -@node Image Cache -@subsection Image Cache -@cindex image cache - - Emacs stores images in an image cache so that it can display them -again more efficiently. When Emacs displays an image, it searches the -image cache for an existing image specification @code{equal} to the -desired specification. If a match is found, the image is displayed -from the cache; otherwise, Emacs loads the image normally. - - Occasionally, you may need to tell Emacs to refresh the images -associated with a given image specification. For example, suppose you -display an image using a specification that contains a @code{:file} -property. The image is loaded from the given file and stored in the -image cache. If you later display the image again, using the same -image specification, the image is displayed from the image cache. -Normally, this is not a problem. However, if the image file has -changed in the meantime, Emacs would be displaying the old version of -the image. In such a situation, it is necessary to ``refresh'' the -image using @code{image-refresh}. - -@defun image-refresh spec &optional frame -This function refreshes any images having image specifications -@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is -@code{nil}, the selected frame is used. If @var{frame} is @code{t}, -the refresh is applied to all existing frames. - -This works by removing all image with image specifications matching -@var{spec} from the image cache. Thus, the next time the image is -displayed, Emacs will load the image again. -@end defun - -@defun clear-image-cache &optional frame -This function clears the entire image cache. If @var{frame} is -non-@code{nil}, only the cache for that frame is cleared. Otherwise, -all frames' caches are cleared. -@end defun - -If an image in the image cache has not been displayed for a specified -period of time, Emacs removes it from the cache and frees the -associated memory. - -@defvar image-cache-eviction-delay -This variable specifies the number of seconds an image can remain in the -cache without being displayed. When an image is not displayed for this -length of time, Emacs removes it from the image cache. - -If the value is @code{nil}, Emacs does not remove images from the cache -except when you explicitly clear it. This mode can be useful for -debugging. -@end defvar - -@node Buttons -@section Buttons -@cindex buttons in buffers -@cindex clickable buttons in buffers - - The @emph{button} package defines functions for inserting and -manipulating clickable (with the mouse, or via keyboard commands) -buttons in Emacs buffers, such as might be used for help hyper-links, -etc. Emacs uses buttons for the hyper-links in help text and the like. - - A button is essentially a set of properties attached (via text -properties or overlays) to a region of text in an Emacs buffer. These -properties are called @dfn{button properties}. - - One of these properties (@code{action}) is a function, which will -be called when the user invokes it using the keyboard or the mouse. -The invoked function may then examine the button and use its other -properties as desired. - - In some ways the Emacs button package duplicates functionality offered -by the widget package (@pxref{Top, , Introduction, widget, The Emacs -Widget Library}), but the button package has the advantage that it is -much faster, much smaller, and much simpler to use (for elisp -programmers---for users, the result is about the same). The extra -speed and space savings are useful mainly if you need to create many -buttons in a buffer (for instance an @code{*Apropos*} buffer uses -buttons to make entries clickable, and may contain many thousands of -entries). - -@menu -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. -@end menu - -@node Button Properties -@subsection Button Properties -@cindex button properties - - Buttons have an associated list of properties defining their -appearance and behavior, and other arbitrary properties may be used -for application specific purposes. Some properties that have special -meaning to the button package include: - -@table @code -@item action -@kindex action @r{(button property)} -The function to call when the user invokes the button, which is passed -the single argument @var{button}. By default this is @code{ignore}, -which does nothing. - -@item mouse-action -@kindex mouse-action @r{(button property)} -This is similar to @code{action}, and when present, will be used -instead of @code{action} for button invocations resulting from -mouse-clicks (instead of the user hitting @key{RET}). If not -present, mouse-clicks use @code{action} instead. - -@item face -@kindex face @r{(button property)} -This is an Emacs face controlling how buttons of this type are -displayed; by default this is the @code{button} face. - -@item mouse-face -@kindex mouse-face @r{(button property)} -This is an additional face which controls appearance during -mouse-overs (merged with the usual button face); by default this is -the usual Emacs @code{highlight} face. - -@item keymap -@kindex keymap @r{(button property)} -The button's keymap, defining bindings active within the button -region. By default this is the usual button region keymap, stored -in the variable @code{button-map}, which defines @key{RET} and -@key{mouse-2} to invoke the button. - -@item type -@kindex type @r{(button property)} -The button-type of the button. When creating a button, this is -usually specified using the @code{:type} keyword argument. -@xref{Button Types}. - -@item help-echo -@kindex help-index @r{(button property)} -A string displayed by the Emacs tool-tip help system; by default, -@code{"mouse-2, RET: Push this button"}. - -@item follow-link -@kindex follow-link @r{(button property)} -The follow-link property, defining how a @key{Mouse-1} click behaves -on this button, @xref{Links and Mouse-1}. - -@item button -@kindex button @r{(button property)} -All buttons have a non-@code{nil} @code{button} property, which may be useful -in finding regions of text that comprise buttons (which is what the -standard button functions do). -@end table - - There are other properties defined for the regions of text in a -button, but these are not generally interesting for typical uses. - -@node Button Types -@subsection Button Types -@cindex button types - - Every button has a button @emph{type}, which defines default values -for the button's properties. Button types are arranged in a -hierarchy, with specialized types inheriting from more general types, -so that it's easy to define special-purpose types of buttons for -specific tasks. - -@defun define-button-type name &rest properties -Define a `button type' called @var{name}. The remaining arguments -form a sequence of @var{property value} pairs, specifying default -property values for buttons with this type (a button's type may be set -by giving it a @code{type} property when creating the button, using -the @code{:type} keyword argument). - -In addition, the keyword argument @code{:supertype} may be used to -specify a button-type from which @var{name} inherits its default -property values. Note that this inheritance happens only when -@var{name} is defined; subsequent changes to a supertype are not -reflected in its subtypes. -@end defun - - Using @code{define-button-type} to define default properties for -buttons is not necessary---buttons without any specified type use the -built-in button-type @code{button}---but it is encouraged, since -doing so usually makes the resulting code clearer and more efficient. - -@node Making Buttons -@subsection Making Buttons -@cindex making buttons - - Buttons are associated with a region of text, using an overlay or -text properties to hold button-specific information, all of which are -initialized from the button's type (which defaults to the built-in -button type @code{button}). Like all Emacs text, the appearance of -the button is governed by the @code{face} property; by default (via -the @code{face} property inherited from the @code{button} button-type) -this is a simple underline, like a typical web-page link. - - For convenience, there are two sorts of button-creation functions, -those that add button properties to an existing region of a buffer, -called @code{make-...button}, and those that also insert the button -text, called @code{insert-...button}. - - The button-creation functions all take the @code{&rest} argument -@var{properties}, which should be a sequence of @var{property value} -pairs, specifying properties to add to the button; see @ref{Button -Properties}. In addition, the keyword argument @code{:type} may be -used to specify a button-type from which to inherit other properties; -see @ref{Button Types}. Any properties not explicitly specified -during creation will be inherited from the button's type (if the type -defines such a property). - - The following functions add a button using an overlay -(@pxref{Overlays}) to hold the button properties: - -@defun make-button beg end &rest properties -This makes a button from @var{beg} to @var{end} in the -current buffer, and returns it. -@end defun - -@defun insert-button label &rest properties -This insert a button with the label @var{label} at point, -and returns it. -@end defun - - The following functions are similar, but use Emacs text properties -(@pxref{Text Properties}) to hold the button properties, making the -button actually part of the text instead of being a property of the -buffer. Buttons using text properties do not create markers into the -buffer, which is important for speed when you use extremely large -numbers of buttons. Both functions return the position of the start -of the new button: - -@defun make-text-button beg end &rest properties -This makes a button from @var{beg} to @var{end} in the current buffer, using -text properties. -@end defun - -@defun insert-text-button label &rest properties -This inserts a button with the label @var{label} at point, using text -properties. -@end defun - -@node Manipulating Buttons -@subsection Manipulating Buttons -@cindex manipulating buttons - -These are functions for getting and setting properties of buttons. -Often these are used by a button's invocation function to determine -what to do. - -Where a @var{button} parameter is specified, it means an object -referring to a specific button, either an overlay (for overlay -buttons), or a buffer-position or marker (for text property buttons). -Such an object is passed as the first argument to a button's -invocation function when it is invoked. - -@defun button-start button -Return the position at which @var{button} starts. -@end defun - -@defun button-end button -Return the position at which @var{button} ends. -@end defun - -@defun button-get button prop -Get the property of button @var{button} named @var{prop}. -@end defun - -@defun button-put button prop val -Set @var{button}'s @var{prop} property to @var{val}. -@end defun - -@defun button-activate button &optional use-mouse-action -Call @var{button}'s @code{action} property (i.e., invoke it). If -@var{use-mouse-action} is non-@code{nil}, try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. -@end defun - -@defun button-label button -Return @var{button}'s text label. -@end defun - -@defun button-type button -Return @var{button}'s button-type. -@end defun - -@defun button-has-type-p button type -Return @code{t} if @var{button} has button-type @var{type}, or one of -@var{type}'s subtypes. -@end defun - -@defun button-at pos -Return the button at position @var{pos} in the current buffer, or @code{nil}. -@end defun - -@defun button-type-put type prop val -Set the button-type @var{type}'s @var{prop} property to @var{val}. -@end defun - -@defun button-type-get type prop -Get the property of button-type @var{type} named @var{prop}. -@end defun - -@defun button-type-subtype-p type supertype -Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. -@end defun - -@node Button Buffer Commands -@subsection Button Buffer Commands -@cindex button buffer commands - -These are commands and functions for locating and operating on -buttons in an Emacs buffer. - -@code{push-button} is the command that a user uses to actually `push' -a button, and is bound by default in the button itself to @key{RET} -and to @key{mouse-2} using a region-specific keymap. Commands -that are useful outside the buttons itself, such as -@code{forward-button} and @code{backward-button} are additionally -available in the keymap stored in @code{button-buffer-map}; a mode -which uses buttons may want to use @code{button-buffer-map} as a -parent keymap for its keymap. - -If the button has a non-@code{nil} @code{follow-link} property, and -@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click -will also activate the @code{push-button} command. -@xref{Links and Mouse-1}. - -@deffn Command push-button &optional pos use-mouse-action -Perform the action specified by a button at location @var{pos}. -@var{pos} may be either a buffer position or a mouse-event. If -@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a -mouse-event (@pxref{Mouse Events}), try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. -@var{pos} defaults to point, except when @code{push-button} is invoked -interactively as the result of a mouse-event, in which case, the mouse -event's position is used. If there's no button at @var{pos}, do -nothing and return @code{nil}, otherwise return @code{t}. -@end deffn - -@deffn Command forward-button n &optional wrap display-message -Move to the @var{n}th next button, or @var{n}th previous button if -@var{n} is negative. If @var{n} is zero, move to the start of any -button at point. If @var{wrap} is non-@code{nil}, moving past either -end of the buffer continues from the other end. If -@var{display-message} is non-@code{nil}, the button's help-echo string -is displayed. Any button with a non-@code{nil} @code{skip} property -is skipped over. Returns the button found. -@end deffn - -@deffn Command backward-button n &optional wrap display-message -Move to the @var{n}th previous button, or @var{n}th next button if -@var{n} is negative. If @var{n} is zero, move to the start of any -button at point. If @var{wrap} is non-@code{nil}, moving past either -end of the buffer continues from the other end. If -@var{display-message} is non-@code{nil}, the button's help-echo string -is displayed. Any button with a non-@code{nil} @code{skip} property -is skipped over. Returns the button found. -@end deffn - -@defun next-button pos &optional count-current -@defunx previous-button pos &optional count-current -Return the next button after (for @code{next-button} or before (for -@code{previous-button}) position @var{pos} in the current buffer. If -@var{count-current} is non-@code{nil}, count any button at @var{pos} -in the search, instead of starting at the next button. -@end defun - -@node Abstract Display -@section Abstract Display -@cindex ewoc -@cindex display, abstract -@cindex display, arbitrary objects -@cindex model/view/controller -@cindex view part, model/view/controller - - The Ewoc package constructs buffer text that represents a structure -of Lisp objects, and updates the text to follow changes in that -structure. This is like the ``view'' component in the -``model/view/controller'' design paradigm. - - An @dfn{ewoc} is a structure that organizes information required to -construct buffer text that represents certain Lisp data. The buffer -text of the ewoc has three parts, in order: first, fixed @dfn{header} -text; next, textual descriptions of a series of data elements (Lisp -objects that you specify); and last, fixed @dfn{footer} text. -Specifically, an ewoc contains information on: - -@itemize @bullet -@item -The buffer which its text is generated in. - -@item -The text's start position in the buffer. - -@item -The header and footer strings. - -@item -A doubly-linked chain of @dfn{nodes}, each of which contains: - -@itemize -@item -A @dfn{data element}, a single Lisp object. - -@item -Links to the preceding and following nodes in the chain. -@end itemize - -@item -A @dfn{pretty-printer} function which is responsible for -inserting the textual representation of a data -element value into the current buffer. -@end itemize - - Typically, you define an ewoc with @code{ewoc-create}, and then pass -the resulting ewoc structure to other functions in the Ewoc package to -build nodes within it, and display it in the buffer. Once it is -displayed in the buffer, other functions determine the correspondance -between buffer positions and nodes, move point from one node's textual -representation to another, and so forth. @xref{Abstract Display -Functions}. - - A node @dfn{encapsulates} a data element much the way a variable -holds a value. Normally, encapsulation occurs as a part of adding a -node to the ewoc. You can retrieve the data element value and place a -new value in its place, like so: - -@lisp -(ewoc-data @var{node}) -@result{} value - -(ewoc-set-data @var{node} @var{new-value}) -@result{} @var{new-value} -@end lisp - -@noindent -You can also use, as the data element value, a Lisp object (list or -vector) that is a container for the ``real'' value, or an index into -some other structure. The example (@pxref{Abstract Display Example}) -uses the latter approach. - - When the data changes, you will want to update the text in the -buffer. You can update all nodes by calling @code{ewoc-refresh}, or -just specific nodes using @code{ewoc-invalidate}, or all nodes -satisfying a predicate using @code{ewoc-map}. Alternatively, you can -delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter}, -and add new nodes in their place. Deleting a node from an ewoc deletes -its associated textual description from buffer, as well. - -@menu -* Abstract Display Functions:: -* Abstract Display Example:: -@end menu - -@node Abstract Display Functions -@subsection Abstract Display Functions - - In this subsection, @var{ewoc} and @var{node} stand for the -structures described above (@pxref{Abstract Display}), while -@var{data} stands for an arbitrary Lisp object used as a data element. - -@defun ewoc-create pretty-printer &optional header footer nosep -This constructs and returns a new ewoc, with no nodes (and thus no data -elements). @var{pretty-printer} should be a function that takes one -argument, a data element of the sort you plan to use in this ewoc, and -inserts its textual description at point using @code{insert} (and never -@code{insert-before-markers}, because that would interfere with the -Ewoc package's internal mechanisms). - -Normally, a newline is automatically inserted after the header, -the footer and every node's textual description. If @var{nosep} -is non-@code{nil}, no newline is inserted. This may be useful for -displaying an entire ewoc on a single line, for example, or for -making nodes ``invisible'' by arranging for @var{pretty-printer} -to do nothing for those nodes. - -An ewoc maintains its text in the buffer that is current when -you create it, so switch to the intended buffer before calling -@code{ewoc-create}. -@end defun - -@defun ewoc-buffer ewoc -This returns the buffer where @var{ewoc} maintains its text. -@end defun - -@defun ewoc-get-hf ewoc -This returns a cons cell @code{(@var{header} . @var{footer})} -made from @var{ewoc}'s header and footer. -@end defun - -@defun ewoc-set-hf ewoc header footer -This sets the header and footer of @var{ewoc} to the strings -@var{header} and @var{footer}, respectively. -@end defun - -@defun ewoc-enter-first ewoc data -@defunx ewoc-enter-last ewoc data -These add a new node encapsulating @var{data}, putting it, respectively, -at the beginning or end of @var{ewoc}'s chain of nodes. -@end defun - -@defun ewoc-enter-before ewoc node data -@defunx ewoc-enter-after ewoc node data -These add a new node encapsulating @var{data}, adding it to -@var{ewoc} before or after @var{node}, respectively. -@end defun - -@defun ewoc-prev ewoc node -@defunx ewoc-next ewoc node -These return, respectively, the previous node and the next node of @var{node} -in @var{ewoc}. -@end defun - -@defun ewoc-nth ewoc n -This returns the node in @var{ewoc} found at zero-based index @var{n}. -A negative @var{n} means count from the end. @code{ewoc-nth} returns -@code{nil} if @var{n} is out of range. -@end defun - -@defun ewoc-data node -This extracts the data encapsulated by @var{node} and returns it. -@end defun - -@defun ewoc-set-data node data -This sets the data encapsulated by @var{node} to @var{data}. -@end defun - -@defun ewoc-locate ewoc &optional pos guess -This determines the node in @var{ewoc} which contains point (or -@var{pos} if specified), and returns that node. If @var{ewoc} has no -nodes, it returns @code{nil}. If @var{pos} is before the first node, -it returns the first node; if @var{pos} is after the last node, it returns -the last node. The optional third arg @var{guess} -should be a node that is likely to be near @var{pos}; this doesn't -alter the result, but makes the function run faster. -@end defun - -@defun ewoc-location node -This returns the start position of @var{node}. -@end defun - -@defun ewoc-goto-prev ewoc arg -@defunx ewoc-goto-next ewoc arg -These move point to the previous or next, respectively, @var{arg}th node -in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at -the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} -moves past the last node, returning @code{nil}. Excepting this special -case, these functions return the node moved to. -@end defun - -@defun ewoc-goto-node ewoc node -This moves point to the start of @var{node} in @var{ewoc}. -@end defun - -@defun ewoc-refresh ewoc -This function regenerates the text of @var{ewoc}. It works by -deleting the text between the header and the footer, i.e., all the -data elements' representations, and then calling the pretty-printer -function for each node, one by one, in order. -@end defun - -@defun ewoc-invalidate ewoc &rest nodes -This is similar to @code{ewoc-refresh}, except that only @var{nodes} in -@var{ewoc} are updated instead of the entire set. -@end defun - -@defun ewoc-delete ewoc &rest nodes -This deletes each node in @var{nodes} from @var{ewoc}. -@end defun - -@defun ewoc-filter ewoc predicate &rest args -This calls @var{predicate} for each data element in @var{ewoc} and -deletes those nodes for which @var{predicate} returns @code{nil}. -Any @var{args} are passed to @var{predicate}. -@end defun - -@defun ewoc-collect ewoc predicate &rest args -This calls @var{predicate} for each data element in @var{ewoc} -and returns a list of those elements for which @var{predicate} -returns non-@code{nil}. The elements in the list are ordered -as in the buffer. Any @var{args} are passed to @var{predicate}. -@end defun - -@defun ewoc-map map-function ewoc &rest args -This calls @var{map-function} for each data element in @var{ewoc} and -updates those nodes for which @var{map-function} returns non-@code{nil}. -Any @var{args} are passed to @var{map-function}. -@end defun - -@node Abstract Display Example -@subsection Abstract Display Example - - Here is a simple example using functions of the ewoc package to -implement a ``color components display,'' an area in a buffer that -represents a vector of three integers (itself representing a 24-bit RGB -value) in various ways. - -@example -(setq colorcomp-ewoc nil - colorcomp-data nil - colorcomp-mode-map nil - colorcomp-labels ["Red" "Green" "Blue"]) - -(defun colorcomp-pp (data) - (if data - (let ((comp (aref colorcomp-data data))) - (insert (aref colorcomp-labels data) "\t: #x" - (format "%02X" comp) " " - (make-string (ash comp -2) ?#) "\n")) - (let ((cstr (format "#%02X%02X%02X" - (aref colorcomp-data 0) - (aref colorcomp-data 1) - (aref colorcomp-data 2))) - (samp " (sample text) ")) - (insert "Color\t: " - (propertize samp 'face `(foreground-color . ,cstr)) - (propertize samp 'face `(background-color . ,cstr)) - "\n")))) - -(defun colorcomp (color) - "Allow fiddling with COLOR in a new buffer. -The buffer is in Color Components mode." - (interactive "sColor (name or #RGB or #RRGGBB): ") - (when (string= "" color) - (setq color "green")) - (unless (color-values color) - (error "No such color: %S" color)) - (switch-to-buffer - (generate-new-buffer (format "originally: %s" color))) - (kill-all-local-variables) - (setq major-mode 'colorcomp-mode - mode-name "Color Components") - (use-local-map colorcomp-mode-map) - (erase-buffer) - (buffer-disable-undo) - (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8)) - (color-values color)))) - (ewoc (ewoc-create 'colorcomp-pp - "\nColor Components\n\n" - (substitute-command-keys - "\n\\@{colorcomp-mode-map@}")))) - (set (make-local-variable 'colorcomp-data) data) - (set (make-local-variable 'colorcomp-ewoc) ewoc) - (ewoc-enter-last ewoc 0) - (ewoc-enter-last ewoc 1) - (ewoc-enter-last ewoc 2) - (ewoc-enter-last ewoc nil))) -@end example - -@cindex controller part, model/view/controller - This example can be extended to be a ``color selection widget'' (in -other words, the controller part of the ``model/view/controller'' -design paradigm) by defining commands to modify @code{colorcomp-data} -and to ``finish'' the selection process, and a keymap to tie it all -together conveniently. - -@smallexample -(defun colorcomp-mod (index limit delta) - (let ((cur (aref colorcomp-data index))) - (unless (= limit cur) - (aset colorcomp-data index (+ cur delta))) - (ewoc-invalidate - colorcomp-ewoc - (ewoc-nth colorcomp-ewoc index) - (ewoc-nth colorcomp-ewoc -1)))) - -(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1)) -(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1)) -(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1)) -(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1)) -(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1)) -(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1)) - -(defun colorcomp-copy-as-kill-and-exit () - "Copy the color components into the kill ring and kill the buffer. -The string is formatted #RRGGBB (hash followed by six hex digits)." - (interactive) - (kill-new (format "#%02X%02X%02X" - (aref colorcomp-data 0) - (aref colorcomp-data 1) - (aref colorcomp-data 2))) - (kill-buffer nil)) - -(setq colorcomp-mode-map - (let ((m (make-sparse-keymap))) - (suppress-keymap m) - (define-key m "i" 'colorcomp-R-less) - (define-key m "o" 'colorcomp-R-more) - (define-key m "k" 'colorcomp-G-less) - (define-key m "l" 'colorcomp-G-more) - (define-key m "," 'colorcomp-B-less) - (define-key m "." 'colorcomp-B-more) - (define-key m " " 'colorcomp-copy-as-kill-and-exit) - m)) -@end smallexample - -Note that we never modify the data in each node, which is fixed when the -ewoc is created to be either @code{nil} or an index into the vector -@code{colorcomp-data}, the actual color components. - -@node Blinking -@section Blinking Parentheses -@cindex parenthesis matching -@cindex blinking parentheses -@cindex balancing parentheses - - This section describes the mechanism by which Emacs shows a matching -open parenthesis when the user inserts a close parenthesis. - -@defvar blink-paren-function -The value of this variable should be a function (of no arguments) to -be called whenever a character with close parenthesis syntax is inserted. -The value of @code{blink-paren-function} may be @code{nil}, in which -case nothing is done. -@end defvar - -@defopt blink-matching-paren -If this variable is @code{nil}, then @code{blink-matching-open} does -nothing. -@end defopt - -@defopt blink-matching-paren-distance -This variable specifies the maximum distance to scan for a matching -parenthesis before giving up. -@end defopt - -@defopt blink-matching-delay -This variable specifies the number of seconds for the cursor to remain -at the matching parenthesis. A fraction of a second often gives -good results, but the default is 1, which works on all systems. -@end defopt - -@deffn Command blink-matching-open -This function is the default value of @code{blink-paren-function}. It -assumes that point follows a character with close parenthesis syntax and -moves the cursor momentarily to the matching opening character. If that -character is not already on the screen, it displays the character's -context in the echo area. To avoid long delays, this function does not -search farther than @code{blink-matching-paren-distance} characters. - -Here is an example of calling this function explicitly. - -@smallexample -@group -(defun interactive-blink-matching-open () -@c Do not break this line! -- rms. -@c The first line of a doc string -@c must stand alone. - "Indicate momentarily the start of sexp before point." - (interactive) -@end group -@group - (let ((blink-matching-paren-distance - (buffer-size)) - (blink-matching-paren t)) - (blink-matching-open))) -@end group -@end smallexample -@end deffn - -@node Usual Display -@section Usual Display Conventions - - The usual display conventions define how to display each character -code. You can override these conventions by setting up a display table -(@pxref{Display Tables}). Here are the usual display conventions: - -@itemize @bullet -@item -Character codes 32 through 126 map to glyph codes 32 through 126. -Normally this means they display as themselves. - -@item -Character code 9 is a horizontal tab. It displays as whitespace -up to a position determined by @code{tab-width}. - -@item -Character code 10 is a newline. - -@item -All other codes in the range 0 through 31, and code 127, display in one -of two ways according to the value of @code{ctl-arrow}. If it is -non-@code{nil}, these codes map to sequences of two glyphs, where the -first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can -specify a glyph to use instead of @samp{^}.) Otherwise, these codes map -just like the codes in the range 128 to 255. - -On MS-DOS terminals, Emacs arranges by default for the character code -127 to be mapped to the glyph code 127, which normally displays as an -empty polygon. This glyph is used to display non-@acronym{ASCII} characters -that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,, -emacs, The GNU Emacs Manual}. - -@item -Character codes 128 through 255 map to sequences of four glyphs, where -the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are -digit characters representing the character code in octal. (A display -table can specify a glyph to use instead of @samp{\}.) - -@item -Multibyte character codes above 256 are displayed as themselves, or as a -question mark or empty box if the terminal cannot display that -character. -@end itemize - - The usual display conventions apply even when there is a display -table, for any character whose entry in the active display table is -@code{nil}. Thus, when you set up a display table, you need only -specify the characters for which you want special behavior. - - These display rules apply to carriage return (character code 13), when -it appears in the buffer. But that character may not appear in the -buffer where you expect it, if it was eliminated as part of end-of-line -conversion (@pxref{Coding System Basics}). - - These variables affect the way certain characters are displayed on the -screen. Since they change the number of columns the characters occupy, -they also affect the indentation functions. These variables also affect -how the mode line is displayed; if you want to force redisplay of the -mode line using the new values, call the function -@code{force-mode-line-update} (@pxref{Mode Line Format}). - -@defopt ctl-arrow -@cindex control characters in display -This buffer-local variable controls how control characters are -displayed. If it is non-@code{nil}, they are displayed as a caret -followed by the character: @samp{^A}. If it is @code{nil}, they are -displayed as a backslash followed by three octal digits: @samp{\001}. -@end defopt - -@c Following may have overfull hbox. -@defvar default-ctl-arrow -The value of this variable is the default value for @code{ctl-arrow} in -buffers that do not override it. @xref{Default Value}. -@end defvar - -@defopt tab-width -The value of this buffer-local variable is the spacing between tab -stops used for displaying tab characters in Emacs buffers. The value -is in units of columns, and the default is 8. Note that this feature -is completely independent of the user-settable tab stops used by the -command @code{tab-to-tab-stop}. @xref{Indent Tabs}. -@end defopt - -@node Display Tables -@section Display Tables - -@cindex display table -You can use the @dfn{display table} feature to control how all possible -character codes display on the screen. This is useful for displaying -European languages that have letters not in the @acronym{ASCII} character -set. - -The display table maps each character code into a sequence of -@dfn{glyphs}, each glyph being a graphic that takes up one character -position on the screen. You can also define how to display each glyph -on your terminal, using the @dfn{glyph table}. - -Display tables affect how the mode line is displayed; if you want to -force redisplay of the mode line using a new display table, call -@code{force-mode-line-update} (@pxref{Mode Line Format}). - -@menu -* Display Table Format:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. -@end menu - -@node Display Table Format -@subsection Display Table Format - - A display table is actually a char-table (@pxref{Char-Tables}) with -@code{display-table} as its subtype. - -@defun make-display-table -This creates and returns a display table. The table initially has -@code{nil} in all elements. -@end defun - - The ordinary elements of the display table are indexed by character -codes; the element at index @var{c} says how to display the character -code @var{c}. The value should be @code{nil} or a vector of the -glyphs to be output (@pxref{Glyphs}). @code{nil} says to display the -character @var{c} according to the usual display conventions -(@pxref{Usual Display}). - - @strong{Warning:} if you use the display table to change the display -of newline characters, the whole buffer will be displayed as one long -``line.'' - - The display table also has six ``extra slots'' which serve special -purposes. Here is a table of their meanings; @code{nil} in any slot -means to use the default for that slot, as stated below. - -@table @asis -@item 0 -The glyph for the end of a truncated screen line (the default for this -is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses -arrows in the fringes to indicate truncation, so the display table has -no effect. - -@item 1 -The glyph for the end of a continued line (the default is @samp{\}). -On graphical terminals, Emacs uses curved arrows in the fringes to -indicate continuation, so the display table has no effect. - -@item 2 -The glyph for indicating a character displayed as an octal character -code (the default is @samp{\}). - -@item 3 -The glyph for indicating a control character (the default is @samp{^}). - -@item 4 -A vector of glyphs for indicating the presence of invisible lines (the -default is @samp{...}). @xref{Selective Display}. - -@item 5 -The glyph used to draw the border between side-by-side windows (the -default is @samp{|}). @xref{Splitting Windows}. This takes effect only -when there are no scroll bars; if scroll bars are supported and in use, -a scroll bar separates the two windows. -@end table - - For example, here is how to construct a display table that mimics the -effect of setting @code{ctl-arrow} to a non-@code{nil} value: - -@example -(setq disptab (make-display-table)) -(let ((i 0)) - (while (< i 32) - (or (= i ?\t) (= i ?\n) - (aset disptab i (vector ?^ (+ i 64)))) - (setq i (1+ i))) - (aset disptab 127 (vector ?^ ??))) -@end example - -@defun display-table-slot display-table slot -This function returns the value of the extra slot @var{slot} of -@var{display-table}. The argument @var{slot} may be a number from 0 to -5 inclusive, or a slot name (symbol). Valid symbols are -@code{truncation}, @code{wrap}, @code{escape}, @code{control}, -@code{selective-display}, and @code{vertical-border}. -@end defun - -@defun set-display-table-slot display-table slot value -This function stores @var{value} in the extra slot @var{slot} of -@var{display-table}. The argument @var{slot} may be a number from 0 to -5 inclusive, or a slot name (symbol). Valid symbols are -@code{truncation}, @code{wrap}, @code{escape}, @code{control}, -@code{selective-display}, and @code{vertical-border}. -@end defun - -@defun describe-display-table display-table -This function displays a description of the display table -@var{display-table} in a help buffer. -@end defun - -@deffn Command describe-current-display-table -This command displays a description of the current display table in a -help buffer. -@end deffn - -@node Active Display Table -@subsection Active Display Table -@cindex active display table - - Each window can specify a display table, and so can each buffer. When -a buffer @var{b} is displayed in window @var{w}, display uses the -display table for window @var{w} if it has one; otherwise, the display -table for buffer @var{b} if it has one; otherwise, the standard display -table if any. The display table chosen is called the @dfn{active} -display table. - -@defun window-display-table &optional window -This function returns @var{window}'s display table, or @code{nil} -if @var{window} does not have an assigned display table. The default -for @var{window} is the selected window. -@end defun - -@defun set-window-display-table window table -This function sets the display table of @var{window} to @var{table}. -The argument @var{table} should be either a display table or -@code{nil}. -@end defun - -@defvar buffer-display-table -This variable is automatically buffer-local in all buffers; its value in -a particular buffer specifies the display table for that buffer. If it -is @code{nil}, that means the buffer does not have an assigned display -table. -@end defvar - -@defvar standard-display-table -This variable's value is the default display table, used whenever a -window has no display table and neither does the buffer displayed in -that window. This variable is @code{nil} by default. -@end defvar - - If there is no display table to use for a particular window---that is, -if the window specifies none, its buffer specifies none, and -@code{standard-display-table} is @code{nil}---then Emacs uses the usual -display conventions for all character codes in that window. @xref{Usual -Display}. - -A number of functions for changing the standard display table -are defined in the library @file{disp-table}. - -@node Glyphs -@subsection Glyphs - -@cindex glyph - A @dfn{glyph} is a generalization of a character; it stands for an -image that takes up a single character position on the screen. Normally -glyphs come from vectors in the display table (@pxref{Display Tables}). - - A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code -can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A -simple glyph code is just a way of specifying a character and a face -to output it in. @xref{Faces}. - - The following functions are used to manipulate simple glyph codes: - -@defun make-glyph-code char &optional face -This function returns a simple glyph code representing char @var{char} -with face @var{face}. -@end defun - -@defun glyph-char glyph -This function returns the character of simple glyph code @var{glyph}. -@end defun - -@defun glyph-face glyph -This function returns face of simple glyph code @var{glyph}, or -@code{nil} if @var{glyph} has the default face (face-id 0). -@end defun - - On character terminals, you can set up a @dfn{glyph table} to define -the meaning of glyph codes (represented as small integers). - -@defvar glyph-table -The value of this variable is the current glyph table. It should be -@code{nil} or a vector whose @var{g}th element defines glyph code -@var{g}. - -If a glyph code is greater than or equal to the length of the glyph -table, that code is automatically simple. If @code{glyph-table} is -@code{nil} then all glyph codes are simple. - -The glyph table is used only on character terminals. On graphical -displays, all glyph codes are simple. -@end defvar - - Here are the meaningful types of elements in the glyph table: - -@table @asis -@item @var{string} -Send the characters in @var{string} to the terminal to output -this glyph code. - -@item @var{code} -Define this glyph code as an alias for glyph code @var{code} created -by @code{make-glyph-code}. You can use such an alias to define a -small-numbered glyph code which specifies a character with a face. - -@item @code{nil} -This glyph code is simple. -@end table - -@defun create-glyph string -This function returns a newly-allocated glyph code which is set up to -display by sending @var{string} to the terminal. -@end defun - -@node Beeping -@section Beeping -@c @cindex beeping "beep" is adjacent -@cindex bell - - This section describes how to make Emacs ring the bell (or blink the -screen) to attract the user's attention. Be conservative about how -often you do this; frequent bells can become irritating. Also be -careful not to use just beeping when signaling an error is more -appropriate. (@xref{Errors}.) - -@defun ding &optional do-not-terminate -@cindex keyboard macro termination -This function beeps, or flashes the screen (see @code{visible-bell} below). -It also terminates any keyboard macro currently executing unless -@var{do-not-terminate} is non-@code{nil}. -@end defun - -@defun beep &optional do-not-terminate -This is a synonym for @code{ding}. -@end defun - -@defopt visible-bell -This variable determines whether Emacs should flash the screen to -represent a bell. Non-@code{nil} means yes, @code{nil} means no. This -is effective on graphical displays, and on text-only terminals -provided the terminal's Termcap entry defines the visible bell -capability (@samp{vb}). -@end defopt - -@defvar ring-bell-function -If this is non-@code{nil}, it specifies how Emacs should ``ring the -bell.'' Its value should be a function of no arguments. If this is -non-@code{nil}, it takes precedence over the @code{visible-bell} -variable. -@end defvar - -@node Window Systems -@section Window Systems - - Emacs works with several window systems, most notably the X Window -System. Both Emacs and X use the term ``window,'' but use it -differently. An Emacs frame is a single window as far as X is -concerned; the individual Emacs windows are not known to X at all. - -@defvar window-system -This variable tells Lisp programs what window system Emacs is running -under. The possible values are - -@table @code -@item x -@cindex X Window System -Emacs is displaying using X. -@item pc -Emacs is displaying using MS-DOS. -@item w32 -Emacs is displaying using Windows. -@item mac -Emacs is displaying using a Macintosh. -@item nil -Emacs is using a character-based terminal. -@end table -@end defvar - -@defvar window-setup-hook -This variable is a normal hook which Emacs runs after handling the -initialization files. Emacs runs this hook after it has completed -loading your init file, the default initialization file (if -any), and the terminal-specific Lisp code, and running the hook -@code{term-setup-hook}. - -This hook is used for internal purposes: setting up communication with -the window system, and creating the initial window. Users should not -interfere with it. -@end defvar - -@ignore - arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6 -@end ignore diff --git a/lispref/doclicense.texi b/lispref/doclicense.texi deleted file mode 100644 index f2f32aaa968..00000000000 --- a/lispref/doclicense.texi +++ /dev/null @@ -1,419 +0,0 @@ -@c -*-texinfo-*- -@node GNU Free Documentation License, GPL, Antinews, Top - -@appendix GNU Free Documentation License -@center Version 1.2, November 2002 - -@display -Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display -@sp 1 -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document ``free'' in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft,'' which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@sp 1 -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document,'' below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you.'' You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque.'' - - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements,'' -``Dedications,'' ``Endorsements,'' or ``History.'') To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. -@sp 1 -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. -@sp 1 -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. -@sp 1 -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -A. Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission.@* -B. List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has fewer than five), - unless they release you from this requirement.@* -C. State on the Title page the name of the publisher of the - Modified Version, as the publisher.@* -D. Preserve all the copyright notices of the Document.@* -E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices.@* -F. Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below.@* -G. Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice.@* -H. Include an unaltered copy of this License.@* -I. Preserve the section Entitled ``History,'' Preserve its Title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section Entitled ``History'' in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence.@* -J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the ``History'' section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission.@* -K. For any section Entitled ``Acknowledgements'' or ``Dedications,'' - Preserve the Title of the section, and preserve in the section all - the substance and tone of each of the contributor acknowledgements - and/or dedications given therein.@* -L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles.@* -M. Delete any section Entitled ``Endorsements.'' Such a section - may not be included in the Modified Version.@* -N. Do not retitle any existing section to be Entitled ``Endorsements'' - or to conflict in title with any Invariant Section.@* -O. Preserve any Warranty Disclaimers.@* -@sp 1 -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements,'' provided it contains -nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. -@sp 1 -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements,'' -and any sections Entitled ``Dedications.'' You must delete all sections -Entitled ``Endorsements.'' -@sp 1 -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. -@sp 1 -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. -@sp 1 -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements,'' -``Dedications,'' or ``History,'' the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. -@sp 1 -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. -@sp 1 -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -http://www.gnu.org/copyleft/. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. - -@end enumerate - -@unnumberedsec ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group -Copyright (C) @var{year} @var{your name}. -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 no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled ``GNU -Free Documentation License.'' -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with...Texts.'' line with this: - -@smallexample -@group -with the Invariant Sections being @var{list their titles}, with the -Front-Cover Texts being @var{list}, and with the Back-Cover Texts being -@var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@ignore - arch-tag: 9014cf6e-f3c4-401d-b8da-4fe52723984c -@end ignore diff --git a/lispref/edebug.texi b/lispref/edebug.texi deleted file mode 100644 index 4be030896c5..00000000000 --- a/lispref/edebug.texi +++ /dev/null @@ -1,1582 +0,0 @@ -@comment -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. - -@c This file can also be used by an independent Edebug User -@c Manual in which case the Edebug node below should be used -@c with the following links to the Bugs section and to the top level: - -@c , Bugs and Todo List, Top, Top - -@node Edebug, Syntax Errors, Debugger, Debugging -@section Edebug -@cindex Edebug debugging facility - - Edebug is a source-level debugger for Emacs Lisp programs with which -you can: - -@itemize @bullet -@item -Step through evaluation, stopping before and after each expression. - -@item -Set conditional or unconditional breakpoints. - -@item -Stop when a specified condition is true (the global break event). - -@item -Trace slow or fast, stopping briefly at each stop point, or -at each breakpoint. - -@item -Display expression results and evaluate expressions as if outside of -Edebug. - -@item -Automatically re-evaluate a list of expressions and -display their results each time Edebug updates the display. - -@item -Output trace info on function enter and exit. - -@item -Stop when an error occurs. - -@item -Display a backtrace, omitting Edebug's own frames. - -@item -Specify argument evaluation for macros and defining forms. - -@item -Obtain rudimentary coverage testing and frequency counts. -@end itemize - -The first three sections below should tell you enough about Edebug to -enable you to use it. - -@menu -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Modes: Edebug Execution Modes. Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Misc: Edebug Misc. Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Views: Edebug Views. Views inside and outside of Edebug. -* Eval: 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. -* Options: Edebug Options. Option variables for customizing Edebug. -@end menu - -@node Using Edebug -@subsection Using Edebug - - To debug a Lisp program with Edebug, you must first @dfn{instrument} -the Lisp code that you want to debug. A simple way to do this is to -first move point into the definition of a function or macro and then do -@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See -@ref{Instrumenting}, for alternative ways to instrument code. - - Once a function is instrumented, any call to the function activates -Edebug. Depending on which Edebug execution mode you have selected, -activating Edebug may stop execution and let you step through the -function, or it may update the display and continue execution while -checking for debugging commands. The default execution mode is step, -which stops execution. @xref{Edebug Execution Modes}. - - Within Edebug, you normally view an Emacs buffer showing the source of -the Lisp code you are debugging. This is referred to as the @dfn{source -code buffer}, and it is temporarily read-only. - - An arrow in the left fringe indicates the line where the function is -executing. Point initially shows where within the line the function is -executing, but this ceases to be true if you move point yourself. - - If you instrument the definition of @code{fac} (shown below) and then -execute @code{(fac 3)}, here is what you would normally see. Point is -at the open-parenthesis before @code{if}. - -@example -(defun fac (n) -=>@point{}(if (< 0 n) - (* n (fac (1- n))) - 1)) -@end example - -@cindex stop points -The places within a function where Edebug can stop execution are called -@dfn{stop points}. These occur both before and after each subexpression -that is a list, and also after each variable reference. -Here we use periods to show the stop points in the function -@code{fac}: - -@example -(defun fac (n) - .(if .(< 0 n.). - .(* n. .(fac .(1- n.).).). - 1).) -@end example - -The special commands of Edebug are available in the source code buffer -in addition to the commands of Emacs Lisp mode. For example, you can -type the Edebug command @key{SPC} to execute until the next stop point. -If you type @key{SPC} once after entry to @code{fac}, here is the -display you will see: - -@example -(defun fac (n) -=>(if @point{}(< 0 n) - (* n (fac (1- n))) - 1)) -@end example - -When Edebug stops execution after an expression, it displays the -expression's value in the echo area. - -Other frequently used commands are @kbd{b} to set a breakpoint at a stop -point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to -exit Edebug and return to the top-level command loop. Type @kbd{?} to -display a list of all Edebug commands. - -@node Instrumenting -@subsection Instrumenting for Edebug - - In order to use Edebug to debug Lisp code, you must first -@dfn{instrument} the code. Instrumenting code inserts additional code -into it, to invoke Edebug at the proper places. - -@kindex C-M-x -@findex eval-defun (Edebug) - When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a -prefix argument on a function definition, it instruments the -definition before evaluating it. (This does not modify the source -code itself.) If the variable @code{edebug-all-defs} is -non-@code{nil}, that inverts the meaning of the prefix argument: in -this case, @kbd{C-M-x} instruments the definition @emph{unless} it has -a prefix argument. The default value of @code{edebug-all-defs} is -@code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value -of the variable @code{edebug-all-defs}. - -@findex eval-region @r{(Edebug)} -@findex eval-buffer @r{(Edebug)} -@findex eval-current-buffer @r{(Edebug)} - If @code{edebug-all-defs} is non-@code{nil}, then the commands -@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} -also instrument any definitions they evaluate. Similarly, -@code{edebug-all-forms} controls whether @code{eval-region} should -instrument @emph{any} form, even non-defining forms. This doesn't apply -to loading or evaluations in the minibuffer. The command @kbd{M-x -edebug-all-forms} toggles this option. - -@findex edebug-eval-top-level-form - Another command, @kbd{M-x edebug-eval-top-level-form}, is available to -instrument any top-level form regardless of the values of -@code{edebug-all-defs} and @code{edebug-all-forms}. - - While Edebug is active, the command @kbd{I} -(@code{edebug-instrument-callee}) instruments the definition of the -function or macro called by the list form after point, if is not already -instrumented. This is possible only if Edebug knows where to find the -source for that function; for this reading, after loading Edebug, -@code{eval-region} records the position of every definition it -evaluates, even if not instrumenting it. See also the @kbd{i} command -(@pxref{Jumping}), which steps into the call after instrumenting the -function. - - Edebug knows how to instrument all the standard special forms, -@code{interactive} forms with an expression argument, anonymous lambda -expressions, and other defining forms. However, Edebug cannot determine -on its own what a user-defined macro will do with the arguments of a -macro call, so you must provide that information using Edebug -specifications; see @ref{Edebug and Macros}, for details. - - When Edebug is about to instrument code for the first time in a -session, it runs the hook @code{edebug-setup-hook}, then sets it to -@code{nil}. You can use this to load Edebug specifications -associated with a package you are using, but only when you use Edebug. - -@findex eval-expression @r{(Edebug)} - To remove instrumentation from a definition, simply re-evaluate its -definition in a way that does not instrument. There are two ways of -evaluating forms that never instrument them: from a file with -@code{load}, and from the minibuffer with @code{eval-expression} -(@kbd{M-:}). - - If Edebug detects a syntax error while instrumenting, it leaves point -at the erroneous code and signals an @code{invalid-read-syntax} error. - - @xref{Edebug Eval}, for other evaluation functions available -inside of Edebug. - -@node Edebug Execution Modes -@subsection Edebug Execution Modes - -@cindex Edebug execution modes -Edebug supports several execution modes for running the program you are -debugging. We call these alternatives @dfn{Edebug execution modes}; do -not confuse them with major or minor modes. The current Edebug execution mode -determines how far Edebug continues execution before stopping---whether -it stops at each stop point, or continues to the next breakpoint, for -example---and how much Edebug displays the progress of the evaluation -before it stops. - -Normally, you specify the Edebug execution mode by typing a command to -continue the program in a certain mode. Here is a table of these -commands; all except for @kbd{S} resume execution of the program, at -least for a certain distance. - -@table @kbd -@item S -Stop: don't execute any more of the program, but wait for more -Edebug commands (@code{edebug-stop}). - -@item @key{SPC} -Step: stop at the next stop point encountered (@code{edebug-step-mode}). - -@item n -Next: stop at the next stop point encountered after an expression -(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in -@ref{Jumping}. - -@item t -Trace: pause (normally one second) at each Edebug stop point -(@code{edebug-trace-mode}). - -@item T -Rapid trace: update the display at each stop point, but don't actually -pause (@code{edebug-Trace-fast-mode}). - -@item g -Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}. - -@item c -Continue: pause one second at each breakpoint, and then continue -(@code{edebug-continue-mode}). - -@item C -Rapid continue: move point to each breakpoint, but don't pause -(@code{edebug-Continue-fast-mode}). - -@item G -Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You -can still stop the program by typing @kbd{S}, or any editing command. -@end table - -In general, the execution modes earlier in the above list run the -program more slowly or stop sooner than the modes later in the list. - -While executing or tracing, you can interrupt the execution by typing -any Edebug command. Edebug stops the program at the next stop point and -then executes the command you typed. For example, typing @kbd{t} during -execution switches to trace mode at the next stop point. You can use -@kbd{S} to stop execution without doing anything else. - -If your function happens to read input, a character you type intending -to interrupt execution may be read by the function instead. You can -avoid such unintended results by paying attention to when your program -wants input. - -@cindex keyboard macros (Edebug) -Keyboard macros containing the commands in this section do not -completely work: exiting from Edebug, to resume the program, loses track -of the keyboard macro. This is not easy to fix. Also, defining or -executing a keyboard macro outside of Edebug does not affect commands -inside Edebug. This is usually an advantage. See also the -@code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}). - -When you enter a new Edebug level, the initial execution mode comes -from the value of the variable @code{edebug-initial-mode}. -(@xref{Edebug Options}.) By default, this specifies step mode. Note -that you may reenter the same Edebug level several times if, for -example, an instrumented function is called several times from one -command. - -@defopt edebug-sit-for-seconds -This option specifies how many seconds to wait between execution steps -in trace mode. The default is 1 second. -@end defopt - -@node Jumping -@subsection Jumping - - The commands described in this section execute until they reach a -specified location. All except @kbd{i} make a temporary breakpoint to -establish the place to stop, then switch to go mode. Any other -breakpoint reached before the intended stop point will also stop -execution. @xref{Breakpoints}, for the details on breakpoints. - - These commands may fail to work as expected in case of nonlocal exit, -as that can bypass the temporary breakpoint where you expected the -program to stop. - -@table @kbd -@item h -Proceed to the stop point near where point is (@code{edebug-goto-here}). - -@item f -Run the program for one expression -(@code{edebug-forward-sexp}). - -@item o -Run the program until the end of the containing sexp. - -@item i -Step into the function or macro called by the form after point. -@end table - -The @kbd{h} command proceeds to the stop point at or after the current -location of point, using a temporary breakpoint. - -The @kbd{f} command runs the program forward over one expression. More -precisely, it sets a temporary breakpoint at the position that -@kbd{C-M-f} would reach, then executes in go mode so that the program -will stop at breakpoints. - -With a prefix argument @var{n}, the temporary breakpoint is placed -@var{n} sexps beyond point. If the containing list ends before @var{n} -more elements, then the place to stop is after the containing -expression. - -You must check that the position @kbd{C-M-f} finds is a place that the -program will really get to. In @code{cond}, for example, this may not -be true. - -For flexibility, the @kbd{f} command does @code{forward-sexp} starting -at point, rather than at the stop point. If you want to execute one -expression @emph{from the current stop point}, first type @kbd{w}, to -move point there, and then type @kbd{f}. - -The @kbd{o} command continues ``out of'' an expression. It places a -temporary breakpoint at the end of the sexp containing point. If the -containing sexp is a function definition itself, @kbd{o} continues until -just before the last sexp in the definition. If that is where you are -now, it returns from the function and then stops. In other words, this -command does not exit the currently executing function unless you are -positioned after the last sexp. - -The @kbd{i} command steps into the function or macro called by the list -form after point, and stops at its first stop point. Note that the form -need not be the one about to be evaluated. But if the form is a -function call about to be evaluated, remember to use this command before -any of the arguments are evaluated, since otherwise it will be too late. - -The @kbd{i} command instruments the function or macro it's supposed to -step into, if it isn't instrumented already. This is convenient, but keep -in mind that the function or macro remains instrumented unless you explicitly -arrange to deinstrument it. - -@node Edebug Misc -@subsection Miscellaneous Edebug Commands - - Some miscellaneous Edebug commands are described here. - -@table @kbd -@item ? -Display the help message for Edebug (@code{edebug-help}). - -@item C-] -Abort one level back to the previous command level -(@code{abort-recursive-edit}). - -@item q -Return to the top level editor command loop (@code{top-level}). This -exits all recursive editing levels, including all levels of Edebug -activity. However, instrumented code protected with -@code{unwind-protect} or @code{condition-case} forms may resume -debugging. - -@item Q -Like @kbd{q}, but don't stop even for protected code -(@code{top-level-nonstop}). - -@item r -Redisplay the most recently known expression result in the echo area -(@code{edebug-previous-result}). - -@item d -Display a backtrace, excluding Edebug's own functions for clarity -(@code{edebug-backtrace}). - -You cannot use debugger commands in the backtrace buffer in Edebug as -you would in the standard debugger. - -The backtrace buffer is killed automatically when you continue -execution. -@end table - -You can invoke commands from Edebug that activate Edebug again -recursively. Whenever Edebug is active, you can quit to the top level -with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can -display a backtrace of all the pending evaluations with @kbd{d}. - -@node Breaks -@subsection Breaks - -Edebug's step mode stops execution when the next stop point is reached. -There are three other ways to stop Edebug execution once it has started: -breakpoints, the global break condition, and source breakpoints. - -@menu -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. -@end menu - -@node Breakpoints -@subsubsection Edebug Breakpoints - -@cindex breakpoints (Edebug) -While using Edebug, you can specify @dfn{breakpoints} in the program you -are testing: these are places where execution should stop. You can set a -breakpoint at any stop point, as defined in @ref{Using Edebug}. For -setting and unsetting breakpoints, the stop point that is affected is -the first one at or after point in the source code buffer. Here are the -Edebug commands for breakpoints: - -@table @kbd -@item b -Set a breakpoint at the stop point at or after point -(@code{edebug-set-breakpoint}). If you use a prefix argument, the -breakpoint is temporary---it turns off the first time it stops the -program. - -@item u -Unset the breakpoint (if any) at the stop point at or after -point (@code{edebug-unset-breakpoint}). - -@item x @var{condition} @key{RET} -Set a conditional breakpoint which stops the program only if -evaluating @var{condition} produces a non-@code{nil} value -(@code{edebug-set-conditional-breakpoint}). With a prefix argument, -the breakpoint is temporary. - -@item B -Move point to the next breakpoint in the current definition -(@code{edebug-next-breakpoint}). -@end table - -While in Edebug, you can set a breakpoint with @kbd{b} and unset one -with @kbd{u}. First move point to the Edebug stop point of your choice, -then type @kbd{b} or @kbd{u} to set or unset a breakpoint there. -Unsetting a breakpoint where none has been set has no effect. - -Re-evaluating or reinstrumenting a definition removes all of its -previous breakpoints. - -A @dfn{conditional breakpoint} tests a condition each time the program -gets there. Any errors that occur as a result of evaluating the -condition are ignored, as if the result were @code{nil}. To set a -conditional breakpoint, use @kbd{x}, and specify the condition -expression in the minibuffer. Setting a conditional breakpoint at a -stop point that has a previously established conditional breakpoint puts -the previous condition expression in the minibuffer so you can edit it. - -You can make a conditional or unconditional breakpoint -@dfn{temporary} by using a prefix argument with the command to set the -breakpoint. When a temporary breakpoint stops the program, it is -automatically unset. - -Edebug always stops or pauses at a breakpoint, except when the Edebug -mode is Go-nonstop. In that mode, it ignores breakpoints entirely. - -To find out where your breakpoints are, use the @kbd{B} command, which -moves point to the next breakpoint following point, within the same -function, or to the first breakpoint if there are no following -breakpoints. This command does not continue execution---it just moves -point in the buffer. - -@node Global Break Condition -@subsubsection Global Break Condition - -@cindex stopping on events -@cindex global break condition - A @dfn{global break condition} stops execution when a specified -condition is satisfied, no matter where that may occur. Edebug -evaluates the global break condition at every stop point; if it -evaluates to a non-@code{nil} value, then execution stops or pauses -depending on the execution mode, as if a breakpoint had been hit. If -evaluating the condition gets an error, execution does not stop. - -@findex edebug-set-global-break-condition - The condition expression is stored in -@code{edebug-global-break-condition}. You can specify a new expression -using the @kbd{X} command from the source code buffer while Edebug is -active, or using @kbd{C-x X X} from any buffer at any time, as long as -Edebug is loaded (@code{edebug-set-global-break-condition}). - - The global break condition is the simplest way to find where in your -code some event occurs, but it makes code run much more slowly. So you -should reset the condition to @code{nil} when not using it. - -@node Source Breakpoints -@subsubsection Source Breakpoints - -@findex edebug -@cindex source breakpoints - All breakpoints in a definition are forgotten each time you -reinstrument it. If you wish to make a breakpoint that won't be -forgotten, you can write a @dfn{source breakpoint}, which is simply a -call to the function @code{edebug} in your source code. You can, of -course, make such a call conditional. For example, in the @code{fac} -function, you can insert the first line as shown below, to stop when the -argument reaches zero: - -@example -(defun fac (n) - (if (= n 0) (edebug)) - (if (< 0 n) - (* n (fac (1- n))) - 1)) -@end example - - When the @code{fac} definition is instrumented and the function is -called, the call to @code{edebug} acts as a breakpoint. Depending on -the execution mode, Edebug stops or pauses there. - - If no instrumented code is being executed when @code{edebug} is called, -that function calls @code{debug}. -@c This may not be a good idea anymore. - -@node Trapping Errors -@subsection Trapping Errors - - Emacs normally displays an error message when an error is signaled and -not handled with @code{condition-case}. While Edebug is active and -executing instrumented code, it normally responds to all unhandled -errors. You can customize this with the options @code{edebug-on-error} -and @code{edebug-on-quit}; see @ref{Edebug Options}. - - When Edebug responds to an error, it shows the last stop point -encountered before the error. This may be the location of a call to a -function which was not instrumented, and within which the error actually -occurred. For an unbound variable error, the last known stop point -might be quite distant from the offending variable reference. In that -case, you might want to display a full backtrace (@pxref{Edebug Misc}). - -@c Edebug should be changed for the following: -- dan - If you change @code{debug-on-error} or @code{debug-on-quit} while -Edebug is active, these changes will be forgotten when Edebug becomes -inactive. Furthermore, during Edebug's recursive edit, these variables -are bound to the values they had outside of Edebug. - -@node Edebug Views -@subsection Edebug Views - - These Edebug commands let you view aspects of the buffer and window -status as they were before entry to Edebug. The outside window -configuration is the collection of windows and contents that were in -effect outside of Edebug. - -@table @kbd -@item v -Switch to viewing the outside window configuration -(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug. - -@item p -Temporarily display the outside current buffer with point at its -outside position (@code{edebug-bounce-point}), pausing for one second -before returning to Edebug. With a prefix argument @var{n}, pause for -@var{n} seconds instead. - -@item w -Move point back to the current stop point in the source code buffer -(@code{edebug-where}). - -If you use this command in a different window displaying the same -buffer, that window will be used instead to display the current -definition in the future. - -@item W -@c Its function is not simply to forget the saved configuration -- dan -Toggle whether Edebug saves and restores the outside window -configuration (@code{edebug-toggle-save-windows}). - -With a prefix argument, @code{W} only toggles saving and restoring of -the selected window. To specify a window that is not displaying the -source code buffer, you must use @kbd{C-x X W} from the global keymap. -@end table - - You can view the outside window configuration with @kbd{v} or just -bounce to the point in the current buffer with @kbd{p}, even if -it is not normally displayed. - - After moving point, you may wish to jump back to the stop point. -You can do that with @kbd{w} from a source code buffer. You can jump -back to the stop point in the source code buffer from any buffer using -@kbd{C-x X w}. - - Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the -saved outside window configuration---so that even if you turn saving -back @emph{on}, the current window configuration remains unchanged when -you next exit Edebug (by continuing the program). However, the -automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may -conflict with the buffers you wish to see unless you have enough windows -open. - -@node Edebug Eval -@subsection Evaluation - - While within Edebug, you can evaluate expressions ``as if'' Edebug -were not running. Edebug tries to be invisible to the expression's -evaluation and printing. Evaluation of expressions that cause side -effects will work as expected, except for changes to data that Edebug -explicitly saves and restores. @xref{The Outside Context}, for details -on this process. - -@table @kbd -@item e @var{exp} @key{RET} -Evaluate expression @var{exp} in the context outside of Edebug -(@code{edebug-eval-expression}). That is, Edebug tries to minimize its -interference with the evaluation. - -@item M-: @var{exp} @key{RET} -Evaluate expression @var{exp} in the context of Edebug itself. - -@item C-x C-e -Evaluate the expression before point, in the context outside of Edebug -(@code{edebug-eval-last-sexp}). -@end table - -@cindex lexical binding (Edebug) - Edebug supports evaluation of expressions containing references to -lexically bound symbols created by the following constructs in -@file{cl.el} (version 2.03 or later): @code{lexical-let}, -@code{macrolet}, and @code{symbol-macrolet}. - -@node Eval List -@subsection Evaluation List Buffer - - You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to -evaluate expressions interactively. You can also set up the -@dfn{evaluation list} of expressions to be evaluated automatically each -time Edebug updates the display. - -@table @kbd -@item E -Switch to the evaluation list buffer @samp{*edebug*} -(@code{edebug-visit-eval-list}). -@end table - - In the @samp{*edebug*} buffer you can use the commands of Lisp -Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs -Manual}) as well as these special commands: - -@table @kbd -@item C-j -Evaluate the expression before point, in the outside context, and insert -the value in the buffer (@code{edebug-eval-print-last-sexp}). - -@item C-x C-e -Evaluate the expression before point, in the context outside of Edebug -(@code{edebug-eval-last-sexp}). - -@item C-c C-u -Build a new evaluation list from the contents of the buffer -(@code{edebug-update-eval-list}). - -@item C-c C-d -Delete the evaluation list group that point is in -(@code{edebug-delete-eval-item}). - -@item C-c C-w -Switch back to the source code buffer at the current stop point -(@code{edebug-where}). -@end table - - You can evaluate expressions in the evaluation list window with -@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*}; -but they are evaluated in the context outside of Edebug. - - The expressions you enter interactively (and their results) are lost -when you continue execution; but you can set up an @dfn{evaluation list} -consisting of expressions to be evaluated each time execution stops. - -@cindex evaluation list group - To do this, write one or more @dfn{evaluation list groups} in the -evaluation list buffer. An evaluation list group consists of one or -more Lisp expressions. Groups are separated by comment lines. - - The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the -evaluation list, scanning the buffer and using the first expression of -each group. (The idea is that the second expression of the group is the -value previously computed and displayed.) - - Each entry to Edebug redisplays the evaluation list by inserting each -expression in the buffer, followed by its current value. It also -inserts comment lines so that each expression becomes its own group. -Thus, if you type @kbd{C-c C-u} again without changing the buffer text, -the evaluation list is effectively unchanged. - - If an error occurs during an evaluation from the evaluation list, the -error message is displayed in a string as if it were the result. -Therefore, expressions that use variables not currently valid do not -interrupt your debugging. - - Here is an example of what the evaluation list window looks like after -several expressions have been added to it: - -@smallexample -(current-buffer) -#<buffer *scratch*> -;--------------------------------------------------------------- -(selected-window) -#<window 16 on *scratch*> -;--------------------------------------------------------------- -(point) -196 -;--------------------------------------------------------------- -bad-var -"Symbol's value as variable is void: bad-var" -;--------------------------------------------------------------- -(recursion-depth) -0 -;--------------------------------------------------------------- -this-command -eval-last-sexp -;--------------------------------------------------------------- -@end smallexample - -To delete a group, move point into it and type @kbd{C-c C-d}, or simply -delete the text for the group and update the evaluation list with -@kbd{C-c C-u}. To add a new expression to the evaluation list, insert -the expression at a suitable place, insert a new comment line, then type -@kbd{C-c C-u}. You need not insert dashes in the comment line---its -contents don't matter. - -After selecting @samp{*edebug*}, you can return to the source code -buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when -you continue execution, and recreated next time it is needed. - -@node Printing in Edebug -@subsection Printing in Edebug - -@cindex printing (Edebug) -@cindex printing circular structures -@pindex cust-print - If an expression in your program produces a value containing circular -list structure, you may get an error when Edebug attempts to print it. - - One way to cope with circular structure is to set @code{print-length} -or @code{print-level} to truncate the printing. Edebug does this for -you; it binds @code{print-length} and @code{print-level} to 50 if they -were @code{nil}. (Actually, the variables @code{edebug-print-length} -and @code{edebug-print-level} specify the values to use within Edebug.) -@xref{Output Variables}. - -@defopt edebug-print-length -If non-@code{nil}, Edebug binds @code{print-length} to this value while -printing results. The default value is @code{50}. -@end defopt - -@defopt edebug-print-level -If non-@code{nil}, Edebug binds @code{print-level} to this value while -printing results. The default value is @code{50}. -@end defopt - - You can also print circular structures and structures that share -elements more informatively by binding @code{print-circle} -to a non-@code{nil} value. - - Here is an example of code that creates a circular structure: - -@example -(setq a '(x y)) -(setcar a a) -@end example - -@noindent -Custom printing prints this as @samp{Result: #1=(#1# y)}. The -@samp{#1=} notation labels the structure that follows it with the label -@samp{1}, and the @samp{#1#} notation references the previously labeled -structure. This notation is used for any shared elements of lists or -vectors. - -@defopt edebug-print-circle -If non-@code{nil}, Edebug binds @code{print-circle} to this value while -printing results. The default value is @code{t}. -@end defopt - - Other programs can also use custom printing; see @file{cust-print.el} -for details. - -@node Trace Buffer -@subsection Trace Buffer -@cindex trace buffer - - Edebug can record an execution trace, storing it in a buffer named -@samp{*edebug-trace*}. This is a log of function calls and returns, -showing the function names and their arguments and values. To enable -trace recording, set @code{edebug-trace} to a non-@code{nil} value. - - Making a trace buffer is not the same thing as using trace execution -mode (@pxref{Edebug Execution Modes}). - - When trace recording is enabled, each function entry and exit adds -lines to the trace buffer. A function entry record consists of -@samp{::::@{}, followed by the function name and argument values. A -function exit record consists of @samp{::::@}}, followed by the function -name and result of the function. - - The number of @samp{:}s in an entry shows its recursion depth. You -can use the braces in the trace buffer to find the matching beginning or -end of function calls. - -@findex edebug-print-trace-before -@findex edebug-print-trace-after - You can customize trace recording for function entry and exit by -redefining the functions @code{edebug-print-trace-before} and -@code{edebug-print-trace-after}. - -@defmac edebug-tracing string body@dots{} -This macro requests additional trace information around the execution -of the @var{body} forms. The argument @var{string} specifies text -to put in the trace buffer, after the @samp{@{} or @samp{@}}. All -the arguments are evaluated, and @code{edebug-tracing} returns the -value of the last form in @var{body}. -@end defmac - -@defun edebug-trace format-string &rest format-args -This function inserts text in the trace buffer. It computes the text -with @code{(apply 'format @var{format-string} @var{format-args})}. -It also appends a newline to separate entries. -@end defun - - @code{edebug-tracing} and @code{edebug-trace} insert lines in the -trace buffer whenever they are called, even if Edebug is not active. -Adding text to the trace buffer also scrolls its window to show the last -lines inserted. - -@node Coverage Testing -@subsection Coverage Testing - -@cindex coverage testing (Edebug) -@cindex frequency counts -@cindex performance analysis - Edebug provides rudimentary coverage testing and display of execution -frequency. - - Coverage testing works by comparing the result of each expression with -the previous result; each form in the program is considered ``covered'' -if it has returned two different values since you began testing coverage -in the current Emacs session. Thus, to do coverage testing on your -program, execute it under various conditions and note whether it behaves -correctly; Edebug will tell you when you have tried enough different -conditions that each form has returned two different values. - - Coverage testing makes execution slower, so it is only done if -@code{edebug-test-coverage} is non-@code{nil}. Frequency counting is -performed for all execution of an instrumented function, even if the -execution mode is Go-nonstop, and regardless of whether coverage testing -is enabled. - -@kindex C-x X = -@findex edebug-temp-display-freq-count - Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both -the coverage information and the frequency counts for a definition. -Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same -information temporarily, only until you type another key. - -@deffn Command edebug-display-freq-count -This command displays the frequency count data for each line of the -current definition. - -The frequency counts appear as comment lines after each line of code, -and you can undo all insertions with one @code{undo} command. The -counts appear under the @samp{(} before an expression or the @samp{)} -after an expression, or on the last character of a variable. To -simplify the display, a count is not shown if it is equal to the -count of an earlier expression on the same line. - -The character @samp{=} following the count for an expression says that -the expression has returned the same value each time it was evaluated. -In other words, it is not yet ``covered'' for coverage testing purposes. - -To clear the frequency count and coverage data for a definition, -simply reinstrument it with @code{eval-defun}. -@end deffn - -For example, after evaluating @code{(fac 5)} with a source -breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when -the breakpoint is reached, the frequency data looks like this: - -@example -(defun fac (n) - (if (= n 0) (edebug)) -;#6 1 = =5 - (if (< 0 n) -;#5 = - (* n (fac (1- n))) -;# 5 0 - 1)) -;# 0 -@end example - -The comment lines show that @code{fac} was called 6 times. The -first @code{if} statement returned 5 times with the same result each -time; the same is true of the condition on the second @code{if}. -The recursive call of @code{fac} did not return at all. - - -@node The Outside Context -@subsection The Outside Context - -Edebug tries to be transparent to the program you are debugging, but it -does not succeed completely. Edebug also tries to be transparent when -you evaluate expressions with @kbd{e} or with the evaluation list -buffer, by temporarily restoring the outside context. This section -explains precisely what context Edebug restores, and how Edebug fails to -be completely transparent. - -@menu -* Checking Whether to Stop:: When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. -@end menu - -@node Checking Whether to Stop -@subsubsection Checking Whether to Stop - -Whenever Edebug is entered, it needs to save and restore certain data -before even deciding whether to make trace information or stop the -program. - -@itemize @bullet -@item -@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both -incremented once to reduce Edebug's impact on the stack. You could, -however, still run out of stack space when using Edebug. - -@item -The state of keyboard macro execution is saved and restored. While -Edebug is active, @code{executing-kbd-macro} is bound to @code{nil} -unless @code{edebug-continue-kbd-macro} is non-@code{nil}. -@end itemize - - -@node Edebug Display Update -@subsubsection Edebug Display Update - -@c This paragraph is not filled, because LaLiberte's conversion script -@c needs an xref to be on just one line. -When Edebug needs to display something (e.g., in trace mode), it saves -the current window configuration from ``outside'' Edebug -(@pxref{Window Configurations}). When you exit Edebug (by continuing -the program), it restores the previous window configuration. - -Emacs redisplays only when it pauses. Usually, when you continue -execution, the program re-enters Edebug at a breakpoint or after -stepping, without pausing or reading input in between. In such cases, -Emacs never gets a chance to redisplay the ``outside'' configuration. -Consequently, what you see is the same window configuration as the last -time Edebug was active, with no interruption. - -Entry to Edebug for displaying something also saves and restores the -following data (though some of them are deliberately not restored if an -error or quit signal occurs). - -@itemize @bullet -@item -@cindex current buffer point and mark (Edebug) -Which buffer is current, and the positions of point and the mark in the -current buffer, are saved and restored. - -@item -@cindex window configuration (Edebug) -The outside window configuration is saved and restored if -@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}). - -The window configuration is not restored on error or quit, but the -outside selected window @emph{is} reselected even on error or quit in -case a @code{save-excursion} is active. If the value of -@code{edebug-save-windows} is a list, only the listed windows are saved -and restored. - -The window start and horizontal scrolling of the source code buffer are -not restored, however, so that the display remains coherent within Edebug. - -@item -The value of point in each displayed buffer is saved and restored if -@code{edebug-save-displayed-buffer-points} is non-@code{nil}. - -@item -The variables @code{overlay-arrow-position} and -@code{overlay-arrow-string} are saved and restored. So you can safely -invoke Edebug from the recursive edit elsewhere in the same buffer. - -@item -@code{cursor-in-echo-area} is locally bound to @code{nil} so that -the cursor shows up in the window. -@end itemize - -@node Edebug Recursive Edit -@subsubsection Edebug Recursive Edit - -When Edebug is entered and actually reads commands from the user, it -saves (and later restores) these additional data: - -@itemize @bullet -@item -The current match data. @xref{Match Data}. - -@item -The variables @code{last-command}, @code{this-command}, -@code{last-command-char}, @code{last-input-char}, -@code{last-input-event}, @code{last-command-event}, -@code{last-event-frame}, @code{last-nonmenu-event}, and -@code{track-mouse}. Commands used within Edebug do not affect these -variables outside of Edebug. - -Executing commands within Edebug can change the key sequence that -would be returned by @code{this-command-keys}, and there is no way to -reset the key sequence from Lisp. - -Edebug cannot save and restore the value of -@code{unread-command-events}. Entering Edebug while this variable has a -nontrivial value can interfere with execution of the program you are -debugging. - -@item -Complex commands executed while in Edebug are added to the variable -@code{command-history}. In rare cases this can alter execution. - -@item -Within Edebug, the recursion depth appears one deeper than the recursion -depth outside Edebug. This is not true of the automatically updated -evaluation list window. - -@item -@code{standard-output} and @code{standard-input} are bound to @code{nil} -by the @code{recursive-edit}, but Edebug temporarily restores them during -evaluations. - -@item -The state of keyboard macro definition is saved and restored. While -Edebug is active, @code{defining-kbd-macro} is bound to -@code{edebug-continue-kbd-macro}. -@end itemize - -@node Edebug and Macros -@subsection Edebug and Macros - -To make Edebug properly instrument expressions that call macros, some -extra care is needed. This subsection explains the details. - -@menu -* Instrumenting Macro Calls:: The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. -@end menu - -@node Instrumenting Macro Calls -@subsubsection Instrumenting Macro Calls - - When Edebug instruments an expression that calls a Lisp macro, it needs -additional information about the macro to do the job properly. This is -because there is no a-priori way to tell which subexpressions of the -macro call are forms to be evaluated. (Evaluation may occur explicitly -in the macro body, or when the resulting expansion is evaluated, or any -time later.) - - Therefore, you must define an Edebug specification for each macro -that Edebug will encounter, to explain the format of calls to that -macro. To do this, add a @code{debug} declaration to the macro -definition. Here is a simple example that shows the specification for -the @code{for} example macro (@pxref{Argument Evaluation}). - -@smallexample -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - (declare (debug (symbolp "from" form "to" form "do" &rest form))) - ...) -@end smallexample - - The Edebug specification says which parts of a call to the macro are -forms to be evaluated. For simple macros, the @var{specification} -often looks very similar to the formal argument list of the macro -definition, but specifications are much more general than macro -arguments. @xref{Defining Macros}, for more explanation of -the @code{declare} form. - - You can also define an edebug specification for a macro separately -from the macro definition with @code{def-edebug-spec}. Adding -@code{debug} declarations is preferred, and more convenient, for macro -definitions in Lisp, but @code{def-edebug-spec} makes it possible to -define Edebug specifications for special forms implemented in C. - -@deffn Macro def-edebug-spec macro specification -Specify which expressions of a call to macro @var{macro} are forms to be -evaluated. @var{specification} should be the edebug specification. -Neither argument is evaluated. - -The @var{macro} argument can actually be any symbol, not just a macro -name. -@end deffn - -Here is a table of the possibilities for @var{specification} and how each -directs processing of arguments. - -@table @asis -@item @code{t} -All arguments are instrumented for evaluation. - -@item @code{0} -None of the arguments is instrumented. - -@item a symbol -The symbol must have an Edebug specification which is used instead. -This indirection is repeated until another kind of specification is -found. This allows you to inherit the specification from another macro. - -@item a list -The elements of the list describe the types of the arguments of a -calling form. The possible elements of a specification list are -described in the following sections. -@end table - -@vindex edebug-eval-macro-args -If a macro has no Edebug specification, neither through a @code{debug} -declaration nor through a @code{def-edebug-spec} call, the variable -@code{edebug-eval-macro-args} comes into play. If it is @code{nil}, -the default, none of the arguments is instrumented for evaluation. -If it is non-@code{nil}, all arguments are instrumented. - -@node Specification List -@subsubsection Specification List - -@cindex Edebug specification list -A @dfn{specification list} is required for an Edebug specification if -some arguments of a macro call are evaluated while others are not. Some -elements in a specification list match one or more arguments, but others -modify the processing of all following elements. The latter, called -@dfn{specification keywords}, are symbols beginning with @samp{&} (such -as @code{&optional}). - -A specification list may contain sublists which match arguments that are -themselves lists, or it may contain vectors used for grouping. Sublists -and groups thus subdivide the specification list into a hierarchy of -levels. Specification keywords apply only to the remainder of the -sublist or group they are contained in. - -When a specification list involves alternatives or repetition, matching -it against an actual macro call may require backtracking. -@xref{Backtracking}, for more details. - -Edebug specifications provide the power of regular expression matching, -plus some context-free grammar constructs: the matching of sublists with -balanced parentheses, recursive processing of forms, and recursion via -indirect specifications. - -Here's a table of the possible elements of a specification list, with -their meanings (see @ref{Specification Examples}, for the referenced -examples): - -@table @code -@item sexp -A single unevaluated Lisp object, which is not instrumented. -@c an "expression" is not necessarily intended for evaluation. - -@item form -A single evaluated expression, which is instrumented. - -@item place -@findex edebug-unwrap -A place to store a value, as in the Common Lisp @code{setf} construct. - -@item body -Short for @code{&rest form}. See @code{&rest} below. - -@item function-form -A function form: either a quoted function symbol, a quoted lambda -expression, or a form (that should evaluate to a function symbol or -lambda expression). This is useful when an argument that's a lambda -expression might be quoted with @code{quote} rather than -@code{function}, since it instruments the body of the lambda expression -either way. - -@item lambda-expr -A lambda expression with no quoting. - -@item &optional -@c @kindex &optional @r{(Edebug)} -All following elements in the specification list are optional; as soon -as one does not match, Edebug stops matching at this level. - -To make just a few elements optional followed by non-optional elements, -use @code{[&optional @var{specs}@dots{}]}. To specify that several -elements must all match or none, use @code{&optional -[@var{specs}@dots{}]}. See the @code{defun} example. - -@item &rest -@c @kindex &rest @r{(Edebug)} -All following elements in the specification list are repeated zero or -more times. In the last repetition, however, it is not a problem if the -expression runs out before matching all of the elements of the -specification list. - -To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}. -To specify several elements that must all match on every repetition, use -@code{&rest [@var{specs}@dots{}]}. - -@item &or -@c @kindex &or @r{(Edebug)} -Each of the following elements in the specification list is an -alternative. One of the alternatives must match, or the @code{&or} -specification fails. - -Each list element following @code{&or} is a single alternative. To -group two or more list elements as a single alternative, enclose them in -@code{[@dots{}]}. - -@item ¬ -@c @kindex ¬ @r{(Edebug)} -Each of the following elements is matched as alternatives as if by using -@code{&or}, but if any of them match, the specification fails. If none -of them match, nothing is matched, but the @code{¬} specification -succeeds. - -@item &define -@c @kindex &define @r{(Edebug)} -Indicates that the specification is for a defining form. The defining -form itself is not instrumented (that is, Edebug does not stop before and -after the defining form), but forms inside it typically will be -instrumented. The @code{&define} keyword should be the first element in -a list specification. - -@item nil -This is successful when there are no more arguments to match at the -current argument list level; otherwise it fails. See sublist -specifications and the backquote example. - -@item gate -@cindex preventing backtracking -No argument is matched but backtracking through the gate is disabled -while matching the remainder of the specifications at this level. This -is primarily used to generate more specific syntax error messages. See -@ref{Backtracking}, for more details. Also see the @code{let} example. - -@item @var{other-symbol} -@cindex indirect specifications -Any other symbol in a specification list may be a predicate or an -indirect specification. - -If the symbol has an Edebug specification, this @dfn{indirect -specification} should be either a list specification that is used in -place of the symbol, or a function that is called to process the -arguments. The specification may be defined with @code{def-edebug-spec} -just as for macros. See the @code{defun} example. - -Otherwise, the symbol should be a predicate. The predicate is called -with the argument and the specification fails if the predicate returns -@code{nil}. In either case, that argument is not instrumented. - -Some suitable predicates include @code{symbolp}, @code{integerp}, -@code{stringp}, @code{vectorp}, and @code{atom}. - -@item [@var{elements}@dots{}] -@cindex [@dots{}] (Edebug) -A vector of elements groups the elements into a single @dfn{group -specification}. Its meaning has nothing to do with vectors. - -@item "@var{string}" -The argument should be a symbol named @var{string}. This specification -is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name -of @var{symbol} is the @var{string}, but the string form is preferred. - -@item (vector @var{elements}@dots{}) -The argument should be a vector whose elements must match the -@var{elements} in the specification. See the backquote example. - -@item (@var{elements}@dots{}) -Any other list is a @dfn{sublist specification} and the argument must be -a list whose elements match the specification @var{elements}. - -@cindex dotted lists (Edebug) -A sublist specification may be a dotted list and the corresponding list -argument may then be a dotted list. Alternatively, the last @sc{cdr} of a -dotted list specification may be another sublist specification (via a -grouping or an indirect specification, e.g., @code{(spec . [(more -specs@dots{})])}) whose elements match the non-dotted list arguments. -This is useful in recursive specifications such as in the backquote -example. Also see the description of a @code{nil} specification -above for terminating such recursion. - -Note that a sublist specification written as @code{(specs . nil)} -is equivalent to @code{(specs)}, and @code{(specs . -(sublist-elements@dots{}))} is equivalent to @code{(specs -sublist-elements@dots{})}. -@end table - -@c Need to document extensions with &symbol and :symbol - -Here is a list of additional specifications that may appear only after -@code{&define}. See the @code{defun} example. - -@table @code -@item name -The argument, a symbol, is the name of the defining form. - -A defining form is not required to have a name field; and it may have -multiple name fields. - -@item :name -This construct does not actually match an argument. The element -following @code{:name} should be a symbol; it is used as an additional -name component for the definition. You can use this to add a unique, -static component to the name of the definition. It may be used more -than once. - -@item arg -The argument, a symbol, is the name of an argument of the defining form. -However, lambda-list keywords (symbols starting with @samp{&}) -are not allowed. - -@item lambda-list -@cindex lambda-list (Edebug) -This matches a lambda list---the argument list of a lambda expression. - -@item def-body -The argument is the body of code in a definition. This is like -@code{body}, described above, but a definition body must be instrumented -with a different Edebug call that looks up information associated with -the definition. Use @code{def-body} for the highest level list of forms -within the definition. - -@item def-form -The argument is a single, highest-level form in a definition. This is -like @code{def-body}, except use this to match a single form rather than -a list of forms. As a special case, @code{def-form} also means that -tracing information is not output when the form is executed. See the -@code{interactive} example. -@end table - -@node Backtracking -@subsubsection Backtracking in Specifications - -@cindex backtracking -@cindex syntax error (Edebug) -If a specification fails to match at some point, this does not -necessarily mean a syntax error will be signaled; instead, -@dfn{backtracking} will take place until all alternatives have been -exhausted. Eventually every element of the argument list must be -matched by some element in the specification, and every required element -in the specification must match some argument. - -When a syntax error is detected, it might not be reported until much -later after higher-level alternatives have been exhausted, and with the -point positioned further from the real error. But if backtracking is -disabled when an error occurs, it can be reported immediately. Note -that backtracking is also reenabled automatically in several situations; -it is reenabled when a new alternative is established by -@code{&optional}, @code{&rest}, or @code{&or}, or at the start of -processing a sublist, group, or indirect specification. The effect of -enabling or disabling backtracking is limited to the remainder of the -level currently being processed and lower levels. - -Backtracking is disabled while matching any of the -form specifications (that is, @code{form}, @code{body}, @code{def-form}, and -@code{def-body}). These specifications will match any form so any error -must be in the form itself rather than at a higher level. - -Backtracking is also disabled after successfully matching a quoted -symbol or string specification, since this usually indicates a -recognized construct. But if you have a set of alternative constructs that -all begin with the same symbol, you can usually work around this -constraint by factoring the symbol out of the alternatives, e.g., -@code{["foo" &or [first case] [second case] ...]}. - -Most needs are satisfied by these two ways that backtracking is -automatically disabled, but occasionally it is useful to explicitly -disable backtracking by using the @code{gate} specification. This is -useful when you know that no higher alternatives could apply. See the -example of the @code{let} specification. - -@node Specification Examples -@subsubsection Specification Examples - -It may be easier to understand Edebug specifications by studying -the examples provided here. - -A @code{let} special form has a sequence of bindings and a body. Each -of the bindings is either a symbol or a sublist with a symbol and -optional expression. In the specification below, notice the @code{gate} -inside of the sublist to prevent backtracking once a sublist is found. - -@example -(def-edebug-spec let - ((&rest - &or symbolp (gate symbolp &optional form)) - body)) -@end example - -Edebug uses the following specifications for @code{defun} and -@code{defmacro} and the associated argument list and @code{interactive} -specifications. It is necessary to handle interactive forms specially -since an expression argument is actually evaluated outside of the -function body. - -@smallexample -(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.} -(def-edebug-spec defun - (&define name lambda-list - [&optional stringp] ; @r{Match the doc string, if present.} - [&optional ("interactive" interactive)] - def-body)) - -(def-edebug-spec lambda-list - (([&rest arg] - [&optional ["&optional" arg &rest arg]] - &optional ["&rest" arg] - ))) - -(def-edebug-spec interactive - (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}} -@end smallexample - -The specification for backquote below illustrates how to match -dotted lists and use @code{nil} to terminate recursion. It also -illustrates how components of a vector may be matched. (The actual -specification defined by Edebug does not support dotted lists because -doing so causes very deep recursion that could fail.) - -@smallexample -(def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.} - -(def-edebug-spec backquote-form - (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) - (backquote-form . [&or nil backquote-form]) - (vector &rest backquote-form) - sexp)) -@end smallexample - - -@node Edebug Options -@subsection Edebug Options - - These options affect the behavior of Edebug: - -@defopt edebug-setup-hook -Functions to call before Edebug is used. Each time it is set to a new -value, Edebug will call those functions once and then -@code{edebug-setup-hook} is reset to @code{nil}. You could use this to -load up Edebug specifications associated with a package you are using -but only when you also use Edebug. -@xref{Instrumenting}. -@end defopt - -@defopt edebug-all-defs -If this is non-@code{nil}, normal evaluation of defining forms such as -@code{defun} and @code{defmacro} instruments them for Edebug. This -applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer}, -and @code{eval-current-buffer}. - -Use the command @kbd{M-x edebug-all-defs} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-all-forms -If this is non-@code{nil}, the commands @code{eval-defun}, -@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer} -instrument all forms, even those that don't define anything. -This doesn't apply to loading or evaluations in the minibuffer. - -Use the command @kbd{M-x edebug-all-forms} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-save-windows -If this is non-@code{nil}, Edebug saves and restores the window -configuration. That takes some time, so if your program does not care -what happens to the window configurations, it is better to set this -variable to @code{nil}. - -If the value is a list, only the listed windows are saved and -restored. - -You can use the @kbd{W} command in Edebug to change this variable -interactively. @xref{Edebug Display Update}. -@end defopt - -@defopt edebug-save-displayed-buffer-points -If this is non-@code{nil}, Edebug saves and restores point in all -displayed buffers. - -Saving and restoring point in other buffers is necessary if you are -debugging code that changes the point of a buffer which is displayed in -a non-selected window. If Edebug or the user then selects the window, -point in that buffer will move to the window's value of point. - -Saving and restoring point in all buffers is expensive, since it -requires selecting each window twice, so enable this only if you need -it. @xref{Edebug Display Update}. -@end defopt - -@defopt edebug-initial-mode -If this variable is non-@code{nil}, it specifies the initial execution -mode for Edebug when it is first activated. Possible values are -@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace}, -@code{Trace-fast}, @code{continue}, and @code{Continue-fast}. - -The default value is @code{step}. -@xref{Edebug Execution Modes}. -@end defopt - -@defopt edebug-trace -If this is non-@code{nil}, trace each function entry and exit. -Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one -function entry or exit per line, indented by the recursion level. - -Also see @code{edebug-tracing}, in @ref{Trace Buffer}. -@end defopt - -@defopt edebug-test-coverage -If non-@code{nil}, Edebug tests coverage of all expressions debugged. -@xref{Coverage Testing}. -@end defopt - -@defopt edebug-continue-kbd-macro -If non-@code{nil}, continue defining or executing any keyboard macro -that is executing outside of Edebug. Use this with caution since it is not -debugged. -@xref{Edebug Execution Modes}. -@end defopt - -@defopt edebug-on-error -Edebug binds @code{debug-on-error} to this value, if -@code{debug-on-error} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - -@defopt edebug-on-quit -Edebug binds @code{debug-on-quit} to this value, if -@code{debug-on-quit} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - - If you change the values of @code{edebug-on-error} or -@code{edebug-on-quit} while Edebug is active, their values won't be used -until the @emph{next} time Edebug is invoked via a new command. -@c Not necessarily a deeper command level. -@c A new command is not precisely true, but that is close enough -- dan - -@defopt edebug-global-break-condition -If non-@code{nil}, an expression to test for at every stop point. If -the result is non-@code{nil}, then break. Errors are ignored. -@xref{Global Break Condition}. -@end defopt - -@ignore - arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd -@end ignore diff --git a/lispref/elisp-covers.texi b/lispref/elisp-covers.texi deleted file mode 100644 index 4b9693dece7..00000000000 --- a/lispref/elisp-covers.texi +++ /dev/null @@ -1,257 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@comment %**start of header -@setfilename covers.info -@settitle GNU Emacs Lisp Reference Manual -@comment %**end of header - -@titlepage -@c ================ Volume 1 ================ -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 ================ -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, -@center Dan LaLiberte, and -@center the GNU Manual Group - -@page -@c ================ Volume 1 with baseline skip 16pt ================ - -@tex -\global\baselineskip = 16pt -@end tex - -16 pts baseline skip: - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 1 with baseline skip 18pt ================ - -@tex -\global\baselineskip = 18pt -@end tex - -18 pts baseline skip, with 15pts between sections - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@tex -\global\baselineskip = 15pt -@end tex - -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, -@center Dan LaLiberte, and -@center the GNU Manual Group - -@page -@c ================ Volume 1 with more baseline skip 24 pts ================ - -@tex -\global\baselineskip = 24pt -@end tex - -24 pts baseline skip: - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 with more baseline skip 18 pts ================ - -@tex -\global\baselineskip = 18pt -@end tex - -18 pts baseline skip: - -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 with more baseline skip 24 pts ================ - -@tex -\global\baselineskip = 24pt -@end tex - -24 pts baseline skip: - -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - - -@page -@c ================ Spine 1 ================ - -@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 1}} -@sp 4 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 4 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@sp 4 -@author The GNU Emacs Lisp Reference Manual --- Vol. 1 -@sp 3 -@author FSF - -@author - -@page -@c ================ Spine 2 ================ - -@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 2}} -@sp 4 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 4 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - - -@sp 4 -@author The GNU Emacs Lisp Reference Manual --- Vol. 2 -@sp 3 -@author FSF - -@end titlepage -@bye - -@ignore - arch-tag: 02d65d63-3b64-49bc-a5c0-bfd5eabb6c98 -@end ignore diff --git a/lispref/elisp.texi b/lispref/elisp.texi deleted file mode 100644 index 613bdbace38..00000000000 --- a/lispref/elisp.texi +++ /dev/null @@ -1,1483 +0,0 @@ -\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 23.0.50 - -@dircategory Emacs -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. The manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@c set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -@set EMACSVER 22.1 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % 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, 2001, 2002, 2003, 2004, 2005, 2006, 2007 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 are free to copy and modify -this GNU Manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, April 2007 - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman -@author and the GNU Manual Group -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -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 - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- 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. -* 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 description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -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. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -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. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -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:: Recording the way a frame is subdivided. -* 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 to 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. -* List Variables:: Modifying lists stored in variables. -* 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:: Special characteristics of Emacs Lisp 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. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. - -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. -* Standard Errors:: List of all error symbols. - -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. -* Standard Buffer-Local Variables:: - List of variables buffer-local in all buffers. - -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. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -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. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, number, - string, file, directory, alist. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -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. - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. -* Accessing Events:: Functions to extract info from events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -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:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A 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:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* 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. -* Standard Keymaps:: List of standard keymaps. - -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. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. - -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. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Setting Syntax Properties:: Defining character syntax based on context - using the Font Lock mechanism. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property -* Region to Fontify:: Controlling which region gets refontified - after a buffer change. - -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. -* Locating Files:: How to find a file in standard places. - -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-level 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 Tree:: The layout and sizes of all windows in a frame. -* 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 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 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. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* 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. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Color Parameters:: Colors of various parts of the frame. - -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. -* 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 character 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. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. - -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 of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -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. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -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. - -Low-Level Network Access - -* Proc: Network Processes. Using @code{make-network-process}. -* Options: Network Options. Further control over network connections. -* Features: Network Feature Testing. - Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -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. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize their warnings. -* Warning Options:: Variables users set to control display of warnings. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Defining Faces:: How to define a face with @code{defface}. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Font Selection:: Finding the best available font for a face. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; magnifying text; moving it - up or down on the page; adjusting the width - of spaces within text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* PostScript Images:: Special features for PostScript format. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Display Tables - -* Display Table Format:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. - -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. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording 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. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -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 the dumped Emacs is made. -* 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 detailmenu -@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 diff --git a/lispref/errors.texi b/lispref/errors.texi deleted file mode 100644 index af2df791c39..00000000000 --- a/lispref/errors.texi +++ /dev/null @@ -1,209 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/errors -@node Standard Errors, Standard Buffer-Local Variables, GNU Emacs Internals, Top -@appendix Standard Errors -@cindex standard errors - - Here is the complete list of the error symbols in standard Emacs, -grouped by concept. The list includes each symbol's message (on the -@code{error-message} property of the symbol) and a cross reference to a -description of how the error can occur. - - Each error symbol has an @code{error-conditions} property that is a -list of symbols. Normally this list includes the error symbol itself -and the symbol @code{error}. Occasionally it includes additional -symbols, which are intermediate classifications, narrower than -@code{error} but broader than a single error symbol. For example, all -the errors in accessing files have the condition @code{file-error}. If -we do not say here that a certain error symbol has additional error -conditions, that means it has none. - - As a special exception, the error symbol @code{quit} does not have the -condition @code{error}, because quitting is not considered an error. - - @xref{Errors}, for an explanation of how errors are generated and -handled. - -@table @code -@item @var{symbol} -@var{string}; @var{reference}. - -@item error -@code{"error"}@* -@xref{Errors}. - -@item quit -@code{"Quit"}@* -@xref{Quitting}. - -@item args-out-of-range -@code{"Args out of range"}@* -This happens when trying to access an element beyond the range of a -sequence or buffer.@* -@xref{Sequences Arrays Vectors}, @xref{Text}. - -@item arith-error -@code{"Arithmetic error"}@* -@xref{Arithmetic Operations}. - -@item beginning-of-buffer -@code{"Beginning of buffer"}@* -@xref{Character Motion}. - -@item buffer-read-only -@code{"Buffer is read-only"}@* -@xref{Read Only Buffers}. - -@item coding-system-error -@code{"Invalid coding system"}@* -@xref{Lisp and Coding Systems}. - -@item cyclic-function-indirection -@code{"Symbol's chain of function indirections\@* contains a loop"}@* -@xref{Function Indirection}. - -@item cyclic-variable-indirection -@code{"Symbol's chain of variable indirections\@* contains a loop"}@* -@xref{Variable Aliases}. - -@item end-of-buffer -@code{"End of buffer"}@* -@xref{Character Motion}. - -@item end-of-file -@code{"End of file during parsing"}@* -Note that this is not a subcategory of @code{file-error}, -because it pertains to the Lisp reader, not to file I/O.@* -@xref{Input Functions}. - -@item file-already-exists -This is a subcategory of @code{file-error}.@* -@xref{Writing to Files}. - -@item file-date-error -This is a subcategory of @code{file-error}. It occurs when -@code{copy-file} tries and fails to set the last-modification time of -the output file.@* -@xref{Changing Files}. - -@item file-error -We do not list the error-strings of this error and its subcategories, -because the error message is normally constructed from the data items -alone when the error condition @code{file-error} is present. Thus, -the error-strings are not very relevant. However, these error symbols -do have @code{error-message} properties, and if no data is provided, -the @code{error-message} property @emph{is} used.@* -@xref{Files}. - -@item file-locked -This is a subcategory of @code{file-error}.@* -@xref{File Locks}. - -@item file-supersession -This is a subcategory of @code{file-error}.@* -@xref{Modification Time}. - -@item ftp-error -This is a subcategory of @code{file-error}, which results from problems -in accessing a remote file using ftp.@* -@xref{Remote Files,,, emacs, The GNU Emacs Manual}. - -@item invalid-function -@code{"Invalid function"}@* -@xref{Function Indirection}. - -@item invalid-read-syntax -@code{"Invalid read syntax"}@* -@xref{Printed Representation}. - -@item invalid-regexp -@code{"Invalid regexp"}@* -@xref{Regular Expressions}. - -@item mark-inactive -@code{"The mark is not active now"}@* -@xref{The Mark}. - -@item no-catch -@code{"No catch for tag"}@* -@xref{Catch and Throw}. - -@item scan-error -@code{"Scan error"}@* -This happens when certain syntax-parsing functions -find invalid syntax or mismatched parentheses.@* -@xref{List Motion}, and @ref{Parsing Expressions}. - -@item search-failed -@code{"Search failed"}@* -@xref{Searching and Matching}. - -@item setting-constant -@code{"Attempt to set a constant symbol"}@* -The values of the symbols @code{nil} and @code{t}, -and any symbols that start with @samp{:}, -may not be changed.@* -@xref{Constant Variables, , Variables that Never Change}. - -@item text-read-only -@code{"Text is read-only"}@* -This is a subcategory of @code{buffer-read-only}.@* -@xref{Special Properties}. - -@item undefined-color -@code{"Undefined color"}@* -@xref{Color Names}. - -@item void-function -@code{"Symbol's function definition is void"}@* -@xref{Function Cells}. - -@item void-variable -@code{"Symbol's value as variable is void"}@* -@xref{Accessing Variables}. - -@item wrong-number-of-arguments -@code{"Wrong number of arguments"}@* -@xref{Classifying Lists}. - -@item wrong-type-argument -@code{"Wrong type argument"}@* -@xref{Type Predicates}. -@end table - - These kinds of error, which are classified as special cases of -@code{arith-error}, can occur on certain systems for invalid use of -mathematical functions. - -@table @code -@item domain-error -@code{"Arithmetic domain error"}@* -@xref{Math Functions}. - -@item overflow-error -@code{"Arithmetic overflow error"}@* -This is a subcategory of @code{domain-error}.@* -@xref{Math Functions}. - -@item range-error -@code{"Arithmetic range error"}@* -@xref{Math Functions}. - -@item singularity-error -@code{"Arithmetic singularity error"}@* -This is a subcategory of @code{domain-error}.@* -@xref{Math Functions}. - -@item underflow-error -@code{"Arithmetic underflow error"}@* -This is a subcategory of @code{domain-error}.@* -@xref{Math Functions}. -@end table - -@ignore - arch-tag: 717c6048-5d9d-4c7d-9a62-df57390b6f19 -@end ignore diff --git a/lispref/eval.texi b/lispref/eval.texi deleted file mode 100644 index 772f502553c..00000000000 --- a/lispref/eval.texi +++ /dev/null @@ -1,758 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/eval -@node Evaluation, Control Structures, Symbols, Top -@chapter Evaluation -@cindex evaluation -@cindex interpreter -@cindex interpreter -@cindex value of expression - - The @dfn{evaluation} of expressions in Emacs Lisp is performed by the -@dfn{Lisp interpreter}---a program that receives a Lisp object as input -and computes its @dfn{value as an expression}. How it does this depends -on the data type of the object, according to rules described in this -chapter. The interpreter runs automatically to evaluate portions of -your program, but can also be called explicitly via the Lisp primitive -function @code{eval}. - -@ifnottex -@menu -* 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. -@end menu - -@node Intro Eval -@section Introduction to Evaluation - - The Lisp interpreter, or evaluator, is the program that computes -the value of an expression that is given to it. When a function -written in Lisp is called, the evaluator computes the value of the -function by evaluating the expressions in the function body. Thus, -running any Lisp program really means running the Lisp interpreter. - - How the evaluator handles an object depends primarily on the data -type of the object. -@end ifnottex - -@cindex forms -@cindex expression - A Lisp object that is intended for evaluation is called an -@dfn{expression} or a @dfn{form}. The fact that expressions are data -objects and not merely text is one of the fundamental differences -between Lisp-like languages and typical programming languages. Any -object can be evaluated, but in practice only numbers, symbols, lists -and strings are evaluated very often. - - It is very common to read a Lisp expression and then evaluate the -expression, but reading and evaluation are separate activities, and -either can be performed alone. Reading per se does not evaluate -anything; it converts the printed representation of a Lisp object to the -object itself. It is up to the caller of @code{read} whether this -object is a form to be evaluated, or serves some entirely different -purpose. @xref{Input Functions}. - - Do not confuse evaluation with command key interpretation. The -editor command loop translates keyboard input into a command (an -interactively callable function) using the active keymaps, and then -uses @code{call-interactively} to invoke the command. The execution of -the command itself involves evaluation if the command is written in -Lisp, but that is not a part of command key interpretation itself. -@xref{Command Loop}. - -@cindex recursive evaluation - Evaluation is a recursive process. That is, evaluation of a form may -call @code{eval} to evaluate parts of the form. For example, evaluation -of a function call first evaluates each argument of the function call, -and then evaluates each form in the function body. Consider evaluation -of the form @code{(car x)}: the subform @code{x} must first be evaluated -recursively, so that its value can be passed as an argument to the -function @code{car}. - - Evaluation of a function call ultimately calls the function specified -in it. @xref{Functions}. The execution of the function may itself work -by evaluating the function definition; or the function may be a Lisp -primitive implemented in C, or it may be a byte-compiled function -(@pxref{Byte Compilation}). - -@cindex environment - The evaluation of forms takes place in a context called the -@dfn{environment}, which consists of the current values and bindings of -all Lisp variables.@footnote{This definition of ``environment'' is -specifically not intended to include all the data that can affect the -result of a program.} Whenever a form refers to a variable without -creating a new binding for it, the value of the variable's binding in -the current environment is used. @xref{Variables}. - -@cindex side effect - Evaluation of a form may create new environments for recursive -evaluation by binding variables (@pxref{Local Variables}). These -environments are temporary and vanish by the time evaluation of the form -is complete. The form may also make changes that persist; these changes -are called @dfn{side effects}. An example of a form that produces side -effects is @code{(setq foo 1)}. - - The details of what evaluation means for each kind of form are -described below (@pxref{Forms}). - -@node Forms -@section Kinds of Forms - - A Lisp object that is intended to be evaluated is called a @dfn{form}. -How Emacs evaluates a form depends on its data type. Emacs has three -different kinds of form that are evaluated differently: symbols, lists, -and ``all other types.'' This section describes all three kinds, one by -one, starting with the ``all other types'' which are self-evaluating -forms. - -@menu -* 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. -@end menu - -@node Self-Evaluating Forms -@subsection Self-Evaluating Forms -@cindex vector evaluation -@cindex literal evaluation -@cindex self-evaluating form - - A @dfn{self-evaluating form} is any form that is not a list or symbol. -Self-evaluating forms evaluate to themselves: the result of evaluation -is the same object that was evaluated. Thus, the number 25 evaluates to -25, and the string @code{"foo"} evaluates to the string @code{"foo"}. -Likewise, evaluation of a vector does not cause evaluation of the -elements of the vector---it returns the same vector with its contents -unchanged. - -@example -@group -'123 ; @r{A number, shown without evaluation.} - @result{} 123 -@end group -@group -123 ; @r{Evaluated as usual---result is the same.} - @result{} 123 -@end group -@group -(eval '123) ; @r{Evaluated ``by hand''---result is the same.} - @result{} 123 -@end group -@group -(eval (eval '123)) ; @r{Evaluating twice changes nothing.} - @result{} 123 -@end group -@end example - - It is common to write numbers, characters, strings, and even vectors -in Lisp code, taking advantage of the fact that they self-evaluate. -However, it is quite unusual to do this for types that lack a read -syntax, because there's no way to write them textually. It is possible -to construct Lisp expressions containing these types by means of a Lisp -program. Here is an example: - -@example -@group -;; @r{Build an expression containing a buffer object.} -(setq print-exp (list 'print (current-buffer))) - @result{} (print #<buffer eval.texi>) -@end group -@group -;; @r{Evaluate it.} -(eval print-exp) - @print{} #<buffer eval.texi> - @result{} #<buffer eval.texi> -@end group -@end example - -@node Symbol Forms -@subsection Symbol Forms -@cindex symbol evaluation - - When a symbol is evaluated, it is treated as a variable. The result -is the variable's value, if it has one. If it has none (if its value -cell is void), an error is signaled. For more information on the use of -variables, see @ref{Variables}. - - In the following example, we set the value of a symbol with -@code{setq}. Then we evaluate the symbol, and get back the value that -@code{setq} stored. - -@example -@group -(setq a 123) - @result{} 123 -@end group -@group -(eval 'a) - @result{} 123 -@end group -@group -a - @result{} 123 -@end group -@end example - - The symbols @code{nil} and @code{t} are treated specially, so that the -value of @code{nil} is always @code{nil}, and the value of @code{t} is -always @code{t}; you cannot set or bind them to any other values. Thus, -these two symbols act like self-evaluating forms, even though -@code{eval} treats them like any other symbol. A symbol whose name -starts with @samp{:} also self-evaluates in the same way; likewise, -its value ordinarily cannot be changed. @xref{Constant Variables}. - -@node Classifying Lists -@subsection Classification of List Forms -@cindex list form evaluation - - A form that is a nonempty list is either a function call, a macro -call, or a special form, according to its first element. These three -kinds of forms are evaluated in different ways, described below. The -remaining list elements constitute the @dfn{arguments} for the function, -macro, or special form. - - The first step in evaluating a nonempty list is to examine its first -element. This element alone determines what kind of form the list is -and how the rest of the list is to be processed. The first element is -@emph{not} evaluated, as it would be in some Lisp dialects such as -Scheme. - -@node Function Indirection -@subsection Symbol Function Indirection -@cindex symbol function indirection -@cindex indirection for functions -@cindex void function - - If the first element of the list is a symbol then evaluation examines -the symbol's function cell, and uses its contents instead of the -original symbol. If the contents are another symbol, this process, -called @dfn{symbol function indirection}, is repeated until it obtains a -non-symbol. @xref{Function Names}, for more information about using a -symbol as a name for a function stored in the function cell of the -symbol. - - One possible consequence of this process is an infinite loop, in the -event that a symbol's function cell refers to the same symbol. Or a -symbol may have a void function cell, in which case the subroutine -@code{symbol-function} signals a @code{void-function} error. But if -neither of these things happens, we eventually obtain a non-symbol, -which ought to be a function or other suitable object. - -@kindex invalid-function - More precisely, we should now have a Lisp function (a lambda -expression), a byte-code function, a primitive function, a Lisp macro, a -special form, or an autoload object. Each of these types is a case -described in one of the following sections. If the object is not one of -these types, the error @code{invalid-function} is signaled. - - The following example illustrates the symbol indirection process. We -use @code{fset} to set the function cell of a symbol and -@code{symbol-function} to get the function cell contents -(@pxref{Function Cells}). Specifically, we store the symbol @code{car} -into the function cell of @code{first}, and the symbol @code{first} into -the function cell of @code{erste}. - -@smallexample -@group -;; @r{Build this function cell linkage:} -;; ------------- ----- ------- ------- -;; | #<subr car> | <-- | car | <-- | first | <-- | erste | -;; ------------- ----- ------- ------- -@end group -@end smallexample - -@smallexample -@group -(symbol-function 'car) - @result{} #<subr car> -@end group -@group -(fset 'first 'car) - @result{} car -@end group -@group -(fset 'erste 'first) - @result{} first -@end group -@group -(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.} - @result{} 1 -@end group -@end smallexample - - By contrast, the following example calls a function without any symbol -function indirection, because the first element is an anonymous Lisp -function, not a symbol. - -@smallexample -@group -((lambda (arg) (erste arg)) - '(1 2 3)) - @result{} 1 -@end group -@end smallexample - -@noindent -Executing the function itself evaluates its body; this does involve -symbol function indirection when calling @code{erste}. - - The built-in function @code{indirect-function} provides an easy way to -perform symbol function indirection explicitly. - -@c Emacs 19 feature -@defun indirect-function function &optional noerror -@anchor{Definition of indirect-function} -This function returns the meaning of @var{function} as a function. If -@var{function} is a symbol, then it finds @var{function}'s function -definition and starts over with that value. If @var{function} is not a -symbol, then it returns @var{function} itself. - -This function signals a @code{void-function} error if the final symbol -is unbound and optional argument @var{noerror} is @code{nil} or -omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns -@code{nil} if the final symbol is unbound. - -It signals a @code{cyclic-function-indirection} error if there is a -loop in the chain of symbols. - -Here is how you could define @code{indirect-function} in Lisp: - -@smallexample -(defun indirect-function (function) - (if (symbolp function) - (indirect-function (symbol-function function)) - function)) -@end smallexample -@end defun - -@node Function Forms -@subsection Evaluation of Function Forms -@cindex function form evaluation -@cindex function call - - If the first element of a list being evaluated is a Lisp function -object, byte-code object or primitive function object, then that list is -a @dfn{function call}. For example, here is a call to the function -@code{+}: - -@example -(+ 1 x) -@end example - - The first step in evaluating a function call is to evaluate the -remaining elements of the list from left to right. The results are the -actual argument values, one value for each list element. The next step -is to call the function with this list of arguments, effectively using -the function @code{apply} (@pxref{Calling Functions}). If the function -is written in Lisp, the arguments are used to bind the argument -variables of the function (@pxref{Lambda Expressions}); then the forms -in the function body are evaluated in order, and the value of the last -body form becomes the value of the function call. - -@node Macro Forms -@subsection Lisp Macro Evaluation -@cindex macro call evaluation - - If the first element of a list being evaluated is a macro object, then -the list is a @dfn{macro call}. When a macro call is evaluated, the -elements of the rest of the list are @emph{not} initially evaluated. -Instead, these elements themselves are used as the arguments of the -macro. The macro definition computes a replacement form, called the -@dfn{expansion} of the macro, to be evaluated in place of the original -form. The expansion may be any sort of form: a self-evaluating -constant, a symbol, or a list. If the expansion is itself a macro call, -this process of expansion repeats until some other sort of form results. - - Ordinary evaluation of a macro call finishes by evaluating the -expansion. However, the macro expansion is not necessarily evaluated -right away, or at all, because other programs also expand macro calls, -and they may or may not evaluate the expansions. - - Normally, the argument expressions are not evaluated as part of -computing the macro expansion, but instead appear as part of the -expansion, so they are computed when the expansion is evaluated. - - For example, given a macro defined as follows: - -@example -@group -(defmacro cadr (x) - (list 'car (list 'cdr x))) -@end group -@end example - -@noindent -an expression such as @code{(cadr (assq 'handler list))} is a macro -call, and its expansion is: - -@example -(car (cdr (assq 'handler list))) -@end example - -@noindent -Note that the argument @code{(assq 'handler list)} appears in the -expansion. - -@xref{Macros}, for a complete description of Emacs Lisp macros. - -@node Special Forms -@subsection Special Forms -@cindex special form evaluation - - A @dfn{special form} is a primitive function specially marked so that -its arguments are not all evaluated. Most special forms define control -structures or perform variable bindings---things which functions cannot -do. - - Each special form has its own rules for which arguments are evaluated -and which are used without evaluation. Whether a particular argument is -evaluated may depend on the results of evaluating other arguments. - - Here is a list, in alphabetical order, of all of the special forms in -Emacs Lisp with a reference to where each is described. - -@table @code -@item and -@pxref{Combining Conditions} - -@item catch -@pxref{Catch and Throw} - -@item cond -@pxref{Conditionals} - -@item condition-case -@pxref{Handling Errors} - -@item defconst -@pxref{Defining Variables} - -@item defmacro -@pxref{Defining Macros} - -@item defun -@pxref{Defining Functions} - -@item defvar -@pxref{Defining Variables} - -@item function -@pxref{Anonymous Functions} - -@item if -@pxref{Conditionals} - -@item interactive -@pxref{Interactive Call} - -@item let -@itemx let* -@pxref{Local Variables} - -@item or -@pxref{Combining Conditions} - -@item prog1 -@itemx prog2 -@itemx progn -@pxref{Sequencing} - -@item quote -@pxref{Quoting} - -@item save-current-buffer -@pxref{Current Buffer} - -@item save-excursion -@pxref{Excursions} - -@item save-restriction -@pxref{Narrowing} - -@item save-window-excursion -@pxref{Window Configurations} - -@item setq -@pxref{Setting Variables} - -@item setq-default -@pxref{Creating Buffer-Local} - -@item track-mouse -@pxref{Mouse Tracking} - -@item unwind-protect -@pxref{Nonlocal Exits} - -@item while -@pxref{Iteration} - -@item with-output-to-temp-buffer -@pxref{Temporary Displays} -@end table - -@cindex CL note---special forms compared -@quotation -@b{Common Lisp note:} Here are some comparisons of special forms in -GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and -@code{catch} are special forms in both Emacs Lisp and Common Lisp. -@code{defun} is a special form in Emacs Lisp, but a macro in Common -Lisp. @code{save-excursion} is a special form in Emacs Lisp, but -doesn't exist in Common Lisp. @code{throw} is a special form in -Common Lisp (because it must be able to throw multiple values), but it -is a function in Emacs Lisp (which doesn't have multiple -values).@refill -@end quotation - -@node Autoloading -@subsection Autoloading - - The @dfn{autoload} feature allows you to call a function or macro -whose function definition has not yet been loaded into Emacs. It -specifies which file contains the definition. When an autoload object -appears as a symbol's function definition, calling that symbol as a -function automatically loads the specified file; then it calls the real -definition loaded from that file. @xref{Autoload}. - -@node Quoting -@section Quoting - - The special form @code{quote} returns its single argument, as written, -without evaluating it. This provides a way to include constant symbols -and lists, which are not self-evaluating objects, in a program. (It is -not necessary to quote self-evaluating objects such as numbers, strings, -and vectors.) - -@defspec quote object -This special form returns @var{object}, without evaluating it. -@end defspec - -@cindex @samp{'} for quoting -@cindex quoting using apostrophe -@cindex apostrophe for quoting -Because @code{quote} is used so often in programs, Lisp provides a -convenient read syntax for it. An apostrophe character (@samp{'}) -followed by a Lisp object (in read syntax) expands to a list whose first -element is @code{quote}, and whose second element is the object. Thus, -the read syntax @code{'x} is an abbreviation for @code{(quote x)}. - -Here are some examples of expressions that use @code{quote}: - -@example -@group -(quote (+ 1 2)) - @result{} (+ 1 2) -@end group -@group -(quote foo) - @result{} foo -@end group -@group -'foo - @result{} foo -@end group -@group -''foo - @result{} (quote foo) -@end group -@group -'(quote foo) - @result{} (quote foo) -@end group -@group -['foo] - @result{} [(quote foo)] -@end group -@end example - - Other quoting constructs include @code{function} (@pxref{Anonymous -Functions}), which causes an anonymous lambda expression written in Lisp -to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote -only part of a list, while computing and substituting other parts. - -@node Eval -@section Eval - - Most often, forms are evaluated automatically, by virtue of their -occurrence in a program being run. On rare occasions, you may need to -write code that evaluates a form that is computed at run time, such as -after reading a form from text being edited or getting one from a -property list. On these occasions, use the @code{eval} function. - - The functions and variables described in this section evaluate forms, -specify limits to the evaluation process, or record recently returned -values. Loading a file also does evaluation (@pxref{Loading}). - - It is generally cleaner and more flexible to store a function in a -data structure, and call it with @code{funcall} or @code{apply}, than -to store an expression in the data structure and evaluate it. Using -functions provides the ability to pass information to them as -arguments. - -@defun eval form -This is the basic function evaluating an expression. It evaluates -@var{form} in the current environment and returns the result. How the -evaluation proceeds depends on the type of the object (@pxref{Forms}). - -Since @code{eval} is a function, the argument expression that appears -in a call to @code{eval} is evaluated twice: once as preparation before -@code{eval} is called, and again by the @code{eval} function itself. -Here is an example: - -@example -@group -(setq foo 'bar) - @result{} bar -@end group -@group -(setq bar 'baz) - @result{} baz -;; @r{Here @code{eval} receives argument @code{foo}} -(eval 'foo) - @result{} bar -;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}} -(eval foo) - @result{} baz -@end group -@end example - -The number of currently active calls to @code{eval} is limited to -@code{max-lisp-eval-depth} (see below). -@end defun - -@deffn Command eval-region start end &optional stream read-function -@anchor{Definition of eval-region} -This function evaluates the forms in the current buffer in the region -defined by the positions @var{start} and @var{end}. It reads forms from -the region and calls @code{eval} on them until the end of the region is -reached, or until an error is signaled and not handled. - -By default, @code{eval-region} does not produce any output. However, -if @var{stream} is non-@code{nil}, any output produced by output -functions (@pxref{Output Functions}), as well as the values that -result from evaluating the expressions in the region are printed using -@var{stream}. @xref{Output Streams}. - -If @var{read-function} is non-@code{nil}, it should be a function, -which is used instead of @code{read} to read expressions one by one. -This function is called with one argument, the stream for reading -input. You can also use the variable @code{load-read-function} -(@pxref{Definition of load-read-function,, How Programs Do Loading}) -to specify this function, but it is more robust to use the -@var{read-function} argument. - -@code{eval-region} does not move point. It always returns @code{nil}. -@end deffn - -@cindex evaluation of buffer contents -@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print -This is similar to @code{eval-region}, but the arguments provide -different optional features. @code{eval-buffer} operates on the -entire accessible portion of buffer @var{buffer-or-name}. -@var{buffer-or-name} can be a buffer, a buffer name (a string), or -@code{nil} (or omitted), which means to use the current buffer. -@var{stream} is used as in @code{eval-region}, unless @var{stream} is -@code{nil} and @var{print} non-@code{nil}. In that case, values that -result from evaluating the expressions are still discarded, but the -output of the output functions is printed in the echo area. -@var{filename} is the file name to use for @code{load-history} -(@pxref{Unloading}), and defaults to @code{buffer-file-name} -(@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil}, -@code{read} converts strings to unibyte whenever possible. - -@findex eval-current-buffer -@code{eval-current-buffer} is an alias for this command. -@end deffn - -@defvar max-lisp-eval-depth -@anchor{Definition of max-lisp-eval-depth} -This variable defines the maximum depth allowed in calls to @code{eval}, -@code{apply}, and @code{funcall} before an error is signaled (with error -message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). - -This limit, with the associated error when it is exceeded, is one way -Emacs Lisp avoids infinite recursion on an ill-defined function. If -you increase the value of @code{max-lisp-eval-depth} too much, such -code can cause stack overflow instead. -@cindex Lisp nesting error - -The depth limit counts internal uses of @code{eval}, @code{apply}, and -@code{funcall}, such as for calling the functions mentioned in Lisp -expressions, and recursive evaluation of function call arguments and -function body forms, as well as explicit calls in Lisp code. - -The default value of this variable is 300. If you set it to a value -less than 100, Lisp will reset it to 100 if the given value is reached. -Entry to the Lisp debugger increases the value, if there is little room -left, to make sure the debugger itself has room to execute. - -@code{max-specpdl-size} provides another limit on nesting. -@xref{Definition of max-specpdl-size,, Local Variables}. -@end defvar - -@defvar values -The value of this variable is a list of the values returned by all the -expressions that were read, evaluated, and printed from buffers -(including the minibuffer) by the standard Emacs commands which do -this. (Note that this does @emph{not} include evaluation in -@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in -@code{lisp-interaction-mode}.) The elements are ordered most recent -first. - -@example -@group -(setq x 1) - @result{} 1 -@end group -@group -(list 'A (1+ 2) auto-save-default) - @result{} (A 3 t) -@end group -@group -values - @result{} ((A 3 t) 1 @dots{}) -@end group -@end example - -This variable is useful for referring back to values of forms recently -evaluated. It is generally a bad idea to print the value of -@code{values} itself, since this may be very long. Instead, examine -particular elements, like this: - -@example -@group -;; @r{Refer to the most recent evaluation result.} -(nth 0 values) - @result{} (A 3 t) -@end group -@group -;; @r{That put a new element on,} -;; @r{so all elements move back one.} -(nth 1 values) - @result{} (A 3 t) -@end group -@group -;; @r{This gets the element that was next-to-most-recent} -;; @r{before this example.} -(nth 3 values) - @result{} 1 -@end group -@end example -@end defvar - -@ignore - arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57 -@end ignore diff --git a/lispref/files.texi b/lispref/files.texi deleted file mode 100644 index bfcbe476f95..00000000000 --- a/lispref/files.texi +++ /dev/null @@ -1,3108 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/files -@node Files, Backups and Auto-Saving, Documentation, Top -@comment node-name, next, previous, up -@chapter Files - - In Emacs, you can find, create, view, save, and otherwise work with -files and file directories. This chapter describes most of the -file-related functions of Emacs Lisp, but a few others are described in -@ref{Buffers}, and those related to backups and auto-saving are -described in @ref{Backups and Auto-Saving}. - - Many of the file functions take one or more arguments that are file -names. A file name is actually a string. Most of these functions -expand file name arguments by calling @code{expand-file-name}, so that -@file{~} is handled correctly, as are relative file names (including -@samp{../}). These functions don't recognize environment variable -substitutions such as @samp{$HOME}. @xref{File Name Expansion}. - - When file I/O functions signal Lisp errors, they usually use the -condition @code{file-error} (@pxref{Handling Errors}). The error -message is in most cases obtained from the operating system, according -to locale @code{system-message-locale}, and decoded using coding system -@code{locale-coding-system} (@pxref{Locales}). - -@menu -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* 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. -@end menu - -@node Visiting Files -@section Visiting Files -@cindex finding files -@cindex visiting files - - Visiting a file means reading a file into a buffer. Once this is -done, we say that the buffer is @dfn{visiting} that file, and call the -file ``the visited file'' of the buffer. - - A file and a buffer are two different things. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of Emacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; then we -say the buffer is visiting that file. The copy in the buffer is what -you modify with editing commands. Such changes to the buffer do not -change the file; therefore, to make the changes permanent, you must -@dfn{save} the buffer, which means copying the altered buffer contents -back into the file. - - In spite of the distinction between files and buffers, people often -refer to a file when they mean a buffer and vice-versa. Indeed, we say, -``I am editing a file,'' rather than, ``I am editing a buffer that I -will soon save as a file of the same name.'' Humans do not usually need -to make the distinction explicit. When dealing with a computer program, -however, it is good to keep the distinction in mind. - -@menu -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. -@end menu - -@node Visiting Functions -@subsection Functions for Visiting Files - - This section describes the functions normally used to visit files. -For historical reasons, these functions have names starting with -@samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for -functions and variables that access the visited file name of a buffer or -that find an existing buffer by its visited file name. - - In a Lisp program, if you want to look at the contents of a file but -not alter it, the fastest way is to use @code{insert-file-contents} in a -temporary buffer. Visiting the file is not necessary and takes longer. -@xref{Reading from Files}. - -@deffn Command find-file filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, -using an existing buffer if there is one, and otherwise creating a -new buffer and reading the file into it. It also returns that buffer. - -Aside from some technical details, the body of the @code{find-file} -function is basically equivalent to: - -@smallexample -(switch-to-buffer (find-file-noselect filename nil nil wildcards)) -@end smallexample - -@noindent -(See @code{switch-to-buffer} in @ref{Displaying Buffers}.) - -If @var{wildcards} is non-@code{nil}, which is always true in an -interactive call, then @code{find-file} expands wildcard characters in -@var{filename} and visits all the matching files. - -When @code{find-file} is called interactively, it prompts for -@var{filename} in the minibuffer. -@end deffn - -@defun find-file-noselect filename &optional nowarn rawfile wildcards -This function is the guts of all the file-visiting functions. It -returns a buffer visiting the file @var{filename}. You may make the -buffer current or display it in a window if you wish, but this -function does not do so. - -The function returns an existing buffer if there is one; otherwise it -creates a new buffer and reads the file into it. When -@code{find-file-noselect} uses an existing buffer, it first verifies -that the file has not changed since it was last visited or saved in -that buffer. If the file has changed, this function asks the user -whether to reread the changed file. If the user says @samp{yes}, any -edits previously made in the buffer are lost. - -Reading the file involves decoding the file's contents (@pxref{Coding -Systems}), including end-of-line conversion, and format conversion -(@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil}, -then @code{find-file-noselect} expands wildcard characters in -@var{filename} and visits all the matching files. - -This function displays warning or advisory messages in various peculiar -cases, unless the optional argument @var{nowarn} is non-@code{nil}. For -example, if it needs to create a buffer, and there is no file named -@var{filename}, it displays the message @samp{(New file)} in the echo -area, and leaves the buffer empty. - -The @code{find-file-noselect} function normally calls -@code{after-find-file} after reading the file (@pxref{Subroutines of -Visiting}). That function sets the buffer major mode, parses local -variables, warns the user if there exists an auto-save file more recent -than the file just visited, and finishes by running the functions in -@code{find-file-hook}. - -If the optional argument @var{rawfile} is non-@code{nil}, then -@code{after-find-file} is not called, and the -@code{find-file-not-found-functions} are not run in case of failure. -What's more, a non-@code{nil} @var{rawfile} value suppresses coding -system conversion and format conversion. - -The @code{find-file-noselect} function usually returns the buffer that -is visiting the file @var{filename}. But, if wildcards are actually -used and expanded, it returns a list of buffers that are visiting the -various files. - -@example -@group -(find-file-noselect "/etc/fstab") - @result{} #<buffer fstab> -@end group -@end example -@end defun - -@deffn Command find-file-other-window filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, but -does so in a window other than the selected window. It may use another -existing window or split a window; see @ref{Displaying Buffers}. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@deffn Command find-file-read-only filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, like -@code{find-file}, but it marks the buffer as read-only. @xref{Read Only -Buffers}, for related functions and variables. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@deffn Command view-file filename -This command visits @var{filename} using View mode, returning to the -previous buffer when you exit View mode. View mode is a minor mode that -provides commands to skim rapidly through the file, but does not let you -modify the text. Entering View mode runs the normal hook -@code{view-mode-hook}. @xref{Hooks}. - -When @code{view-file} is called interactively, it prompts for -@var{filename}. -@end deffn - -@defopt find-file-wildcards -If this variable is non-@code{nil}, then the various @code{find-file} -commands check for wildcard characters and visit all the files that -match them (when invoked interactively or when their @var{wildcards} -argument is non-@code{nil}). If this option is @code{nil}, then -the @code{find-file} commands ignore their @var{wildcards} argument -and never treat wildcard characters specially. -@end defopt - -@defvar find-file-hook -The value of this variable is a list of functions to be called after a -file is visited. The file's local-variables specification (if any) will -have been processed before the hooks are run. The buffer visiting the -file is current when the hook functions are run. - -This variable is a normal hook. @xref{Hooks}. -@end defvar - -@defvar find-file-not-found-functions -The value of this variable is a list of functions to be called when -@code{find-file} or @code{find-file-noselect} is passed a nonexistent -file name. @code{find-file-noselect} calls these functions as soon as -it detects a nonexistent file. It calls them in the order of the list, -until one of them returns non-@code{nil}. @code{buffer-file-name} is -already set up. - -This is not a normal hook because the values of the functions are -used, and in many cases only some of the functions are called. -@end defvar - -@node Subroutines of Visiting -@comment node-name, next, previous, up -@subsection Subroutines of Visiting - - The @code{find-file-noselect} function uses two important subroutines -which are sometimes useful in user Lisp code: @code{create-file-buffer} -and @code{after-find-file}. This section explains how to use them. - -@defun create-file-buffer filename -This function creates a suitably named buffer for visiting -@var{filename}, and returns it. It uses @var{filename} (sans directory) -as the name if that name is free; otherwise, it appends a string such as -@samp{<2>} to get an unused name. See also @ref{Creating Buffers}. - -@strong{Please note:} @code{create-file-buffer} does @emph{not} -associate the new buffer with a file and does not select the buffer. -It also does not use the default major mode. - -@example -@group -(create-file-buffer "foo") - @result{} #<buffer foo> -@end group -@group -(create-file-buffer "foo") - @result{} #<buffer foo<2>> -@end group -@group -(create-file-buffer "foo") - @result{} #<buffer foo<3>> -@end group -@end example - -This function is used by @code{find-file-noselect}. -It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). -@end defun - -@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes -This function sets the buffer major mode, and parses local variables -(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} -and by the default revert function (@pxref{Reverting}). - -@cindex new file message -@cindex file open error -If reading the file got an error because the file does not exist, but -its directory does exist, the caller should pass a non-@code{nil} value -for @var{error}. In that case, @code{after-find-file} issues a warning: -@samp{(New file)}. For more serious errors, the caller should usually not -call @code{after-find-file}. - -If @var{warn} is non-@code{nil}, then this function issues a warning -if an auto-save file exists and is more recent than the visited file. - -If @var{noauto} is non-@code{nil}, that says not to enable or disable -Auto-Save mode. The mode remains enabled if it was enabled before. - -If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that -means this call was from @code{revert-buffer}. This has no direct -effect, but some mode functions and hook functions check the value -of this variable. - -If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's -major mode, don't process local variables specifications in the file, -and don't run @code{find-file-hook}. This feature is used by -@code{revert-buffer} in some cases. - -The last thing @code{after-find-file} does is call all the functions -in the list @code{find-file-hook}. -@end defun - -@node Saving Buffers -@section Saving Buffers -@cindex saving buffers - - When you edit a file in Emacs, you are actually working on a buffer -that is visiting that file---that is, the contents of the file are -copied into the buffer and the copy is what you edit. Changes to the -buffer do not change the file until you @dfn{save} the buffer, which -means copying the contents of the buffer into the file. - -@deffn Command save-buffer &optional backup-option -This function saves the contents of the current buffer in its visited -file if the buffer has been modified since it was last visited or saved. -Otherwise it does nothing. - -@code{save-buffer} is responsible for making backup files. Normally, -@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup -file only if this is the first save since visiting the file. Other -values for @var{backup-option} request the making of backup files in -other circumstances: - -@itemize @bullet -@item -With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the -@code{save-buffer} function marks this version of the file to be -backed up when the buffer is next saved. - -@item -With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the -@code{save-buffer} function unconditionally backs up the previous -version of the file before saving it. - -@item -With an argument of 0, unconditionally do @emph{not} make any backup file. -@end itemize -@end deffn - -@deffn Command save-some-buffers &optional save-silently-p pred -@anchor{Definition of save-some-buffers} -This command saves some modified file-visiting buffers. Normally it -asks the user about each buffer. But if @var{save-silently-p} is -non-@code{nil}, it saves all the file-visiting buffers without querying -the user. - -The optional @var{pred} argument controls which buffers to ask about -(or to save silently if @var{save-silently-p} is non-@code{nil}). -If it is @code{nil}, that means to ask only about file-visiting buffers. -If it is @code{t}, that means also offer to save certain other non-file -buffers---those that have a non-@code{nil} buffer-local value of -@code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says -@samp{yes} to saving a non-file buffer is asked to specify the file -name to use. The @code{save-buffers-kill-emacs} function passes the -value @code{t} for @var{pred}. - -If @var{pred} is neither @code{t} nor @code{nil}, then it should be -a function of no arguments. It will be called in each buffer to decide -whether to offer to save that buffer. If it returns a non-@code{nil} -value in a certain buffer, that means do offer to save that buffer. -@end deffn - -@deffn Command write-file filename &optional confirm -@anchor{Definition of write-file} -This function writes the current buffer into file @var{filename}, makes -the buffer visit that file, and marks it not modified. Then it renames -the buffer based on @var{filename}, appending a string like @samp{<2>} -if necessary to make a unique buffer name. It does most of this work by -calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and -@code{save-buffer}. - -If @var{confirm} is non-@code{nil}, that means to ask for confirmation -before overwriting an existing file. Interactively, confirmation is -required, unless the user supplies a prefix argument. - -If @var{filename} is an existing directory, or a symbolic link to one, -@code{write-file} uses the name of the visited file, in directory -@var{filename}. If the buffer is not visiting a file, it uses the -buffer name instead. -@end deffn - - Saving a buffer runs several hooks. It also performs format -conversion (@pxref{Format Conversion}). - -@defvar write-file-functions -The value of this variable is a list of functions to be called before -writing out a buffer to its visited file. If one of them returns -non-@code{nil}, the file is considered already written and the rest of -the functions are not called, nor is the usual code for writing the file -executed. - -If a function in @code{write-file-functions} returns non-@code{nil}, it -is responsible for making a backup file (if that is appropriate). -To do so, execute the following code: - -@example -(or buffer-backed-up (backup-buffer)) -@end example - -You might wish to save the file modes value returned by -@code{backup-buffer} and use that (if non-@code{nil}) to set the mode -bits of the file that you write. This is what @code{save-buffer} -normally does. @xref{Making Backups,, Making Backup Files}. - -The hook functions in @code{write-file-functions} are also responsible -for encoding the data (if desired): they must choose a suitable coding -system and end-of-line conversion (@pxref{Lisp and Coding Systems}), -perform the encoding (@pxref{Explicit Encoding}), and set -@code{last-coding-system-used} to the coding system that was used -(@pxref{Encoding and I/O}). - -If you set this hook locally in a buffer, it is assumed to be -associated with the file or the way the contents of the buffer were -obtained. Thus the variable is marked as a permanent local, so that -changing the major mode does not alter a buffer-local value. On the -other hand, calling @code{set-visited-file-name} will reset it. -If this is not what you want, you might like to use -@code{write-contents-functions} instead. - -Even though this is not a normal hook, you can use @code{add-hook} and -@code{remove-hook} to manipulate the list. @xref{Hooks}. -@end defvar - -@c Emacs 19 feature -@defvar write-contents-functions -This works just like @code{write-file-functions}, but it is intended -for hooks that pertain to the buffer's contents, not to the particular -visited file or its location. Such hooks are usually set up by major -modes, as buffer-local bindings for this variable. This variable -automatically becomes buffer-local whenever it is set; switching to a -new major mode always resets this variable, but calling -@code{set-visited-file-name} does not. - -If any of the functions in this hook returns non-@code{nil}, the file -is considered already written and the rest are not called and neither -are the functions in @code{write-file-functions}. -@end defvar - -@defopt before-save-hook -This normal hook runs before a buffer is saved in its visited file, -regardless of whether that is done normally or by one of the hooks -described above. For instance, the @file{copyright.el} program uses -this hook to make sure the file you are saving has the current year in -its copyright notice. -@end defopt - -@c Emacs 19 feature -@defopt after-save-hook -This normal hook runs after a buffer has been saved in its visited file. -One use of this hook is in Fast Lock mode; it uses this hook to save the -highlighting information in a cache file. -@end defopt - -@defopt file-precious-flag -If this variable is non-@code{nil}, then @code{save-buffer} protects -against I/O errors while saving by writing the new file to a temporary -name instead of the name it is supposed to have, and then renaming it to -the intended name after it is clear there are no errors. This procedure -prevents problems such as a lack of disk space from resulting in an -invalid file. - -As a side effect, backups are necessarily made by copying. @xref{Rename -or Copy}. Yet, at the same time, saving a precious file always breaks -all hard links between the file you save and other file names. - -Some modes give this variable a non-@code{nil} buffer-local value -in particular buffers. -@end defopt - -@defopt require-final-newline -This variable determines whether files may be written out that do -@emph{not} end with a newline. If the value of the variable is -@code{t}, then @code{save-buffer} silently adds a newline at the end of -the file whenever the buffer being saved does not already end in one. -If the value of the variable is non-@code{nil}, but not @code{t}, then -@code{save-buffer} asks the user whether to add a newline each time the -case arises. - -If the value of the variable is @code{nil}, then @code{save-buffer} -doesn't add newlines at all. @code{nil} is the default value, but a few -major modes set it to @code{t} in particular buffers. -@end defopt - - See also the function @code{set-visited-file-name} (@pxref{Buffer File -Name}). - -@node Reading from Files -@comment node-name, next, previous, up -@section Reading from Files -@cindex reading from files - - You can copy a file from the disk and insert it into a buffer -using the @code{insert-file-contents} function. Don't use the user-level -command @code{insert-file} in a Lisp program, as that sets the mark. - -@defun insert-file-contents filename &optional visit beg end replace -This function inserts the contents of file @var{filename} into the -current buffer after point. It returns a list of the absolute file name -and the length of the data inserted. An error is signaled if -@var{filename} is not the name of a file that can be read. - -The function @code{insert-file-contents} checks the file contents -against the defined file formats, and converts the file contents if -appropriate and also calls the functions in -the list @code{after-insert-file-functions}. @xref{Format Conversion}. -Normally, one of the functions in the -@code{after-insert-file-functions} list determines the coding system -(@pxref{Coding Systems}) used for decoding the file's contents, -including end-of-line conversion. - -If @var{visit} is non-@code{nil}, this function additionally marks the -buffer as unmodified and sets up various fields in the buffer so that it -is visiting the file @var{filename}: these include the buffer's visited -file name and its last save file modtime. This feature is used by -@code{find-file-noselect} and you probably should not use it yourself. - -If @var{beg} and @var{end} are non-@code{nil}, they should be integers -specifying the portion of the file to insert. In this case, @var{visit} -must be @code{nil}. For example, - -@example -(insert-file-contents filename nil 0 500) -@end example - -@noindent -inserts the first 500 characters of a file. - -If the argument @var{replace} is non-@code{nil}, it means to replace the -contents of the buffer (actually, just the accessible portion) with the -contents of the file. This is better than simply deleting the buffer -contents and inserting the whole file, because (1) it preserves some -marker positions and (2) it puts less data in the undo list. - -It is possible to read a special file (such as a FIFO or an I/O device) -with @code{insert-file-contents}, as long as @var{replace} and -@var{visit} are @code{nil}. -@end defun - -@defun insert-file-contents-literally filename &optional visit beg end replace -This function works like @code{insert-file-contents} except that it does -not do format decoding (@pxref{Format Conversion}), does not do -character code conversion (@pxref{Coding Systems}), does not run -@code{find-file-hook}, does not perform automatic uncompression, and so -on. -@end defun - -If you want to pass a file name to another process so that another -program can read the file, use the function @code{file-local-copy}; see -@ref{Magic File Names}. - -@node Writing to Files -@comment node-name, next, previous, up -@section Writing to Files -@cindex writing to files - - You can write the contents of a buffer, or part of a buffer, directly -to a file on disk using the @code{append-to-file} and -@code{write-region} functions. Don't use these functions to write to -files that are being visited; that could cause confusion in the -mechanisms for visiting. - -@deffn Command append-to-file start end filename -This function appends the contents of the region delimited by -@var{start} and @var{end} in the current buffer to the end of file -@var{filename}. If that file does not exist, it is created. This -function returns @code{nil}. - -An error is signaled if @var{filename} specifies a nonwritable file, -or a nonexistent file in a directory where files cannot be created. - -When called from Lisp, this function is completely equivalent to: - -@example -(write-region start end filename t) -@end example -@end deffn - -@deffn Command write-region start end filename &optional append visit lockname mustbenew -This function writes the region delimited by @var{start} and @var{end} -in the current buffer into the file specified by @var{filename}. - -If @var{start} is @code{nil}, then the command writes the entire buffer -contents (@emph{not} just the accessible portion) to the file and -ignores @var{end}. - -@c Emacs 19 feature -If @var{start} is a string, then @code{write-region} writes or appends -that string, rather than text from the buffer. @var{end} is ignored in -this case. - -If @var{append} is non-@code{nil}, then the specified text is appended -to the existing file contents (if any). If @var{append} is an -integer, @code{write-region} seeks to that byte offset from the start -of the file and writes the data from there. - -If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks -for confirmation if @var{filename} names an existing file. If -@var{mustbenew} is the symbol @code{excl}, then @code{write-region} -does not ask for confirmation, but instead it signals an error -@code{file-already-exists} if the file already exists. - -The test for an existing file, when @var{mustbenew} is @code{excl}, uses -a special system feature. At least for files on a local disk, there is -no chance that some other program could create a file of the same name -before Emacs does, without Emacs's noticing. - -If @var{visit} is @code{t}, then Emacs establishes an association -between the buffer and the file: the buffer is then visiting that file. -It also sets the last file modification time for the current buffer to -@var{filename}'s modtime, and marks the buffer as not modified. This -feature is used by @code{save-buffer}, but you probably should not use -it yourself. - -@c Emacs 19 feature -If @var{visit} is a string, it specifies the file name to visit. This -way, you can write the data to one file (@var{filename}) while recording -the buffer as visiting another file (@var{visit}). The argument -@var{visit} is used in the echo area message and also for file locking; -@var{visit} is stored in @code{buffer-file-name}. This feature is used -to implement @code{file-precious-flag}; don't use it yourself unless you -really know what you're doing. - -The optional argument @var{lockname}, if non-@code{nil}, specifies the -file name to use for purposes of locking and unlocking, overriding -@var{filename} and @var{visit} for that purpose. - -The function @code{write-region} converts the data which it writes to -the appropriate file formats specified by @code{buffer-file-format} -and also calls the functions in the list -@code{write-region-annotate-functions}. -@xref{Format Conversion}. - -Normally, @code{write-region} displays the message @samp{Wrote -@var{filename}} in the echo area. If @var{visit} is neither @code{t} -nor @code{nil} nor a string, then this message is inhibited. This -feature is useful for programs that use files for internal purposes, -files that the user does not need to know about. -@end deffn - -@defmac with-temp-file file body@dots{} -@anchor{Definition of with-temp-file} -The @code{with-temp-file} macro evaluates the @var{body} forms with a -temporary buffer as the current buffer; then, at the end, it writes the -buffer contents into file @var{file}. It kills the temporary buffer -when finished, restoring the buffer that was current before the -@code{with-temp-file} form. Then it returns the value of the last form -in @var{body}. - -The current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -See also @code{with-temp-buffer} in @ref{Definition of -with-temp-buffer,, The Current Buffer}. -@end defmac - -@node File Locks -@section File Locks -@cindex file locks -@cindex lock file - - When two users edit the same file at the same time, they are likely -to interfere with each other. Emacs tries to prevent this situation -from arising by recording a @dfn{file lock} when a file is being -modified. (File locks are not implemented on Microsoft systems.) -Emacs can then detect the first attempt to modify a buffer visiting a -file that is locked by another Emacs job, and ask the user what to do. -The file lock is really a file, a symbolic link with a special name, -stored in the same directory as the file you are editing. - - When you access files using NFS, there may be a small probability that -you and another user will both lock the same file ``simultaneously.'' -If this happens, it is possible for the two users to make changes -simultaneously, but Emacs will still warn the user who saves second. -Also, the detection of modification of a buffer visiting a file changed -on disk catches some cases of simultaneous editing; see -@ref{Modification Time}. - -@defun file-locked-p filename -This function returns @code{nil} if the file @var{filename} is not -locked. It returns @code{t} if it is locked by this Emacs process, and -it returns the name of the user who has locked it if it is locked by -some other job. - -@example -@group -(file-locked-p "foo") - @result{} nil -@end group -@end example -@end defun - -@defun lock-buffer &optional filename -This function locks the file @var{filename}, if the current buffer is -modified. The argument @var{filename} defaults to the current buffer's -visited file. Nothing is done if the current buffer is not visiting a -file, or is not modified, or if the system does not support locking. -@end defun - -@defun unlock-buffer -This function unlocks the file being visited in the current buffer, -if the buffer is modified. If the buffer is not modified, then -the file should not be locked, so this function does nothing. It also -does nothing if the current buffer is not visiting a file, or if the -system does not support locking. -@end defun - - File locking is not supported on some systems. On systems that do not -support it, the functions @code{lock-buffer}, @code{unlock-buffer} and -@code{file-locked-p} do nothing and return @code{nil}. - -@defun ask-user-about-lock file other-user -This function is called when the user tries to modify @var{file}, but it -is locked by another user named @var{other-user}. The default -definition of this function asks the user to say what to do. The value -this function returns determines what Emacs does next: - -@itemize @bullet -@item -A value of @code{t} says to grab the lock on the file. Then -this user may edit the file and @var{other-user} loses the lock. - -@item -A value of @code{nil} says to ignore the lock and let this -user edit the file anyway. - -@item -@kindex file-locked -This function may instead signal a @code{file-locked} error, in which -case the change that the user was about to make does not take place. - -The error message for this error looks like this: - -@example -@error{} File is locked: @var{file} @var{other-user} -@end example - -@noindent -where @code{file} is the name of the file and @var{other-user} is the -name of the user who has locked the file. -@end itemize - -If you wish, you can replace the @code{ask-user-about-lock} function -with your own version that makes the decision in another way. The code -for its usual definition is in @file{userlock.el}. -@end defun - -@node Information about Files -@section Information about Files -@cindex file, information about - - The functions described in this section all operate on strings that -designate file names. With a few exceptions, all the functions have -names that begin with the word @samp{file}. These functions all -return information about actual files or directories, so their -arguments must all exist as actual files or directories unless -otherwise noted. - -@menu -* 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. -* Locating Files:: How to find a file in standard places. -@end menu - -@node Testing Accessibility -@comment node-name, next, previous, up -@subsection Testing Accessibility -@cindex accessibility of a file -@cindex file accessibility - - These functions test for permission to access a file in specific -ways. Unless explicitly stated otherwise, they recursively follow -symbolic links for their file name arguments, at all levels (at the -level of the file itself and at all levels of parent directories). - -@defun file-exists-p filename -This function returns @code{t} if a file named @var{filename} appears -to exist. This does not mean you can necessarily read the file, only -that you can find out its attributes. (On Unix and GNU/Linux, this is -true if the file exists and you have execute permission on the -containing directories, regardless of the protection of the file -itself.) - -If the file does not exist, or if fascist access control policies -prevent you from finding the attributes of the file, this function -returns @code{nil}. - -Directories are files, so @code{file-exists-p} returns @code{t} when -given a directory name. However, symbolic links are treated -specially; @code{file-exists-p} returns @code{t} for a symbolic link -name only if the target file exists. -@end defun - -@defun file-readable-p filename -This function returns @code{t} if a file named @var{filename} exists -and you can read it. It returns @code{nil} otherwise. - -@example -@group -(file-readable-p "files.texi") - @result{} t -@end group -@group -(file-exists-p "/usr/spool/mqueue") - @result{} t -@end group -@group -(file-readable-p "/usr/spool/mqueue") - @result{} nil -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun file-executable-p filename -This function returns @code{t} if a file named @var{filename} exists and -you can execute it. It returns @code{nil} otherwise. On Unix and -GNU/Linux, if the file is a directory, execute permission means you can -check the existence and attributes of files inside the directory, and -open those files if their modes permit. -@end defun - -@defun file-writable-p filename -This function returns @code{t} if the file @var{filename} can be written -or created by you, and @code{nil} otherwise. A file is writable if the -file exists and you can write it. It is creatable if it does not exist, -but the specified directory does exist and you can write in that -directory. - -In the third example below, @file{foo} is not writable because the -parent directory does not exist, even though the user could create such -a directory. - -@example -@group -(file-writable-p "~/foo") - @result{} t -@end group -@group -(file-writable-p "/foo") - @result{} nil -@end group -@group -(file-writable-p "~/no-such-dir/foo") - @result{} nil -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun file-accessible-directory-p dirname -This function returns @code{t} if you have permission to open existing -files in the directory whose name as a file is @var{dirname}; -otherwise (or if there is no such directory), it returns @code{nil}. -The value of @var{dirname} may be either a directory name (such as -@file{/foo/}) or the file name of a file which is a directory -(such as @file{/foo}, without the final slash). - -Example: after the following, - -@example -(file-accessible-directory-p "/foo") - @result{} nil -@end example - -@noindent -we can deduce that any attempt to read a file in @file{/foo/} will -give an error. -@end defun - -@defun access-file filename string -This function opens file @var{filename} for reading, then closes it and -returns @code{nil}. However, if the open fails, it signals an error -using @var{string} as the error message text. -@end defun - -@defun file-ownership-preserved-p filename -This function returns @code{t} if deleting the file @var{filename} and -then creating it anew would keep the file's owner unchanged. It also -returns @code{t} for nonexistent files. - -If @var{filename} is a symbolic link, then, unlike the other functions -discussed here, @code{file-ownership-preserved-p} does @emph{not} -replace @var{filename} with its target. However, it does recursively -follow symbolic links at all levels of parent directories. -@end defun - -@defun file-newer-than-file-p filename1 filename2 -@cindex file age -@cindex file modification time -This function returns @code{t} if the file @var{filename1} is -newer than file @var{filename2}. If @var{filename1} does not -exist, it returns @code{nil}. If @var{filename1} does exist, but -@var{filename2} does not, it returns @code{t}. - -In the following example, assume that the file @file{aug-19} was written -on the 19th, @file{aug-20} was written on the 20th, and the file -@file{no-file} doesn't exist at all. - -@example -@group -(file-newer-than-file-p "aug-19" "aug-20") - @result{} nil -@end group -@group -(file-newer-than-file-p "aug-20" "aug-19") - @result{} t -@end group -@group -(file-newer-than-file-p "aug-19" "no-file") - @result{} t -@end group -@group -(file-newer-than-file-p "no-file" "aug-19") - @result{} nil -@end group -@end example - -You can use @code{file-attributes} to get a file's last modification -time as a list of two numbers. @xref{File Attributes}. -@end defun - -@node Kinds of Files -@comment node-name, next, previous, up -@subsection Distinguishing Kinds of Files - - This section describes how to distinguish various kinds of files, such -as directories, symbolic links, and ordinary files. - -@defun file-symlink-p filename -@cindex file symbolic links -If the file @var{filename} is a symbolic link, the -@code{file-symlink-p} function returns the (non-recursive) link target -as a string. (Determining the file name that the link points to from -the target is nontrivial.) First, this function recursively follows -symbolic links at all levels of parent directories. - -If the file @var{filename} is not a symbolic link (or there is no such file), -@code{file-symlink-p} returns @code{nil}. - -@example -@group -(file-symlink-p "foo") - @result{} nil -@end group -@group -(file-symlink-p "sym-link") - @result{} "foo" -@end group -@group -(file-symlink-p "sym-link2") - @result{} "sym-link" -@end group -@group -(file-symlink-p "/bin") - @result{} "/pub/bin" -@end group -@end example - -@c !!! file-symlink-p: should show output of ls -l for comparison -@end defun - -The next two functions recursively follow symbolic links at -all levels for @var{filename}. - -@defun file-directory-p filename -This function returns @code{t} if @var{filename} is the name of an -existing directory, @code{nil} otherwise. - -@example -@group -(file-directory-p "~rms") - @result{} t -@end group -@group -(file-directory-p "~rms/lewis/files.texi") - @result{} nil -@end group -@group -(file-directory-p "~rms/lewis/no-such-file") - @result{} nil -@end group -@group -(file-directory-p "$HOME") - @result{} nil -@end group -@group -(file-directory-p - (substitute-in-file-name "$HOME")) - @result{} t -@end group -@end example -@end defun - -@defun file-regular-p filename -This function returns @code{t} if the file @var{filename} exists and is -a regular file (not a directory, named pipe, terminal, or -other I/O device). -@end defun - -@node Truenames -@subsection Truenames -@cindex truename (of file) - -@c Emacs 19 features - The @dfn{truename} of a file is the name that you get by following -symbolic links at all levels until none remain, then simplifying away -@samp{.}@: and @samp{..}@: appearing as name components. This results -in a sort of canonical name for the file. A file does not always have a -unique truename; the number of distinct truenames a file has is equal to -the number of hard links to the file. However, truenames are useful -because they eliminate symbolic links as a cause of name variation. - -@defun file-truename filename -The function @code{file-truename} returns the truename of the file -@var{filename}. The argument must be an absolute file name. - -This function does not expand environment variables. Only -@code{substitute-in-file-name} does that. @xref{Definition of -substitute-in-file-name}. - -If you may need to follow symbolic links preceding @samp{..}@: -appearing as a name component, you should make sure to call -@code{file-truename} without prior direct or indirect calls to -@code{expand-file-name}, as otherwise the file name component -immediately preceding @samp{..} will be ``simplified away'' before -@code{file-truename} is called. To eliminate the need for a call to -@code{expand-file-name}, @code{file-truename} handles @samp{~} in the -same way that @code{expand-file-name} does. @xref{File Name -Expansion,, Functions that Expand Filenames}. -@end defun - -@defun file-chase-links filename &optional limit -This function follows symbolic links, starting with @var{filename}, -until it finds a file name which is not the name of a symbolic link. -Then it returns that file name. This function does @emph{not} follow -symbolic links at the level of parent directories. - -If you specify a number for @var{limit}, then after chasing through -that many links, the function just returns what it has even if that is -still a symbolic link. -@end defun - - To illustrate the difference between @code{file-chase-links} and -@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to -the directory @file{/home/foo}, and @file{/home/foo/hello} is an -ordinary file (or at least, not a symbolic link) or nonexistent. Then -we would have: - -@example -(file-chase-links "/usr/foo/hello") - ;; @r{This does not follow the links in the parent directories.} - @result{} "/usr/foo/hello" -(file-truename "/usr/foo/hello") - ;; @r{Assuming that @file{/home} is not a symbolic link.} - @result{} "/home/foo/hello" -@end example - - @xref{Buffer File Name}, for related information. - -@node File Attributes -@comment node-name, next, previous, up -@subsection Other Information about Files - - This section describes the functions for getting detailed information -about a file, other than its contents. This information includes the -mode bits that control access permission, the owner and group numbers, -the number of names, the inode number, the size, and the times of access -and modification. - -@defun file-modes filename -@cindex permission -@cindex file attributes -This function returns the mode bits of @var{filename}, as an integer. -The mode bits are also called the file permissions, and they specify -access control in the usual Unix fashion. If the low-order bit is 1, -then the file is executable by all users, if the second-lowest-order bit -is 1, then the file is writable by all users, etc. - -The highest value returnable is 4095 (7777 octal), meaning that -everyone has read, write, and execute permission, that the @acronym{SUID} bit -is set for both others and group, and that the sticky bit is set. - -If @var{filename} does not exist, @code{file-modes} returns @code{nil}. - -This function recursively follows symbolic links at all levels. - -@example -@group -(file-modes "~/junk/diffs") - @result{} 492 ; @r{Decimal integer.} -@end group -@group -(format "%o" 492) - @result{} "754" ; @r{Convert to octal.} -@end group - -@group -(set-file-modes "~/junk/diffs" 438) - @result{} nil -@end group - -@group -(format "%o" 438) - @result{} "666" ; @r{Convert to octal.} -@end group - -@group -% ls -l diffs - -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs -@end group -@end example -@end defun - -If the @var{filename} argument to the next two functions is a symbolic -link, then these function do @emph{not} replace it with its target. -However, they both recursively follow symbolic links at all levels of -parent directories. - -@defun file-nlinks filename -This functions returns the number of names (i.e., hard links) that -file @var{filename} has. If the file does not exist, then this function -returns @code{nil}. Note that symbolic links have no effect on this -function, because they are not considered to be names of the files they -link to. - -@example -@group -% ls -l foo* --rw-rw-rw- 2 rms 4 Aug 19 01:27 foo --rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 -@end group - -@group -(file-nlinks "foo") - @result{} 2 -@end group -@group -(file-nlinks "doesnt-exist") - @result{} nil -@end group -@end example -@end defun - -@defun file-attributes filename &optional id-format -@anchor{Definition of file-attributes} -This function returns a list of attributes of file @var{filename}. If -the specified file cannot be opened, it returns @code{nil}. -The optional parameter @var{id-format} specifies the preferred format -of attributes @acronym{UID} and @acronym{GID} (see below)---the -valid values are @code{'string} and @code{'integer}. The latter is -the default, but we plan to change that, so you should specify a -non-@code{nil} value for @var{id-format} if you use the returned -@acronym{UID} or @acronym{GID}. - -The elements of the list, in order, are: - -@enumerate 0 -@item -@code{t} for a directory, a string for a symbolic link (the name -linked to), or @code{nil} for a text file. - -@c Wordy so as to prevent an overfull hbox. --rjc 15mar92 -@item -The number of names the file has. Alternate names, also known as hard -links, can be created by using the @code{add-name-to-file} function -(@pxref{Changing Files}). - -@item -The file's @acronym{UID}, normally as a string. However, if it does -not correspond to a named user, the value is an integer or a floating -point number. - -@item -The file's @acronym{GID}, likewise. - -@item -The time of last access, as a list of two integers. -The first integer has the high-order 16 bits of time, -the second has the low 16 bits. (This is similar to the -value of @code{current-time}; see @ref{Time of Day}.) - -@item -The time of last modification as a list of two integers (as above). -@cindex modification time of file - -@item -The time of last status change as a list of two integers (as above). - -@item -The size of the file in bytes. If the size is too large to fit in a -Lisp integer, this is a floating point number. - -@item -The file's modes, as a string of ten letters or dashes, -as in @samp{ls -l}. - -@item -@code{t} if the file's @acronym{GID} would change if file were -deleted and recreated; @code{nil} otherwise. - -@item -The file's inode number. If possible, this is an integer. If the inode -number is too large to be represented as an integer in Emacs Lisp, then -the value has the form @code{(@var{high} . @var{low})}, where @var{low} -holds the low 16 bits. - -@item -The file system number of the file system that the file is in. -Depending on the magnitude of the value, this can be either an integer -or a cons cell, in the same manner as the inode number. This element -and the file's inode number together give enough information to -distinguish any two files on the system---no two files can have the same -values for both of these numbers. -@end enumerate - -For example, here are the file attributes for @file{files.texi}: - -@example -@group -(file-attributes "files.texi" 'string) - @result{} (nil 1 "lh" "users" - (8489 20284) - (8489 20284) - (8489 20285) - 14906 "-rw-rw-rw-" - nil 129500 -32252) -@end group -@end example - -@noindent -and here is how the result is interpreted: - -@table @code -@item nil -is neither a directory nor a symbolic link. - -@item 1 -has only one name (the name @file{files.texi} in the current default -directory). - -@item "lh" -is owned by the user with name "lh". - -@item "users" -is in the group with name "users". - -@item (8489 20284) -was last accessed on Aug 19 00:09. - -@item (8489 20284) -was last modified on Aug 19 00:09. - -@item (8489 20285) -last had its inode changed on Aug 19 00:09. - -@item 14906 -is 14906 bytes long. (It may not contain 14906 characters, though, -if some of the bytes belong to multibyte sequences.) - -@item "-rw-rw-rw-" -has a mode of read and write access for the owner, group, and world. - -@item nil -would retain the same @acronym{GID} if it were recreated. - -@item 129500 -has an inode number of 129500. -@item -32252 -is on file system number -32252. -@end table -@end defun - -@node Locating Files -@subsection How to Locate Files in Standard Places -@cindex locate file in path -@cindex find file in path - - This section explains how to search for a file in a list of -directories (a @dfn{path}). One example is when you need to look for -a program's executable file, e.g., to find out whether a given program -is installed on the user's system. Another example is the search for -Lisp libraries (@pxref{Library Search}). Such searches generally need -to try various possible file name extensions, in addition to various -possible directories. Emacs provides a function for such a -generalized search for a file. - -@defun locate-file filename path &optional suffixes predicate -This function searches for a file whose name is @var{filename} in a -list of directories given by @var{path}, trying the suffixes in -@var{suffixes}. If it finds such a file, it returns the full -@dfn{absolute file name} of the file (@pxref{Relative File Names}); -otherwise it returns @code{nil}. - -The optional argument @var{suffixes} gives the list of file-name -suffixes to append to @var{filename} when searching. -@code{locate-file} tries each possible directory with each of these -suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there -are no suffixes, and @var{filename} is used only as-is. Typical -values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess -Creation, exec-suffixes}), @code{load-suffixes}, -@code{load-file-rep-suffixes} and the return value of the function -@code{get-load-suffixes} (@pxref{Load Suffixes}). - -Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess -Creation, exec-path}) when looking for executable programs or -@code{load-path} (@pxref{Library Search, load-path}) when looking for -Lisp files. If @var{filename} is absolute, @var{path} has no effect, -but the suffixes in @var{suffixes} are still tried. - -The optional argument @var{predicate}, if non-@code{nil}, specifies -the predicate function to use for testing whether a candidate file is -suitable. The predicate function is passed the candidate file name as -its single argument. If @var{predicate} is @code{nil} or unspecified, -@code{locate-file} uses @code{file-readable-p} as the default -predicate. Useful non-default predicates include -@code{file-executable-p}, @code{file-directory-p}, and other -predicates described in @ref{Kinds of Files}. - -For compatibility, @var{predicate} can also be one of the symbols -@code{executable}, @code{readable}, @code{writable}, @code{exists}, or -a list of one or more of these symbols. -@end defun - -@defun executable-find program -This function searches for the executable file of the named -@var{program} and returns the full absolute name of the executable, -including its file-name extensions, if any. It returns @code{nil} if -the file is not found. The functions searches in all the directories -in @code{exec-path} and tries all the file-name extensions in -@code{exec-suffixes}. -@end defun - -@node Changing Files -@section Changing File Names and Attributes -@c @cindex renaming files Duplicates rename-file -@cindex copying files -@cindex deleting files -@cindex linking files -@cindex setting modes of files - - The functions in this section rename, copy, delete, link, and set the -modes of files. - - In the functions that have an argument @var{newname}, if a file by the -name of @var{newname} already exists, the actions taken depend on the -value of the argument @var{ok-if-already-exists}: - -@itemize @bullet -@item -Signal a @code{file-already-exists} error if -@var{ok-if-already-exists} is @code{nil}. - -@item -Request confirmation if @var{ok-if-already-exists} is a number. - -@item -Replace the old file without confirmation if @var{ok-if-already-exists} -is any other value. -@end itemize - -The next four commands all recursively follow symbolic links at all -levels of parent directories for their first argument, but, if that -argument is itself a symbolic link, then only @code{copy-file} -replaces it with its (recursive) target. - -@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists -@cindex file with multiple names -@cindex file hard link -This function gives the file named @var{oldname} the additional name -@var{newname}. This means that @var{newname} becomes a new ``hard -link'' to @var{oldname}. - -In the first part of the following example, we list two files, -@file{foo} and @file{foo3}. - -@example -@group -% ls -li fo* -81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo -84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 -@end group -@end example - -Now we create a hard link, by calling @code{add-name-to-file}, then list -the files again. This shows two names for one file, @file{foo} and -@file{foo2}. - -@example -@group -(add-name-to-file "foo" "foo2") - @result{} nil -@end group - -@group -% ls -li fo* -81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo -81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 -84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 -@end group -@end example - -Finally, we evaluate the following: - -@example -(add-name-to-file "foo" "foo3" t) -@end example - -@noindent -and list the files again. Now there are three names -for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old -contents of @file{foo3} are lost. - -@example -@group -(add-name-to-file "foo1" "foo3") - @result{} nil -@end group - -@group -% ls -li fo* -81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo -81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 -81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 -@end group -@end example - -This function is meaningless on operating systems where multiple names -for one file are not allowed. Some systems implement multiple names -by copying the file instead. - -See also @code{file-nlinks} in @ref{File Attributes}. -@end deffn - -@deffn Command rename-file filename newname &optional ok-if-already-exists -This command renames the file @var{filename} as @var{newname}. - -If @var{filename} has additional names aside from @var{filename}, it -continues to have those names. In fact, adding the name @var{newname} -with @code{add-name-to-file} and then deleting @var{filename} has the -same effect as renaming, aside from momentary intermediate states. -@end deffn - -@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid -This command copies the file @var{oldname} to @var{newname}. An -error is signaled if @var{oldname} does not exist. If @var{newname} -names a directory, it copies @var{oldname} into that directory, -preserving its final name component. - -If @var{time} is non-@code{nil}, then this function gives the new file -the same last-modified time that the old one has. (This works on only -some operating systems.) If setting the time gets an error, -@code{copy-file} signals a @code{file-date-error} error. In an -interactive call, a prefix argument specifies a non-@code{nil} value -for @var{time}. - -This function copies the file modes, too. - -If argument @var{preserve-uid-gid} is @code{nil}, we let the operating -system decide the user and group ownership of the new file (this is -usually set to the user running Emacs). If @var{preserve-uid-gid} is -non-@code{nil}, we attempt to copy the user and group ownership of the -file. This works only on some operating systems, and only if you have -the correct permissions to do so. -@end deffn - -@deffn Command make-symbolic-link filename newname &optional ok-if-exists -@pindex ln -@kindex file-already-exists -This command makes a symbolic link to @var{filename}, named -@var{newname}. This is like the shell command @samp{ln -s -@var{filename} @var{newname}}. - -This function is not available on systems that don't support symbolic -links. -@end deffn - -@deffn Command delete-file filename -@pindex rm -This command deletes the file @var{filename}, like the shell command -@samp{rm @var{filename}}. If the file has multiple names, it continues -to exist under the other names. - -A suitable kind of @code{file-error} error is signaled if the file does -not exist, or is not deletable. (On Unix and GNU/Linux, a file is -deletable if its directory is writable.) - -If @var{filename} is a symbolic link, @code{delete-file} does not -replace it with its target, but it does follow symbolic links at all -levels of parent directories. - -See also @code{delete-directory} in @ref{Create/Delete Dirs}. -@end deffn - -@defun define-logical-name varname string -This function defines the logical name @var{varname} to have the value -@var{string}. It is available only on VMS. -@end defun - -@defun set-file-modes filename mode -This function sets mode bits of @var{filename} to @var{mode} (which -must be an integer). Only the low 12 bits of @var{mode} are used. -This function recursively follows symbolic links at all levels for -@var{filename}. -@end defun - -@c Emacs 19 feature -@defun set-default-file-modes mode -@cindex umask -This function sets the default file protection for new files created by -Emacs and its subprocesses. Every file created with Emacs initially has -this protection, or a subset of it (@code{write-region} will not give a -file execute permission even if the default file protection allows -execute permission). On Unix and GNU/Linux, the default protection is -the bitwise complement of the ``umask'' value. - -The argument @var{mode} must be an integer. On most systems, only the -low 9 bits of @var{mode} are meaningful. You can use the Lisp construct -for octal character codes to enter @var{mode}; for example, - -@example -(set-default-file-modes ?\644) -@end example - -Saving a modified version of an existing file does not count as creating -the file; it preserves the existing file's mode, whatever that is. So -the default file protection has no effect. -@end defun - -@defun default-file-modes -This function returns the current default protection value. -@end defun - -@defun set-file-times filename &optional time -This function sets the access and modification times of @var{filename} -to @var{time}. The return value is @code{t} if the times are successfully -set, otherwise it is @code{nil}. @var{time} defaults to the current -time and must be in the format returned by @code{current-time} -(@pxref{Time of Day}). -@end defun - -@cindex MS-DOS and file modes -@cindex file modes and MS-DOS - On MS-DOS, there is no such thing as an ``executable'' file mode bit. -So Emacs considers a file executable if its name ends in one of the -standard executable extensions, such as @file{.com}, @file{.bat}, -@file{.exe}, and some others. Files that begin with the Unix-standard -@samp{#!} signature, such as shell and Perl scripts, are also considered -as executable files. This is reflected in the values returned by -@code{file-modes} and @code{file-attributes}. Directories are also -reported with executable bit set, for compatibility with Unix. - -@node File Names -@section File Names -@cindex file names - - Files are generally referred to by their names, in Emacs as elsewhere. -File names in Emacs are represented as strings. The functions that -operate on a file all expect a file name argument. - - In addition to operating on files themselves, Emacs Lisp programs -often need to operate on file names; i.e., to take them apart and to use -part of a name to construct related file names. This section describes -how to manipulate file names. - - The functions in this section do not actually access files, so they -can operate on file names that do not refer to an existing file or -directory. - - On MS-DOS and MS-Windows, these functions (like the function that -actually operate on files) accept MS-DOS or MS-Windows file-name syntax, -where backslashes separate the components, as well as Unix syntax; but -they always return Unix syntax. On VMS, these functions (and the ones -that operate on files) understand both VMS file-name syntax and Unix -syntax. This enables Lisp programs to specify file names in Unix syntax -and work properly on all systems without change. - -@menu -* 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. -@end menu - -@node File Name Components -@subsection File Name Components -@cindex directory part (of file name) -@cindex nondirectory part (of file name) -@cindex version number (in file name) - - The operating system groups files into directories. To specify a -file, you must specify the directory and the file's name within that -directory. Therefore, Emacs considers a file name as having two main -parts: the @dfn{directory name} part, and the @dfn{nondirectory} part -(or @dfn{file name within the directory}). Either part may be empty. -Concatenating these two parts reproduces the original file name. - - On most systems, the directory part is everything up to and including -the last slash (backslash is also allowed in input on MS-DOS or -MS-Windows); the nondirectory part is the rest. The rules in VMS syntax -are complicated. - - For some purposes, the nondirectory part is further subdivided into -the name proper and the @dfn{version number}. On most systems, only -backup files have version numbers in their names. On VMS, every file -has a version number, but most of the time the file name actually used -in Emacs omits the version number, so that version numbers in Emacs are -found mostly in directory lists. - -@defun file-name-directory filename -This function returns the directory part of @var{filename}, as a -directory name (@pxref{Directory Names}), or @code{nil} if -@var{filename} does not include a directory part. - -On GNU and Unix systems, a string returned by this function always -ends in a slash. On MS-DOS it can also end in a colon. On VMS, it -returns a string ending in one of the three characters @samp{:}, -@samp{]}, or @samp{>}. - -@example -@group -(file-name-directory "lewis/foo") ; @r{Unix example} - @result{} "lewis/" -@end group -@group -(file-name-directory "foo") ; @r{Unix example} - @result{} nil -@end group -@group -(file-name-directory "[X]FOO.TMP") ; @r{VMS example} - @result{} "[X]" -@end group -@end example -@end defun - -@defun file-name-nondirectory filename -This function returns the nondirectory part of @var{filename}. - -@example -@group -(file-name-nondirectory "lewis/foo") - @result{} "foo" -@end group -@group -(file-name-nondirectory "foo") - @result{} "foo" -@end group -@group -(file-name-nondirectory "lewis/") - @result{} "" -@end group -@group -;; @r{The following example is accurate only on VMS.} -(file-name-nondirectory "[X]FOO.TMP") - @result{} "FOO.TMP" -@end group -@end example -@end defun - -@defun file-name-sans-versions filename &optional keep-backup-version -This function returns @var{filename} with any file version numbers, -backup version numbers, or trailing tildes discarded. - -If @var{keep-backup-version} is non-@code{nil}, then true file version -numbers understood as such by the file system are discarded from the -return value, but backup version numbers are kept. - -@example -@group -(file-name-sans-versions "~rms/foo.~1~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo") - @result{} "~rms/foo" -@end group -@group -;; @r{The following example applies to VMS only.} -(file-name-sans-versions "foo;23") - @result{} "foo" -@end group -@end example -@end defun - -@defun file-name-extension filename &optional period -This function returns @var{filename}'s final ``extension,'' if any, -after applying @code{file-name-sans-versions} to remove any -version/backup part. The extension, in a file name, is the part that -starts with the last @samp{.} in the last name component (minus -any version/backup part). - -This function returns @code{nil} for extensionless file names such as -@file{foo}. It returns @code{""} for null extensions, as in -@file{foo.}. If the last component of a file name begins with a -@samp{.}, that @samp{.} doesn't count as the beginning of an -extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not -@samp{.emacs}. - -If @var{period} is non-@code{nil}, then the returned value includes -the period that delimits the extension, and if @var{filename} has no -extension, the value is @code{""}. -@end defun - -@defun file-name-sans-extension filename -This function returns @var{filename} minus its extension, if any. The -version/backup part, if present, is only removed if the file has an -extension. For example, - -@example -(file-name-sans-extension "foo.lose.c") - @result{} "foo.lose" -(file-name-sans-extension "big.hack/foo") - @result{} "big.hack/foo" -(file-name-sans-extension "/my/home/.emacs") - @result{} "/my/home/.emacs" -(file-name-sans-extension "/my/home/.emacs.el") - @result{} "/my/home/.emacs" -(file-name-sans-extension "~/foo.el.~3~") - @result{} "~/foo" -(file-name-sans-extension "~/foo.~3~") - @result{} "~/foo.~3~" -@end example - -Note that the @samp{.~3~} in the two last examples is the backup part, -not an extension. -@end defun - -@ignore -Andrew Innes says that this - -@c @defvar directory-sep-char -This variable holds the character that Emacs normally uses to separate -file name components. The default value is @code{?/}, but on MS-Windows -you can set it to @code{?\\}; then the functions that transform file names -use backslashes in their output. - -File names using backslashes work as input to Lisp primitives even on -MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default -value of @code{?/}. -@end defvar -@end ignore - -@node Relative File Names -@subsection Absolute and Relative File Names -@cindex absolute file name -@cindex relative file name - - All the directories in the file system form a tree starting at the -root directory. A file name can specify all the directory names -starting from the root of the tree; then it is called an @dfn{absolute} -file name. Or it can specify the position of the file in the tree -relative to a default directory; then it is called a @dfn{relative} file -name. On Unix and GNU/Linux, an absolute file name starts with a slash -or a tilde (@samp{~}), and a relative one does not. On MS-DOS and -MS-Windows, an absolute file name starts with a slash or a backslash, or -with a drive specification @samp{@var{x}:/}, where @var{x} is the -@dfn{drive letter}. The rules on VMS are complicated. - -@defun file-name-absolute-p filename -This function returns @code{t} if file @var{filename} is an absolute -file name, @code{nil} otherwise. On VMS, this function understands both -Unix syntax and VMS syntax. - -@example -@group -(file-name-absolute-p "~rms/foo") - @result{} t -@end group -@group -(file-name-absolute-p "rms/foo") - @result{} nil -@end group -@group -(file-name-absolute-p "/user/rms/foo") - @result{} t -@end group -@end example -@end defun - - Given a possibly relative file name, you can convert it to an -absolute name using @code{expand-file-name} (@pxref{File Name -Expansion}). This function converts absolute file names to relative -names: - -@defun file-relative-name filename &optional directory -This function tries to return a relative name that is equivalent to -@var{filename}, assuming the result will be interpreted relative to -@var{directory} (an absolute directory name or directory file name). -If @var{directory} is omitted or @code{nil}, it defaults to the -current buffer's default directory. - -On some operating systems, an absolute file name begins with a device -name. On such systems, @var{filename} has no relative equivalent based -on @var{directory} if they start with two different device names. In -this case, @code{file-relative-name} returns @var{filename} in absolute -form. - -@example -(file-relative-name "/foo/bar" "/foo/") - @result{} "bar" -(file-relative-name "/foo/bar" "/hack/") - @result{} "../foo/bar" -@end example -@end defun - -@node Directory Names -@comment node-name, next, previous, up -@subsection Directory Names -@cindex directory name -@cindex file name of directory - - A @dfn{directory name} is the name of a directory. A directory is -actually a kind of file, so it has a file name, which is related to -the directory name but not identical to it. (This is not quite the -same as the usual Unix terminology.) These two different names for -the same entity are related by a syntactic transformation. On GNU and -Unix systems, this is simple: a directory name ends in a slash, -whereas the directory's name as a file lacks that slash. On MS-DOS and -VMS, the relationship is more complicated. - - The difference between a directory name and its name as a file is -subtle but crucial. When an Emacs variable or function argument is -described as being a directory name, a file name of a directory is not -acceptable. When @code{file-name-directory} returns a string, that is -always a directory name. - - The following two functions convert between directory names and file -names. They do nothing special with environment variable substitutions -such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}. - -@defun file-name-as-directory filename -This function returns a string representing @var{filename} in a form -that the operating system will interpret as the name of a directory. On -most systems, this means appending a slash to the string (if it does not -already end in one). On VMS, the function converts a string of the form -@file{[X]Y.DIR.1} to the form @file{[X.Y]}. - -@example -@group -(file-name-as-directory "~rms/lewis") - @result{} "~rms/lewis/" -@end group -@end example -@end defun - -@defun directory-file-name dirname -This function returns a string representing @var{dirname} in a form that -the operating system will interpret as the name of a file. On most -systems, this means removing the final slash (or backslash) from the -string. On VMS, the function converts a string of the form @file{[X.Y]} -to @file{[X]Y.DIR.1}. - -@example -@group -(directory-file-name "~lewis/") - @result{} "~lewis" -@end group -@end example -@end defun - - Given a directory name, you can combine it with a relative file name -using @code{concat}: - -@example -(concat @var{dirname} @var{relfile}) -@end example - -@noindent -Be sure to verify that the file name is relative before doing that. -If you use an absolute file name, the results could be syntactically -invalid or refer to the wrong file. - - If you want to use a directory file name in making such a -combination, you must first convert it to a directory name using -@code{file-name-as-directory}: - -@example -(concat (file-name-as-directory @var{dirfile}) @var{relfile}) -@end example - -@noindent -Don't try concatenating a slash by hand, as in - -@example -;;; @r{Wrong!} -(concat @var{dirfile} "/" @var{relfile}) -@end example - -@noindent -because this is not portable. Always use -@code{file-name-as-directory}. - -@cindex directory name abbreviation - Directory name abbreviations are useful for directories that are -normally accessed through symbolic links. Sometimes the users recognize -primarily the link's name as ``the name'' of the directory, and find it -annoying to see the directory's ``real'' name. If you define the link -name as an abbreviation for the ``real'' name, Emacs shows users the -abbreviation instead. - -@defvar directory-abbrev-alist -The variable @code{directory-abbrev-alist} contains an alist of -abbreviations to use for file directories. Each element has the form -@code{(@var{from} . @var{to})}, and says to replace @var{from} with -@var{to} when it appears in a directory name. The @var{from} string is -actually a regular expression; it should always start with @samp{^}. -The @var{to} string should be an ordinary absolute directory name. Do -not use @samp{~} to stand for a home directory in that string. The -function @code{abbreviate-file-name} performs these substitutions. - -You can set this variable in @file{site-init.el} to describe the -abbreviations appropriate for your site. - -Here's an example, from a system on which file system @file{/home/fsf} -and so on are normally accessed through symbolic links named @file{/fsf} -and so on. - -@example -(("^/home/fsf" . "/fsf") - ("^/home/gp" . "/gp") - ("^/home/gd" . "/gd")) -@end example -@end defvar - - To convert a directory name to its abbreviation, use this -function: - -@defun abbreviate-file-name filename -@anchor{Definition of abbreviate-file-name} -This function applies abbreviations from @code{directory-abbrev-alist} -to its argument, and substitutes @samp{~} for the user's home -directory. You can use it for directory names and for file names, -because it recognizes abbreviations even as part of the name. -@end defun - -@node File Name Expansion -@subsection Functions that Expand Filenames -@cindex expansion of file names - - @dfn{Expansion} of a file name means converting a relative file name -to an absolute one. Since this is done relative to a default directory, -you must specify the default directory name as well as the file name to -be expanded. Expansion also simplifies file names by eliminating -redundancies such as @file{./} and @file{@var{name}/../}. - -@defun expand-file-name filename &optional directory -This function converts @var{filename} to an absolute file name. If -@var{directory} is supplied, it is the default directory to start with -if @var{filename} is relative. (The value of @var{directory} should -itself be an absolute directory name or directory file name; it may -start with @samp{~}.) Otherwise, the current buffer's value of -@code{default-directory} is used. For example: - -@example -@group -(expand-file-name "foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@group -(expand-file-name "../foo") - @result{} "/xcssun/users/rms/foo" -@end group -@group -(expand-file-name "foo" "/usr/spool/") - @result{} "/usr/spool/foo" -@end group -@group -(expand-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/lewis/$HOME/foo" -@end group -@end example - -If the part of the combined file name before the first slash is -@samp{~}, it expands to the value of the @env{HOME} environment -variable (usually your home directory). If the part before the first -slash is @samp{~@var{user}} and if @var{user} is a valid login name, -it expands to @var{user}'s home directory. - -Filenames containing @samp{.} or @samp{..} are simplified to their -canonical form: - -@example -@group -(expand-file-name "bar/../foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@end example - -In some cases, a leading @samp{..} component can remain in the output: - -@example -@group -(expand-file-name "../home" "/") - @result{} "/../home" -@end group -@end example - -@noindent -This is for the sake of filesystems that have the concept of a -``superroot'' above the root directory @file{/}. On other filesystems, -@file{/../} is interpreted exactly the same as @file{/}. - -Note that @code{expand-file-name} does @emph{not} expand environment -variables; only @code{substitute-in-file-name} does that. - -Note also that @code{expand-file-name} does not follow symbolic links -at any level. This results in a difference between the way -@code{file-truename} and @code{expand-file-name} treat @samp{..}. -Assuming that @samp{/tmp/bar} is a symbolic link to the directory -@samp{/tmp/foo/bar} we get: - -@example -@group -(file-truename "/tmp/bar/../myfile") - @result{} "/tmp/foo/myfile" -@end group -@group -(expand-file-name "/tmp/bar/../myfile") - @result{} "/tmp/myfile" -@end group -@end example - -If you may need to follow symbolic links preceding @samp{..}, you -should make sure to call @code{file-truename} without prior direct or -indirect calls to @code{expand-file-name}. @xref{Truenames}. -@end defun - -@defvar default-directory -The value of this buffer-local variable is the default directory for the -current buffer. It should be an absolute directory name; it may start -with @samp{~}. This variable is buffer-local in every buffer. - -@code{expand-file-name} uses the default directory when its second -argument is @code{nil}. - -Aside from VMS, the value is always a string ending with a slash. - -@example -@group -default-directory - @result{} "/user/lewis/manual/" -@end group -@end example -@end defvar - -@defun substitute-in-file-name filename -@anchor{Definition of substitute-in-file-name} -This function replaces environment variable references in -@var{filename} with the environment variable values. Following -standard Unix shell syntax, @samp{$} is the prefix to substitute an -environment variable value. If the input contains @samp{$$}, that is -converted to @samp{$}; this gives the user a way to ``quote'' a -@samp{$}. - -The environment variable name is the series of alphanumeric characters -(including underscores) that follow the @samp{$}. If the character following -the @samp{$} is a @samp{@{}, then the variable name is everything up to the -matching @samp{@}}. - -Calling @code{substitute-in-file-name} on output produced by -@code{substitute-in-file-name} tends to give incorrect results. For -instance, use of @samp{$$} to quote a single @samp{$} won't work -properly, and @samp{$} in an environment variable's value could lead -to repeated substitution. Therefore, programs that call this function -and put the output where it will be passed to this function need to -double all @samp{$} characters to prevent subsequent incorrect -results. - -@c Wordy to avoid overfull hbox. --rjc 15mar92 -Here we assume that the environment variable @code{HOME}, which holds -the user's home directory name, has value @samp{/xcssun/users/rms}. - -@example -@group -(substitute-in-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/foo" -@end group -@end example - -After substitution, if a @samp{~} or a @samp{/} appears immediately -after another @samp{/}, the function discards everything before it (up -through the immediately preceding @samp{/}). - -@example -@group -(substitute-in-file-name "bar/~/foo") - @result{} "~/foo" -@end group -@group -(substitute-in-file-name "/usr/local/$HOME/foo") - @result{} "/xcssun/users/rms/foo" - ;; @r{@file{/usr/local/} has been discarded.} -@end group -@end example - -On VMS, @samp{$} substitution is not done, so this function does nothing -on VMS except discard superfluous initial components as shown above. -@end defun - -@node Unique File Names -@subsection Generating Unique File Names - - Some programs need to write temporary files. Here is the usual way to -construct a name for such a file: - -@example -(make-temp-file @var{name-of-application}) -@end example - -@noindent -The job of @code{make-temp-file} is to prevent two different users or -two different jobs from trying to use the exact same file name. - -@defun make-temp-file prefix &optional dir-flag suffix -This function creates a temporary file and returns its name. Emacs -creates the temporary file's name by adding to @var{prefix} some -random characters that are different in each Emacs job. The result is -guaranteed to be a newly created empty file. On MS-DOS, this function -can truncate the @var{string} prefix to fit into the 8+3 file-name -limits. If @var{prefix} is a relative file name, it is expanded -against @code{temporary-file-directory}. - -@example -@group -(make-temp-file "foo") - @result{} "/tmp/foo232J6v" -@end group -@end example - -When @code{make-temp-file} returns, the file has been created and is -empty. At that point, you should write the intended contents into the -file. - -If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an -empty directory instead of an empty file. It returns the file name, -not the directory name, of that directory. @xref{Directory Names}. - -If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at -the end of the file name. - -To prevent conflicts among different libraries running in the same -Emacs, each Lisp program that uses @code{make-temp-file} should have its -own @var{prefix}. The number added to the end of @var{prefix} -distinguishes between the same application running in different Emacs -jobs. Additional added characters permit a large number of distinct -names even in one Emacs job. -@end defun - - The default directory for temporary files is controlled by the -variable @code{temporary-file-directory}. This variable gives the user -a uniform way to specify the directory for all temporary files. Some -programs use @code{small-temporary-file-directory} instead, if that is -non-@code{nil}. To use it, you should expand the prefix against -the proper directory before calling @code{make-temp-file}. - - In older Emacs versions where @code{make-temp-file} does not exist, -you should use @code{make-temp-name} instead: - -@example -(make-temp-name - (expand-file-name @var{name-of-application} - temporary-file-directory)) -@end example - -@defun make-temp-name string -This function generates a string that can be used as a unique file -name. The name starts with @var{string}, and has several random -characters appended to it, which are different in each Emacs job. It -is like @code{make-temp-file} except that it just constructs a name, -and does not create a file. Another difference is that @var{string} -should be an absolute file name. On MS-DOS, this function can -truncate the @var{string} prefix to fit into the 8+3 file-name limits. -@end defun - -@defvar temporary-file-directory -@cindex @code{TMPDIR} environment variable -@cindex @code{TMP} environment variable -@cindex @code{TEMP} environment variable -This variable specifies the directory name for creating temporary files. -Its value should be a directory name (@pxref{Directory Names}), but it -is good for Lisp programs to cope if the value is a directory's file -name instead. Using the value as the second argument to -@code{expand-file-name} is a good way to achieve that. - -The default value is determined in a reasonable way for your operating -system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP} -environment variables, with a fall-back to a system-dependent name if -none of these variables is defined. - -Even if you do not use @code{make-temp-file} to create the temporary -file, you should still use this variable to decide which directory to -put the file in. However, if you expect the file to be small, you -should use @code{small-temporary-file-directory} first if that is -non-@code{nil}. -@end defvar - -@defvar small-temporary-file-directory -This variable specifies the directory name for -creating certain temporary files, which are likely to be small. - -If you want to write a temporary file which is likely to be small, you -should compute the directory like this: - -@example -(make-temp-file - (expand-file-name @var{prefix} - (or small-temporary-file-directory - temporary-file-directory))) -@end example -@end defvar - -@node File Name Completion -@subsection File Name Completion -@cindex file name completion subroutines -@cindex completion, file name - - This section describes low-level subroutines for completing a file -name. For higher level functions, see @ref{Reading File Names}. - -@defun file-name-all-completions partial-filename directory -This function returns a list of all possible completions for a file -whose name starts with @var{partial-filename} in directory -@var{directory}. The order of the completions is the order of the files -in the directory, which is unpredictable and conveys no useful -information. - -The argument @var{partial-filename} must be a file name containing no -directory part and no slash (or backslash on some systems). The current -buffer's default directory is prepended to @var{directory}, if -@var{directory} is not absolute. - -In the following example, suppose that @file{~rms/lewis} is the current -default directory, and has five files whose names begin with @samp{f}: -@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill - -@example -@group -(file-name-all-completions "f" "") - @result{} ("foo" "file~" "file.c.~2~" - "file.c.~1~" "file.c") -@end group - -@group -(file-name-all-completions "fo" "") - @result{} ("foo") -@end group -@end example -@end defun - -@defun file-name-completion filename directory &optional predicate -This function completes the file name @var{filename} in directory -@var{directory}. It returns the longest prefix common to all file names -in directory @var{directory} that start with @var{filename}. If -@var{predicate} is non-@code{nil} then it ignores possible completions -that don't satisfy @var{predicate}, after calling that function -with one argument, the expanded absolute file name. - -If only one match exists and @var{filename} matches it exactly, the -function returns @code{t}. The function returns @code{nil} if directory -@var{directory} contains no name starting with @var{filename}. - -In the following example, suppose that the current default directory -has five files whose names begin with @samp{f}: @file{foo}, -@file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill - -@example -@group -(file-name-completion "fi" "") - @result{} "file" -@end group - -@group -(file-name-completion "file.c.~1" "") - @result{} "file.c.~1~" -@end group - -@group -(file-name-completion "file.c.~1~" "") - @result{} t -@end group - -@group -(file-name-completion "file.c.~3" "") - @result{} nil -@end group -@end example -@end defun - -@defopt completion-ignored-extensions -@code{file-name-completion} usually ignores file names that end in any -string in this list. It does not ignore them when all the possible -completions end in one of these suffixes. This variable has no effect -on @code{file-name-all-completions}.@refill - -A typical value might look like this: - -@example -@group -completion-ignored-extensions - @result{} (".o" ".elc" "~" ".dvi") -@end group -@end example - -If an element of @code{completion-ignored-extensions} ends in a slash -@samp{/}, it signals a directory. The elements which do @emph{not} end -in a slash will never match a directory; thus, the above value will not -filter out a directory named @file{foo.elc}. -@end defopt - -@node Standard File Names -@subsection Standard File Names - - Most of the file names used in Lisp programs are entered by the user. -But occasionally a Lisp program needs to specify a standard file name -for a particular use---typically, to hold customization information -about each user. For example, abbrev definitions are stored (by -default) in the file @file{~/.abbrev_defs}; the @code{completion} -package stores completions in the file @file{~/.completions}. These are -two of the many standard file names used by parts of Emacs for certain -purposes. - - Various operating systems have their own conventions for valid file -names and for which file names to use for user profile data. A Lisp -program which reads a file using a standard file name ought to use, on -each type of system, a file name suitable for that system. The function -@code{convert-standard-filename} makes this easy to do. - -@defun convert-standard-filename filename -This function alters the file name @var{filename} to fit the conventions -of the operating system in use, and returns the result as a new string. -@end defun - - The recommended way to specify a standard file name in a Lisp program -is to choose a name which fits the conventions of GNU and Unix systems, -usually with a nondirectory part that starts with a period, and pass it -to @code{convert-standard-filename} instead of using it directly. Here -is an example from the @code{completion} package: - -@example -(defvar save-completions-file-name - (convert-standard-filename "~/.completions") - "*The file name to save completions to.") -@end example - - On GNU and Unix systems, and on some other systems as well, -@code{convert-standard-filename} returns its argument unchanged. On -some other systems, it alters the name to fit the system's conventions. - - For example, on MS-DOS the alterations made by this function include -converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the -middle of the name to @samp{.} if there is no other @samp{.}, inserting -a @samp{.} after eight characters if there is none, and truncating to -three characters after the @samp{.}. (It makes other changes as well.) -Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and -@file{.completions} becomes @file{_complet.ion}. - -@node Contents of Directories -@section Contents of Directories -@cindex directory-oriented functions -@cindex file names in directory - - A directory is a kind of file that contains other files entered under -various names. Directories are a feature of the file system. - - Emacs can list the names of the files in a directory as a Lisp list, -or display the names in a buffer using the @code{ls} shell command. In -the latter case, it can optionally display information about each file, -depending on the options passed to the @code{ls} command. - -@defun directory-files directory &optional full-name match-regexp nosort -This function returns a list of the names of the files in the directory -@var{directory}. By default, the list is in alphabetical order. - -If @var{full-name} is non-@code{nil}, the function returns the files' -absolute file names. Otherwise, it returns the names relative to -the specified directory. - -If @var{match-regexp} is non-@code{nil}, this function returns only -those file names that contain a match for that regular expression---the -other file names are excluded from the list. On case-insensitive -filesystems, the regular expression matching is case-insensitive. - -@c Emacs 19 feature -If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort -the list, so you get the file names in no particular order. Use this if -you want the utmost possible speed and don't care what order the files -are processed in. If the order of processing is visible to the user, -then the user will probably be happier if you do sort the names. - -@example -@group -(directory-files "~lewis") - @result{} ("#foo#" "#foo.el#" "." ".." - "dired-mods.el" "files.texi" - "files.texi.~1~") -@end group -@end example - -An error is signaled if @var{directory} is not the name of a directory -that can be read. -@end defun - -@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format -This is similar to @code{directory-files} in deciding which files -to report on and how to report their names. However, instead -of returning a list of file names, it returns for each file a -list @code{(@var{filename} . @var{attributes})}, where @var{attributes} -is what @code{file-attributes} would return for that file. -The optional argument @var{id-format} has the same meaning as the -corresponding argument to @code{file-attributes} (@pxref{Definition -of file-attributes}). -@end defun - -@defun file-name-all-versions file dirname -This function returns a list of all versions of the file named -@var{file} in directory @var{dirname}. It is only available on VMS. -@end defun - -@defun file-expand-wildcards pattern &optional full -This function expands the wildcard pattern @var{pattern}, returning -a list of file names that match it. - -If @var{pattern} is written as an absolute file name, -the values are absolute also. - -If @var{pattern} is written as a relative file name, it is interpreted -relative to the current default directory. The file names returned are -normally also relative to the current default directory. However, if -@var{full} is non-@code{nil}, they are absolute. -@end defun - -@defun insert-directory file switches &optional wildcard full-directory-p -This function inserts (in the current buffer) a directory listing for -directory @var{file}, formatted with @code{ls} according to -@var{switches}. It leaves point after the inserted text. -@var{switches} may be a string of options, or a list of strings -representing individual options. - -The argument @var{file} may be either a directory name or a file -specification including wildcard characters. If @var{wildcard} is -non-@code{nil}, that means treat @var{file} as a file specification with -wildcards. - -If @var{full-directory-p} is non-@code{nil}, that means the directory -listing is expected to show the full contents of a directory. You -should specify @code{t} when @var{file} is a directory and switches do -not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to -describe a directory itself as a file, rather than showing its -contents.) - -On most systems, this function works by running a directory listing -program whose name is in the variable @code{insert-directory-program}. -If @var{wildcard} is non-@code{nil}, it also runs the shell specified by -@code{shell-file-name}, to expand the wildcards. - -MS-DOS and MS-Windows systems usually lack the standard Unix program -@code{ls}, so this function emulates the standard Unix program @code{ls} -with Lisp code. - -As a technical detail, when @var{switches} contains the long -@samp{--dired} option, @code{insert-directory} treats it specially, -for the sake of dired. However, the normally equivalent short -@samp{-D} option is just passed on to @code{insert-directory-program}, -as any other option. -@end defun - -@defvar insert-directory-program -This variable's value is the program to run to generate a directory listing -for the function @code{insert-directory}. It is ignored on systems -which generate the listing with Lisp code. -@end defvar - -@node Create/Delete Dirs -@section Creating and Deleting Directories -@cindex creating and deleting directories -@c Emacs 19 features - - Most Emacs Lisp file-manipulation functions get errors when used on -files that are directories. For example, you cannot delete a directory -with @code{delete-file}. These special functions exist to create and -delete directories. - -@defun make-directory dirname &optional parents -This function creates a directory named @var{dirname}. -If @var{parents} is non-@code{nil}, as is always the case in an -interactive call, that means to create the parent directories first, -if they don't already exist. -@end defun - -@defun delete-directory dirname -This function deletes the directory named @var{dirname}. The function -@code{delete-file} does not work for files that are directories; you -must use @code{delete-directory} for them. If the directory contains -any files, @code{delete-directory} signals an error. - -This function only follows symbolic links at the level of parent -directories. -@end defun - -@node Magic File Names -@section Making Certain File Names ``Magic'' -@cindex magic file names - -@c Emacs 19 feature - You can implement special handling for certain file names. This is -called making those names @dfn{magic}. The principal use for this -feature is in implementing remote file names (@pxref{Remote Files,, -Remote Files, emacs, The GNU Emacs Manual}). - - To define a kind of magic file name, you must supply a regular -expression to define the class of names (all those that match the -regular expression), plus a handler that implements all the primitive -Emacs file operations for file names that do match. - - The variable @code{file-name-handler-alist} holds a list of handlers, -together with regular expressions that determine when to apply each -handler. Each element has this form: - -@example -(@var{regexp} . @var{handler}) -@end example - -@noindent -All the Emacs primitives for file access and file name transformation -check the given file name against @code{file-name-handler-alist}. If -the file name matches @var{regexp}, the primitives handle that file by -calling @var{handler}. - - The first argument given to @var{handler} is the name of the -primitive, as a symbol; the remaining arguments are the arguments that -were passed to that primitive. (The first of these arguments is most -often the file name itself.) For example, if you do this: - -@example -(file-exists-p @var{filename}) -@end example - -@noindent -and @var{filename} has handler @var{handler}, then @var{handler} is -called like this: - -@example -(funcall @var{handler} 'file-exists-p @var{filename}) -@end example - - When a function takes two or more arguments that must be file names, -it checks each of those names for a handler. For example, if you do -this: - -@example -(expand-file-name @var{filename} @var{dirname}) -@end example - -@noindent -then it checks for a handler for @var{filename} and then for a handler -for @var{dirname}. In either case, the @var{handler} is called like -this: - -@example -(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname}) -@end example - -@noindent -The @var{handler} then needs to figure out whether to handle -@var{filename} or @var{dirname}. - - If the specified file name matches more than one handler, the one -whose match starts last in the file name gets precedence. This rule -is chosen so that handlers for jobs such as uncompression are handled -first, before handlers for jobs such as remote file access. - - Here are the operations that a magic file name handler gets to handle: - -@ifnottex -@noindent -@code{access-file}, @code{add-name-to-file}, -@code{byte-compiler-base-file-name},@* -@code{copy-file}, @code{delete-directory}, -@code{delete-file}, -@code{diff-latest-backup-file}, -@code{directory-file-name}, -@code{directory-files}, -@code{directory-files-and-attributes}, -@code{dired-compress-file}, @code{dired-uncache},@* -@code{expand-file-name}, -@code{file-accessible-directory-p}, -@code{file-attributes}, -@code{file-directory-p}, -@code{file-executable-p}, @code{file-exists-p}, -@code{file-local-copy}, @code{file-remote-p}, -@code{file-modes}, @code{file-name-all-completions}, -@code{file-name-as-directory}, -@code{file-name-completion}, -@code{file-name-directory}, -@code{file-name-nondirectory}, -@code{file-name-sans-versions}, @code{file-newer-than-file-p}, -@code{file-ownership-preserved-p}, -@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, -@code{file-truename}, @code{file-writable-p}, -@code{find-backup-file-name}, -@code{find-file-noselect},@* -@code{get-file-buffer}, -@code{insert-directory}, -@code{insert-file-contents},@* -@code{load}, -@code{make-auto-save-file-name}, -@code{make-directory}, -@code{make-directory-internal}, -@code{make-symbolic-link},@* -@code{process-file}, -@code{rename-file}, @code{set-file-modes}, @code{set-file-times}, -@code{set-visited-file-modtime}, @code{shell-command}, -@code{start-file-process}, -@code{substitute-in-file-name},@* -@code{unhandled-file-name-directory}, -@code{vc-registered}, -@code{verify-visited-file-modtime},@* -@code{write-region}. -@end ifnottex -@iftex -@noindent -@flushleft -@code{access-file}, @code{add-name-to-file}, -@code{byte-com@discretionary{}{}{}piler-base-file-name}, -@code{copy-file}, @code{delete-directory}, -@code{delete-file}, -@code{diff-latest-backup-file}, -@code{directory-file-name}, -@code{directory-files}, -@code{directory-files-and-at@discretionary{}{}{}tributes}, -@code{dired-compress-file}, @code{dired-uncache}, -@code{expand-file-name}, -@code{file-accessible-direc@discretionary{}{}{}tory-p}, -@code{file-attributes}, -@code{file-direct@discretionary{}{}{}ory-p}, -@code{file-executable-p}, @code{file-exists-p}, -@code{file-local-copy}, @code{file-remote-p}, -@code{file-modes}, @code{file-name-all-completions}, -@code{file-name-as-directory}, -@code{file-name-completion}, -@code{file-name-directory}, -@code{file-name-nondirec@discretionary{}{}{}tory}, -@code{file-name-sans-versions}, @code{file-newer-than-file-p}, -@code{file-ownership-pre@discretionary{}{}{}served-p}, -@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, -@code{file-truename}, @code{file-writable-p}, -@code{find-backup-file-name}, -@code{find-file-noselect}, -@code{get-file-buffer}, -@code{insert-directory}, -@code{insert-file-contents}, -@code{load}, @code{make-direc@discretionary{}{}{}tory}, -@code{make-direc@discretionary{}{}{}tory-internal}, -@code{make-symbolic-link}, -@code{process-file}, -@code{rename-file}, @code{set-file-modes}, -@code{set-visited-file-modtime}, @code{shell-command}, -@code{start-file-process}, -@code{substitute-in-file-name}, -@code{unhandled-file-name-directory}, -@code{vc-regis@discretionary{}{}{}tered}, -@code{verify-visited-file-modtime}, -@code{write-region}. -@end flushleft -@end iftex - - Handlers for @code{insert-file-contents} typically need to clear the -buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the -@var{visit} argument is non-@code{nil}. This also has the effect of -unlocking the buffer if it is locked. - - The handler function must handle all of the above operations, and -possibly others to be added in the future. It need not implement all -these operations itself---when it has nothing special to do for a -certain operation, it can reinvoke the primitive, to handle the -operation ``in the usual way.'' It should always reinvoke the primitive -for an operation it does not recognize. Here's one way to do this: - -@smallexample -(defun my-file-handler (operation &rest args) - ;; @r{First check for the specific operations} - ;; @r{that we have special handling for.} - (cond ((eq operation 'insert-file-contents) @dots{}) - ((eq operation 'write-region) @dots{}) - @dots{} - ;; @r{Handle any operation we don't know about.} - (t (let ((inhibit-file-name-handlers - (cons 'my-file-handler - (and (eq inhibit-file-name-operation operation) - inhibit-file-name-handlers))) - (inhibit-file-name-operation operation)) - (apply operation args))))) -@end smallexample - - When a handler function decides to call the ordinary Emacs primitive for -the operation at hand, it needs to prevent the primitive from calling -the same handler once again, thus leading to an infinite recursion. The -example above shows how to do this, with the variables -@code{inhibit-file-name-handlers} and -@code{inhibit-file-name-operation}. Be careful to use them exactly as -shown above; the details are crucial for proper behavior in the case of -multiple handlers, and for operations that have two file names that may -each have handlers. - -@kindex safe-magic (@r{property}) - Handlers that don't really do anything special for actual access to the -file---such as the ones that implement completion of host names for -remote file names---should have a non-@code{nil} @code{safe-magic} -property. For instance, Emacs normally ``protects'' directory names -it finds in @code{PATH} from becoming magic, if they look like magic -file names, by prefixing them with @samp{/:}. But if the handler that -would be used for them has a non-@code{nil} @code{safe-magic} -property, the @samp{/:} is not added. - -@kindex operations (@r{property}) - A file name handler can have an @code{operations} property to -declare which operations it handles in a nontrivial way. If this -property has a non-@code{nil} value, it should be a list of -operations; then only those operations will call the handler. This -avoids inefficiency, but its main purpose is for autoloaded handler -functions, so that they won't be loaded except when they have real -work to do. - - Simply deferring all operations to the usual primitives does not -work. For instance, if the file name handler applies to -@code{file-exists-p}, then it must handle @code{load} itself, because -the usual @code{load} code won't work properly in that case. However, -if the handler uses the @code{operations} property to say it doesn't -handle @code{file-exists-p}, then it need not handle @code{load} -nontrivially. - -@defvar inhibit-file-name-handlers -This variable holds a list of handlers whose use is presently inhibited -for a certain operation. -@end defvar - -@defvar inhibit-file-name-operation -The operation for which certain handlers are presently inhibited. -@end defvar - -@defun find-file-name-handler file operation -This function returns the handler function for file name @var{file}, -or @code{nil} if there is none. The argument @var{operation} should -be the operation to be performed on the file---the value you will pass -to the handler as its first argument when you call it. If -@var{operation} equals @code{inhibit-file-name-operation}, or if it is -not found in the @code{operations} property of the handler, this -function returns @code{nil}. -@end defun - -@defun file-local-copy filename -This function copies file @var{filename} to an ordinary non-magic file -on the local machine, if it isn't on the local machine already. Magic -file names should handle the @code{file-local-copy} operation if they -refer to files on other machines. A magic file name that is used for -other purposes than remote file access should not handle -@code{file-local-copy}; then this function will treat the file as -local. - -If @var{filename} is local, whether magic or not, this function does -nothing and returns @code{nil}. Otherwise it returns the file name -of the local copy file. -@end defun - -@defun file-remote-p filename &optional identification connected -This function tests whether @var{filename} is a remote file. If -@var{filename} is local (not remote), the return value is @code{nil}. -If @var{filename} is indeed remote, the return value is a string that -identifies the remote system. - -This identifier string can include a host name and a user name, as -well as characters designating the method used to access the remote -system. For example, the remote identifier string for the filename -@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}. - -If @code{file-remote-p} returns the same identifier for two different -filenames, that means they are stored on the same file system and can -be accessed locally with respect to each other. This means, for -example, that it is possible to start a remote process accessing both -files at the same time. Implementors of file handlers need to ensure -this principle is valid. - -@var{identification} specifies which part of the identifier shall be -returned as string. @var{identification} can be the symbol -@code{method}, @code{user} or @code{host}; any other value is handled -like @code{nil} and means to return the complete identifier string. -In the example above, the remote @code{user} identifier string would -be @code{root}. - -If @var{connected} is non-@code{nil}, this function returns @code{nil} -even if @var{filename} is remote, if Emacs has no network connection -to its host. This is useful when you want to avoid the delay of -making connections when they don't exist. -@end defun - -@defun unhandled-file-name-directory filename -This function returns the name of a directory that is not magic. It -uses the directory part of @var{filename} if that is not magic. For a -magic file name, it invokes the file name handler, which therefore -decides what value to return. - -This is useful for running a subprocess; every subprocess must have a -non-magic directory to serve as its current directory, and this function -is a good way to come up with one. -@end defun - -@node Format Conversion -@section File Format Conversion - -@cindex file format conversion -@cindex encoding file formats -@cindex decoding file formats -@cindex text properties in files -@cindex saving text properties - Emacs performs several steps to convert the data in a buffer (text, -text properties, and possibly other information) to and from a -representation suitable for storing into a file. This section describes -the fundamental functions that perform this @dfn{format conversion}, -namely @code{insert-file-contents} for reading a file into a buffer, -and @code{write-region} for writing a buffer into a file. - -@menu -* Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region} -* Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}. -* Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion. -@end menu - -@node Format Conversion Overview -@subsection Overview -@noindent -The function @code{insert-file-contents}: - -@itemize -@item initially, inserts bytes from the file into the buffer; -@item decodes bytes to characters as appropriate; -@item processes formats as defined by entries in @code{format-alist}; and -@item calls functions in @code{after-insert-file-functions}. -@end itemize - -@noindent -The function @code{write-region}: - -@itemize -@item initially, calls functions in @code{write-region-annotate-functions}; -@item processes formats as defined by entries in @code{format-alist}; -@item encodes characters to bytes as appropriate; and -@item modifies the file with the bytes. -@end itemize - - This shows the symmetry of the lowest-level operations; reading and -writing handle things in opposite order. The rest of this section -describes the two facilities surrounding the three variables named -above, as well as some related functions. @ref{Coding Systems}, for -details on character encoding and decoding. - -@node Format Conversion Round-Trip -@subsection Round-Trip Specification - - The most general of the two facilities is controlled by the variable -@code{format-alist}, a list of @dfn{file format} specifications, which -describe textual representations used in files for the data in an Emacs -buffer. The descriptions for reading and writing are paired, which is -why we call this ``round-trip'' specification -(@pxref{Format Conversion Piecemeal}, for non-paired specification). - -@defvar format-alist -This list contains one format definition for each defined file format. -Each format definition is a list of this form: - -@example -(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn}) -@end example -@end defvar - -@cindex format definition -@noindent -Here is what the elements in a format definition mean: - -@table @var -@item name -The name of this format. - -@item doc-string -A documentation string for the format. - -@item regexp -A regular expression which is used to recognize files represented in -this format. - -@item from-fn -A shell command or function to decode data in this format (to convert -file data into the usual Emacs data representation). - -A shell command is represented as a string; Emacs runs the command as a -filter to perform the conversion. - -If @var{from-fn} is a function, it is called with two arguments, @var{begin} -and @var{end}, which specify the part of the buffer it should convert. -It should convert the text by editing it in place. Since this can -change the length of the text, @var{from-fn} should return the modified -end position. - -One responsibility of @var{from-fn} is to make sure that the beginning -of the file no longer matches @var{regexp}. Otherwise it is likely to -get called again. - -@item to-fn -A shell command or function to encode data in this format---that is, to -convert the usual Emacs data representation into this format. - -If @var{to-fn} is a string, it is a shell command; Emacs runs the -command as a filter to perform the conversion. - -If @var{to-fn} is a function, it is called with three arguments: -@var{begin} and @var{end}, which specify the part of the buffer it -should convert, and @var{buffer}, which specifies which buffer. There -are two ways it can do the conversion: - -@itemize @bullet -@item -By editing the buffer in place. In this case, @var{to-fn} should -return the end-position of the range of text, as modified. - -@item -By returning a list of annotations. This is a list of elements of the -form @code{(@var{position} . @var{string})}, where @var{position} is an -integer specifying the relative position in the text to be written, and -@var{string} is the annotation to add there. The list must be sorted in -order of position when @var{to-fn} returns it. - -When @code{write-region} actually writes the text from the buffer to the -file, it intermixes the specified annotations at the corresponding -positions. All this takes place without modifying the buffer. -@end itemize - -@item modify -A flag, @code{t} if the encoding function modifies the buffer, and -@code{nil} if it works by returning a list of annotations. - -@item mode-fn -A minor-mode function to call after visiting a file converted from this -format. The function is called with one argument, the integer 1; -that tells a minor-mode function to enable the mode. -@end table - -The function @code{insert-file-contents} automatically recognizes file -formats when it reads the specified file. It checks the text of the -beginning of the file against the regular expressions of the format -definitions, and if it finds a match, it calls the decoding function for -that format. Then it checks all the known formats over again. -It keeps checking them until none of them is applicable. - -Visiting a file, with @code{find-file-noselect} or the commands that use -it, performs conversion likewise (because it calls -@code{insert-file-contents}); it also calls the mode function for each -format that it decodes. It stores a list of the format names in the -buffer-local variable @code{buffer-file-format}. - -@defvar buffer-file-format -This variable states the format of the visited file. More precisely, -this is a list of the file format names that were decoded in the course -of visiting the current buffer's file. It is always buffer-local in all -buffers. -@end defvar - -When @code{write-region} writes data into a file, it first calls the -encoding functions for the formats listed in @code{buffer-file-format}, -in the order of appearance in the list. - -@deffn Command format-write-file file format &optional confirm -This command writes the current buffer contents into the file -@var{file} in format @var{format}, and makes that format the default -for future saves of the buffer. The argument @var{format} is a list -of format names. Except for the @var{format} argument, this command -is similar to @code{write-file}. In particular, @var{confirm} has the -same meaning and interactive treatment as the corresponding argument -to @code{write-file}. @xref{Definition of write-file}. -@end deffn - -@deffn Command format-find-file file format -This command finds the file @var{file}, converting it according to -format @var{format}. It also makes @var{format} the default if the -buffer is saved later. - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end deffn - -@deffn Command format-insert-file file format &optional beg end -This command inserts the contents of file @var{file}, converting it -according to format @var{format}. If @var{beg} and @var{end} are -non-@code{nil}, they specify which part of the file to read, as in -@code{insert-file-contents} (@pxref{Reading from Files}). - -The return value is like what @code{insert-file-contents} returns: a -list of the absolute file name and the length of the data inserted -(after conversion). - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end deffn - -@defvar buffer-auto-save-file-format -This variable specifies the format to use for auto-saving. Its value is -a list of format names, just like the value of -@code{buffer-file-format}; however, it is used instead of -@code{buffer-file-format} for writing auto-save files. If the value -is @code{t}, the default, auto-saving uses the same format as a -regular save in the same buffer. This variable is always buffer-local -in all buffers. -@end defvar - -@node Format Conversion Piecemeal -@subsection Piecemeal Specification - - In contrast to the round-trip specification described in the previous -subsection (@pxref{Format Conversion Round-Trip}), you can use the variables -@code{after-insert-file-functions} and @code{write-region-annotate-functions} -to separately control the respective reading and writing conversions. - - Conversion starts with one representation and produces another -representation. When there is only one conversion to do, there is no -conflict about what to start with. However, when there are multiple -conversions involved, conflict may arise when two conversions need to -start with the same data. - - This situation is best understood in the context of converting text -properties during @code{write-region}. For example, the character at -position 42 in a buffer is @samp{X} with a text property @code{foo}. If -the conversion for @code{foo} is done by inserting into the buffer, say, -@samp{FOO:}, then that changes the character at position 42 from -@samp{X} to @samp{F}. The next conversion will start with the wrong -data straight away. - - To avoid conflict, cooperative conversions do not modify the buffer, -but instead specify @dfn{annotations}, a list of elements of the form -@code{(@var{position} . @var{string})}, sorted in order of increasing -@var{position}. - - If there is more than one conversion, @code{write-region} merges their -annotations destructively into one sorted list. Later, when the text -from the buffer is actually written to the file, it intermixes the -specified annotations at the corresponding positions. All this takes -place without modifying the buffer. - -@c ??? What about ``overriding'' conversions like those allowed -@c ??? for `write-region-annotate-functions', below? --ttn - - In contrast, when reading, the annotations intermixed with the text -are handled immediately. @code{insert-file-contents} sets point to the -beginning of some text to be converted, then calls the conversion -functions with the length of that text. These functions should always -return with point at the beginning of the inserted text. This approach -makes sense for reading because annotations removed by the first -converter can't be mistakenly processed by a later converter. - - Each conversion function should scan for the annotations it -recognizes, remove the annotation, modify the buffer text (to set a text -property, for example), and return the updated length of the text, as it -stands after those changes. The value returned by one function becomes -the argument to the next function. - -@defvar write-region-annotate-functions -A list of functions for @code{write-region} to call. Each function in -the list is called with two arguments: the start and end of the region -to be written. These functions should not alter the contents of the -buffer. Instead, they should return annotations. - -@c ??? Following adapted from comment in `build_annotations' (fileio.c). -@c ??? Perhaps this is intended for internal use only? -@c ??? Someone who understands this, please reword it. --ttn -As a special case, if a function returns with a different buffer -current, Emacs takes it to mean the current buffer contains altered text -to be output, and discards all previous annotations because they should -have been dealt with by this function. -@end defvar - -@defvar after-insert-file-functions -Each function in this list is called by @code{insert-file-contents} -with one argument, the number of characters inserted, and with point -at the beginning of the inserted text. Each function should leave -point unchanged, and return the new character count describing the -inserted text as modified by the function. -@c ??? The docstring mentions a handler from `file-name-handler-alist' -@c "intercepting" `insert-file-contents'. Hmmm. --ttn -@end defvar - - We invite users to write Lisp programs to store and retrieve text -properties in files, using these hooks, and thus to experiment with -various data formats and find good ones. Eventually we hope users -will produce good, general extensions we can install in Emacs. - - We suggest not trying to handle arbitrary Lisp objects as text property -names or values---because a program that general is probably difficult -to write, and slow. Instead, choose a set of possible data types that -are reasonably flexible, and not too hard to encode. - -@ignore - arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c -@end ignore diff --git a/lispref/frames.texi b/lispref/frames.texi deleted file mode 100644 index 7d2ea7cf70e..00000000000 --- a/lispref/frames.texi +++ /dev/null @@ -1,2208 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/frames -@node Frames, Positions, Windows, Top -@chapter Frames -@cindex frame - - In Emacs editing, A @dfn{frame} is a screen object that contains one -or more Emacs windows. It's the kind of object that is called a -``window'' in the terminology of graphical environments; but we can't -call it a ``window'' here, because Emacs uses that word in a different -way. - - A frame initially contains a single main window and/or a minibuffer -window; you can subdivide the main window vertically or horizontally -into smaller windows. In Emacs Lisp, a @dfn{frame object} is a Lisp -object that represents a frame on the screen. - -@cindex terminal frame - When Emacs runs on a text-only terminal, it starts with one -@dfn{terminal frame}. If you create additional ones, Emacs displays -one and only one at any given time---on the terminal screen, of course. - -@cindex window frame - When Emacs communicates directly with a supported window system, such -as X, it does not have a terminal frame; instead, it starts with -a single @dfn{window frame}, but you can create more, and Emacs can -display several such frames at once as is usual for window systems. - -@defun framep object -This predicate returns a non-@code{nil} value if @var{object} is a -frame, and @code{nil} otherwise. For a frame, the value indicates which -kind of display the frame uses: - -@table @code -@item x -The frame is displayed in an X window. -@item t -A terminal frame on a character display. -@item mac -The frame is displayed on a Macintosh. -@item w32 -The frame is displayed on MS-Windows 9X/NT. -@item pc -The frame is displayed on an MS-DOS terminal. -@end table -@end defun - -@menu -* Creating Frames:: Creating additional frames. -* Multiple Displays:: Creating frames on other 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 windows; - lowering it makes the others hide it. -* 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 X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* 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. -@end menu - - @xref{Display}, for information about the related topic of -controlling Emacs redisplay. - -@node Creating Frames -@section Creating Frames - -To create a new frame, call the function @code{make-frame}. - -@defun make-frame &optional alist -This function creates and returns a new frame, displaying the current -buffer. If you are using a supported window system, it makes a window -frame; otherwise, it makes a terminal frame. - -The argument is an alist specifying frame parameters. Any parameters -not mentioned in @var{alist} default according to the value of the -variable @code{default-frame-alist}; parameters not specified even there -default from the standard X resources or whatever is used instead on -your system. - -The set of possible parameters depends in principle on what kind of -window system Emacs uses to display its frames. @xref{Window Frame -Parameters}, for documentation of individual parameters you can specify. - -This function itself does not make the new frame the selected frame. -@xref{Input Focus}. The previously selected frame remains selected. -However, the window system may select the new frame for its own reasons, -for instance if the frame appears under the mouse pointer and your -setup is for focus to follow the pointer. -@end defun - -@defvar before-make-frame-hook -A normal hook run by @code{make-frame} before it actually creates the -frame. -@end defvar - -@defvar after-make-frame-functions -An abnormal hook run by @code{make-frame} after it creates the frame. -Each function in @code{after-make-frame-functions} receives one argument, the -frame just created. -@end defvar - -@node Multiple Displays -@section Multiple Displays -@cindex multiple X displays -@cindex displays, multiple - - A single Emacs can talk to more than one X display. -Initially, Emacs uses just one display---the one chosen with the -@code{DISPLAY} environment variable or with the @samp{--display} option -(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to -another display, use the command @code{make-frame-on-display} or specify -the @code{display} frame parameter when you create the frame. - - Emacs treats each X server as a separate terminal, giving each one its -own selected frame and its own minibuffer windows. However, only one of -those frames is ``@emph{the} selected frame'' at any given moment, see -@ref{Input Focus}. - - A few Lisp variables are @dfn{terminal-local}; that is, they have a -separate binding for each terminal. The binding in effect at any time -is the one for the terminal that the currently selected frame belongs -to. These variables include @code{default-minibuffer-frame}, -@code{defining-kbd-macro}, @code{last-kbd-macro}, and -@code{system-key-alist}. They are always terminal-local, and can never -be buffer-local (@pxref{Buffer-Local Variables}) or frame-local. - - A single X server can handle more than one screen. A display name -@samp{@var{host}:@var{server}.@var{screen}} has three parts; the last -part specifies the screen number for a given server. When you use two -screens belonging to one server, Emacs knows by the similarity in their -names that they share a single keyboard, and it treats them as a single -terminal. - - Note that some graphical terminals can output to more than a one -monitor (or other output device) at the same time. On these -``multi-monitor'' setups, a single @var{display} value controls the -output to all the physical monitors. In this situation, there is -currently no platform-independent way for Emacs to distinguish between -the different physical monitors. - -@deffn Command make-frame-on-display display &optional parameters -This creates and returns a new frame on display @var{display}, taking -the other frame parameters from @var{parameters}. Aside from the -@var{display} argument, it is like @code{make-frame} (@pxref{Creating -Frames}). -@end deffn - -@defun x-display-list -This returns a list that indicates which X displays Emacs has a -connection to. The elements of the list are strings, and each one is -a display name. -@end defun - -@defun x-open-connection display &optional xrm-string must-succeed -This function opens a connection to the X display @var{display}. It -does not create a frame on that display, but it permits you to check -that communication can be established with that display. - -The optional argument @var{xrm-string}, if not @code{nil}, is a -string of resource names and values, in the same format used in the -@file{.Xresources} file. The values you specify override the resource -values recorded in the X server itself; they apply to all Emacs frames -created on this display. Here's an example of what this string might -look like: - -@example -"*BorderWidth: 3\n*InternalBorder: 2\n" -@end example - -@xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. - -If @var{must-succeed} is non-@code{nil}, failure to open the connection -terminates Emacs. Otherwise, it is an ordinary Lisp error. -@end defun - -@defun x-close-connection display -This function closes the connection to display @var{display}. Before -you can do this, you must first delete all the frames that were open on -that display (@pxref{Deleting Frames}). -@end defun - -@node Frame Parameters -@section Frame Parameters -@cindex frame parameters - - A frame has many parameters that control its appearance and behavior. -Just what parameters a frame has depends on what display mechanism it -uses. - - Frame parameters exist mostly for the sake of window systems. A -terminal frame has a few parameters, mostly for compatibility's sake; -only the @code{height}, @code{width}, @code{name}, @code{title}, -@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate} -parameters do something special. If the terminal supports colors, the -parameters @code{foreground-color}, @code{background-color}, -@code{background-mode} and @code{display-type} are also meaningful. - -@menu -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. -@end menu - -@node Parameter Access -@subsection Access to Frame Parameters - -These functions let you read and change the parameter values of a -frame. - -@defun frame-parameter frame parameter -This function returns the value of the parameter @var{parameter} (a -symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the -selected frame's parameter. If @var{frame} has no setting for -@var{parameter}, this function returns @code{nil}. -@end defun - -@defun frame-parameters &optional frame -The function @code{frame-parameters} returns an alist listing all the -parameters of @var{frame} and their values. If @var{frame} is -@code{nil} or omitted, this returns the selected frame's parameters -@end defun - -@defun modify-frame-parameters frame alist -This function alters the parameters of frame @var{frame} based on the -elements of @var{alist}. Each element of @var{alist} has the form -@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a -parameter. If you don't mention a parameter in @var{alist}, its value -doesn't change. If @var{frame} is @code{nil}, it defaults to the selected -frame. -@end defun - -@defun modify-all-frames-parameters alist -This function alters the frame parameters of all existing frames -according to @var{alist}, then modifies @code{default-frame-alist} -(and, if necessary, @code{initial-frame-alist}) to apply the same -parameter values to frames that will be created henceforth. -@end defun - -@node Initial Parameters -@subsection Initial Frame Parameters - -You can specify the parameters for the initial startup frame -by setting @code{initial-frame-alist} in your init file (@pxref{Init File}). - -@defvar initial-frame-alist -This variable's value is an alist of parameter values used when creating -the initial window frame. You can set this variable to specify the -appearance of the initial frame without altering subsequent frames. -Each element has the form: - -@example -(@var{parameter} . @var{value}) -@end example - -Emacs creates the initial frame before it reads your init -file. After reading that file, Emacs checks @code{initial-frame-alist}, -and applies the parameter settings in the altered value to the already -created initial frame. - -If these settings affect the frame geometry and appearance, you'll see -the frame appear with the wrong ones and then change to the specified -ones. If that bothers you, you can specify the same geometry and -appearance with X resources; those do take effect before the frame is -created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. - -X resource settings typically apply to all frames. If you want to -specify some X resources solely for the sake of the initial frame, and -you don't want them to apply to subsequent frames, here's how to achieve -this. Specify parameters in @code{default-frame-alist} to override the -X resources for subsequent frames; then, to prevent these from affecting -the initial frame, specify the same parameters in -@code{initial-frame-alist} with values that match the X resources. -@end defvar - -If these parameters specify a separate minibuffer-only frame with -@code{(minibuffer . nil)}, and you have not created one, Emacs creates -one for you. - -@defvar minibuffer-frame-alist -This variable's value is an alist of parameter values used when creating -an initial minibuffer-only frame---if such a frame is needed, according -to the parameters for the main initial frame. -@end defvar - -@defvar default-frame-alist -This is an alist specifying default values of frame parameters for all -Emacs frames---the first frame, and subsequent frames. When using the X -Window System, you can get the same results by means of X resources -in many cases. - -Setting this variable does not affect existing frames. -@end defvar - -See also @code{special-display-frame-alist}. @xref{Definition of -special-display-frame-alist}. - -If you use options that specify window appearance when you invoke Emacs, -they take effect by adding elements to @code{default-frame-alist}. One -exception is @samp{-geometry}, which adds the specified position to -@code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command -Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}. - -@node Window Frame Parameters -@subsection Window Frame Parameters - - Just what parameters a frame has depends on what display mechanism -it uses. This section describes the parameters that have special -meanings on some or all kinds of terminals. Of these, @code{name}, -@code{title}, @code{height}, @code{width}, @code{buffer-list} and -@code{buffer-predicate} provide meaningful information in terminal -frames, and @code{tty-color-mode} is meaningful @emph{only} in -terminal frames. - -@menu -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Color Parameters:: Colors of various parts of the frame. -@end menu - -@node Basic Parameters -@subsubsection Basic Parameters - - These frame parameters give the most basic information about the -frame. @code{title} and @code{name} are meaningful on all terminals. - -@table @code -@item display -The display on which to open this frame. It should be a string of the -form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the -@code{DISPLAY} environment variable. - -@item display-type -This parameter describes the range of possible colors that can be used -in this frame. Its value is @code{color}, @code{grayscale} or -@code{mono}. - -@item title -If a frame has a non-@code{nil} title, it appears in the window system's -border for the frame, and also in the mode line of windows in that frame -if @code{mode-line-frame-identification} uses @samp{%F} -(@pxref{%-Constructs}). This is normally the case when Emacs is not -using a window system, and can only display one frame at a time. -@xref{Frame Titles}. - -@item name -The name of the frame. The frame name serves as a default for the frame -title, if the @code{title} parameter is unspecified or @code{nil}. If -you don't specify a name, Emacs sets the frame name automatically -(@pxref{Frame Titles}). - -If you specify the frame name explicitly when you create the frame, the -name is also used (instead of the name of the Emacs executable) when -looking up X resources for the frame. - -@item display-environment-variable -The value of the @code{DISPLAY} environment variable for the frame. It -is passed to child processes. - -@item term-environment-variable -The value of the @code{TERM} environment variable for the frame. It -is passed to child processes. -@end table - -@node Position Parameters -@subsubsection Position Parameters - - Position parameters' values are normally measured in pixels, but on -text-only terminals they count characters or lines instead. - -@table @code -@item left -The screen position of the left edge, in pixels, with respect to the -left edge of the screen. The value may be a positive number @var{pos}, -or a list of the form @code{(+ @var{pos})} which permits specifying a -negative @var{pos} value. - -A negative number @minus{}@var{pos}, or a list of the form @code{(- -@var{pos})}, actually specifies the position of the right edge of the -window with respect to the right edge of the screen. A positive value -of @var{pos} counts toward the left. @strong{Reminder:} if the -parameter is a negative integer @minus{}@var{pos}, then @var{pos} is -positive. - -Some window managers ignore program-specified positions. If you want to -be sure the position you specify is not ignored, specify a -non-@code{nil} value for the @code{user-position} parameter as well. - -@item top -The screen position of the top edge, in pixels, with respect to the -top edge of the screen. It works just like @code{left}, except vertically -instead of horizontally. - -@item icon-left -The screen position of the left edge @emph{of the frame's icon}, in -pixels, counting from the left edge of the screen. This takes effect if -and when the frame is iconified. - -If you specify a value for this parameter, then you must also specify -a value for @code{icon-top} and vice versa. The window manager may -ignore these two parameters. - -@item icon-top -The screen position of the top edge @emph{of the frame's icon}, in -pixels, counting from the top edge of the screen. This takes effect if -and when the frame is iconified. - -@item user-position -When you create a frame and specify its screen position with the -@code{left} and @code{top} parameters, use this parameter to say whether -the specified position was user-specified (explicitly requested in some -way by a human user) or merely program-specified (chosen by a program). -A non-@code{nil} value says the position was user-specified. - -Window managers generally heed user-specified positions, and some heed -program-specified positions too. But many ignore program-specified -positions, placing the window in a default fashion or letting the user -place it with the mouse. Some window managers, including @code{twm}, -let the user specify whether to obey program-specified positions or -ignore them. - -When you call @code{make-frame}, you should specify a non-@code{nil} -value for this parameter if the values of the @code{left} and @code{top} -parameters represent the user's stated preference; otherwise, use -@code{nil}. -@end table - -@node Size Parameters -@subsubsection Size Parameters - - Size parameters' values are normally measured in pixels, but on -text-only terminals they count characters or lines instead. - -@table @code -@item height -The height of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) - -@item width -The width of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) - -@item user-size -This does for the size parameters @code{height} and @code{width} what -the @code{user-position} parameter (see above) does for the position -parameters @code{top} and @code{left}. - -@item fullscreen -Specify that width, height or both shall be set to the size of the screen. -The value @code{fullwidth} specifies that width shall be the size of the -screen. The value @code{fullheight} specifies that height shall be the -size of the screen. The value @code{fullboth} specifies that both the -width and the height shall be set to the size of the screen. -@end table - -@node Layout Parameters -@subsubsection Layout Parameters - - These frame parameters enable or disable various parts of the -frame, or control their sizes. - -@table @code -@item border-width -The width in pixels of the frame's border. - -@item internal-border-width -The distance in pixels between text (or fringe) and the frame's border. - -@item vertical-scroll-bars -Whether the frame has scroll bars for vertical scrolling, and which side -of the frame they should be on. The possible values are @code{left}, -@code{right}, and @code{nil} for no scroll bars. - -@ignore -@item horizontal-scroll-bars -Whether the frame has scroll bars for horizontal scrolling -(non-@code{nil} means yes). Horizontal scroll bars are not currently -implemented. -@end ignore - -@item scroll-bar-width -The width of vertical scroll bars, in pixels, or @code{nil} meaning to -use the default width. - -@item left-fringe -@itemx right-fringe -The default width of the left and right fringes of windows in this -frame (@pxref{Fringes}). If either of these is zero, that effectively -removes the corresponding fringe. A value of @code{nil} stands for -the standard fringe width, which is the width needed to display the -fringe bitmaps. - -The combined fringe widths must add up to an integral number of -columns, so the actual default fringe widths for the frame may be -larger than the specified values. The extra width needed to reach an -acceptable total is distributed evenly between the left and right -fringe. However, you can force one fringe or the other to a precise -width by specifying that width as a negative integer. If both widths are -negative, only the left fringe gets the specified width. - -@item menu-bar-lines -The number of lines to allocate at the top of the frame for a menu -bar. The default is 1. A value of @code{nil} means don't display a -menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one -menu bar line; they treat larger values as 1.) - -@item tool-bar-lines -The number of lines to use for the tool bar. A value of @code{nil} -means don't display a tool bar. (GTK allows at most one tool bar line; -it treats larger values as 1.) - -@item line-spacing -Additional space to leave below each text line, in pixels (a positive -integer). @xref{Line Height}, for more information. -@end table - -@node Buffer Parameters -@subsubsection Buffer Parameters - - These frame parameters, meaningful on all kinds of terminals, deal -with which buffers have been, or should, be displayed in the frame. - -@table @code -@item minibuffer -Whether this frame has its own minibuffer. The value @code{t} means -yes, @code{nil} means no, @code{only} means this frame is just a -minibuffer. If the value is a minibuffer window (in some other frame), -the new frame uses that minibuffer. - -@item buffer-predicate -The buffer-predicate function for this frame. The function -@code{other-buffer} uses this predicate (from the selected frame) to -decide which buffers it should consider, if the predicate is not -@code{nil}. It calls the predicate with one argument, a buffer, once for -each buffer; if the predicate returns a non-@code{nil} value, it -considers that buffer. - -@item buffer-list -A list of buffers that have been selected in this frame, -ordered most-recently-selected first. - -@item unsplittable -If non-@code{nil}, this frame's window is never split automatically. -@end table - -@node Management Parameters -@subsubsection Window Management Parameters -@cindex window manager, and frame parameters - - These frame parameters, meaningful only on window system displays, -interact with the window manager. - -@table @code -@item visibility -The state of visibility of the frame. There are three possibilities: -@code{nil} for invisible, @code{t} for visible, and @code{icon} for -iconified. @xref{Visibility of Frames}. - -@item auto-raise -Whether selecting the frame raises it (non-@code{nil} means yes). - -@item auto-lower -Whether deselecting the frame lowers it (non-@code{nil} means yes). - -@item icon-type -The type of icon to use for this frame when it is iconified. If the -value is a string, that specifies a file containing a bitmap to use. -Any other non-@code{nil} value specifies the default bitmap icon (a -picture of a gnu); @code{nil} specifies a text icon. - -@item icon-name -The name to use in the icon for this frame, when and if the icon -appears. If this is @code{nil}, the frame's title is used. - -@item window-id -The number of the window-system window used by the frame -to contain the actual Emacs windows. - -@item outer-window-id -The number of the outermost window-system window used for the whole frame. - -@item wait-for-wm -If non-@code{nil}, tell Xt to wait for the window manager to confirm -geometry changes. Some window managers, including versions of Fvwm2 -and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to -prevent hanging with those window managers. - -@ignore -@item parent-id -@c ??? Not yet working. -The X window number of the window that should be the parent of this one. -Specifying this lets you create an Emacs window inside some other -application's window. (It is not certain this will be implemented; try -it and see if it works.) -@end ignore -@end table - -@node Cursor Parameters -@subsubsection Cursor Parameters - - This frame parameter controls the way the cursor looks. - -@table @code -@item cursor-type -How to display the cursor. Legitimate values are: - -@table @code -@item box -Display a filled box. (This is the default.) -@item hollow -Display a hollow box. -@item nil -Don't display a cursor. -@item bar -Display a vertical bar between characters. -@item (bar . @var{width}) -Display a vertical bar @var{width} pixels wide between characters. -@item hbar -Display a horizontal bar. -@item (hbar . @var{height}) -Display a horizontal bar @var{height} pixels high. -@end table -@end table - -@vindex cursor-type -The buffer-local variable @code{cursor-type} overrides the value of -the @code{cursor-type} frame parameter, but if it is @code{t}, that -means to use the cursor specified for the frame. - -@defvar blink-cursor-alist -This variable specifies how to blink the cursor. Each element has the -form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor -type equals @var{on-state} (comparing using @code{equal}), the -corresponding @var{off-state} specifies what the cursor looks like -when it blinks ``off.'' Both @var{on-state} and @var{off-state} -should be suitable values for the @code{cursor-type} frame parameter. - -There are various defaults for how to blink each type of cursor, if -the type is not mentioned as an @var{on-state} here. Changes in this -variable do not take effect immediately, because the variable is -examined only when you specify the @code{cursor-type} parameter. -@end defvar - -@node Color Parameters -@subsubsection Color Parameters - - These frame parameters control the use of colors. - -@table @code -@item background-mode -This parameter is either @code{dark} or @code{light}, according -to whether the background color is a light one or a dark one. - -@item tty-color-mode -@cindex standard colors for character terminals -This parameter overrides the terminal's color support as given by the -system's terminal capabilities database in that this parameter's value -specifies the color mode to use in terminal frames. The value can be -either a symbol or a number. A number specifies the number of colors -to use (and, indirectly, what commands to issue to produce each -color). For example, @code{(tty-color-mode . 8)} specifies use of the -ANSI escape sequences for 8 standard text colors. A value of -1 turns -off color support. - -If the parameter's value is a symbol, it specifies a number through -the value of @code{tty-color-mode-alist}, and the associated number is -used instead. - -@item screen-gamma -@cindex gamma correction -If this is a number, Emacs performs ``gamma correction'' which adjusts -the brightness of all colors. The value should be the screen gamma of -your display, a floating point number. - -Usual PC monitors have a screen gamma of 2.2, so color values in -Emacs, and in X windows generally, are calibrated to display properly -on a monitor with that gamma value. If you specify 2.2 for -@code{screen-gamma}, that means no correction is needed. Other values -request correction, designed to make the corrected colors appear on -your screen the way they would have appeared without correction on an -ordinary monitor with a gamma value of 2.2. - -If your monitor displays colors too light, you should specify a -@code{screen-gamma} value smaller than 2.2. This requests correction -that makes colors darker. A screen gamma value of 1.5 may give good -results for LCD color displays. -@end table - -These frame parameters are semi-obsolete in that they are automatically -equivalent to particular face attributes of particular faces. -@xref{Standard Faces,,, emacs, The Emacs Manual}. - -@table @code -@item font -The name of the font for displaying text in the frame. This is a -string, either a valid font name for your system or the name of an Emacs -fontset (@pxref{Fontsets}). It is equivalent to the @code{font} -attribute of the @code{default} face. - -@item foreground-color -The color to use for the image of a character. It is equivalent to -the @code{:foreground} attribute of the @code{default} face. - -@item background-color -The color to use for the background of characters. It is equivalent to -the @code{:background} attribute of the @code{default} face. - -@item mouse-color -The color for the mouse pointer. It is equivalent to the @code{:background} -attribute of the @code{mouse} face. - -@item cursor-color -The color for the cursor that shows point. It is equivalent to the -@code{:background} attribute of the @code{cursor} face. - -@item border-color -The color for the border of the frame. It is equivalent to the -@code{:background} attribute of the @code{border} face. - -@item scroll-bar-foreground -If non-@code{nil}, the color for the foreground of scroll bars. It is -equivalent to the @code{:foreground} attribute of the -@code{scroll-bar} face. - -@item scroll-bar-background -If non-@code{nil}, the color for the background of scroll bars. It is -equivalent to the @code{:background} attribute of the -@code{scroll-bar} face. -@end table - -@node Size and Position -@subsection Frame Size And Position -@cindex size of frame -@cindex screen size -@cindex frame size -@cindex resize frame - - You can read or change the size and position of a frame using the -frame parameters @code{left}, @code{top}, @code{height}, and -@code{width}. Whatever geometry parameters you don't specify are chosen -by the window manager in its usual fashion. - - Here are some special features for working with sizes and positions. -(For the precise meaning of ``selected frame'' used by these functions, -see @ref{Input Focus}.) - -@defun set-frame-position frame left top -This function sets the position of the top left corner of @var{frame} to -@var{left} and @var{top}. These arguments are measured in pixels, and -normally count from the top left corner of the screen. - -Negative parameter values position the bottom edge of the window up from -the bottom edge of the screen, or the right window edge to the left of -the right edge of the screen. It would probably be better if the values -were always counted from the left and top, so that negative arguments -would position the frame partly off the top or left edge of the screen, -but it seems inadvisable to change that now. -@end defun - -@defun frame-height &optional frame -@defunx frame-width &optional frame -These functions return the height and width of @var{frame}, measured in -lines and columns. If you don't supply @var{frame}, they use the -selected frame. -@end defun - -@defun screen-height -@defunx screen-width -These functions are old aliases for @code{frame-height} and -@code{frame-width}. When you are using a non-window terminal, the size -of the frame is normally the same as the size of the terminal screen. -@end defun - -@defun frame-pixel-height &optional frame -@defunx frame-pixel-width &optional frame -These functions return the height and width of @var{frame}, measured in -pixels. If you don't supply @var{frame}, they use the selected frame. -@end defun - -@defun frame-char-height &optional frame -@defunx frame-char-width &optional frame -These functions return the height and width of a character in -@var{frame}, measured in pixels. The values depend on the choice of -font. If you don't supply @var{frame}, these functions use the selected -frame. -@end defun - -@defun set-frame-size frame cols rows -This function sets the size of @var{frame}, measured in characters; -@var{cols} and @var{rows} specify the new width and height. - -To set the size based on values measured in pixels, use -@code{frame-char-height} and @code{frame-char-width} to convert -them to units of characters. -@end defun - -@defun set-frame-height frame lines &optional pretend -This function resizes @var{frame} to a height of @var{lines} lines. The -sizes of existing windows in @var{frame} are altered proportionally to -fit. - -If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines} -lines of output in @var{frame}, but does not change its value for the -actual height of the frame. This is only useful for a terminal frame. -Using a smaller height than the terminal actually implements may be -useful to reproduce behavior observed on a smaller screen, or if the -terminal malfunctions when using its whole screen. Setting the frame -height ``for real'' does not always work, because knowing the correct -actual size may be necessary for correct cursor positioning on a -terminal frame. -@end defun - -@defun set-frame-width frame width &optional pretend -This function sets the width of @var{frame}, measured in characters. -The argument @var{pretend} has the same meaning as in -@code{set-frame-height}. -@end defun - -@findex set-screen-height -@findex set-screen-width - The older functions @code{set-screen-height} and -@code{set-screen-width} were used to specify the height and width of the -screen, in Emacs versions that did not support multiple frames. They -are semi-obsolete, but still work; they apply to the selected frame. - -@node Geometry -@subsection Geometry - - Here's how to examine the data in an X-style window geometry -specification: - -@defun x-parse-geometry geom -@cindex geometry specification -The function @code{x-parse-geometry} converts a standard X window -geometry string to an alist that you can use as part of the argument to -@code{make-frame}. - -The alist describes which parameters were specified in @var{geom}, and -gives the values specified for them. Each element looks like -@code{(@var{parameter} . @var{value})}. The possible @var{parameter} -values are @code{left}, @code{top}, @code{width}, and @code{height}. - -For the size parameters, the value must be an integer. The position -parameter names @code{left} and @code{top} are not totally accurate, -because some values indicate the position of the right or bottom edges -instead. These are the @var{value} possibilities for the position -parameters: - -@table @asis -@item an integer -A positive integer relates the left edge or top edge of the window to -the left or top edge of the screen. A negative integer relates the -right or bottom edge of the window to the right or bottom edge of the -screen. - -@item @code{(+ @var{position})} -This specifies the position of the left or top edge of the window -relative to the left or top edge of the screen. The integer -@var{position} may be positive or negative; a negative value specifies a -position outside the screen. - -@item @code{(- @var{position})} -This specifies the position of the right or bottom edge of the window -relative to the right or bottom edge of the screen. The integer -@var{position} may be positive or negative; a negative value specifies a -position outside the screen. -@end table - -Here is an example: - -@example -(x-parse-geometry "35x70+0-0") - @result{} ((height . 70) (width . 35) - (top - 0) (left . 0)) -@end example -@end defun - -@node Frame Titles -@section Frame Titles -@cindex frame title - - Every frame has a @code{name} parameter; this serves as the default -for the frame title which window systems typically display at the top of -the frame. You can specify a name explicitly by setting the @code{name} -frame property. - - Normally you don't specify the name explicitly, and Emacs computes the -frame name automatically based on a template stored in the variable -@code{frame-title-format}. Emacs recomputes the name each time the -frame is redisplayed. - -@defvar frame-title-format -This variable specifies how to compute a name for a frame when you have -not explicitly specified one. The variable's value is actually a mode -line construct, just like @code{mode-line-format}, except that the -@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line -Data}. -@end defvar - -@defvar icon-title-format -This variable specifies how to compute the name for an iconified frame, -when you have not explicitly specified the frame title. This title -appears in the icon itself. -@end defvar - -@defvar multiple-frames -This variable is set automatically by Emacs. Its value is @code{t} when -there are two or more frames (not counting minibuffer-only frames or -invisible frames). The default value of @code{frame-title-format} uses -@code{multiple-frames} so as to put the buffer name in the frame title -only when there is more than one frame. - -The value of this variable is not guaranteed to be accurate except -while processing @code{frame-title-format} or -@code{icon-title-format}. -@end defvar - -@node Deleting Frames -@section Deleting Frames -@cindex deleting frames - -Frames remain potentially visible until you explicitly @dfn{delete} -them. A deleted frame cannot appear on the screen, but continues to -exist as a Lisp object until there are no references to it. - -@deffn Command delete-frame &optional frame force -@vindex delete-frame-functions -This function deletes the frame @var{frame}. Unless @var{frame} is a -tooltip, it first runs the hook @code{delete-frame-functions} (each -function gets one argument, @var{frame}). By default, @var{frame} is -the selected frame. - -A frame cannot be deleted if its minibuffer is used by other frames. -Normally, you cannot delete a frame if all other frames are invisible, -but if the @var{force} is non-@code{nil}, then you are allowed to do so. -@end deffn - -@defun frame-live-p frame -The function @code{frame-live-p} returns non-@code{nil} if the frame -@var{frame} has not been deleted. The possible non-@code{nil} return -values are like those of @code{framep}. @xref{Frames}. -@end defun - - Some window managers provide a command to delete a window. These work -by sending a special message to the program that operates the window. -When Emacs gets one of these commands, it generates a -@code{delete-frame} event, whose normal definition is a command that -calls the function @code{delete-frame}. @xref{Misc Events}. - -@node Finding All Frames -@section Finding All Frames -@cindex frames, scanning all - -@defun frame-list -The function @code{frame-list} returns a list of all the frames that -have not been deleted. It is analogous to @code{buffer-list} for -buffers, and includes frames on all terminals. The list that you get is -newly created, so modifying the list doesn't have any effect on the -internals of Emacs. -@end defun - -@defun visible-frame-list -This function returns a list of just the currently visible frames. -@xref{Visibility of Frames}. (Terminal frames always count as -``visible,'' even though only the selected one is actually displayed.) -@end defun - -@defun next-frame &optional frame minibuf -The function @code{next-frame} lets you cycle conveniently through all -the frames on the current display from an arbitrary starting point. It -returns the ``next'' frame after @var{frame} in the cycle. If -@var{frame} is omitted or @code{nil}, it defaults to the selected frame -(@pxref{Input Focus}). - -The second argument, @var{minibuf}, says which frames to consider: - -@table @asis -@item @code{nil} -Exclude minibuffer-only frames. -@item @code{visible} -Consider all visible frames. -@item 0 -Consider all visible or iconified frames. -@item a window -Consider only the frames using that particular window as their -minibuffer. -@item anything else -Consider all frames. -@end table -@end defun - -@defun previous-frame &optional frame minibuf -Like @code{next-frame}, but cycles through all frames in the opposite -direction. -@end defun - - See also @code{next-window} and @code{previous-window}, in @ref{Cyclic -Window Ordering}. - -@node Frames and Windows -@section Frames and Windows - - Each window is part of one and only one frame; you can get the frame -with @code{window-frame}. - -@defun window-frame window -This function returns the frame that @var{window} is on. -@end defun - - All the non-minibuffer windows in a frame are arranged in a cyclic -order. The order runs from the frame's top window, which is at the -upper left corner, down and to the right, until it reaches the window at -the lower right corner (always the minibuffer window, if the frame has -one), and then it moves back to the top. @xref{Cyclic Window Ordering}. - -@defun frame-first-window &optional frame -This returns the topmost, leftmost window of frame @var{frame}. -If omitted or @code{nil}, @var{frame} defaults to the selected frame. -@end defun - -At any time, exactly one window on any frame is @dfn{selected within the -frame}. The significance of this designation is that selecting the -frame also selects this window. You can get the frame's current -selected window with @code{frame-selected-window}. - -@defun frame-selected-window &optional frame -This function returns the window on @var{frame} that is selected -within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to -the selected frame. -@end defun - -@defun set-frame-selected-window frame window -This sets the selected window of frame @var{frame} to @var{window}. -If @var{frame} is @code{nil}, it operates on the selected frame. If -@var{frame} is the selected frame, this makes @var{window} the -selected window. This function returns @var{window}. -@end defun - - Conversely, selecting a window for Emacs with @code{select-window} also -makes that window selected within its frame. @xref{Selecting Windows}. - - Another function that (usually) returns one of the windows in a given -frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}. - -@node Minibuffers and Frames -@section Minibuffers and Frames - -Normally, each frame has its own minibuffer window at the bottom, which -is used whenever that frame is selected. If the frame has a minibuffer, -you can get it with @code{minibuffer-window} (@pxref{Definition of -minibuffer-window}). - -However, you can also create a frame with no minibuffer. Such a frame -must use the minibuffer window of some other frame. When you create the -frame, you can specify explicitly the minibuffer window to use (in some -other frame). If you don't, then the minibuffer is found in the frame -which is the value of the variable @code{default-minibuffer-frame}. Its -value should be a frame that does have a minibuffer. - -If you use a minibuffer-only frame, you might want that frame to raise -when you enter the minibuffer. If so, set the variable -@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}. - -@defvar default-minibuffer-frame -This variable specifies the frame to use for the minibuffer window, by -default. It does not affect existing frames. It is always local to -the current terminal and cannot be buffer-local. @xref{Multiple -Displays}. -@end defvar - -@node Input Focus -@section Input Focus -@cindex input focus -@c @cindex selected frame Duplicates selected-frame - -At any time, one frame in Emacs is the @dfn{selected frame}. The selected -window always resides on the selected frame. - -When Emacs displays its frames on several terminals (@pxref{Multiple -Displays}), each terminal has its own selected frame. But only one of -these is ``@emph{the} selected frame'': it's the frame that belongs to -the terminal from which the most recent input came. That is, when Emacs -runs a command that came from a certain terminal, the selected frame is -the one of that terminal. Since Emacs runs only a single command at any -given time, it needs to consider only one selected frame at a time; this -frame is what we call @dfn{the selected frame} in this manual. The -display on which the selected frame is displayed is the @dfn{selected -frame's display}. - -@defun selected-frame -This function returns the selected frame. -@end defun - -Some window systems and window managers direct keyboard input to the -window object that the mouse is in; others require explicit clicks or -commands to @dfn{shift the focus} to various window objects. Either -way, Emacs automatically keeps track of which frame has the focus. To -switch to a different frame from a Lisp function, call -@code{select-frame-set-input-focus}. - -Lisp programs can also switch frames ``temporarily'' by calling the -function @code{select-frame}. This does not alter the window system's -concept of focus; rather, it escapes from the window manager's control -until that control is somehow reasserted. - -When using a text-only terminal, only one frame can be displayed at a -time on the terminal, so after a call to @code{select-frame}, the next -redisplay actually displays the newly selected frame. This frame -remains selected until a subsequent call to @code{select-frame} or -@code{select-frame-set-input-focus}. Each terminal frame has a number -which appears in the mode line before the buffer name (@pxref{Mode -Line Variables}). - -@defun select-frame-set-input-focus frame -This function makes @var{frame} the selected frame, raises it (should -it happen to be obscured by other frames) and tries to give it the X -server's focus. On a text-only terminal, the next redisplay displays -the new frame on the entire terminal screen. The return value of this -function is not significant. -@end defun - -@c ??? This is not yet implemented properly. -@defun select-frame frame -This function selects frame @var{frame}, temporarily disregarding the -focus of the X server if any. The selection of @var{frame} lasts until -the next time the user does something to select a different frame, or -until the next time this function is called. (If you are using a -window system, the previously selected frame may be restored as the -selected frame after return to the command loop, because it still may -have the window system's input focus.) The specified @var{frame} -becomes the selected frame, as explained above, and the terminal that -@var{frame} is on becomes the selected terminal. This function -returns @var{frame}, or @code{nil} if @var{frame} has been deleted. - -In general, you should never use @code{select-frame} in a way that could -switch to a different terminal without switching back when you're done. -@end defun - -Emacs cooperates with the window system by arranging to select frames as -the server and window manager request. It does so by generating a -special kind of input event, called a @dfn{focus} event, when -appropriate. The command loop handles a focus event by calling -@code{handle-switch-frame}. @xref{Focus Events}. - -@deffn Command handle-switch-frame frame -This function handles a focus event by selecting frame @var{frame}. - -Focus events normally do their job by invoking this command. -Don't call it for any other reason. -@end deffn - -@defun redirect-frame-focus frame &optional focus-frame -This function redirects focus from @var{frame} to @var{focus-frame}. -This means that @var{focus-frame} will receive subsequent keystrokes and -events intended for @var{frame}. After such an event, the value of -@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame -events specifying @var{frame} will instead select @var{focus-frame}. - -If @var{focus-frame} is omitted or @code{nil}, that cancels any existing -redirection for @var{frame}, which therefore once again receives its own -events. - -One use of focus redirection is for frames that don't have minibuffers. -These frames use minibuffers on other frames. Activating a minibuffer -on another frame redirects focus to that frame. This puts the focus on -the minibuffer's frame, where it belongs, even though the mouse remains -in the frame that activated the minibuffer. - -Selecting a frame can also change focus redirections. Selecting frame -@code{bar}, when @code{foo} had been selected, changes any redirections -pointing to @code{foo} so that they point to @code{bar} instead. This -allows focus redirection to work properly when the user switches from -one frame to another using @code{select-window}. - -This means that a frame whose focus is redirected to itself is treated -differently from a frame whose focus is not redirected. -@code{select-frame} affects the former but not the latter. - -The redirection lasts until @code{redirect-frame-focus} is called to -change it. -@end defun - -@defopt focus-follows-mouse -This option is how you inform Emacs whether the window manager transfers -focus when the user moves the mouse. Non-@code{nil} says that it does. -When this is so, the command @code{other-frame} moves the mouse to a -position consistent with the new selected frame. (This option has no -effect on MS-Windows, where the mouse pointer is always automatically -moved by the OS to the selected frame.) -@end defopt - -@node Visibility of Frames -@section Visibility of Frames -@cindex visible frame -@cindex invisible frame -@cindex iconified frame -@cindex frame visibility - -A window frame may be @dfn{visible}, @dfn{invisible}, or -@dfn{iconified}. If it is visible, you can see its contents, unless -other windows cover it. If it is iconified, the frame's contents do -not appear on the screen, but an icon does. If the frame is -invisible, it doesn't show on the screen, not even as an icon. - -Visibility is meaningless for terminal frames, since only the selected -one is actually displayed in any case. - -@deffn Command make-frame-visible &optional frame -This function makes frame @var{frame} visible. If you omit -@var{frame}, it makes the selected frame visible. This does not raise -the frame, but you can do that with @code{raise-frame} if you wish -(@pxref{Raising and Lowering}). -@end deffn - -@deffn Command make-frame-invisible &optional frame force -This function makes frame @var{frame} invisible. If you omit -@var{frame}, it makes the selected frame invisible. - -Unless @var{force} is non-@code{nil}, this function refuses to make -@var{frame} invisible if all other frames are invisible.. -@end deffn - -@deffn Command iconify-frame &optional frame -This function iconifies frame @var{frame}. If you omit @var{frame}, it -iconifies the selected frame. -@end deffn - -@defun frame-visible-p frame -This returns the visibility status of frame @var{frame}. The value is -@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and -@code{icon} if it is iconified. - -On a text-only terminal, all frames are considered visible, whether -they are currently being displayed or not, and this function returns -@code{t} for all frames. -@end defun - - The visibility status of a frame is also available as a frame -parameter. You can read or change it as such. @xref{Management -Parameters}. - - The user can iconify and deiconify frames with the window manager. -This happens below the level at which Emacs can exert any control, but -Emacs does provide events that you can use to keep track of such -changes. @xref{Misc Events}. - -@node Raising and Lowering -@section Raising and Lowering Frames - - Most window systems use a desktop metaphor. Part of this metaphor is -the idea that windows are stacked in a notional third dimension -perpendicular to the screen surface, and thus ordered from ``highest'' -to ``lowest.'' Where two windows overlap, the one higher up covers -the one underneath. Even a window at the bottom of the stack can be -seen if no other window overlaps it. - -@c @cindex raising a frame redundant with raise-frame -@cindex lowering a frame - A window's place in this ordering is not fixed; in fact, users tend -to change the order frequently. @dfn{Raising} a window means moving -it ``up,'' to the top of the stack. @dfn{Lowering} a window means -moving it to the bottom of the stack. This motion is in the notional -third dimension only, and does not change the position of the window -on the screen. - - You can raise and lower Emacs frame Windows with these functions: - -@deffn Command raise-frame &optional frame -This function raises frame @var{frame} (default, the selected frame). -If @var{frame} is invisible or iconified, this makes it visible. -@end deffn - -@deffn Command lower-frame &optional frame -This function lowers frame @var{frame} (default, the selected frame). -@end deffn - -@defopt minibuffer-auto-raise -If this is non-@code{nil}, activation of the minibuffer raises the frame -that the minibuffer window is in. -@end defopt - -You can also enable auto-raise (raising automatically when a frame is -selected) or auto-lower (lowering automatically when it is deselected) -for any frame using frame parameters. @xref{Management Parameters}. - -@node Frame Configurations -@section Frame Configurations -@cindex frame configuration - - A @dfn{frame configuration} records the current arrangement of frames, -all their properties, and the window configuration of each one. -(@xref{Window Configurations}.) - -@defun current-frame-configuration -This function returns a frame configuration list that describes -the current arrangement of frames and their contents. -@end defun - -@defun set-frame-configuration configuration &optional nodelete -This function restores the state of frames described in -@var{configuration}. However, this function does not restore deleted -frames. - -Ordinarily, this function deletes all existing frames not listed in -@var{configuration}. But if @var{nodelete} is non-@code{nil}, the -unwanted frames are iconified instead. -@end defun - -@node Mouse Tracking -@section Mouse Tracking -@cindex mouse tracking -@c @cindex tracking the mouse Duplicates track-mouse - - Sometimes it is useful to @dfn{track} the mouse, which means to display -something to indicate where the mouse is and move the indicator as the -mouse moves. For efficient mouse tracking, you need a way to wait until -the mouse actually moves. - - The convenient way to track the mouse is to ask for events to represent -mouse motion. Then you can wait for motion by waiting for an event. In -addition, you can easily handle any other sorts of events that may -occur. That is useful, because normally you don't want to track the -mouse forever---only until some other event, such as the release of a -button. - -@defspec track-mouse body@dots{} -This special form executes @var{body}, with generation of mouse motion -events enabled. Typically @var{body} would use @code{read-event} to -read the motion events and modify the display accordingly. @xref{Motion -Events}, for the format of mouse motion events. - -The value of @code{track-mouse} is that of the last form in @var{body}. -You should design @var{body} to return when it sees the up-event that -indicates the release of the button, or whatever kind of event means -it is time to stop tracking. -@end defspec - -The usual purpose of tracking mouse motion is to indicate on the screen -the consequences of pushing or releasing a button at the current -position. - -In many cases, you can avoid the need to track the mouse by using -the @code{mouse-face} text property (@pxref{Special Properties}). -That works at a much lower level and runs more smoothly than -Lisp-level mouse tracking. - -@ignore -@c These are not implemented yet. - -These functions change the screen appearance instantaneously. The -effect is transient, only until the next ordinary Emacs redisplay. That -is OK for mouse tracking, since it doesn't make sense for mouse tracking -to change the text, and the body of @code{track-mouse} normally reads -the events itself and does not do redisplay. - -@defun x-contour-region window beg end -This function draws lines to make a box around the text from @var{beg} -to @var{end}, in window @var{window}. -@end defun - -@defun x-uncontour-region window beg end -This function erases the lines that would make a box around the text -from @var{beg} to @var{end}, in window @var{window}. Use it to remove -a contour that you previously made by calling @code{x-contour-region}. -@end defun - -@defun x-draw-rectangle frame left top right bottom -This function draws a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. It uses the cursor color, the one used for indicating the -location of point. -@end defun - -@defun x-erase-rectangle frame left top right bottom -This function erases a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. Erasure means redrawing the text and background that -normally belong in the specified rectangle. -@end defun -@end ignore - -@node Mouse Position -@section Mouse Position -@cindex mouse position -@cindex position of mouse - - The functions @code{mouse-position} and @code{set-mouse-position} -give access to the current position of the mouse. - -@defun mouse-position -This function returns a description of the position of the mouse. The -value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} -and @var{y} are integers giving the position in characters relative to -the top left corner of the inside of @var{frame}. -@end defun - -@defvar mouse-position-function -If non-@code{nil}, the value of this variable is a function for -@code{mouse-position} to call. @code{mouse-position} calls this -function just before returning, with its normal return value as the -sole argument, and it returns whatever this function returns to it. - -This abnormal hook exists for the benefit of packages like -@file{xt-mouse.el} that need to do mouse handling at the Lisp level. -@end defvar - -@defun set-mouse-position frame x y -This function @dfn{warps the mouse} to position @var{x}, @var{y} in -frame @var{frame}. The arguments @var{x} and @var{y} are integers, -giving the position in characters relative to the top left corner of the -inside of @var{frame}. If @var{frame} is not visible, this function -does nothing. The return value is not significant. -@end defun - -@defun mouse-pixel-position -This function is like @code{mouse-position} except that it returns -coordinates in units of pixels rather than units of characters. -@end defun - -@defun set-mouse-pixel-position frame x y -This function warps the mouse like @code{set-mouse-position} except that -@var{x} and @var{y} are in units of pixels rather than units of -characters. These coordinates are not required to be within the frame. - -If @var{frame} is not visible, this function does nothing. The return -value is not significant. -@end defun - -@need 3000 - -@node Pop-Up Menus -@section Pop-Up Menus - - When using a window system, a Lisp program can pop up a menu so that -the user can choose an alternative with the mouse. - -@defun x-popup-menu position menu -This function displays a pop-up menu and returns an indication of -what selection the user makes. - -The argument @var{position} specifies where on the screen to put the -top left corner of the menu. It can be either a mouse button event -(which says to put the menu where the user actuated the button) or a -list of this form: - -@example -((@var{xoffset} @var{yoffset}) @var{window}) -@end example - -@noindent -where @var{xoffset} and @var{yoffset} are coordinates, measured in -pixels, counting from the top left corner of @var{window}. @var{window} -may be a window or a frame. - -If @var{position} is @code{t}, it means to use the current mouse -position. If @var{position} is @code{nil}, it means to precompute the -key binding equivalents for the keymaps specified in @var{menu}, -without actually displaying or popping up the menu. - -The argument @var{menu} says what to display in the menu. It can be a -keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the -return value is the list of events corresponding to the user's choice. -(This list has more than one element if the choice occurred in a -submenu.) Note that @code{x-popup-menu} does not actually execute the -command bound to that sequence of events. - -Alternatively, @var{menu} can have the following form: - -@example -(@var{title} @var{pane1} @var{pane2}...) -@end example - -@noindent -where each pane is a list of form - -@example -(@var{title} @var{item1} @var{item2}...) -@end example - -Each item should normally be a cons cell @code{(@var{line} . @var{value})}, -where @var{line} is a string, and @var{value} is the value to return if -that @var{line} is chosen. An item can also be a string; this makes a -non-selectable line in the menu. - -If the user gets rid of the menu without making a valid choice, for -instance by clicking the mouse away from a valid choice or by typing -keyboard input, then this normally results in a quit and -@code{x-popup-menu} does not return. But if @var{position} is a mouse -button event (indicating that the user invoked the menu with the -mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}. -@end defun - - @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu -if you could do the job with a prefix key defined with a menu keymap. -If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h -a} can see the individual items in that menu and provide help for them. -If instead you implement the menu by defining a command that calls -@code{x-popup-menu}, the help facilities cannot know what happens inside -that command, so they cannot give any help for the menu's items. - - The menu bar mechanism, which lets you switch between submenus by -moving the mouse, cannot look within the definition of a command to see -that it calls @code{x-popup-menu}. Therefore, if you try to implement a -submenu using @code{x-popup-menu}, it cannot work with the menu bar in -an integrated fashion. This is why all menu bar submenus are -implemented with menu keymaps within the parent menu, and never with -@code{x-popup-menu}. @xref{Menu Bar}. - - If you want a menu bar submenu to have contents that vary, you should -still use a menu keymap to implement it. To make the contents vary, add -a hook function to @code{menu-bar-update-hook} to update the contents of -the menu keymap as necessary. - -@node Dialog Boxes -@section Dialog Boxes -@cindex dialog boxes - - A dialog box is a variant of a pop-up menu---it looks a little -different, it always appears in the center of a frame, and it has just -one level and one or more buttons. The main use of dialog boxes is -for asking questions that the user can answer with ``yes,'' ``no,'' -and a few other alternatives. With a single button, they can also -force the user to acknowledge important information. The functions -@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the -keyboard, when called from commands invoked by mouse clicks. - -@defun x-popup-dialog position contents &optional header -This function displays a pop-up dialog box and returns an indication of -what selection the user makes. The argument @var{contents} specifies -the alternatives to offer; it has this format: - -@example -(@var{title} (@var{string} . @var{value})@dots{}) -@end example - -@noindent -which looks like the list that specifies a single pane for -@code{x-popup-menu}. - -The return value is @var{value} from the chosen alternative. - -As for @code{x-popup-menu}, an element of the list may be just a -string instead of a cons cell @code{(@var{string} . @var{value})}. -That makes a box that cannot be selected. - -If @code{nil} appears in the list, it separates the left-hand items from -the right-hand items; items that precede the @code{nil} appear on the -left, and items that follow the @code{nil} appear on the right. If you -don't include a @code{nil} in the list, then approximately half the -items appear on each side. - -Dialog boxes always appear in the center of a frame; the argument -@var{position} specifies which frame. The possible values are as in -@code{x-popup-menu}, but the precise coordinates or the individual -window don't matter; only the frame matters. - -If @var{header} is non-@code{nil}, the frame title for the box is -@samp{Information}, otherwise it is @samp{Question}. The former is used -for @code{message-box} (@pxref{message-box}). - -In some configurations, Emacs cannot display a real dialog box; so -instead it displays the same items in a pop-up menu in the center of the -frame. - -If the user gets rid of the dialog box without making a valid choice, -for instance using the window manager, then this produces a quit and -@code{x-popup-dialog} does not return. -@end defun - -@node Pointer Shape -@section Pointer Shape -@cindex pointer shape -@cindex mouse pointer shape - - You can specify the mouse pointer style for particular text or -images using the @code{pointer} text property, and for images with the -@code{:pointer} and @code{:map} image properties. The values you can -use in these properties are @code{text} (or @code{nil}), @code{arrow}, -@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and -@code{hourglass}. @code{text} stands for the usual mouse pointer -style used over text. - - Over void parts of the window (parts that do not correspond to any -of the buffer contents), the mouse pointer usually uses the -@code{arrow} style, but you can specify a different style (one of -those above) by setting @code{void-text-area-pointer}. - -@defvar void-text-area-pointer -This variable specifies the mouse pointer style for void text areas. -These include the areas after the end of a line or below the last line -in the buffer. The default is to use the @code{arrow} (non-text) -pointer style. -@end defvar - - You can specify what the @code{text} pointer style really looks like -by setting the variable @code{x-pointer-shape}. - -@defvar x-pointer-shape -This variable specifies the pointer shape to use ordinarily in the -Emacs frame, for the @code{text} pointer style. -@end defvar - -@defvar x-sensitive-text-pointer-shape -This variable specifies the pointer shape to use when the mouse -is over mouse-sensitive text. -@end defvar - - These variables affect newly created frames. They do not normally -affect existing frames; however, if you set the mouse color of a -frame, that also installs the current value of those two variables. -@xref{Color Parameters}. - - The values you can use, to specify either of these pointer shapes, are -defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos -@key{RET} x-pointer @key{RET}} to see a list of them. - -@node Window System Selections -@section Window System Selections -@cindex selection (for window systems) - -The X server records a set of @dfn{selections} which permit transfer of -data between application programs. The various selections are -distinguished by @dfn{selection types}, represented in Emacs by -symbols. X clients including Emacs can read or set the selection for -any given type. - -@deffn Command x-set-selection type data -This function sets a ``selection'' in the X server. It takes two -arguments: a selection type @var{type}, and the value to assign to it, -@var{data}. If @var{data} is @code{nil}, it means to clear out the -selection. Otherwise, @var{data} may be a string, a symbol, an integer -(or a cons of two integers or list of two integers), an overlay, or a -cons of two markers pointing to the same buffer. An overlay or a pair -of markers stands for text in the overlay or between the markers. - -The argument @var{data} may also be a vector of valid non-vector -selection values. - -Each possible @var{type} has its own selection value, which changes -independently. The usual values of @var{type} are @code{PRIMARY}, -@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case -names, in accord with X Window System conventions. If @var{type} is -@code{nil}, that stands for @code{PRIMARY}. - -This function returns @var{data}. -@end deffn - -@defun x-get-selection &optional type data-type -This function accesses selections set up by Emacs or by other X -clients. It takes two optional arguments, @var{type} and -@var{data-type}. The default for @var{type}, the selection type, is -@code{PRIMARY}. - -The @var{data-type} argument specifies the form of data conversion to -use, to convert the raw data obtained from another X client into Lisp -data. Meaningful values include @code{TEXT}, @code{STRING}, -@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE}, -@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME}, -@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS}, -@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and -@code{INTEGER}. (These are symbols with upper-case names in accord -with X conventions.) The default for @var{data-type} is -@code{STRING}. -@end defun - -@cindex cut buffer -The X server also has a set of eight numbered @dfn{cut buffers} which can -store text or other data being moved between applications. Cut buffers -are considered obsolete, but Emacs supports them for the sake of X -clients that still use them. Cut buffers are numbered from 0 to 7. - -@defun x-get-cut-buffer &optional n -This function returns the contents of cut buffer number @var{n}. -If omitted @var{n} defaults to 0. -@end defun - -@defun x-set-cut-buffer string &optional push -@anchor{Definition of x-set-cut-buffer} -This function stores @var{string} into the first cut buffer (cut buffer -0). If @var{push} is @code{nil}, only the first cut buffer is changed. -If @var{push} is non-@code{nil}, that says to move the values down -through the series of cut buffers, much like the way successive kills in -Emacs move down the kill ring. In other words, the previous value of -the first cut buffer moves into the second cut buffer, and the second to -the third, and so on through all eight cut buffers. -@end defun - -@defvar selection-coding-system -This variable specifies the coding system to use when reading and -writing selections or the clipboard. @xref{Coding -Systems}. The default is @code{compound-text-with-extensions}, which -converts to the text representation that X11 normally uses. -@end defvar - -@cindex clipboard support (for MS-Windows) -When Emacs runs on MS-Windows, it does not implement X selections in -general, but it does support the clipboard. @code{x-get-selection} -and @code{x-set-selection} on MS-Windows support the text data type -only; if the clipboard holds other types of data, Emacs treats the -clipboard as empty. - -@cindex scrap support (for Mac OS) -On Mac OS, selection-like data transfer between applications is -performed through a mechanism called @dfn{scraps}. The clipboard is a -particular scrap named @code{com.apple.scrap.clipboard}. Types of scrap -data are called @dfn{scrap flavor types}, which are identified by -four-char codes such as @code{TEXT}. Emacs associates a selection with -a scrap, and a selection type with a scrap flavor type via -@code{mac-scrap-name} and @code{mac-ostype} properties, respectively. - -@example -(get 'CLIPBOARD 'mac-scrap-name) - @result{} "com.apple.scrap.clipboard" -(get 'com.apple.traditional-mac-plain-text 'mac-ostype) - @result{} "TEXT" -@end example - -Conventionally, selection types for scrap flavor types on Mac OS have -the form of @acronym{UTI, Uniform Type Identifier} such as -@code{com.apple.traditional-mac-plain-text}, -@code{public.utf16-plain-text}, and @code{public.file-url}. - -@defopt x-select-enable-clipboard -If this is non-@code{nil}, the Emacs yank functions consult the -clipboard before the primary selection, and the kill functions store in -the clipboard as well as the primary selection. Otherwise they do not -access the clipboard at all. The default is @code{nil} on most systems, -but @code{t} on MS-Windows and Mac. -@end defopt - -@node Drag and Drop -@section Drag and Drop - -@vindex x-dnd-test-function -@vindex x-dnd-known-types - When a user drags something from another application over Emacs, that other -application expects Emacs to tell it if Emacs can handle the data that is -dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine -what to reply. The default value is @code{x-dnd-default-test-function} -which accepts drops if the type of the data to be dropped is present in -@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or -@code{x-dnd-known-types} if you want Emacs to accept or reject drops based -on some other criteria. - -@vindex x-dnd-types-alist - If you want to change the way Emacs handles drop of different types -or add a new type, customize @code{x-dnd-types-alist}. This requires -detailed knowledge of what types other applications use for drag and -drop. - -@vindex dnd-protocol-alist - When an URL is dropped on Emacs it may be a file, but it may also be -another URL type (ftp, http, etc.). Emacs first checks -@code{dnd-protocol-alist} to determine what to do with the URL. If -there is no match there and if @code{browse-url-browser-function} is -an alist, Emacs looks for a match there. If no match is found the -text for the URL is inserted. If you want to alter Emacs behavior, -you can customize these variables. - -@node Color Names -@section Color Names - -@cindex color names -@cindex specify color -@cindex numerical RGB color specification - A color name is text (usually in a string) that specifies a color. -Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc., -are allowed; use @kbd{M-x list-colors-display} to see a list of -defined names. You can also specify colors numerically in forms such -as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where -@var{r} specifies the red level, @var{g} specifies the green level, -and @var{b} specifies the blue level. You can use either one, two, -three, or four hex digits for @var{r}; then you must use the same -number of hex digits for all @var{g} and @var{b} as well, making -either 3, 6, 9 or 12 hex digits in all. (See the documentation of the -X Window System for more details about numerical RGB specification of -colors.) - - These functions provide a way to determine which color names are -valid, and what they look like. In some cases, the value depends on the -@dfn{selected frame}, as described below; see @ref{Input Focus}, for the -meaning of the term ``selected frame.'' - -@defun color-defined-p color &optional frame -This function reports whether a color name is meaningful. It returns -@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says -which frame's display to ask about; if @var{frame} is omitted or -@code{nil}, the selected frame is used. - -Note that this does not tell you whether the display you are using -really supports that color. When using X, you can ask for any defined -color on any kind of display, and you will get some result---typically, -the closest it can do. To determine whether a frame can really display -a certain color, use @code{color-supported-p} (see below). - -@findex x-color-defined-p -This function used to be called @code{x-color-defined-p}, -and that name is still supported as an alias. -@end defun - -@defun defined-colors &optional frame -This function returns a list of the color names that are defined -and supported on frame @var{frame} (default, the selected frame). -If @var{frame} does not support colors, the value is @code{nil}. - -@findex x-defined-colors -This function used to be called @code{x-defined-colors}, -and that name is still supported as an alias. -@end defun - -@defun color-supported-p color &optional frame background-p -This returns @code{t} if @var{frame} can really display the color -@var{color} (or at least something close to it). If @var{frame} is -omitted or @code{nil}, the question applies to the selected frame. - -Some terminals support a different set of colors for foreground and -background. If @var{background-p} is non-@code{nil}, that means you are -asking whether @var{color} can be used as a background; otherwise you -are asking whether it can be used as a foreground. - -The argument @var{color} must be a valid color name. -@end defun - -@defun color-gray-p color &optional frame -This returns @code{t} if @var{color} is a shade of gray, as defined on -@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the -question applies to the selected frame. If @var{color} is not a valid -color name, this function returns @code{nil}. -@end defun - -@defun color-values color &optional frame -@cindex rgb value -This function returns a value that describes what @var{color} should -ideally look like on @var{frame}. If @var{color} is defined, the -value is a list of three integers, which give the amount of red, the -amount of green, and the amount of blue. Each integer ranges in -principle from 0 to 65535, but some displays may not use the full -range. This three-element list is called the @dfn{rgb values} of the -color. - -If @var{color} is not defined, the value is @code{nil}. - -@example -(color-values "black") - @result{} (0 0 0) -(color-values "white") - @result{} (65280 65280 65280) -(color-values "red") - @result{} (65280 0 0) -(color-values "pink") - @result{} (65280 49152 51968) -(color-values "hungry") - @result{} nil -@end example - -The color values are returned for @var{frame}'s display. If -@var{frame} is omitted or @code{nil}, the information is returned for -the selected frame's display. If the frame cannot display colors, the -value is @code{nil}. - -@findex x-color-values -This function used to be called @code{x-color-values}, -and that name is still supported as an alias. -@end defun - -@node Text Terminal Colors -@section Text Terminal Colors -@cindex colors on text-only terminals - - Text-only terminals usually support only a small number of colors, -and the computer uses small integers to select colors on the terminal. -This means that the computer cannot reliably tell what the selected -color looks like; instead, you have to inform your application which -small integers correspond to which colors. However, Emacs does know -the standard set of colors and will try to use them automatically. - - The functions described in this section control how terminal colors -are used by Emacs. - - Several of these functions use or return @dfn{rgb values}, described -in @ref{Color Names}. - - These functions accept a display (either a frame or the name of a -terminal) as an optional argument. We hope in the future to make Emacs -support more than one text-only terminal at one time; then this argument -will specify which terminal to operate on (the default being the -selected frame's terminal; @pxref{Input Focus}). At present, though, -the @var{frame} argument has no effect. - -@defun tty-color-define name number &optional rgb frame -This function associates the color name @var{name} with -color number @var{number} on the terminal. - -The optional argument @var{rgb}, if specified, is an rgb value, a list -of three numbers that specify what the color actually looks like. -If you do not specify @var{rgb}, then this color cannot be used by -@code{tty-color-approximate} to approximate other colors, because -Emacs will not know what it looks like. -@end defun - -@defun tty-color-clear &optional frame -This function clears the table of defined colors for a text-only terminal. -@end defun - -@defun tty-color-alist &optional frame -This function returns an alist recording the known colors supported by a -text-only terminal. - -Each element has the form @code{(@var{name} @var{number} . @var{rgb})} -or @code{(@var{name} @var{number})}. Here, @var{name} is the color -name, @var{number} is the number used to specify it to the terminal. -If present, @var{rgb} is a list of three color values (for red, green, -and blue) that says what the color actually looks like. -@end defun - -@defun tty-color-approximate rgb &optional frame -This function finds the closest color, among the known colors -supported for @var{display}, to that described by the rgb value -@var{rgb} (a list of color values). The return value is an element of -@code{tty-color-alist}. -@end defun - -@defun tty-color-translate color &optional frame -This function finds the closest color to @var{color} among the known -colors supported for @var{display} and returns its index (an integer). -If the name @var{color} is not defined, the value is @code{nil}. -@end defun - -@node Resources -@section X Resources - -@defun x-get-resource attribute class &optional component subclass -The function @code{x-get-resource} retrieves a resource value from the X -Window defaults database. - -Resources are indexed by a combination of a @dfn{key} and a @dfn{class}. -This function searches using a key of the form -@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name -under which Emacs was invoked), and using @samp{Emacs.@var{class}} as -the class. - -The optional arguments @var{component} and @var{subclass} add to the key -and the class, respectively. You must specify both of them or neither. -If you specify them, the key is -@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is -@samp{Emacs.@var{class}.@var{subclass}}. -@end defun - -@defvar x-resource-class -This variable specifies the application name that @code{x-get-resource} -should look up. The default value is @code{"Emacs"}. You can examine X -resources for application names other than ``Emacs'' by binding this -variable to some other string, around a call to @code{x-get-resource}. -@end defvar - -@defvar x-resource-name -This variable specifies the instance name that @code{x-get-resource} -should look up. The default value is the name Emacs was invoked with, -or the value specified with the @samp{-name} or @samp{-rn} switches. -@end defvar - -To illustrate some of the above, suppose that you have the line: - -@example -xterm.vt100.background: yellow -@end example - -@noindent -in your X resources file (whose name is usually @file{~/.Xdefaults} -or @file{~/.Xresources}). Then: - -@example -@group -(let ((x-resource-class "XTerm") (x-resource-name "xterm")) - (x-get-resource "vt100.background" "VT100.Background")) - @result{} "yellow" -@end group -@group -(let ((x-resource-class "XTerm") (x-resource-name "xterm")) - (x-get-resource "background" "VT100" "vt100" "Background")) - @result{} "yellow" -@end group -@end example - - @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. - -@node Display Feature Testing -@section Display Feature Testing -@cindex display feature testing - - The functions in this section describe the basic capabilities of a -particular display. Lisp programs can use them to adapt their behavior -to what the display can do. For example, a program that ordinarily uses -a popup menu could use the minibuffer if popup menus are not supported. - - The optional argument @var{display} in these functions specifies which -display to ask the question about. It can be a display name, a frame -(which designates the display that frame is on), or @code{nil} (which -refers to the selected frame's display, @pxref{Input Focus}). - - @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to -obtain information about displays. - -@defun display-popup-menus-p &optional display -This function returns @code{t} if popup menus are supported on -@var{display}, @code{nil} if not. Support for popup menus requires that -the mouse be available, since the user cannot choose menu items without -a mouse. -@end defun - -@defun display-graphic-p &optional display -This function returns @code{t} if @var{display} is a graphic display -capable of displaying several frames and several different fonts at -once. This is true for displays that use a window system such as X, and -false for text-only terminals. -@end defun - -@defun display-mouse-p &optional display -@cindex mouse, availability -This function returns @code{t} if @var{display} has a mouse available, -@code{nil} if not. -@end defun - -@defun display-color-p &optional display -@findex x-display-color-p -This function returns @code{t} if the screen is a color screen. -It used to be called @code{x-display-color-p}, and that name -is still supported as an alias. -@end defun - -@defun display-grayscale-p &optional display -This function returns @code{t} if the screen can display shades of gray. -(All color displays can do this.) -@end defun - -@defun display-supports-face-attributes-p attributes &optional display -@anchor{Display Face Attribute Testing} -This function returns non-@code{nil} if all the face attributes in -@var{attributes} are supported (@pxref{Face Attributes}). - -The definition of `supported' is somewhat heuristic, but basically -means that a face containing all the attributes in @var{attributes}, -when merged with the default face for display, can be represented in a -way that's - -@enumerate -@item -different in appearance than the default face, and - -@item -`close in spirit' to what the attributes specify, if not exact. -@end enumerate - -Point (2) implies that a @code{:weight black} attribute will be -satisfied by any display that can display bold, as will -@code{:foreground "yellow"} as long as some yellowish color can be -displayed, but @code{:slant italic} will @emph{not} be satisfied by -the tty display code's automatic substitution of a `dim' face for -italic. -@end defun - -@defun display-selections-p &optional display -This function returns @code{t} if @var{display} supports selections. -Windowed displays normally support selections, but they may also be -supported in some other cases. -@end defun - -@defun display-images-p &optional display -This function returns @code{t} if @var{display} can display images. -Windowed displays ought in principle to handle images, but some -systems lack the support for that. On a display that does not support -images, Emacs cannot display a tool bar. -@end defun - -@defun display-screens &optional display -This function returns the number of screens associated with the display. -@end defun - -@defun display-pixel-height &optional display -This function returns the height of the screen in pixels. -On a character terminal, it gives the height in characters. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the pixel width for all physical monitors associated with -@var{display}. @xref{Multiple Displays}. -@end defun - -@defun display-pixel-width &optional display -This function returns the width of the screen in pixels. -On a character terminal, it gives the width in characters. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the pixel width for all physical monitors associated with -@var{display}. @xref{Multiple Displays}. -@end defun - -@defun display-mm-height &optional display -This function returns the height of the screen in millimeters, -or @code{nil} if Emacs cannot get that information. -@end defun - -@defun display-mm-width &optional display -This function returns the width of the screen in millimeters, -or @code{nil} if Emacs cannot get that information. -@end defun - -@defvar display-mm-dimensions-alist -This variable allows the user to specify the dimensions of graphical -displays returned by @code{display-mm-height} and -@code{display-mm-width} in case the system provides incorrect values. -@end defvar - -@defun display-backing-store &optional display -This function returns the backing store capability of the display. -Backing store means recording the pixels of windows (and parts of -windows) that are not exposed, so that when exposed they can be -displayed very quickly. - -Values can be the symbols @code{always}, @code{when-mapped}, or -@code{not-useful}. The function can also return @code{nil} -when the question is inapplicable to a certain kind of display. -@end defun - -@defun display-save-under &optional display -This function returns non-@code{nil} if the display supports the -SaveUnder feature. That feature is used by pop-up windows -to save the pixels they obscure, so that they can pop down -quickly. -@end defun - -@defun display-planes &optional display -This function returns the number of planes the display supports. -This is typically the number of bits per pixel. -For a tty display, it is log to base two of the number of colors supported. -@end defun - -@defun display-visual-class &optional display -This function returns the visual class for the screen. The value is one -of the symbols @code{static-gray}, @code{gray-scale}, -@code{static-color}, @code{pseudo-color}, @code{true-color}, and -@code{direct-color}. -@end defun - -@defun display-color-cells &optional display -This function returns the number of color cells the screen supports. -@end defun - - These functions obtain additional information specifically -about X displays. - -@defun x-server-version &optional display -This function returns the list of version numbers of the X server -running the display. The value is a list of three integers: the major -and minor version numbers of the X protocol, and the -distributor-specific release number of the X server software itself. -@end defun - -@defun x-server-vendor &optional display -This function returns the ``vendor'' that provided the X server -software (as a string). Really this means whoever distributes the X -server. - -When the developers of X labelled software distributors as -``vendors,'' they showed their false assumption that no system could -ever be developed and distributed noncommercially. -@end defun - -@ignore -@defvar x-no-window-manager -This variable's value is @code{t} if no X window manager is in use. -@end defvar -@end ignore - -@ignore -@item -The functions @code{x-pixel-width} and @code{x-pixel-height} return the -width and height of an X Window frame, measured in pixels. -@end ignore - -@ignore - arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba -@end ignore diff --git a/lispref/front-cover-1.texi b/lispref/front-cover-1.texi deleted file mode 100644 index 5c9f4351f42..00000000000 --- a/lispref/front-cover-1.texi +++ /dev/null @@ -1,56 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename front1.info -@settitle GNU Emacs Lisp Reference Manual -@smallbook -@comment %**end of header - -@titlepage -. -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19.29 -@center for Unix Users -@center Edition 2.4, June 1995 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group -@page -. -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19.29 -@center for Unix Users -@center Edition 2.4, June 1995 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@end titlepage -@bye - -@ignore - arch-tag: 5182b306-c403-4e4f-ba24-e1911bc6da9d -@end ignore diff --git a/lispref/functions.texi b/lispref/functions.texi deleted file mode 100644 index eedfa8c124f..00000000000 --- a/lispref/functions.texi +++ /dev/null @@ -1,1374 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/functions -@node Functions, Macros, Variables, Top -@chapter Functions - - A Lisp program is composed mainly of Lisp functions. This chapter -explains what functions are, how they accept arguments, and how to -define them. - -@menu -* 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. -@end menu - -@node What Is a Function -@section What Is a Function? - - In a general sense, a function is a rule for carrying on a computation -given several values called @dfn{arguments}. The result of the -computation is called the value of the function. The computation can -also have side effects: lasting changes in the values of variables or -the contents of data structures. - - Here are important terms for functions in Emacs Lisp and for other -function-like objects. - -@table @dfn -@item function -@cindex function -In Emacs Lisp, a @dfn{function} is anything that can be applied to -arguments in a Lisp program. In some cases, we use it more -specifically to mean a function written in Lisp. Special forms and -macros are not functions. - -@item primitive -@cindex primitive -@cindex subr -@cindex built-in function -A @dfn{primitive} is a function callable from Lisp that is written in C, -such as @code{car} or @code{append}. These functions are also called -@dfn{built-in functions}, or @dfn{subrs}. (Special forms are also -considered primitives.) - -Usually the reason we implement a function as a primitive is either -because it is fundamental, because it provides a low-level interface -to operating system services, or because it needs to run fast. -Primitives can be modified or added only by changing the C sources and -recompiling the editor. See @ref{Writing Emacs Primitives}. - -@item lambda expression -A @dfn{lambda expression} is a function written in Lisp. -These are described in the following section. -@ifnottex -@xref{Lambda Expressions}. -@end ifnottex - -@item special form -A @dfn{special form} is a primitive that is like a function but does not -evaluate all of its arguments in the usual way. It may evaluate only -some of the arguments, or may evaluate them in an unusual order, or -several times. Many special forms are described in @ref{Control -Structures}. - -@item macro -@cindex macro -A @dfn{macro} is a construct defined in Lisp by the programmer. It -differs from a function in that it translates a Lisp expression that you -write into an equivalent expression to be evaluated instead of the -original expression. Macros enable Lisp programmers to do the sorts of -things that special forms can do. @xref{Macros}, for how to define and -use macros. - -@item command -@cindex command -A @dfn{command} is an object that @code{command-execute} can invoke; it -is a possible definition for a key sequence. Some functions are -commands; a function written in Lisp is a command if it contains an -interactive declaration (@pxref{Defining Commands}). Such a function -can be called from Lisp expressions like other functions; in this case, -the fact that the function is a command makes no difference. - -Keyboard macros (strings and vectors) are commands also, even though -they are not functions. A symbol is a command if its function -definition is a command; such symbols can be invoked with @kbd{M-x}. -The symbol is a function as well if the definition is a function. -@xref{Interactive Call}. - -@item keystroke command -@cindex keystroke command -A @dfn{keystroke command} is a command that is bound to a key sequence -(typically one to three keystrokes). The distinction is made here -merely to avoid confusion with the meaning of ``command'' in non-Emacs -editors; for Lisp programs, the distinction is normally unimportant. - -@item byte-code function -A @dfn{byte-code function} is a function that has been compiled by the -byte compiler. @xref{Byte-Code Type}. -@end table - -@defun functionp object -This function returns @code{t} if @var{object} is any kind of -function, or a special form, or, recursively, a symbol whose function -definition is a function or special form. (This does not include -macros.) -@end defun - -Unlike @code{functionp}, the next three functions do @emph{not} -treat a symbol as its function definition. - -@defun subrp object -This function returns @code{t} if @var{object} is a built-in function -(i.e., a Lisp primitive). - -@example -@group -(subrp 'message) ; @r{@code{message} is a symbol,} - @result{} nil ; @r{not a subr object.} -@end group -@group -(subrp (symbol-function 'message)) - @result{} t -@end group -@end example -@end defun - -@defun byte-code-function-p object -This function returns @code{t} if @var{object} is a byte-code -function. For example: - -@example -@group -(byte-code-function-p (symbol-function 'next-line)) - @result{} t -@end group -@end example -@end defun - -@defun subr-arity subr -This function provides information about the argument list of a -primitive, @var{subr}. The returned value is a pair -@code{(@var{min} . @var{max})}. @var{min} is the minimum number of -args. @var{max} is the maximum number or the symbol @code{many}, for a -function with @code{&rest} arguments, or the symbol @code{unevalled} if -@var{subr} is a special form. -@end defun - -@node Lambda Expressions -@section Lambda Expressions -@cindex lambda expression - - A function written in Lisp is a list that looks like this: - -@example -(lambda (@var{arg-variables}@dots{}) - @r{[}@var{documentation-string}@r{]} - @r{[}@var{interactive-declaration}@r{]} - @var{body-forms}@dots{}) -@end example - -@noindent -Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it -actually is valid as an expression---it evaluates to itself. In some -other Lisp dialects, a lambda expression is not a valid expression at -all. In either case, its main use is not to be evaluated as an -expression, but to be called as a function. - -@menu -* 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. -@end menu - -@node Lambda Components -@subsection Components of a Lambda Expression - -@ifnottex - - A function written in Lisp (a ``lambda expression'') is a list that -looks like this: - -@example -(lambda (@var{arg-variables}@dots{}) - [@var{documentation-string}] - [@var{interactive-declaration}] - @var{body-forms}@dots{}) -@end example -@end ifnottex - -@cindex lambda list - The first element of a lambda expression is always the symbol -@code{lambda}. This indicates that the list represents a function. The -reason functions are defined to start with @code{lambda} is so that -other lists, intended for other uses, will not accidentally be valid as -functions. - - The second element is a list of symbols---the argument variable names. -This is called the @dfn{lambda list}. When a Lisp function is called, -the argument values are matched up against the variables in the lambda -list, which are given local bindings with the values provided. -@xref{Local Variables}. - - The documentation string is a Lisp string object placed within the -function definition to describe the function for the Emacs help -facilities. @xref{Function Documentation}. - - The interactive declaration is a list of the form @code{(interactive -@var{code-string})}. This declares how to provide arguments if the -function is used interactively. Functions with this declaration are called -@dfn{commands}; they can be called using @kbd{M-x} or bound to a key. -Functions not intended to be called in this way should not have interactive -declarations. @xref{Defining Commands}, for how to write an interactive -declaration. - -@cindex body of function - The rest of the elements are the @dfn{body} of the function: the Lisp -code to do the work of the function (or, as a Lisp programmer would say, -``a list of Lisp forms to evaluate''). The value returned by the -function is the value returned by the last element of the body. - -@node Simple Lambda -@subsection A Simple Lambda-Expression Example - - Consider for example the following function: - -@example -(lambda (a b c) (+ a b c)) -@end example - -@noindent -We can call this function by writing it as the @sc{car} of an -expression, like this: - -@example -@group -((lambda (a b c) (+ a b c)) - 1 2 3) -@end group -@end example - -@noindent -This call evaluates the body of the lambda expression with the variable -@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3. -Evaluation of the body adds these three numbers, producing the result 6; -therefore, this call to the function returns the value 6. - - Note that the arguments can be the results of other function calls, as in -this example: - -@example -@group -((lambda (a b c) (+ a b c)) - 1 (* 2 3) (- 5 4)) -@end group -@end example - -@noindent -This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5 -4)} from left to right. Then it applies the lambda expression to the -argument values 1, 6 and 1 to produce the value 8. - - It is not often useful to write a lambda expression as the @sc{car} of -a form in this way. You can get the same result, of making local -variables and giving them values, using the special form @code{let} -(@pxref{Local Variables}). And @code{let} is clearer and easier to use. -In practice, lambda expressions are either stored as the function -definitions of symbols, to produce named functions, or passed as -arguments to other functions (@pxref{Anonymous Functions}). - - However, calls to explicit lambda expressions were very useful in the -old days of Lisp, before the special form @code{let} was invented. At -that time, they were the only way to bind and initialize local -variables. - -@node Argument List -@subsection Other Features of Argument Lists -@kindex wrong-number-of-arguments -@cindex argument binding -@cindex binding arguments -@cindex argument lists, features - - Our simple sample function, @code{(lambda (a b c) (+ a b c))}, -specifies three argument variables, so it must be called with three -arguments: if you try to call it with only two arguments or four -arguments, you get a @code{wrong-number-of-arguments} error. - - It is often convenient to write a function that allows certain -arguments to be omitted. For example, the function @code{substring} -accepts three arguments---a string, the start index and the end -index---but the third argument defaults to the @var{length} of the -string if you omit it. It is also convenient for certain functions to -accept an indefinite number of arguments, as the functions @code{list} -and @code{+} do. - -@cindex optional arguments -@cindex rest arguments -@kindex &optional -@kindex &rest - To specify optional arguments that may be omitted when a function -is called, simply include the keyword @code{&optional} before the optional -arguments. To specify a list of zero or more extra arguments, include the -keyword @code{&rest} before one final argument. - - Thus, the complete syntax for an argument list is as follows: - -@example -@group -(@var{required-vars}@dots{} - @r{[}&optional @var{optional-vars}@dots{}@r{]} - @r{[}&rest @var{rest-var}@r{]}) -@end group -@end example - -@noindent -The square brackets indicate that the @code{&optional} and @code{&rest} -clauses, and the variables that follow them, are optional. - - A call to the function requires one actual argument for each of the -@var{required-vars}. There may be actual arguments for zero or more of -the @var{optional-vars}, and there cannot be any actual arguments beyond -that unless the lambda list uses @code{&rest}. In that case, there may -be any number of extra actual arguments. - - If actual arguments for the optional and rest variables are omitted, -then they always default to @code{nil}. There is no way for the -function to distinguish between an explicit argument of @code{nil} and -an omitted argument. However, the body of the function is free to -consider @code{nil} an abbreviation for some other meaningful value. -This is what @code{substring} does; @code{nil} as the third argument to -@code{substring} means to use the length of the string supplied. - -@cindex CL note---default optional arg -@quotation -@b{Common Lisp note:} Common Lisp allows the function to specify what -default value to use when an optional argument is omitted; Emacs Lisp -always uses @code{nil}. Emacs Lisp does not support ``supplied-p'' -variables that tell you whether an argument was explicitly passed. -@end quotation - - For example, an argument list that looks like this: - -@example -(a b &optional c d &rest e) -@end example - -@noindent -binds @code{a} and @code{b} to the first two actual arguments, which are -required. If one or two more arguments are provided, @code{c} and -@code{d} are bound to them respectively; any arguments after the first -four are collected into a list and @code{e} is bound to that list. If -there are only two arguments, @code{c} is @code{nil}; if two or three -arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e} -is @code{nil}. - - There is no way to have required arguments following optional -ones---it would not make sense. To see why this must be so, suppose -that @code{c} in the example were optional and @code{d} were required. -Suppose three actual arguments are given; which variable would the -third argument be for? Would it be used for the @var{c}, or for -@var{d}? One can argue for both possibilities. Similarly, it makes -no sense to have any more arguments (either required or optional) -after a @code{&rest} argument. - - Here are some examples of argument lists and proper calls: - -@smallexample -((lambda (n) (1+ n)) ; @r{One required:} - 1) ; @r{requires exactly one argument.} - @result{} 2 -((lambda (n &optional n1) ; @r{One required and one optional:} - (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.} - 1 2) - @result{} 3 -((lambda (n &rest ns) ; @r{One required and one rest:} - (+ n (apply '+ ns))) ; @r{1 or more arguments.} - 1 2 3 4 5) - @result{} 15 -@end smallexample - -@node Function Documentation -@subsection Documentation Strings of Functions -@cindex documentation of function - - A lambda expression may optionally have a @dfn{documentation string} just -after the lambda list. This string does not affect execution of the -function; it is a kind of comment, but a systematized comment which -actually appears inside the Lisp world and can be used by the Emacs help -facilities. @xref{Documentation}, for how the @var{documentation-string} is -accessed. - - It is a good idea to provide documentation strings for all the -functions in your program, even those that are called only from within -your program. Documentation strings are like comments, except that they -are easier to access. - - The first line of the documentation string should stand on its own, -because @code{apropos} displays just this first line. It should consist -of one or two complete sentences that summarize the function's purpose. - - The start of the documentation string is usually indented in the -source file, but since these spaces come before the starting -double-quote, they are not part of the string. Some people make a -practice of indenting any additional lines of the string so that the -text lines up in the program source. @emph{That is a mistake.} The -indentation of the following lines is inside the string; what looks -nice in the source code will look ugly when displayed by the help -commands. - - You may wonder how the documentation string could be optional, since -there are required components of the function that follow it (the body). -Since evaluation of a string returns that string, without any side effects, -it has no effect if it is not the last form in the body. Thus, in -practice, there is no confusion between the first form of the body and the -documentation string; if the only body form is a string then it serves both -as the return value and as the documentation. - - The last line of the documentation string can specify calling -conventions different from the actual function arguments. Write -text like this: - -@example -\(fn @var{arglist}) -@end example - -@noindent -following a blank line, at the beginning of the line, with no newline -following it inside the documentation string. (The @samp{\} is used -to avoid confusing the Emacs motion commands.) The calling convention -specified in this way appears in help messages in place of the one -derived from the actual arguments of the function. - - This feature is particularly useful for macro definitions, since the -arguments written in a macro definition often do not correspond to the -way users think of the parts of the macro call. - -@node Function Names -@section Naming a Function -@cindex function definition -@cindex named function -@cindex function name - - In most computer languages, every function has a name; the idea of a -function without a name is nonsensical. In Lisp, a function in the -strictest sense has no name. It is simply a list whose first element is -@code{lambda}, a byte-code function object, or a primitive subr-object. - - However, a symbol can serve as the name of a function. This happens -when you put the function in the symbol's @dfn{function cell} -(@pxref{Symbol Components}). Then the symbol itself becomes a valid, -callable function, equivalent to the list or subr-object that its -function cell refers to. The contents of the function cell are also -called the symbol's @dfn{function definition}. The procedure of using a -symbol's function definition in place of the symbol is called -@dfn{symbol function indirection}; see @ref{Function Indirection}. - - In practice, nearly all functions are given names in this way and -referred to through their names. For example, the symbol @code{car} works -as a function and does what it does because the primitive subr-object -@code{#<subr car>} is stored in its function cell. - - We give functions names because it is convenient to refer to them by -their names in Lisp expressions. For primitive subr-objects such as -@code{#<subr car>}, names are the only way you can refer to them: there -is no read syntax for such objects. For functions written in Lisp, the -name is more convenient to use in a call than an explicit lambda -expression. Also, a function with a name can refer to itself---it can -be recursive. Writing the function's name in its own definition is much -more convenient than making the function definition point to itself -(something that is not impossible but that has various disadvantages in -practice). - - We often identify functions with the symbols used to name them. For -example, we often speak of ``the function @code{car},'' not -distinguishing between the symbol @code{car} and the primitive -subr-object that is its function definition. For most purposes, the -distinction is not important. - - Even so, keep in mind that a function need not have a unique name. While -a given function object @emph{usually} appears in the function cell of only -one symbol, this is just a matter of convenience. It is easy to store -it in several symbols using @code{fset}; then each of the symbols is -equally well a name for the same function. - - A symbol used as a function name may also be used as a variable; these -two uses of a symbol are independent and do not conflict. (Some Lisp -dialects, such as Scheme, do not distinguish between a symbol's value -and its function definition; a symbol's value as a variable is also its -function definition.) If you have not given a symbol a function -definition, you cannot use it as a function; whether the symbol has a -value as a variable makes no difference to this. - -@node Defining Functions -@section Defining Functions -@cindex defining a function - - We usually give a name to a function when it is first created. This -is called @dfn{defining a function}, and it is done with the -@code{defun} special form. - -@defspec defun name argument-list body-forms -@code{defun} is the usual way to define new Lisp functions. It -defines the symbol @var{name} as a function that looks like this: - -@example -(lambda @var{argument-list} . @var{body-forms}) -@end example - -@code{defun} stores this lambda expression in the function cell of -@var{name}. It returns the value @var{name}, but usually we ignore this -value. - -As described previously, @var{argument-list} is a list of argument -names and may include the keywords @code{&optional} and @code{&rest} -(@pxref{Lambda Expressions}). Also, the first two of the -@var{body-forms} may be a documentation string and an interactive -declaration. - -There is no conflict if the same symbol @var{name} is also used as a -variable, since the symbol's value cell is independent of the function -cell. @xref{Symbol Components}. - -Here are some examples: - -@example -@group -(defun foo () 5) - @result{} foo -@end group -@group -(foo) - @result{} 5 -@end group - -@group -(defun bar (a &optional b &rest c) - (list a b c)) - @result{} bar -@end group -@group -(bar 1 2 3 4 5) - @result{} (1 2 (3 4 5)) -@end group -@group -(bar 1) - @result{} (1 nil nil) -@end group -@group -(bar) -@error{} Wrong number of arguments. -@end group - -@group -(defun capitalize-backwards () - "Upcase the last letter of a word." - (interactive) - (backward-word 1) - (forward-word 1) - (backward-char 1) - (capitalize-word 1)) - @result{} capitalize-backwards -@end group -@end example - -Be careful not to redefine existing functions unintentionally. -@code{defun} redefines even primitive functions such as @code{car} -without any hesitation or notification. Redefining a function already -defined is often done deliberately, and there is no way to distinguish -deliberate redefinition from unintentional redefinition. -@end defspec - -@cindex function aliases -@defun defalias name definition &optional docstring -@anchor{Definition of defalias} -This special form defines the symbol @var{name} as a function, with -definition @var{definition} (which can be any valid Lisp function). -It returns @var{definition}. - -If @var{docstring} is non-@code{nil}, it becomes the function -documentation of @var{name}. Otherwise, any documentation provided by -@var{definition} is used. - -The proper place to use @code{defalias} is where a specific function -name is being defined---especially where that name appears explicitly in -the source file being loaded. This is because @code{defalias} records -which file defined the function, just like @code{defun} -(@pxref{Unloading}). - -By contrast, in programs that manipulate function definitions for other -purposes, it is better to use @code{fset}, which does not keep such -records. @xref{Function Cells}. -@end defun - - You cannot create a new primitive function with @code{defun} or -@code{defalias}, but you can use them to change the function definition of -any symbol, even one such as @code{car} or @code{x-popup-menu} whose -normal definition is a primitive. However, this is risky: for -instance, it is next to impossible to redefine @code{car} without -breaking Lisp completely. Redefining an obscure function such as -@code{x-popup-menu} is less dangerous, but it still may not work as -you expect. If there are calls to the primitive from C code, they -call the primitive's C definition directly, so changing the symbol's -definition will have no effect on them. - - See also @code{defsubst}, which defines a function like @code{defun} -and tells the Lisp compiler to open-code it. @xref{Inline Functions}. - -@node Calling Functions -@section Calling Functions -@cindex function invocation -@cindex calling a function - - Defining functions is only half the battle. Functions don't do -anything until you @dfn{call} them, i.e., tell them to run. Calling a -function is also known as @dfn{invocation}. - - The most common way of invoking a function is by evaluating a list. -For example, evaluating the list @code{(concat "a" "b")} calls the -function @code{concat} with arguments @code{"a"} and @code{"b"}. -@xref{Evaluation}, for a description of evaluation. - - When you write a list as an expression in your program, you specify -which function to call, and how many arguments to give it, in the text -of the program. Usually that's just what you want. Occasionally you -need to compute at run time which function to call. To do that, use -the function @code{funcall}. When you also need to determine at run -time how many arguments to pass, use @code{apply}. - -@defun funcall function &rest arguments -@code{funcall} calls @var{function} with @var{arguments}, and returns -whatever @var{function} returns. - -Since @code{funcall} is a function, all of its arguments, including -@var{function}, are evaluated before @code{funcall} is called. This -means that you can use any expression to obtain the function to be -called. It also means that @code{funcall} does not see the -expressions you write for the @var{arguments}, only their values. -These values are @emph{not} evaluated a second time in the act of -calling @var{function}; the operation of @code{funcall} is like the -normal procedure for calling a function, once its arguments have -already been evaluated. - -The argument @var{function} must be either a Lisp function or a -primitive function. Special forms and macros are not allowed, because -they make sense only when given the ``unevaluated'' argument -expressions. @code{funcall} cannot provide these because, as we saw -above, it never knows them in the first place. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(funcall f 'x 'y 'z) - @result{} (x y z) -@end group -@group -(funcall f 'x 'y '(z)) - @result{} (x y (z)) -@end group -@group -(funcall 'and t nil) -@error{} Invalid function: #<subr and> -@end group -@end example - -Compare these examples with the examples of @code{apply}. -@end defun - -@defun apply function &rest arguments -@code{apply} calls @var{function} with @var{arguments}, just like -@code{funcall} but with one difference: the last of @var{arguments} is a -list of objects, which are passed to @var{function} as separate -arguments, rather than a single list. We say that @code{apply} -@dfn{spreads} this list so that each individual element becomes an -argument. - -@code{apply} returns the result of calling @var{function}. As with -@code{funcall}, @var{function} must either be a Lisp function or a -primitive function; special forms and macros do not make sense in -@code{apply}. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(apply f 'x 'y 'z) -@error{} Wrong type argument: listp, z -@end group -@group -(apply '+ 1 2 '(3 4)) - @result{} 10 -@end group -@group -(apply '+ '(1 2 3 4)) - @result{} 10 -@end group - -@group -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end group -@end example - -For an interesting example of using @code{apply}, see @ref{Definition -of mapcar}. -@end defun - -@cindex functionals - It is common for Lisp functions to accept functions as arguments or -find them in data structures (especially in hook variables and property -lists) and call them using @code{funcall} or @code{apply}. Functions -that accept function arguments are often called @dfn{functionals}. - - Sometimes, when you call a functional, it is useful to supply a no-op -function as the argument. Here are two different kinds of no-op -function: - -@defun identity arg -This function returns @var{arg} and has no side effects. -@end defun - -@defun ignore &rest args -This function ignores any arguments and returns @code{nil}. -@end defun - -@node Mapping Functions -@section Mapping Functions -@cindex mapping functions - - A @dfn{mapping function} applies a given function (@emph{not} a -special form or macro) to each element of a list or other collection. -Emacs Lisp has several such functions; @code{mapcar} and -@code{mapconcat}, which scan a list, are described here. -@xref{Definition of mapatoms}, for the function @code{mapatoms} which -maps over the symbols in an obarray. @xref{Definition of maphash}, -for the function @code{maphash} which maps over key/value associations -in a hash table. - - These mapping functions do not allow char-tables because a char-table -is a sparse array whose nominal range of indices is very large. To map -over a char-table in a way that deals properly with its sparse nature, -use the function @code{map-char-table} (@pxref{Char-Tables}). - -@defun mapcar function sequence -@anchor{Definition of mapcar} -@code{mapcar} applies @var{function} to each element of @var{sequence} -in turn, and returns a list of the results. - -The argument @var{sequence} can be any kind of sequence except a -char-table; that is, a list, a vector, a bool-vector, or a string. The -result is always a list. The length of the result is the same as the -length of @var{sequence}. For example: - -@smallexample -@group -(mapcar 'car '((a b) (c d) (e f))) - @result{} (a c e) -(mapcar '1+ [1 2 3]) - @result{} (2 3 4) -(mapcar 'char-to-string "abc") - @result{} ("a" "b" "c") -@end group - -@group -;; @r{Call each function in @code{my-hooks}.} -(mapcar 'funcall my-hooks) -@end group - -@group -(defun mapcar* (function &rest args) - "Apply FUNCTION to successive cars of all ARGS. -Return the list of results." - ;; @r{If no list is exhausted,} - (if (not (memq nil args)) - ;; @r{apply function to @sc{car}s.} - (cons (apply function (mapcar 'car args)) - (apply 'mapcar* function - ;; @r{Recurse for rest of elements.} - (mapcar 'cdr args))))) -@end group - -@group -(mapcar* 'cons '(a b c) '(1 2 3 4)) - @result{} ((a . 1) (b . 2) (c . 3)) -@end group -@end smallexample -@end defun - -@defun mapc function sequence -@code{mapc} is like @code{mapcar} except that @var{function} is used for -side-effects only---the values it returns are ignored, not collected -into a list. @code{mapc} always returns @var{sequence}. -@end defun - -@defun mapconcat function sequence separator -@code{mapconcat} applies @var{function} to each element of -@var{sequence}: the results, which must be strings, are concatenated. -Between each pair of result strings, @code{mapconcat} inserts the string -@var{separator}. Usually @var{separator} contains a space or comma or -other suitable punctuation. - -The argument @var{function} must be a function that can take one -argument and return a string. The argument @var{sequence} can be any -kind of sequence except a char-table; that is, a list, a vector, a -bool-vector, or a string. - -@smallexample -@group -(mapconcat 'symbol-name - '(The cat in the hat) - " ") - @result{} "The cat in the hat" -@end group - -@group -(mapconcat (function (lambda (x) (format "%c" (1+ x)))) - "HAL-8000" - "") - @result{} "IBM.9111" -@end group -@end smallexample -@end defun - -@node Anonymous Functions -@section Anonymous Functions -@cindex anonymous function - - In Lisp, a function is a list that starts with @code{lambda}, a -byte-code function compiled from such a list, or alternatively a -primitive subr-object; names are ``extra.'' Although usually functions -are defined with @code{defun} and given names at the same time, it is -occasionally more concise to use an explicit lambda expression---an -anonymous function. Such a list is valid wherever a function name is. - - Any method of creating such a list makes a valid function. Even this: - -@smallexample -@group -(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x)))) -@result{} (lambda (x) (+ 12 x)) -@end group -@end smallexample - -@noindent -This computes a list that looks like @code{(lambda (x) (+ 12 x))} and -makes it the value (@emph{not} the function definition!) of -@code{silly}. - - Here is how we might call this function: - -@example -@group -(funcall silly 1) -@result{} 13 -@end group -@end example - -@noindent -(It does @emph{not} work to write @code{(silly 1)}, because this function -is not the @emph{function definition} of @code{silly}. We have not given -@code{silly} any function definition, just a value as a variable.) - - Most of the time, anonymous functions are constants that appear in -your program. For example, you might want to pass one as an argument to -the function @code{mapcar}, which applies any given function to each -element of a list. - - Here we define a function @code{change-property} which -uses a function as its third argument: - -@example -@group -(defun change-property (symbol prop function) - (let ((value (get symbol prop))) - (put symbol prop (funcall function value)))) -@end group -@end example - -@noindent -Here we define a function that uses @code{change-property}, -passing it a function to double a number: - -@example -@group -(defun double-property (symbol prop) - (change-property symbol prop '(lambda (x) (* 2 x)))) -@end group -@end example - -@noindent -In such cases, we usually use the special form @code{function} instead -of simple quotation to quote the anonymous function, like this: - -@example -@group -(defun double-property (symbol prop) - (change-property symbol prop - (function (lambda (x) (* 2 x))))) -@end group -@end example - -Using @code{function} instead of @code{quote} makes a difference if you -compile the function @code{double-property}. For example, if you -compile the second definition of @code{double-property}, the anonymous -function is compiled as well. By contrast, if you compile the first -definition which uses ordinary @code{quote}, the argument passed to -@code{change-property} is the precise list shown: - -@example -(lambda (x) (* x 2)) -@end example - -@noindent -The Lisp compiler cannot assume this list is a function, even though it -looks like one, since it does not know what @code{change-property} will -do with the list. Perhaps it will check whether the @sc{car} of the third -element is the symbol @code{*}! Using @code{function} tells the -compiler it is safe to go ahead and compile the constant function. - - Nowadays it is possible to omit @code{function} entirely, like this: - -@example -@group -(defun double-property (symbol prop) - (change-property symbol prop (lambda (x) (* 2 x)))) -@end group -@end example - -@noindent -This is because @code{lambda} itself implies @code{function}. - - We sometimes write @code{function} instead of @code{quote} when -quoting the name of a function, but this usage is just a sort of -comment: - -@example -(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol} -@end example - -@cindex @samp{#'} syntax - The read syntax @code{#'} is a short-hand for using @code{function}. -For example, - -@example -#'(lambda (x) (* x x)) -@end example - -@noindent -is equivalent to - -@example -(function (lambda (x) (* x x))) -@end example - -@defspec function function-object -@cindex function quoting -This special form returns @var{function-object} without evaluating it. -In this, it is equivalent to @code{quote}. However, it serves as a -note to the Emacs Lisp compiler that @var{function-object} is intended -to be used only as a function, and therefore can safely be compiled. -Contrast this with @code{quote}, in @ref{Quoting}. -@end defspec - - @xref{describe-symbols example}, for a realistic example using -@code{function} and an anonymous function. - -@node Function Cells -@section Accessing Function Cell Contents - - The @dfn{function definition} of a symbol is the object stored in the -function cell of the symbol. The functions described here access, test, -and set the function cell of symbols. - - See also the function @code{indirect-function}. @xref{Definition of -indirect-function}. - -@defun symbol-function symbol -@kindex void-function -This returns the object in the function cell of @var{symbol}. If the -symbol's function cell is void, a @code{void-function} error is -signaled. - -This function does not check that the returned object is a legitimate -function. - -@example -@group -(defun bar (n) (+ n 2)) - @result{} bar -@end group -@group -(symbol-function 'bar) - @result{} (lambda (n) (+ n 2)) -@end group -@group -(fset 'baz 'bar) - @result{} bar -@end group -@group -(symbol-function 'baz) - @result{} bar -@end group -@end example -@end defun - -@cindex void function cell - If you have never given a symbol any function definition, we say that -that symbol's function cell is @dfn{void}. In other words, the function -cell does not have any Lisp object in it. If you try to call such a symbol -as a function, it signals a @code{void-function} error. - - Note that void is not the same as @code{nil} or the symbol -@code{void}. The symbols @code{nil} and @code{void} are Lisp objects, -and can be stored into a function cell just as any other object can be -(and they can be valid functions if you define them in turn with -@code{defun}). A void function cell contains no object whatsoever. - - You can test the voidness of a symbol's function definition with -@code{fboundp}. After you have given a symbol a function definition, you -can make it void once more using @code{fmakunbound}. - -@defun fboundp symbol -This function returns @code{t} if the symbol has an object in its -function cell, @code{nil} otherwise. It does not check that the object -is a legitimate function. -@end defun - -@defun fmakunbound symbol -This function makes @var{symbol}'s function cell void, so that a -subsequent attempt to access this cell will cause a -@code{void-function} error. It returns @var{symbol}. (See also -@code{makunbound}, in @ref{Void Variables}.) - -@example -@group -(defun foo (x) x) - @result{} foo -@end group -@group -(foo 1) - @result{}1 -@end group -@group -(fmakunbound 'foo) - @result{} foo -@end group -@group -(foo 1) -@error{} Symbol's function definition is void: foo -@end group -@end example -@end defun - -@defun fset symbol definition -This function stores @var{definition} in the function cell of -@var{symbol}. The result is @var{definition}. Normally -@var{definition} should be a function or the name of a function, but -this is not checked. The argument @var{symbol} is an ordinary evaluated -argument. - -There are three normal uses of this function: - -@itemize @bullet -@item -Copying one symbol's function definition to another---in other words, -making an alternate name for a function. (If you think of this as the -definition of the new name, you should use @code{defalias} instead of -@code{fset}; see @ref{Definition of defalias}.) - -@item -Giving a symbol a function definition that is not a list and therefore -cannot be made with @code{defun}. For example, you can use @code{fset} -to give a symbol @code{s1} a function definition which is another symbol -@code{s2}; then @code{s1} serves as an alias for whatever definition -@code{s2} presently has. (Once again use @code{defalias} instead of -@code{fset} if you think of this as the definition of @code{s1}.) - -@item -In constructs for defining or altering functions. If @code{defun} -were not a primitive, it could be written in Lisp (as a macro) using -@code{fset}. -@end itemize - -Here are examples of these uses: - -@example -@group -;; @r{Save @code{foo}'s definition in @code{old-foo}.} -(fset 'old-foo (symbol-function 'foo)) -@end group - -@group -;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.} -;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)} -(fset 'xfirst 'car) - @result{} car -@end group -@group -(xfirst '(1 2 3)) - @result{} 1 -@end group -@group -(symbol-function 'xfirst) - @result{} car -@end group -@group -(symbol-function (symbol-function 'xfirst)) - @result{} #<subr car> -@end group - -@group -;; @r{Define a named keyboard macro.} -(fset 'kill-two-lines "\^u2\^k") - @result{} "\^u2\^k" -@end group - -@group -;; @r{Here is a function that alters other functions.} -(defun copy-function-definition (new old) - "Define NEW with the same function definition as OLD." - (fset new (symbol-function old))) -@end group -@end example -@end defun - - @code{fset} is sometimes used to save the old definition of a -function before redefining it. That permits the new definition to -invoke the old definition. But it is unmodular and unclean for a Lisp -file to redefine a function defined elsewhere. If you want to modify -a function defined by another package, it is cleaner to use -@code{defadvice} (@pxref{Advising Functions}). - -@node Obsolete Functions -@section Declaring Functions Obsolete - -You can use @code{make-obsolete} to declare a function obsolete. This -indicates that the function may be removed at some stage in the future. - -@defun make-obsolete obsolete-name current-name &optional when -This function makes the byte compiler warn that the function -@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the -warning message says to use @var{current-name} instead of -@var{obsolete-name}. @var{current-name} does not need to be an alias for -@var{obsolete-name}; it can be a different function with similar -functionality. If @var{current-name} is a string, it is the warning -message. - -If provided, @var{when} should be a string indicating when the function -was first made obsolete---for example, a date or a release number. -@end defun - -You can define a function as an alias and declare it obsolete at the -same time using the macro @code{define-obsolete-function-alias}. - -@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring -This macro marks the function @var{obsolete-name} obsolete and also -defines it as an alias for the function @var{current-name}. It is -equivalent to the following: - -@example -(defalias @var{obsolete-name} @var{current-name} @var{docstring}) -(make-obsolete @var{obsolete-name} @var{current-name} @var{when}) -@end example -@end defmac - -@node Inline Functions -@section Inline Functions -@cindex inline functions - -@findex defsubst -You can define an @dfn{inline function} by using @code{defsubst} instead -of @code{defun}. An inline function works just like an ordinary -function except for one thing: when you compile a call to the function, -the function's definition is open-coded into the caller. - -Making a function inline makes explicit calls run faster. But it also -has disadvantages. For one thing, it reduces flexibility; if you -change the definition of the function, calls already inlined still use -the old definition until you recompile them. - -Another disadvantage is that making a large function inline can increase -the size of compiled code both in files and in memory. Since the speed -advantage of inline functions is greatest for small functions, you -generally should not make large functions inline. - -Also, inline functions do not behave well with respect to debugging, -tracing, and advising (@pxref{Advising Functions}). Since ease of -debugging and the flexibility of redefining functions are important -features of Emacs, you should not make a function inline, even if it's -small, unless its speed is really crucial, and you've timed the code -to verify that using @code{defun} actually has performance problems. - -It's possible to define a macro to expand into the same code that an -inline function would execute. (@xref{Macros}.) But the macro would be -limited to direct use in expressions---a macro cannot be called with -@code{apply}, @code{mapcar} and so on. Also, it takes some work to -convert an ordinary function into a macro. To convert it into an inline -function is very easy; simply replace @code{defun} with @code{defsubst}. -Since each argument of an inline function is evaluated exactly once, you -needn't worry about how many times the body uses the arguments, as you -do for macros. (@xref{Argument Evaluation}.) - -Inline functions can be used and open-coded later on in the same file, -following the definition, just like macros. - -@node Function Safety -@section Determining whether a Function is Safe to Call -@cindex function safety -@cindex safety of functions - -Some major modes such as SES call functions that are stored in user -files. (@inforef{Top, ,ses}, for more information on SES.) User -files sometimes have poor pedigrees---you can get a spreadsheet from -someone you've just met, or you can get one through email from someone -you've never met. So it is risky to call a function whose source code -is stored in a user file until you have determined that it is safe. - -@defun unsafep form &optional unsafep-vars -Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or -returns a list that describes why it might be unsafe. The argument -@var{unsafep-vars} is a list of symbols known to have temporary -bindings at this point; it is mainly used for internal recursive -calls. The current buffer is an implicit argument, which provides a -list of buffer-local bindings. -@end defun - -Being quick and simple, @code{unsafep} does a very light analysis and -rejects many Lisp expressions that are actually safe. There are no -known cases where @code{unsafep} returns @code{nil} for an unsafe -expression. However, a ``safe'' Lisp expression can return a string -with a @code{display} property, containing an associated Lisp -expression to be executed after the string is inserted into a buffer. -This associated expression can be a virus. In order to be safe, you -must delete properties from all strings calculated by user code before -inserting them into buffers. - -@ignore -What is a safe Lisp expression? Basically, it's an expression that -calls only built-in functions with no side effects (or only innocuous -ones). Innocuous side effects include displaying messages and -altering non-risky buffer-local variables (but not global variables). - -@table @dfn -@item Safe expression -@itemize -@item -An atom or quoted thing. -@item -A call to a safe function (see below), if all its arguments are -safe expressions. -@item -One of the special forms @code{and}, @code{catch}, @code{cond}, -@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn}, -@code{while}, and @code{unwind-protect}], if all its arguments are -safe. -@item -A form that creates temporary bindings (@code{condition-case}, -@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or -@code{let*}), if all args are safe and the symbols to be bound are not -explicitly risky (see @pxref{File Local Variables}). -@item -An assignment using @code{add-to-list}, @code{setq}, @code{push}, or -@code{pop}, if all args are safe and the symbols to be assigned are -not explicitly risky and they already have temporary or buffer-local -bindings. -@item -One of [apply, mapc, mapcar, mapconcat] if the first argument is a -safe explicit lambda and the other args are safe expressions. -@end itemize - -@item Safe function -@itemize -@item -A lambda containing safe expressions. -@item -A symbol on the list @code{safe-functions}, so the user says it's safe. -@item -A symbol with a non-@code{nil} @code{side-effect-free} property. -@item -A symbol with a non-@code{nil} @code{safe-function} property. Value t -indicates a function that is safe but has innocuous side effects. -Other values will someday indicate functions with classes of side -effects that are not always safe. -@end itemize - -The @code{side-effect-free} and @code{safe-function} properties are -provided for built-in functions and for low-level functions and macros -defined in @file{subr.el}. You can assign these properties for the -functions you write. -@end table -@end ignore - -@node Related Topics -@section Other Topics Related to Functions - - Here is a table of several functions that do things related to -function calling and function definitions. They are documented -elsewhere, but we provide cross references here. - -@table @code -@item apply -See @ref{Calling Functions}. - -@item autoload -See @ref{Autoload}. - -@item call-interactively -See @ref{Interactive Call}. - -@item commandp -See @ref{Interactive Call}. - -@item documentation -See @ref{Accessing Documentation}. - -@item eval -See @ref{Eval}. - -@item funcall -See @ref{Calling Functions}. - -@item function -See @ref{Anonymous Functions}. - -@item ignore -See @ref{Calling Functions}. - -@item indirect-function -See @ref{Function Indirection}. - -@item interactive -See @ref{Using Interactive}. - -@item interactive-p -See @ref{Interactive Call}. - -@item mapatoms -See @ref{Creating Symbols}. - -@item mapcar -See @ref{Mapping Functions}. - -@item map-char-table -See @ref{Char-Tables}. - -@item mapconcat -See @ref{Mapping Functions}. - -@item undefined -See @ref{Functions for Key Lookup}. -@end table - -@ignore - arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2 -@end ignore diff --git a/lispref/gpl.texi b/lispref/gpl.texi deleted file mode 100644 index e9f7218ede9..00000000000 --- a/lispref/gpl.texi +++ /dev/null @@ -1,727 +0,0 @@ -@c -*-texinfo-*- -@setfilename ../info/gpl - -@node GPL, Tips, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@appendix GNU General Public License -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``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 PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. - -@ignore - arch-tag: d00ac830-e120-41fb-bbc5-7ca3eeaa227f -@end ignore diff --git a/lispref/hash.texi b/lispref/hash.texi deleted file mode 100644 index c5b68e26d91..00000000000 --- a/lispref/hash.texi +++ /dev/null @@ -1,337 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2001, 2002, 2003, 2004, 2005, -@c 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/hash -@node Hash Tables, Symbols, Sequences Arrays Vectors, Top -@chapter Hash Tables -@cindex hash tables -@cindex lookup tables - - A hash table is a very fast kind of lookup table, somewhat like an -alist (@pxref{Association Lists}) in that it maps keys to -corresponding values. It differs from an alist in these ways: - -@itemize @bullet -@item -Lookup in a hash table is extremely fast for large tables---in fact, the -time required is essentially @emph{independent} of how many elements are -stored in the table. For smaller tables (a few tens of elements) -alists may still be faster because hash tables have a more-or-less -constant overhead. - -@item -The correspondences in a hash table are in no particular order. - -@item -There is no way to share structure between two hash tables, -the way two alists can share a common tail. -@end itemize - - Emacs Lisp provides a general-purpose hash table data type, along -with a series of functions for operating on them. Hash tables have no -read syntax, and print in hash notation, like this: - -@example -(make-hash-table) - @result{} #<hash-table 'eql nil 0/65 0x83af980> -@end example - -@noindent -(The term ``hash notation'' refers to the initial @samp{#} -character---@pxref{Printed Representation}---and has nothing to do with -the term ``hash table.'') - - Obarrays are also a kind of hash table, but they are a different type -of object and are used only for recording interned symbols -(@pxref{Creating Symbols}). - -@menu -* 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. -@end menu - -@node Creating Hash -@section Creating Hash Tables -@cindex creating hash tables - - The principal function for creating a hash table is -@code{make-hash-table}. - -@defun make-hash-table &rest keyword-args -This function creates a new hash table according to the specified -arguments. The arguments should consist of alternating keywords -(particular symbols recognized specially) and values corresponding to -them. - -Several keywords make sense in @code{make-hash-table}, but the only two -that you really need to know about are @code{:test} and @code{:weakness}. - -@table @code -@item :test @var{test} -This specifies the method of key lookup for this hash table. The -default is @code{eql}; @code{eq} and @code{equal} are other -alternatives: - -@table @code -@item eql -Keys which are numbers are ``the same'' if they are @code{equal}, that -is, if they are equal in value and either both are integers or both -are floating point numbers; otherwise, two distinct objects are never -``the same.'' - -@item eq -Any two distinct Lisp objects are ``different'' as keys. - -@item equal -Two Lisp objects are ``the same,'' as keys, if they are equal -according to @code{equal}. -@end table - -You can use @code{define-hash-table-test} (@pxref{Defining Hash}) to -define additional possibilities for @var{test}. - -@item :weakness @var{weak} -The weakness of a hash table specifies whether the presence of a key or -value in the hash table preserves it from garbage collection. - -The value, @var{weak}, must be one of @code{nil}, @code{key}, -@code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t} -which is an alias for @code{key-and-value}. If @var{weak} is @code{key} -then the hash table does not prevent its keys from being collected as -garbage (if they are not referenced anywhere else); if a particular key -does get collected, the corresponding association is removed from the -hash table. - -If @var{weak} is @code{value}, then the hash table does not prevent -values from being collected as garbage (if they are not referenced -anywhere else); if a particular value does get collected, the -corresponding association is removed from the hash table. - -If @var{weak} is @code{key-and-value} or @code{t}, both the key and -the value must be live in order to preserve the association. Thus, -the hash table does not protect either keys or values from garbage -collection; if either one is collected as garbage, that removes the -association. - -If @var{weak} is @code{key-or-value}, either the key or -the value can preserve the association. Thus, associations are -removed from the hash table when both their key and value would be -collected as garbage (if not for references from weak hash tables). - -The default for @var{weak} is @code{nil}, so that all keys and values -referenced in the hash table are preserved from garbage collection. - -@item :size @var{size} -This specifies a hint for how many associations you plan to store in the -hash table. If you know the approximate number, you can make things a -little more efficient by specifying it this way. If you specify too -small a size, the hash table will grow automatically when necessary, but -doing that takes some extra time. - -The default size is 65. - -@item :rehash-size @var{rehash-size} -When you add an association to a hash table and the table is ``full,'' -it grows automatically. This value specifies how to make the hash table -larger, at that time. - -If @var{rehash-size} is an integer, it should be positive, and the hash -table grows by adding that much to the nominal size. If -@var{rehash-size} is a floating point number, it had better be greater -than 1, and the hash table grows by multiplying the old size by that -number. - -The default value is 1.5. - -@item :rehash-threshold @var{threshold} -This specifies the criterion for when the hash table is ``full'' (so -it should be made larger). The value, @var{threshold}, should be a -positive floating point number, no greater than 1. The hash table is -``full'' whenever the actual number of entries exceeds this fraction -of the nominal size. The default for @var{threshold} is 0.8. -@end table -@end defun - -@defun makehash &optional test -This is equivalent to @code{make-hash-table}, but with a different style -argument list. The argument @var{test} specifies the method -of key lookup. - -This function is obsolete. Use @code{make-hash-table} instead. -@end defun - -@node Hash Access -@section Hash Table Access - - This section describes the functions for accessing and storing -associations in a hash table. In general, any Lisp object can be used -as a hash key, unless the comparison method imposes limits. Any Lisp -object can also be used as the value. - -@defun gethash key table &optional default -This function looks up @var{key} in @var{table}, and returns its -associated @var{value}---or @var{default}, if @var{key} has no -association in @var{table}. -@end defun - -@defun puthash key value table -This function enters an association for @var{key} in @var{table}, with -value @var{value}. If @var{key} already has an association in -@var{table}, @var{value} replaces the old associated value. -@end defun - -@defun remhash key table -This function removes the association for @var{key} from @var{table}, if -there is one. If @var{key} has no association, @code{remhash} does -nothing. - -@b{Common Lisp note:} In Common Lisp, @code{remhash} returns -non-@code{nil} if it actually removed an association and @code{nil} -otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}. -@end defun - -@defun clrhash table -This function removes all the associations from hash table @var{table}, -so that it becomes empty. This is also called @dfn{clearing} the hash -table. - -@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty -@var{table}. In Emacs Lisp, it returns @code{nil}. -@end defun - -@defun maphash function table -@anchor{Definition of maphash} -This function calls @var{function} once for each of the associations in -@var{table}. The function @var{function} should accept two -arguments---a @var{key} listed in @var{table}, and its associated -@var{value}. @code{maphash} returns @code{nil}. -@end defun - -@node Defining Hash -@section Defining Hash Comparisons -@cindex hash code -@cindex define hash comparisons - - You can define new methods of key lookup by means of -@code{define-hash-table-test}. In order to use this feature, you need -to understand how hash tables work, and what a @dfn{hash code} means. - - You can think of a hash table conceptually as a large array of many -slots, each capable of holding one association. To look up a key, -@code{gethash} first computes an integer, the hash code, from the key. -It reduces this integer modulo the length of the array, to produce an -index in the array. Then it looks in that slot, and if necessary in -other nearby slots, to see if it has found the key being sought. - - Thus, to define a new method of key lookup, you need to specify both a -function to compute the hash code from a key, and a function to compare -two keys directly. - -@defun define-hash-table-test name test-fn hash-fn -This function defines a new hash table test, named @var{name}. - -After defining @var{name} in this way, you can use it as the @var{test} -argument in @code{make-hash-table}. When you do that, the hash table -will use @var{test-fn} to compare key values, and @var{hash-fn} to compute -a ``hash code'' from a key value. - -The function @var{test-fn} should accept two arguments, two keys, and -return non-@code{nil} if they are considered ``the same.'' - -The function @var{hash-fn} should accept one argument, a key, and return -an integer that is the ``hash code'' of that key. For good results, the -function should use the whole range of integer values for hash codes, -including negative integers. - -The specified functions are stored in the property list of @var{name} -under the property @code{hash-table-test}; the property value's form is -@code{(@var{test-fn} @var{hash-fn})}. -@end defun - -@defun sxhash obj -This function returns a hash code for Lisp object @var{obj}. -This is an integer which reflects the contents of @var{obj} -and the other Lisp objects it points to. - -If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash -@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer. - -If the two objects are not equal, the values returned by @code{sxhash} -are usually different, but not always; once in a rare while, by luck, -you will encounter two distinct-looking objects that give the same -result from @code{sxhash}. -@end defun - - This example creates a hash table whose keys are strings that are -compared case-insensitively. - -@example -(defun case-fold-string= (a b) - (compare-strings a nil nil b nil nil t)) -(defun case-fold-string-hash (a) - (sxhash (upcase a))) - -(define-hash-table-test 'case-fold - 'case-fold-string= 'case-fold-string-hash) - -(make-hash-table :test 'case-fold) -@end example - - Here is how you could define a hash table test equivalent to the -predefined test value @code{equal}. The keys can be any Lisp object, -and equal-looking objects are considered the same key. - -@example -(define-hash-table-test 'contents-hash 'equal 'sxhash) - -(make-hash-table :test 'contents-hash) -@end example - -@node Other Hash -@section Other Hash Table Functions - - Here are some other functions for working with hash tables. - -@defun hash-table-p table -This returns non-@code{nil} if @var{table} is a hash table object. -@end defun - -@defun copy-hash-table table -This function creates and returns a copy of @var{table}. Only the table -itself is copied---the keys and values are shared. -@end defun - -@defun hash-table-count table -This function returns the actual number of entries in @var{table}. -@end defun - -@defun hash-table-test table -This returns the @var{test} value that was given when @var{table} was -created, to specify how to hash and compare keys. See -@code{make-hash-table} (@pxref{Creating Hash}). -@end defun - -@defun hash-table-weakness table -This function returns the @var{weak} value that was specified for hash -table @var{table}. -@end defun - -@defun hash-table-rehash-size table -This returns the rehash size of @var{table}. -@end defun - -@defun hash-table-rehash-threshold table -This returns the rehash threshold of @var{table}. -@end defun - -@defun hash-table-size table -This returns the current nominal size of @var{table}. -@end defun - -@ignore - arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e -@end ignore diff --git a/lispref/help.texi b/lispref/help.texi deleted file mode 100644 index dd56aa872b7..00000000000 --- a/lispref/help.texi +++ /dev/null @@ -1,699 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/help -@node Documentation, Files, Modes, Top -@chapter Documentation -@cindex documentation strings - - GNU Emacs Lisp has convenient on-line help facilities, most of which -derive their information from the documentation strings associated with -functions and variables. This chapter describes how to write good -documentation strings for your Lisp programs, as well as how to write -programs to access documentation. - - Note that the documentation strings for Emacs are not the same thing -as the Emacs manual. Manuals have their own source files, written in -the Texinfo language; documentation strings are specified in the -definitions of the functions and variables they apply to. A collection -of documentation strings is not sufficient as a manual because a good -manual is not organized in that fashion; it is organized in terms of -topics of discussion. - - For commands to display documentation strings, see @ref{Help, , -Help, emacs, The GNU Emacs Manual}. For the conventions for writing -documentation strings, see @ref{Documentation Tips}. - -@menu -* 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. -@end menu - -@node Documentation Basics -@comment node-name, next, previous, up -@section Documentation Basics -@cindex documentation conventions -@cindex writing a documentation string -@cindex string, writing a doc string - - A documentation string is written using the Lisp syntax for strings, -with double-quote characters surrounding the text of the string. This -is because it really is a Lisp string object. The string serves as -documentation when it is written in the proper place in the definition -of a function or variable. In a function definition, the documentation -string follows the argument list. In a variable definition, the -documentation string follows the initial value of the variable. - - When you write a documentation string, make the first line a -complete sentence (or two complete sentences) since some commands, -such as @code{apropos}, show only the first line of a multi-line -documentation string. Also, you should not indent the second line of -a documentation string, if it has one, because that looks odd when you -use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v} -(@code{describe-variable}) to view the documentation string. There -are many other conventions for doc strings; see @ref{Documentation -Tips}. - - Documentation strings can contain several special substrings, which -stand for key bindings to be looked up in the current keymaps when the -documentation is displayed. This allows documentation strings to refer -to the keys for related commands and be accurate even when a user -rearranges the key bindings. (@xref{Keys in Documentation}.) - -@vindex emacs-lisp-docstring-fill-column - Emacs Lisp mode fills documentation strings to the width -specified by @code{emacs-lisp-docstring-fill-column}. - - In Emacs Lisp, a documentation string is accessible through the -function or variable that it describes: - -@itemize @bullet -@item -@kindex function-documentation -The documentation for a function is usually stored in the function -definition itself (@pxref{Lambda Expressions}). The function -@code{documentation} knows how to extract it. You can also put -function documentation in the @code{function-documentation} property -of the function name. That is useful with definitions such as -keyboard macros that can't hold a documentation string. - -@item -@kindex variable-documentation -The documentation for a variable is stored in the variable's property -list under the property name @code{variable-documentation}. The -function @code{documentation-property} knows how to retrieve it. -@end itemize - -@cindex @file{DOC-@var{version}} (documentation) file -To save space, the documentation for preloaded functions and variables -(including primitive functions and autoloaded functions) is stored in -the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The -documentation strings for functions and variables loaded during the -Emacs session from byte-compiled files are stored in those files -(@pxref{Docs and Compilation}). - -The data structure inside Emacs has an integer offset into the file, or -a list containing a file name and an integer, in place of the -documentation string. The functions @code{documentation} and -@code{documentation-property} use that information to fetch the -documentation string from the appropriate file; this is transparent to -the user. - -@c Wordy to prevent overfull hbox. --rjc 15mar92 - The @file{emacs/lib-src} directory contains two utilities that you can -use to print nice-looking hardcopy for the file -@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and -@file{digest-doc}. - -@node Accessing Documentation -@section Access to Documentation Strings - -@defun documentation-property symbol property &optional verbatim -This function returns the documentation string that is recorded in -@var{symbol}'s property list under property @var{property}. It -retrieves the text from a file if the value calls for that. If the -property value isn't @code{nil}, isn't a string, and doesn't refer to -text in a file, then it is evaluated to obtain a string. - -The last thing this function does is pass the string through -@code{substitute-command-keys} to substitute actual key bindings, -unless @var{verbatim} is non-@code{nil}. - -@smallexample -@group -(documentation-property 'command-line-processed - 'variable-documentation) - @result{} "Non-nil once command line has been processed" -@end group -@group -(symbol-plist 'command-line-processed) - @result{} (variable-documentation 188902) -@end group -@group -(documentation-property 'emacs 'group-documentation) - @result{} "Customization of the One True Editor." -@end group -@end smallexample -@end defun - -@defun documentation function &optional verbatim -This function returns the documentation string of @var{function}. -@code{documentation} handles macros, named keyboard macros, and -special forms, as well as ordinary functions. - -If @var{function} is a symbol, this function first looks for the -@code{function-documentation} property of that symbol; if that has a -non-@code{nil} value, the documentation comes from that value (if the -value is not a string, it is evaluated). If @var{function} is not a -symbol, or if it has no @code{function-documentation} property, then -@code{documentation} extracts the documentation string from the actual -function definition, reading it from a file if called for. - -Finally, unless @var{verbatim} is non-@code{nil}, it calls -@code{substitute-command-keys} so as to return a value containing the -actual (current) key bindings. - -The function @code{documentation} signals a @code{void-function} error -if @var{function} has no function definition. However, it is OK if -the function definition has no documentation string. In that case, -@code{documentation} returns @code{nil}. -@end defun - -@defun face-documentation face -This function returns the documentation string of @var{face} as a -face. -@end defun - -@c Wordy to prevent overfull hboxes. --rjc 15mar92 -Here is an example of using the two functions, @code{documentation} and -@code{documentation-property}, to display the documentation strings for -several symbols in a @samp{*Help*} buffer. - -@anchor{describe-symbols example} -@smallexample -@group -(defun describe-symbols (pattern) - "Describe the Emacs Lisp symbols matching PATTERN. -All symbols that have PATTERN in their name are described -in the `*Help*' buffer." - (interactive "sDescribe symbols matching: ") - (let ((describe-func - (function - (lambda (s) -@end group -@group - ;; @r{Print description of symbol.} - (if (fboundp s) ; @r{It is a function.} - (princ - (format "%s\t%s\n%s\n\n" s - (if (commandp s) - (let ((keys (where-is-internal s))) - (if keys - (concat - "Keys: " - (mapconcat 'key-description - keys " ")) - "Keys: none")) - "Function") -@end group -@group - (or (documentation s) - "not documented")))) - - (if (boundp s) ; @r{It is a variable.} -@end group -@group - (princ - (format "%s\t%s\n%s\n\n" s - (if (user-variable-p s) - "Option " "Variable") -@end group -@group - (or (documentation-property - s 'variable-documentation) - "not documented"))))))) - sym-list) -@end group - -@group - ;; @r{Build a list of symbols that match pattern.} - (mapatoms (function - (lambda (sym) - (if (string-match pattern (symbol-name sym)) - (setq sym-list (cons sym sym-list)))))) -@end group - -@group - ;; @r{Display the data.} - (with-output-to-temp-buffer "*Help*" - (mapcar describe-func (sort sym-list 'string<)) - (print-help-return-message)))) -@end group -@end smallexample - - The @code{describe-symbols} function works like @code{apropos}, -but provides more information. - -@smallexample -@group -(describe-symbols "goal") - ----------- Buffer: *Help* ---------- -goal-column Option -*Semipermanent goal column for vertical motion, as set by @dots{} -@end group -@c Do not blithely break or fill these lines. -@c That makes them incorrect. - -@group -set-goal-column Keys: C-x C-n -Set the current horizontal position as a goal for C-n and C-p. -@end group -@c DO NOT put a blank line here! That is factually inaccurate! -@group -Those commands will move to this position in the line moved to -rather than trying to keep the same horizontal position. -With a non-nil argument, clears out the goal column -so that C-n and C-p resume vertical motion. -The goal column is stored in the variable `goal-column'. -@end group - -@group -temporary-goal-column Variable -Current goal column for vertical motion. -It is the column where point was -at the start of current run of vertical motion commands. -When the `track-eol' feature is doing its job, the value is 9999. ----------- Buffer: *Help* ---------- -@end group -@end smallexample - -The asterisk @samp{*} as the first character of a variable's doc string, -as shown above for the @code{goal-column} variable, means that it is a -user option; see the description of @code{defvar} in @ref{Defining -Variables}. - -@defun Snarf-documentation filename -@anchor{Definition of Snarf-documentation} -This function is used only during Emacs initialization, just before -the runnable Emacs is dumped. It finds the file offsets of the -documentation strings stored in the file @var{filename}, and records -them in the in-core function definitions and variable property lists in -place of the actual strings. @xref{Building Emacs}. - -Emacs reads the file @var{filename} from the @file{emacs/etc} directory. -When the dumped Emacs is later executed, the same file will be looked -for in the directory @code{doc-directory}. Usually @var{filename} is -@code{"DOC-@var{version}"}. -@end defun - -@c Emacs 19 feature -@defvar doc-directory -This variable holds the name of the directory which should contain the -file @code{"DOC-@var{version}"} that contains documentation strings for -built-in and preloaded functions and variables. - -In most cases, this is the same as @code{data-directory}. They may be -different when you run Emacs from the directory where you built it, -without actually installing it. @xref{Definition of data-directory}. - -In older Emacs versions, @code{exec-directory} was used for this. -@end defvar - -@node Keys in Documentation -@section Substituting Key Bindings in Documentation -@cindex documentation, keys in -@cindex keys in documentation strings -@cindex substituting keys in documentation - - When documentation strings refer to key sequences, they should use the -current, actual key bindings. They can do so using certain special text -sequences described below. Accessing documentation strings in the usual -way substitutes current key binding information for these special -sequences. This works by calling @code{substitute-command-keys}. You -can also call that function yourself. - - Here is a list of the special sequences and what they mean: - -@table @code -@item \[@var{command}] -stands for a key sequence that will invoke @var{command}, or @samp{M-x -@var{command}} if @var{command} has no key bindings. - -@item \@{@var{mapvar}@} -stands for a summary of the keymap which is the value of the variable -@var{mapvar}. The summary is made using @code{describe-bindings}. - -@item \<@var{mapvar}> -stands for no text itself. It is used only for a side effect: it -specifies @var{mapvar}'s value as the keymap for any following -@samp{\[@var{command}]} sequences in this documentation string. - -@item \= -quotes the following character and is discarded; thus, @samp{\=\[} puts -@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the -output. -@end table - -@strong{Please note:} Each @samp{\} must be doubled when written in a -string in Emacs Lisp. - -@defun substitute-command-keys string -This function scans @var{string} for the above special sequences and -replaces them by what they stand for, returning the result as a string. -This permits display of documentation that refers accurately to the -user's own customized key bindings. -@end defun - - Here are examples of the special sequences: - -@smallexample -@group -(substitute-command-keys - "To abort recursive edit, type: \\[abort-recursive-edit]") -@result{} "To abort recursive edit, type: C-]" -@end group - -@group -(substitute-command-keys - "The keys that are defined for the minibuffer here are: - \\@{minibuffer-local-must-match-map@}") -@result{} "The keys that are defined for the minibuffer here are: -@end group - -? minibuffer-completion-help -SPC minibuffer-complete-word -TAB minibuffer-complete -C-j minibuffer-complete-and-exit -RET minibuffer-complete-and-exit -C-g abort-recursive-edit -" - -@group -(substitute-command-keys - "To abort a recursive edit from the minibuffer, type\ -\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].") -@result{} "To abort a recursive edit from the minibuffer, type C-g." -@end group -@end smallexample - - There are other special conventions for the text in documentation -strings---for instance, you can refer to functions, variables, and -sections of this manual. @xref{Documentation Tips}, for details. - -@node Describing Characters -@section Describing Characters for Help Messages -@cindex describe characters and events - - These functions convert events, key sequences, or characters to -textual descriptions. These descriptions are useful for including -arbitrary text characters or key sequences in messages, because they -convert non-printing and whitespace characters to sequences of printing -characters. The description of a non-whitespace printing character is -the character itself. - -@defun key-description sequence &optional prefix -@cindex Emacs event standard notation -This function returns a string containing the Emacs standard notation -for the input events in @var{sequence}. If @var{prefix} is -non-@code{nil}, it is a sequence of input events leading up to -@var{sequence} and is included in the return value. Both arguments -may be strings, vectors or lists. @xref{Input Events}, for more -information about valid events. - -@smallexample -@group -(key-description [?\M-3 delete]) - @result{} "M-3 <delete>" -@end group -@group -(key-description [delete] "\M-3") - @result{} "M-3 <delete>" -@end group -@end smallexample - - See also the examples for @code{single-key-description}, below. -@end defun - -@defun single-key-description event &optional no-angles -@cindex event printing -@cindex character printing -@cindex control character printing -@cindex meta character printing -This function returns a string describing @var{event} in the standard -Emacs notation for keyboard input. A normal printing character -appears as itself, but a control character turns into a string -starting with @samp{C-}, a meta character turns into a string starting -with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC}, -@samp{TAB}, etc. A function key symbol appears inside angle brackets -@samp{<@dots{}>}. An event that is a list appears as the name of the -symbol in the @sc{car} of the list, inside angle brackets. - -If the optional argument @var{no-angles} is non-@code{nil}, the angle -brackets around function keys and event symbols are omitted; this is -for compatibility with old versions of Emacs which didn't use the -brackets. - -@smallexample -@group -(single-key-description ?\C-x) - @result{} "C-x" -@end group -@group -(key-description "\C-x \M-y \n \t \r \f123") - @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3" -@end group -@group -(single-key-description 'delete) - @result{} "<delete>" -@end group -@group -(single-key-description 'C-mouse-1) - @result{} "<C-mouse-1>" -@end group -@group -(single-key-description 'C-mouse-1 t) - @result{} "C-mouse-1" -@end group -@end smallexample -@end defun - -@defun text-char-description character -This function returns a string describing @var{character} in the -standard Emacs notation for characters that appear in text---like -@code{single-key-description}, except that control characters are -represented with a leading caret (which is how control characters in -Emacs buffers are usually displayed). Another difference is that -@code{text-char-description} recognizes the 2**7 bit as the Meta -character, whereas @code{single-key-description} uses the 2**27 bit -for Meta. - -@smallexample -@group -(text-char-description ?\C-c) - @result{} "^C" -@end group -@group -(text-char-description ?\M-m) - @result{} "\xed" -@end group -@group -(text-char-description ?\C-\M-m) - @result{} "\x8d" -@end group -@group -(text-char-description (+ 128 ?m)) - @result{} "M-m" -@end group -@group -(text-char-description (+ 128 ?\C-m)) - @result{} "M-^M" -@end group -@end smallexample -@end defun - -@defun read-kbd-macro string &optional need-vector -This function is used mainly for operating on keyboard macros, but it -can also be used as a rough inverse for @code{key-description}. You -call it with a string containing key descriptions, separated by spaces; -it returns a string or vector containing the corresponding events. -(This may or may not be a single valid key sequence, depending on what -events you use; @pxref{Key Sequences}.) If @var{need-vector} is -non-@code{nil}, the return value is always a vector. -@end defun - -@node Help Functions -@section Help Functions - - Emacs provides a variety of on-line help functions, all accessible to -the user as subcommands of the prefix @kbd{C-h}. For more information -about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here -we describe some program-level interfaces to the same information. - -@deffn Command apropos pattern &optional do-all -This function finds all ``meaningful'' symbols whose names contain a -match for the apropos pattern @var{pattern}. An apropos pattern is -either a word to match, a space-separated list of words of which at -least two must match, or a regular expression (if any special regular -expression characters occur). A symbol is ``meaningful'' if it has a -definition as a function, variable, or face, or has properties. - -The function returns a list of elements that look like this: - -@example -(@var{symbol} @var{score} @var{fn-doc} @var{var-doc} - @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc}) -@end example - -Here, @var{score} is an integer measure of how important the symbol -seems to be as a match, and the remaining elements are documentation -strings for @var{symbol}'s various roles (or @code{nil}). - -It also displays the symbols in a buffer named @samp{*Apropos*}, each -with a one-line description taken from the beginning of its -documentation string. - -@c Emacs 19 feature -If @var{do-all} is non-@code{nil}, or if the user option -@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also -shows key bindings for the functions that are found; it also shows -@emph{all} interned symbols, not just meaningful ones (and it lists -them in the return value as well). -@end deffn - -@defvar help-map -The value of this variable is a local keymap for characters following the -Help key, @kbd{C-h}. -@end defvar - -@deffn {Prefix Command} help-command -This symbol is not a function; its function definition cell holds the -keymap known as @code{help-map}. It is defined in @file{help.el} as -follows: - -@smallexample -@group -(define-key global-map (char-to-string help-char) 'help-command) -(fset 'help-command help-map) -@end group -@end smallexample -@end deffn - -@defun print-help-return-message &optional function -This function builds a string that explains how to restore the previous -state of the windows after a help command. After building the message, -it applies @var{function} to it if @var{function} is non-@code{nil}. -Otherwise it calls @code{message} to display it in the echo area. - -This function expects to be called inside a -@code{with-output-to-temp-buffer} special form, and expects -@code{standard-output} to have the value bound by that special form. -For an example of its use, see the long example in @ref{Accessing -Documentation}. -@end defun - -@defvar help-char -The value of this variable is the help character---the character that -Emacs recognizes as meaning Help. By default, its value is 8, which -stands for @kbd{C-h}. When Emacs reads this character, if -@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that -expression, and displays the result in a window if it is a string. - -Usually the value of @code{help-form} is @code{nil}. Then the -help character has no special meaning at the level of command input, and -it becomes part of a key sequence in the normal way. The standard key -binding of @kbd{C-h} is a prefix key for several general-purpose help -features. - -The help character is special after prefix keys, too. If it has no -binding as a subcommand of the prefix key, it runs -@code{describe-prefix-bindings}, which displays a list of all the -subcommands of the prefix key. -@end defvar - -@defvar help-event-list -The value of this variable is a list of event types that serve as -alternative ``help characters.'' These events are handled just like the -event specified by @code{help-char}. -@end defvar - -@defvar help-form -If this variable is non-@code{nil}, its value is a form to evaluate -whenever the character @code{help-char} is read. If evaluating the form -produces a string, that string is displayed. - -A command that calls @code{read-event} or @code{read-char} probably -should bind @code{help-form} to a non-@code{nil} expression while it -does input. (The time when you should not do this is when @kbd{C-h} has -some other meaning.) Evaluating this expression should result in a -string that explains what the input is for and how to enter it properly. - -Entry to the minibuffer binds this variable to the value of -@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}). -@end defvar - -@defvar prefix-help-command -This variable holds a function to print help for a prefix key. The -function is called when the user types a prefix key followed by the help -character, and the help character has no binding after that prefix. The -variable's default value is @code{describe-prefix-bindings}. -@end defvar - -@defun describe-prefix-bindings -This function calls @code{describe-bindings} to display a list of all -the subcommands of the prefix key of the most recent key sequence. The -prefix described consists of all but the last event of that key -sequence. (The last event is, presumably, the help character.) -@end defun - - The following two functions are meant for modes that want to provide -help without relinquishing control, such as the ``electric'' modes. -Their names begin with @samp{Helper} to distinguish them from the -ordinary help functions. - -@deffn Command Helper-describe-bindings -This command pops up a window displaying a help buffer containing a -listing of all of the key bindings from both the local and global keymaps. -It works by calling @code{describe-bindings}. -@end deffn - -@deffn Command Helper-help -This command provides help for the current mode. It prompts the user -in the minibuffer with the message @samp{Help (Type ? for further -options)}, and then provides assistance in finding out what the key -bindings are, and what the mode is intended for. It returns @code{nil}. - -This can be customized by changing the map @code{Helper-help-map}. -@end deffn - -@c Emacs 19 feature -@defvar data-directory -@anchor{Definition of data-directory} -This variable holds the name of the directory in which Emacs finds -certain documentation and text files that come with Emacs. In older -Emacs versions, @code{exec-directory} was used for this. -@end defvar - -@c Emacs 19 feature -@defmac make-help-screen fname help-line help-text help-map -This macro defines a help command named @var{fname} that acts like a -prefix key that shows a list of the subcommands it offers. - -When invoked, @var{fname} displays @var{help-text} in a window, then -reads and executes a key sequence according to @var{help-map}. The -string @var{help-text} should describe the bindings available in -@var{help-map}. - -The command @var{fname} is defined to handle a few events itself, by -scrolling the display of @var{help-text}. When @var{fname} reads one of -those special events, it does the scrolling and then reads another -event. When it reads an event that is not one of those few, and which -has a binding in @var{help-map}, it executes that key's binding and -then returns. - -The argument @var{help-line} should be a single-line summary of the -alternatives in @var{help-map}. In the current version of Emacs, this -argument is used only if you set the option @code{three-step-help} to -@code{t}. - -This macro is used in the command @code{help-for-help} which is the -binding of @kbd{C-h C-h}. -@end defmac - -@defopt three-step-help -If this variable is non-@code{nil}, commands defined with -@code{make-help-screen} display their @var{help-line} strings in the -echo area at first, and display the longer @var{help-text} strings only -if the user types the help character again. -@end defopt - -@ignore - arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815 -@end ignore diff --git a/lispref/hooks.texi b/lispref/hooks.texi deleted file mode 100644 index 572d3b79d93..00000000000 --- a/lispref/hooks.texi +++ /dev/null @@ -1,338 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/hooks -@node Standard Hooks, Index, Standard Keymaps, Top -@appendix Standard Hooks -@cindex standard hooks -@cindex hook variables, list of - -The following is a list of hook variables that let you provide -functions to be called from within Emacs on suitable occasions. - -Most of these variables have names ending with @samp{-hook}. They are -@dfn{normal hooks}, run by means of @code{run-hooks}. The value of such -a hook is a list of functions; the functions are called with no -arguments and their values are completely ignored. The recommended way -to put a new function on such a hook is to call @code{add-hook}. -@xref{Hooks}, for more information about using hooks. - -Every major mode defines a mode hook named -@samp{@var{modename}-mode-hook}. The major mode command runs this -normal hook with @code{run-mode-hooks} as the very last thing it does. -@xref{Mode Hooks}. Most minor modes have mode hooks too. Mode hooks -are omitted in the list below. - -The variables whose names end in @samp{-hooks} or @samp{-functions} are -usually @dfn{abnormal hooks}; their values are lists of functions, but -these functions are called in a special way (they are passed arguments, -or their values are used). The variables whose names end in -@samp{-function} have single functions as their values. - -@c We need to xref to where each hook is documented or else document -@c it here. - -@table @code -@item activate-mark-hook -@xref{The Mark}. - -@item after-change-functions -@xref{Change Hooks}. - -@item after-change-major-mode-hook -@xref{Mode Hooks}. - -@item after-init-hook -@xref{Init File}. - -@item after-insert-file-functions -@xref{Format Conversion}. - -@item after-make-frame-functions -@xref{Creating Frames}. - -@item after-revert-hook -@xref{Reverting}. - -@item after-save-hook -@xref{Saving Buffers}. - -@item auto-fill-function -@xref{Auto Filling}. - -@item auto-save-hook -@xref{Auto-Saving}. - -@item before-change-functions -@xref{Change Hooks}. - -@item before-init-hook -@xref{Init File}. - -@item before-make-frame-hook -@xref{Creating Frames}. - -@item before-revert-hook -@xref{Reverting}. - -@item before-save-hook -@xref{Saving Buffers}. - -@item blink-paren-function -@xref{Blinking}. - -@item buffer-access-fontify-functions -@xref{Lazy Properties}. - -@item calendar-load-hook -@iftex -@inforef{Calendar Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing,,, emacs}. -@end ifnottex - - -@item change-major-mode-hook -@xref{Creating Buffer-Local}. - -@item command-line-functions -@xref{Command-Line Arguments}. - -@item comment-indent-function -@xref{Options for Comments,, Options Controlling Comments, emacs, the -GNU Emacs Manual}. - -@item compilation-finish-functions -Functions to call when a compilation process finishes. - -@item custom-define-hook -Hook called after defining each customize option. - -@item deactivate-mark-hook -@xref{The Mark}. - -@item desktop-after-read-hook -Normal hook run after a successful @code{desktop-read}. May be used -to show a buffer list. @xref{Saving Emacs Sessions,, Saving Emacs -Sessions, emacs, the GNU Emacs Manual}. - -@item desktop-no-desktop-file-hook -Normal hook run when @code{desktop-read} can't find a desktop file. -May be used to show a dired buffer. @xref{Saving Emacs Sessions,, -Saving Emacs Sessions, emacs, the GNU Emacs Manual}. - -@item desktop-save-hook -Normal hook run before the desktop is saved in a desktop file. This -is useful for truncating history lists, for example. @xref{Saving -Emacs Sessions,, Saving Emacs Sessions, emacs, the GNU Emacs Manual}. - -@item diary-display-hook -@iftex -@inforef{Fancy Diary Display,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Fancy Diary Display,,, emacs}. -@end ifnottex - -@item diary-hook -List of functions called after the display of the diary. Can be used -for appointment notification. - -@item disabled-command-function -@xref{Disabling Commands}. - -@item echo-area-clear-hook -@xref{Echo Area Customization}. - -@item emacs-startup-hook -@xref{Init File}. - -@item find-file-hook -@xref{Visiting Functions}. - -@item find-file-not-found-functions -@xref{Visiting Functions}. - -@item first-change-hook -@xref{Change Hooks}. - -@item font-lock-beginning-of-syntax-function -@xref{Syntactic Font Lock}. - -@item font-lock-fontify-buffer-function -@xref{Other Font Lock Variables}. - -@item font-lock-fontify-region-function -@xref{Other Font Lock Variables}. - -@item font-lock-mark-block-function -@xref{Other Font Lock Variables}. - -@item font-lock-syntactic-face-function -@xref{Syntactic Font Lock}. - -@item font-lock-unfontify-buffer-function -@xref{Other Font Lock Variables}. - -@item font-lock-unfontify-region-function -@xref{Other Font Lock Variables}. - -@item initial-calendar-window-hook -@iftex -@inforef{Calendar Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing,,, emacs}. -@end ifnottex - -@item kbd-macro-termination-hook -@xref{Keyboard Macros}. - -@item kill-buffer-hook -@xref{Killing Buffers}. - -@item kill-buffer-query-functions -@xref{Killing Buffers}. - -@item kill-emacs-hook -@xref{Killing Emacs}. - -@item kill-emacs-query-functions -@xref{Killing Emacs}. - -@item lisp-indent-function - -@item list-diary-entries-hook -@iftex -@inforef{Fancy Diary Display,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Fancy Diary Display,,, emacs}. -@end ifnottex - -@item mail-setup-hook -@xref{Mail Mode Misc,, Mail Mode Miscellany, emacs, the GNU Emacs -Manual}. - -@item mark-diary-entries-hook -@iftex -@inforef{Fancy Diary Display,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Fancy Diary Display,,, emacs}. -@end ifnottex - -@item menu-bar-update-hook -@xref{Menu Bar}. - -@item minibuffer-setup-hook -@xref{Minibuffer Misc}. - -@item minibuffer-exit-hook -@xref{Minibuffer Misc}. - -@item mouse-position-function -@xref{Mouse Position}. - -@item nongregorian-diary-listing-hook -@iftex -@inforef{Hebrew/Islamic Entries,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Hebrew/Islamic Entries,,, emacs}. -@end ifnottex - -@item nongregorian-diary-marking-hook -@iftex -@inforef{Hebrew/Islamic Entries,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Hebrew/Islamic Entries,,, emacs}. -@end ifnottex - -@item occur-hook - -@item post-command-hook -@xref{Command Overview}. - -@item pre-abbrev-expand-hook -@xref{Abbrev Expansion}. - -@item pre-command-hook -@xref{Command Overview}. - -@item print-diary-entries-hook -@iftex -@inforef{Diary Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Diary Customizing,,, emacs}. -@end ifnottex - -@item redisplay-end-trigger-functions -@xref{Window Hooks}. - -@item scheme-indent-function - -@item suspend-hook -@xref{Suspending Emacs}. - -@item suspend-resume-hook -@xref{Suspending Emacs}. - -@item temp-buffer-setup-hook -@xref{Temporary Displays}. - -@item temp-buffer-show-function -@xref{Temporary Displays}. - -@item temp-buffer-show-hook -@xref{Temporary Displays}. - -@item term-setup-hook -@xref{Terminal-Specific}. - -@item today-visible-calendar-hook -@iftex -@inforef{Calendar Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing,,, emacs}. -@end ifnottex - -@item today-invisible-calendar-hook -@iftex -@inforef{Calendar Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing,,, emacs}. -@end ifnottex - -@item window-configuration-change-hook -@xref{Window Hooks}. - -@item window-scroll-functions -@xref{Window Hooks}. - -@item window-setup-hook -@xref{Window Systems}. - -@item window-size-change-functions -@xref{Window Hooks}. - -@item write-contents-functions -@xref{Saving Buffers}. - -@item write-file-functions -@xref{Saving Buffers}. - -@item write-region-annotate-functions -@xref{Format Conversion}. -@end table - -@ignore - arch-tag: 55fd0296-d906-4551-b300-979d3846aa88 -@end ignore diff --git a/lispref/index.texi b/lispref/index.texi deleted file mode 100644 index cfa8f25e126..00000000000 --- a/lispref/index.texi +++ /dev/null @@ -1,29 +0,0 @@ -@c -*-texinfo-*- -@setfilename ../info/index - -@c Indexing guidelines - -@c I assume that all indexes will be combined. -@c Therefore, if a generated findex and permutations -@c cover the ways an index user would look up the entry, -@c then no cindex is added. -@c Concept index (cindex) entries will also be permuted. Therefore, they -@c have no commas and few irrelevant connectives in them. - -@c I tried to include words in a cindex that give the context of the entry, -@c particularly if there is more than one entry for the same concept. -@c For example, "nil in keymap" -@c Similarly for explicit findex and vindex entries, e.g. "print example". - -@c Error codes are given cindex entries, e.g. "end-of-file error". - -@c pindex is used for .el files and Unix programs - -@node Index, , Standard Hooks, Top -@unnumbered Index - -@c Print the indices - -@printindex fn - - diff --git a/lispref/internals.texi b/lispref/internals.texi deleted file mode 100644 index 3cd42ed69ff..00000000000 --- a/lispref/internals.texi +++ /dev/null @@ -1,1522 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 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 the dumped Emacs is made. -* 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. -@end menu - -@node Building Emacs -@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 that is still impure but no longer -bare. - -@cindex dumping Emacs - 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} that 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 substantial 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} that loads them. You may need to add a definition - -@example -#define SITELOAD_PURESIZE_EXTRA @var{n} -@end example - -@noindent -to make @var{n} added bytes of pure space to hold 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. - - After @file{loadup.el} reads @file{site-load.el}, it finds the -documentation strings for primitive and preloaded functions (and -variables) in the file @file{etc/DOC} where they are stored, by -calling @code{Snarf-documentation} (@pxref{Definition of -Snarf-documentation,, Accessing Documentation}). - -@cindex @file{site-init.el} -@cindex preloading additional functions and variables - You can specify other Lisp expressions to execute just before dumping -by putting them in a library named @file{site-init.el}. This file is -executed after the documentation strings are found. - - If you want to preload function or variable definitions, there are -three ways you can do this and make their documentation strings -accessible when you subsequently run Emacs: - -@itemize @bullet -@item -Arrange to scan these files when producing the @file{etc/DOC} file, -and load them with @file{site-load.el}. - -@item -Load the files with @file{site-init.el}, then copy the files into the -installation directory for Lisp files when you install Emacs. - -@item -Specify a non-@code{nil} value for -@code{byte-compile-dynamic-docstrings} as a local variable in each of these -files, and load them with either @file{site-load.el} or -@file{site-init.el}. (This method has the drawback that the -documentation strings take up space in Emacs all the time.) -@end itemize - - It is not advisable to put anything in @file{site-load.el} or -@file{site-init.el} that would alter any of the features that users -expect in an ordinary unmodified Emacs. If you feel you must override -normal features for your site, do it with @file{default.el}, so that -users can override your changes if they wish. @xref{Startup Summary}. - - In a package that can be preloaded, it is sometimes useful to -specify a computation to be done when Emacs subsequently starts up. -For this, use @code{eval-at-startup}: - -@defmac eval-at-startup body@dots{} -This evaluates the @var{body} forms, either immediately if running in -an Emacs that has already started up, or later when Emacs does start -up. Since the value of the @var{body} forms is not necessarily -available when the @code{eval-at-startup} form is run, that form -always returns @code{nil}. -@end defmac - -@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 want to use this function in an Emacs that was already dumped, -you must run Emacs with @samp{-batch}. -@end defun - -@node Pure Storage -@appendixsec Pure Storage -@cindex pure storage - - Emacs Lisp uses two kinds of storage for user-created Lisp objects: -@dfn{normal storage} and @dfn{pure storage}. Normal storage is where -all the new data created during an Emacs session are 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 that 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} allocates dynamic memory for -the part that didn't fit. If that happens, you should increase the -compilation parameter @code{PURESIZE} in the file -@file{src/puresize.h} and rebuild Emacs, even though the resulting -image will work: garbage collection is disabled in this situation, -causing a memory leak. Such an overflow normally won't happen unless you -try to preload additional libraries or add features to the standard -ones. Emacs will display a warning about the overflow when it -starts. - -@defun purecopy object -This function makes a copy in pure storage of @var{object}, and returns -it. It copies a string by simply making a new string with the same -characters, but without text properties, in pure storage. It -recursively copies the contents of vectors and cons cells. It does -not make copies of other objects such as symbols, but just returns -them unchanged. It signals an error if asked to copy markers. - -This function is a no-op except while Emacs is being built and dumped; -it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but -a few packages call it just in case you decide to preload them. -@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). Dumping Emacs as an executable always writes -@code{nil} in this variable, regardless of the value it actually has -before and after dumping. - -You should not change this flag in a running Emacs. -@end defvar - -@node Garbage Collection -@appendixsec Garbage Collection -@cindex garbage collection - -@cindex memory allocation - When a program creates a list or the user defines a new function (such -as by loading a library), 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, long strings, -buffers and certain other editing types, which are fairly large, are -allocated in individual blocks, one per object, while small 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 finding and marking all Lisp objects -that are still accessible to Lisp programs. To begin with, it assumes -all the symbols, their values and associated function definitions, and -any data presently on the stack, are accessible. Any objects that can -be reached indirectly through other accessible objects are also -accessible. - - When marking is finished, all objects still unmarked 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 miss them. The second -(``sweep'') phase of the garbage collector arranges to reuse them. - -@c ??? Maybe add something describing weak hash tables here? - -@cindex free list - The sweep phase puts unused cons cells onto a @dfn{free list} -for future allocation; likewise for symbols and markers. It compacts -the accessible strings so they occupy fewer 8k blocks; then it frees the -other 8k blocks. Vectors, buffers, windows, and other large objects are -individually allocated and freed using @code{malloc} and @code{free}. - -@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: - -@example -@group -((@var{used-conses} . @var{free-conses}) - (@var{used-syms} . @var{free-syms}) -@end group - (@var{used-miscs} . @var{free-miscs}) - @var{used-string-chars} - @var{used-vector-slots} - (@var{used-floats} . @var{free-floats}) - (@var{used-intervals} . @var{free-intervals}) - (@var{used-strings} . @var{free-strings})) -@end example - -Here is an example: - -@example -@group -(garbage-collect) - @result{} ((106886 . 13184) (9769 . 0) - (7731 . 4651) 347543 121628 - (31 . 94) (1273 . 168) - (25474 . 3569)) -@end group -@end example - -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-miscs -The number of miscellaneous objects in use. These include markers and -overlays, plus certain objects not visible to users. - -@item free-miscs -The number of miscellaneous objects 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. - -@item used-intervals -The number of intervals in use. Intervals are an internal -data structure used for representing text properties. - -@item free-intervals -The number of intervals for which space has been obtained -from the operating system, but that are not currently being used. - -@item used-strings -The number of strings in use. - -@item free-strings -The number of string headers for which the space was obtained from the -operating system, but which are currently not in use. (A string -object consists of a header and the storage for the string text -itself; the latter is only allocated when the string is created.) -@end table - -If there was overflow in pure space (see the previous section), -@code{garbage-collect} returns @code{nil}, because a real garbage -collection can not be done in this situation. -@end deffn - -@defopt garbage-collection-messages -If this variable is non-@code{nil}, Emacs displays a message at the -beginning and end of garbage collection. The default value is -@code{nil}, meaning there are no such messages. -@end defopt - -@defvar post-gc-hook -This is a normal hook that is run at the end of garbage collection. -Garbage collection is inhibited while the hook functions run, so be -careful writing them. -@end defvar - -@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 -trigger 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 subsequent 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 400,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 that 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 - -@defopt gc-cons-percentage -The value of this variable specifies the amount of consing before a -garbage collection occurs, as a fraction of the current heap size. -This criterion and @code{gc-cons-threshold} apply in parallel, and -garbage collection occurs only when both criteria are satisfied. - -As the heap size increases, the time to perform a garbage collection -increases. Thus, it can be desirable to do them less frequently in -proportion. -@end defopt - - The value returned by @code{garbage-collect} describes the amount of -memory used by Lisp data, broken down by data type. By contrast, the -function @code{memory-limit} provides information on the total amount of -memory Emacs is currently using. - -@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 - -@defvar memory-full -This variable is @code{t} if Emacs is close to out of memory for Lisp -objects, and @code{nil} otherwise. -@end defvar - -@defun memory-use-counts -This returns a list of numbers that count the number of objects -created in this Emacs session. Each of these counters increments for -a certain kind of object. See the documentation string for details. -@end defun - -@defvar gcs-done -This variable contains the total number of garbage collections -done so far in this Emacs session. -@end defvar - -@defvar gc-elapsed -This variable contains the total number of seconds of elapsed time -during garbage collection so far in this Emacs session, as a floating -point number. -@end defvar - -@node Memory Usage -@section Memory Usage -@cindex memory usage - - These functions and variables give information about the total amount -of memory allocation that Emacs has done, broken down by data type. -Note the difference between these and the values returned by -@code{(garbage-collect)}; those count objects that currently exist, but -these count the number or size of all allocations, including those for -objects that have since been freed. - -@defvar cons-cells-consed -The total number of cons cells that have been allocated so far -in this Emacs session. -@end defvar - -@defvar floats-consed -The total number of floats that have been allocated so far -in this Emacs session. -@end defvar - -@defvar vector-cells-consed -The total number of vector cells that have been allocated so far -in this Emacs session. -@end defvar - -@defvar symbols-consed -The total number of symbols that have been allocated so far -in this Emacs session. -@end defvar - -@defvar string-chars-consed -The total number of string characters that have been allocated so far -in this Emacs session. -@end defvar - -@defvar misc-objects-consed -The total number of miscellaneous objects that have been allocated so -far in this Emacs session. These include markers and overlays, plus -certain objects not visible to users. -@end defvar - -@defvar intervals-consed -The total number of intervals that have been allocated so far -in this Emacs session. -@end defvar - -@defvar strings-consed -The total number of strings that have been allocated so far in this -Emacs session. -@end defvar - -@node Writing Emacs Primitives -@appendixsec Writing Emacs Primitives -@cindex primitive function internals -@cindex writing Emacs primitives - - 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, - doc: /* Eval args until one of them yields non-nil, then return that -value. The remaining args are not evalled at all. -If all args return nil, return nil. -@end group -@group -usage: (or CONDITIONS ...) */) - (args) - Lisp_Object args; -@{ - register Lisp_Object val = Qnil; - struct gcpro gcpro1; -@end group - -@group - GCPRO1 (args); -@end group - -@group - while (CONSP (args)) - @{ - val = Feval (XCAR (args)); - if (!NILP (val)) - break; - args = XCDR (args); - @} -@end group - -@group - UNGCPRO; - return val; -@} -@end group -@end smallexample - -@cindex @code{DEFUN}, C macro to define Lisp primitives - Let's start with a precise explanation of the arguments to the -@code{DEFUN} macro. Here is a template 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 as the function name; 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. The -function @code{or} allows a minimum of zero arguments. - -@item max -This is the maximum number of arguments that the function accepts, if -there is a fixed maximum. Alternatively, it can be @code{UNEVALLED}, -indicating a special form that receives unevaluated arguments, or -@code{MANY}, indicating an unlimited number of evaluated arguments (the -equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are -macros. If @var{max} is a number, it may not be less than @var{min} and -it may not be greater than eight. - -@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 a function that -should receive no arguments when called interactively. - -@item doc -This is the documentation string. It uses C comment syntax rather -than C string syntax because comment syntax requires nothing special -to include multiple lines. The @samp{doc:} identifies the comment -that follows as the documentation string. The @samp{/*} and @samp{*/} -delimiters that begin and end the comment are not part of the -documentation string. - -If the last line of the documentation string begins with the keyword -@samp{usage:}, the rest of the line is treated as the argument list -for documentation purposes. This way, you can use different argument -names in the documentation string from the ones used in the C code. -@samp{usage:} is required if the function has an unlimited number of -arguments. - -All the usual rules for documentation strings in Lisp code -(@pxref{Documentation Tips}) apply to C code documentation strings -too. -@end table - - After the call to the @code{DEFUN} macro, you must write the argument -name list that every C function must have, followed by ordinary C -declarations for the arguments. For a function with a fixed maximum -number of arguments, declare a C argument for each Lisp argument, and -give them all type @code{Lisp_Object}. When a Lisp function has no -upper limit on the number of arguments, its implementation in C actually -receives exactly two arguments: the first is the number of Lisp -arguments, and the second is the address of a block containing their -values. They have types @code{int} and @w{@code{Lisp_Object *}}. - -@cindex @code{GCPRO} and @code{UNGCPRO} -@cindex protect C variables from garbage collection - 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. GC protection 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 this function may -refer to again must be protected somehow. - - It suffices to ensure that at least one pointer to each object is -GC-protected; that way, the object cannot be recycled, so all pointers -to it remain valid. Thus, a particular local variable can do without -protection if it is certain that the object it points to will be -preserved by some other pointer (such as another local variable which -has a @code{GCPRO})@footnote{Formerly, strings were a special -exception; in older Emacs versions, every local variable that might -point to a string needed a @code{GCPRO}.}. Otherwise, the local -variable needs a @code{GCPRO}. - - The macro @code{GCPRO1} protects just one local variable. If you -want to protect two variables, use @code{GCPRO2} instead; repeating -@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4}, -@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros -implicitly use local variables such as @code{gcpro1}; you must declare -these explicitly, with type @code{struct gcpro}. Thus, if you use -@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. -Alas, we can't explain all the tricky details here. - - @code{UNGCPRO} cancels the protection of the variables that are -protected in the current function. It is necessary to do this -explicitly. - - Built-in functions that take a variable number of arguments actually -accept two arguments at the C level: the number of Lisp arguments, and -a @code{Lisp_Object *} pointer to a C vector containing those Lisp -arguments. This C vector may be part of a Lisp vector, but it need -not be. The responsibility for using @code{GCPRO} to protect the Lisp -arguments from GC if necessary rests with the caller in this case, -since the caller allocated or found the storage for them. - - You must not use C initializers for static or global variables unless -the variables are never written once Emacs is dumped. These variables -with initializers are allocated in an area of memory that becomes -read-only (on certain operating systems) as a result of dumping Emacs. -@xref{Pure Storage}. - - Do not use static variables within functions---place all static -variables at top level in the file. This is necessary because Emacs on -some operating systems defines the keyword @code{static} as a null -macro. (This definition is used because those systems put all variables -declared static in a place that becomes read-only after dumping, whether -they have initializers or not.) - -@cindex @code{defsubr}, Lisp symbol for a primitive - Defining the C function is not enough to make a Lisp primitive -available; you must also create the Lisp symbol for the primitive and -store a suitable subr object in its function cell. The code looks like -this: - -@example -defsubr (&@var{subr-structure-name}); -@end example - -@noindent -Here @var{subr-structure-name} is the name you used as the third -argument to @code{DEFUN}. - - If you add a new 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 the call to @code{defsubr} -there. 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. - -@anchor{Defining Lisp variables in C} -@vindex byte-boolean-vars -@cindex defining Lisp variables in C -@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL} - The function @code{syms_of_@var{filename}} is also the place to define -any C variables that are to be visible as Lisp variables. -@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible -in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int} -visible in Lisp with a value that is always an integer. -@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp -with a value that is either @code{t} or @code{nil}. Note that variables -defined with @code{DEFVAR_BOOL} are automatically added to the list -@code{byte-boolean-vars} used by the byte compiler. - -@cindex @code{staticpro}, protection from GC - If you define a file-scope C variable of type @code{Lisp_Object}, -you must protect it from garbage-collection by calling @code{staticpro} -in @code{syms_of_@var{filename}}, like this: - -@example -staticpro (&@var{variable}); -@end example - - Here is another example function, with more complicated arguments. -This comes from the code in @file{window.c}, 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 COORDINATES is in WINDOW.\n\ -COORDINATES is a cons of the form (X . Y), X and Y being distances\n\ -... -@end group -@group -If they are on the border between WINDOW and its right sibling,\n\ - `vertical-line' is returned.") - (coordinates, window) - register Lisp_Object coordinates, window; -@{ - int x, y; -@end group - -@group - CHECK_LIVE_WINDOW (window, 0); - CHECK_CONS (coordinates, 1); - x = XINT (Fcar (coordinates)); - y = XINT (Fcdr (coordinates)); -@end group - -@group - switch (coordinates_in_window (XWINDOW (window), &x, &y)) - @{ - case 0: /* NOT in window at all. */ - return Qnil; -@end group - -@group - case 1: /* In text part of window. */ - return Fcons (make_number (x), make_number (y)); -@end group - -@group - case 2: /* In mode line of window. */ - return Qmode_line; -@end group - -@group - case 3: /* On right border of window. */ - return Qvertical_line; -@end group - -@group - default: - abort (); - @} -@} -@end group -@end smallexample - - Note that C code cannot call functions by name unless they are defined -in C. The way to call a function written in Lisp is to use -@code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since -the Lisp function @code{funcall} accepts an unlimited number of -arguments, in C it takes two: the number of Lisp-level arguments, and a -one-dimensional array containing their values. The first Lisp-level -argument is the Lisp function to call, and the rest are the arguments to -pass to it. Since @code{Ffuncall} can call the evaluator, you must -protect pointers from garbage collection around the call to -@code{Ffuncall}. - - The C functions @code{call0}, @code{call1}, @code{call2}, and so on, -provide handy ways to call a Lisp function conveniently with a fixed -number of arguments. They work by calling @code{Ffuncall}. - - @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. - - If you define a function which is side-effect free, update the code -in @file{byte-opt.el} which binds @code{side-effect-free-fns} and -@code{side-effect-and-error-free-fns} so that the compiler optimizer -knows about it. - -@node Object 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-nine bits are used to address the -object, and the remaining three bits are used for the tag that -identifies the object's type. - - Because Lisp objects are represented as tagged pointers, it is always -possible to determine the Lisp data type of any object. The C data type -@code{Lisp_Object} can hold any Lisp object of any data type. Ordinary -variables have type @code{Lisp_Object}, which means they can hold any -type of Lisp value; you can determine the actual data type only at run -time. The same is true for function arguments; 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 -@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. - -Two structures are used to represent buffers in C. The -@code{buffer_text} structure contains fields describing the text of a -buffer; the @code{buffer} structure holds other fields. In the case -of indirect buffers, two or more @code{buffer} structures reference -the same @code{buffer_text} structure. - -Here is a list of the @code{struct buffer_text} fields: - -@table @code -@item beg -This field contains the actual address of the buffer contents. - -@item gpt -This holds the character position of the gap in the buffer. -@xref{Buffer Gap}. - -@item z -This field contains the character position of the end of the buffer -text. - -@item gpt_byte -Contains the byte position of the gap. - -@item z_byte -Holds the byte position of the end of the buffer text. - -@item gap_size -Contains the size of buffer's gap. @xref{Buffer Gap}. - -@item modiff -This field counts buffer-modification events for this buffer. It is -incremented for each such event, and never otherwise changed. - -@item save_modiff -Contains the previous value of @code{modiff}, as of the last time a -buffer was visited or saved in a file. - -@item overlay_modiff -Counts modifications to overlays analogous to @code{modiff}. - -@item beg_unchanged -Holds the number of characters at the start of the text that are known -to be unchanged since the last redisplay that finished. - -@item end_unchanged -Holds the number of characters at the end of the text that are known to -be unchanged since the last redisplay that finished. - -@item unchanged_modified -Contains the value of @code{modiff} at the time of the last redisplay -that finished. If this value matches @code{modiff}, -@code{beg_unchanged} and @code{end_unchanged} contain no useful -information. - -@item overlay_unchanged_modified -Contains the value of @code{overlay_modiff} at the time of the last -redisplay that finished. If this value matches @code{overlay_modiff}, -@code{beg_unchanged} and @code{end_unchanged} contain no useful -information. - -@item markers -The markers that refer to this buffer. This is actually a single -marker, and successive elements in its marker @code{chain} are the other -markers referring to this buffer text. - -@item intervals -Contains the interval tree which records the text properties of this -buffer. -@end table - -The fields of @code{struct buffer} are: - -@table @code -@item next -Points to the next buffer, in the chain of all buffers including killed -buffers. This chain is used only for garbage collection, in order to -collect killed buffers properly. Note that vectors, and most kinds of -objects allocated as vectors, are all on one chain, but buffers are on a -separate chain of their own. - -@item own_text -This is a @code{struct buffer_text} structure. In an ordinary buffer, -it holds the buffer contents. In indirect buffers, this field is not -used. - -@item text -This points to the @code{buffer_text} structure that is used for this -buffer. In an ordinary buffer, this is the @code{own_text} field above. -In an indirect buffer, this is the @code{own_text} field of the base -buffer. - -@item pt -Contains the character position of point in a buffer. - -@item pt_byte -Contains the byte position of point in a buffer. - -@item begv -This field contains the character position of the beginning of the -accessible range of text in the buffer. - -@item begv_byte -This field contains the byte position of the beginning of the -accessible range of text in the buffer. - -@item zv -This field contains the character position of the end of the -accessible range of text in the buffer. - -@item zv_byte -This field contains the byte position of the end of the -accessible range of text in the buffer. - -@item base_buffer -In an indirect buffer, this points to the base buffer. In an ordinary -buffer, it is null. - -@item local_var_flags -This field contains flags indicating that certain variables are local in -this buffer. Such variables are declared in the C code using -@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored in -fields in the buffer structure itself. (Some of these fields are -described in this table.) - -@item modtime -This field contains the modification time of the visited file. It is -set when the file is written or read. Before writing the buffer into a -file, this field is compared to the modification time of the file to see -if the file has changed on disk. @xref{Buffer Modification}. - -@item auto_save_modified -This field contains the time when the buffer was last auto-saved. - -@item auto_save_failure_time -The time at which we detected a failure to auto-save, or -1 if we didn't -have a failure. - -@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 clip_changed -This flag is set when narrowing changes in a buffer. - -@item prevent_redisplay_optimizations_p -this flag indicates that redisplay optimizations should not be used -to display this buffer. - -@item undo_list -This field points to the buffer's undo list. @xref{Undo}. - -@item name -The buffer name is a string that names the buffer. It is guaranteed to -be unique. @xref{Buffer Names}. - -@item filename -The name of the file visited in this buffer, or @code{nil}. - -@item directory -The directory for expanding relative file names. - -@item save_length -Length of the file this buffer is visiting, when last read or saved. -This and other fields concerned with saving are not kept in the -@code{buffer_text} structure because indirect buffers are never saved. - -@item auto_save_file_name -File name used for auto-saving this buffer. This is not in the -@code{buffer_text} because it's not used in indirect buffers at all. - -@item read_only -Non-@code{nil} means this buffer is read-only. - -@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 describing the buffer-local -variable bindings of this buffer, not including the built-in -buffer-local bindings that have special slots in the buffer object. -(Those slots are omitted from this table.) @xref{Buffer-Local -Variables}. - -@item major_mode -Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}. - -@item mode_name -Pretty name of major mode, e.g., @code{"Lisp"}. - -@item mode_line_format -Mode line element that controls the format of the mode line. If this -is @code{nil}, no mode line will be displayed. - -@item header_line_format -This field is analogous to @code{mode_line_format} for the mode -line displayed at the top of windows. - -@item keymap -This field holds the buffer's local keymap. @xref{Keymaps}. - -@item abbrev_table -This buffer's local abbrevs. - -@item syntax_table -This field contains the syntax table for the buffer. @xref{Syntax Tables}. - -@item category_table -This field contains the category table for the buffer. - -@item case_fold_search -The value of @code{case-fold-search} in this buffer. - -@item tab_width -The value of @code{tab-width} in this buffer. - -@item fill_column -The value of @code{fill-column} in this buffer. - -@item left_margin -The value of @code{left-margin} in this buffer. - -@item auto_fill_function -The value of @code{auto-fill-function} in this buffer. - -@item downcase_table -This field contains the conversion table for converting text to lower case. -@xref{Case Tables}. - -@item upcase_table -This field contains the conversion table for converting text to upper case. -@xref{Case Tables}. - -@item case_canon_table -This field contains the conversion table for canonicalizing text for -case-folding search. @xref{Case Tables}. - -@item case_eqv_table -This field contains the equivalence table for case-folding search. -@xref{Case Tables}. - -@item truncate_lines -The value of @code{truncate-lines} in this buffer. - -@item ctl_arrow -The value of @code{ctl-arrow} in this buffer. - -@item selective_display -The value of @code{selective-display} in this buffer. - -@item selective_display_ellipsis -The value of @code{selective-display-ellipsis} in this buffer. - -@item minor_modes -An alist of the minor modes of this buffer. - -@item overwrite_mode -The value of @code{overwrite_mode} in this buffer. - -@item abbrev_mode -The value of @code{abbrev-mode} in this buffer. - -@item display_table -This field contains the buffer's display table, or @code{nil} if it doesn't -have one. @xref{Display Tables}. - -@item save_modified -This field contains the time when the buffer was last saved, as an integer. -@xref{Buffer Modification}. - -@item mark_active -This field is non-@code{nil} if the buffer's mark is active. - -@item overlays_before -This field holds a list of the overlays in this buffer that end at or -before the current overlay center position. They are sorted in order of -decreasing end position. - -@item overlays_after -This field holds a list of the overlays in this buffer that end after -the current overlay center position. They are sorted in order of -increasing beginning position. - -@item overlay_center -This field holds the current overlay center position. @xref{Overlays}. - -@item enable_multibyte_characters -This field holds the buffer's local value of -@code{enable-multibyte-characters}---either @code{t} or @code{nil}. - -@item buffer_file_coding_system -The value of @code{buffer-file-coding-system} in this buffer. - -@item file_format -The value of @code{buffer-file-format} in this buffer. - -@item auto_save_file_format -The value of @code{buffer-auto-save-file-format} in this buffer. - -@item pt_marker -In an indirect buffer, or a buffer that is the base of an indirect -buffer, this holds a marker that records point for this buffer when the -buffer is not current. - -@item begv_marker -In an indirect buffer, or a buffer that is the base of an indirect -buffer, this holds a marker that records @code{begv} for this buffer -when the buffer is not current. - -@item zv_marker -In an indirect buffer, or a buffer that is the base of an indirect -buffer, this holds a marker that records @code{zv} for this buffer when -the buffer is not current. - -@item file_truename -The truename of the visited file, or @code{nil}. - -@item invisibility_spec -The value of @code{buffer-invisibility-spec} in this buffer. - -@item last_selected_window -This is the last window that was selected with this buffer in it, or @code{nil} -if that window no longer displays this buffer. - -@item display_count -This field is incremented each time the buffer is displayed in a window. - -@item left_margin_width -The value of @code{left-margin-width} in this buffer. - -@item right_margin_width -The value of @code{right-margin-width} in this buffer. - -@item indicate_empty_lines -Non-@code{nil} means indicate empty lines (lines with no text) with a -small bitmap in the fringe, when using a window system that can do it. - -@item display_time -This holds a time stamp that is updated each time this buffer is -displayed in a window. - -@item scroll_up_aggressively -The value of @code{scroll-up-aggressively} in this buffer. - -@item scroll_down_aggressively -The value of @code{scroll-down-aggressively} in this buffer. -@end table - -@node Window 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 parent -Internally, Emacs arranges windows in a tree; each group of siblings has -a parent window whose area includes all the siblings. This field points -to a window's parent. - -Parent windows do not display buffers, and play little role in display -except to shape their child windows. Emacs Lisp programs usually have -no access to the parent windows; they operate on the windows at the -leaves of the tree, which actually display buffers. - -The following four fields also describe the window tree structure. - -@item hchild -In a window subdivided horizontally by child windows, the leftmost child. -Otherwise, @code{nil}. - -@item vchild -In a window subdivided vertically by child windows, the topmost child. -Otherwise, @code{nil}. - -@item next -The next sibling of this window. It is @code{nil} in a window that is -the rightmost or bottommost of a group of siblings. - -@item prev -The previous sibling of this window. It is @code{nil} in a window that -is the leftmost or topmost of a group of siblings. - -@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 height -The height of the window, measured in lines. - -@item width -The width of the window, measured in columns. This width includes the -scroll bar and fringes, and/or the separator line on the right of the -window (if any). - -@item buffer -The buffer that the window is displaying. This may change often during -the life of the window. - -@item start -The position in the buffer that 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 force_start -If this flag is non-@code{nil}, it says that the window has been -scrolled explicitly by the Lisp program. This affects what the next -redisplay does if point is off the screen: instead of scrolling the -window to show the text around point, it moves point to a location that -is on the screen. - -@item frozen_window_start_p -This field is set temporarily to 1 to indicate to redisplay that -@code{start} of this window should not be changed, even if point -gets invisible. - -@item start_at_line_beg -Non-@code{nil} means current value of @code{start} was the beginning of a line -when it was chosen. - -@item too_small_ok -Non-@code{nil} means don't delete this window for becoming ``too small.'' - -@item height_fixed_p -This field is temporarily set to 1 to fix the height of the selected -window when the echo area is resized. - -@item use_time -This is the last time that the window was selected. The function -@code{get-lru-window} uses this field. - -@item sequence_number -A unique number assigned to this window when it was created. - -@item last_modified -The @code{modiff} field of the window's buffer, as of the last time -a redisplay completed in this window. - -@item last_overlay_modified -The @code{overlay_modiff} field of the window's buffer, as of the last -time a redisplay completed in this window. - -@item last_point -The buffer's value of point, as of the last time a redisplay completed -in this window. - -@item last_had_star -A non-@code{nil} value means the window's buffer was ``modified'' when the -window was last updated. - -@item vertical_scroll_bar -This window's vertical scroll bar. - -@item left_margin_width -The width of the left margin in this window, or @code{nil} not to -specify it (in which case the buffer's value of @code{left-margin-width} -is used. - -@item right_margin_width -Likewise for the right margin. - -@ignore -@item last_mark_x -@item last_mark_y -???Not used. -@end ignore - -@item window_end_pos -This is computed as @code{z} minus the buffer position of the last glyph -in the current matrix of the window. The value is only valid if -@code{window_end_valid} is not @code{nil}. - -@item window_end_bytepos -The byte position corresponding to @code{window_end_pos}. - -@item window_end_vpos -The window-relative vertical position of the line containing -@code{window_end_pos}. - -@item window_end_valid -This field is set to a non-@code{nil} value if @code{window_end_pos} is truly -valid. This is @code{nil} if nontrivial redisplay is preempted since in that -case the display that @code{window_end_pos} was computed for did not get -onto the screen. - -@item redisplay_end_trigger -If redisplay in this window goes beyond this buffer position, it runs -the @code{redisplay-end-trigger-hook}. - -@ignore -@item orig_height -@item orig_top -??? Are temporary storage areas. -@end ignore - -@item cursor -A structure describing where the cursor is in this window. - -@item last_cursor -The value of @code{cursor} as of the last redisplay that finished. - -@item phys_cursor -A structure describing where the cursor of this window physically is. - -@item phys_cursor_type -The type of cursor that was last displayed on this window. - -@item phys_cursor_on_p -This field is non-zero if the cursor is physically on. - -@item cursor_off_p -Non-zero means the cursor in this window is logically on. - -@item last_cursor_off_p -This field contains the value of @code{cursor_off_p} as of the time of -the last redisplay. - -@item must_be_updated_p -This is set to 1 during redisplay when this window must be updated. - -@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 vscroll -Vertical scroll amount, in pixels. Normally, this is 0. - -@item dedicated -Non-@code{nil} if this window is dedicated to its buffer. - -@item display_table -The window's display table, or @code{nil} if none is specified for it. - -@item update_mode_line -Non-@code{nil} means this window's mode line needs to be updated. - -@item base_line_number -The line number of a certain position in the buffer, or @code{nil}. -This is used for displaying the line number of point in the mode line. - -@item base_line_pos -The position in the buffer for which the line number is known, or -@code{nil} meaning none is known. - -@item region_showing -If the region (or part of it) is highlighted in this window, this field -holds the mark position that made one end of that region. Otherwise, -this field is @code{nil}. - -@item column_number_displayed -The column number currently displayed in this window's mode line, or @code{nil} -if column numbers are not being displayed. - -@item current_matrix -A glyph matrix describing the current display of this window. - -@item desired_matrix -A glyph matrix describing the desired display of this window. -@end table - -@node Process 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 operating system's process @acronym{ID}. - -@item childp -A flag, non-@code{nil} if this is really a child process. -It is @code{nil} for a network connection. - -@item mark -A marker indicating the position of the end of the last output from this -process inserted into the buffer. This is often but not always the end -of the buffer. - -@item kill_without_query -If this is non-@code{nil}, killing Emacs while this process is still -running does not ask for confirmation about killing the process. - -@item raw_status_low -@itemx raw_status_high -These two fields record 16 bits each of the process status returned by -the @code{wait} system call. - -@item status -The process status, as @code{process-status} should return it. - -@item tick -@itemx update_tick -If these two fields are not equal, a change in the status of the process -needs to be reported, either by running the sentinel or by inserting a -message in the process buffer. - -@item pty_flag -Non-@code{nil} if communication with the subprocess uses a @acronym{PTY}; -@code{nil} if it uses a pipe. - -@item infd -The file descriptor for input from the process. - -@item outfd -The file descriptor for output to the process. - -@item subtty -The file descriptor for the terminal that the subprocess is using. (On -some systems, there is no need to record this, so the value is -@code{nil}.) - -@item tty_name -The name of the terminal that the subprocess is using, -or @code{nil} if it is using pipes. - -@item decode_coding_system -Coding-system for decoding the input from this process. - -@item decoding_buf -A working buffer for decoding. - -@item decoding_carryover -Size of carryover in decoding. - -@item encode_coding_system -Coding-system for encoding the output to this process. - -@item encoding_buf -A working buffer for encoding. - -@item encoding_carryover -Size of carryover in encoding. - -@item inherit_coding_system_flag -Flag to set @code{coding-system} of the process buffer from the -coding system used to decode process output. -@end table - -@ignore - arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e -@end ignore diff --git a/lispref/intro.texi b/lispref/intro.texi deleted file mode 100644 index ed0fd1c0699..00000000000 --- a/lispref/intro.texi +++ /dev/null @@ -1,560 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/intro - -@node Introduction, Lisp Data Types, Top, Top -@comment node-name, next, previous, up -@chapter 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 attempts to be a full description of Emacs Lisp. For a -beginner's introduction to Emacs Lisp, see @cite{An Introduction to -Emacs Lisp Programming}, by Bob Chassell, also published by the Free -Software Foundation. This manual presumes considerable familiarity with -the use of Emacs for editing; see @cite{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 @value{VERSION} of the GNU Emacs Lisp Reference -Manual, corresponding to Emacs version @value{EMACSVER}. - -@menu -* 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. -@end menu - -@node Caveats -@section Caveats -@cindex bugs in this manual - - This manual has gone through numerous drafts. It is nearly complete -but not flawless. There are a few topics that are not covered, 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 information about usage on VMS. - - 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. - -@iftex - As you use this manual, we ask that you mark pages with corrections so -you can later look them up and send them to us. 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 chapter name, section name, and function name, as appropriate, since -page numbers and chapter and section numbers will change and we may have -trouble finding the text you are talking about. Also state the number -of the edition you are criticizing. -@end iftex -@ifnottex - -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. Also state the number of the edition -you are criticizing. -@end ifnottex - -@cindex bugs -@cindex suggestions -Please mail comments and corrections to - -@example -bug-lisp-manual@@gnu.org -@end example - -@noindent -We let mail to this list accumulate unread until someone decides to -apply the corrections. Months, and sometimes years, go by between -updates. So please attach no significance to the lack of a reply---your -mail @emph{will} be acted on in due time. If you want to contact the -Emacs maintainers more quickly, send mail to -@code{bug-gnu-emacs@@gnu.org}. - -@node Lisp History -@section Lisp History -@cindex 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 ideal -for other purposes as well, such as writing editing commands. - -@cindex Maclisp -@cindex Common Lisp - 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 1960s at MIT's Project MAC. Eventually the -implementors of the descendants of Maclisp came together and developed a -standard for Lisp systems, called Common Lisp. In the meantime, Gerry -Sussman and Guy Steele at MIT developed a simplified but very powerful -dialect of Lisp, called Scheme. - - 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 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. - -@pindex cl - A certain amount of Common Lisp emulation is available via the -@file{cl} library. @inforef{Top, Overview, cl}. - - Emacs Lisp is not at all influenced by Scheme; but the GNU project has -an implementation of Scheme, called Guile. We use Guile in all new GNU -software that calls for extensibility. - -@node Conventions -@section 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 @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* 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. -@end menu - -@node Some Terms -@subsection Some Terms - - Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp -printer'' refer to those routines in Lisp that convert textual -representations of Lisp objects into actual Lisp objects, and vice -versa. @xref{Printed Representation}, for more details. You, the -person reading this manual, are thought of as ``the programmer'' and are -addressed as ``you.'' ``The user'' is the person who uses Lisp -programs, including those you write. - -@cindex fonts in this manual - Examples of Lisp code are formatted like this: @code{(list 1 2 3)}. -Names that represent metasyntactic variables, or arguments to a function -being described, are formatted like this: @var{first-number}. - -@node nil and t -@subsection @code{nil} and @code{t} -@cindex truth value -@cindex boolean - -@cindex @code{nil} -@cindex false - In Lisp, the symbol @code{nil} has three separate meanings: it -is a symbol with the name @samp{nil}; it is the logical truth value -@var{false}; and it is the empty list---the list of zero elements. -When used as a variable, @code{nil} always has the value @code{nil}. - - As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are -identical: they stand for the same object, the symbol @code{nil}. The -different ways of writing the symbol are intended entirely for human -readers. After the Lisp reader has read either @samp{()} or @samp{nil}, -there is no way to determine which representation was actually written -by the programmer. - - In this manual, we write @code{()} when we wish to emphasize that it -means the empty list, and we write @code{nil} when we wish to emphasize -that it means the truth value @var{false}. That is a good convention to use -in Lisp programs also. - -@example -(cons 'foo ()) ; @r{Emphasize the empty list} -(setq foo-flag nil) ; @r{Emphasize the truth value @var{false}} -@end example - -@cindex @code{t} -@cindex true - In contexts where a truth value is expected, any non-@code{nil} value -is considered to be @var{true}. However, @code{t} is the preferred way -to represent the truth value @var{true}. When you need to choose a -value which represents @var{true}, and there is no other basis for -choosing, use @code{t}. The symbol @code{t} always has the value -@code{t}. - - In Emacs Lisp, @code{nil} and @code{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 @code{setting-constant} error. @xref{Constant -Variables}. - -@defun booleanp object -Return non-nil if @var{object} is one of the two canonical boolean -values: @code{t} or @code{nil}. -@end defun - -@node Evaluation Notation -@subsection Evaluation Notation -@cindex evaluation notation -@cindex documentation notation -@cindex notation - - A Lisp expression that you can evaluate is called a @dfn{form}. -Evaluating a form always produces a result, which is a Lisp object. In -the examples in this manual, this is indicated with @samp{@result{}}: - -@example -(car '(1 2)) - @result{} 1 -@end example - -@noindent -You can read this as ``@code{(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 -@samp{@expansion{}}. We may or may not show the result of the -evaluation of the expanded form. - -@example -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end example - - Sometimes to help describe one form we show another form that -produces identical results. The exact equivalence of two forms is -indicated with @samp{@equiv{}}. - -@example -(make-sparse-keymap) @equiv{} (list 'keymap) -@end example - -@node Printing Notation -@subsection Printing Notation -@cindex printing notation - - Many of the examples in this manual print text when they are -evaluated. If you execute example code in a Lisp Interaction buffer -(such as the buffer @samp{*scratch*}), the printed text is inserted into -the buffer. If you execute the example by other means (such as by -evaluating the function @code{eval-region}), the printed text is -displayed in the echo area. - - Examples in this manual indicate printed text with @samp{@print{}}, -irrespective of where that text goes. The value returned by -evaluating the form (here @code{bar}) follows on a separate line with -@samp{@result{}}. - -@example -@group -(progn (prin1 'foo) (princ "\n") (prin1 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end example - -@node Error Messages -@subsection Error Messages -@cindex error message notation - - Some examples signal errors. This normally displays an error message -in the echo area. We show the error message on a line starting with -@samp{@error{}}. Note that @samp{@error{}} itself does not appear in -the echo area. - -@example -(+ 23 'x) -@error{} Wrong type argument: number-or-marker-p, x -@end example - -@node Buffer Text Notation -@subsection Buffer Text Notation -@cindex buffer text notation - - Some examples describe modifications to the contents of a buffer, by -showing the ``before'' and ``after'' versions of the text. These -examples show the contents of the buffer in question between two lines -of dashes containing the buffer name. In addition, @samp{@point{}} -indicates the location of point. (The symbol for point, of course, is -not part of the text in the buffer; it indicates the place -@emph{between} two characters where point is currently located.) - -@example ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- -@end example - -@node Format of Descriptions -@subsection Format of Descriptions -@cindex description format - - Functions, variables, macros, commands, user options, and special -forms are described in this manual in a uniform format. The first -line of a description contains the name of the item followed by its -arguments, if any. -@ifnottex -The category---function, variable, or whatever---appears at the -beginning of the line. -@end ifnottex -@iftex -The category---function, variable, or whatever---is printed next to the -right margin. -@end iftex -The description follows on succeeding lines, sometimes with examples. - -@menu -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, - @code{electric-future-map}. -@end menu - -@node A Sample Function Description -@subsubsection A Sample Function Description -@cindex function descriptions -@cindex command descriptions -@cindex macro descriptions -@cindex special form descriptions - - In a function description, the name of the function being described -appears first. It is followed on the same line by a list of argument -names. These names are also used in the body of the description, to -stand for the values of the arguments. - - The appearance of the keyword @code{&optional} in the argument list -indicates that the subsequent arguments may be omitted (omitted -arguments default to @code{nil}). Do not write @code{&optional} when -you call the function. - - The keyword @code{&rest} (which must be followed by a single -argument name) indicates that any number of arguments can follow. The -single argument name following @code{&rest} will receive, as its -value, a list of all the remaining arguments passed to the function. -Do not write @code{&rest} when you call the function. - - Here is a description of an imaginary function @code{foo}: - -@defun foo integer1 &optional integer2 &rest integers -The function @code{foo} subtracts @var{integer1} from @var{integer2}, -then adds all the rest of the arguments to the result. If @var{integer2} -is not supplied, then the number 19 is used by default. - -@example -(foo 1 5 3 9) - @result{} 16 -(foo 5) - @result{} 14 -@end example - -@need 1500 -More generally, - -@example -(foo @var{w} @var{x} @var{y}@dots{}) -@equiv{} -(+ (- @var{x} @var{w}) @var{y}@dots{}) -@end example -@end defun - - Any argument whose name contains the name of a type (e.g., -@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that -type. A plural of a type (such as @var{buffers}) often means a list of -objects of that type. Arguments named @var{object} may be of any type. -(@xref{Lisp Data Types}, for a list of Emacs object types.) Arguments -with other sorts of names (e.g., @var{new-file}) are discussed -specifically in the description of the function. In some sections, -features common to the arguments of several functions are described at -the beginning. - - @xref{Lambda Expressions}, for a more complete description of optional -and rest arguments. - - Command, macro, and special form descriptions have the same format, -but the word `Function' is replaced by `Command', `Macro', or `Special -Form', respectively. Commands are simply functions that may be called -interactively; macros process their arguments differently from functions -(the arguments are not evaluated), but are presented the same way. - - Special form descriptions use a more complex notation to specify -optional and repeated arguments because they can break the argument -list down into separate arguments in more complicated ways. -@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is -optional and @samp{@var{repeated-args}@dots{}} stands for zero or more -arguments. Parentheses are used when several arguments are grouped into -additional levels of list structure. Here is an example: - -@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -This imaginary special form implements a loop that executes the -@var{body} forms and then increments the variable @var{var} on each -iteration. On the first iteration, the variable has the value -@var{from}; on subsequent iterations, it is incremented by one (or by -@var{inc} if that is given). The loop exits before executing @var{body} -if @var{var} equals @var{to}. Here is an example: - -@example -(count-loop (i 0 10) - (prin1 i) (princ " ") - (prin1 (aref vector i)) - (terpri)) -@end example - -If @var{from} and @var{to} are omitted, @var{var} is bound to -@code{nil} before the loop begins, and the loop exits if @var{var} is -non-@code{nil} at the beginning of an iteration. Here is an example: - -@example -(count-loop (done) - (if (pending) - (fixit) - (setq done t))) -@end example - -In this special form, the arguments @var{from} and @var{to} are -optional, but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the form. -@end defspec - -@node A Sample Variable Description -@subsubsection A Sample Variable Description -@cindex variable descriptions -@cindex option descriptions - - A @dfn{variable} is a name that can hold a value. Although nearly -all variables can be set by the user, certain variables exist -specifically so that users can change them; these are called @dfn{user -options}. Ordinary variables and user options are described using a -format like that for functions except that there are no arguments. - - Here is a description of the imaginary @code{electric-future-map} -variable.@refill - -@defvar electric-future-map -The value of this variable is a full keymap used by Electric Command -Future mode. The functions in this map allow you to edit commands you -have not yet thought about executing. -@end defvar - - User option descriptions have the same format, but `Variable' is -replaced by `User Option'. - -@node Version Info -@section Version Information - - These facilities provide information about which version of Emacs is -in use. - -@deffn Command emacs-version &optional here -This function returns a string describing the version of Emacs that is -running. It is useful to include this string in bug reports. - -@smallexample -@group -(emacs-version) - @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit) - of Sat Feb 14 1998 on psilocin.gnu.org" -@end group -@end smallexample - -If @var{here} is non-@code{nil}, it inserts the text in the buffer -before point, and returns @code{nil}. Called interactively, the -function prints the same information in the echo area, but giving a -prefix argument makes @var{here} non-@code{nil}. -@end deffn - -@defvar emacs-build-time -The value of this variable indicates the time at which Emacs was built -at the local site. It is a list of three integers, like the value -of @code{current-time} (@pxref{Time of Day}). - -@example -@group -emacs-build-time - @result{} (13623 62065 344633) -@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{"20.3.1"}. The last number in this string is not -really part of the Emacs release version number; it is incremented each -time you build Emacs in any given directory. A value with four numeric -components, such as @code{"20.3.9.1"}, indicates an unreleased test -version. -@end defvar - - The following two variables have existed since Emacs version 19.23: - -@defvar emacs-major-version -The major version number of Emacs, as an integer. For Emacs version -20.3, the value is 20. -@end defvar - -@defvar emacs-minor-version -The minor version number of Emacs, as an integer. For Emacs version -20.3, the value is 3. -@end defvar - -@node Acknowledgements -@section Acknowledgements - - This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, -Richard@tie{}M. Stallman and Chris Welty, the volunteers of the GNU -manual group, in an effort extending over several years. -Robert@tie{}J. Chassell helped to review and edit the manual, with the -support of the Defense Advanced Research Projects Agency, ARPA Order -6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic, -Inc. - - Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom, -Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence -R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly -Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea, -Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki -Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe -Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland -McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson, -Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul -Rockwell, Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, -Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty, -Dale Worley, Rusty Wright, and David D. Zuhn. - -@ignore - arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa -@end ignore diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi deleted file mode 100644 index bf20680dd81..00000000000 --- a/lispref/keymaps.texi +++ /dev/null @@ -1,2785 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/keymaps -@node Keymaps, Modes, Command Loop, Top -@chapter Keymaps -@cindex keymap - - The command bindings of input events are recorded in data structures -called @dfn{keymaps}. Each entry in a keymap associates (or -@dfn{binds}) an individual event type, either to another keymap or to -a command. When an event type is bound to a keymap, that keymap is -used to look up the next input event; this continues until a command -is found. The whole process is called @dfn{key lookup}. - -@menu -* 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:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. -@end menu - -@node Key Sequences -@section Key Sequences -@cindex key -@cindex keystroke -@cindex key sequence - - A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one -or more input events that form a unit. Input events include -characters, function keys, and mouse actions (@pxref{Input Events}). -The Emacs Lisp representation for a key sequence is a string or -vector. Unless otherwise stated, any Emacs Lisp function that accepts -a key sequence as an argument can handle both representations. - - In the string representation, alphanumeric characters ordinarily -stand for themselves; for example, @code{"a"} represents @kbd{a} -and @code{"2"} represents @kbd{2}. Control character events are -prefixed by the substring @code{"\C-"}, and meta characters by -@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}. -In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events -are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and -@code{"\d"} respectively. The string representation of a complete key -sequence is the concatenation of the string representations of the -constituent events; thus, @code{"\C-xl"} represents the key sequence -@kbd{C-x l}. - - Key sequences containing function keys, mouse button events, or -non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be -represented as strings; they have to be represented as vectors. - - In the vector representation, each element of the vector represents -an input event, in its Lisp form. @xref{Input Events}. For example, -the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}. - - For examples of key sequences written in string and vector -representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}. - -@defmac kbd keyseq-text -This macro converts the text @var{keyseq-text} (a string constant) -into a key sequence (a string or vector constant). The contents of -@var{keyseq-text} should describe the key sequence using almost the same -syntax used in this manual. More precisely, it uses the same syntax -that Edit Macro mode uses for editing keyboard macros (@pxref{Edit -Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround -function key names with @samp{<@dots{}>}. - -@example -(kbd "C-x") @result{} "\C-x" -(kbd "C-x C-f") @result{} "\C-x\C-f" -(kbd "C-x 4 C-f") @result{} "\C-x4\C-f" -(kbd "X") @result{} "X" -(kbd "RET") @result{} "\^M" -(kbd "C-c SPC") @result{} "\C-c@ " -(kbd "<f1> SPC") @result{} [f1 32] -(kbd "C-M-<down>") @result{} [C-M-down] -@end example - -This macro is not meant for use with arguments that vary---only -with string constants. -@end defmac - -@node Keymap Basics -@section Keymap Basics -@cindex key binding -@cindex binding of a key -@cindex complete key -@cindex undefined key - - A keymap is a Lisp data structure that specifies @dfn{key bindings} -for various key sequences. - - A single keymap directly specifies definitions for individual -events. When a key sequence consists of a single event, its binding -in a keymap is the keymap's definition for that event. The binding of -a longer key sequence is found by an iterative process: first find the -definition of the first event (which must itself be a keymap); then -find the second event's definition in that keymap, and so on until all -the events in the key sequence have been processed. - - If the binding of a key sequence is a keymap, we call the key sequence -a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because -no more events can be added to it). If the binding is @code{nil}, -we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c}, -@kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are -@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete -keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more -details. - - The rule for finding the binding of a key sequence assumes that the -intermediate bindings (found for the events before the last) are all -keymaps; if this is not so, the sequence of events does not form a -unit---it is not really one key sequence. In other words, removing one -or more events from the end of any valid key sequence must always yield -a prefix key. For example, @kbd{C-f C-n} is not a key sequence; -@kbd{C-f} is not a prefix key, so a longer sequence starting with -@kbd{C-f} cannot be a key sequence. - - The set of possible multi-event key sequences depends on the bindings -for prefix keys; therefore, it can be different for different keymaps, -and can change when bindings are changed. However, a one-event sequence -is always a key sequence, because it does not depend on any prefix keys -for its well-formedness. - - At any time, several primary keymaps are @dfn{active}---that is, in -use for finding key bindings. These are the @dfn{global map}, which is -shared by all buffers; the @dfn{local keymap}, which is usually -associated with a specific major mode; and zero or more @dfn{minor mode -keymaps}, which belong to currently enabled minor modes. (Not all minor -modes have keymaps.) The local keymap bindings shadow (i.e., take -precedence over) the corresponding global bindings. The minor mode -keymaps shadow both local and global keymaps. @xref{Active Keymaps}, -for details. - -@node Format of Keymaps -@section Format of Keymaps -@cindex format of keymaps -@cindex keymap format -@cindex full keymap -@cindex sparse keymap - - Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The -remaining elements of the list define the key bindings of the keymap. -A symbol whose function definition is a keymap is also a keymap. Use -the function @code{keymapp} (see below) to test whether an object is a -keymap. - - Several kinds of elements may appear in a keymap, after the symbol -@code{keymap} that begins it: - -@table @code -@item (@var{type} .@: @var{binding}) -This specifies one binding, for events of type @var{type}. Each -ordinary binding applies to events of a particular @dfn{event type}, -which is always a character or a symbol. @xref{Classifying Events}. -In this kind of binding, @var{binding} is a command. - -@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding}) -This specifies a binding which is also a simple menu item that -displays as @var{item-name} in the menu. @var{cache}, if present, -caches certain information for display in the menu. @xref{Simple Menu -Items}. - -@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding}) -This is a simple menu item with help string @var{help-string}. - -@item (@var{type} menu-item .@: @var{details}) -This specifies a binding which is also an extended menu item. This -allows use of other features. @xref{Extended Menu Items}. - -@item (t .@: @var{binding}) -@cindex default key binding -This specifies a @dfn{default key binding}; any event not bound by other -elements of the keymap is given @var{binding} as its binding. Default -bindings allow a keymap to bind all possible event types without having -to enumerate all of them. A keymap that has a default binding -completely masks any lower-precedence keymap, except for events -explicitly bound to @code{nil} (see below). - -@item @var{char-table} -If an element of a keymap is a char-table, it counts as holding -bindings for all character events with no modifier bits -(@pxref{modifier bits}): element @var{n} is the binding for the -character with code @var{n}. This is a compact way to record lots of -bindings. A keymap with such a char-table is called a @dfn{full -keymap}. Other keymaps are called @dfn{sparse keymaps}. - -@item @var{string} -@cindex keymap prompt string -@cindex overall prompt string -@cindex prompt string of keymap -Aside from elements that specify bindings for keys, a keymap can also -have a string as an element. This is called the @dfn{overall prompt -string} and makes it possible to use the keymap as a menu. -@xref{Defining Menus}. -@end table - -When the binding is @code{nil}, it doesn't constitute a definition -but it does take precedence over a default binding or a binding in the -parent keymap. On the other hand, a binding of @code{nil} does -@emph{not} override lower-precedence keymaps; thus, if the local map -gives a binding of @code{nil}, Emacs uses the binding from the -global map. - -@cindex meta characters lookup - Keymaps do not directly record bindings for the meta characters. -Instead, meta characters are regarded for purposes of key lookup as -sequences of two characters, the first of which is @key{ESC} (or -whatever is currently the value of @code{meta-prefix-char}). Thus, the -key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its -global binding is found at the slot for @kbd{a} in @code{esc-map} -(@pxref{Prefix Keys}). - - This conversion applies only to characters, not to function keys or -other input events; thus, @kbd{M-@key{end}} has nothing to do with -@kbd{@key{ESC} @key{end}}. - - Here as an example is the local keymap for Lisp mode, a sparse -keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c -C-l}, @kbd{M-C-q}, and @kbd{M-C-x}. - -@example -@group -lisp-mode-map -@result{} -@end group -@group -(keymap - (3 keymap - ;; @kbd{C-c C-z} - (26 . run-lisp)) -@end group -@group - (27 keymap - ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}} - (24 . lisp-send-defun) - keymap - ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp)) -@end group -@group - ;; @r{This part is inherited from @code{lisp-mode-shared-map}.} - keymap - ;; @key{DEL} - (127 . backward-delete-char-untabify) -@end group -@group - (27 keymap - ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp)) - (9 . lisp-indent-line)) -@end group -@end example - -@defun keymapp object -This function returns @code{t} if @var{object} is a keymap, @code{nil} -otherwise. More precisely, this function tests for a list whose -@sc{car} is @code{keymap}, or for a symbol whose function definition -satisfies @code{keymapp}. - -@example -@group -(keymapp '(keymap)) - @result{} t -@end group -@group -(fset 'foo '(keymap)) -(keymapp 'foo) - @result{} t -@end group -@group -(keymapp (current-global-map)) - @result{} t -@end group -@end example -@end defun - -@node Creating Keymaps -@section Creating Keymaps -@cindex creating keymaps - - Here we describe the functions for creating keymaps. - -@defun make-sparse-keymap &optional prompt -This function creates and returns a new sparse keymap with no entries. -(A sparse keymap is the kind of keymap you usually want.) The new -keymap does not contain a char-table, unlike @code{make-keymap}, and -does not bind any events. - -@example -@group -(make-sparse-keymap) - @result{} (keymap) -@end group -@end example - -If you specify @var{prompt}, that becomes the overall prompt string -for the keymap. You should specify this only for menu keymaps -(@pxref{Defining Menus}). A keymap with an overall prompt string will -always present a mouse menu or a keyboard menu if it is active for -looking up the next input event. Don't specify an overall prompt string -for the main map of a major or minor mode, because that would cause -the command loop to present a keyboard menu every time. -@end defun - -@defun make-keymap &optional prompt -This function creates and returns a new full keymap. That keymap -contains a char-table (@pxref{Char-Tables}) with slots for all -characters without modifiers. The new keymap initially binds all -these characters to @code{nil}, and does not bind any other kind of -event. The argument @var{prompt} specifies a -prompt string, as in @code{make-sparse-keymap}. - -@example -@group -(make-keymap) - @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap]) -@end group -@end example - -A full keymap is more efficient than a sparse keymap when it holds -lots of bindings; for just a few, the sparse keymap is better. -@end defun - -@defun copy-keymap keymap -This function returns a copy of @var{keymap}. Any keymaps that -appear directly as bindings in @var{keymap} are also copied recursively, -and so on to any number of levels. However, recursive copying does not -take place when the definition of a character is a symbol whose function -definition is a keymap; the same symbol appears in the new copy. -@c Emacs 19 feature - -@example -@group -(setq map (copy-keymap (current-local-map))) -@result{} (keymap -@end group -@group - ;; @r{(This implements meta characters.)} - (27 keymap - (83 . center-paragraph) - (115 . center-line)) - (9 . tab-to-tab-stop)) -@end group - -@group -(eq map (current-local-map)) - @result{} nil -@end group -@group -(equal map (current-local-map)) - @result{} t -@end group -@end example -@end defun - -@node Inheritance and Keymaps -@section Inheritance and Keymaps -@cindex keymap inheritance -@cindex inheriting a keymap's bindings - - A keymap can inherit the bindings of another keymap, which we call the -@dfn{parent keymap}. Such a keymap looks like this: - -@example -(keymap @var{elements}@dots{} . @var{parent-keymap}) -@end example - -@noindent -The effect is that this keymap inherits all the bindings of -@var{parent-keymap}, whatever they may be at the time a key is looked up, -but can add to them or override them with @var{elements}. - -If you change the bindings in @var{parent-keymap} using -@code{define-key} or other key-binding functions, these changed -bindings are visible in the inheriting keymap, unless shadowed by the -bindings made by @var{elements}. The converse is not true: if you use -@code{define-key} to change bindings in the inheriting keymap, these -changes are recorded in @var{elements}, but have no effect on -@var{parent-keymap}. - -The proper way to construct a keymap with a parent is to use -@code{set-keymap-parent}; if you have code that directly constructs a -keymap with a parent, please convert the program to use -@code{set-keymap-parent} instead. - -@defun keymap-parent keymap -This returns the parent keymap of @var{keymap}. If @var{keymap} -has no parent, @code{keymap-parent} returns @code{nil}. -@end defun - -@defun set-keymap-parent keymap parent -This sets the parent keymap of @var{keymap} to @var{parent}, and returns -@var{parent}. If @var{parent} is @code{nil}, this function gives -@var{keymap} no parent at all. - -If @var{keymap} has submaps (bindings for prefix keys), they too receive -new parent keymaps that reflect what @var{parent} specifies for those -prefix keys. -@end defun - - Here is an example showing how to make a keymap that inherits -from @code{text-mode-map}: - -@example -(let ((map (make-sparse-keymap))) - (set-keymap-parent map text-mode-map) - map) -@end example - - A non-sparse keymap can have a parent too, but this is not very -useful. A non-sparse keymap always specifies something as the binding -for every numeric character code without modifier bits, even if it is -@code{nil}, so these character's bindings are never inherited from -the parent keymap. - -@node Prefix Keys -@section Prefix Keys -@cindex prefix key - - A @dfn{prefix key} is a key sequence whose binding is a keymap. The -keymap defines what to do with key sequences that extend the prefix key. -For example, @kbd{C-x} is a prefix key, and it uses a keymap that is -also stored in the variable @code{ctl-x-map}. This keymap defines -bindings for key sequences starting with @kbd{C-x}. - - Some of the standard Emacs prefix keys use keymaps that are -also found in Lisp variables: - -@itemize @bullet -@item -@vindex esc-map -@findex ESC-prefix -@code{esc-map} is the global keymap for the @key{ESC} prefix key. Thus, -the global definitions of all meta characters are actually found here. -This map is also the function definition of @code{ESC-prefix}. - -@item -@cindex @kbd{C-h} -@code{help-map} is the global keymap for the @kbd{C-h} prefix key. - -@item -@cindex @kbd{C-c} -@vindex mode-specific-map -@code{mode-specific-map} is the global keymap for the prefix key -@kbd{C-c}. This map is actually global, not mode-specific, but its name -provides useful information about @kbd{C-c} in the output of @kbd{C-h b} -(@code{display-bindings}), since the main use of this prefix key is for -mode-specific bindings. - -@item -@cindex @kbd{C-x} -@vindex ctl-x-map -@findex Control-X-prefix -@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key. -This map is found via the function cell of the symbol -@code{Control-X-prefix}. - -@item -@cindex @kbd{C-x @key{RET}} -@vindex mule-keymap -@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}} -prefix key. - -@item -@cindex @kbd{C-x 4} -@vindex ctl-x-4-map -@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix -key. - -@c Emacs 19 feature -@item -@cindex @kbd{C-x 5} -@vindex ctl-x-5-map -@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix -key. - -@c Emacs 19 feature -@item -@cindex @kbd{C-x 6} -@vindex 2C-mode-map -@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix -key. - -@item -@cindex @kbd{C-x v} -@vindex vc-prefix-map -@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix -key. - -@item -@cindex @kbd{M-o} -@vindex facemenu-keymap -@code{facemenu-keymap} is the global keymap used for the @kbd{M-o} -prefix key. - -@c Emacs 19 feature -@item -The other Emacs prefix keys are @kbd{M-g}, @kbd{C-x @@}, @kbd{C-x a i}, -@kbd{C-x @key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps -that have no special names. -@end itemize - - The keymap binding of a prefix key is used for looking up the event -that follows the prefix key. (It may instead be a symbol whose function -definition is a keymap. The effect is the same, but the symbol serves -as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the -symbol @code{Control-X-prefix}, whose function cell holds the keymap -for @kbd{C-x} commands. (The same keymap is also the value of -@code{ctl-x-map}.) - - Prefix key definitions can appear in any active keymap. The -definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix -keys appear in the global map, so these prefix keys are always -available. Major and minor modes can redefine a key as a prefix by -putting a prefix key definition for it in the local map or the minor -mode's map. @xref{Active Keymaps}. - - If a key is defined as a prefix in more than one active map, then its -various definitions are in effect merged: the commands defined in the -minor mode keymaps come first, followed by those in the local map's -prefix definition, and then by those from the global map. - - In the following example, we make @kbd{C-p} a prefix key in the local -keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then -the binding for @kbd{C-p C-f} is the function @code{find-file}, just -like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any -active keymap. - -@example -@group -(use-local-map (make-sparse-keymap)) - @result{} nil -@end group -@group -(local-set-key "\C-p" ctl-x-map) - @result{} nil -@end group -@group -(key-binding "\C-p\C-f") - @result{} find-file -@end group - -@group -(key-binding "\C-p6") - @result{} nil -@end group -@end example - -@defun define-prefix-command symbol &optional mapvar prompt -@cindex prefix command -@anchor{Definition of define-prefix-command} -This function prepares @var{symbol} for use as a prefix key's binding: -it creates a sparse keymap and stores it as @var{symbol}'s function -definition. Subsequently binding a key sequence to @var{symbol} will -make that key sequence into a prefix key. The return value is @code{symbol}. - -This function also sets @var{symbol} as a variable, with the keymap as -its value. But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar} -as a variable instead. - -If @var{prompt} is non-@code{nil}, that becomes the overall prompt -string for the keymap. The prompt string should be given for menu keymaps -(@pxref{Defining Menus}). -@end defun - -@node Active Keymaps -@section Active Keymaps -@cindex active keymap -@cindex global keymap -@cindex local keymap - - Emacs normally contains many keymaps; at any given time, just a few -of them are @dfn{active}, meaning that they participate in the -interpretation of user input. All the active keymaps are used -together to determine what command to execute when a key is entered. - - Normally the active keymaps are the @code{keymap} property keymap, -the keymaps of any enabled minor modes, the current buffer's local -keymap, and the global keymap, in that order. Emacs searches for each -input key sequence in all these keymaps. @xref{Searching Keymaps}, -for more details of this procedure. - - When the key sequence starts with a mouse event (optionally preceded -by a symbolic prefix), the active keymaps are determined based on the -position in that event. If the event happened on a string embedded -with a @code{display}, @code{before-string}, or @code{after-string} -property (@pxref{Special Properties}), the non-@code{nil} map -properties of the string override those of the buffer. - - The @dfn{global keymap} holds the bindings of keys that are defined -regardless of the current buffer, such as @kbd{C-f}. The variable -@code{global-map} holds this keymap, which is always active. - - Each buffer may have another keymap, its @dfn{local keymap}, which -may contain new or overriding definitions for keys. The current -buffer's local keymap is always active except when -@code{overriding-local-map} overrides it. The @code{local-map} text -or overlay property can specify an alternative local keymap for certain -parts of the buffer; see @ref{Special Properties}. - - Each minor mode can have a keymap; if it does, the keymap is active -when the minor mode is enabled. Modes for emulation can specify -additional active keymaps through the variable -@code{emulation-mode-map-alists}. - - The highest precedence normal keymap comes from the @code{keymap} -text or overlay property. If that is non-@code{nil}, it is the first -keymap to be processed, in normal circumstances. - - However, there are also special ways for programs to substitute -other keymaps for some of those. The variable -@code{overriding-local-map}, if non-@code{nil}, specifies a keymap -that replaces all the usual active keymaps except the global keymap. -Another way to do this is with @code{overriding-terminal-local-map}; -it operates on a per-terminal basis. These variables are documented -below. - -@cindex major mode keymap - Since every buffer that uses the same major mode normally uses the -same local keymap, you can think of the keymap as local to the mode. A -change to the local keymap of a buffer (using @code{local-set-key}, for -example) is seen also in the other buffers that share that keymap. - - The local keymaps that are used for Lisp mode and some other major -modes exist even if they have not yet been used. These local keymaps are -the values of variables such as @code{lisp-mode-map}. For most major -modes, which are less frequently used, the local keymap is constructed -only when the mode is used for the first time in a session. - - The minibuffer has local keymaps, too; they contain various completion -and exit commands. @xref{Intro to Minibuffers}. - - Emacs has other keymaps that are used in a different way---translating -events within @code{read-key-sequence}. @xref{Translation Keymaps}. - - @xref{Standard Keymaps}, for a list of standard keymaps. - -@defun current-active-maps &optional olp position -This returns the list of active keymaps that would be used by the -command loop in the current circumstances to look up a key sequence. -Normally it ignores @code{overriding-local-map} and -@code{overriding-terminal-local-map}, but if @var{olp} is non-@code{nil} -then it pays attention to them. @var{position} can optionally be either -an event position as returned by @code{event-start} or a buffer -position, and may change the keymaps as described for -@code{key-binding}. -@end defun - -@defun key-binding key &optional accept-defaults no-remap position -This function returns the binding for @var{key} according to the -current active keymaps. The result is @code{nil} if @var{key} is -undefined in the keymaps. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}). - -When commands are remapped (@pxref{Remapping Commands}), -@code{key-binding} normally processes command remappings so as to -returns the remapped command that will actually be executed. However, -if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores -remappings and returns the binding directly specified for @var{key}. - -If @var{key} starts with a mouse event (perhaps following a prefix -event), the maps to be consulted are determined based on the event's -position. Otherwise, they are determined based on the value of point. -However, you can override either of them by specifying @var{position}. -If @var{position} is non-@code{nil}, it should be either a buffer -position or an event position like the value of @code{event-start}. -Then the maps consulted are determined based on @var{position}. - -An error is signaled if @var{key} is not a string or a vector. - -@example -@group -(key-binding "\C-x\C-f") - @result{} find-file -@end group -@end example -@end defun - -@node Searching Keymaps -@section Searching the Active Keymaps -@cindex searching active keymaps for keys - - After translation of event subsequences (@pxref{Translation -Keymaps}) Emacs looks for them in the active keymaps. Here is a -pseudo-Lisp description of the order and conditions for searching -them: - -@lisp -(or (if overriding-terminal-local-map - (@var{find-in} overriding-terminal-local-map) - (if overriding-local-map - (@var{find-in} overriding-local-map) - (or (@var{find-in} (get-char-property (point) 'keymap)) - (@var{find-in-any} emulation-mode-map-alists) - (@var{find-in-any} minor-mode-overriding-map-alist) - (@var{find-in-any} minor-mode-map-alist) - (if (get-text-property (point) 'local-map) - (@var{find-in} (get-char-property (point) 'local-map)) - (@var{find-in} (current-local-map)))))) - (@var{find-in} (current-global-map))) -@end lisp - -@noindent -The @var{find-in} and @var{find-in-any} are pseudo functions that -search in one keymap and in an alist of keymaps, respectively. -(Searching a single keymap for a binding is called @dfn{key lookup}; -see @ref{Key Lookup}.) If the key sequence starts with a mouse event, -or a symbolic prefix event followed by a mouse event, that event's -position is used instead of point and the current buffer. Mouse -events on an embedded string use non-@code{nil} text properties from -that string instead of the buffer. - -@enumerate -@item -The function finally found may be remapped -(@pxref{Remapping Commands}). - -@item -Characters that are bound to @code{self-insert-command} are translated -according to @code{translation-table-for-input} before insertion. - -@item -@code{current-active-maps} returns a list of the -currently active keymaps at point. - -@item -When a match is found (@pxref{Key Lookup}), if the binding in the -keymap is a function, the search is over. However if the keymap entry -is a symbol with a value or a string, Emacs replaces the input key -sequences with the variable's value or the string, and restarts the -search of the active keymaps. -@end enumerate - -@node Controlling Active Maps -@section Controlling the Active Keymaps - -@defvar global-map -This variable contains the default global keymap that maps Emacs -keyboard input to commands. The global keymap is normally this -keymap. The default global keymap is a full keymap that binds -@code{self-insert-command} to all of the printing characters. - -It is normal practice to change the bindings in the global keymap, but you -should not assign this variable any value other than the keymap it starts -out with. -@end defvar - -@defun current-global-map -This function returns the current global keymap. This is the -same as the value of @code{global-map} unless you change one or the -other. - -@example -@group -(current-global-map) -@result{} (keymap [set-mark-command beginning-of-line @dots{} - delete-backward-char]) -@end group -@end example -@end defun - -@defun current-local-map -This function returns the current buffer's local keymap, or @code{nil} -if it has none. In the following example, the keymap for the -@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap -in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse -keymap. - -@example -@group -(current-local-map) -@result{} (keymap - (10 . eval-print-last-sexp) - (9 . lisp-indent-line) - (127 . backward-delete-char-untabify) -@end group -@group - (27 keymap - (24 . eval-defun) - (17 . indent-sexp))) -@end group -@end example -@end defun - -@defun current-minor-mode-maps -This function returns a list of the keymaps of currently enabled minor modes. -@end defun - -@defun use-global-map keymap -This function makes @var{keymap} the new current global keymap. It -returns @code{nil}. - -It is very unusual to change the global keymap. -@end defun - -@defun use-local-map keymap -This function makes @var{keymap} the new local keymap of the current -buffer. If @var{keymap} is @code{nil}, then the buffer has no local -keymap. @code{use-local-map} returns @code{nil}. Most major mode -commands use this function. -@end defun - -@c Emacs 19 feature -@defvar minor-mode-map-alist -@anchor{Definition of minor-mode-map-alist} -This variable is an alist describing keymaps that may or may not be -active according to the values of certain variables. Its elements look -like this: - -@example -(@var{variable} . @var{keymap}) -@end example - -The keymap @var{keymap} is active whenever @var{variable} has a -non-@code{nil} value. Typically @var{variable} is the variable that -enables or disables a minor mode. @xref{Keymaps and Minor Modes}. - -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. The @sc{cdr} can be either a keymap (a list) or a symbol whose -function definition is a keymap. - -When more than one minor mode keymap is active, the earlier one in -@code{minor-mode-map-alist} takes priority. 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. - -See @ref{Keymaps and Minor Modes}, for more information about minor -modes. See also @code{minor-mode-key-binding} (@pxref{Functions for Key -Lookup}). -@end defvar - -@defvar minor-mode-overriding-map-alist -This variable allows major modes to override the key bindings for -particular minor modes. The elements of this alist look like the -elements of @code{minor-mode-map-alist}: @code{(@var{variable} -. @var{keymap})}. - -If a variable appears as an element of -@code{minor-mode-overriding-map-alist}, the map specified by that -element totally replaces any map specified for the same variable in -@code{minor-mode-map-alist}. - -@code{minor-mode-overriding-map-alist} is automatically buffer-local in -all buffers. -@end defvar - -@defvar overriding-local-map -If non-@code{nil}, this variable holds a keymap to use instead of the -buffer's local keymap, any text property or overlay keymaps, and any -minor mode keymaps. This keymap, if specified, overrides all other -maps that would have been active, except for the current global map. -@end defvar - -@defvar overriding-terminal-local-map -If non-@code{nil}, this variable holds a keymap to use instead of -@code{overriding-local-map}, the buffer's local keymap, text property -or overlay keymaps, and all the minor mode keymaps. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Displays}. It is used to implement -incremental search mode. -@end defvar - -@defvar overriding-local-map-menu-flag -If this variable is non-@code{nil}, the value of -@code{overriding-local-map} or @code{overriding-terminal-local-map} can -affect the display of the menu bar. The default value is @code{nil}, so -those map variables have no effect on the menu bar. - -Note that these two map variables do affect the execution of key -sequences entered using the menu bar, even if they do not affect the -menu bar display. So if a menu bar key sequence comes in, you should -clear the variables before looking up and executing that key sequence. -Modes that use the variables would typically do this anyway; normally -they respond to events that they do not handle by ``unreading'' them and -exiting. -@end defvar - -@defvar special-event-map -This variable holds a keymap for special events. If an event type has a -binding in this keymap, then it is special, and the binding for the -event is run directly by @code{read-event}. @xref{Special Events}. -@end defvar - -@defvar emulation-mode-map-alists -This variable holds a list of keymap alists to use for emulations -modes. It is intended for modes or packages using multiple minor-mode -keymaps. Each element is a keymap alist which has the same format and -meaning as @code{minor-mode-map-alist}, or a symbol with a variable -binding which is such an alist. The ``active'' keymaps in each alist -are used before @code{minor-mode-map-alist} and -@code{minor-mode-overriding-map-alist}. -@end defvar - -@node Key Lookup -@section Key Lookup -@cindex key lookup -@cindex keymap entry - - @dfn{Key lookup} is the process of finding the binding of a key -sequence from a given keymap. The execution or use of the binding is -not part of key lookup. - - Key lookup uses just the event type of each event in the key sequence; -the rest of the event is ignored. In fact, a key sequence used for key -lookup may designate a mouse event with just its types (a symbol) -instead of the entire event (a list). @xref{Input Events}. Such -a ``key sequence'' is insufficient for @code{command-execute} to run, -but it is sufficient for looking up or rebinding a key. - - When the key sequence consists of multiple events, key lookup -processes the events sequentially: the binding of the first event is -found, and must be a keymap; then the second event's binding is found in -that keymap, and so on until all the events in the key sequence are used -up. (The binding thus found for the last event may or may not be a -keymap.) Thus, the process of key lookup is defined in terms of a -simpler process for looking up a single event in a keymap. How that is -done depends on the type of object associated with the event in that -keymap. - - Let's use the term @dfn{keymap entry} to describe the value found by -looking up an event type in a keymap. (This doesn't include the item -string and other extra elements in a keymap element for a menu item, because -@code{lookup-key} and other key lookup functions don't include them in -the returned value.) While any Lisp object may be stored in a keymap -as a keymap entry, not all make sense for key lookup. Here is a table -of the meaningful types of keymap entries: - -@table @asis -@item @code{nil} -@cindex @code{nil} in keymap -@code{nil} means that the events used so far in the lookup form an -undefined key. When a keymap fails to mention an event type at all, and -has no default binding, that is equivalent to a binding of @code{nil} -for that event type. - -@item @var{command} -@cindex command in keymap -The events used so far in the lookup form a complete key, -and @var{command} is its binding. @xref{What Is a Function}. - -@item @var{array} -@cindex string in keymap -The array (either a string or a vector) is a keyboard macro. The events -used so far in the lookup form a complete key, and the array is its -binding. See @ref{Keyboard Macros}, for more information. - -@item @var{keymap} -@cindex keymap in keymap -The events used so far in the lookup form a prefix key. The next -event of the key sequence is looked up in @var{keymap}. - -@item @var{list} -@cindex list in keymap -The meaning of a list depends on what it contains: - -@itemize @bullet -@item -If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list -is a keymap, and is treated as a keymap (see above). - -@item -@cindex @code{lambda} in keymap -If the @sc{car} of @var{list} is @code{lambda}, then the list is a -lambda expression. This is presumed to be a function, and is treated -as such (see above). In order to execute properly as a key binding, -this function must be a command---it must have an @code{interactive} -specification. @xref{Defining Commands}. - -@item -If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event -type, then this is an @dfn{indirect entry}: - -@example -(@var{othermap} . @var{othertype}) -@end example - -When key lookup encounters an indirect entry, it looks up instead the -binding of @var{othertype} in @var{othermap} and uses that. - -This feature permits you to define one key as an alias for another key. -For example, an entry whose @sc{car} is the keymap called @code{esc-map} -and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global -binding of @kbd{Meta-@key{SPC}}, whatever that may be.'' -@end itemize - -@item @var{symbol} -@cindex symbol in keymap -The function definition of @var{symbol} is used in place of -@var{symbol}. If that too is a symbol, then this process is repeated, -any number of times. Ultimately this should lead to an object that is -a keymap, a command, or a keyboard macro. A list is allowed if it is a -keymap or a command, but indirect entries are not understood when found -via symbols. - -Note that keymaps and keyboard macros (strings and vectors) are not -valid functions, so a symbol with a keymap, string, or vector as its -function definition is invalid as a function. It is, however, valid as -a key binding. If the definition is a keyboard macro, then the symbol -is also valid as an argument to @code{command-execute} -(@pxref{Interactive Call}). - -@cindex @code{undefined} in keymap -The symbol @code{undefined} is worth special mention: it means to treat -the key as undefined. Strictly speaking, the key is defined, and its -binding is the command @code{undefined}; but that command does the same -thing that is done automatically for an undefined key: it rings the bell -(by calling @code{ding}) but does not signal an error. - -@cindex preventing prefix key -@code{undefined} is used in local keymaps to override a global key -binding and make the key ``undefined'' locally. A local binding of -@code{nil} would fail to do this because it would not override the -global binding. - -@item @var{anything else} -If any other type of object is found, the events used so far in the -lookup form a complete key, and the object is its binding, but the -binding is not executable as a command. -@end table - - In short, a keymap entry may be a keymap, a command, a keyboard macro, -a symbol that leads to one of them, or an indirection or @code{nil}. -Here is an example of a sparse keymap with two characters bound to -commands and one bound to another keymap. This map is the normal value -of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB}, -127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for -@kbd{C-x}. - -@example -@group -(keymap (9 . lisp-indent-line) - (127 . backward-delete-char-untabify) - (27 keymap (17 . indent-sexp) (24 . eval-defun))) -@end group -@end example - -@node Functions for Key Lookup -@section Functions for Key Lookup - - Here are the functions and variables pertaining to key lookup. - -@defun lookup-key keymap key &optional accept-defaults -This function returns the definition of @var{key} in @var{keymap}. All -the other functions described in this chapter that look up keys use -@code{lookup-key}. Here are examples: - -@example -@group -(lookup-key (current-global-map) "\C-x\C-f") - @result{} find-file -@end group -@group -(lookup-key (current-global-map) (kbd "C-x C-f")) - @result{} find-file -@end group -@group -(lookup-key (current-global-map) "\C-x\C-f12345") - @result{} 2 -@end group -@end example - -If the string or vector @var{key} is not a valid key sequence according -to the prefix keys specified in @var{keymap}, it must be ``too long'' -and have extra events at the end that do not fit into a single key -sequence. Then the value is a number, the number of events at the front -of @var{key} that compose a complete key. - -@c Emacs 19 feature -If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} -considers default bindings as well as bindings for the specific events -in @var{key}. Otherwise, @code{lookup-key} reports only bindings for -the specific sequence @var{key}, ignoring default bindings except when -you explicitly ask about them. (To do this, supply @code{t} as an -element of @var{key}; see @ref{Format of Keymaps}.) - -If @var{key} contains a meta character (not a function key), that -character is implicitly replaced by a two-character sequence: the value -of @code{meta-prefix-char}, followed by the corresponding non-meta -character. Thus, the first example below is handled by conversion into -the second example. - -@example -@group -(lookup-key (current-global-map) "\M-f") - @result{} forward-word -@end group -@group -(lookup-key (current-global-map) "\ef") - @result{} forward-word -@end group -@end example - -Unlike @code{read-key-sequence}, this function does not modify the -specified events in ways that discard information (@pxref{Key Sequence -Input}). In particular, it does not convert letters to lower case and -it does not change drag events to clicks. -@end defun - -@deffn Command undefined -Used in keymaps to undefine keys. It calls @code{ding}, but does -not cause an error. -@end deffn - -@defun local-key-binding key &optional accept-defaults -This function returns the binding for @var{key} in the current -local keymap, or @code{nil} if it is undefined there. - -@c Emacs 19 feature -The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). -@end defun - -@defun global-key-binding key &optional accept-defaults -This function returns the binding for command @var{key} in the -current global keymap, or @code{nil} if it is undefined there. - -@c Emacs 19 feature -The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). -@end defun - -@c Emacs 19 feature -@defun minor-mode-key-binding key &optional accept-defaults -This function returns a list of all the active minor mode bindings of -@var{key}. More precisely, it returns an alist of pairs -@code{(@var{modename} . @var{binding})}, where @var{modename} is the -variable that enables the minor mode, and @var{binding} is @var{key}'s -binding in that mode. If @var{key} has no minor-mode bindings, the -value is @code{nil}. - -If the first binding found is not a prefix definition (a keymap or a -symbol defined as a keymap), all subsequent bindings from other minor -modes are omitted, since they would be completely shadowed. Similarly, -the list omits non-prefix bindings that follow prefix bindings. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (above). -@end defun - -@defvar meta-prefix-char -@cindex @key{ESC} -This variable is the meta-prefix character code. It is used for -translating a meta character to a two-character sequence so it can be -looked up in a keymap. For useful results, the value should be a -prefix event (@pxref{Prefix Keys}). The default value is 27, which is -the @acronym{ASCII} code for @key{ESC}. - -As long as the value of @code{meta-prefix-char} remains 27, key lookup -translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined -as the @code{backward-word} command. However, if you were to set -@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will -translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the -@code{switch-to-buffer} command. (Don't actually do this!) Here is an -illustration of what would happen: - -@smallexample -@group -meta-prefix-char ; @r{The default value.} - @result{} 27 -@end group -@group -(key-binding "\M-b") - @result{} backward-word -@end group -@group -?\C-x ; @r{The print representation} - @result{} 24 ; @r{of a character.} -@end group -@group -(setq meta-prefix-char 24) - @result{} 24 -@end group -@group -(key-binding "\M-b") - @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is} - ; @r{like typing @kbd{C-x b}.} - -(setq meta-prefix-char 27) ; @r{Avoid confusion!} - @result{} 27 ; @r{Restore the default value!} -@end group -@end smallexample - -This translation of one event into two happens only for characters, not -for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function -key, is not converted into @kbd{@key{ESC} @key{F1}}. -@end defvar - -@node Changing Key Bindings -@section Changing Key Bindings -@cindex changing key bindings -@cindex rebinding - - The way to rebind a key is to change its entry in a keymap. If you -change a binding in the global keymap, the change is effective in all -buffers (though it has no direct effect in buffers that shadow the -global binding with a local one). If you change the current buffer's -local map, that usually affects all buffers using the same major mode. -The @code{global-set-key} and @code{local-set-key} functions are -convenient interfaces for these operations (@pxref{Key Binding -Commands}). You can also use @code{define-key}, a more general -function; then you must specify explicitly the map to change. - - When choosing the key sequences for Lisp programs to rebind, please -follow the Emacs conventions for use of various keys (@pxref{Key -Binding Conventions}). - -@cindex meta character key constants -@cindex control character key constants - In writing the key sequence to rebind, it is good to use the special -escape sequences for control and meta characters (@pxref{String Type}). -The syntax @samp{\C-} means that the following character is a control -character and @samp{\M-} means that the following character is a meta -character. Thus, the string @code{"\M-x"} is read as containing a -single @kbd{M-x}, @code{"\C-f"} is read as containing a single -@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as -containing a single @kbd{C-M-x}. You can also use this escape syntax in -vectors, as well as others that aren't allowed in strings; one example -is @samp{[?\C-\H-x home]}. @xref{Character Type}. - - The key definition and lookup functions accept an alternate syntax for -event types in a key sequence that is a vector: you can use a list -containing modifier names plus one base event (a character or function -key name). For example, @code{(control ?a)} is equivalent to -@code{?\C-a} and @code{(hyper control left)} is equivalent to -@code{C-H-left}. One advantage of such lists is that the precise -numeric codes for the modifier bits don't appear in compiled files. - - The functions below signal an error if @var{keymap} is not a keymap, -or if @var{key} is not a string or vector representing a key sequence. -You can use event types (symbols) as shorthand for events that are -lists. The @code{kbd} macro (@pxref{Key Sequences}) is a convenient -way to specify the key sequence. - -@defun define-key keymap key binding -This function sets the binding for @var{key} in @var{keymap}. (If -@var{key} is more than one event long, the change is actually made -in another keymap reached from @var{keymap}.) The argument -@var{binding} can be any Lisp object, but only certain types are -meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) -The value returned by @code{define-key} is @var{binding}. - -If @var{key} is @code{[t]}, this sets the default binding in -@var{keymap}. When an event has no binding of its own, the Emacs -command loop uses the keymap's default binding, if there is one. - -@cindex invalid prefix key error -@cindex key sequence error -Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap) -or undefined; otherwise an error is signaled. If some prefix of -@var{key} is undefined, then @code{define-key} defines it as a prefix -key so that the rest of @var{key} can be defined as specified. - -If there was previously no binding for @var{key} in @var{keymap}, the -new binding is added at the beginning of @var{keymap}. The order of -bindings in a keymap makes no difference for keyboard input, but it -does matter for menu keymaps (@pxref{Menu Keymaps}). -@end defun - - This example creates a sparse keymap and makes a number of -bindings in it: - -@smallexample -@group -(setq map (make-sparse-keymap)) - @result{} (keymap) -@end group -@group -(define-key map "\C-f" 'forward-char) - @result{} forward-char -@end group -@group -map - @result{} (keymap (6 . forward-char)) -@end group - -@group -;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} -(define-key map (kbd "C-x f") 'forward-word) - @result{} forward-word -@end group -@group -map -@result{} (keymap - (24 keymap ; @kbd{C-x} - (102 . forward-word)) ; @kbd{f} - (6 . forward-char)) ; @kbd{C-f} -@end group - -@group -;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} -(define-key map (kbd "C-p") ctl-x-map) -;; @code{ctl-x-map} -@result{} [nil @dots{} find-file @dots{} backward-kill-sentence] -@end group - -@group -;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} -(define-key map (kbd "C-p C-f") 'foo) -@result{} 'foo -@end group -@group -map -@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.} - (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence]) - (24 keymap - (102 . forward-word)) - (6 . forward-char)) -@end group -@end smallexample - -@noindent -Note that storing a new binding for @kbd{C-p C-f} actually works by -changing an entry in @code{ctl-x-map}, and this has the effect of -changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the -default global map. - - The function @code{substitute-key-definition} scans a keymap for -keys that have a certain binding and rebinds them with a different -binding. Another feature which is cleaner and can often produce the -same results to remap one command into another (@pxref{Remapping -Commands}). - -@defun substitute-key-definition olddef newdef keymap &optional oldmap -@cindex replace bindings -This function replaces @var{olddef} with @var{newdef} for any keys in -@var{keymap} that were bound to @var{olddef}. In other words, -@var{olddef} is replaced with @var{newdef} wherever it appears. The -function returns @code{nil}. - -For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with -standard bindings: - -@smallexample -@group -(substitute-key-definition - 'find-file 'find-file-read-only (current-global-map)) -@end group -@end smallexample - -@c Emacs 19 feature -If @var{oldmap} is non-@code{nil}, that changes the behavior of -@code{substitute-key-definition}: the bindings in @var{oldmap} determine -which keys to rebind. The rebindings still happen in @var{keymap}, not -in @var{oldmap}. Thus, you can change one map under the control of the -bindings in another. For example, - -@smallexample -(substitute-key-definition - 'delete-backward-char 'my-funny-delete - my-map global-map) -@end smallexample - -@noindent -puts the special deletion command in @code{my-map} for whichever keys -are globally bound to the standard deletion command. - -Here is an example showing a keymap before and after substitution: - -@smallexample -@group -(setq map '(keymap - (?1 . olddef-1) - (?2 . olddef-2) - (?3 . olddef-1))) -@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1)) -@end group - -@group -(substitute-key-definition 'olddef-1 'newdef map) -@result{} nil -@end group -@group -map -@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef)) -@end group -@end smallexample -@end defun - -@defun suppress-keymap keymap &optional nodigits -@cindex @code{self-insert-command} override -This function changes the contents of the full keymap @var{keymap} by -remapping @code{self-insert-command} to the command @code{undefined} -(@pxref{Remapping Commands}). This has the effect of undefining all -printing characters, thus making ordinary insertion of text impossible. -@code{suppress-keymap} returns @code{nil}. - -If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines -digits to run @code{digit-argument}, and @kbd{-} to run -@code{negative-argument}. Otherwise it makes them undefined like the -rest of the printing characters. - -@cindex yank suppression -@cindex @code{quoted-insert} suppression -The @code{suppress-keymap} function does not make it impossible to -modify a buffer, as it does not suppress commands such as @code{yank} -and @code{quoted-insert}. To prevent any modification of a buffer, make -it read-only (@pxref{Read Only Buffers}). - -Since this function modifies @var{keymap}, you would normally use it -on a newly created keymap. Operating on an existing keymap -that is used for some other purpose is likely to cause trouble; for -example, suppressing @code{global-map} would make it impossible to use -most of Emacs. - -Most often, @code{suppress-keymap} is used to initialize local -keymaps of modes such as Rmail and Dired where insertion of text is not -desirable and the buffer is read-only. Here is an example taken from -the file @file{emacs/lisp/dired.el}, showing how the local keymap for -Dired mode is set up: - -@smallexample -@group -(setq dired-mode-map (make-keymap)) -(suppress-keymap dired-mode-map) -(define-key dired-mode-map "r" 'dired-rename-file) -(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted) -(define-key dired-mode-map "d" 'dired-flag-file-deleted) -(define-key dired-mode-map "v" 'dired-view-file) -(define-key dired-mode-map "e" 'dired-find-file) -(define-key dired-mode-map "f" 'dired-find-file) -@dots{} -@end group -@end smallexample -@end defun - -@node Remapping Commands -@section Remapping Commands -@cindex remapping commands - - A special kind of key binding, using a special ``key sequence'' -which includes a command name, has the effect of @dfn{remapping} that -command into another. Here's how it works. You make a key binding -for a key sequence that starts with the dummy event @code{remap}, -followed by the command name you want to remap. Specify the remapped -definition as the definition in this binding. The remapped definition -is usually a command name, but it can be any valid definition for -a key binding. - - Here's an example. Suppose that My mode uses special commands -@code{my-kill-line} and @code{my-kill-word}, which should be invoked -instead of @code{kill-line} and @code{kill-word}. It can establish -this by making these two command-remapping bindings in its keymap: - -@smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -(define-key my-mode-map [remap kill-word] 'my-kill-word) -@end smallexample - -Whenever @code{my-mode-map} is an active keymap, if the user types -@kbd{C-k}, Emacs will find the standard global binding of -@code{kill-line} (assuming nobody has changed it). But -@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line}, -so instead of running @code{kill-line}, Emacs runs -@code{my-kill-line}. - -Remapping only works through a single level. In other words, - -@smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line) -@end smallexample - -@noindent -does not have the effect of remapping @code{kill-line} into -@code{my-other-kill-line}. If an ordinary key binding specifies -@code{kill-line}, this keymap will remap it to @code{my-kill-line}; -if an ordinary binding specifies @code{my-kill-line}, this keymap will -remap it to @code{my-other-kill-line}. - -@defun command-remapping command &optional position keymaps -This function returns the remapping for @var{command} (a symbol), -given the current active keymaps. If @var{command} is not remapped -(which is the usual situation), or not a symbol, the function returns -@code{nil}. @code{position} can optionally specify a buffer position -or an event position to determine the keymaps to use, as in -@code{key-binding}. - -If the optional argument @code{keymaps} is non-@code{nil}, it -specifies a list of keymaps to search in. This argument is ignored if -@code{position} is non-@code{nil}. -@end defun - -@node Translation Keymaps -@section Keymaps for Translating Sequences of Events -@cindex keymaps for translating events - - This section describes keymaps that are used during reading a key -sequence, to translate certain event sequences into others. -@code{read-key-sequence} checks every subsequence of the key sequence -being read, as it is read, against @code{function-key-map} and then -against @code{key-translation-map}. - -@defvar function-key-map -This variable holds a keymap that describes the character sequences sent -by function keys on an ordinary character terminal. This keymap has the -same structure as other keymaps, but is used differently: it specifies -translations to make while reading key sequences, rather than bindings -for key sequences. - -If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector -@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a -key sequence, it is replaced with the events in @var{v}. - -For example, VT100 terminals send @kbd{@key{ESC} O P} when the -keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate -that sequence of events into the single event @code{pf1}. We accomplish -this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in -@code{function-key-map}, when using a VT100. - -Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c -@key{ESC} O P}; later the function @code{read-key-sequence} translates -this back into @kbd{C-c @key{PF1}}, which it returns as the vector -@code{[?\C-c pf1]}. - -Entries in @code{function-key-map} are ignored if they conflict with -bindings made in the minor mode, local, or global keymaps. The intent -is that the character sequences that function keys send should not have -command bindings in their own right---but if they do, the ordinary -bindings take priority. - -The value of @code{function-key-map} is usually set up automatically -according to the terminal's Terminfo or Termcap entry, but sometimes -those need help from terminal-specific Lisp files. Emacs comes with -terminal-specific files for many common terminals; their main purpose is -to make entries in @code{function-key-map} beyond those that can be -deduced from Termcap and Terminfo. @xref{Terminal-Specific}. -@end defvar - -@defvar key-translation-map -This variable is another keymap used just like @code{function-key-map} -to translate input events into other events. It differs from -@code{function-key-map} in two ways: - -@itemize @bullet -@item -@code{key-translation-map} goes to work after @code{function-key-map} is -finished; it receives the results of translation by -@code{function-key-map}. - -@item -Non-prefix bindings in @code{key-translation-map} override actual key -bindings. For example, if @kbd{C-x f} has a non-prefix binding in -@code{key-translation-map}, that translation takes effect even though -@kbd{C-x f} also has a key binding in the global map. -@end itemize - -Note however that actual key bindings can have an effect on -@code{key-translation-map}, even though they are overridden by it. -Indeed, actual key bindings override @code{function-key-map} and thus -may alter the key sequence that @code{key-translation-map} receives. -Clearly, it is better to avoid this type of situation. - -The intent of @code{key-translation-map} is for users to map one -character set to another, including ordinary characters normally bound -to @code{self-insert-command}. -@end defvar - -@cindex key translation function -You can use @code{function-key-map} or @code{key-translation-map} for -more than simple aliases, by using a function, instead of a key -sequence, as the ``translation'' of a key. Then this function is called -to compute the translation of that key. - -The key translation function receives one argument, which is the prompt -that was specified in @code{read-key-sequence}---or @code{nil} if the -key sequence is being read by the editor command loop. In most cases -you can ignore the prompt value. - -If the function reads input itself, it can have the effect of altering -the event that follows. For example, here's how to define @kbd{C-c h} -to turn the character that follows into a Hyper character: - -@example -@group -(defun hyperify (prompt) - (let ((e (read-event))) - (vector (if (numberp e) - (logior (lsh 1 24) e) - (if (memq 'hyper (event-modifiers e)) - e - (add-event-modifier "H-" e)))))) - -(defun add-event-modifier (string e) - (let ((symbol (if (symbolp e) e (car e)))) - (setq symbol (intern (concat string - (symbol-name symbol)))) -@end group -@group - (if (symbolp e) - symbol - (cons symbol (cdr e))))) - -(define-key function-key-map "\C-ch" 'hyperify) -@end group -@end example - - If you have enabled keyboard character set decoding using -@code{set-keyboard-coding-system}, decoding is done after the -translations listed above. @xref{Terminal I/O Encoding}. However, in -future Emacs versions, character set decoding may be done at an -earlier stage. - -@node Key Binding Commands -@section Commands for Binding Keys - - This section describes some convenient interactive interfaces for -changing key bindings. They work by calling @code{define-key}. - - People often use @code{global-set-key} in their init files -(@pxref{Init File}) for simple customization. For example, - -@smallexample -(global-set-key (kbd "C-x C-\\") 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [?\C-x ?\C-\\] 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [(control ?x) (control ?\\)] 'next-line) -@end smallexample - -@noindent -redefines @kbd{C-x C-\} to move down a line. - -@smallexample -(global-set-key [M-mouse-1] 'mouse-set-point) -@end smallexample - -@noindent -redefines the first (leftmost) mouse button, entered with the Meta key, to -set point where you click. - -@cindex non-@acronym{ASCII} text in keybindings - Be careful when using non-@acronym{ASCII} text characters in Lisp -specifications of keys to bind. If these are read as multibyte text, as -they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you -must type the keys as multibyte too. For instance, if you use this: - -@smallexample -(global-set-key "@"o" 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -or - -@smallexample -(global-set-key ?@"o 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -and your language environment is multibyte Latin-1, these commands -actually bind the multibyte character with code 2294, not the unibyte -Latin-1 character with code 246 (@kbd{M-v}). In order to use this -binding, you need to enter the multibyte Latin-1 character as keyboard -input. One way to do this is by using an appropriate input method -(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}). - - If you want to use a unibyte character in the key binding, you can -construct the key sequence string using @code{multibyte-char-to-unibyte} -or @code{string-make-unibyte} (@pxref{Converting Representations}). - -@deffn Command global-set-key key binding -This function sets the binding of @var{key} in the current global map -to @var{binding}. - -@smallexample -@group -(global-set-key @var{key} @var{binding}) -@equiv{} -(define-key (current-global-map) @var{key} @var{binding}) -@end group -@end smallexample -@end deffn - -@deffn Command global-unset-key key -@cindex unbinding keys -This function removes the binding of @var{key} from the current -global map. - -One use of this function is in preparation for defining a longer key -that uses @var{key} as a prefix---which would not be allowed if -@var{key} has a non-prefix binding. For example: - -@smallexample -@group -(global-unset-key "\C-l") - @result{} nil -@end group -@group -(global-set-key "\C-l\C-l" 'redraw-display) - @result{} nil -@end group -@end smallexample - -This function is implemented simply using @code{define-key}: - -@smallexample -@group -(global-unset-key @var{key}) -@equiv{} -(define-key (current-global-map) @var{key} nil) -@end group -@end smallexample -@end deffn - -@deffn Command local-set-key key binding -This function sets the binding of @var{key} in the current local -keymap to @var{binding}. - -@smallexample -@group -(local-set-key @var{key} @var{binding}) -@equiv{} -(define-key (current-local-map) @var{key} @var{binding}) -@end group -@end smallexample -@end deffn - -@deffn Command local-unset-key key -This function removes the binding of @var{key} from the current -local map. - -@smallexample -@group -(local-unset-key @var{key}) -@equiv{} -(define-key (current-local-map) @var{key} nil) -@end group -@end smallexample -@end deffn - -@node Scanning Keymaps -@section Scanning Keymaps - - This section describes functions used to scan all the current keymaps -for the sake of printing help information. - -@defun accessible-keymaps keymap &optional prefix -This function returns a list of all the keymaps that can be reached (via -zero or more prefix keys) from @var{keymap}. The value is an -association list with elements of the form @code{(@var{key} .@: -@var{map})}, where @var{key} is a prefix key whose definition in -@var{keymap} is @var{map}. - -The elements of the alist are ordered so that the @var{key} increases -in length. The first element is always @code{([] .@: @var{keymap})}, -because the specified keymap is accessible from itself with a prefix of -no events. - -If @var{prefix} is given, it should be a prefix key sequence; then -@code{accessible-keymaps} includes only the submaps whose prefixes start -with @var{prefix}. These elements look just as they do in the value of -@code{(accessible-keymaps)}; the only difference is that some elements -are omitted. - -In the example below, the returned alist indicates that the key -@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose -definition is the sparse keymap @code{(keymap (83 .@: center-paragraph) -(115 .@: foo))}. - -@smallexample -@group -(accessible-keymaps (current-local-map)) -@result{}(([] keymap - (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.} - (83 . center-paragraph) - (115 . center-line)) - (9 . tab-to-tab-stop)) -@end group - -@group - ("^[" keymap - (83 . center-paragraph) - (115 . foo))) -@end group -@end smallexample - -In the following example, @kbd{C-h} is a prefix key that uses a sparse -keymap starting with @code{(keymap (118 . describe-variable)@dots{})}. -Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of -the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of -several dummy events used as prefixes for mouse actions in special parts -of a window. - -@smallexample -@group -(accessible-keymaps (current-global-map)) -@result{} (([] keymap [set-mark-command beginning-of-line @dots{} - delete-backward-char]) -@end group -@group - ("^H" keymap (118 . describe-variable) @dots{} - (8 . help-for-help)) -@end group -@group - ("^X" keymap [x-flush-mouse-queue @dots{} - backward-kill-sentence]) -@end group -@group - ("^[" keymap [mark-sexp backward-sexp @dots{} - backward-kill-word]) -@end group - ("^X4" keymap (15 . display-buffer) @dots{}) -@group - ([mode-line] keymap - (S-mouse-2 . mouse-split-window-horizontally) @dots{})) -@end group -@end smallexample - -@noindent -These are not all the keymaps you would see in actuality. -@end defun - -@defun map-keymap function keymap -The function @code{map-keymap} calls @var{function} once -for each binding in @var{keymap}. It passes two arguments, -the event type and the value of the binding. If @var{keymap} -has a parent, the parent's bindings are included as well. -This works recursively: if the parent has itself a parent, then the -grandparent's bindings are also included and so on. - -This function is the cleanest way to examine all the bindings -in a keymap. -@end defun - -@defun where-is-internal command &optional keymap firstonly noindirect no-remap -This function is a subroutine used by the @code{where-is} command -(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list -of all key sequences (of any length) that are bound to @var{command} in a -set of keymaps. - -The argument @var{command} can be any object; it is compared with all -keymap entries using @code{eq}. - -If @var{keymap} is @code{nil}, then the maps used are the current active -keymaps, disregarding @code{overriding-local-map} (that is, pretending -its value is @code{nil}). If @var{keymap} is a keymap, then the -maps searched are @var{keymap} and the global keymap. If @var{keymap} -is a list of keymaps, only those keymaps are searched. - -Usually it's best to use @code{overriding-local-map} as the expression -for @var{keymap}. Then @code{where-is-internal} searches precisely the -keymaps that are active. To search only the global map, pass -@code{(keymap)} (an empty keymap) as @var{keymap}. - -If @var{firstonly} is @code{non-ascii}, then the value is a single -vector representing the first key sequence found, rather than a list of -all possible key sequences. If @var{firstonly} is @code{t}, then the -value is the first key sequence, except that key sequences consisting -entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} -characters) are preferred to all other key sequences and that the -return value can never be a menu binding. - -If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't -follow indirect keymap bindings. This makes it possible to search for -an indirect definition itself. - -When command remapping is in effect (@pxref{Remapping Commands}), -@code{where-is-internal} figures out when a command will be run due to -remapping and reports keys accordingly. It also returns @code{nil} if -@var{command} won't really be run because it has been remapped to some -other command. However, if @var{no-remap} is non-@code{nil}. -@code{where-is-internal} ignores remappings. - -@smallexample -@group -(where-is-internal 'describe-function) - @result{} ([8 102] [f1 102] [help 102] - [menu-bar help-menu describe describe-function]) -@end group -@end smallexample -@end defun - -@deffn Command describe-bindings &optional prefix buffer-or-name -This function creates a listing of all current key bindings, and -displays it in a buffer named @samp{*Help*}. The text is grouped by -modes---minor modes first, then the major mode, then global bindings. - -If @var{prefix} is non-@code{nil}, it should be a prefix key; then the -listing includes only keys that start with @var{prefix}. - -The listing describes meta characters as @key{ESC} followed by the -corresponding non-meta character. - -When several characters with consecutive @acronym{ASCII} codes have the -same definition, they are shown together, as -@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to -know the @acronym{ASCII} codes to understand which characters this means. -For example, in the default global map, the characters @samp{@key{SPC} -..@: ~} are described by a single line. @key{SPC} is @acronym{ASCII} 32, -@kbd{~} is @acronym{ASCII} 126, and the characters between them include all -the normal printing characters, (e.g., letters, digits, punctuation, -etc.@:); all these characters are bound to @code{self-insert-command}. - -If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a -buffer name. Then @code{describe-bindings} lists that buffer's bindings, -instead of the current buffer's. -@end deffn - -@node Menu Keymaps -@section Menu Keymaps -@cindex menu keymaps - -A keymap can operate as a menu as well as defining bindings for -keyboard keys and mouse buttons. Menus are usually actuated with the -mouse, but they can function with the keyboard also. If a menu keymap -is active for the next input event, that activates the keyboard menu -feature. - -@menu -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. -@end menu - -@node Defining Menus -@subsection Defining Menus -@cindex defining menus -@cindex menu prompt string -@cindex prompt string (of menu) - -A keymap acts as a menu if it has an @dfn{overall prompt string}, -which is a string that appears as an element of the keymap. -(@xref{Format of Keymaps}.) The string should describe the purpose of -the menu's commands. Emacs displays the overall prompt string as the -menu title in some cases, depending on the toolkit (if any) used for -displaying menus.@footnote{It is required for menus which do not use a -toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the -overall prompt string. - -The easiest way to construct a keymap with a prompt string is to -specify the string as an argument when you call @code{make-keymap}, -@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or -@code{define-prefix-command} (@pxref{Definition of -define-prefix-command}). If you do not want the keymap to operate as -a menu, don't specify a prompt string for it. - -@defun keymap-prompt keymap -This function returns the overall prompt string of @var{keymap}, -or @code{nil} if it has none. -@end defun - -The menu's items are the bindings in the keymap. Each binding -associates an event type to a definition, but the event types have no -significance for the menu appearance. (Usually we use pseudo-events, -symbols that the keyboard cannot generate, as the event types for menu -item bindings.) The menu is generated entirely from the bindings that -correspond in the keymap to these events. - -The order of items in the menu is the same as the order of bindings in -the keymap. Since @code{define-key} puts new bindings at the front, you -should define the menu items starting at the bottom of the menu and -moving to the top, if you care about the order. When you add an item to -an existing menu, you can specify its position in the menu using -@code{define-key-after} (@pxref{Modifying Menus}). - -@menu -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. -@end menu - -@node Simple Menu Items -@subsubsection Simple Menu Items - - The simpler (and original) way to define a menu item is to bind some -event type (it doesn't matter what event type) to a binding like this: - -@example -(@var{item-string} . @var{real-binding}) -@end example - -@noindent -The @sc{car}, @var{item-string}, is the string to be displayed in the -menu. It should be short---preferably one to three words. It should -describe the action of the command it corresponds to. Note that it is -not generally possible to display non-@acronym{ASCII} text in menus. It will -work for keyboard menus and will work to a large extent when Emacs is -built with the Gtk+ toolkit.@footnote{In this case, the text is first -encoded using the @code{utf-8} coding system and then rendered by the -toolkit as it sees fit.} - - You can also supply a second string, called the help string, as follows: - -@example -(@var{item-string} @var{help} . @var{real-binding}) -@end example - -@noindent -@var{help} specifies a ``help-echo'' string to display while the mouse -is on that item in the same way as @code{help-echo} text properties -(@pxref{Help display}). - - As far as @code{define-key} is concerned, @var{item-string} and -@var{help-string} are part of the event's binding. However, -@code{lookup-key} returns just @var{real-binding}, and only -@var{real-binding} is used for executing the key. - - If @var{real-binding} is @code{nil}, then @var{item-string} appears in -the menu but cannot be selected. - - If @var{real-binding} is a symbol and has a non-@code{nil} -@code{menu-enable} property, that property is an expression that -controls whether the menu item is enabled. Every time the keymap is -used to display a menu, Emacs evaluates the expression, and it enables -the menu item only if the expression's value is non-@code{nil}. When a -menu item is disabled, it is displayed in a ``fuzzy'' fashion, and -cannot be selected. - - The menu bar does not recalculate which items are enabled every time you -look at a menu. This is because the X toolkit requires the whole tree -of menus in advance. To force recalculation of the menu bar, call -@code{force-mode-line-update} (@pxref{Mode Line Format}). - - You've probably noticed that menu items show the equivalent keyboard key -sequence (if any) to invoke the same command. To save time on -recalculation, menu display caches this information in a sublist in the -binding, like this: - -@c This line is not too long--rms. -@example -(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding}) -@end example - -@noindent -Don't put these sublists in the menu item yourself; menu display -calculates them automatically. Don't mention keyboard equivalents in -the item strings themselves, since that is redundant. - -@node Extended Menu Items -@subsubsection Extended Menu Items -@kindex menu-item - - An extended-format menu item is a more flexible and also cleaner -alternative to the simple format. You define an event type with a -binding that's a list starting with the symbol @code{menu-item}. -For a non-selectable string, the binding looks like this: - -@example -(menu-item @var{item-name}) -@end example - -@noindent -A string starting with two or more dashes specifies a separator line; -see @ref{Menu Separators}. - - To define a real menu item which can be selected, the extended format -binding looks like this: - -@example -(menu-item @var{item-name} @var{real-binding} - . @var{item-property-list}) -@end example - -@noindent -Here, @var{item-name} is an expression which evaluates to the menu item -string. Thus, the string need not be a constant. The third element, -@var{real-binding}, is the command to execute. The tail of the list, -@var{item-property-list}, has the form of a property list which contains -other information. - - When an equivalent keyboard key binding is cached, the extended menu -item binding looks like this: - -@example -(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data}) - . @var{item-property-list}) -@end example - - Here is a table of the properties that are supported: - -@table @code -@item :enable @var{form} -The result of evaluating @var{form} determines whether the item is -enabled (non-@code{nil} means yes). If the item is not enabled, -you can't really click on it. - -@item :visible @var{form} -The result of evaluating @var{form} determines whether the item should -actually appear in the menu (non-@code{nil} means yes). If the item -does not appear, then the menu is displayed as if this item were -not defined at all. - -@item :help @var{help} -The value of this property, @var{help}, specifies a ``help-echo'' string -to display while the mouse is on that item. This is displayed in the -same way as @code{help-echo} text properties (@pxref{Help display}). -Note that this must be a constant string, unlike the @code{help-echo} -property for text and overlays. - -@item :button (@var{type} . @var{selected}) -This property provides a way to define radio buttons and toggle buttons. -The @sc{car}, @var{type}, says which: it should be @code{:toggle} or -@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the -result of evaluating it says whether this button is currently selected. - -A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off'' -according to the value of @var{selected}. The command itself should -toggle @var{selected}, setting it to @code{t} if it is @code{nil}, -and to @code{nil} if it is @code{t}. Here is how the menu item -to toggle the @code{debug-on-error} flag is defined: - -@example -(menu-item "Debug on Error" toggle-debug-on-error - :button (:toggle - . (and (boundp 'debug-on-error) - debug-on-error))) -@end example - -@noindent -This works because @code{toggle-debug-on-error} is defined as a command -which toggles the variable @code{debug-on-error}. - -@dfn{Radio buttons} are a group of menu items, in which at any time one -and only one is ``selected.'' There should be a variable whose value -says which one is selected at any time. The @var{selected} form for -each radio button in the group should check whether the variable has the -right value for selecting that button. Clicking on the button should -set the variable so that the button you clicked on becomes selected. - -@item :key-sequence @var{key-sequence} -This property specifies which key sequence is likely to be bound to the -same command invoked by this menu item. If you specify the right key -sequence, that makes preparing the menu for display run much faster. - -If you specify the wrong key sequence, it has no effect; before Emacs -displays @var{key-sequence} in the menu, it verifies that -@var{key-sequence} is really equivalent to this menu item. - -@item :key-sequence nil -This property indicates that there is normally no key binding which is -equivalent to this menu item. Using this property saves time in -preparing the menu for display, because Emacs does not need to search -the keymaps for a keyboard equivalent for this menu item. - -However, if the user has rebound this item's definition to a key -sequence, Emacs ignores the @code{:keys} property and finds the keyboard -equivalent anyway. - -@item :keys @var{string} -This property specifies that @var{string} is the string to display -as the keyboard equivalent for this menu item. You can use -the @samp{\\[...]} documentation construct in @var{string}. - -@item :filter @var{filter-fn} -This property provides a way to compute the menu item dynamically. -The property value @var{filter-fn} should be a function of one argument; -when it is called, its argument will be @var{real-binding}. The -function should return the binding to use instead. - -Emacs can call this function at any time that it does redisplay or -operates on menu data structures, so you should write it so it can -safely be called at any time. -@end table - -@node Menu Separators -@subsubsection Menu Separators -@cindex menu separators - - A menu separator is a kind of menu item that doesn't display any -text---instead, it divides the menu into subparts with a horizontal line. -A separator looks like this in the menu keymap: - -@example -(menu-item @var{separator-type}) -@end example - -@noindent -where @var{separator-type} is a string starting with two or more dashes. - - In the simplest case, @var{separator-type} consists of only dashes. -That specifies the default kind of separator. (For compatibility, -@code{""} and @code{-} also count as separators.) - - Certain other values of @var{separator-type} specify a different -style of separator. Here is a table of them: - -@table @code -@item "--no-line" -@itemx "--space" -An extra vertical space, with no actual line. - -@item "--single-line" -A single line in the menu's foreground color. - -@item "--double-line" -A double line in the menu's foreground color. - -@item "--single-dashed-line" -A single dashed line in the menu's foreground color. - -@item "--double-dashed-line" -A double dashed line in the menu's foreground color. - -@item "--shadow-etched-in" -A single line with a 3D sunken appearance. This is the default, -used separators consisting of dashes only. - -@item "--shadow-etched-out" -A single line with a 3D raised appearance. - -@item "--shadow-etched-in-dash" -A single dashed line with a 3D sunken appearance. - -@item "--shadow-etched-out-dash" -A single dashed line with a 3D raised appearance. - -@item "--shadow-double-etched-in" -Two lines with a 3D sunken appearance. - -@item "--shadow-double-etched-out" -Two lines with a 3D raised appearance. - -@item "--shadow-double-etched-in-dash" -Two dashed lines with a 3D sunken appearance. - -@item "--shadow-double-etched-out-dash" -Two dashed lines with a 3D raised appearance. -@end table - - You can also give these names in another style, adding a colon after -the double-dash and replacing each single dash with capitalization of -the following word. Thus, @code{"--:singleLine"}, is equivalent to -@code{"--single-line"}. - - Some systems and display toolkits don't really handle all of these -separator types. If you use a type that isn't supported, the menu -displays a similar kind of separator that is supported. - -@node Alias Menu Items -@subsubsection Alias Menu Items - - Sometimes it is useful to make menu items that use the ``same'' -command but with different enable conditions. The best way to do this -in Emacs now is with extended menu items; before that feature existed, -it could be done by defining alias commands and using them in menu -items. Here's an example that makes two aliases for -@code{toggle-read-only} and gives them different enable conditions: - -@example -(defalias 'make-read-only 'toggle-read-only) -(put 'make-read-only 'menu-enable '(not buffer-read-only)) -(defalias 'make-writable 'toggle-read-only) -(put 'make-writable 'menu-enable 'buffer-read-only) -@end example - -When using aliases in menus, often it is useful to display the -equivalent key bindings for the ``real'' command name, not the aliases -(which typically don't have any key bindings except for the menu -itself). To request this, give the alias symbol a non-@code{nil} -@code{menu-alias} property. Thus, - -@example -(put 'make-read-only 'menu-alias t) -(put 'make-writable 'menu-alias t) -@end example - -@noindent -causes menu items for @code{make-read-only} and @code{make-writable} to -show the keyboard bindings for @code{toggle-read-only}. - -@node Mouse Menus -@subsection Menus and the Mouse - - The usual way to make a menu keymap produce a menu is to make it the -definition of a prefix key. (A Lisp program can explicitly pop up a -menu and receive the user's choice---see @ref{Pop-Up Menus}.) - - If the prefix key ends with a mouse event, Emacs handles the menu keymap -by popping up a visible menu, so that the user can select a choice with -the mouse. When the user clicks on a menu item, the event generated is -whatever character or symbol has the binding that brought about that -menu item. (A menu item may generate a series of events if the menu has -multiple levels or comes from the menu bar.) - - It's often best to use a button-down event to trigger the menu. Then -the user can select a menu item by releasing the button. - - A single keymap can appear as multiple menu panes, if you explicitly -arrange for this. The way to do this is to make a keymap for each pane, -then create a binding for each of those maps in the main keymap of the -menu. Give each of these bindings an item string that starts with -@samp{@@}. The rest of the item string becomes the name of the pane. -See the file @file{lisp/mouse.el} for an example of this. Any ordinary -bindings with @samp{@@}-less item strings are grouped into one pane, -which appears along with the other panes explicitly created for the -submaps. - - X toolkit menus don't have panes; instead, they can have submenus. -Every nested keymap becomes a submenu, whether the item string starts -with @samp{@@} or not. In a toolkit version of Emacs, the only thing -special about @samp{@@} at the beginning of an item string is that the -@samp{@@} doesn't appear in the menu item. - - Multiple keymaps that define the same menu prefix key produce -separate panes or separate submenus. - -@node Keyboard Menus -@subsection Menus and the Keyboard - - When a prefix key ending with a keyboard event (a character or -function key) has a definition that is a menu keymap, the keymap -operates as a keyboard menu; the user specifies the next event by -choosing a menu item with the keyboard. - - Emacs displays the keyboard menu with the map's overall prompt -string, followed by the alternatives (the item strings of the map's -bindings), in the echo area. If the bindings don't all fit at once, -the user can type @key{SPC} to see the next line of alternatives. -Successive uses of @key{SPC} eventually get to the end of the menu and -then cycle around to the beginning. (The variable -@code{menu-prompt-more-char} specifies which character is used for -this; @key{SPC} is the default.) - - When the user has found the desired alternative from the menu, he or -she should type the corresponding character---the one whose binding is -that alternative. - -@ignore -In a menu intended for keyboard use, each menu item must clearly -indicate what character to type. The best convention to use is to make -the character the first letter of the item string---that is something -users will understand without being told. We plan to change this; by -the time you read this manual, keyboard menus may explicitly name the -key for each alternative. -@end ignore - - This way of using menus in an Emacs-like editor was inspired by the -Hierarkey system. - -@defvar menu-prompt-more-char -This variable specifies the character to use to ask to see -the next line of a menu. Its initial value is 32, the code -for @key{SPC}. -@end defvar - -@node Menu Example -@subsection Menu Example -@cindex menu definition example - - Here is a complete example of defining a menu keymap. It is the -definition of the @samp{Replace} submenu in the @samp{Edit} menu in -the menu bar, and it uses the extended menu item format -(@pxref{Extended Menu Items}). First we create the keymap, and give -it a name: - -@smallexample -(defvar menu-bar-replace-menu (make-sparse-keymap "Replace")) -@end smallexample - -@noindent -Next we define the menu items: - -@smallexample -(define-key menu-bar-replace-menu [tags-repl-continue] - '(menu-item "Continue Replace" tags-loop-continue - :help "Continue last tags replace operation")) -(define-key menu-bar-replace-menu [tags-repl] - '(menu-item "Replace in tagged files" tags-query-replace - :help "Interactively replace a regexp in all tagged files")) -(define-key menu-bar-replace-menu [separator-replace-tags] - '(menu-item "--")) -;; @r{@dots{}} -@end smallexample - -@noindent -Note the symbols which the bindings are ``made for''; these appear -inside square brackets, in the key sequence being defined. In some -cases, this symbol is the same as the command name; sometimes it is -different. These symbols are treated as ``function keys,'' but they are -not real function keys on the keyboard. They do not affect the -functioning of the menu itself, but they are ``echoed'' in the echo area -when the user selects from the menu, and they appear in the output of -@code{where-is} and @code{apropos}. - - The menu in this example is intended for use with the mouse. If a -menu is intended for use with the keyboard, that is, if it is bound to -a key sequence ending with a keyboard event, then the menu items -should be bound to characters or ``real'' function keys, that can be -typed with the keyboard. - - The binding whose definition is @code{("--")} is a separator line. -Like a real menu item, the separator has a key symbol, in this case -@code{separator-replace-tags}. If one menu has two separators, they -must have two different key symbols. - - Here is how we make this menu appear as an item in the parent menu: - -@example -(define-key menu-bar-edit-menu [replace] - (list 'menu-item "Replace" menu-bar-replace-menu)) -@end example - -@noindent -Note that this incorporates the submenu keymap, which is the value of -the variable @code{menu-bar-replace-menu}, rather than the symbol -@code{menu-bar-replace-menu} itself. Using that symbol in the parent -menu item would be meaningless because @code{menu-bar-replace-menu} is -not a command. - - If you wanted to attach the same replace menu to a mouse click, you -can do it this way: - -@example -(define-key global-map [C-S-down-mouse-1] - menu-bar-replace-menu) -@end example - -@node Menu Bar -@subsection The Menu Bar -@cindex menu bar - - Most window systems allow each frame to have a @dfn{menu bar}---a -permanently displayed menu stretching horizontally across the top of the -frame. The items of the menu bar are the subcommands of the fake -``function key'' @code{menu-bar}, as defined in the active keymaps. - - To add an item to the menu bar, invent a fake ``function key'' of your -own (let's call it @var{key}), and make a binding for the key sequence -@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap, -so that pressing a button on the menu bar item leads to another menu. - - When more than one active keymap defines the same fake function key -for the menu bar, the item appears just once. If the user clicks on -that menu bar item, it brings up a single, combined menu containing -all the subcommands of that item---the global subcommands, the local -subcommands, and the minor mode subcommands. - - The variable @code{overriding-local-map} is normally ignored when -determining the menu bar contents. That is, the menu bar is computed -from the keymaps that would be active if @code{overriding-local-map} -were @code{nil}. @xref{Active Keymaps}. - - In order for a frame to display a menu bar, its @code{menu-bar-lines} -parameter must be greater than zero. Emacs uses just one line for the -menu bar itself; if you specify more than one line, the other lines -serve to separate the menu bar from the windows in the frame. We -recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout -Parameters}. - - Here's an example of setting up a menu bar item: - -@example -@group -(modify-frame-parameters (selected-frame) - '((menu-bar-lines . 2))) -@end group - -@group -;; @r{Make a menu keymap (with a prompt string)} -;; @r{and make it the menu bar item's definition.} -(define-key global-map [menu-bar words] - (cons "Words" (make-sparse-keymap "Words"))) -@end group - -@group -;; @r{Define specific subcommands in this menu.} -(define-key global-map - [menu-bar words forward] - '("Forward word" . forward-word)) -@end group -@group -(define-key global-map - [menu-bar words backward] - '("Backward word" . backward-word)) -@end group -@end example - - A local keymap can cancel a menu bar item made by the global keymap by -rebinding the same fake function key with @code{undefined} as the -binding. For example, this is how Dired suppresses the @samp{Edit} menu -bar item: - -@example -(define-key dired-mode-map [menu-bar edit] 'undefined) -@end example - -@noindent -@code{edit} is the fake function key used by the global map for the -@samp{Edit} menu bar item. The main reason to suppress a global -menu bar item is to regain space for mode-specific items. - -@defvar menu-bar-final-items -Normally the menu bar shows global items followed by items defined by the -local maps. - -This variable holds a list of fake function keys for items to display at -the end of the menu bar rather than in normal sequence. The default -value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears -at the end of the menu bar, following local menu items. -@end defvar - -@defvar menu-bar-update-hook -This normal hook is run by redisplay to update the menu bar contents, -before redisplaying the menu bar. You can use it to update submenus -whose contents should vary. Since this hook is run frequently, we -advise you to ensure that the functions it calls do not take much time -in the usual case. -@end defvar - -@node Tool Bar -@subsection Tool bars -@cindex tool bar - - A @dfn{tool bar} is a row of icons at the top of a frame, that execute -commands when you click on them---in effect, a kind of graphical menu -bar. - - The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar}) -controls how many lines' worth of height to reserve for the tool bar. A -zero value suppresses the tool bar. If the value is nonzero, and -@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and -contracts automatically as needed to hold the specified contents. - - If the value of @code{auto-resize-tool-bars} is @code{grow-only}, -the tool bar expands automatically, but does not contract automatically. -To contract the tool bar, the user has to redraw the frame by entering -@kbd{C-l}. - - The tool bar contents are controlled by a menu keymap attached to a -fake ``function key'' called @code{tool-bar} (much like the way the menu -bar is controlled). So you define a tool bar item using -@code{define-key}, like this: - -@example -(define-key global-map [tool-bar @var{key}] @var{item}) -@end example - -@noindent -where @var{key} is a fake ``function key'' to distinguish this item from -other items, and @var{item} is a menu item key binding (@pxref{Extended -Menu Items}), which says how to display this item and how it behaves. - - The usual menu keymap item properties, @code{:visible}, -@code{:enable}, @code{:button}, and @code{:filter}, are useful in -tool bar bindings and have their normal meanings. The @var{real-binding} -in the item must be a command, not a keymap; in other words, it does not -work to define a tool bar icon as a prefix key. - - The @code{:help} property specifies a ``help-echo'' string to display -while the mouse is on that item. This is displayed in the same way as -@code{help-echo} text properties (@pxref{Help display}). - - In addition, you should use the @code{:image} property; -this is how you specify the image to display in the tool bar: - -@table @code -@item :image @var{image} -@var{images} is either a single image specification or a vector of four -image specifications. If you use a vector of four, -one of them is used, depending on circumstances: - -@table @asis -@item item 0 -Used when the item is enabled and selected. -@item item 1 -Used when the item is enabled and deselected. -@item item 2 -Used when the item is disabled and selected. -@item item 3 -Used when the item is disabled and deselected. -@end table -@end table - -If @var{image} is a single image specification, Emacs draws the tool bar -button in disabled state by applying an edge-detection algorithm to the -image. - -The default tool bar is defined so that items specific to editing do not -appear for major modes whose command symbol has a @code{mode-class} -property of @code{special} (@pxref{Major Mode Conventions}). Major -modes may add items to the global bar by binding @code{[tool-bar -@var{foo}]} in their local map. It makes sense for some major modes to -replace the default tool bar items completely, since not many can be -accommodated conveniently, and the default bindings make this easy by -using an indirection through @code{tool-bar-map}. - -@defvar tool-bar-map -By default, the global map binds @code{[tool-bar]} as follows: -@example -(global-set-key [tool-bar] - '(menu-item "tool bar" ignore - :filter (lambda (ignore) tool-bar-map))) -@end example -@noindent -Thus the tool bar map is derived dynamically from the value of variable -@code{tool-bar-map} and you should normally adjust the default (global) -tool bar by changing that map. Major modes may replace the global bar -completely by making @code{tool-bar-map} buffer-local and set to a -keymap containing only the desired items. Info mode provides an -example. -@end defvar - -There are two convenience functions for defining tool bar items, as -follows. - -@defun tool-bar-add-item icon def key &rest props -This function adds an item to the tool bar by modifying -@code{tool-bar-map}. The image to use is defined by @var{icon}, which -is the base name of an XPM, XBM or PBM image file to be located by -@code{find-image}. Given a value @samp{"exit"}, say, @file{exit.xpm}, -@file{exit.pbm} and @file{exit.xbm} would be searched for in that order -on a color display. On a monochrome display, the search order is -@samp{.pbm}, @samp{.xbm} and @samp{.xpm}. The binding to use is the -command @var{def}, and @var{key} is the fake function key symbol in the -prefix keymap. The remaining arguments @var{props} are additional -property list elements to add to the menu item specification. - -To define items in some local map, bind @code{tool-bar-map} with -@code{let} around calls of this function: -@example -(defvar foo-tool-bar-map - (let ((tool-bar-map (make-sparse-keymap))) - (tool-bar-add-item @dots{}) - @dots{} - tool-bar-map)) -@end example -@end defun - -@defun tool-bar-add-item-from-menu command icon &optional map &rest props -This function is a convenience for defining tool bar items which are -consistent with existing menu bar bindings. The binding of -@var{command} is looked up in the menu bar in @var{map} (default -@code{global-map}) and modified to add an image specification for -@var{icon}, which is found in the same way as by -@code{tool-bar-add-item}. The resulting binding is then placed in -@code{tool-bar-map}, so use this function only for global tool bar -items. - -@var{map} must contain an appropriate keymap bound to -@code{[menu-bar]}. The remaining arguments @var{props} are additional -property list elements to add to the menu item specification. -@end defun - -@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props -This function is used for making non-global tool bar items. Use it -like @code{tool-bar-add-item-from-menu} except that @var{in-map} -specifies the local map to make the definition in. The argument -@var{from-map} is like the @var{map} argument of -@code{tool-bar-add-item-from-menu}. -@end defun - -@defvar auto-resize-tool-bar -If this variable is non-@code{nil}, the tool bar automatically resizes to -show all defined tool bar items---but not larger than a quarter of the -frame's height. - -If the value is @code{grow-only}, the tool bar expands automatically, -but does not contract automatically. To contract the tool bar, the -user has to redraw the frame by entering @kbd{C-l}. -@end defvar - -@defvar auto-raise-tool-bar-buttons -If this variable is non-@code{nil}, tool bar items display -in raised form when the mouse moves over them. -@end defvar - -@defvar tool-bar-button-margin -This variable specifies an extra margin to add around tool bar items. -The value is an integer, a number of pixels. The default is 4. -@end defvar - -@defvar tool-bar-button-relief -This variable specifies the shadow width for tool bar items. -The value is an integer, a number of pixels. The default is 1. -@end defvar - -@defvar tool-bar-border -This variable specifies the height of the border drawn below the tool -bar area. An integer value specifies height as a number of pixels. -If the value is one of @code{internal-border-width} (the default) or -@code{border-width}, the tool bar border height corresponds to the -corresponding frame parameter. -@end defvar - - You can define a special meaning for clicking on a tool bar item with -the shift, control, meta, etc., modifiers. You do this by setting up -additional items that relate to the original item through the fake -function keys. Specifically, the additional items should use the -modified versions of the same fake function key used to name the -original item. - - Thus, if the original item was defined this way, - -@example -(define-key global-map [tool-bar shell] - '(menu-item "Shell" shell - :image (image :type xpm :file "shell.xpm"))) -@end example - -@noindent -then here is how you can define clicking on the same tool bar image with -the shift modifier: - -@example -(define-key global-map [tool-bar S-shell] 'some-command) -@end example - -@xref{Function Keys}, for more information about how to add modifiers to -function keys. - -@node Modifying Menus -@subsection Modifying Menus - - When you insert a new item in an existing menu, you probably want to -put it in a particular place among the menu's existing items. If you -use @code{define-key} to add the item, it normally goes at the front of -the menu. To put it elsewhere in the menu, use @code{define-key-after}: - -@defun define-key-after map key binding &optional after -Define a binding in @var{map} for @var{key}, with value @var{binding}, -just like @code{define-key}, but position the binding in @var{map} after -the binding for the event @var{after}. The argument @var{key} should be -of length one---a vector or string with just one element. But -@var{after} should be a single event type---a symbol or a character, not -a sequence. The new binding goes after the binding for @var{after}. If -@var{after} is @code{t} or is omitted, then the new binding goes last, at -the end of the keymap. However, new bindings are added before any -inherited keymap. - -Here is an example: - -@example -(define-key-after my-menu [drink] - '("Drink" . drink-command) 'eat) -@end example - -@noindent -makes a binding for the fake function key @key{DRINK} and puts it -right after the binding for @key{EAT}. - -Here is how to insert an item called @samp{Work} in the @samp{Signals} -menu of Shell mode, after the item @code{break}: - -@example -(define-key-after - (lookup-key shell-mode-map [menu-bar signals]) - [work] '("Work" . work-command) 'break) -@end example -@end defun - -@ignore - arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794 -@end ignore diff --git a/lispref/lay-flat.texi b/lispref/lay-flat.texi deleted file mode 100644 index 1677058d7ca..00000000000 --- a/lispref/lay-flat.texi +++ /dev/null @@ -1,48 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@comment %**start of header -@setfilename inner-covers.info -@settitle Inner Covers -@smallbook -@comment %**end of header - -@headings off - -@w{ } -@sp 4 -@tex -\center {\secfonts \rm Lay-Flat Binding} -@end tex -@sp 2 - -We have bound this manual using a new @dfn{lay-flat} binding -technology. This type of binding allows you to open a soft cover book -so that it ``lays flat'' on a table without creasing the binding. - -In order to make the book lay flat properly, you need to ``crack'' the -binding. To do this, divide the book into two sections and bend it so -that the front and back covers meet. Do not worry; the pages are -sewn and glued to the binding, and will not fall out easily. -The outer cardboard binding itself is designed so that it will not -break or crease as an ordinary paperback binding will. Bend the book -several times in this manner, dividing it in a different place each -time and pressing the pages flat and open. With use, the binding will -become flexible and the pages will lay flat without needing to be -pushed or held down. - -@page - - -@tex -\center {\secfonts \rm Notes} -@end tex - -@bye - -@ignore - arch-tag: 9e03a1c7-6f62-4346-85d9-ed5b79386e07 -@end ignore diff --git a/lispref/lists.texi b/lispref/lists.texi deleted file mode 100644 index ffe4df2413d..00000000000 --- a/lispref/lists.texi +++ /dev/null @@ -1,1904 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/lists -@node Lists, Sequences Arrays Vectors, Strings and Characters, Top -@chapter Lists -@cindex lists -@cindex element (of list) - - A @dfn{list} represents a sequence of zero or more elements (which may -be any Lisp objects). The important difference between lists and -vectors is that two or more lists can share part of their structure; in -addition, you can insert or delete elements in a list without copying -the whole list. - -@menu -* 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. -* List Variables:: Modifying lists stored in variables. -* 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. -@end menu - -@node Cons Cells -@section Lists and Cons Cells -@cindex lists and cons cells - - Lists in Lisp are not a primitive data type; they are built up from -@dfn{cons cells}. A cons cell is a data object that represents an -ordered pair. That is, it has two slots, and each slot @dfn{holds}, or -@dfn{refers to}, some Lisp object. One slot is known as the @sc{car}, -and the other is known as the @sc{cdr}. (These names are traditional; -see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.'' - - We say that ``the @sc{car} of this cons cell is'' whatever object -its @sc{car} slot currently holds, and likewise for the @sc{cdr}. - - A list is a series of cons cells ``chained together,'' so that each -cell refers to the next one. There is one cons cell for each element of -the list. By convention, the @sc{car}s of the cons cells hold the -elements of the list, and the @sc{cdr}s are used to chain the list: the -@sc{cdr} slot of each cons cell refers to the following cons cell. The -@sc{cdr} of the last cons cell is @code{nil}. This asymmetry between -the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the -level of cons cells, the @sc{car} and @sc{cdr} slots have the same -characteristics. - -@cindex true list - Since @code{nil} is the conventional value to put in the @sc{cdr} of -the last cons cell in the list, we call that case a @dfn{true list}. - - In Lisp, we consider the symbol @code{nil} a list as well as a -symbol; it is the list with no elements. For convenience, the symbol -@code{nil} is considered to have @code{nil} as its @sc{cdr} (and also -as its @sc{car}). Therefore, the @sc{cdr} of a true list is always a -true list. - -@cindex dotted list -@cindex circular list - If the @sc{cdr} of a list's last cons cell is some other value, -neither @code{nil} nor another cons cell, we call the structure a -@dfn{dotted list}, since its printed representation would use -@samp{.}. There is one other possibility: some cons cell's @sc{cdr} -could point to one of the previous cons cells in the list. We call -that structure a @dfn{circular list}. - - For some purposes, it does not matter whether a list is true, -circular or dotted. If the program doesn't look far enough down the -list to see the @sc{cdr} of the final cons cell, it won't care. -However, some functions that operate on lists demand true lists and -signal errors if given a dotted list. Most functions that try to find -the end of a list enter infinite loops if given a circular list. - -@cindex list structure - Because most cons cells are used as part of lists, the phrase -@dfn{list structure} has come to mean any structure made out of cons -cells. - - The @sc{cdr} of any nonempty true list @var{l} is a list containing all the -elements of @var{l} except the first. - - @xref{Cons Cell Type}, for the read and print syntax of cons cells and -lists, and for ``box and arrow'' illustrations of lists. - -@node List-related Predicates -@section Predicates on Lists - - The following predicates test whether a Lisp object is an atom, -whether it is a cons cell or is a list, or whether it is the -distinguished object @code{nil}. (Many of these predicates can be -defined in terms of the others, but they are used so often that it is -worth having all of them.) - -@defun consp object -This function returns @code{t} if @var{object} is a cons cell, @code{nil} -otherwise. @code{nil} is not a cons cell, although it @emph{is} a list. -@end defun - -@defun atom object -This function returns @code{t} if @var{object} is an atom, @code{nil} -otherwise. All objects except cons cells are atoms. The symbol -@code{nil} is an atom and is also a list; it is the only Lisp object -that is both. - -@example -(atom @var{object}) @equiv{} (not (consp @var{object})) -@end example -@end defun - -@defun listp object -This function returns @code{t} if @var{object} is a cons cell or -@code{nil}. Otherwise, it returns @code{nil}. - -@example -@group -(listp '(1)) - @result{} t -@end group -@group -(listp '()) - @result{} t -@end group -@end example -@end defun - -@defun nlistp object -This function is the opposite of @code{listp}: it returns @code{t} if -@var{object} is not a list. Otherwise, it returns @code{nil}. - -@example -(listp @var{object}) @equiv{} (not (nlistp @var{object})) -@end example -@end defun - -@defun null object -This function returns @code{t} if @var{object} is @code{nil}, and -returns @code{nil} otherwise. This function is identical to @code{not}, -but as a matter of clarity we use @code{null} when @var{object} is -considered a list and @code{not} when it is considered a truth value -(see @code{not} in @ref{Combining Conditions}). - -@example -@group -(null '(1)) - @result{} nil -@end group -@group -(null '()) - @result{} t -@end group -@end example -@end defun - - -@node List Elements -@section Accessing Elements of Lists -@cindex list elements - -@defun car cons-cell -This function returns the value referred to by the first slot of the -cons cell @var{cons-cell}. Expressed another way, this function -returns the @sc{car} of @var{cons-cell}. - -As a special case, if @var{cons-cell} is @code{nil}, then @code{car} -is defined to return @code{nil}; therefore, any list is a valid argument -for @code{car}. An error is signaled if the argument is not a cons cell -or @code{nil}. - -@example -@group -(car '(a b c)) - @result{} a -@end group -@group -(car '()) - @result{} nil -@end group -@end example -@end defun - -@defun cdr cons-cell -This function returns the value referred to by the second slot of -the cons cell @var{cons-cell}. Expressed another way, this function -returns the @sc{cdr} of @var{cons-cell}. - -As a special case, if @var{cons-cell} is @code{nil}, then @code{cdr} -is defined to return @code{nil}; therefore, any list is a valid argument -for @code{cdr}. An error is signaled if the argument is not a cons cell -or @code{nil}. - -@example -@group -(cdr '(a b c)) - @result{} (b c) -@end group -@group -(cdr '()) - @result{} nil -@end group -@end example -@end defun - -@defun car-safe object -This function lets you take the @sc{car} of a cons cell while avoiding -errors for other data types. It returns the @sc{car} of @var{object} if -@var{object} is a cons cell, @code{nil} otherwise. This is in contrast -to @code{car}, which signals an error if @var{object} is not a list. - -@example -@group -(car-safe @var{object}) -@equiv{} -(let ((x @var{object})) - (if (consp x) - (car x) - nil)) -@end group -@end example -@end defun - -@defun cdr-safe object -This function lets you take the @sc{cdr} of a cons cell while -avoiding errors for other data types. It returns the @sc{cdr} of -@var{object} if @var{object} is a cons cell, @code{nil} otherwise. -This is in contrast to @code{cdr}, which signals an error if -@var{object} is not a list. - -@example -@group -(cdr-safe @var{object}) -@equiv{} -(let ((x @var{object})) - (if (consp x) - (cdr x) - nil)) -@end group -@end example -@end defun - -@defmac pop listname -This macro is a way of examining the @sc{car} of a list, -and taking it off the list, all at once. - -It operates on the list which is stored in the symbol @var{listname}. -It removes this element from the list by setting @var{listname} -to the @sc{cdr} of its old value---but it also returns the @sc{car} -of that list, which is the element being removed. - -@example -x - @result{} (a b c) -(pop x) - @result{} a -x - @result{} (b c) -@end example -@end defmac - -@defun nth n list -@anchor{Definition of nth} -This function returns the @var{n}th element of @var{list}. Elements -are numbered starting with zero, so the @sc{car} of @var{list} is -element number zero. If the length of @var{list} is @var{n} or less, -the value is @code{nil}. - -If @var{n} is negative, @code{nth} returns the first element of -@var{list}. - -@example -@group -(nth 2 '(1 2 3 4)) - @result{} 3 -@end group -@group -(nth 10 '(1 2 3 4)) - @result{} nil -@end group -@group -(nth -3 '(1 2 3 4)) - @result{} 1 - -(nth n x) @equiv{} (car (nthcdr n x)) -@end group -@end example - -The function @code{elt} is similar, but applies to any kind of sequence. -For historical reasons, it takes its arguments in the opposite order. -@xref{Sequence Functions}. -@end defun - -@defun nthcdr n list -This function returns the @var{n}th @sc{cdr} of @var{list}. In other -words, it skips past the first @var{n} links of @var{list} and returns -what follows. - -If @var{n} is zero or negative, @code{nthcdr} returns all of -@var{list}. If the length of @var{list} is @var{n} or less, -@code{nthcdr} returns @code{nil}. - -@example -@group -(nthcdr 1 '(1 2 3 4)) - @result{} (2 3 4) -@end group -@group -(nthcdr 10 '(1 2 3 4)) - @result{} nil -@end group -@group -(nthcdr -3 '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@end example -@end defun - -@defun last list &optional n -This function returns the last link of @var{list}. The @code{car} of -this link is the list's last element. If @var{list} is null, -@code{nil} is returned. If @var{n} is non-@code{nil}, the -@var{n}th-to-last link is returned instead, or the whole of @var{list} -if @var{n} is bigger than @var{list}'s length. -@end defun - -@defun safe-length list -@anchor{Definition of safe-length} -This function returns the length of @var{list}, with no risk of either -an error or an infinite loop. It generally returns the number of -distinct cons cells in the list. However, for circular lists, -the value is just an upper bound; it is often too large. - -If @var{list} is not @code{nil} or a cons cell, @code{safe-length} -returns 0. -@end defun - - The most common way to compute the length of a list, when you are not -worried that it may be circular, is with @code{length}. @xref{Sequence -Functions}. - -@defun caar cons-cell -This is the same as @code{(car (car @var{cons-cell}))}. -@end defun - -@defun cadr cons-cell -This is the same as @code{(car (cdr @var{cons-cell}))} -or @code{(nth 1 @var{cons-cell})}. -@end defun - -@defun cdar cons-cell -This is the same as @code{(cdr (car @var{cons-cell}))}. -@end defun - -@defun cddr cons-cell -This is the same as @code{(cdr (cdr @var{cons-cell}))} -or @code{(nthcdr 2 @var{cons-cell})}. -@end defun - -@defun butlast x &optional n -This function returns the list @var{x} with the last element, -or the last @var{n} elements, removed. If @var{n} is greater -than zero it makes a copy of the list so as not to damage the -original list. In general, @code{(append (butlast @var{x} @var{n}) -(last @var{x} @var{n}))} will return a list equal to @var{x}. -@end defun - -@defun nbutlast x &optional n -This is a version of @code{butlast} that works by destructively -modifying the @code{cdr} of the appropriate element, rather than -making a copy of the list. -@end defun - -@node Building Lists -@comment node-name, next, previous, up -@section Building Cons Cells and Lists -@cindex cons cells -@cindex building lists - - Many functions build lists, as lists reside at the very heart of Lisp. -@code{cons} is the fundamental list-building function; however, it is -interesting to note that @code{list} is used more times in the source -code for Emacs than @code{cons}. - -@defun cons object1 object2 -This function is the most basic function for building new list -structure. It creates a new cons cell, making @var{object1} the -@sc{car}, and @var{object2} the @sc{cdr}. It then returns the new -cons cell. The arguments @var{object1} and @var{object2} may be any -Lisp objects, but most often @var{object2} is a list. - -@example -@group -(cons 1 '(2)) - @result{} (1 2) -@end group -@group -(cons 1 '()) - @result{} (1) -@end group -@group -(cons 1 2) - @result{} (1 . 2) -@end group -@end example - -@cindex consing -@code{cons} is often used to add a single element to the front of a -list. This is called @dfn{consing the element onto the list}. -@footnote{There is no strictly equivalent way to add an element to -the end of a list. You can use @code{(append @var{listname} (list -@var{newelt}))}, which creates a whole new list by copying @var{listname} -and adding @var{newelt} to its end. Or you can use @code{(nconc -@var{listname} (list @var{newelt}))}, which modifies @var{listname} -by following all the @sc{cdr}s and then replacing the terminating -@code{nil}. Compare this to adding an element to the beginning of a -list with @code{cons}, which neither copies nor modifies the list.} -For example: - -@example -(setq list (cons newelt list)) -@end example - -Note that there is no conflict between the variable named @code{list} -used in this example and the function named @code{list} described below; -any symbol can serve both purposes. -@end defun - -@defun list &rest objects -This function creates a list with @var{objects} as its elements. The -resulting list is always @code{nil}-terminated. If no @var{objects} -are given, the empty list is returned. - -@example -@group -(list 1 2 3 4 5) - @result{} (1 2 3 4 5) -@end group -@group -(list 1 2 '(3 4 5) 'foo) - @result{} (1 2 (3 4 5) foo) -@end group -@group -(list) - @result{} nil -@end group -@end example -@end defun - -@defun make-list length object -This function creates a list of @var{length} elements, in which each -element is @var{object}. Compare @code{make-list} with -@code{make-string} (@pxref{Creating Strings}). - -@example -@group -(make-list 3 'pigs) - @result{} (pigs pigs pigs) -@end group -@group -(make-list 0 'pigs) - @result{} nil -@end group -@group -(setq l (make-list 3 '(a b)) - @result{} ((a b) (a b) (a b)) -(eq (car l) (cadr l)) - @result{} t -@end group -@end example -@end defun - -@defun append &rest sequences -@cindex copying lists -This function returns a list containing all the elements of -@var{sequences}. The @var{sequences} may be lists, vectors, -bool-vectors, or strings, but the last one should usually be a list. -All arguments except the last one are copied, so none of the arguments -is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join -lists with no copying.) - -More generally, the final argument to @code{append} may be any Lisp -object. The final argument is not copied or converted; it becomes the -@sc{cdr} of the last cons cell in the new list. If the final argument -is itself a list, then its elements become in effect elements of the -result list. If the final element is not a list, the result is a -dotted list since its final @sc{cdr} is not @code{nil} as required -in a true list. - -In Emacs 20 and before, the @code{append} function also allowed -integers as (non last) arguments. It converted them to strings of -digits, making up the decimal print representation of the integer, and -then used the strings instead of the original integers. This obsolete -usage no longer works. The proper way to convert an integer to a -decimal number in this way is with @code{format} (@pxref{Formatting -Strings}) or @code{number-to-string} (@pxref{String Conversion}). -@end defun - - Here is an example of using @code{append}: - -@example -@group -(setq trees '(pine oak)) - @result{} (pine oak) -(setq more-trees (append '(maple birch) trees)) - @result{} (maple birch pine oak) -@end group - -@group -trees - @result{} (pine oak) -more-trees - @result{} (maple birch pine oak) -@end group -@group -(eq trees (cdr (cdr more-trees))) - @result{} t -@end group -@end example - - You can see how @code{append} works by looking at a box diagram. The -variable @code{trees} is set to the list @code{(pine oak)} and then the -variable @code{more-trees} is set to the list @code{(maple birch pine -oak)}. However, the variable @code{trees} continues to refer to the -original list: - -@smallexample -@group -more-trees trees -| | -| --- --- --- --- -> --- --- --- --- - --> | | |--> | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- --- --- - | | | | - | | | | - --> maple -->birch --> pine --> oak -@end group -@end smallexample - - An empty sequence contributes nothing to the value returned by -@code{append}. As a consequence of this, a final @code{nil} argument -forces a copy of the previous argument: - -@example -@group -trees - @result{} (pine oak) -@end group -@group -(setq wood (append trees nil)) - @result{} (pine oak) -@end group -@group -wood - @result{} (pine oak) -@end group -@group -(eq wood trees) - @result{} nil -@end group -@end example - -@noindent -This once was the usual way to copy a list, before the function -@code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}. - - Here we show the use of vectors and strings as arguments to @code{append}: - -@example -@group -(append [a b] "cd" nil) - @result{} (a b 99 100) -@end group -@end example - - With the help of @code{apply} (@pxref{Calling Functions}), we can append -all the lists in a list of lists: - -@example -@group -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end group -@end example - - If no @var{sequences} are given, @code{nil} is returned: - -@example -@group -(append) - @result{} nil -@end group -@end example - - Here are some examples where the final argument is not a list: - -@example -(append '(x y) 'z) - @result{} (x y . z) -(append '(x y) [z]) - @result{} (x y . [z]) -@end example - -@noindent -The second example shows that when the final argument is a sequence but -not a list, the sequence's elements do not become elements of the -resulting list. Instead, the sequence becomes the final @sc{cdr}, like -any other non-list final argument. - -@defun reverse list -This function creates a new list whose elements are the elements of -@var{list}, but in reverse order. The original argument @var{list} is -@emph{not} altered. - -@example -@group -(setq x '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@group -(reverse x) - @result{} (4 3 2 1) -x - @result{} (1 2 3 4) -@end group -@end example -@end defun - -@defun copy-tree tree &optional vecp -This function returns a copy of the tree @code{tree}. If @var{tree} is a -cons cell, this makes a new cons cell with the same @sc{car} and -@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the -same way. - -Normally, when @var{tree} is anything other than a cons cell, -@code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is -non-@code{nil}, it copies vectors too (and operates recursively on -their elements). -@end defun - -@defun number-sequence from &optional to separation -This returns a list of numbers starting with @var{from} and -incrementing by @var{separation}, and ending at or just before -@var{to}. @var{separation} can be positive or negative and defaults -to 1. If @var{to} is @code{nil} or numerically equal to @var{from}, -the value is the one-element list @code{(@var{from})}. If @var{to} is -less than @var{from} with a positive @var{separation}, or greater than -@var{from} with a negative @var{separation}, the value is @code{nil} -because those arguments specify an empty sequence. - -If @var{separation} is 0 and @var{to} is neither @code{nil} nor -numerically equal to @var{from}, @code{number-sequence} signals an -error, since those arguments specify an infinite sequence. - -All arguments can be integers or floating point numbers. However, -floating point arguments can be tricky, because floating point -arithmetic is inexact. For instance, depending on the machine, it may -quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns -the one element list @code{(0.4)}, whereas -@code{(number-sequence 0.4 0.8 0.2)} returns a list with three -elements. The @var{n}th element of the list is computed by the exact -formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if -one wants to make sure that @var{to} is included in the list, one can -pass an expression of this exact type for @var{to}. Alternatively, -one can replace @var{to} with a slightly larger value (or a slightly -more negative value if @var{separation} is negative). - -Some examples: - -@example -(number-sequence 4 9) - @result{} (4 5 6 7 8 9) -(number-sequence 9 4 -1) - @result{} (9 8 7 6 5 4) -(number-sequence 9 4 -2) - @result{} (9 7 5) -(number-sequence 8) - @result{} (8) -(number-sequence 8 5) - @result{} nil -(number-sequence 5 8 -1) - @result{} nil -(number-sequence 1.5 6 2) - @result{} (1.5 3.5 5.5) -@end example -@end defun - -@node List Variables -@section Modifying List Variables - - These functions, and one macro, provide convenient ways -to modify a list which is stored in a variable. - -@defmac push newelt listname -This macro provides an alternative way to write -@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. - -@example -(setq l '(a b)) - @result{} (a b) -(push 'c l) - @result{} (c a b) -l - @result{} (c a b) -@end example -@end defmac - - Two functions modify lists that are the values of variables. - -@defun add-to-list symbol element &optional append compare-fn -This function sets the variable @var{symbol} by consing @var{element} -onto the old value, if @var{element} is not already a member of that -value. It returns the resulting list, whether updated or not. The -value of @var{symbol} had better be a list already before the call. -@code{add-to-list} uses @var{compare-fn} to compare @var{element} -against existing list members; if @var{compare-fn} is @code{nil}, it -uses @code{equal}. - -Normally, if @var{element} is added, it is added to the front of -@var{symbol}, but if the optional argument @var{append} is -non-@code{nil}, it is added at the end. - -The argument @var{symbol} is not implicitly quoted; @code{add-to-list} -is an ordinary function, like @code{set} and unlike @code{setq}. Quote -the argument yourself if that is what you want. -@end defun - -Here's a scenario showing how to use @code{add-to-list}: - -@example -(setq foo '(a b)) - @result{} (a b) - -(add-to-list 'foo 'c) ;; @r{Add @code{c}.} - @result{} (c a b) - -(add-to-list 'foo 'b) ;; @r{No effect.} - @result{} (c a b) - -foo ;; @r{@code{foo} was changed.} - @result{} (c a b) -@end example - - An equivalent expression for @code{(add-to-list '@var{var} -@var{value})} is this: - -@example -(or (member @var{value} @var{var}) - (setq @var{var} (cons @var{value} @var{var}))) -@end example - -@defun add-to-ordered-list symbol element &optional order -This function sets the variable @var{symbol} by inserting -@var{element} into the old value, which must be a list, at the -position specified by @var{order}. If @var{element} is already a -member of the list, its position in the list is adjusted according -to @var{order}. Membership is tested using @code{eq}. -This function returns the resulting list, whether updated or not. - -The @var{order} is typically a number (integer or float), and the -elements of the list are sorted in non-decreasing numerical order. - -@var{order} may also be omitted or @code{nil}. Then the numeric order -of @var{element} stays unchanged if it already has one; otherwise, -@var{element} has no numeric order. Elements without a numeric list -order are placed at the end of the list, in no particular order. - -Any other value for @var{order} removes the numeric order of @var{element} -if it already has one; otherwise, it is equivalent to @code{nil}. - -The argument @var{symbol} is not implicitly quoted; -@code{add-to-ordered-list} is an ordinary function, like @code{set} -and unlike @code{setq}. Quote the argument yourself if that is what -you want. - -The ordering information is stored in a hash table on @var{symbol}'s -@code{list-order} property. -@end defun - -Here's a scenario showing how to use @code{add-to-ordered-list}: - -@example -(setq foo '()) - @result{} nil - -(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.} - @result{} (a) - -(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.} - @result{} (a c) - -(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.} - @result{} (a b c) - -(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.} - @result{} (a c b) - -(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} - @result{} (a c b d) - -(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. - @result{} (a c b e d) - -foo ;; @r{@code{foo} was changed.} - @result{} (a c b e d) -@end example - -@node Modifying Lists -@section Modifying Existing List Structure -@cindex destructive list operations - - You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the -primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' -operations because they change existing list structure. - -@cindex CL note---@code{rplaca} vs @code{setcar} -@quotation -@findex rplaca -@findex rplacd -@b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and -@code{rplacd} to alter list structure; they change structure the same -way as @code{setcar} and @code{setcdr}, but the Common Lisp functions -return the cons cell while @code{setcar} and @code{setcdr} return the -new @sc{car} or @sc{cdr}. -@end quotation - -@menu -* 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. -@end menu - -@node Setcar -@subsection Altering List Elements with @code{setcar} - - Changing the @sc{car} of a cons cell is done with @code{setcar}. When -used on a list, @code{setcar} replaces one element of a list with a -different element. - -@defun setcar cons object -This function stores @var{object} as the new @sc{car} of @var{cons}, -replacing its previous @sc{car}. In other words, it changes the -@sc{car} slot of @var{cons} to refer to @var{object}. It returns the -value @var{object}. For example: - -@example -@group -(setq x '(1 2)) - @result{} (1 2) -@end group -@group -(setcar x 4) - @result{} 4 -@end group -@group -x - @result{} (4 2) -@end group -@end example -@end defun - - When a cons cell is part of the shared structure of several lists, -storing a new @sc{car} into the cons changes one element of each of -these lists. Here is an example: - -@example -@group -;; @r{Create two lists that are partly shared.} -(setq x1 '(a b c)) - @result{} (a b c) -(setq x2 (cons 'z (cdr x1))) - @result{} (z b c) -@end group - -@group -;; @r{Replace the @sc{car} of a shared link.} -(setcar (cdr x1) 'foo) - @result{} foo -x1 ; @r{Both lists are changed.} - @result{} (a foo c) -x2 - @result{} (z foo c) -@end group - -@group -;; @r{Replace the @sc{car} of a link that is not shared.} -(setcar x1 'baz) - @result{} baz -x1 ; @r{Only one list is changed.} - @result{} (baz foo c) -x2 - @result{} (z foo c) -@end group -@end example - - Here is a graphical depiction of the shared structure of the two lists -in the variables @code{x1} and @code{x2}, showing why replacing @code{b} -changes them both: - -@example -@group - --- --- --- --- --- --- -x1---> | | |----> | | |--> | | |--> nil - --- --- --- --- --- --- - | --> | | - | | | | - --> a | --> b --> c - | - --- --- | -x2--> | | |-- - --- --- - | - | - --> z -@end group -@end example - - Here is an alternative form of box diagram, showing the same relationship: - -@example -@group -x1: - -------------- -------------- -------------- -| car | cdr | | car | cdr | | car | cdr | -| a | o------->| b | o------->| c | nil | -| | | -->| | | | | | - -------------- | -------------- -------------- - | -x2: | - -------------- | -| car | cdr | | -| z | o---- -| | | - -------------- -@end group -@end example - -@node Setcdr -@subsection Altering the CDR of a List - - The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: - -@defun setcdr cons object -This function stores @var{object} as the new @sc{cdr} of @var{cons}, -replacing its previous @sc{cdr}. In other words, it changes the -@sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the -value @var{object}. -@end defun - - Here is an example of replacing the @sc{cdr} of a list with a -different list. All but the first element of the list are removed in -favor of a different sequence of elements. The first element is -unchanged, because it resides in the @sc{car} of the list, and is not -reached via the @sc{cdr}. - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(setcdr x '(4)) - @result{} (4) -@end group -@group -x - @result{} (1 4) -@end group -@end example - - You can delete elements from the middle of a list by altering the -@sc{cdr}s of the cons cells in the list. For example, here we delete -the second element, @code{b}, from the list @code{(a b c)}, by changing -the @sc{cdr} of the first cons cell: - -@example -@group -(setq x1 '(a b c)) - @result{} (a b c) -(setcdr x1 (cdr (cdr x1))) - @result{} (c) -x1 - @result{} (a c) -@end group -@end example - - Here is the result in box notation: - -@smallexample -@group - -------------------- - | | - -------------- | -------------- | -------------- -| car | cdr | | | car | cdr | -->| car | cdr | -| a | o----- | b | o-------->| c | nil | -| | | | | | | | | - -------------- -------------- -------------- -@end group -@end smallexample - -@noindent -The second cons cell, which previously held the element @code{b}, still -exists and its @sc{car} is still @code{b}, but it no longer forms part -of this list. - - It is equally easy to insert a new element by changing @sc{cdr}s: - -@example -@group -(setq x1 '(a b c)) - @result{} (a b c) -(setcdr x1 (cons 'd (cdr x1))) - @result{} (d b c) -x1 - @result{} (a d b c) -@end group -@end example - - Here is this result in box notation: - -@smallexample -@group - -------------- ------------- ------------- -| car | cdr | | car | cdr | | car | cdr | -| a | o | -->| b | o------->| c | nil | -| | | | | | | | | | | - --------- | -- | ------------- ------------- - | | - ----- -------- - | | - | --------------- | - | | car | cdr | | - -->| d | o------ - | | | - --------------- -@end group -@end smallexample - -@node Rearrangement -@subsection Functions that Rearrange Lists -@cindex rearrangement of lists -@cindex modification of lists - - Here are some functions that rearrange lists ``destructively'' by -modifying the @sc{cdr}s of their component cons cells. We call these -functions ``destructive'' because they chew up the original lists passed -to them as arguments, relinking their cons cells to form a new list that -is the returned value. - -@ifnottex - See @code{delq}, in @ref{Sets And Lists}, for another function -that modifies cons cells. -@end ifnottex -@iftex - The function @code{delq} in the following section is another example -of destructive list manipulation. -@end iftex - -@defun nconc &rest lists -@cindex concatenating lists -@cindex joining lists -This function returns a list containing all the elements of @var{lists}. -Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are -@emph{not} copied. Instead, the last @sc{cdr} of each of the -@var{lists} is changed to refer to the following list. The last of the -@var{lists} is not altered. For example: - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(nconc x '(4 5)) - @result{} (1 2 3 4 5) -@end group -@group -x - @result{} (1 2 3 4 5) -@end group -@end example - - Since the last argument of @code{nconc} is not itself modified, it is -reasonable to use a constant list, such as @code{'(4 5)}, as in the -above example. For the same reason, the last argument need not be a -list: - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(nconc x 'z) - @result{} (1 2 3 . z) -@end group -@group -x - @result{} (1 2 3 . z) -@end group -@end example - -However, the other arguments (all but the last) must be lists. - -A common pitfall is to use a quoted constant list as a non-last -argument to @code{nconc}. If you do this, your program will change -each time you run it! Here is what happens: - -@smallexample -@group -(defun add-foo (x) ; @r{We want this function to add} - (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.} -@end group - -@group -(symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo)) x)) -@end group - -@group -(setq xx (add-foo '(1 2))) ; @r{It seems to work.} - @result{} (foo 1 2) -@end group -@group -(setq xy (add-foo '(3 4))) ; @r{What happened?} - @result{} (foo 1 2 3 4) -@end group -@group -(eq xx xy) - @result{} t -@end group - -@group -(symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) -@end group -@end smallexample -@end defun - -@defun nreverse list -@cindex reversing a list - This function reverses the order of the elements of @var{list}. -Unlike @code{reverse}, @code{nreverse} alters its argument by reversing -the @sc{cdr}s in the cons cells forming the list. The cons cell that -used to be the last one in @var{list} becomes the first cons cell of the -value. - - For example: - -@example -@group -(setq x '(a b c)) - @result{} (a b c) -@end group -@group -x - @result{} (a b c) -(nreverse x) - @result{} (c b a) -@end group -@group -;; @r{The cons cell that was first is now last.} -x - @result{} (a) -@end group -@end example - - To avoid confusion, we usually store the result of @code{nreverse} -back in the same variable which held the original list: - -@example -(setq x (nreverse x)) -@end example - - Here is the @code{nreverse} of our favorite example, @code{(a b c)}, -presented graphically: - -@smallexample -@group -@r{Original list head:} @r{Reversed list:} - ------------- ------------- ------------ -| car | cdr | | car | cdr | | car | cdr | -| a | nil |<-- | b | o |<-- | c | o | -| | | | | | | | | | | | | - ------------- | --------- | - | -------- | - - | | | | - ------------- ------------ -@end group -@end smallexample -@end defun - -@defun sort list predicate -@cindex stable sort -@cindex sorting lists -This function sorts @var{list} stably, though destructively, and -returns the sorted list. It compares elements using @var{predicate}. A -stable sort is one in which elements with equal sort keys maintain their -relative order before and after the sort. Stability is important when -successive sorts are used to order elements according to different -criteria. - -The argument @var{predicate} must be a function that accepts two -arguments. It is called with two elements of @var{list}. To get an -increasing order sort, the @var{predicate} should return non-@code{nil} if the -first element is ``less than'' the second, or @code{nil} if not. - -The comparison function @var{predicate} must give reliable results for -any given pair of arguments, at least within a single call to -@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is -less than @var{b}, @var{b} must not be less than @var{a}. It must be -@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} -is less than @var{c}, then @var{a} must be less than @var{c}. If you -use a comparison function which does not meet these requirements, the -result of @code{sort} is unpredictable. - -The destructive aspect of @code{sort} is that it rearranges the cons -cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort -function would create new cons cells to store the elements in their -sorted order. If you wish to make a sorted copy without destroying the -original, copy it first with @code{copy-sequence} and then sort. - -Sorting does not change the @sc{car}s of the cons cells in @var{list}; -the cons cell that originally contained the element @code{a} in -@var{list} still has @code{a} in its @sc{car} after sorting, but it now -appears in a different position in the list due to the change of -@sc{cdr}s. For example: - -@example -@group -(setq nums '(1 3 2 6 5 4 0)) - @result{} (1 3 2 6 5 4 0) -@end group -@group -(sort nums '<) - @result{} (0 1 2 3 4 5 6) -@end group -@group -nums - @result{} (1 2 3 4 5 6) -@end group -@end example - -@noindent -@strong{Warning}: Note that the list in @code{nums} no longer contains -0; this is the same cons cell that it was before, but it is no longer -the first one in the list. Don't assume a variable that formerly held -the argument now holds the entire sorted list! Instead, save the result -of @code{sort} and use that. Most often we store the result back into -the variable that held the original list: - -@example -(setq nums (sort nums '<)) -@end example - -@xref{Sorting}, for more functions that perform sorting. -See @code{documentation} in @ref{Accessing Documentation}, for a -useful example of @code{sort}. -@end defun - -@node Sets And Lists -@section Using Lists as Sets -@cindex lists as sets -@cindex sets - - A list can represent an unordered mathematical set---simply consider a -value an element of a set if it appears in the list, and ignore the -order of the list. To form the union of two sets, use @code{append} (as -long as you don't mind having duplicate elements). You can remove -@code{equal} duplicates using @code{delete-dups}. Other useful -functions for sets include @code{memq} and @code{delq}, and their -@code{equal} versions, @code{member} and @code{delete}. - -@cindex CL note---lack @code{union}, @code{intersection} -@quotation -@b{Common Lisp note:} Common Lisp has functions @code{union} (which -avoids duplicate elements) and @code{intersection} for set operations, -but GNU Emacs Lisp does not have them. You can write them in Lisp if -you wish. -@end quotation - -@defun memq object list -@cindex membership in a list -This function tests to see whether @var{object} is a member of -@var{list}. If it is, @code{memq} returns a list starting with the -first occurrence of @var{object}. Otherwise, it returns @code{nil}. -The letter @samp{q} in @code{memq} says that it uses @code{eq} to -compare @var{object} against the elements of the list. For example: - -@example -@group -(memq 'b '(a b c b a)) - @result{} (b c b a) -@end group -@group -(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} - @result{} nil -@end group -@end example -@end defun - -@defun delq object list -@cindex deleting list elements -This function destructively removes all elements @code{eq} to -@var{object} from @var{list}. The letter @samp{q} in @code{delq} says -that it uses @code{eq} to compare @var{object} against the elements of -the list, like @code{memq} and @code{remq}. -@end defun - -When @code{delq} deletes elements from the front of the list, it does so -simply by advancing down the list and returning a sublist that starts -after those elements: - -@example -@group -(delq 'a '(a b c)) @equiv{} (cdr '(a b c)) -@end group -@end example - -When an element to be deleted appears in the middle of the list, -removing it involves changing the @sc{cdr}s (@pxref{Setcdr}). - -@example -@group -(setq sample-list '(a b c (4))) - @result{} (a b c (4)) -@end group -@group -(delq 'a sample-list) - @result{} (b c (4)) -@end group -@group -sample-list - @result{} (a b c (4)) -@end group -@group -(delq 'c sample-list) - @result{} (a b (4)) -@end group -@group -sample-list - @result{} (a b (4)) -@end group -@end example - -Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to -splice out the third element, but @code{(delq 'a sample-list)} does not -splice anything---it just returns a shorter list. Don't assume that a -variable which formerly held the argument @var{list} now has fewer -elements, or that it still holds the original list! Instead, save the -result of @code{delq} and use that. Most often we store the result back -into the variable that held the original list: - -@example -(setq flowers (delq 'rose flowers)) -@end example - -In the following example, the @code{(4)} that @code{delq} attempts to match -and the @code{(4)} in the @code{sample-list} are not @code{eq}: - -@example -@group -(delq '(4) sample-list) - @result{} (a c (4)) -@end group - -If you want to delete elements that are @code{equal} to a given value, -use @code{delete} (see below). -@end example - -@defun remq object list -This function returns a copy of @var{list}, with all elements removed -which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq} -says that it uses @code{eq} to compare @var{object} against the elements -of @code{list}. - -@example -@group -(setq sample-list '(a b c a b c)) - @result{} (a b c a b c) -@end group -@group -(remq 'a sample-list) - @result{} (b c b c) -@end group -@group -sample-list - @result{} (a b c a b c) -@end group -@end example -@end defun - -@defun memql object list -The function @code{memql} tests to see whether @var{object} is a member -of @var{list}, comparing members with @var{object} using @code{eql}, -so floating point elements are compared by value. -If @var{object} is a member, @code{memql} returns a list starting with -its first occurrence in @var{list}. Otherwise, it returns @code{nil}. - -Compare this with @code{memq}: - -@example -@group -(memql 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are @code{eql}.} - @result{} (1.2 1.3) -@end group -@group -(memq 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are not @code{eq}.} - @result{} nil -@end group -@end example -@end defun - -The following three functions are like @code{memq}, @code{delq} and -@code{remq}, but use @code{equal} rather than @code{eq} to compare -elements. @xref{Equality Predicates}. - -@defun member object list -The function @code{member} tests to see whether @var{object} is a member -of @var{list}, comparing members with @var{object} using @code{equal}. -If @var{object} is a member, @code{member} returns a list starting with -its first occurrence in @var{list}. Otherwise, it returns @code{nil}. - -Compare this with @code{memq}: - -@example -@group -(member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.} - @result{} ((2)) -@end group -@group -(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} - @result{} nil -@end group -@group -;; @r{Two strings with the same contents are @code{equal}.} -(member "foo" '("foo" "bar")) - @result{} ("foo" "bar") -@end group -@end example -@end defun - -@defun delete object sequence -If @code{sequence} is a list, this function destructively removes all -elements @code{equal} to @var{object} from @var{sequence}. For lists, -@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it -uses @code{equal} to compare elements with @var{object}, like -@code{member}; when it finds an element that matches, it cuts the -element out just as @code{delq} would. - -If @code{sequence} is a vector or string, @code{delete} returns a copy -of @code{sequence} with all elements @code{equal} to @code{object} -removed. - -For example: - -@example -@group -(setq l '((2) (1) (2))) -(delete '(2) l) - @result{} ((1)) -l - @result{} ((2) (1)) -;; @r{If you want to change @code{l} reliably,} -;; @r{write @code{(setq l (delete elt l))}.} -@end group -@group -(setq l '((2) (1) (2))) -(delete '(1) l) - @result{} ((2) (2)) -l - @result{} ((2) (2)) -;; @r{In this case, it makes no difference whether you set @code{l},} -;; @r{but you should do so for the sake of the other case.} -@end group -@group -(delete '(2) [(2) (1) (2)]) - @result{} [(1)] -@end group -@end example -@end defun - -@defun remove object sequence -This function is the non-destructive counterpart of @code{delete}. It -returns a copy of @code{sequence}, a list, vector, or string, with -elements @code{equal} to @code{object} removed. For example: - -@example -@group -(remove '(2) '((2) (1) (2))) - @result{} ((1)) -@end group -@group -(remove '(2) [(2) (1) (2)]) - @result{} [(1)] -@end group -@end example -@end defun - -@quotation -@b{Common Lisp note:} The functions @code{member}, @code{delete} and -@code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common -Lisp. The Common Lisp versions do not use @code{equal} to compare -elements. -@end quotation - -@defun member-ignore-case object list -This function is like @code{member}, except that @var{object} should -be a string and that it ignores differences in letter-case and text -representation: upper-case and lower-case letters are treated as -equal, and unibyte strings are converted to multibyte prior to -comparison. -@end defun - -@defun delete-dups list -This function destructively removes all @code{equal} duplicates from -@var{list}, stores the result in @var{list} and returns it. Of -several @code{equal} occurrences of an element in @var{list}, -@code{delete-dups} keeps the first one. -@end defun - - See also the function @code{add-to-list}, in @ref{List Variables}, -for a way to add an element to a list stored in a variable and used as a -set. - -@node Association Lists -@section Association Lists -@cindex association list -@cindex alist - - An @dfn{association list}, or @dfn{alist} for short, records a mapping -from keys to values. It is a list of cons cells called -@dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the -@sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key'' -is not related to the term ``key sequence''; it means a value used to -look up an item in a table. In this case, the table is the alist, and -the alist associations are the items.} - - Here is an example of an alist. The key @code{pine} is associated with -the value @code{cones}; the key @code{oak} is associated with -@code{acorns}; and the key @code{maple} is associated with @code{seeds}. - -@example -@group -((pine . cones) - (oak . acorns) - (maple . seeds)) -@end group -@end example - - Both the values and the keys in an alist may be any Lisp objects. -For example, in the following alist, the symbol @code{a} is -associated with the number @code{1}, and the string @code{"b"} is -associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of -the alist element: - -@example -((a . 1) ("b" 2 3)) -@end example - - Sometimes it is better to design an alist to store the associated -value in the @sc{car} of the @sc{cdr} of the element. Here is an -example of such an alist: - -@example -((rose red) (lily white) (buttercup yellow)) -@end example - -@noindent -Here we regard @code{red} as the value associated with @code{rose}. One -advantage of this kind of alist is that you can store other related -information---even a list of other items---in the @sc{cdr} of the -@sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see -below) to find the element containing a given value. When neither of -these considerations is important, the choice is a matter of taste, as -long as you are consistent about it for any given alist. - - The same alist shown above could be regarded as having the -associated value in the @sc{cdr} of the element; the value associated -with @code{rose} would be the list @code{(red)}. - - Association lists are often used to record information that you might -otherwise keep on a stack, since new associations may be added easily to -the front of the list. When searching an association list for an -association with a given key, the first one found is returned, if there -is more than one. - - In Emacs Lisp, it is @emph{not} an error if an element of an -association list is not a cons cell. The alist search functions simply -ignore such elements. Many other versions of Lisp signal errors in such -cases. - - Note that property lists are similar to association lists in several -respects. A property list behaves like an association list in which -each key can occur only once. @xref{Property Lists}, for a comparison -of property lists and association lists. - -@defun assoc key alist -This function returns the first association for @var{key} in -@var{alist}, comparing @var{key} against the alist elements using -@code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no -association in @var{alist} has a @sc{car} @code{equal} to @var{key}. -For example: - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - @result{} ((pine . cones) (oak . acorns) (maple . seeds)) -(assoc 'oak trees) - @result{} (oak . acorns) -(cdr (assoc 'oak trees)) - @result{} acorns -(assoc 'birch trees) - @result{} nil -@end smallexample - -Here is another example, in which the keys and values are not symbols: - -@smallexample -(setq needles-per-cluster - '((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine"))) - -(cdr (assoc 3 needles-per-cluster)) - @result{} ("Pitch Pine") -(cdr (assoc 2 needles-per-cluster)) - @result{} ("Austrian Pine" "Red Pine") -@end smallexample -@end defun - - The function @code{assoc-string} is much like @code{assoc} except -that it ignores certain differences between strings. @xref{Text -Comparison}. - -@defun rassoc value alist -This function returns the first association with value @var{value} in -@var{alist}. It returns @code{nil} if no association in @var{alist} has -a @sc{cdr} @code{equal} to @var{value}. - -@code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of -each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assoc},'' finding the key for a given value. -@end defun - -@defun assq key alist -This function is like @code{assoc} in that it returns the first -association for @var{key} in @var{alist}, but it makes the comparison -using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil} -if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}. -This function is used more often than @code{assoc}, since @code{eq} is -faster than @code{equal} and most alists use symbols as keys. -@xref{Equality Predicates}. - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - @result{} ((pine . cones) (oak . acorns) (maple . seeds)) -(assq 'pine trees) - @result{} (pine . cones) -@end smallexample - -On the other hand, @code{assq} is not usually useful in alists where the -keys may not be symbols: - -@smallexample -(setq leaves - '(("simple leaves" . oak) - ("compound leaves" . horsechestnut))) - -(assq "simple leaves" leaves) - @result{} nil -(assoc "simple leaves" leaves) - @result{} ("simple leaves" . oak) -@end smallexample -@end defun - -@defun rassq value alist -This function returns the first association with value @var{value} in -@var{alist}. It returns @code{nil} if no association in @var{alist} has -a @sc{cdr} @code{eq} to @var{value}. - -@code{rassq} is like @code{assq} except that it compares the @sc{cdr} of -each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assq},'' finding the key for a given value. - -For example: - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - -(rassq 'acorns trees) - @result{} (oak . acorns) -(rassq 'spores trees) - @result{} nil -@end smallexample - -@code{rassq} cannot search for a value stored in the @sc{car} -of the @sc{cdr} of an element: - -@smallexample -(setq colors '((rose red) (lily white) (buttercup yellow))) - -(rassq 'white colors) - @result{} nil -@end smallexample - -In this case, the @sc{cdr} of the association @code{(lily white)} is not -the symbol @code{white}, but rather the list @code{(white)}. This -becomes clearer if the association is written in dotted pair notation: - -@smallexample -(lily white) @equiv{} (lily . (white)) -@end smallexample -@end defun - -@defun assoc-default key alist &optional test default -This function searches @var{alist} for a match for @var{key}. For each -element of @var{alist}, it compares the element (if it is an atom) or -the element's @sc{car} (if it is a cons) against @var{key}, by calling -@var{test} with two arguments: the element or its @sc{car}, and -@var{key}. The arguments are passed in that order so that you can get -useful results using @code{string-match} with an alist that contains -regular expressions (@pxref{Regexp Search}). If @var{test} is omitted -or @code{nil}, @code{equal} is used for comparison. - -If an alist element matches @var{key} by this criterion, -then @code{assoc-default} returns a value based on this element. -If the element is a cons, then the value is the element's @sc{cdr}. -Otherwise, the return value is @var{default}. - -If no alist element matches @var{key}, @code{assoc-default} returns -@code{nil}. -@end defun - -@defun copy-alist alist -@cindex copying alists -This function returns a two-level deep copy of @var{alist}: it creates a -new copy of each association, so that you can alter the associations of -the new alist without changing the old one. - -@smallexample -@group -(setq needles-per-cluster - '((2 . ("Austrian Pine" "Red Pine")) - (3 . ("Pitch Pine")) -@end group - (5 . ("White Pine")))) -@result{} -((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine")) - -(setq copy (copy-alist needles-per-cluster)) -@result{} -((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine")) - -(eq needles-per-cluster copy) - @result{} nil -(equal needles-per-cluster copy) - @result{} t -(eq (car needles-per-cluster) (car copy)) - @result{} nil -(cdr (car (cdr needles-per-cluster))) - @result{} ("Pitch Pine") -@group -(eq (cdr (car (cdr needles-per-cluster))) - (cdr (car (cdr copy)))) - @result{} t -@end group -@end smallexample - - This example shows how @code{copy-alist} makes it possible to change -the associations of one copy without affecting the other: - -@smallexample -@group -(setcdr (assq 3 copy) '("Martian Vacuum Pine")) -(cdr (assq 3 needles-per-cluster)) - @result{} ("Pitch Pine") -@end group -@end smallexample -@end defun - -@defun assq-delete-all key alist -This function deletes from @var{alist} all the elements whose @sc{car} -is @code{eq} to @var{key}, much as if you used @code{delq} to delete -each such element one by one. It returns the shortened alist, and -often modifies the original list structure of @var{alist}. For -correct results, use the return value of @code{assq-delete-all} rather -than looking at the saved value of @var{alist}. - -@example -(setq alist '((foo 1) (bar 2) (foo 3) (lose 4))) - @result{} ((foo 1) (bar 2) (foo 3) (lose 4)) -(assq-delete-all 'foo alist) - @result{} ((bar 2) (lose 4)) -alist - @result{} ((foo 1) (bar 2) (lose 4)) -@end example -@end defun - -@defun rassq-delete-all value alist -This function deletes from @var{alist} all the elements whose @sc{cdr} -is @code{eq} to @var{value}. It returns the shortened alist, and -often modifies the original list structure of @var{alist}. -@code{rassq-delete-all} is like @code{assq-delete-all} except that it -compares the @sc{cdr} of each @var{alist} association instead of the -@sc{car}. -@end defun - -@node Rings -@section Managing a Fixed-Size Ring of Objects - -@cindex ring data structure - This section describes functions for operating on rings. A -@dfn{ring} is a fixed-size data structure that supports insertion, -deletion, rotation, and modulo-indexed reference and traversal. - -@defun make-ring size -This returns a new ring capable of holding @var{size} objects. -@var{size} should be an integer. -@end defun - -@defun ring-p object -This returns @code{t} if @var{object} is a ring, @code{nil} otherwise. -@end defun - -@defun ring-size ring -This returns the maximum capacity of the @var{ring}. -@end defun - -@defun ring-length ring -This returns the number of objects that @var{ring} currently contains. -The value will never exceed that returned by @code{ring-size}. -@end defun - -@defun ring-elements ring -This returns a list of the objects in @var{ring}, in order, newest first. -@end defun - -@defun ring-copy ring -This returns a new ring which is a copy of @var{ring}. -The new ring contains the same (@code{eq}) objects as @var{ring}. -@end defun - -@defun ring-empty-p ring -This returns @code{t} if @var{ring} is empty, @code{nil} otherwise. -@end defun - - The newest element in the ring always has index 0. Higher indices -correspond to older elements. Indices are computed modulo the ring -length. Index @minus{}1 corresponds to the oldest element, @minus{}2 -to the next-oldest, and so forth. - -@defun ring-ref ring index -This returns the object in @var{ring} found at index @var{index}. -@var{index} may be negative or greater than the ring length. If -@var{ring} is empty, @code{ring-ref} signals an error. -@end defun - -@defun ring-insert ring object -This inserts @var{object} into @var{ring}, making it the newest -element, and returns @var{object}. - -If the ring is full, insertion removes the oldest element to -make room for the new element. -@end defun - -@defun ring-remove ring &optional index -Remove an object from @var{ring}, and return that object. The -argument @var{index} specifies which item to remove; if it is -@code{nil}, that means to remove the oldest item. If @var{ring} is -empty, @code{ring-remove} signals an error. -@end defun - -@defun ring-insert-at-beginning ring object -This inserts @var{object} into @var{ring}, treating it as the oldest -element. The return value is not significant. - -If the ring is full, this function removes the newest element to make -room for the inserted element. -@end defun - -@cindex fifo data structure - If you are careful not to exceed the ring size, you can -use the ring as a first-in-first-out queue. For example: - -@lisp -(let ((fifo (make-ring 5))) - (mapc (lambda (obj) (ring-insert fifo obj)) - '(0 one "two")) - (list (ring-remove fifo) t - (ring-remove fifo) t - (ring-remove fifo))) - @result{} (0 t one t "two") -@end lisp - -@ignore - arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4 -@end ignore diff --git a/lispref/loading.texi b/lispref/loading.texi deleted file mode 100644 index 058ed9c8984..00000000000 --- a/lispref/loading.texi +++ /dev/null @@ -1,968 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/loading -@node Loading, Byte Compilation, Customization, Top -@chapter Loading -@cindex loading -@cindex library -@cindex Lisp library - - Loading a file of Lisp code means bringing its contents into the Lisp -environment in the form of Lisp objects. Emacs finds and opens the -file, reads the text, evaluates each form, and then closes the file. - - The load functions evaluate all the expressions in a file just -as the @code{eval-buffer} function evaluates all the -expressions in a buffer. The difference is that the load functions -read and evaluate the text in the file as found on disk, not the text -in an Emacs buffer. - -@cindex top-level form - The loaded file must contain Lisp expressions, either as source code -or as byte-compiled code. Each form in the file is called a -@dfn{top-level form}. There is no special format for the forms in a -loadable file; any form in a file may equally well be typed directly -into a buffer and evaluated there. (Indeed, most code is tested this -way.) Most often, the forms are function definitions and variable -definitions. - - A file containing Lisp code is often called a @dfn{library}. Thus, -the ``Rmail library'' is a file containing code for Rmail mode. -Similarly, a ``Lisp library directory'' is a directory of files -containing Lisp code. - -@menu -* 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. -@end menu - -@node How Programs Do Loading -@section How Programs Do Loading - - Emacs Lisp has several interfaces for loading. For example, -@code{autoload} creates a placeholder object for a function defined in a -file; trying to call the autoloading function loads the file to get the -function's real definition (@pxref{Autoload}). @code{require} loads a -file if it isn't already loaded (@pxref{Named Features}). Ultimately, -all these facilities call the @code{load} function to do the work. - -@defun load filename &optional missing-ok nomessage nosuffix must-suffix -This function finds and opens a file of Lisp code, evaluates all the -forms in it, and closes the file. - -To find the file, @code{load} first looks for a file named -@file{@var{filename}.elc}, that is, for a file whose name is -@var{filename} with the extension @samp{.elc} appended. If such a -file exists, it is loaded. If there is no file by that name, then -@code{load} looks for a file named @file{@var{filename}.el}. If that -file exists, it is loaded. Finally, if neither of those names is -found, @code{load} looks for a file named @var{filename} with nothing -appended, and loads it if it exists. (The @code{load} function is not -clever about looking at @var{filename}. In the perverse case of a -file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will -indeed find it.) - -If Auto Compression mode is enabled, as it is by default, then if -@code{load} can not find a file, it searches for a compressed version -of the file before trying other file names. It decompresses and loads -it if it exists. It looks for compressed versions by appending each -of the suffixes in @code{jka-compr-load-suffixes} to the file name. -The value of this variable must be a list of strings. Its standard -value is @code{(".gz")}. - -If the optional argument @var{nosuffix} is non-@code{nil}, then -@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In -this case, you must specify the precise file name you want, except -that, if Auto Compression mode is enabled, @code{load} will still use -@code{jka-compr-load-suffixes} to find compressed versions. By -specifying the precise file name and using @code{t} for -@var{nosuffix}, you can prevent perverse file names such as -@file{foo.el.el} from being tried. - -If the optional argument @var{must-suffix} is non-@code{nil}, then -@code{load} insists that the file name used must end in either -@samp{.el} or @samp{.elc} (possibly extended with a compression -suffix), unless it contains an explicit directory name. - -If @var{filename} is a relative file name, such as @file{foo} or -@file{baz/foo.bar}, @code{load} searches for the file using the variable -@code{load-path}. It appends @var{filename} to each of the directories -listed in @code{load-path}, and loads the first file it finds whose name -matches. The current default directory is tried only if it is specified -in @code{load-path}, where @code{nil} stands for the default directory. -@code{load} tries all three possible suffixes in the first directory in -@code{load-path}, then all three suffixes in the second directory, and -so on. @xref{Library Search}. - -If you get a warning that @file{foo.elc} is older than @file{foo.el}, it -means you should consider recompiling @file{foo.el}. @xref{Byte -Compilation}. - -When loading a source file (not compiled), @code{load} performs -character set translation just as Emacs would do when visiting the file. -@xref{Coding Systems}. - -Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear -in the echo area during loading unless @var{nomessage} is -non-@code{nil}. - -@cindex load errors -Any unhandled errors while loading a file terminate loading. If the -load was done for the sake of @code{autoload}, any function definitions -made during the loading are undone. - -@kindex file-error -If @code{load} can't find the file to load, then normally it signals the -error @code{file-error} (with @samp{Cannot open load file -@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then -@code{load} just returns @code{nil}. - -You can use the variable @code{load-read-function} to specify a function -for @code{load} to use instead of @code{read} for reading expressions. -See below. - -@code{load} returns @code{t} if the file loads successfully. -@end defun - -@deffn Command load-file filename -This command loads the file @var{filename}. If @var{filename} is a -relative file name, then the current default directory is assumed. -This command does not use @code{load-path}, and does not append -suffixes. However, it does look for compressed versions (if Auto -Compression Mode is enabled). Use this command if you wish to specify -precisely the file name to load. -@end deffn - -@deffn Command load-library library -This command loads the library named @var{library}. It is equivalent to -@code{load}, except in how it reads its argument interactively. -@end deffn - -@defvar load-in-progress -This variable is non-@code{nil} if Emacs is in the process of loading a -file, and it is @code{nil} otherwise. -@end defvar - -@defvar load-read-function -@anchor{Definition of load-read-function} -@c do not allow page break at anchor; work around Texinfo deficiency. -This variable specifies an alternate expression-reading function for -@code{load} and @code{eval-region} to use instead of @code{read}. -The function should accept one argument, just as @code{read} does. - -Normally, the variable's value is @code{nil}, which means those -functions should use @code{read}. - -Instead of using this variable, it is cleaner to use another, newer -feature: to pass the function as the @var{read-function} argument to -@code{eval-region}. @xref{Definition of eval-region,, Eval}. -@end defvar - - For information about how @code{load} is used in building Emacs, see -@ref{Building Emacs}. - -@node Load Suffixes -@section Load Suffixes -We now describe some technical details about the exact suffixes that -@code{load} tries. - -@defvar load-suffixes -This is a list of suffixes indicating (compiled or source) Emacs Lisp -files. It should not include the empty string. @code{load} uses -these suffixes in order when it appends Lisp suffixes to the specified -file name. The standard value is @code{(".elc" ".el")} which produces -the behavior described in the previous section. -@end defvar - -@defvar load-file-rep-suffixes -This is a list of suffixes that indicate representations of the same -file. This list should normally start with the empty string. -When @code{load} searches for a file it appends the suffixes in this -list, in order, to the file name, before searching for another file. - -Enabling Auto Compression mode appends the suffixes in -@code{jka-compr-load-suffixes} to this list and disabling Auto -Compression mode removes them again. The standard value of -@code{load-file-rep-suffixes} if Auto Compression mode is disabled is -@code{("")}. Given that the standard value of -@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value -of @code{load-file-rep-suffixes} if Auto Compression mode is enabled -is @code{("" ".gz")}. -@end defvar - -@defun get-load-suffixes -This function returns the list of all suffixes that @code{load} should -try, in order, when its @var{must-suffix} argument is non-@code{nil}. -This takes both @code{load-suffixes} and @code{load-file-rep-suffixes} -into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes} -and @code{load-file-rep-suffixes} all have their standard values, this -function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto -Compression mode is enabled and @code{(".elc" ".el")} if Auto -Compression mode is disabled. -@end defun - -To summarize, @code{load} normally first tries the suffixes in the -value of @code{(get-load-suffixes)} and then those in -@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil}, -it skips the former group, and if @var{must-suffix} is non-@code{nil}, -it skips the latter group. - -@node Library Search -@section Library Search -@cindex library search -@cindex find library - - When Emacs loads a Lisp library, it searches for the library -in a list of directories specified by the variable @code{load-path}. - -@defopt load-path -@cindex @code{EMACSLOADPATH} environment variable -The value of this variable is a list of directories to search when -loading files with @code{load}. Each element is a string (which must be -a directory name) or @code{nil} (which stands for the current working -directory). -@end defopt - - The value of @code{load-path} is initialized from the environment -variable @code{EMACSLOADPATH}, if that exists; otherwise its default -value is specified in @file{emacs/src/epaths.h} when Emacs is built. -Then the list is expanded by adding subdirectories of the directories -in the list. - - The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH}; -@samp{:} (or @samp{;}, according to the operating system) separates -directory names, and @samp{.} is used for the current default directory. -Here is an example of how to set your @code{EMACSLOADPATH} variable from -a @code{csh} @file{.login} file: - -@smallexample -setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp -@end smallexample - - Here is how to set it using @code{sh}: - -@smallexample -export EMACSLOADPATH -EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp -@end smallexample - - Here is an example of code you can place in your init file (@pxref{Init -File}) to add several directories to the front of your default -@code{load-path}: - -@smallexample -@group -(setq load-path - (append (list nil "/user/bil/emacs" - "/usr/local/lisplib" - "~/emacs") - load-path)) -@end group -@end smallexample - -@c Wordy to rid us of an overfull hbox. --rjc 15mar92 -@noindent -In this example, the path searches the current working directory first, -followed then by the @file{/user/bil/emacs} directory, the -@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory, -which are then followed by the standard directories for Lisp code. - - Dumping Emacs uses a special value of @code{load-path}. If the value of -@code{load-path} at the end of dumping is unchanged (that is, still the -same special value), the dumped Emacs switches to the ordinary -@code{load-path} value when it starts up, as described above. But if -@code{load-path} has any other value at the end of dumping, that value -is used for execution of the dumped Emacs also. - - Therefore, if you want to change @code{load-path} temporarily for -loading a few libraries in @file{site-init.el} or @file{site-load.el}, -you should bind @code{load-path} locally with @code{let} around the -calls to @code{load}. - - The default value of @code{load-path}, when running an Emacs which has -been installed on the system, includes two special directories (and -their subdirectories as well): - -@smallexample -"/usr/local/share/emacs/@var{version}/site-lisp" -@end smallexample - -@noindent -and - -@smallexample -"/usr/local/share/emacs/site-lisp" -@end smallexample - -@noindent -The first one is for locally installed packages for a particular Emacs -version; the second is for locally installed packages meant for use with -all installed Emacs versions. - - There are several reasons why a Lisp package that works well in one -Emacs version can cause trouble in another. Sometimes packages need -updating for incompatible changes in Emacs; sometimes they depend on -undocumented internal Emacs data that can change without notice; -sometimes a newer Emacs version incorporates a version of the package, -and should be used only with that version. - - Emacs finds these directories' subdirectories and adds them to -@code{load-path} when it starts up. Both immediate subdirectories and -subdirectories multiple levels down are added to @code{load-path}. - - Not all subdirectories are included, though. Subdirectories whose -names do not start with a letter or digit are excluded. Subdirectories -named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which -contains a file named @file{.nosearch} is excluded. You can use these -methods to prevent certain subdirectories of the @file{site-lisp} -directories from being searched. - - If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---then @code{load-path} -normally contains two additional directories. These are the @code{lisp} -and @code{site-lisp} subdirectories of the main build directory. (Both -are represented as absolute file names.) - -@deffn Command locate-library library &optional nosuffix path interactive-call -This command finds the precise file name for library @var{library}. It -searches for the library in the same way @code{load} does, and the -argument @var{nosuffix} has the same meaning as in @code{load}: don't -add suffixes @samp{.elc} or @samp{.el} to the specified name -@var{library}. - -If the @var{path} is non-@code{nil}, that list of directories is used -instead of @code{load-path}. - -When @code{locate-library} is called from a program, it returns the file -name as a string. When the user runs @code{locate-library} -interactively, the argument @var{interactive-call} is @code{t}, and this -tells @code{locate-library} to display the file name in the echo area. -@end deffn - -@node Loading Non-ASCII -@section Loading Non-@acronym{ASCII} Characters - - When Emacs Lisp programs contain string constants with non-@acronym{ASCII} -characters, these can be represented within Emacs either as unibyte -strings or as multibyte strings (@pxref{Text Representations}). Which -representation is used depends on how the file is read into Emacs. If -it is read with decoding into multibyte representation, the text of the -Lisp program will be multibyte text, and its string constants will be -multibyte strings. If a file containing Latin-1 characters (for -example) is read without decoding, the text of the program will be -unibyte text, and its string constants will be unibyte strings. -@xref{Coding Systems}. - - To make the results more predictable, Emacs always performs decoding -into the multibyte representation when loading Lisp files, even if it -was started with the @samp{--unibyte} option. This means that string -constants with non-@acronym{ASCII} characters translate into multibyte -strings. The only exception is when a particular file specifies no -decoding. - - The reason Emacs is designed this way is so that Lisp programs give -predictable results, regardless of how Emacs was started. In addition, -this enables programs that depend on using multibyte text to work even -in a unibyte Emacs. Of course, such programs should be designed to -notice whether the user prefers unibyte or multibyte text, by checking -@code{default-enable-multibyte-characters}, and convert representations -appropriately. - - In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are -multibyte strings should not be noticeable, since inserting them in -unibyte buffers converts them to unibyte automatically. However, if -this does make a difference, you can force a particular Lisp file to be -interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a -comment on the file's first line. With that designator, the file will -unconditionally be interpreted as unibyte, even in an ordinary -multibyte Emacs session. This can matter when making keybindings to -non-@acronym{ASCII} characters written as @code{?v@var{literal}}. - -@node Autoload -@section Autoload -@cindex autoload - - The @dfn{autoload} facility allows you to make a function or macro -known in Lisp, but put off loading the file that defines it. The first -call to the function automatically reads the proper file to install the -real definition and other associated code, then runs the real definition -as if it had been loaded all along. - - There are two ways to set up an autoloaded function: by calling -@code{autoload}, and by writing a special ``magic'' comment in the -source before the real definition. @code{autoload} is the low-level -primitive for autoloading; any Lisp program can call @code{autoload} at -any time. Magic comments are the most convenient way to make a function -autoload, for packages installed along with Emacs. These comments do -nothing on their own, but they serve as a guide for the command -@code{update-file-autoloads}, which constructs calls to @code{autoload} -and arranges to execute them when Emacs is built. - -@defun autoload function filename &optional docstring interactive type -This function defines the function (or macro) named @var{function} so as -to load automatically from @var{filename}. The string @var{filename} -specifies the file to load to get the real definition of @var{function}. - -If @var{filename} does not contain either a directory name, or the -suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding -one of these suffixes, and it will not load from a file whose name is -just @var{filename} with no added suffix. (The variable -@code{load-suffixes} specifies the exact required suffixes.) - -The argument @var{docstring} is the documentation string for the -function. Specifying the documentation string in the call to -@code{autoload} makes it possible to look at the documentation without -loading the function's real definition. Normally, this should be -identical to the documentation string in the function definition -itself. If it isn't, the function definition's documentation string -takes effect when it is loaded. - -If @var{interactive} is non-@code{nil}, that says @var{function} can be -called interactively. This lets completion in @kbd{M-x} work without -loading @var{function}'s real definition. The complete interactive -specification is not given here; it's not needed unless the user -actually calls @var{function}, and when that happens, it's time to load -the real definition. - -You can autoload macros and keymaps as well as ordinary functions. -Specify @var{type} as @code{macro} if @var{function} is really a macro. -Specify @var{type} as @code{keymap} if @var{function} is really a -keymap. Various parts of Emacs need to know this information without -loading the real definition. - -An autoloaded keymap loads automatically during key lookup when a prefix -key's binding is the symbol @var{function}. Autoloading does not occur -for other kinds of access to the keymap. In particular, it does not -happen when a Lisp program gets the keymap from the value of a variable -and calls @code{define-key}; not even if the variable name is the same -symbol @var{function}. - -@cindex function cell in autoload -If @var{function} already has a non-void function definition that is not -an autoload object, @code{autoload} does nothing and returns @code{nil}. -If the function cell of @var{function} is void, or is already an autoload -object, then it is defined as an autoload object like this: - -@example -(autoload @var{filename} @var{docstring} @var{interactive} @var{type}) -@end example - -For example, - -@example -@group -(symbol-function 'run-prolog) - @result{} (autoload "prolog" 169681 t nil) -@end group -@end example - -@noindent -In this case, @code{"prolog"} is the name of the file to load, 169681 -refers to the documentation string in the -@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}), -@code{t} means the function is interactive, and @code{nil} that it is -not a macro or a keymap. -@end defun - -@cindex autoload errors - The autoloaded file usually contains other definitions and may require -or provide one or more features. If the file is not completely loaded -(due to an error in the evaluation of its contents), any function -definitions or @code{provide} calls that occurred during the load are -undone. This is to ensure that the next attempt to call any function -autoloading from this file will try again to load the file. If not for -this, then some of the functions in the file might be defined by the -aborted load, but fail to work properly for the lack of certain -subroutines not loaded successfully because they come later in the file. - - If the autoloaded file fails to define the desired Lisp function or -macro, then an error is signaled with data @code{"Autoloading failed to -define function @var{function-name}"}. - -@findex update-file-autoloads -@findex update-directory-autoloads -@cindex magic autoload comment -@cindex autoload cookie -@anchor{autoload cookie} - A magic autoload comment (often called an @dfn{autoload cookie}) -consists of @samp{;;;###autoload}, on a line by itself, -just before the real definition of the function in its -autoloadable source file. The command @kbd{M-x update-file-autoloads} -writes a corresponding @code{autoload} call into @file{loaddefs.el}. -Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. -@kbd{M-x update-directory-autoloads} is even more powerful; it updates -autoloads for all files in the current directory. - - The same magic comment can copy any kind of form into -@file{loaddefs.el}. If the form following the magic comment is not a -function-defining form or a @code{defcustom} form, it is copied -verbatim. ``Function-defining forms'' include @code{define-skeleton}, -@code{define-derived-mode}, @code{define-generic-mode} and -@code{define-minor-mode} as well as @code{defun} and -@code{defmacro}. To save space, a @code{defcustom} form is converted to -a @code{defvar} in @file{loaddefs.el}, with some additional information -if it uses @code{:require}. - - You can also use a magic comment to execute a form at build time -@emph{without} executing it when the file itself is loaded. To do this, -write the form @emph{on the same line} as the magic comment. Since it -is in a comment, it does nothing when you load the source file; but -@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where -it is executed while building Emacs. - - The following example shows how @code{doctor} is prepared for -autoloading with a magic comment: - -@smallexample -;;;###autoload -(defun doctor () - "Switch to *doctor* buffer and start giving psychotherapy." - (interactive) - (switch-to-buffer "*doctor*") - (doctor-mode)) -@end smallexample - -@noindent -Here's what that produces in @file{loaddefs.el}: - -@smallexample -(autoload (quote doctor) "doctor" "\ -Switch to *doctor* buffer and start giving psychotherapy. - -\(fn)" t nil) -@end smallexample - -@noindent -@cindex @code{fn} in function's documentation string -The backslash and newline immediately following the double-quote are a -convention used only in the preloaded uncompiled Lisp files such as -@file{loaddefs.el}; they tell @code{make-docfile} to put the -documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. -See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)} -in the usage part of the documentation string is replaced with the -function's name when the various help functions (@pxref{Help -Functions}) display it. - - If you write a function definition with an unusual macro that is not -one of the known and recognized function definition methods, use of an -ordinary magic autoload comment would copy the whole definition into -@code{loaddefs.el}. That is not desirable. You can put the desired -@code{autoload} call into @code{loaddefs.el} instead by writing this: - -@smallexample -;;;###autoload (autoload 'foo "myfile") -(mydefunmacro foo - ...) -@end smallexample - -@node Repeated Loading -@section Repeated Loading -@cindex repeated loading - - You can load a given file more than once in an Emacs session. For -example, after you have rewritten and reinstalled a function definition -by editing it in a buffer, you may wish to return to the original -version; you can do this by reloading the file it came from. - - When you load or reload files, bear in mind that the @code{load} and -@code{load-library} functions automatically load a byte-compiled file -rather than a non-compiled file of similar name. If you rewrite a file -that you intend to save and reinstall, you need to byte-compile the new -version; otherwise Emacs will load the older, byte-compiled file instead -of your newer, non-compiled file! If that happens, the message -displayed when loading the file includes, @samp{(compiled; note, source is -newer)}, to remind you to recompile it. - - When writing the forms in a Lisp library file, keep in mind that the -file might be loaded more than once. For example, think about whether -each variable should be reinitialized when you reload the library; -@code{defvar} does not change the value if the variable is already -initialized. (@xref{Defining Variables}.) - - The simplest way to add an element to an alist is like this: - -@example -(push '(leif-mode " Leif") minor-mode-alist) -@end example - -@noindent -But this would add multiple elements if the library is reloaded. -To avoid the problem, write this: - -@example -(or (assq 'leif-mode minor-mode-alist) - (push '(leif-mode " Leif") minor-mode-alist)) -@end example - -@noindent -or this: - -@example -(add-to-list '(leif-mode " Leif") minor-mode-alist) -@end example - - Occasionally you will want to test explicitly whether a library has -already been loaded. Here's one way to test, in a library, whether it -has been loaded before: - -@example -(defvar foo-was-loaded nil) - -(unless foo-was-loaded - @var{execute-first-time-only} - (setq foo-was-loaded t)) -@end example - -@noindent -If the library uses @code{provide} to provide a named feature, you can -use @code{featurep} earlier in the file to test whether the -@code{provide} call has been executed before. -@ifnottex -@xref{Named Features}. -@end ifnottex - -@node Named Features -@section Features -@cindex features -@cindex requiring features -@cindex providing features - - @code{provide} and @code{require} are an alternative to -@code{autoload} for loading files automatically. They work in terms of -named @dfn{features}. Autoloading is triggered by calling a specific -function, but a feature is loaded the first time another program asks -for it by name. - - A feature name is a symbol that stands for a collection of functions, -variables, etc. The file that defines them should @dfn{provide} the -feature. Another program that uses them may ensure they are defined by -@dfn{requiring} the feature. This loads the file of definitions if it -hasn't been loaded already. - - To require the presence of a feature, call @code{require} with the -feature name as argument. @code{require} looks in the global variable -@code{features} to see whether the desired feature has been provided -already. If not, it loads the feature from the appropriate file. This -file should call @code{provide} at the top level to add the feature to -@code{features}; if it fails to do so, @code{require} signals an error. -@cindex load error with require - - For example, in @file{emacs/lisp/prolog.el}, -the definition for @code{run-prolog} includes the following code: - -@smallexample -(defun run-prolog () - "Run an inferior Prolog process, with I/O via buffer *prolog*." - (interactive) - (require 'comint) - (switch-to-buffer (make-comint "prolog" prolog-program-name)) - (inferior-prolog-mode)) -@end smallexample - -@noindent -The expression @code{(require 'comint)} loads the file @file{comint.el} -if it has not yet been loaded. This ensures that @code{make-comint} is -defined. Features are normally named after the files that provide them, -so that @code{require} need not be given the file name. - -The @file{comint.el} file contains the following top-level expression: - -@smallexample -(provide 'comint) -@end smallexample - -@noindent -This adds @code{comint} to the global @code{features} list, so that -@code{(require 'comint)} will henceforth know that nothing needs to be -done. - -@cindex byte-compiling @code{require} - When @code{require} is used at top level in a file, it takes effect -when you byte-compile that file (@pxref{Byte Compilation}) as well as -when you load it. This is in case the required package contains macros -that the byte compiler must know about. It also avoids byte-compiler -warnings for functions and variables defined in the file loaded with -@code{require}. - - Although top-level calls to @code{require} are evaluated during -byte compilation, @code{provide} calls are not. Therefore, you can -ensure that a file of definitions is loaded before it is byte-compiled -by including a @code{provide} followed by a @code{require} for the same -feature, as in the following example. - -@smallexample -@group -(provide 'my-feature) ; @r{Ignored by byte compiler,} - ; @r{evaluated by @code{load}.} -(require 'my-feature) ; @r{Evaluated by byte compiler.} -@end group -@end smallexample - -@noindent -The compiler ignores the @code{provide}, then processes the -@code{require} by loading the file in question. Loading the file does -execute the @code{provide} call, so the subsequent @code{require} call -does nothing when the file is loaded. - -@defun provide feature &optional subfeatures -This function announces that @var{feature} is now loaded, or being -loaded, into the current Emacs session. This means that the facilities -associated with @var{feature} are or will be available for other Lisp -programs. - -The direct effect of calling @code{provide} is to add @var{feature} to -the front of the list @code{features} if it is not already in the list. -The argument @var{feature} must be a symbol. @code{provide} returns -@var{feature}. - -If provided, @var{subfeatures} should be a list of symbols indicating -a set of specific subfeatures provided by this version of -@var{feature}. You can test the presence of a subfeature using -@code{featurep}. The idea of subfeatures is that you use them when a -package (which is one @var{feature}) is complex enough to make it -useful to give names to various parts or functionalities of the -package, which might or might not be loaded, or might or might not be -present in a given version. @xref{Network Feature Testing}, for -an example. - -@smallexample -features - @result{} (bar bish) - -(provide 'foo) - @result{} foo -features - @result{} (foo bar bish) -@end smallexample - -When a file is loaded to satisfy an autoload, and it stops due to an -error in the evaluation of its contents, any function definitions or -@code{provide} calls that occurred during the load are undone. -@xref{Autoload}. -@end defun - -@defun require feature &optional filename noerror -This function checks whether @var{feature} is present in the current -Emacs session (using @code{(featurep @var{feature})}; see below). The -argument @var{feature} must be a symbol. - -If the feature is not present, then @code{require} loads @var{filename} -with @code{load}. If @var{filename} is not supplied, then the name of -the symbol @var{feature} is used as the base file name to load. -However, in this case, @code{require} insists on finding @var{feature} -with an added @samp{.el} or @samp{.elc} suffix (possibly extended with -a compression suffix); a file whose name is just @var{feature} won't -be used. (The variable @code{load-suffixes} specifies the exact -required Lisp suffixes.) - -If @var{noerror} is non-@code{nil}, that suppresses errors from actual -loading of the file. In that case, @code{require} returns @code{nil} -if loading the file fails. Normally, @code{require} returns -@var{feature}. - -If loading the file succeeds but does not provide @var{feature}, -@code{require} signals an error, @samp{Required feature @var{feature} -was not provided}. -@end defun - -@defun featurep feature &optional subfeature -This function returns @code{t} if @var{feature} has been provided in -the current Emacs session (i.e.@:, if @var{feature} is a member of -@code{features}.) If @var{subfeature} is non-@code{nil}, then the -function returns @code{t} only if that subfeature is provided as well -(i.e.@: if @var{subfeature} is a member of the @code{subfeature} -property of the @var{feature} symbol.) -@end defun - -@defvar features -The value of this variable is a list of symbols that are the features -loaded in the current Emacs session. Each symbol was put in this list -with a call to @code{provide}. The order of the elements in the -@code{features} list is not significant. -@end defvar - -@node Where Defined -@section Which File Defined a Certain Symbol - -@defun symbol-file symbol &optional type -This function returns the name of the file that defined @var{symbol}. -If @var{type} is @code{nil}, then any kind of definition is -acceptable. If @var{type} is @code{defun} or @code{defvar}, that -specifies function definition only or variable definition only. - -The value is normally an absolute file name. It can also be -@code{nil}, if the definition is not associated with any file. -@end defun - - The basis for @code{symbol-file} is the data in the variable -@code{load-history}. - -@defvar load-history -This variable's value is an alist connecting library file names with the -names of functions and variables they define, the features they provide, -and the features they require. - -Each element is a list and describes one library. The @sc{car} of the -list is the absolute file name of the library, as a string. The rest -of the list elements have these forms: - -@table @code -@item @var{var} -The symbol @var{var} was defined as a variable. -@item (defun . @var{fun}) -The function @var{fun} was defined. -@item (t . @var{fun}) -The function @var{fun} was previously an autoload before this library -redefined it as a function. The following element is always -@code{(defun . @var{fun})}, which represents defining @var{fun} as a -function. -@item (autoload . @var{fun}) -The function @var{fun} was defined as an autoload. -@item (require . @var{feature}) -The feature @var{feature} was required. -@item (provide . @var{feature}) -The feature @var{feature} was provided. -@end table - -The value of @code{load-history} may have one element whose @sc{car} is -@code{nil}. This element describes definitions made with -@code{eval-buffer} on a buffer that is not visiting a file. -@end defvar - - The command @code{eval-region} updates @code{load-history}, but does so -by adding the symbols defined to the element for the file being visited, -rather than replacing that element. @xref{Eval}. - -@node Unloading -@section Unloading -@cindex unloading packages - -@c Emacs 19 feature - You can discard the functions and variables loaded by a library to -reclaim memory for other Lisp objects. To do this, use the function -@code{unload-feature}: - -@deffn Command unload-feature feature &optional force -This command unloads the library that provided feature @var{feature}. -It undefines all functions, macros, and variables defined in that -library with @code{defun}, @code{defalias}, @code{defsubst}, -@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}. -It then restores any autoloads formerly associated with those symbols. -(Loading saves these in the @code{autoload} property of the symbol.) - -@vindex unload-feature-special-hooks -Before restoring the previous definitions, @code{unload-feature} runs -@code{remove-hook} to remove functions in the library from certain -hooks. These hooks include variables whose names end in @samp{hook} -or @samp{-hooks}, plus those listed in -@code{unload-feature-special-hooks}. This is to prevent Emacs from -ceasing to function because important hooks refer to functions that -are no longer defined. - -@vindex @var{feature}-unload-hook -If these measures are not sufficient to prevent malfunction, a library -can define an explicit unload hook. If @code{@var{feature}-unload-hook} -is defined, it is run as a normal hook before restoring the previous -definitions, @emph{instead of} the usual hook-removing actions. The -unload hook ought to undo all the global state changes made by the -library that might cease to work once the library is unloaded. -@code{unload-feature} can cause problems with libraries that fail to do -this, so it should be used with caution. - -Ordinarily, @code{unload-feature} refuses to unload a library on which -other loaded libraries depend. (A library @var{a} depends on library -@var{b} if @var{a} contains a @code{require} for @var{b}.) If the -optional argument @var{force} is non-@code{nil}, dependencies are -ignored and you can unload any library. -@end deffn - - The @code{unload-feature} function is written in Lisp; its actions are -based on the variable @code{load-history}. - -@defvar unload-feature-special-hooks -This variable holds a list of hooks to be scanned before unloading a -library, to remove functions defined in the library. -@end defvar - -@node Hooks for Loading -@section Hooks for Loading -@cindex loading hooks -@cindex hooks for loading - -You can ask for code to be executed if and when a particular library is -loaded, by calling @code{eval-after-load}. - -@defun eval-after-load library form -This function arranges to evaluate @var{form} at the end of loading -the file @var{library}, each time @var{library} is loaded. If -@var{library} is already loaded, it evaluates @var{form} right away. -Don't forget to quote @var{form}! - -You don't need to give a directory or extension in the file name -@var{library}---normally you just give a bare file name, like this: - -@example -(eval-after-load "edebug" '(def-edebug-spec c-point t)) -@end example - -To restrict which files can trigger the evaluation, include a -directory or an extension or both in @var{library}. Only a file whose -absolute true name (i.e., the name with all symbolic links chased out) -matches all the given name components will match. In the following -example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory -@code{..../foo/bar} will trigger the evaluation, but not -@file{my_inst.el}: - -@example -(eval-after-load "foo/bar/my_inst.elc" @dots{}) -@end example - -@var{library} can also be a feature (i.e.@: a symbol), in which case -@var{form} is evaluated when @code{(provide @var{library})} is called. - -An error in @var{form} does not undo the load, but does prevent -execution of the rest of @var{form}. -@end defun - -In general, well-designed Lisp programs should not use this feature. -The clean and modular ways to interact with a Lisp library are (1) -examine and set the library's variables (those which are meant for -outside use), and (2) call the library's functions. If you wish to -do (1), you can do it immediately---there is no need to wait for when -the library is loaded. To do (2), you must load the library (preferably -with @code{require}). - -But it is OK to use @code{eval-after-load} in your personal -customizations if you don't feel they must meet the design standards for -programs meant for wider use. - -@defvar after-load-alist -This variable, an alist built by @code{eval-after-load}, holds the -expressions to evaluate when particular libraries are loaded. Each -element looks like this: - -@example -(@var{regexp-or-feature} @var{forms}@dots{}) -@end example - -The key @var{regexp-or-feature} is either a regular expression or a -symbol, and the value is a list of forms. The forms are evaluated when -the key matches the absolute true name of the file being -@code{load}ed or the symbol being @code{provide}d. -@end defvar - -@ignore - arch-tag: df731f89-0900-4389-a436-9105241b6f7a -@end ignore diff --git a/lispref/locals.texi b/lispref/locals.texi deleted file mode 100644 index 4edbc2a815f..00000000000 --- a/lispref/locals.texi +++ /dev/null @@ -1,232 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/locals -@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top -@appendix Buffer-Local Variables -@c The title "Standard Buffer-Local Variables" is too long for -@c smallbook. --rjc 30mar92 -@cindex buffer-local variables, general-purpose -@cindex standard buffer-local variables - - The table below lists the general-purpose Emacs variables that -automatically become buffer-local in each buffer. Most become -buffer-local only when set; a few of them are always local in every -buffer. Many Lisp packages define such variables for their internal -use, but we don't try to list them all here. - - Every buffer-specific minor mode defines a buffer-local variable -named @samp{@var{modename}-mode}. @xref{Minor Mode Conventions}. -Minor mode variables will not be listed here. - -@table @code -@item auto-fill-function -@xref{Auto Filling}. - -@item buffer-auto-save-file-format -@xref{Format Conversion}. - -@item buffer-auto-save-file-name -@xref{Auto-Saving}. - -@item buffer-backed-up -@xref{Making Backups}. - -@item buffer-display-count -@xref{Buffers and Windows}. - -@item buffer-display-table -@xref{Active Display Table}. - -@item buffer-display-time -@xref{Buffers and Windows}. - -@item buffer-file-coding-system -@xref{Encoding and I/O}. - -@item buffer-file-format -@xref{Format Conversion}. - -@item buffer-file-name -@xref{Buffer File Name}. - -@item buffer-file-number -@xref{Buffer File Name}. - -@item buffer-file-truename -@xref{Buffer File Name}. - -@item buffer-file-type -@xref{MS-DOS File Types}. - -@item buffer-invisibility-spec -@xref{Invisible Text}. - -@item buffer-offer-save -@xref{Killing Buffers}. - -@item buffer-save-without-query -@xref{Killing Buffers}. - -@item buffer-read-only -@xref{Read Only Buffers}. - -@item buffer-saved-size -@xref{Auto-Saving}. - -@item buffer-undo-list -@xref{Undo}. - -@item cache-long-line-scans -@xref{Truncation}. - -@item case-fold-search -@xref{Searching and Case}. - -@item ctl-arrow -@xref{Usual Display}. - -@item cursor-type -@xref{Cursor Parameters}. - -@item cursor-in-non-selected-windows -@xref{Basic Windows}. - -@item comment-column -@xref{Comments,,, emacs, The GNU Emacs Manual}. - -@item default-directory -@xref{File Name Expansion}. - -@item defun-prompt-regexp -@xref{List Motion}. - -@item desktop-save-buffer -@xref{Desktop Save Mode}. - -@ignore -@item direction-reversed -Does not work yet. -@end ignore - -@item enable-multibyte-characters -@ref{Text Representations}. - -@item fill-column -@xref{Margins}. - -@item fill-prefix -@xref{Margins}. - -@item font-lock-defaults -@xref{Font Lock Basics}. - -@item fringe-cursor-alist -@xref{Fringe Cursors}. - -@item fringe-indicator-alist -@xref{Fringe Indicators}. - -@item fringes-outside-margins -@xref{Fringes}. - -@item goal-column -@xref{Moving Point,,, emacs, The GNU Emacs Manual}. - -@item header-line-format -@xref{Header Lines}. - -@item indicate-buffer-boundaries -@xref{Usual Display}. - -@item indicate-empty-lines -@xref{Usual Display}. - -@item left-fringe-width -@xref{Fringe Size/Pos}. - -@item left-margin -@xref{Margins}. - -@item left-margin-width -@xref{Display Margins}. - -@item line-spacing -@xref{Line Height}. - -@item local-abbrev-table -@xref{Standard Abbrev Tables}. - -@item major-mode -@xref{Mode Help}. - -@item mark-active -@xref{The Mark}. - -@item mark-ring -@xref{The Mark}. - -@item mode-line-buffer-identification -@xref{Mode Line Variables}. - -@item mode-line-format -@xref{Mode Line Data}. - -@item mode-line-modified -@xref{Mode Line Variables}. - -@item mode-line-process -@xref{Mode Line Variables}. - -@item mode-name -@xref{Mode Line Variables}. - -@item point-before-scroll -Used for communication between mouse commands and scroll-bar commands. - -@item right-fringe-width -@xref{Fringe Size/Pos}. - -@item right-margin-width -@xref{Display Margins}. - -@item save-buffer-coding-system -@xref{Encoding and I/O}. - -@item scroll-bar-width -@xref{Scroll Bars}. - -@item scroll-down-aggressively -@xref{Textual Scrolling}. - -@item scroll-up-aggressively -@xref{Textual Scrolling}. - -@item selective-display -@xref{Selective Display}. - -@item selective-display-ellipses -@xref{Selective Display}. - -@item tab-width -@xref{Usual Display}. - -@item truncate-lines -@xref{Truncation}. - -@item vertical-scroll-bar -@xref{Scroll Bars}. - -@item window-size-fixed -@xref{Resizing Windows}. - -@item write-contents-functions -@xref{Saving Buffers}. -@end table - - -@ignore - arch-tag: 6baae835-b667-4447-91e2-9829ae1cf543 -@end ignore diff --git a/lispref/macros.texi b/lispref/macros.texi deleted file mode 100644 index b62c8b99d74..00000000000 --- a/lispref/macros.texi +++ /dev/null @@ -1,752 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/macros -@node Macros, Customization, Functions, Top -@chapter Macros -@cindex macros - - @dfn{Macros} enable you to define new control constructs and other -language features. A macro is defined much like a function, but instead -of telling how to compute a value, it tells how to compute another Lisp -expression which will in turn compute the value. We call this -expression the @dfn{expansion} of the macro. - - Macros can do this because they operate on the unevaluated expressions -for the arguments, not on the argument values as functions do. They can -therefore construct an expansion containing these argument expressions -or parts of them. - - If you are using a macro to do something an ordinary function could -do, just for the sake of speed, consider using an inline function -instead. @xref{Inline Functions}. - -@menu -* 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. -@end menu - -@node Simple Macro -@section A Simple Example of a Macro - - Suppose we would like to define a Lisp construct to increment a -variable value, much like the @code{++} operator in C. We would like to -write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}. -Here's a macro definition that does the job: - -@findex inc -@example -@group -(defmacro inc (var) - (list 'setq var (list '1+ var))) -@end group -@end example - - When this is called with @code{(inc x)}, the argument @var{var} is the -symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would -be in a function. The body of the macro uses this to construct the -expansion, which is @code{(setq x (1+ x))}. Once the macro definition -returns this expansion, Lisp proceeds to evaluate it, thus incrementing -@code{x}. - -@node Expansion -@section Expansion of a Macro Call -@cindex expansion of macros -@cindex macro call - - A macro call looks just like a function call in that it is a list which -starts with the name of the macro. The rest of the elements of the list -are the arguments of the macro. - - Evaluation of the macro call begins like evaluation of a function call -except for one crucial difference: the macro arguments are the actual -expressions appearing in the macro call. They are not evaluated before -they are given to the macro definition. By contrast, the arguments of a -function are results of evaluating the elements of the function call -list. - - Having obtained the arguments, Lisp invokes the macro definition just -as a function is invoked. The argument variables of the macro are bound -to the argument values from the macro call, or to a list of them in the -case of a @code{&rest} argument. And the macro body executes and -returns its value just as a function body does. - - The second crucial difference between macros and functions is that the -value returned by the macro body is not the value of the macro call. -Instead, it is an alternate expression for computing that value, also -known as the @dfn{expansion} of the macro. The Lisp interpreter -proceeds to evaluate the expansion as soon as it comes back from the -macro. - - Since the expansion is evaluated in the normal manner, it may contain -calls to other macros. It may even be a call to the same macro, though -this is unusual. - - You can see the expansion of a given macro call by calling -@code{macroexpand}. - -@defun macroexpand form &optional environment -@cindex macro expansion -This function expands @var{form}, if it is a macro call. If the result -is another macro call, it is expanded in turn, until something which is -not a macro call results. That is the value returned by -@code{macroexpand}. If @var{form} is not a macro call to begin with, it -is returned as given. - -Note that @code{macroexpand} does not look at the subexpressions of -@var{form} (although some macro definitions may do so). Even if they -are macro calls themselves, @code{macroexpand} does not expand them. - -The function @code{macroexpand} does not expand calls to inline functions. -Normally there is no need for that, since a call to an inline function is -no harder to understand than a call to an ordinary function. - -If @var{environment} is provided, it specifies an alist of macro -definitions that shadow the currently defined macros. Byte compilation -uses this feature. - -@smallexample -@group -(defmacro inc (var) - (list 'setq var (list '1+ var))) - @result{} inc -@end group - -@group -(macroexpand '(inc r)) - @result{} (setq r (1+ r)) -@end group - -@group -(defmacro inc2 (var1 var2) - (list 'progn (list 'inc var1) (list 'inc var2))) - @result{} inc2 -@end group - -@group -(macroexpand '(inc2 r s)) - @result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.} -@end group -@end smallexample -@end defun - - -@defun macroexpand-all form &optional environment -@code{macroexpand-all} expands macros like @code{macroexpand}, but -will look for and expand all macros in @var{form}, not just at the -top-level. If no macros are expanded, the return value is @code{eq} -to @var{form}. - -Repeating the example used for @code{macroexpand} above with -@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does} -expand the embedded calls to @code{inc}: - -@smallexample -(macroexpand-all '(inc2 r s)) - @result{} (progn (setq r (1+ r)) (setq s (1+ s))) -@end smallexample - -@end defun - -@node Compiling Macros -@section Macros and Byte Compilation -@cindex byte-compiling macros - - You might ask why we take the trouble to compute an expansion for a -macro and then evaluate the expansion. Why not have the macro body -produce the desired results directly? The reason has to do with -compilation. - - When a macro call appears in a Lisp program being compiled, the Lisp -compiler calls the macro definition just as the interpreter would, and -receives an expansion. But instead of evaluating this expansion, it -compiles the expansion as if it had appeared directly in the program. -As a result, the compiled code produces the value and side effects -intended for the macro, but executes at full compiled speed. This would -not work if the macro body computed the value and side effects -itself---they would be computed at compile time, which is not useful. - - In order for compilation of macro calls to work, the macros must -already be defined in Lisp when the calls to them are compiled. The -compiler has a special feature to help you do this: if a file being -compiled contains a @code{defmacro} form, the macro is defined -temporarily for the rest of the compilation of that file. To make this -feature work, you must put the @code{defmacro} in the same file where it -is used, and before its first use. - - Byte-compiling a file executes any @code{require} calls at top-level -in the file. This is in case the file needs the required packages for -proper compilation. One way to ensure that necessary macro definitions -are available during compilation is to require the files that define -them (@pxref{Named Features}). To avoid loading the macro definition files -when someone @emph{runs} the compiled program, write -@code{eval-when-compile} around the @code{require} calls (@pxref{Eval -During Compile}). - -@node Defining Macros -@section Defining Macros - - A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should -be a function; expansion of the macro works by applying the function -(with @code{apply}) to the list of unevaluated argument-expressions -from the macro call. - - It is possible to use an anonymous Lisp macro just like an anonymous -function, but this is never done, because it does not make sense to pass -an anonymous macro to functionals such as @code{mapcar}. In practice, -all Lisp macros have names, and they are usually defined with the -special form @code{defmacro}. - -@defspec defmacro name argument-list body-forms@dots{} -@code{defmacro} defines the symbol @var{name} as a macro that looks -like this: - -@example -(macro lambda @var{argument-list} . @var{body-forms}) -@end example - -(Note that the @sc{cdr} of this list is a function---a lambda expression.) -This macro object is stored in the function cell of @var{name}. The -value returned by evaluating the @code{defmacro} form is @var{name}, but -usually we ignore this value. - -The shape and meaning of @var{argument-list} is the same as in a -function, and the keywords @code{&rest} and @code{&optional} may be used -(@pxref{Argument List}). Macros may have a documentation string, but -any @code{interactive} declaration is ignored since macros cannot be -called interactively. -@end defspec - - The body of the macro definition can include a @code{declare} form, -which can specify how @key{TAB} should indent macro calls, and how to -step through them for Edebug. - -@defmac declare @var{specs}@dots{} -@anchor{Definition of declare} -A @code{declare} form is used in a macro definition to specify various -additional information about it. Two kinds of specification are -currently supported: - -@table @code -@item (debug @var{edebug-form-spec}) -Specify how to step through macro calls for Edebug. -@xref{Instrumenting Macro Calls}. - -@item (indent @var{indent-spec}) -Specify how to indent calls to this macro. @xref{Indenting Macros}, -for more details. -@end table - -A @code{declare} form only has its special effect in the body of a -@code{defmacro} form if it immediately follows the documentation -string, if present, or the argument list otherwise. (Strictly -speaking, @emph{several} @code{declare} forms can follow the -documentation string or argument list, but since a @code{declare} form -can have several @var{specs}, they can always be combined into a -single form.) When used at other places in a @code{defmacro} form, or -outside a @code{defmacro} form, @code{declare} just returns @code{nil} -without evaluating any @var{specs}. -@end defmac - - No macro absolutely needs a @code{declare} form, because that form -has no effect on how the macro expands, on what the macro means in the -program. It only affects secondary features: indentation and Edebug. - -@node Backquote -@section Backquote -@cindex backquote (list substitution) -@cindex ` (list substitution) -@findex ` - - Macros often need to construct large list structures from a mixture of -constants and nonconstant parts. To make this easier, use the @samp{`} -syntax (usually called @dfn{backquote}). - - Backquote allows you to quote a list, but selectively evaluate -elements of that list. In the simplest case, it is identical to the -special form @code{quote} (@pxref{Quoting}). For example, these -two forms yield identical results: - -@example -@group -`(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@group -'(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@end example - -@findex , @r{(with backquote)} -The special marker @samp{,} inside of the argument to backquote -indicates a value that isn't constant. Backquote evaluates the -argument of @samp{,} and puts the value in the list structure: - -@example -@group -(list 'a 'list 'of (+ 2 3) 'elements) - @result{} (a list of 5 elements) -@end group -@group -`(a list of ,(+ 2 3) elements) - @result{} (a list of 5 elements) -@end group -@end example - - Substitution with @samp{,} is allowed at deeper levels of the list -structure also. For example: - -@example -@group -(defmacro t-becomes-nil (variable) - `(if (eq ,variable t) - (setq ,variable nil))) -@end group - -@group -(t-becomes-nil foo) - @equiv{} (if (eq foo t) (setq foo nil)) -@end group -@end example - -@findex ,@@ @r{(with backquote)} -@cindex splicing (with backquote) - You can also @dfn{splice} an evaluated value into the resulting list, -using the special marker @samp{,@@}. The elements of the spliced list -become elements at the same level as the other elements of the resulting -list. The equivalent code without using @samp{`} is often unreadable. -Here are some examples: - -@example -@group -(setq some-list '(2 3)) - @result{} (2 3) -@end group -@group -(cons 1 (append some-list '(4) some-list)) - @result{} (1 2 3 4 2 3) -@end group -@group -`(1 ,@@some-list 4 ,@@some-list) - @result{} (1 2 3 4 2 3) -@end group - -@group -(setq list '(hack foo bar)) - @result{} (hack foo bar) -@end group -@group -(cons 'use - (cons 'the - (cons 'words (append (cdr list) '(as elements))))) - @result{} (use the words foo bar as elements) -@end group -@group -`(use the words ,@@(cdr list) as elements) - @result{} (use the words foo bar as elements) -@end group -@end example - -In old Emacs versions, before version 19.29, @samp{`} used a different -syntax which required an extra level of parentheses around the entire -backquote construct. Likewise, each @samp{,} or @samp{,@@} substitution -required an extra level of parentheses surrounding both the @samp{,} or -@samp{,@@} and the following expression. The old syntax required -whitespace between the @samp{`}, @samp{,} or @samp{,@@} and the -following expression. - -This syntax is still accepted, for compatibility with old Emacs -versions, but support for it will soon disappear. - -@node Problems with Macros -@section Common Problems Using Macros - - The basic facts of macro expansion have counterintuitive consequences. -This section describes some important consequences that can lead to -trouble, and rules to follow to avoid trouble. - -@menu -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. -@end menu - -@node Wrong Time -@subsection Wrong Time - - The most common problem in writing macros is doing some of the -real work prematurely---while expanding the macro, rather than in the -expansion itself. For instance, one real package had this macro -definition: - -@example -(defmacro my-set-buffer-multibyte (arg) - (if (fboundp 'set-buffer-multibyte) - (set-buffer-multibyte arg))) -@end example - -With this erroneous macro definition, the program worked fine when -interpreted but failed when compiled. This macro definition called -@code{set-buffer-multibyte} during compilation, which was wrong, and -then did nothing when the compiled package was run. The definition -that the programmer really wanted was this: - -@example -(defmacro my-set-buffer-multibyte (arg) - (if (fboundp 'set-buffer-multibyte) - `(set-buffer-multibyte ,arg))) -@end example - -@noindent -This macro expands, if appropriate, into a call to -@code{set-buffer-multibyte} that will be executed when the compiled -program is actually run. - -@node Argument Evaluation -@subsection Evaluating Macro Arguments Repeatedly - - When defining a macro you must pay attention to the number of times -the arguments will be evaluated when the expansion is executed. The -following macro (used to facilitate iteration) illustrates the problem. -This macro allows us to write a simple ``for'' loop such as one might -find in Pascal. - -@findex for -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - (list 'let (list (list var init)) - (cons 'while (cons (list '<= var final) - (append body (list (list 'inc var))))))) -@end group -@result{} for - -@group -(for i from 1 to 3 do - (setq square (* i i)) - (princ (format "\n%d %d" i square))) -@expansion{} -@end group -@group -(let ((i 1)) - (while (<= i 3) - (setq square (* i i)) - (princ (format "\n%d %d" i square)) - (inc i))) -@end group -@group - - @print{}1 1 - @print{}2 4 - @print{}3 9 -@result{} nil -@end group -@end smallexample - -@noindent -The arguments @code{from}, @code{to}, and @code{do} in this macro are -``syntactic sugar''; they are entirely ignored. The idea is that you -will write noise words (such as @code{from}, @code{to}, and @code{do}) -in those positions in the macro call. - -Here's an equivalent definition simplified through use of backquote: - -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - `(let ((,var ,init)) - (while (<= ,var ,final) - ,@@body - (inc ,var)))) -@end group -@end smallexample - -Both forms of this definition (with backquote and without) suffer from -the defect that @var{final} is evaluated on every iteration. If -@var{final} is a constant, this is not a problem. If it is a more -complex form, say @code{(long-complex-calculation x)}, this can slow -down the execution significantly. If @var{final} has side effects, -executing it more than once is probably incorrect. - -@cindex macro argument evaluation -A well-designed macro definition takes steps to avoid this problem by -producing an expansion that evaluates the argument expressions exactly -once unless repeated evaluation is part of the intended purpose of the -macro. Here is a correct expansion for the @code{for} macro: - -@smallexample -@group -(let ((i 1) - (max 3)) - (while (<= i max) - (setq square (* i i)) - (princ (format "%d %d" i square)) - (inc i))) -@end group -@end smallexample - -Here is a macro definition that creates this expansion: - -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." - `(let ((,var ,init) - (max ,final)) - (while (<= ,var max) - ,@@body - (inc ,var)))) -@end group -@end smallexample - - Unfortunately, this fix introduces another problem, -described in the following section. - -@node Surprising Local Vars -@subsection Local Variables in Macro Expansions - -@ifnottex - In the previous section, the definition of @code{for} was fixed as -follows to make the expansion evaluate the macro arguments the proper -number of times: - -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." -@end group -@group - `(let ((,var ,init) - (max ,final)) - (while (<= ,var max) - ,@@body - (inc ,var)))) -@end group -@end smallexample -@end ifnottex - - The new definition of @code{for} has a new problem: it introduces a -local variable named @code{max} which the user does not expect. This -causes trouble in examples such as the following: - -@smallexample -@group -(let ((max 0)) - (for x from 0 to 10 do - (let ((this (frob x))) - (if (< max this) - (setq max this))))) -@end group -@end smallexample - -@noindent -The references to @code{max} inside the body of the @code{for}, which -are supposed to refer to the user's binding of @code{max}, really access -the binding made by @code{for}. - -The way to correct this is to use an uninterned symbol instead of -@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be -bound and referred to just like any other symbol, but since it is -created by @code{for}, we know that it cannot already appear in the -user's program. Since it is not interned, there is no way the user can -put it into the program later. It will never appear anywhere except -where put by @code{for}. Here is a definition of @code{for} that works -this way: - -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." - (let ((tempvar (make-symbol "max"))) - `(let ((,var ,init) - (,tempvar ,final)) - (while (<= ,var ,tempvar) - ,@@body - (inc ,var))))) -@end group -@end smallexample - -@noindent -This creates an uninterned symbol named @code{max} and puts it in the -expansion instead of the usual interned symbol @code{max} that appears -in expressions ordinarily. - -@node Eval During Expansion -@subsection Evaluating Macro Arguments in Expansion - - Another problem can happen if the macro definition itself -evaluates any of the macro argument expressions, such as by calling -@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the -user's variables, you may have trouble if the user happens to use a -variable with the same name as one of the macro arguments. Inside the -macro body, the macro argument binding is the most local binding of this -variable, so any references inside the form being evaluated do refer to -it. Here is an example: - -@example -@group -(defmacro foo (a) - (list 'setq (eval a) t)) - @result{} foo -@end group -@group -(setq x 'b) -(foo x) @expansion{} (setq b t) - @result{} t ; @r{and @code{b} has been set.} -;; @r{but} -(setq a 'c) -(foo a) @expansion{} (setq a t) - @result{} t ; @r{but this set @code{a}, not @code{c}.} - -@end group -@end example - - It makes a difference whether the user's variable is named @code{a} or -@code{x}, because @code{a} conflicts with the macro argument variable -@code{a}. - - Another problem with calling @code{eval} in a macro definition is that -it probably won't do what you intend in a compiled program. The -byte-compiler runs macro definitions while compiling the program, when -the program's own computations (which you might have wished to access -with @code{eval}) don't occur and its local variable bindings don't -exist. - - To avoid these problems, @strong{don't evaluate an argument expression -while computing the macro expansion}. Instead, substitute the -expression into the macro expansion, so that its value will be computed -as part of executing the expansion. This is how the other examples in -this chapter work. - -@node Repeated Expansion -@subsection How Many Times is the Macro Expanded? - - Occasionally problems result from the fact that a macro call is -expanded each time it is evaluated in an interpreted function, but is -expanded only once (during compilation) for a compiled function. If the -macro definition has side effects, they will work differently depending -on how many times the macro is expanded. - - Therefore, you should avoid side effects in computation of the -macro expansion, unless you really know what you are doing. - - One special kind of side effect can't be avoided: constructing Lisp -objects. Almost all macro expansions include constructed lists; that is -the whole point of most macros. This is usually safe; there is just one -case where you must be careful: when the object you construct is part of a -quoted constant in the macro expansion. - - If the macro is expanded just once, in compilation, then the object is -constructed just once, during compilation. But in interpreted -execution, the macro is expanded each time the macro call runs, and this -means a new object is constructed each time. - - In most clean Lisp code, this difference won't matter. It can matter -only if you perform side-effects on the objects constructed by the macro -definition. Thus, to avoid trouble, @strong{avoid side effects on -objects constructed by macro definitions}. Here is an example of how -such side effects can get you into trouble: - -@lisp -@group -(defmacro empty-object () - (list 'quote (cons nil nil))) -@end group - -@group -(defun initialize (condition) - (let ((object (empty-object))) - (if condition - (setcar object condition)) - object)) -@end group -@end lisp - -@noindent -If @code{initialize} is interpreted, a new list @code{(nil)} is -constructed each time @code{initialize} is called. Thus, no side effect -survives between calls. If @code{initialize} is compiled, then the -macro @code{empty-object} is expanded during compilation, producing a -single ``constant'' @code{(nil)} that is reused and altered each time -@code{initialize} is called. - -One way to avoid pathological cases like this is to think of -@code{empty-object} as a funny kind of constant, not as a memory -allocation construct. You wouldn't use @code{setcar} on a constant such -as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)} -either. - -@node Indenting Macros -@section Indenting Macros - - You can use the @code{declare} form in the macro definition to -specify how to @key{TAB} should indent indent calls to the macro. You -write it like this: - -@example -(declare (indent @var{indent-spec})) -@end example - -@noindent -Here are the possibilities for @var{indent-spec}: - -@table @asis -@item @code{nil} -This is the same as no property---use the standard indentation pattern. -@item @code{defun} -Handle this function like a @samp{def} construct: treat the second -line as the start of a @dfn{body}. -@item an integer, @var{number} -The first @var{number} arguments of the function are -@dfn{distinguished} arguments; the rest are considered the body -of the expression. A line in the expression is indented according to -whether the first argument on it is distinguished or not. If the -argument is part of the body, the line is indented @code{lisp-body-indent} -more columns than the open-parenthesis starting the containing -expression. If the argument is distinguished and is either the first -or second argument, it is indented @emph{twice} that many extra columns. -If the argument is distinguished and not the first or second argument, -the line uses the standard pattern. -@item a symbol, @var{symbol} -@var{symbol} should be a function name; that function is called to -calculate the indentation of a line within this expression. The -function receives two arguments: -@table @asis -@item @var{state} -The value returned by @code{parse-partial-sexp} (a Lisp primitive for -indentation and nesting computation) when it parses up to the -beginning of this line. -@item @var{pos} -The position at which the line being indented begins. -@end table -@noindent -It should return either a number, which is the number of columns of -indentation for that line, or a list whose car is such a number. The -difference between returning a number and returning a list is that a -number says that all following lines at the same nesting level should -be indented just like this one; a list says that following lines might -call for different indentations. This makes a difference when the -indentation is being computed by @kbd{C-M-q}; if the value is a -number, @kbd{C-M-q} need not recalculate indentation for the following -lines until the end of the list. -@end table - -@ignore - arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b -@end ignore diff --git a/lispref/makefile.w32-in b/lispref/makefile.w32-in deleted file mode 100644 index 7e35339d17f..00000000000 --- a/lispref/makefile.w32-in +++ /dev/null @@ -1,123 +0,0 @@ -# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual. - -# Copyright (C) 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 3, or (at your option) -# any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs; see the file COPYING. If not, write to -# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -# Boston, MA 02110-1301, USA. - -# Standard configure variables. -srcdir = . - -infodir = $(srcdir)/../info -usermanualdir = $(srcdir)/../man - -# Redefine `TEX' if `tex' does not invoke plain TeX. For example: -# TEX=platex -TEX=tex -INSTALL_INFO = install-info -MAKEINFO = makeinfo --force - -# The environment variable and its value to add $(srcdir) to the path -# searched for TeX input files. -texinputdir = $(srcdir)\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" /C - -# The name of the manual: -VERSION=2.9 -manual = elisp-manual-21-$(VERSION) - -# List of all the texinfo files in the manual: - -srcs = \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/back.texi \ - $(srcdir)/backups.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/compile.texi \ - $(srcdir)/control.texi \ - $(srcdir)/customize.texi \ - $(srcdir)/debugging.texi \ - $(srcdir)/display.texi \ - $(srcdir)/edebug.texi \ - $(srcdir)/elisp.texi \ - $(srcdir)/errors.texi \ - $(srcdir)/eval.texi \ - $(srcdir)/files.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/functions.texi \ - $(srcdir)/hash.texi \ - $(srcdir)/help.texi \ - $(srcdir)/hooks.texi \ - $(srcdir)/internals.texi \ - $(srcdir)/intro.texi \ - $(srcdir)/keymaps.texi \ - $(srcdir)/lists.texi \ - $(srcdir)/loading.texi \ - $(srcdir)/locals.texi \ - $(srcdir)/macros.texi \ - $(srcdir)/maps.texi \ - $(srcdir)/markers.texi \ - $(srcdir)/minibuf.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/nonascii.texi \ - $(srcdir)/numbers.texi \ - $(srcdir)/objects.texi \ - $(srcdir)/os.texi \ - $(srcdir)/positions.texi \ - $(srcdir)/processes.texi \ - $(srcdir)/searching.texi \ - $(srcdir)/sequences.texi \ - $(srcdir)/streams.texi \ - $(srcdir)/strings.texi \ - $(srcdir)/symbols.texi \ - $(srcdir)/syntax.texi \ - $(srcdir)/text.texi \ - $(srcdir)/tips.texi \ - $(srcdir)/variables.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/index.texi \ - $(srcdir)/gpl.texi \ - $(srcdir)/doclicense.texi - - -.PHONY: clean - -# The info file is named `elisp'. - -info: $(infodir)/elisp - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp - -$(infodir)/elisp: $(srcs) - $(MAKEINFO) -I. -I$(srcdir) -o $(infodir)/elisp $(srcdir)/elisp.texi - -elisp.dvi: $(srcs) - $(texinputdir) $(TEX) -I $(usermanualdir) $(srcdir)/elisp.texi - -clean: - - $(DEL) *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ - *.vr *.vrs *.pg *.pgs *.ky *.kys - - $(DEL) make.out core - - $(DEL) $(infodir)/elisp* - -distclean: clean - -maintainer-clean: distclean - - $(DEL) elisp elisp-? elisp-?? elisp.dvi elisp.oaux diff --git a/lispref/maps.texi b/lispref/maps.texi deleted file mode 100644 index 724091970c3..00000000000 --- a/lispref/maps.texi +++ /dev/null @@ -1,230 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 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 -@cindex standard keymaps - -The following symbols are used as the names for various keymaps. -Some of these exist when Emacs is first started, others are -loaded only when their respective mode is used. This is not -an exhaustive list. - -Several keymaps are used in the minibuffer. @xref{Completion Commands}. - -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 apropos-mode-map -@vindex apropos-mode-map -A sparse keymap for @code{apropos} buffers. - -@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 by C mode. - -@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-5-map -A sparse keymap for subcommands of the prefix @kbd{C-x 5}. - -@item ctl-x-map -A full keymap for @kbd{C-x} commands. - -@item custom-mode-map -A full keymap for Custom mode. - -@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 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 by Emacs Lisp mode. - -@item esc-map -A full keymap for @kbd{ESC} (or @kbd{Meta}) commands. - -@item facemenu-menu -@vindex facemenu-menu -The sparse keymap that displays the Text Properties menu. - -@item facemenu-background-menu -@vindex facemenu-background-menu -The sparse keymap that displays the Background Color submenu of the Text -Properties menu. - -@item facemenu-face-menu -@vindex facemenu-face-menu -The sparse keymap that displays the Face submenu of the Text Properties menu. - -@item facemenu-foreground-menu -@vindex facemenu-foreground-menu -The sparse keymap that displays the Foreground Color submenu of the Text -Properties menu. - -@item facemenu-indentation-menu -@vindex facemenu-indentation-menu -The sparse keymap that displays the Indentation submenu of the Text -Properties menu. - -@item facemenu-justification-menu -@vindex facemenu-justification-menu -The sparse keymap that displays the Justification submenu of the Text -Properties menu. - -@item facemenu-special-menu -@vindex facemenu-special-menu -The sparse keymap that displays the Special Props submenu of the Text -Properties menu. - -@item function-key-map -The keymap for translating keypad and function keys.@* -If there are none, then it contains an empty sparse keymap. -@xref{Translation Keymaps}. - -@item fundamental-mode-map -@vindex fundamental-mode-map -The sparse keymap for Fundamental mode.@* -It is empty and should not be changed. - -@item global-map -The full keymap containing default global key bindings.@* -Modes should not modify the Global map. - -@item grep-mode-map -@vindex grep-mode-map -The keymap for @code{grep-mode} buffers. - -@item help-map -The sparse keymap for the keys that follow the help character @kbd{C-h}. - -@item help-mode-map -@vindex help-mode-map -The sparse keymap for Help mode. - -@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 -@vindex isearch-mode-map -A keymap that defines the characters you can type within incremental -search. - -@item key-translation-map -A keymap for translating keys. This one overrides ordinary key -bindings, unlike @code{function-key-map}. @xref{Translation Keymaps}. - -@item kmacro-map -@vindex kmacro-map -A sparse keymap for keys that follows the @kbd{C-x C-k} prefix -search. - -@item lisp-interaction-mode-map -@vindex lisp-interaction-mode-map -A sparse keymap used by Lisp Interaction mode. - -@item lisp-mode-map -@vindex lisp-mode-map -A sparse keymap used by Lisp mode. - -@item menu-bar-edit-menu -@vindex menu-bar-edit-menu -The keymap which displays the Edit menu in the menu bar. - -@item menu-bar-files-menu -@vindex menu-bar-files-menu -The keymap which displays the Files menu in the menu bar. - -@item menu-bar-help-menu -@vindex menu-bar-help-menu -The keymap which displays the Help menu in the menu bar. - -@item menu-bar-mule-menu -@vindex menu-bar-mule-menu -The keymap which displays the Mule menu in the menu bar. - -@item menu-bar-search-menu -@vindex menu-bar-search-menu -The keymap which displays the Search menu in the menu bar. - -@item menu-bar-tools-menu -@vindex menu-bar-tools-menu -The keymap which displays the Tools menu in the menu bar. - -@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 sparse keymap used by Occur mode. - -@item query-replace-map -A sparse 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 tool-bar-map -The keymap defining the contents of the tool bar. - -@item view-mode-map -@vindex view-mode-map -A full keymap used by View mode. -@end table - -@ignore - arch-tag: b741253c-7e23-4a02-b3fa-cffd9e4d72b9 -@end ignore diff --git a/lispref/markers.texi b/lispref/markers.texi deleted file mode 100644 index 519b8a1316a..00000000000 --- a/lispref/markers.texi +++ /dev/null @@ -1,664 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/markers -@node Markers, Text, Positions, Top -@chapter Markers -@cindex markers - - A @dfn{marker} is a Lisp object used to specify a position in a buffer -relative to the surrounding text. A marker changes its offset from the -beginning of the buffer automatically whenever text is inserted or -deleted, so that it stays with the two characters on either side of it. - -@menu -* 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". -@end menu - -@node Overview of Markers -@section Overview of Markers - - A marker specifies a buffer and a position in that buffer. The -marker can be used to represent a position in the functions that -require one, just as an integer could be used. In that case, the -marker's buffer is normally ignored. Of course, a marker used in this -way usually points to a position in the buffer that the function -operates on, but that is entirely the programmer's responsibility. -@xref{Positions}, for a complete description of positions. - - A marker has three attributes: the marker position, the marker -buffer, and the insertion type. The marker position is an integer -that is equivalent (at a given time) to the marker as a position in -that buffer. But the marker's position value can change often during -the life of the marker. Insertion and deletion of text in the buffer -relocate the marker. The idea is that a marker positioned between two -characters remains between those two characters despite insertion and -deletion elsewhere in the buffer. Relocation changes the integer -equivalent of the marker. - -@cindex marker relocation - Deleting text around a marker's position leaves the marker between the -characters immediately before and after the deleted text. Inserting -text at the position of a marker normally leaves the marker either in -front of or after the new text, depending on the marker's @dfn{insertion -type} (@pxref{Marker Insertion Types})---unless the insertion is done -with @code{insert-before-markers} (@pxref{Insertion}). - -@cindex marker garbage collection - Insertion and deletion in a buffer must check all the markers and -relocate them if necessary. This slows processing in a buffer with a -large number of markers. For this reason, it is a good idea to make a -marker point nowhere if you are sure you don't need it any more. -Unreferenced markers are garbage collected eventually, but until then -will continue to use time if they do point somewhere. - -@cindex markers as numbers - Because it is common to perform arithmetic operations on a marker -position, most of the arithmetic operations (including @code{+} and -@code{-}) accept markers as arguments. In such cases, the marker -stands for its current position. - -Here are examples of creating markers, setting markers, and moving point -to markers: - -@example -@group -;; @r{Make a new marker that initially does not point anywhere:} -(setq m1 (make-marker)) - @result{} #<marker in no buffer> -@end group - -@group -;; @r{Set @code{m1} to point between the 99th and 100th characters} -;; @r{in the current buffer:} -(set-marker m1 100) - @result{} #<marker at 100 in markers.texi> -@end group - -@group -;; @r{Now insert one character at the beginning of the buffer:} -(goto-char (point-min)) - @result{} 1 -(insert "Q") - @result{} nil -@end group - -@group -;; @r{@code{m1} is updated appropriately.} -m1 - @result{} #<marker at 101 in markers.texi> -@end group - -@group -;; @r{Two markers that point to the same position} -;; @r{are not @code{eq}, but they are @code{equal}.} -(setq m2 (copy-marker m1)) - @result{} #<marker at 101 in markers.texi> -(eq m1 m2) - @result{} nil -(equal m1 m2) - @result{} t -@end group - -@group -;; @r{When you are finished using a marker, make it point nowhere.} -(set-marker m1 nil) - @result{} #<marker in no buffer> -@end group -@end example - -@node Predicates on Markers -@section Predicates on Markers - - You can test an object to see whether it is a marker, or whether it is -either an integer or a marker. The latter test is useful in connection -with the arithmetic functions that work with both markers and integers. - -@defun markerp object -This function returns @code{t} if @var{object} is a marker, @code{nil} -otherwise. Note that integers are not markers, even though many -functions will accept either a marker or an integer. -@end defun - -@defun integer-or-marker-p object -This function returns @code{t} if @var{object} is an integer or a marker, -@code{nil} otherwise. -@end defun - -@defun number-or-marker-p object -This function returns @code{t} if @var{object} is a number (either -integer or floating point) or a marker, @code{nil} otherwise. -@end defun - -@node Creating Markers -@section Functions that Create Markers - - When you create a new marker, you can make it point nowhere, or point -to the present position of point, or to the beginning or end of the -accessible portion of the buffer, or to the same place as another given -marker. - -The next four functions all return markers with insertion type -@code{nil}. @xref{Marker Insertion Types}. - -@defun make-marker -This function returns a newly created marker that does not point -anywhere. - -@example -@group -(make-marker) - @result{} #<marker in no buffer> -@end group -@end example -@end defun - -@defun point-marker -This function returns a new marker that points to the present position -of point in the current buffer. @xref{Point}. For an example, see -@code{copy-marker}, below. -@end defun - -@defun point-min-marker -This function returns a new marker that points to the beginning of the -accessible portion of the buffer. This will be the beginning of the -buffer unless narrowing is in effect. @xref{Narrowing}. -@end defun - -@defun point-max-marker -This function returns a new marker that points to the end of the -accessible portion of the buffer. This will be the end of the buffer -unless narrowing is in effect. @xref{Narrowing}. - -Here are examples of this function and @code{point-min-marker}, shown in -a buffer containing a version of the source file for the text of this -chapter. - -@example -@group -(point-min-marker) - @result{} #<marker at 1 in markers.texi> -(point-max-marker) - @result{} #<marker at 15573 in markers.texi> -@end group - -@group -(narrow-to-region 100 200) - @result{} nil -@end group -@group -(point-min-marker) - @result{} #<marker at 100 in markers.texi> -@end group -@group -(point-max-marker) - @result{} #<marker at 200 in markers.texi> -@end group -@end example -@end defun - -@defun copy-marker marker-or-integer &optional insertion-type -If passed a marker as its argument, @code{copy-marker} returns a -new marker that points to the same place and the same buffer as does -@var{marker-or-integer}. If passed an integer as its argument, -@code{copy-marker} returns a new marker that points to position -@var{marker-or-integer} in the current buffer. - -The new marker's insertion type is specified by the argument -@var{insertion-type}. @xref{Marker Insertion Types}. - -If passed an integer argument less than 1, @code{copy-marker} returns a -new marker that points to the beginning of the current buffer. If -passed an integer argument greater than the length of the buffer, -@code{copy-marker} returns a new marker that points to the end of the -buffer. - -@example -@group -(copy-marker 0) - @result{} #<marker at 1 in markers.texi> -@end group - -@group -(copy-marker 20000) - @result{} #<marker at 7572 in markers.texi> -@end group -@end example - -An error is signaled if @var{marker} is neither a marker nor an -integer. -@end defun - - Two distinct markers are considered @code{equal} (even though not -@code{eq}) to each other if they have the same position and buffer, or -if they both point nowhere. - -@example -@group -(setq p (point-marker)) - @result{} #<marker at 2139 in markers.texi> -@end group - -@group -(setq q (copy-marker p)) - @result{} #<marker at 2139 in markers.texi> -@end group - -@group -(eq p q) - @result{} nil -@end group - -@group -(equal p q) - @result{} t -@end group -@end example - -@node Information from Markers -@section Information from Markers - - This section describes the functions for accessing the components of a -marker object. - -@defun marker-position marker -This function returns the position that @var{marker} points to, or -@code{nil} if it points nowhere. -@end defun - -@defun marker-buffer marker -This function returns the buffer that @var{marker} points into, or -@code{nil} if it points nowhere. - -@example -@group -(setq m (make-marker)) - @result{} #<marker in no buffer> -@end group -@group -(marker-position m) - @result{} nil -@end group -@group -(marker-buffer m) - @result{} nil -@end group - -@group -(set-marker m 3770 (current-buffer)) - @result{} #<marker at 3770 in markers.texi> -@end group -@group -(marker-buffer m) - @result{} #<buffer markers.texi> -@end group -@group -(marker-position m) - @result{} 3770 -@end group -@end example -@end defun - -@defun buffer-has-markers-at position -This function returns @code{t} if one or more markers -point at position @var{position} in the current buffer. -@end defun - -@node Marker Insertion Types -@section Marker Insertion Types - -@cindex insertion type of a marker - When you insert text directly at the place where a marker points, -there are two possible ways to relocate that marker: it can point before -the inserted text, or point after it. You can specify which one a given -marker should do by setting its @dfn{insertion type}. Note that use of -@code{insert-before-markers} ignores markers' insertion types, always -relocating a marker to point after the inserted text. - -@defun set-marker-insertion-type marker type -This function sets the insertion type of marker @var{marker} to -@var{type}. If @var{type} is @code{t}, @var{marker} will advance when -text is inserted at its position. If @var{type} is @code{nil}, -@var{marker} does not advance when text is inserted there. -@end defun - -@defun marker-insertion-type marker -This function reports the current insertion type of @var{marker}. -@end defun - -Most functions that create markers, without an argument allowing to -specify the insertion type, create them with insertion type -@code{nil}. Also, the mark has, by default, insertion type -@code{nil}. - -@node Moving Markers -@section Moving Marker Positions - - This section describes how to change the position of an existing -marker. When you do this, be sure you know whether the marker is used -outside of your program, and, if so, what effects will result from -moving it---otherwise, confusing things may happen in other parts of -Emacs. - -@defun set-marker marker position &optional buffer -This function moves @var{marker} to @var{position} -in @var{buffer}. If @var{buffer} is not provided, it defaults to -the current buffer. - -If @var{position} is less than 1, @code{set-marker} moves @var{marker} -to the beginning of the buffer. If @var{position} is greater than the -size of the buffer, @code{set-marker} moves marker to the end of the -buffer. If @var{position} is @code{nil} or a marker that points -nowhere, then @var{marker} is set to point nowhere. - -The value returned is @var{marker}. - -@example -@group -(setq m (point-marker)) - @result{} #<marker at 4714 in markers.texi> -@end group -@group -(set-marker m 55) - @result{} #<marker at 55 in markers.texi> -@end group -@group -(setq b (get-buffer "foo")) - @result{} #<buffer foo> -@end group -@group -(set-marker m 0 b) - @result{} #<marker at 1 in foo> -@end group -@end example -@end defun - -@defun move-marker marker position &optional buffer -This is another name for @code{set-marker}. -@end defun - -@node The Mark -@section The Mark -@cindex mark, the -@cindex mark ring - - One special marker in each buffer is designated @dfn{the mark}. It -specifies a position to bound a range of text for commands such as -@code{kill-region} and @code{indent-rigidly}. Lisp programs should -set the mark only to values that have a potential use to the user, and -never for their own internal purposes. For example, the -@code{replace-regexp} command sets the mark to the value of point -before doing any replacements, because this enables the user to move -back there conveniently after the replace is finished. - - Many commands are designed to operate on the text between point and -the mark when called interactively. If you are writing such a -command, don't examine the mark directly; instead, use -@code{interactive} with the @samp{r} specification. This provides the -values of point and the mark as arguments to the command in an -interactive call, but permits other Lisp programs to specify arguments -explicitly. @xref{Interactive Codes}. - - Each buffer has a marker which represents the value of the mark in -that buffer, independent of any other buffer. When a buffer is newly -created, this marker exists but does not point anywhere. That means -the mark ``doesn't exist'' in that buffer as yet. - - Once the mark ``exists'' in a buffer, it normally never ceases to -exist. However, it may become @dfn{inactive}, if Transient Mark mode is -enabled. The variable @code{mark-active}, which is always buffer-local -in all buffers, indicates whether the mark is active: non-@code{nil} -means yes. A command can request deactivation of the mark upon return -to the editor command loop by setting @code{deactivate-mark} to a -non-@code{nil} value (but this causes deactivation only if Transient -Mark mode is enabled). - - The main motivation for using Transient Mark mode is that this mode -also enables highlighting of the region when the mark is active. -@xref{Display}. - - In addition to the mark, each buffer has a @dfn{mark ring} which is a -list of markers containing previous values of the mark. When editing -commands change the mark, they should normally save the old value of the -mark on the mark ring. The variable @code{mark-ring-max} specifies the -maximum number of entries in the mark ring; once the list becomes this -long, adding a new element deletes the last element. - - There is also a separate global mark ring, but that is used only in a -few particular user-level commands, and is not relevant to Lisp -programming. So we do not describe it here. - -@defun mark &optional force -@cindex current buffer mark -This function returns the current buffer's mark position as an integer, -or @code{nil} if no mark has ever been set in this buffer. - -If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is -@code{nil}, @code{mark} signals an error if the mark is inactive. -However, if @var{force} is non-@code{nil}, then @code{mark} disregards -inactivity of the mark, and returns the mark position anyway (or -@code{nil}). -@end defun - -@defun mark-marker -This function returns the marker that represents the current buffer's -mark. It is not a copy, it is the marker used internally. Therefore, -changing this marker's position will directly affect the buffer's -mark. Don't do that unless that is the effect you want. - -@example -@group -(setq m (mark-marker)) - @result{} #<marker at 3420 in markers.texi> -@end group -@group -(set-marker m 100) - @result{} #<marker at 100 in markers.texi> -@end group -@group -(mark-marker) - @result{} #<marker at 100 in markers.texi> -@end group -@end example - -Like any marker, this marker can be set to point at any buffer you -like. If you make it point at any buffer other than the one of which -it is the mark, it will yield perfectly consistent, but rather odd, -results. We recommend that you not do it! -@end defun - -@ignore -@deffn Command set-mark-command jump -If @var{jump} is @code{nil}, this command sets the mark to the value -of point and pushes the previous value of the mark on the mark ring. The -message @samp{Mark set} is also displayed in the echo area. - -If @var{jump} is not @code{nil}, this command sets point to the value -of the mark, and sets the mark to the previous saved mark value, which -is popped off the mark ring. - -This function is @emph{only} intended for interactive use. -@end deffn -@end ignore - -@defun set-mark position -This function sets the mark to @var{position}, and activates the mark. -The old value of the mark is @emph{not} pushed onto the mark ring. - -@strong{Please note:} Use this function only if you want the user to -see that the mark has moved, and you want the previous mark position to -be lost. Normally, when a new mark is set, the old one should go on the -@code{mark-ring}. For this reason, most applications should use -@code{push-mark} and @code{pop-mark}, not @code{set-mark}. - -Novice Emacs Lisp programmers often try to use the mark for the wrong -purposes. The mark saves a location for the user's convenience. An -editing command should not alter the mark unless altering the mark is -part of the user-level functionality of the command. (And, in that -case, this effect should be documented.) To remember a location for -internal use in the Lisp program, store it in a Lisp variable. For -example: - -@example -@group -(let ((beg (point))) - (forward-line 1) - (delete-region beg (point))). -@end group -@end example -@end defun - -@c for interactive use only -@ignore -@deffn Command exchange-point-and-mark -This function exchanges the positions of point and the mark. -It is intended for interactive use. -@end deffn -@end ignore - -@defun push-mark &optional position nomsg activate -This function sets the current buffer's mark to @var{position}, and -pushes a copy of the previous mark onto @code{mark-ring}. If -@var{position} is @code{nil}, then the value of point is used. -@code{push-mark} returns @code{nil}. - -The function @code{push-mark} normally @emph{does not} activate the -mark. To do that, specify @code{t} for the argument @var{activate}. - -A @samp{Mark set} message is displayed unless @var{nomsg} is -non-@code{nil}. -@end defun - -@defun pop-mark -This function pops off the top element of @code{mark-ring} and makes -that mark become the buffer's actual mark. This does not move point in -the buffer, and it does nothing if @code{mark-ring} is empty. It -deactivates the mark. - -The return value is not meaningful. -@end defun - -@defopt transient-mark-mode -@c @cindex Transient Mark mode Redundant -This variable if non-@code{nil} enables Transient Mark mode, in which -every buffer-modifying primitive sets @code{deactivate-mark}. The -consequence of this is that commands that modify the buffer normally -make the mark inactive. - -Lisp programs can set @code{transient-mark-mode} to @code{only} to -enable Transient Mark mode for the following command only. During -that following command, the value of @code{transient-mark-mode} is -@code{identity}. If it is still @code{identity} at the end of the -command, it changes to @code{nil}. -@end defopt - -@defopt mark-even-if-inactive -If this is non-@code{nil}, Lisp programs and the Emacs user can use the -mark even when it is inactive. This option affects the behavior of -Transient Mark mode. When the option is non-@code{nil}, deactivation of -the mark turns off region highlighting, but commands that use the mark -behave as if the mark were still active. -@end defopt - -@defvar deactivate-mark -If an editor command sets this variable non-@code{nil}, then the editor -command loop deactivates the mark after the command returns (if -Transient Mark mode is enabled). All the primitives that change the -buffer set @code{deactivate-mark}, to deactivate the mark when the -command is finished. - -To write Lisp code that modifies the buffer without causing -deactivation of the mark at the end of the command, bind -@code{deactivate-mark} to @code{nil} around the code that does the -modification. For example: - -@example -(let (deactivate-mark) - (insert " ")) -@end example -@end defvar - -@defun deactivate-mark -This function deactivates the mark, if Transient Mark mode is enabled. -Otherwise it does nothing. -@end defun - -@defvar mark-active -The mark is active when this variable is non-@code{nil}. This variable -is always buffer-local in each buffer. -@end defvar - -@defvar activate-mark-hook -@defvarx deactivate-mark-hook -These normal hooks are run, respectively, when the mark becomes active -and when it becomes inactive. The hook @code{activate-mark-hook} is -also run at the end of a command if the mark is active and it is -possible that the region may have changed. -@end defvar - -@defvar mark-ring -The value of this buffer-local variable is the list of saved former -marks of the current buffer, most recent first. - -@example -@group -mark-ring -@result{} (#<marker at 11050 in markers.texi> - #<marker at 10832 in markers.texi> - @dots{}) -@end group -@end example -@end defvar - -@defopt mark-ring-max -The value of this variable is the maximum size of @code{mark-ring}. If -more marks than this are pushed onto the @code{mark-ring}, -@code{push-mark} discards an old mark when it adds a new one. -@end defopt - -@node The Region -@section The Region -@cindex region (between point and mark) - - The text between point and the mark is known as @dfn{the region}. -Various functions operate on text delimited by point and the mark, but -only those functions specifically related to the region itself are -described here. - -The next two functions signal an error if the mark does not point -anywhere. If Transient Mark mode is enabled and -@code{mark-even-if-inactive} is @code{nil}, they also signal an error -if the mark is inactive. - -@defun region-beginning -This function returns the position of the beginning of the region (as -an integer). This is the position of either point or the mark, -whichever is smaller. -@end defun - -@defun region-end -This function returns the position of the end of the region (as an -integer). This is the position of either point or the mark, whichever is -larger. -@end defun - - Few programs need to use the @code{region-beginning} and -@code{region-end} functions. A command designed to operate on a region -should normally use @code{interactive} with the @samp{r} specification -to find the beginning and end of the region. This lets other Lisp -programs specify the bounds explicitly as arguments. (@xref{Interactive -Codes}.) - -@ignore - arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299 -@end ignore diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi deleted file mode 100644 index 98901df87f8..00000000000 --- a/lispref/minibuf.texi +++ /dev/null @@ -1,1964 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/minibuf -@node Minibuffers, Command Loop, Read and Print, Top -@chapter Minibuffers -@cindex arguments, reading -@cindex complex arguments -@cindex minibuffer - - A @dfn{minibuffer} is a special buffer that Emacs commands use to -read arguments more complicated than the single numeric prefix -argument. These arguments include file names, buffer names, and -command names (as in @kbd{M-x}). The minibuffer is displayed on the -bottom line of the frame, in the same place as the echo area -(@pxref{The Echo Area}), but only while it is in use for reading an -argument. - -@menu -* 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. -@end menu - -@node Intro to Minibuffers -@section Introduction to Minibuffers - - In most ways, a minibuffer is a normal Emacs buffer. Most operations -@emph{within} a buffer, such as editing commands, work normally in a -minibuffer. However, many operations for managing buffers do not apply -to minibuffers. The name of a minibuffer always has the form @w{@samp{ -*Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are -displayed only in special windows used only for minibuffers; these -windows always appear at the bottom of a frame. (Sometimes frames have -no minibuffer window, and sometimes a special kind of frame contains -nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) - - The text in the minibuffer always starts with the @dfn{prompt string}, -the text that was specified by the program that is using the minibuffer -to tell the user what sort of input to type. This text is marked -read-only so you won't accidentally delete or change it. It is also -marked as a field (@pxref{Fields}), so that certain motion functions, -including @code{beginning-of-line}, @code{forward-word}, -@code{forward-sentence}, and @code{forward-paragraph}, stop at the -boundary between the prompt and the actual text. (In older Emacs -versions, the prompt was displayed using a special mechanism and was not -part of the buffer contents.) - - The minibuffer's window is normally a single line; it grows -automatically if necessary if the contents require more space. You can -explicitly resize it temporarily with the window sizing commands; it -reverts to its normal size when the minibuffer is exited. You can -resize it permanently by using the window sizing commands in the frame's -other window, when the minibuffer is not active. If the frame contains -just a minibuffer, you can change the minibuffer's size by changing the -frame's size. - - Use of the minibuffer reads input events, and that alters the values -of variables such as @code{this-command} and @code{last-command} -(@pxref{Command Loop Info}). Your program should bind them around the -code that uses the minibuffer, if you do not want that to change them. - - If a command uses a minibuffer while there is an active minibuffer, -this is called a @dfn{recursive minibuffer}. The first minibuffer is -named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by -incrementing the number at the end of the name. (The names begin with a -space so that they won't show up in normal buffer lists.) Of several -recursive minibuffers, the innermost (or most recently entered) is the -active minibuffer. We usually call this ``the'' minibuffer. You can -permit or forbid recursive minibuffers by setting the variable -@code{enable-recursive-minibuffers} or by putting properties of that -name on command symbols (@pxref{Recursive Mini}). - - Like other buffers, a minibuffer uses a local keymap -(@pxref{Keymaps}) to specify special key bindings. The function that -invokes the minibuffer also sets up its local map according to the job -to be done. @xref{Text from Minibuffer}, for the non-completion -minibuffer local maps. @xref{Completion Commands}, for the minibuffer -local maps for completion. - - When Emacs is running in batch mode, any request to read from the -minibuffer actually reads a line from the standard input descriptor that -was supplied when Emacs was started. - -@node Text from Minibuffer -@section Reading Text Strings with the Minibuffer - - Most often, the minibuffer is used to read text as a string. It can -also be used to read a Lisp object in textual form. The most basic -primitive for minibuffer input is @code{read-from-minibuffer}; it can do -either one. There are also specialized commands for reading -commands, variables, file names, etc. (@pxref{Completion}). - - In most cases, you should not call minibuffer input functions in the -middle of a Lisp function. Instead, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} -specification. @xref{Defining Commands}. - -@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method -This function is the most general way to get input through the -minibuffer. By default, it accepts arbitrary text and returns it as a -string; however, if @var{read} is non-@code{nil}, then it uses -@code{read} to convert the text into a Lisp object (@pxref{Input -Functions}). - -The first thing this function does is to activate a minibuffer and -display it with @var{prompt-string} as the prompt. This value must be a -string. Then the user can edit text in the minibuffer. - -When the user types a command to exit the minibuffer, -@code{read-from-minibuffer} constructs the return value from the text in -the minibuffer. Normally it returns a string containing that text. -However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer} -reads the text and returns the resulting Lisp object, unevaluated. -(@xref{Input Functions}, for information about reading.) - -The argument @var{default} specifies a default value to make available -through the history commands. It should be a string, or @code{nil}. -If non-@code{nil}, the user can access it using -@code{next-history-element}, usually bound in the minibuffer to -@kbd{M-n}. If @var{read} is non-@code{nil}, then @var{default} is -also used as the input to @code{read}, if the user enters empty input. -(If @var{read} is non-@code{nil} and @var{default} is @code{nil}, empty -input results in an @code{end-of-file} error.) However, in the usual -case (where @var{read} is @code{nil}), @code{read-from-minibuffer} -ignores @var{default} when the user enters empty input and returns an -empty string, @code{""}. In this respect, it is different from all -the other minibuffer input functions in this chapter. - -If @var{keymap} is non-@code{nil}, that keymap is the local keymap to -use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the -value of @code{minibuffer-local-map} is used as the keymap. Specifying -a keymap is the most important way to customize the minibuffer for -various applications such as completion. - -The argument @var{hist} specifies which history list variable to use -for saving the input and for history commands used in the minibuffer. -It defaults to @code{minibuffer-history}. @xref{Minibuffer History}. - -If the variable @code{minibuffer-allow-text-properties} is -non-@code{nil}, then the string which is returned includes whatever text -properties were present in the minibuffer. Otherwise all the text -properties are stripped when the value is returned. - -If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current input method (@pxref{Input Methods}) and -the setting of @code{enable-multibyte-characters} (@pxref{Text -Representations}) from whichever buffer was current before entering the -minibuffer. - -Use of @var{initial-contents} is mostly deprecated; we recommend using -a non-@code{nil} value only in conjunction with specifying a cons cell -for @var{hist}. @xref{Initial Input}. -@end defun - -@defun read-string prompt &optional initial history default inherit-input-method -This function reads a string from the minibuffer and returns it. The -arguments @var{prompt}, @var{initial}, @var{history} and -@var{inherit-input-method} are used as in @code{read-from-minibuffer}. -The keymap used is @code{minibuffer-local-map}. - -The optional argument @var{default} is used as in -@code{read-from-minibuffer}, except that, if non-@code{nil}, it also -specifies a default value to return if the user enters null input. As -in @code{read-from-minibuffer} it should be a string, or @code{nil}, -which is equivalent to an empty string. - -This function is a simplified interface to the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit}) -@equiv{} -(let ((value - (read-from-minibuffer @var{prompt} @var{initial} nil nil - @var{history} @var{default} @var{inherit}))) - (if (and (equal value "") @var{default}) - @var{default} - value)) -@end group -@end smallexample -@end defun - -@defvar minibuffer-allow-text-properties -If this variable is @code{nil}, then @code{read-from-minibuffer} strips -all text properties from the minibuffer input before returning it. -This variable also affects @code{read-string}. However, -@code{read-no-blanks-input} (see below), as well as -@code{read-minibuffer} and related functions (@pxref{Object from -Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all -functions that do minibuffer input with completion, discard text -properties unconditionally, regardless of the value of this variable. -@end defvar - -@defvar minibuffer-local-map -This -@anchor{Definition of minibuffer-local-map} -@c avoid page break at anchor; work around Texinfo deficiency -is the default local keymap for reading from the minibuffer. By -default, it makes the following bindings: - -@table @asis -@item @kbd{C-j} -@code{exit-minibuffer} - -@item @key{RET} -@code{exit-minibuffer} - -@item @kbd{C-g} -@code{abort-recursive-edit} - -@item @kbd{M-n} -@itemx @key{DOWN} -@code{next-history-element} - -@item @kbd{M-p} -@itemx @key{UP} -@code{previous-history-element} - -@item @kbd{M-s} -@code{next-matching-history-element} - -@item @kbd{M-r} -@code{previous-matching-history-element} -@end table -@end defvar - -@c In version 18, initial is required -@c Emacs 19 feature -@defun read-no-blanks-input prompt &optional initial inherit-input-method -This function reads a string from the minibuffer, but does not allow -whitespace characters as part of the input: instead, those characters -terminate the input. The arguments @var{prompt}, @var{initial}, and -@var{inherit-input-method} are used as in @code{read-from-minibuffer}. - -This is a simplified interface to the @code{read-from-minibuffer} -function, and passes the value of the @code{minibuffer-local-ns-map} -keymap as the @var{keymap} argument for that function. Since the keymap -@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is} -possible to put a space into the string, by quoting it. - -This function discards text properties, regardless of the value of -@code{minibuffer-allow-text-properties}. - -@smallexample -@group -(read-no-blanks-input @var{prompt} @var{initial}) -@equiv{} -(let (minibuffer-allow-text-properties) - (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)) -@end group -@end smallexample -@end defun - -@defvar minibuffer-local-ns-map -This built-in variable is the keymap used as the minibuffer local keymap -in the function @code{read-no-blanks-input}. By default, it makes the -following bindings, in addition to those of @code{minibuffer-local-map}: - -@table @asis -@item @key{SPC} -@cindex @key{SPC} in minibuffer -@code{exit-minibuffer} - -@item @key{TAB} -@cindex @key{TAB} in minibuffer -@code{exit-minibuffer} - -@item @kbd{?} -@cindex @kbd{?} in minibuffer -@code{self-insert-and-exit} -@end table -@end defvar - -@node Object from Minibuffer -@section Reading Lisp Objects with the Minibuffer - - This section describes functions for reading Lisp objects with the -minibuffer. - -@defun read-minibuffer prompt &optional initial -This function reads a Lisp object using the minibuffer, and returns it -without evaluating it. The arguments @var{prompt} and @var{initial} are -used as in @code{read-from-minibuffer}. - -This is a simplified interface to the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-minibuffer @var{prompt} @var{initial}) -@equiv{} -(let (minibuffer-allow-text-properties) - (read-from-minibuffer @var{prompt} @var{initial} nil t)) -@end group -@end smallexample - -Here is an example in which we supply the string @code{"(testing)"} as -initial input: - -@smallexample -@group -(read-minibuffer - "Enter an expression: " (format "%s" '(testing))) - -;; @r{Here is how the minibuffer is displayed:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Enter an expression: (testing)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -The user can type @key{RET} immediately to use the initial input as a -default, or can edit the input. -@end defun - -@defun eval-minibuffer prompt &optional initial -This function reads a Lisp expression using the minibuffer, evaluates -it, then returns the result. The arguments @var{prompt} and -@var{initial} are used as in @code{read-from-minibuffer}. - -This function simply evaluates the result of a call to -@code{read-minibuffer}: - -@smallexample -@group -(eval-minibuffer @var{prompt} @var{initial}) -@equiv{} -(eval (read-minibuffer @var{prompt} @var{initial})) -@end group -@end smallexample -@end defun - -@defun edit-and-eval-command prompt form -This function reads a Lisp expression in the minibuffer, and then -evaluates it. The difference between this command and -@code{eval-minibuffer} is that here the initial @var{form} is not -optional and it is treated as a Lisp object to be converted to printed -representation rather than as a string of text. It is printed with -@code{prin1}, so if it is a string, double-quote characters (@samp{"}) -appear in the initial text. @xref{Output Functions}. - -The first thing @code{edit-and-eval-command} does is to activate the -minibuffer with @var{prompt} as the prompt. Then it inserts the printed -representation of @var{form} in the minibuffer, and lets the user edit it. -When the user exits the minibuffer, the edited text is read with -@code{read} and then evaluated. The resulting value becomes the value -of @code{edit-and-eval-command}. - -In the following example, we offer the user an expression with initial -text which is a valid form already: - -@smallexample -@group -(edit-and-eval-command "Please edit: " '(forward-word 1)) - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Please edit: (forward-word 1)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -Typing @key{RET} right away would exit the minibuffer and evaluate the -expression, thus moving point forward one word. -@code{edit-and-eval-command} returns @code{nil} in this example. -@end defun - -@node Minibuffer History -@section Minibuffer History -@cindex minibuffer history -@cindex history list - - A @dfn{minibuffer history list} records previous minibuffer inputs so -the user can reuse them conveniently. A history list is actually a -symbol, not a list; it is a variable whose value is a list of strings -(previous inputs), most recent first. - - There are many separate history lists, used for different kinds of -inputs. It's the Lisp programmer's job to specify the right history -list for each use of the minibuffer. - - You specify the history list with the optional @var{hist} argument -to either @code{read-from-minibuffer} or @code{completing-read}. Here -are the possible values for it: - -@table @asis -@item @var{variable} -Use @var{variable} (a symbol) as the history list. - -@item (@var{variable} . @var{startpos}) -Use @var{variable} (a symbol) as the history list, and assume that the -initial history position is @var{startpos} (a nonnegative integer). - -Specifying 0 for @var{startpos} is equivalent to just specifying the -symbol @var{variable}. @code{previous-history-element} will display -the most recent element of the history list in the minibuffer. If you -specify a positive @var{startpos}, the minibuffer history functions -behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the -history element currently shown in the minibuffer. - -For consistency, you should also specify that element of the history -as the initial minibuffer contents, using the @var{initial} argument -to the minibuffer input function (@pxref{Initial Input}). -@end table - - If you don't specify @var{hist}, then the default history list -@code{minibuffer-history} is used. For other standard history lists, -see below. You can also create your own history list variable; just -initialize it to @code{nil} before the first use. - - Both @code{read-from-minibuffer} and @code{completing-read} add new -elements to the history list automatically, and provide commands to -allow the user to reuse items on the list. The only thing your program -needs to do to use a history list is to initialize it and to pass its -name to the input functions when you wish. But it is safe to modify the -list by hand when the minibuffer input functions are not using it. - - Emacs functions that add a new element to a history list can also -delete old elements if the list gets too long. The variable -@code{history-length} specifies the maximum length for most history -lists. To specify a different maximum length for a particular history -list, put the length in the @code{history-length} property of the -history list symbol. The variable @code{history-delete-duplicates} -specifies whether to delete duplicates in history. - -@defun add-to-history history-var newelt &optional maxelt keep-all -This function adds a new element @var{newelt}, if it isn't the empty -string, to the history list stored in the variable @var{history-var}, -and returns the updated history list. It limits the list length to -the value of @var{maxelt} (if non-@code{nil}) or @code{history-length} -(described below). The possible values of @var{maxelt} have the same -meaning as the values of @code{history-length}. - -Normally, @code{add-to-history} removes duplicate members from the -history list if @code{history-delete-duplicates} is non-@code{nil}. -However, if @var{keep-all} is non-@code{nil}, that says not to remove -duplicates, and to add @var{newelt} to the list even if it is empty. -@end defun - -@defvar history-add-new-input -If the value of this variable is @code{nil}, standard functions that -read from the minibuffer don't add new elements to the history list. -This lets Lisp programs explicitly manage input history by using -@code{add-to-history}. By default, @code{history-add-new-input} is -set to a non-@code{nil} value. -@end defvar - -@defvar history-length -The value of this variable specifies the maximum length for all -history lists that don't specify their own maximum lengths. If the -value is @code{t}, that means there no maximum (don't delete old -elements). The value of @code{history-length} property of the history -list variable's symbol, if set, overrides this variable for that -particular history list. -@end defvar - -@defvar history-delete-duplicates -If the value of this variable is @code{t}, that means when adding a -new history element, all previous identical elements are deleted. -@end defvar - - Here are some of the standard minibuffer history list variables: - -@defvar minibuffer-history -The default history list for minibuffer history input. -@end defvar - -@defvar query-replace-history -A history list for arguments to @code{query-replace} (and similar -arguments to other commands). -@end defvar - -@defvar file-name-history -A history list for file-name arguments. -@end defvar - -@defvar buffer-name-history -A history list for buffer-name arguments. -@end defvar - -@defvar regexp-history -A history list for regular expression arguments. -@end defvar - -@defvar extended-command-history -A history list for arguments that are names of extended commands. -@end defvar - -@defvar shell-command-history -A history list for arguments that are shell commands. -@end defvar - -@defvar read-expression-history -A history list for arguments that are Lisp expressions to evaluate. -@end defvar - -@node Initial Input -@section Initial Input - -Several of the functions for minibuffer input have an argument called -@var{initial} or @var{initial-contents}. This is a mostly-deprecated -feature for specifying that the minibuffer should start out with -certain text, instead of empty as usual. - -If @var{initial} is a string, the minibuffer starts out containing the -text of the string, with point at the end, when the user starts to -edit the text. If the user simply types @key{RET} to exit the -minibuffer, it will use the initial input string to determine the -value to return. - -@strong{We discourage use of a non-@code{nil} value for -@var{initial}}, because initial input is an intrusive interface. -History lists and default values provide a much more convenient method -to offer useful default inputs to the user. - -There is just one situation where you should specify a string for an -@var{initial} argument. This is when you specify a cons cell for the -@var{hist} or @var{history} argument. @xref{Minibuffer History}. - -@var{initial} can also be a cons cell of the form @code{(@var{string} -. @var{position})}. This means to insert @var{string} in the -minibuffer but put point at @var{position} within the string's text. - -As a historical accident, @var{position} was implemented -inconsistently in different functions. In @code{completing-read}, -@var{position}'s value is interpreted as origin-zero; that is, a value -of 0 means the beginning of the string, 1 means after the first -character, etc. In @code{read-minibuffer}, and the other -non-completion minibuffer input functions that support this argument, -1 means the beginning of the string 2 means after the first character, -etc. - -Use of a cons cell as the value for @var{initial} arguments is -deprecated in user code. - -@node Completion -@section Completion -@cindex completion - - @dfn{Completion} is a feature that fills in the rest of a name -starting from an abbreviation for it. Completion works by comparing the -user's input against a list of valid names and determining how much of -the name is determined uniquely by what the user has typed. For -example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then -type the first few letters of the name of the buffer to which you wish -to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs -extends the name as far as it can. - - Standard Emacs commands offer completion for names of symbols, files, -buffers, and processes; with the functions in this section, you can -implement completion for other kinds of names. - - The @code{try-completion} function is the basic primitive for -completion: it returns the longest determined completion of a given -initial string, with a given set of strings to match against. - - The function @code{completing-read} provides a higher-level interface -for completion. A call to @code{completing-read} specifies how to -determine the list of valid names. The function then activates the -minibuffer with a local keymap that binds a few keys to commands useful -for completion. Other functions provide convenient simple interfaces -for reading certain kinds of names with completion. - -@menu -* 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:: Writing your own completion-function. -@end menu - -@node Basic Completion -@subsection Basic Completion Functions - - The completion functions @code{try-completion}, -@code{all-completions} and @code{test-completion} have nothing in -themselves to do with minibuffers. We describe them in this chapter -so as to keep them near the higher-level completion features that do -use the minibuffer. - - If you store a completion alist in a variable, you should mark the -variable as ``risky'' with a non-@code{nil} -@code{risky-local-variable} property. - -@defun try-completion string collection &optional predicate -This function returns the longest common substring of all possible -completions of @var{string} in @var{collection}. The value of -@var{collection} must be a list of strings or symbols, an alist, an -obarray, a hash table, or a function that implements a virtual set of -strings (see below). - -Completion compares @var{string} against each of the permissible -completions specified by @var{collection}; if the beginning of the -permissible completion equals @var{string}, it matches. If no permissible -completions match, @code{try-completion} returns @code{nil}. If only -one permissible completion matches, and the match is exact, then -@code{try-completion} returns @code{t}. Otherwise, the value is the -longest initial sequence common to all the permissible completions that -match. - -If @var{collection} is an alist (@pxref{Association Lists}), the -permissible completions are the elements of the alist that are either -strings, symbols, or conses whose @sc{car} is a string or symbol. -Symbols are converted to strings using @code{symbol-name}. Other -elements of the alist are ignored. (Remember that in Emacs Lisp, the -elements of alists do not @emph{have} to be conses.) In particular, a -list of strings or symbols is allowed, even though we usually do not -think of such lists as alists. - -@cindex obarray in completion -If @var{collection} is an obarray (@pxref{Creating Symbols}), the names -of all symbols in the obarray form the set of permissible completions. The -global variable @code{obarray} holds an obarray containing the names of -all interned Lisp symbols. - -Note that the only valid way to make a new obarray is to create it -empty and then add symbols to it one by one using @code{intern}. -Also, you cannot intern a given symbol in more than one obarray. - -If @var{collection} is a hash table, then the keys that are strings -are the possible completions. Other keys are ignored. - -You can also use a symbol that is a function as @var{collection}. Then -the function is solely responsible for performing completion; -@code{try-completion} returns whatever this function returns. The -function is called with three arguments: @var{string}, @var{predicate} -and @code{nil}. (The reason for the third argument is so that the same -function can be used in @code{all-completions} and do the appropriate -thing in either case.) @xref{Programmed Completion}. - -If the argument @var{predicate} is non-@code{nil}, then it must be a -function of one argument, unless @var{collection} is a hash table, in -which case it should be a function of two arguments. It is used to -test each possible match, and the match is accepted only if -@var{predicate} returns non-@code{nil}. The argument given to -@var{predicate} is either a string or a cons cell (the @sc{car} of -which is a string) from the alist, or a symbol (@emph{not} a symbol -name) from the obarray. If @var{collection} is a hash table, -@var{predicate} is called with two arguments, the string key and the -associated value. - -In addition, to be acceptable, a completion must also match all the -regular expressions in @code{completion-regexp-list}. (Unless -@var{collection} is a function, in which case that function has to -handle @code{completion-regexp-list} itself.) - -In the first of the following examples, the string @samp{foo} is -matched by three of the alist @sc{car}s. All of the matches begin with -the characters @samp{fooba}, so that is the result. In the second -example, there is only one possible match, and it is exact, so the value -is @code{t}. - -@smallexample -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) - @result{} "fooba" -@end group - -@group -(try-completion "foo" '(("barfoo" 2) ("foo" 3))) - @result{} t -@end group -@end smallexample - -In the following example, numerous symbols begin with the characters -@samp{forw}, and all of them begin with the word @samp{forward}. In -most of the symbols, this is followed with a @samp{-}, but not in all, -so no more than @samp{forward} can be completed. - -@smallexample -@group -(try-completion "forw" obarray) - @result{} "forward" -@end group -@end smallexample - -Finally, in the following example, only two of the three possible -matches pass the predicate @code{test} (the string @samp{foobaz} is -too short). Both of those begin with the string @samp{foobar}. - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} "foobar" -@end group -@end smallexample -@end defun - -@defun all-completions string collection &optional predicate nospace -This function returns a list of all possible completions of -@var{string}. The arguments to this function (aside from -@var{nospace}) are the same as those of @code{try-completion}. Also, -this function uses @code{completion-regexp-list} in the same way that -@code{try-completion} does. The optional argument @var{nospace} only -matters if @var{string} is the empty string. In that case, if -@var{nospace} is non-@code{nil}, completions that start with a space -are ignored. - -If @var{collection} is a function, it is called with three arguments: -@var{string}, @var{predicate} and @code{t}; then @code{all-completions} -returns whatever the function returns. @xref{Programmed Completion}. - -Here is an example, using the function @code{test} shown in the -example for @code{try-completion}: - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group - -@group -(all-completions - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} ("foobar1" "foobar2") -@end group -@end smallexample -@end defun - -@defun test-completion string collection &optional predicate -@anchor{Definition of test-completion} -This function returns non-@code{nil} if @var{string} is a valid -completion possibility specified by @var{collection} and -@var{predicate}. The arguments are the same as in -@code{try-completion}. For instance, if @var{collection} is a list of -strings, this is true if @var{string} appears in the list and -@var{predicate} is satisfied. - -This function uses @code{completion-regexp-list} in the same -way that @code{try-completion} does. - -If @var{predicate} is non-@code{nil} and if @var{collection} contains -several strings that are equal to each other, as determined by -@code{compare-strings} according to @code{completion-ignore-case}, -then @var{predicate} should accept either all or none of them. -Otherwise, the return value of @code{test-completion} is essentially -unpredictable. - -If @var{collection} is a function, it is called with three arguments, -the values @var{string}, @var{predicate} and @code{lambda}; whatever -it returns, @code{test-completion} returns in turn. -@end defun - -@defvar completion-ignore-case -If the value of this variable is non-@code{nil}, Emacs does not -consider case significant in completion. -@end defvar - -@defvar completion-regexp-list -This is a list of regular expressions. The completion functions only -consider a completion acceptable if it matches all regular expressions -in this list, with @code{case-fold-search} (@pxref{Searching and Case}) -bound to the value of @code{completion-ignore-case}. -@end defvar - -@defmac lazy-completion-table var fun -This macro provides a way to initialize the variable @var{var} as a -collection for completion in a lazy way, not computing its actual -contents until they are first needed. You use this macro to produce a -value that you store in @var{var}. The actual computation of the -proper value is done the first time you do completion using @var{var}. -It is done by calling @var{fun} with no arguments. The -value @var{fun} returns becomes the permanent value of @var{var}. - -Here is an example of use: - -@smallexample -(defvar foo (lazy-completion-table foo make-my-alist)) -@end smallexample -@end defmac - -@node Minibuffer Completion -@subsection Completion and the Minibuffer -@cindex minibuffer completion -@cindex reading from minibuffer with completion - - This section describes the basic interface for reading from the -minibuffer with completion. - -@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method -This function reads a string in the minibuffer, assisting the user by -providing completion. It activates the minibuffer with prompt -@var{prompt}, which must be a string. - -The actual completion is done by passing @var{collection} and -@var{predicate} to the function @code{try-completion}. This happens -in certain commands bound in the local keymaps used for completion. -Some of these commands also call @code{test-completion}. Thus, if -@var{predicate} is non-@code{nil}, it should be compatible with -@var{collection} and @code{completion-ignore-case}. @xref{Definition -of test-completion}. - -If @var{require-match} is @code{nil}, the exit commands work regardless -of the input in the minibuffer. If @var{require-match} is @code{t}, the -usual minibuffer exit commands won't exit unless the input completes to -an element of @var{collection}. If @var{require-match} is neither -@code{nil} nor @code{t}, then the exit commands won't exit unless the -input already in the buffer matches an element of @var{collection}. - -However, empty input is always permitted, regardless of the value of -@var{require-match}; in that case, @code{completing-read} returns -@var{default}, or @code{""}, if @var{default} is @code{nil}. The -value of @var{default} (if non-@code{nil}) is also available to the -user through the history commands. - -The function @code{completing-read} uses -@code{minibuffer-local-completion-map} as the keymap if -@var{require-match} is @code{nil}, and uses -@code{minibuffer-local-must-match-map} if @var{require-match} is -non-@code{nil}. @xref{Completion Commands}. - -The argument @var{hist} specifies which history list variable to use for -saving the input and for minibuffer history commands. It defaults to -@code{minibuffer-history}. @xref{Minibuffer History}. - -The argument @var{initial} is mostly deprecated; we recommend using a -non-@code{nil} value only in conjunction with specifying a cons cell -for @var{hist}. @xref{Initial Input}. For default input, use -@var{default} instead. - -If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current input method (@pxref{Input -Methods}) and the setting of @code{enable-multibyte-characters} -(@pxref{Text Representations}) from whichever buffer was current before -entering the minibuffer. - -If the built-in variable @code{completion-ignore-case} is -non-@code{nil}, completion ignores case when comparing the input -against the possible matches. @xref{Basic Completion}. In this mode -of operation, @var{predicate} must also ignore case, or you will get -surprising results. - -Here's an example of using @code{completing-read}: - -@smallexample -@group -(completing-read - "Complete a foo: " - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - nil t "fo") -@end group - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} - ----------- Buffer: Minibuffer ---------- -Complete a foo: fo@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}}, -@code{completing-read} returns @code{barfoo}. - -The @code{completing-read} function binds variables to pass -information to the commands that actually do completion. -They are described in the following section. -@end defun - -@node Completion Commands -@subsection Minibuffer Commands that Do Completion - - This section describes the keymaps, commands and user options used -in the minibuffer to do completion. The description refers to the -situation when Partial Completion mode is disabled (as it is by -default). When enabled, this minor mode uses its own alternatives to -some of the commands described below. @xref{Completion Options,,, -emacs, The GNU Emacs Manual}, for a short description of Partial -Completion mode. - -@defvar minibuffer-completion-table -The value of this variable is the collection used for completion in -the minibuffer. This is the global variable that contains what -@code{completing-read} passes to @code{try-completion}. It is used by -minibuffer completion commands such as @code{minibuffer-complete-word}. -@end defvar - -@defvar minibuffer-completion-predicate -This variable's value is the predicate that @code{completing-read} -passes to @code{try-completion}. The variable is also used by the other -minibuffer completion functions. -@end defvar - -@defvar minibuffer-completion-confirm -When the value of this variable is non-@code{nil}, Emacs asks for -confirmation of a completion before exiting the minibuffer. -@code{completing-read} binds this variable, and the function -@code{minibuffer-complete-and-exit} checks the value before exiting. -@end defvar - -@deffn Command minibuffer-complete-word -This function completes the minibuffer contents by at most a single -word. Even if the minibuffer contents have only one completion, -@code{minibuffer-complete-word} does not add any characters beyond the -first character that is not a word constituent. @xref{Syntax Tables}. -@end deffn - -@deffn Command minibuffer-complete -This function completes the minibuffer contents as far as possible. -@end deffn - -@deffn Command minibuffer-complete-and-exit -This function completes the minibuffer contents, and exits if -confirmation is not required, i.e., if -@code{minibuffer-completion-confirm} is @code{nil}. If confirmation -@emph{is} required, it is given by repeating this command -immediately---the command is programmed to work without confirmation -when run twice in succession. -@end deffn - -@deffn Command minibuffer-completion-help -This function creates a list of the possible completions of the -current minibuffer contents. It works by calling @code{all-completions} -using the value of the variable @code{minibuffer-completion-table} as -the @var{collection} argument, and the value of -@code{minibuffer-completion-predicate} as the @var{predicate} argument. -The list of completions is displayed as text in a buffer named -@samp{*Completions*}. -@end deffn - -@defun display-completion-list completions &optional common-substring -This function displays @var{completions} to the stream in -@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more -information about streams.) The argument @var{completions} is normally -a list of completions just returned by @code{all-completions}, but it -does not have to be. Each element may be a symbol or a string, either -of which is simply printed. It can also be a list of two strings, -which is printed as if the strings were concatenated. The first of -the two strings is the actual completion, the second string serves as -annotation. - -The argument @var{common-substring} is the prefix that is common to -all the completions. With normal Emacs completion, it is usually the -same as the string that was completed. @code{display-completion-list} -uses this to highlight text in the completion list for better visual -feedback. This is not needed in the minibuffer; for minibuffer -completion, you can pass @code{nil}. - -This function is called by @code{minibuffer-completion-help}. The -most common way to use it is together with -@code{with-output-to-temp-buffer}, like this: - -@example -(with-output-to-temp-buffer "*Completions*" - (display-completion-list - (all-completions (buffer-string) my-alist) - (buffer-string))) -@end example -@end defun - -@defopt completion-auto-help -If this variable is non-@code{nil}, the completion commands -automatically display a list of possible completions whenever nothing -can be completed because the next character is not uniquely determined. -@end defopt - -@defvar minibuffer-local-completion-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is not required. By default, this -keymap makes the following bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} -@end table - -@noindent -with other characters bound as in @code{minibuffer-local-map} -(@pxref{Definition of minibuffer-local-map}). -@end defvar - -@defvar minibuffer-local-must-match-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is required. Therefore, no keys -are bound to @code{exit-minibuffer}, the command that exits the -minibuffer unconditionally. By default, this keymap makes the following -bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} - -@item @kbd{C-j} -@code{minibuffer-complete-and-exit} - -@item @key{RET} -@code{minibuffer-complete-and-exit} -@end table - -@noindent -with other characters bound as in @code{minibuffer-local-map}. -@end defvar - -@defvar minibuffer-local-filename-completion-map -This is like @code{minibuffer-local-completion-map} -except that it does not bind @key{SPC}. This keymap is used by the -function @code{read-file-name}. -@end defvar - -@defvar minibuffer-local-must-match-filename-map -This is like @code{minibuffer-local-must-match-map} -except that it does not bind @key{SPC}. This keymap is used by the -function @code{read-file-name}. -@end defvar - -@node High-Level Completion -@subsection High-Level Completion Functions - - This section describes the higher-level convenient functions for -reading certain sorts of names with completion. - - In most cases, you should not call these functions in the middle of a -Lisp function. When possible, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} -specification. @xref{Defining Commands}. - -@defun read-buffer prompt &optional default existing -This function reads the name of a buffer and returns it as a string. -The argument @var{default} is the default name to use, the value to -return if the user exits with an empty minibuffer. If non-@code{nil}, -it should be a string or a buffer. It is mentioned in the prompt, but -is not inserted in the minibuffer as initial input. - -The argument @var{prompt} should be a string ending with a colon and a -space. If @var{default} is non-@code{nil}, the function inserts it in -@var{prompt} before the colon to follow the convention for reading from -the minibuffer with a default value (@pxref{Programming Tips}). - -If @var{existing} is non-@code{nil}, then the name specified must be -that of an existing buffer. The usual commands to exit the minibuffer -do not exit if the text is not valid, and @key{RET} does completion to -attempt to find a valid name. If @var{existing} is neither @code{nil} -nor @code{t}, confirmation is required after completion. (However, -@var{default} is not checked for validity; it is returned, whatever it -is, if the user exits with the minibuffer empty.) - -In the following example, the user enters @samp{minibuffer.t}, and -then types @key{RET}. The argument @var{existing} is @code{t}, and the -only buffer name starting with the given input is -@samp{minibuffer.texi}, so that name is the value. - -@example -(read-buffer "Buffer name: " "foo" t) -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Buffer name (default foo): @point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{The user types @kbd{minibuffer.t @key{RET}}.} - @result{} "minibuffer.texi" -@end group -@end example -@end defun - -@defvar read-buffer-function -This variable specifies how to read buffer names. For example, if you -set this variable to @code{iswitchb-read-buffer}, all Emacs commands -that call @code{read-buffer} to read a buffer name will actually use the -@code{iswitchb} package to read it. -@end defvar - -@defun read-command prompt &optional default -This function reads the name of a command and returns it as a Lisp -symbol. The argument @var{prompt} is used as in -@code{read-from-minibuffer}. Recall that a command is anything for -which @code{commandp} returns @code{t}, and a command name is a symbol -for which @code{commandp} returns @code{t}. @xref{Interactive Call}. - -The argument @var{default} specifies what to return if the user enters -null input. It can be a symbol or a string; if it is a string, -@code{read-command} interns it before returning it. If @var{default} is -@code{nil}, that means no default has been specified; then if the user -enters null input, the return value is @code{(intern "")}, that is, a -symbol whose name is an empty string. - -@example -(read-command "Command name? ") - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Command name? ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -If the user types @kbd{forward-c @key{RET}}, then this function returns -@code{forward-char}. - -The @code{read-command} function is a simplified interface to -@code{completing-read}. It uses the variable @code{obarray} so as to -complete in the set of extant Lisp symbols, and it uses the -@code{commandp} predicate so as to accept only command names: - -@cindex @code{commandp} example -@example -@group -(read-command @var{prompt}) -@equiv{} -(intern (completing-read @var{prompt} obarray - 'commandp t nil)) -@end group -@end example -@end defun - -@defun read-variable prompt &optional default -@anchor{Definition of read-variable} -This function reads the name of a user variable and returns it as a -symbol. - -The argument @var{default} specifies what to return if the user enters -null input. It can be a symbol or a string; if it is a string, -@code{read-variable} interns it before returning it. If @var{default} -is @code{nil}, that means no default has been specified; then if the -user enters null input, the return value is @code{(intern "")}. - -@example -@group -(read-variable "Variable name? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Variable name? @point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -If the user then types @kbd{fill-p @key{RET}}, @code{read-variable} -returns @code{fill-prefix}. - -In general, @code{read-variable} is similar to @code{read-command}, -but uses the predicate @code{user-variable-p} instead of -@code{commandp}: - -@cindex @code{user-variable-p} example -@example -@group -(read-variable @var{prompt}) -@equiv{} -(intern - (completing-read @var{prompt} obarray - 'user-variable-p t nil)) -@end group -@end example -@end defun - - See also the functions @code{read-coding-system} and -@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}, -and @code{read-input-method-name}, in @ref{Input Methods}. - -@node Reading File Names -@subsection Reading File Names -@cindex read file names -@cindex prompt for file name - - Here is another high-level completion function, designed for reading a -file name. It provides special features including automatic insertion -of the default directory. - -@defun read-file-name prompt &optional directory default existing initial predicate -This function reads a file name in the minibuffer, prompting with -@var{prompt} and providing completion. - -If @var{existing} is non-@code{nil}, then the user must specify the name -of an existing file; @key{RET} performs completion to make the name -valid if possible, and then refuses to exit if it is not valid. If the -value of @var{existing} is neither @code{nil} nor @code{t}, then -@key{RET} also requires confirmation after completion. If -@var{existing} is @code{nil}, then the name of a nonexistent file is -acceptable. - -@code{read-file-name} uses -@code{minibuffer-local-filename-completion-map} as the keymap if -@var{existing} is @code{nil}, and uses -@code{minibuffer-local-must-match-filename-map} if @var{existing} is -non-@code{nil}. @xref{Completion Commands}. - -The argument @var{directory} specifies the directory to use for -completion of relative file names. It should be an absolute directory -name. If @code{insert-default-directory} is non-@code{nil}, -@var{directory} is also inserted in the minibuffer as initial input. -It defaults to the current buffer's value of @code{default-directory}. - -@c Emacs 19 feature -If you specify @var{initial}, that is an initial file name to insert -in the buffer (after @var{directory}, if that is inserted). In this -case, point goes at the beginning of @var{initial}. The default for -@var{initial} is @code{nil}---don't insert any file name. To see what -@var{initial} does, try the command @kbd{C-x C-v}. @strong{Please -note:} we recommend using @var{default} rather than @var{initial} in -most cases. - -If @var{default} is non-@code{nil}, then the function returns -@var{default} if the user exits the minibuffer with the same non-empty -contents that @code{read-file-name} inserted initially. The initial -minibuffer contents are always non-empty if -@code{insert-default-directory} is non-@code{nil}, as it is by -default. @var{default} is not checked for validity, regardless of the -value of @var{existing}. However, if @var{existing} is -non-@code{nil}, the initial minibuffer contents should be a valid file -(or directory) name. Otherwise @code{read-file-name} attempts -completion if the user exits without any editing, and does not return -@var{default}. @var{default} is also available through the history -commands. - -If @var{default} is @code{nil}, @code{read-file-name} tries to find a -substitute default to use in its place, which it treats in exactly the -same way as if it had been specified explicitly. If @var{default} is -@code{nil}, but @var{initial} is non-@code{nil}, then the default is -the absolute file name obtained from @var{directory} and -@var{initial}. If both @var{default} and @var{initial} are @code{nil} -and the buffer is visiting a file, @code{read-file-name} uses the -absolute file name of that file as default. If the buffer is not -visiting a file, then there is no default. In that case, if the user -types @key{RET} without any editing, @code{read-file-name} simply -returns the pre-inserted contents of the minibuffer. - -If the user types @key{RET} in an empty minibuffer, this function -returns an empty string, regardless of the value of @var{existing}. -This is, for instance, how the user can make the current buffer visit -no file using @code{M-x set-visited-file-name}. - -If @var{predicate} is non-@code{nil}, it specifies a function of one -argument that decides which file names are acceptable completion -possibilities. A file name is an acceptable value if @var{predicate} -returns non-@code{nil} for it. - -@code{read-file-name} does not automatically expand file names. You -must call @code{expand-file-name} yourself if an absolute file name is -required. - -Here is an example: - -@example -@group -(read-file-name "The file is ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -Typing @kbd{manual @key{TAB}} results in the following: - -@example -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/manual.texi@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@c Wordy to avoid overfull hbox in smallbook mode. -@noindent -If the user types @key{RET}, @code{read-file-name} returns the file name -as the string @code{"/gp/gnu/elisp/manual.texi"}. -@end defun - -@defvar read-file-name-function -If non-@code{nil}, this should be a function that accepts the same -arguments as @code{read-file-name}. When @code{read-file-name} is -called, it calls this function with the supplied arguments instead of -doing its usual work. -@end defvar - -@defvar read-file-name-completion-ignore-case -If this variable is non-@code{nil}, @code{read-file-name} ignores case -when performing completion. -@end defvar - -@defun read-directory-name prompt &optional directory default existing initial -This function is like @code{read-file-name} but allows only directory -names as completion possibilities. - -If @var{default} is @code{nil} and @var{initial} is non-@code{nil}, -@code{read-directory-name} constructs a substitute default by -combining @var{directory} (or the current buffer's default directory -if @var{directory} is @code{nil}) and @var{initial}. If both -@var{default} and @var{initial} are @code{nil}, this function uses -@var{directory} as substitute default, or the current buffer's default -directory if @var{directory} is @code{nil}. -@end defun - -@defopt insert-default-directory -This variable is used by @code{read-file-name}, and thus, indirectly, -by most commands reading file names. (This includes all commands that -use the code letters @samp{f} or @samp{F} in their interactive form. -@xref{Interactive Codes,, Code Characters for interactive}.) Its -value controls whether @code{read-file-name} starts by placing the -name of the default directory in the minibuffer, plus the initial file -name if any. If the value of this variable is @code{nil}, then -@code{read-file-name} does not place any initial input in the -minibuffer (unless you specify initial input with the @var{initial} -argument). In that case, the default directory is still used for -completion of relative file names, but is not displayed. - -If this variable is @code{nil} and the initial minibuffer contents are -empty, the user may have to explicitly fetch the next history element -to access a default value. If the variable is non-@code{nil}, the -initial minibuffer contents are always non-empty and the user can -always request a default value by immediately typing @key{RET} in an -unedited minibuffer. (See above.) - -For example: - -@example -@group -;; @r{Here the minibuffer starts out with the default directory.} -(let ((insert-default-directory t)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is ~lewis/manual/@point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{Here the minibuffer is empty and only the prompt} -;; @r{appears on its line.} -(let ((insert-default-directory nil)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is @point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example -@end defopt - -@node Programmed Completion -@subsection Programmed Completion -@cindex programmed completion - - Sometimes it is not possible to create an alist or an obarray -containing all the intended possible completions. In such a case, you -can supply your own function to compute the completion of a given string. -This is called @dfn{programmed completion}. - - To use this feature, pass a symbol with a function definition as the -@var{collection} argument to @code{completing-read}. The function -@code{completing-read} arranges to pass your completion function along -to @code{try-completion} and @code{all-completions}, which will then let -your function do all the work. - - The completion function should accept three arguments: - -@itemize @bullet -@item -The string to be completed. - -@item -The predicate function to filter possible matches, or @code{nil} if -none. Your function should call the predicate for each possible match, -and ignore the possible match if the predicate returns @code{nil}. - -@item -A flag specifying the type of operation. -@end itemize - - There are three flag values for three operations: - -@itemize @bullet -@item -@code{nil} specifies @code{try-completion}. The completion function -should return the completion of the specified string, or @code{t} if the -string is a unique and exact match already, or @code{nil} if the string -matches no possibility. - -If the string is an exact match for one possibility, but also matches -other longer possibilities, the function should return the string, not -@code{t}. - -@item -@code{t} specifies @code{all-completions}. The completion function -should return a list of all possible completions of the specified -string. - -@item -@code{lambda} specifies @code{test-completion}. The completion -function should return @code{t} if the specified string is an exact -match for some possibility; @code{nil} otherwise. -@end itemize - - It would be consistent and clean for completion functions to allow -lambda expressions (lists that are functions) as well as function -symbols as @var{collection}, but this is impossible. Lists as -completion tables already have other meanings, and it would be -unreliable to treat one differently just because it is also a possible -function. So you must arrange for any function you wish to use for -completion to be encapsulated in a symbol. - - Emacs uses programmed completion when completing file names. -@xref{File Name Completion}. - -@defmac dynamic-completion-table function -This macro is a convenient way to write a function that can act as -programmed completion function. The argument @var{function} should be -a function that takes one argument, a string, and returns an alist of -possible completions of it. You can think of -@code{dynamic-completion-table} as a transducer between that interface -and the interface for programmed completion functions. -@end defmac - -@node Yes-or-No Queries -@section Yes-or-No Queries -@cindex asking the user questions -@cindex querying the user -@cindex yes-or-no questions - - This section describes functions used to ask the user a yes-or-no -question. The function @code{y-or-n-p} can be answered with a single -character; it is useful for questions where an inadvertent wrong answer -will not have serious consequences. @code{yes-or-no-p} is suitable for -more momentous questions, since it requires three or four characters to -answer. - - If either of these functions is called in a command that was invoked -using the mouse---more precisely, if @code{last-nonmenu-event} -(@pxref{Command Loop Info}) is either @code{nil} or a list---then it -uses a dialog box or pop-up menu to ask the question. Otherwise, it -uses keyboard input. You can force use of the mouse or use of keyboard -input by binding @code{last-nonmenu-event} to a suitable value around -the call. - - Strictly speaking, @code{yes-or-no-p} uses the minibuffer and -@code{y-or-n-p} does not; but it seems best to describe them together. - -@defun y-or-n-p prompt -This function asks the user a question, expecting input in the echo -area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the -user types @kbd{n}. This function also accepts @key{SPC} to mean yes -and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit,'' like -@kbd{C-g}, because the question might look like a minibuffer and for -that reason the user might try to use @kbd{C-]} to get out. The answer -is a single character, with no @key{RET} needed to terminate it. Upper -and lower case are equivalent. - -``Asking the question'' means printing @var{prompt} in the echo area, -followed by the string @w{@samp{(y or n) }}. If the input is not one of -the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}}, -@kbd{@key{DEL}}, or something that quits), the function responds -@samp{Please answer y or n.}, and repeats the request. - -This function does not actually use the minibuffer, since it does not -allow editing of the answer. It actually uses the echo area (@pxref{The -Echo Area}), which uses the same screen space as the minibuffer. The -cursor moves to the echo area while the question is being asked. - -The answers and their meanings, even @samp{y} and @samp{n}, are not -hardwired. The keymap @code{query-replace-map} specifies them. -@xref{Search and Replace}. - -In the following example, the user first types @kbd{q}, which is -invalid. At the next prompt the user types @kbd{y}. - -@smallexample -@group -(y-or-n-p "Do you need a lift? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears in the echo area:} -@end group - -@group ----------- Echo area ---------- -Do you need a lift? (y or n) ----------- Echo area ---------- -@end group - -;; @r{If the user then types @kbd{q}, the following appears:} - -@group ----------- Echo area ---------- -Please answer y or n. Do you need a lift? (y or n) ----------- Echo area ---------- -@end group - -;; @r{When the user types a valid answer,} -;; @r{it is displayed after the question:} - -@group ----------- Echo area ---------- -Do you need a lift? (y or n) y ----------- Echo area ---------- -@end group -@end smallexample - -@noindent -We show successive lines of echo area messages, but only one actually -appears on the screen at a time. -@end defun - -@defun y-or-n-p-with-timeout prompt seconds default-value -Like @code{y-or-n-p}, except that if the user fails to answer within -@var{seconds} seconds, this function stops waiting and returns -@var{default-value}. It works by setting up a timer; see @ref{Timers}. -The argument @var{seconds} may be an integer or a floating point number. -@end defun - -@defun yes-or-no-p prompt -This function asks the user a question, expecting input in the -minibuffer. It returns @code{t} if the user enters @samp{yes}, -@code{nil} if the user types @samp{no}. The user must type @key{RET} to -finalize the response. Upper and lower case are equivalent. - -@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area, -followed by @w{@samp{(yes or no) }}. The user must type one of the -expected responses; otherwise, the function responds @samp{Please answer -yes or no.}, waits about two seconds and repeats the request. - -@code{yes-or-no-p} requires more work from the user than -@code{y-or-n-p} and is appropriate for more crucial decisions. - -Here is an example: - -@smallexample -@group -(yes-or-no-p "Do you really want to remove everything? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: minibuffer ---------- -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user first types @kbd{y @key{RET}}, which is invalid because this -function demands the entire word @samp{yes}, it responds by displaying -these prompts, with a brief pause between them: - -@smallexample -@group ----------- Buffer: minibuffer ---------- -Please answer yes or no. -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample -@end defun - -@node Multiple Queries -@section Asking Multiple Y-or-N Questions - - When you have a series of similar questions to ask, such as ``Do you -want to save this buffer'' for each buffer in turn, you should use -@code{map-y-or-n-p} to ask the collection of questions, rather than -asking each question individually. This gives the user certain -convenient facilities such as the ability to answer the whole series at -once. - -@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area -This function asks the user a series of questions, reading a -single-character answer in the echo area for each one. - -The value of @var{list} specifies the objects to ask questions about. -It should be either a list of objects or a generator function. If it is -a function, it should expect no arguments, and should return either the -next object to ask about, or @code{nil} meaning stop asking questions. - -The argument @var{prompter} specifies how to ask each question. If -@var{prompter} is a string, the question text is computed like this: - -@example -(format @var{prompter} @var{object}) -@end example - -@noindent -where @var{object} is the next object to ask about (as obtained from -@var{list}). - -If not a string, @var{prompter} should be a function of one argument -(the next object to ask about) and should return the question text. If -the value is a string, that is the question to ask the user. The -function can also return @code{t} meaning do act on this object (and -don't ask the user), or @code{nil} meaning ignore this object (and don't -ask the user). - -The argument @var{actor} says how to act on the answers that the user -gives. It should be a function of one argument, and it is called with -each object that the user says yes for. Its argument is always an -object obtained from @var{list}. - -If the argument @var{help} is given, it should be a list of this form: - -@example -(@var{singular} @var{plural} @var{action}) -@end example - -@noindent -where @var{singular} is a string containing a singular noun that -describes the objects conceptually being acted on, @var{plural} is the -corresponding plural noun, and @var{action} is a transitive verb -describing what @var{actor} does. - -If you don't specify @var{help}, the default is @code{("object" -"objects" "act on")}. - -Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or -@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip -that object; @kbd{!} to act on all following objects; @key{ESC} or -@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on -the current object and then exit; or @kbd{C-h} to get help. These are -the same answers that @code{query-replace} accepts. The keymap -@code{query-replace-map} defines their meaning for @code{map-y-or-n-p} -as well as for @code{query-replace}; see @ref{Search and Replace}. - -You can use @var{action-alist} to specify additional possible answers -and what they mean. It is an alist of elements of the form -@code{(@var{char} @var{function} @var{help})}, each of which defines one -additional answer. In this element, @var{char} is a character (the -answer); @var{function} is a function of one argument (an object from -@var{list}); @var{help} is a string. - -When the user responds with @var{char}, @code{map-y-or-n-p} calls -@var{function}. If it returns non-@code{nil}, the object is considered -``acted upon,'' and @code{map-y-or-n-p} advances to the next object in -@var{list}. If it returns @code{nil}, the prompt is repeated for the -same object. - -Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while -prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it -does not do that. - -If @code{map-y-or-n-p} is called in a command that was invoked using the -mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command -Loop Info}) is either @code{nil} or a list---then it uses a dialog box -or pop-up menu to ask the question. In this case, it does not use -keyboard input or the echo area. You can force use of the mouse or use -of keyboard input by binding @code{last-nonmenu-event} to a suitable -value around the call. - -The return value of @code{map-y-or-n-p} is the number of objects acted on. -@end defun - -@node Reading a Password -@section Reading a Password -@cindex passwords, reading - - To read a password to pass to another program, you can use the -function @code{read-passwd}. - -@defun read-passwd prompt &optional confirm default -This function reads a password, prompting with @var{prompt}. It does -not echo the password as the user types it; instead, it echoes @samp{.} -for each character in the password. - -The optional argument @var{confirm}, if non-@code{nil}, says to read the -password twice and insist it must be the same both times. If it isn't -the same, the user has to type it over and over until the last two -times match. - -The optional argument @var{default} specifies the default password to -return if the user enters empty input. If @var{default} is @code{nil}, -then @code{read-passwd} returns the null string in that case. -@end defun - -@node Minibuffer Commands -@section Minibuffer Commands - - This section describes some commands meant for use in the -minibuffer. - -@deffn Command exit-minibuffer -This command exits the active minibuffer. It is normally bound to -keys in minibuffer local keymaps. -@end deffn - -@deffn Command self-insert-and-exit -This command exits the active minibuffer after inserting the last -character typed on the keyboard (found in @code{last-command-char}; -@pxref{Command Loop Info}). -@end deffn - -@deffn Command previous-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element. -@end deffn - -@deffn Command next-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th more recent history element. -@end deffn - -@deffn Command previous-matching-history-element pattern n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element that matches @var{pattern} (a -regular expression). -@end deffn - -@deffn Command next-matching-history-element pattern n -This command replaces the minibuffer contents with the value of the -@var{n}th next (newer) history element that matches @var{pattern} (a -regular expression). -@end deffn - -@node Minibuffer Windows -@section Minibuffer Windows -@cindex minibuffer windows - - These functions access and select minibuffer windows -and test whether they are active. - -@defun active-minibuffer-window -This function returns the currently active minibuffer window, or -@code{nil} if none is currently active. -@end defun - -@defun minibuffer-window &optional frame -@anchor{Definition of minibuffer-window} -This function returns the minibuffer window used for frame @var{frame}. -If @var{frame} is @code{nil}, that stands for the current frame. Note -that the minibuffer window used by a frame need not be part of that -frame---a frame that has no minibuffer of its own necessarily uses some -other frame's minibuffer window. -@end defun - -@defun set-minibuffer-window window -This function specifies @var{window} as the minibuffer window to use. -This affects where the minibuffer is displayed if you put text in it -without invoking the usual minibuffer commands. It has no effect on -the usual minibuffer input functions because they all start by -choosing the minibuffer window according to the current frame. -@end defun - -@c Emacs 19 feature -@defun window-minibuffer-p &optional window -This function returns non-@code{nil} if @var{window} is a minibuffer -window. -@var{window} defaults to the selected window. -@end defun - -It is not correct to determine whether a given window is a minibuffer by -comparing it with the result of @code{(minibuffer-window)}, because -there can be more than one minibuffer window if there is more than one -frame. - -@defun minibuffer-window-active-p window -This function returns non-@code{nil} if @var{window}, assumed to be -a minibuffer window, is currently active. -@end defun - -@node Minibuffer Contents -@section Minibuffer Contents - - These functions access the minibuffer prompt and contents. - -@defun minibuffer-prompt -This function returns the prompt string of the currently active -minibuffer. If no minibuffer is active, it returns @code{nil}. -@end defun - -@defun minibuffer-prompt-end -This function returns the current -position of the end of the minibuffer prompt, if a minibuffer is -current. Otherwise, it returns the minimum valid buffer position. -@end defun - -@defun minibuffer-prompt-width -This function returns the current display-width of the minibuffer -prompt, if a minibuffer is current. Otherwise, it returns zero. -@end defun - -@defun minibuffer-contents -This function returns the editable -contents of the minibuffer (that is, everything except the prompt) as -a string, if a minibuffer is current. Otherwise, it returns the -entire contents of the current buffer. -@end defun - -@defun minibuffer-contents-no-properties -This is like @code{minibuffer-contents}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -@end defun - -@defun minibuffer-completion-contents -This is like @code{minibuffer-contents}, except that it returns only -the contents before point. That is the part that completion commands -operate on. @xref{Minibuffer Completion}. -@end defun - -@defun delete-minibuffer-contents -This function erases the editable contents of the minibuffer (that is, -everything except the prompt), if a minibuffer is current. Otherwise, -it erases the entire current buffer. -@end defun - -@node Recursive Mini -@section Recursive Minibuffers -@cindex recursive minibuffers - - These functions and variables deal with recursive minibuffers -(@pxref{Recursive Editing}): - -@defun minibuffer-depth -This function returns the current depth of activations of the -minibuffer, a nonnegative integer. If no minibuffers are active, it -returns zero. -@end defun - -@defopt enable-recursive-minibuffers -If this variable is non-@code{nil}, you can invoke commands (such as -@code{find-file}) that use minibuffers even while the minibuffer window -is active. Such invocation produces a recursive editing level for a new -minibuffer. The outer-level minibuffer is invisible while you are -editing the inner one. - -If this variable is @code{nil}, you cannot invoke minibuffer -commands when the minibuffer window is active, not even if you switch to -another window to do it. -@end defopt - -@c Emacs 19 feature -If a command name has a property @code{enable-recursive-minibuffers} -that is non-@code{nil}, then the command can use the minibuffer to read -arguments even if it is invoked from the minibuffer. A command can -also achieve this by binding @code{enable-recursive-minibuffers} -to @code{t} in the interactive declaration (@pxref{Using Interactive}). -The minibuffer command @code{next-matching-history-element} (normally -@kbd{M-s} in the minibuffer) does the latter. - -@node Minibuffer Misc -@section Minibuffer Miscellany - -@defun minibufferp &optional buffer-or-name -This function returns non-@code{nil} if @var{buffer-or-name} is a -minibuffer. If @var{buffer-or-name} is omitted, it tests the current -buffer. -@end defun - -@defvar minibuffer-setup-hook -This is a normal hook that is run whenever the minibuffer is entered. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-exit-hook -This is a normal hook that is run whenever the minibuffer is exited. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-help-form -@anchor{Definition of minibuffer-help-form} -The current value of this variable is used to rebind @code{help-form} -locally inside the minibuffer (@pxref{Help Functions}). -@end defvar - -@defvar minibuffer-scroll-window -@anchor{Definition of minibuffer-scroll-window} -If the value of this variable is non-@code{nil}, it should be a window -object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. -@end defvar - -@defun minibuffer-selected-window -This function returns the window which was selected when the -minibuffer was entered. If selected window is not a minibuffer -window, it returns @code{nil}. -@end defun - -@defopt max-mini-window-height -This variable specifies the maximum height for resizing minibuffer -windows. If a float, it specifies a fraction of the height of the -frame. If an integer, it specifies a number of lines. -@end defopt - -@defun minibuffer-message string -This function displays @var{string} temporarily at the end of the -minibuffer text, for two seconds, or until the next input event -arrives, whichever comes first. -@end defun - -@ignore - arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218 -@end ignore diff --git a/lispref/mkinstalldirs b/lispref/mkinstalldirs deleted file mode 100755 index f945dbf2bce..00000000000 --- a/lispref/mkinstalldirs +++ /dev/null @@ -1,38 +0,0 @@ -#! /bin/sh -# mkinstalldirs --- make directory hierarchy -# Author: Noah Friedman <friedman@prep.ai.mit.edu> -# Created: 1993-05-16 -# Public domain - -errstatus=0 - -for file -do - set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` - shift - - pathcomp= - for d - do - pathcomp="$pathcomp$d" - case "$pathcomp" in - -* ) pathcomp=./$pathcomp ;; - esac - - if test ! -d "$pathcomp"; then - echo "mkdir $pathcomp" 1>&2 - - mkdir "$pathcomp" || lasterr=$? - - if test ! -d "$pathcomp"; then - errstatus=$lasterr - fi - fi - - pathcomp="$pathcomp/" - done -done - -exit $errstatus - -# mkinstalldirs ends here diff --git a/lispref/modes.texi b/lispref/modes.texi deleted file mode 100644 index 3d60756a901..00000000000 --- a/lispref/modes.texi +++ /dev/null @@ -1,3271 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 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 -* 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. -@end menu - -@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 init file (@pxref{Init File}), but Lisp programs can set them also. -@xref{Standard Hooks}, for a list of standard hook variables. - -@cindex normal hook - Most of the hooks in Emacs are @dfn{normal hooks}. These variables -contain lists of functions to be called with no arguments. By -convention, whenever the hook name ends in @samp{-hook}, that tells -you it is normal. We try to make all hooks normal, as much as -possible, so that you can use them in a uniform way. - - Every major mode function is supposed to run a normal hook called -the @dfn{mode hook} as the one of the last steps of initialization. -This makes it easy for a user to customize the behavior of the mode, -by overriding the buffer-local variable assignments already made by -the mode. Most minor mode functions also run a mode hook at the end. -But hooks are used in other contexts too. For example, the hook -@code{suspend-hook} runs just before Emacs suspends itself -(@pxref{Suspending Emacs}). - - 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. You can add hooks either -globally or buffer-locally with @code{add-hook}. - -@cindex abnormal hook - If the hook variable's name does not end with @samp{-hook}, that -indicates it is probably an @dfn{abnormal hook}. That means the hook -functions are called with arguments, or their return values are used -in some way. The hook's documentation says how the functions are -called. You can use @code{add-hook} to add a function to an abnormal -hook, but you must write the function to follow the hook's calling -convention. - - By convention, abnormal hook names end in @samp{-functions} or -@samp{-hooks}. If the variable's name ends in @samp{-function}, then -its value is just a single function, not a list of functions. - - Here's an example that uses a mode hook to turn on Auto Fill mode when -in Lisp Interaction mode: - -@example -(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) -@end example - - At the appropriate time, Emacs uses the @code{run-hooks} function to -run particular hooks. - -@defun run-hooks &rest hookvars -This function takes one or more normal hook variable names as -arguments, and runs each hook in turn. Each argument should be a -symbol that is a normal hook variable. These arguments are processed -in the order specified. - -If a hook variable has a non-@code{nil} value, that value should be a -list of functions. @code{run-hooks} calls all the functions, one by -one, with no arguments. - -The hook variable's value can also be a single function---either a -lambda expression or a symbol with a function definition---which -@code{run-hooks} calls. But this usage is obsolete. -@end defun - -@defun run-hook-with-args hook &rest args -This function is the way to run an abnormal hook and always call all -of the hook functions. It calls each of the hook functions one by -one, passing each of them the arguments @var{args}. -@end defun - -@defun run-hook-with-args-until-failure hook &rest args -This function is the way to run an abnormal hook until one of the hook -functions fails. It calls each of the hook functions, passing each of -them the arguments @var{args}, until some hook function returns -@code{nil}. It then stops and returns @code{nil}. If none of the -hook functions return @code{nil}, it returns a non-@code{nil} value. -@end defun - -@defun run-hook-with-args-until-success hook &rest args -This function is the way to run an abnormal hook until a hook function -succeeds. It calls each of the hook functions, passing each of them -the arguments @var{args}, until some hook function returns -non-@code{nil}. Then it stops, and returns whatever was returned by -the last hook function that was called. If all hook functions return -@code{nil}, it returns @code{nil} as well. -@end defun - -@defun add-hook hook function &optional append local -This function is the handy way to add function @var{function} to hook -variable @var{hook}. You can use it for abnormal hooks as well as for -normal hooks. @var{function} can be any Lisp function that can accept -the proper number of arguments for @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}. - -If @var{function} is already present in @var{hook} (comparing using -@code{equal}), then @code{add-hook} does not add it a second time. - -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. - -@code{add-hook} can handle the cases where @var{hook} is void or its -value is a single function; it sets or changes the value to a list of -functions. - -If @var{local} is non-@code{nil}, that says to add @var{function} to -the buffer-local hook list instead of to the global hook list. If -needed, this makes the hook buffer-local and adds @code{t} to the -buffer-local value. The latter acts as a flag to run the hook -functions in the default value as well as in the local value. -@end defun - -@defun remove-hook hook function &optional local -This function removes @var{function} from the hook variable -@var{hook}. It compares @var{function} with elements of @var{hook} -using @code{equal}, so it works for both symbols and lambda -expressions. - -If @var{local} is non-@code{nil}, that says to remove @var{function} -from the buffer-local hook list instead of from the global hook list. -@end defun - -@node Major Modes -@section Major Modes -@cindex major mode - - Major modes specialize Emacs for editing particular kinds of text. -Each buffer has only one major mode at a time. For each major mode -there is a function to switch to that mode in the current buffer; its -name should end in @samp{-mode}. These functions work by setting -buffer-local variable bindings and other data associated with the -buffer, such as a local keymap. The effect lasts until you switch -to another major mode in the same buffer. - -@menu -* Major Mode Basics:: -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* 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. -* Example Major Modes:: Text mode and Lisp modes. -@end menu - -@node Major Mode Basics -@subsection Major Mode Basics -@cindex Fundamental mode - - 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 -@kbd{C-j} (@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 use @code{define-derived-mode} to -define a @dfn{derived mode} (@pxref{Derived Modes}). For example, -Rmail Edit mode is a major mode that is very similar to Text mode -except that it provides two additional commands. Its definition is -distinct from that of Text mode, but uses that of Text mode. - - Even if the new mode is not an obvious derivative of any other mode, -it is convenient to use @code{define-derived-mode} with a @code{nil} -parent argument, since it automatically enforces the most important -coding conventions for you. - - For a very simple programming language major mode that handles -comments and fontification, you can use @code{define-generic-mode}. -@xref{Generic Modes}. - - Rmail Edit mode offers an example of changing the major mode -temporarily for a buffer, so it can be edited in a different way (with -ordinary Emacs commands rather than Rmail commands). In such cases, the -temporary major mode usually provides 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 an -alternative major mode avoids this limitation. @xref{Recursive -Editing}. - - The standard GNU Emacs Lisp library directory tree contains the code -for several major modes, in files such as @file{text-mode.el}, -@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and -@file{rmail.el}. They are found in various subdirectories of the -@file{lisp} directory. You can study 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. - -@node Major Mode Conventions -@subsection Major Mode Conventions -@cindex major mode conventions -@cindex conventions for writing major modes - - 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. (Fundamental mode is an exception to many -of these conventions, because its definition is to present the global -state of Emacs.) - - This list of conventions is only partial, because each major mode -should aim for consistency in general with other Emacs major modes. -This makes Emacs as a whole more coherent. It is impossible to list -here all the possible points where this issue might come up; if the -Emacs developers point out an area where your major mode deviates from -the usual conventions, please make it compatible. - -@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 buffer-local variables in an -existing buffer, without changing the buffer's contents. - -@item -Write a documentation string for this command that 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}>}, which 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 runs the normal hook -@code{change-major-mode-hook}, then gets rid of the buffer-local -variables of the major mode previously in effect. @xref{Creating -Buffer-Local}. - -@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 string 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{Coding Conventions}. - -@item -In a major mode for editing some kind of structured text, such as a -programming language, indentation of text according to structure is -probably useful. So the mode should set @code{indent-line-function} -to a suitable function, and probably customize other variables -for indentation. - -@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 command should -call @code{use-local-map} to install this local map. @xref{Active -Keymaps}, for more information. - -This keymap should be stored permanently in a global variable named -@code{@var{modename}-mode-map}. Normally the library that defines the -mode sets this variable. - -@xref{Tips for Defining}, for advice about how to write the code to set -up the mode's keymap variable. - -@item -The key sequences bound in a major mode keymap should usually start with -@kbd{C-c}, followed by a control character, a digit, or @kbd{@{}, -@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation -characters are reserved for minor modes, and ordinary letters are -reserved for users. - -A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and -@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally -be some kind of ``moving forward and backward,'' but this does not -necessarily mean cursor motion. - -It is legitimate for a major mode to rebind a standard key sequence if -it provides a command that does ``the same job'' in a way better -suited to the text this mode is used for. For example, a major mode -for editing a programming language might redefine @kbd{C-M-a} to -``move to the beginning of a function'' in a way that works better for -that language. - -It is also legitimate for a major mode to rebind a standard key -sequence whose standard meaning is rarely useful in that mode. For -instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is -rarely of any use in the minibuffer. Major modes such as Dired or -Rmail that do not allow self-insertion of text can reasonably redefine -letters and other printing characters as special commands. - -@item -Major modes modes for editing text should not define @key{RET} to do -anything other than insert a newline. However, it is ok for -specialized modes for text that users don't directly edit, such as -Dired and Info modes, to redefine @key{RET} to do something entirely -different. - -@item -Major modes should not alter options that are primarily a matter of user -preference, such as whether Auto-Fill mode is enabled. Leave this to -each user to decide. However, a major mode should customize other -variables so that Auto-Fill mode will work usefully @emph{if} the user -decides to use it. - -@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}. @xref{Syntax -Tables}. - -@item -If the mode handles a language that has a syntax for comments, it should -set the variables that define the comment syntax. @xref{Options for -Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}. - -@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}. If the -major mode command defines any abbrevs itself, it should pass @code{t} -for the @var{system-flag} argument to @code{define-abbrev}. -@xref{Defining Abbrevs}. - -@item -The mode should specify how to do highlighting for Font Lock mode, by -setting up a buffer-local value for the variable -@code{font-lock-defaults} (@pxref{Font Lock Mode}). - -@item -The mode should specify how Imenu should find the definitions or -sections of a buffer, by setting up a buffer-local value for the -variable @code{imenu-generic-expression}, for the two variables -@code{imenu-prev-index-position-function} and -@code{imenu-extract-index-name-function}, or for the variable -@code{imenu-create-index-function} (@pxref{Imenu}). - -@item -The mode can specify a local value for -@code{eldoc-documentation-function} to tell ElDoc mode how to handle -this mode. - -@item -Use @code{defvar} or @code{defcustom} to set mode-related variables, so -that they are not reinitialized if they already have a value. (Such -reinitialization could discard customizations made by the user.) - -@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}. - -With rare exceptions, the only reasonable way to use -@code{make-variable-buffer-local} in a Lisp package is for a variable -which is used only within that package. Using it on a variable used by -other packages would interfere with them. - -@item -@cindex mode hook -@cindex major mode hook -Each major mode should have a normal @dfn{mode hook} named -@code{@var{modename}-mode-hook}. The very last thing the major mode command -should do is to call @code{run-mode-hooks}. This runs the mode hook, -and then runs the normal hook @code{after-change-major-mode-hook}. -@xref{Mode Hooks}. - -@item -The major mode command may start by calling some other major mode -command (called the @dfn{parent mode}) and then alter some of its -settings. A mode that does this is called a @dfn{derived mode}. The -recommended way to define one is to use @code{define-derived-mode}, -but this is not required. Such a mode should call the parent mode -command inside a @code{delay-mode-hooks} form. (Using -@code{define-derived-mode} does this automatically.) @xref{Derived -Modes}, and @ref{Mode Hooks}. - -@item -If something special should be done if the user switches a buffer from -this mode to any other major mode, this mode can set up a buffer-local -value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}). - -@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: - -@kindex mode-class @r{(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 is -in Funny mode should not inherit Funny mode, in case -@code{default-major-mode} is @code{nil}. 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 (@pxref{Auto Major Mode}). If you -define the mode command to autoload, you should add this element in -the same file that calls @code{autoload}. If you use an autoload -cookie for the mode command, you can also use an autoload cookie for -the form that adds the element (@pxref{autoload cookie}). If you do -not autoload the mode command, it is sufficient to add the element in -the file that contains the mode definition. - -@item -In the comments that document the file, 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 init files -(@pxref{Init File}). - -@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 - -@node Auto Major Mode -@subsection How Emacs Chooses a Major Mode -@cindex major mode, automatic selection - - 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. It also processes local variables specified in the file text. - -@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 mode 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 buffer-local variable -bindings for the current buffer. First it calls @code{set-auto-mode} -(see below), then it runs @code{hack-local-variables} to parse, and -bind or evaluate as appropriate, the file's local variables -(@pxref{File 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 local variables in the @samp{-*-} -line or at the end of the file. The variable -@code{enable-local-variables} controls whether to do so. @xref{File -Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, -for the syntax of the local variables section of a file. - -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 file local variables. - -If @code{normal-mode} processes the local variables list and this list -specifies a major mode, that mode overrides any mode chosen by -@code{set-auto-mode}. If neither @code{set-auto-mode} nor -@code{hack-local-variables} specify a major mode, the buffer stays in -the major mode determined by @code{default-major-mode} (see below). - -@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 - -@defun set-auto-mode &optional keep-mode-if-same -@cindex visited file mode - This function selects the major mode that is appropriate for the -current buffer. It bases its decision (in order of precedence) on -the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using -@code{interpreter-mode-alist}), on the text at the beginning of the -buffer (using @code{magic-mode-alist}), and finally on the visited -file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How -Major Modes are Chosen, emacs, The GNU Emacs Manual}. 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. -If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode} -does not check the @w{@samp{-*-}} line for a mode tag either. - -If @var{keep-mode-if-same} is non-@code{nil}, this function does not -call the mode command if the buffer is already in the proper major -mode. For instance, @code{set-visited-file-name} sets this to -@code{t} to avoid killing buffer local variables that the user may -have set. -@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 as the default major mode -of a new buffer. However, if that 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 - -@defun set-buffer-major-mode buffer -This function sets the major mode of @var{buffer} to the value of -@code{default-major-mode}; if that variable is @code{nil}, it uses the -current buffer's major mode (if that is suitable). As an exception, -if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to -@code{initial-major-mode}. - -The low-level primitives for creating buffers do not use this function, -but medium-level commands such as @code{switch-to-buffer} and -@code{find-file-noselect} use it whenever they create buffers. -@end defun - -@defopt 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. The default value is @code{lisp-interaction-mode}. -@end defopt - -@defvar interpreter-mode-alist -This variable specifies major modes to use for scripts that specify a -command interpreter in a @samp{#!} line. Its value is an alist with -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 an interpreter which matches @var{interpreter}. -@end defvar - -@defvar magic-mode-alist -This variable's value is an alist with elements of the form -@code{(@var{regexp} . @var{function})}, where @var{regexp} is a -regular expression and @var{function} is a function or @code{nil}. -After visiting a file, @code{set-auto-mode} calls @var{function} if -the text at the beginning of the buffer matches @var{regexp} and -@var{function} is non-@code{nil}; if @var{function} is @code{nil}, -@code{auto-mode-alist} gets to decide the mode. -@end defvar - -@defvar magic-fallback-mode-alist -This works like @code{magic-mode-alist}, except that it is handled -only if @code{auto-mode-alist} does not specify a mode for this file. -@end defvar - -@defvar auto-mode-alist -This variable contains an association list of file name patterns -(regular expressions) and corresponding major mode commands. 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}), with version numbers and backup suffixes removed using -@code{file-name-sans-versions} (@pxref{File Name Components}), 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 feature is useful for -uncompression packages: an entry of the form @code{("\\.gz\\'" -@var{function} t)} 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 -init file.) - -@smallexample -@group -(setq auto-mode-alist - (append - ;; @r{File name (within directory) starts with a dot.} - '(("/\\.[^/]*\\'" . fundamental-mode) - ;; @r{File name has no dot.} - ("[^\\./]*\\'" . fundamental-mode) - ;; @r{File name ends in @samp{.C}.} - ("\\.C\\'" . c++-mode)) - auto-mode-alist)) -@end group -@end smallexample -@end defvar - -@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 buffer-local variable holds the symbol for the current buffer's -major mode. This symbol should have a function definition that is the -command to switch to that major mode. The @code{describe-mode} -function uses the documentation string of the function as the -documentation of the major mode. -@end defvar - -@node Derived Modes -@subsection Defining Derived Modes -@cindex derived mode - - 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 docstring keyword-args@dots{} body@dots{} -This construct defines @var{variant} as a major mode command, using -@var{name} as the string form of the mode name. @var{variant} and -@var{parent} should be unquoted symbols. - -The new command @var{variant} is defined to call the function -@var{parent}, then override certain aspects of that parent mode: - -@itemize @bullet -@item -The new mode has its own sparse keymap, named -@code{@var{variant}-map}. @code{define-derived-mode} -makes the parent mode's keymap the parent of the new map, unless -@code{@var{variant}-map} is already set and already has a parent. - -@item -The new mode has its own syntax table, kept in the variable -@code{@var{variant}-syntax-table}, unless you override this using the -@code{:syntax-table} keyword (see below). @code{define-derived-mode} -makes the parent mode's syntax-table the parent of -@code{@var{variant}-syntax-table}, unless the latter is already set -and already has a parent different from the standard syntax table. - -@item -The new mode has its own abbrev table, kept in the variable -@code{@var{variant}-abbrev-table}, unless you override this using the -@code{:abbrev-table} keyword (see below). - -@item -The new mode has its own mode hook, @code{@var{variant}-hook}. It -runs this hook, after running the hooks of its ancestor modes, with -@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. -@end itemize - -In addition, you can specify how to override other aspects of -@var{parent} with @var{body}. The command @var{variant} -evaluates the forms in @var{body} after setting up all its usual -overrides, just before running the mode hooks. - -You can also specify @code{nil} for @var{parent}. This gives the new -mode no parent. Then @code{define-derived-mode} behaves as described -above, but, of course, omits all actions connected with @var{parent}. - -The argument @var{docstring} specifies the documentation string for -the new mode. @code{define-derived-mode} adds some general -information about the mode's hook, followed by the mode's keymap, at -the end of this docstring. If you omit @var{docstring}, -@code{define-derived-mode} generates a documentation string. - -The @var{keyword-args} are pairs of keywords and values. The values -are evaluated. The following keywords are currently supported: - -@table @code -@item :syntax-table -You can use this to explicitly specify a syntax table for the new -mode. If you specify a @code{nil} value, the new mode uses the same -syntax table as @var{parent}, or the standard syntax table if -@var{parent} is @code{nil}. (Note that this does @emph{not} follow -the convention used for non-keyword arguments that a @code{nil} value -is equivalent with not specifying the argument.) - -@item :abbrev-table -You can use this to explicitly specify an abbrev table for the new -mode. If you specify a @code{nil} value, the new mode uses the same -abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} -if @var{parent} is @code{nil}. (Again, a @code{nil} value is -@emph{not} equivalent to not specifying this keyword.) - -@item :group -If this is specified, the value should be the customization group for -this mode. (Not all major modes have one.) Only the (still -experimental and unadvertised) command @code{customize-mode} currently -uses this. @code{define-derived-mode} does @emph{not} automatically -define the specified customization group. -@end table - -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 - -Do not write an @code{interactive} spec in the definition; -@code{define-derived-mode} does that automatically. -@end defmac - -@node Generic Modes -@subsection Generic Modes -@cindex generic mode - - @dfn{Generic modes} are simple major modes with basic support for -comment syntax and Font Lock mode. To define a generic mode, use the -macro @code{define-generic-mode}. See the file @file{generic-x.el} -for some examples of the use of @code{define-generic-mode}. - -@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring -This macro defines a generic mode command named @var{mode} (a symbol, -not quoted). The optional argument @var{docstring} is the -documentation for the mode command. If you do not supply it, -@code{define-generic-mode} generates one by default. - -The argument @var{comment-list} is a list in which each element is -either a character, a string of one or two characters, or a cons cell. -A character or a string is set up in the mode's syntax table as a -``comment starter.'' If the entry is a cons cell, the @sc{car} is set -up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.'' -(Use @code{nil} for the latter if you want comments to end at the end -of the line.) Note that the syntax table mechanism has limitations -about what comment starters and enders are actually possible. -@xref{Syntax Tables}. - -The argument @var{keyword-list} is a list of keywords to highlight -with @code{font-lock-keyword-face}. Each keyword should be a string. -Meanwhile, @var{font-lock-list} is a list of additional expressions to -highlight. Each element of this list should have the same form as an -element of @code{font-lock-keywords}. @xref{Search-based -Fontification}. - -The argument @var{auto-mode-list} is a list of regular expressions to -add to the variable @code{auto-mode-alist}. They are added by the execution -of the @code{define-generic-mode} form, not by expanding the macro call. - -Finally, @var{function-list} is a list of functions for the mode -command to call for additional setup. It calls these functions just -before it runs the mode hook variable @code{@var{mode}-hook}. -@end defmac - -@node Mode Hooks -@subsection Mode Hooks - - Every major mode function should finish by running its mode hook and -the mode-independent normal hook @code{after-change-major-mode-hook}. -It does this by calling @code{run-mode-hooks}. If the major mode is a -derived mode, that is if it calls another major mode (the parent mode) -in its body, it should do this inside @code{delay-mode-hooks} so that -the parent won't run these hooks itself. Instead, the derived mode's -call to @code{run-mode-hooks} runs the parent's mode hook too. -@xref{Major Mode Conventions}. - - Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. -When user-implemented major modes have not been updated to use it, -they won't entirely follow these conventions: they may run the -parent's mode hook too early, or fail to run -@code{after-change-major-mode-hook}. If you encounter such a major -mode, please correct it to follow these conventions. - - When you defined a major mode using @code{define-derived-mode}, it -automatically makes sure these conventions are followed. If you -define a major mode ``by hand,'' not using @code{define-derived-mode}, -use the following functions to handle these conventions automatically. - -@defun run-mode-hooks &rest hookvars -Major modes should run their mode hook using this function. It is -similar to @code{run-hooks} (@pxref{Hooks}), but it also runs -@code{after-change-major-mode-hook}. - -When this function is called during the execution of a -@code{delay-mode-hooks} form, it does not run the hooks immediately. -Instead, it arranges for the next call to @code{run-mode-hooks} to run -them. -@end defun - -@defmac delay-mode-hooks body@dots{} -When one major mode command calls another, it should do so inside of -@code{delay-mode-hooks}. - -This macro executes @var{body}, but tells all @code{run-mode-hooks} -calls during the execution of @var{body} to delay running their hooks. -The hooks will actually run during the next call to -@code{run-mode-hooks} after the end of the @code{delay-mode-hooks} -construct. -@end defmac - -@defvar after-change-major-mode-hook -This is a normal hook run by @code{run-mode-hooks}. It is run at the -very end of every properly-written major mode function. -@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 the syntax table for this mode.} -(defvar text-mode-syntax-table - (let ((st (make-syntax-table))) - (modify-syntax-entry ?\" ". " st) - (modify-syntax-entry ?\\ ". " st) - ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. - (modify-syntax-entry ?' "w p" st) - st) - "Syntax table used while in `text-mode'.") -@end group - -;; @r{Create the keymap for this mode.} -@group -(defvar text-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\e\t" 'ispell-complete-word) - (define-key map "\es" 'center-line) - (define-key map "\eS" 'center-paragraph) - map) - "Keymap for `text-mode'. -Many other modes, such as Mail mode, Outline mode -and Indented Text mode, inherit all the commands -defined in this map.") -@end group -@end smallexample - - Here is how the actual mode command is defined now: - -@smallexample -@group -(define-derived-mode text-mode nil "Text" - "Major mode for editing text written for humans to read. -In this mode, paragraphs are delimited only by blank or white lines. -You can thus get the full benefit of adaptive filling - (see the variable `adaptive-fill-mode'). -\\@{text-mode-map@} -Turning on Text mode runs the normal hook `text-mode-hook'." -@end group -@group - (make-local-variable 'text-mode-variant) - (setq text-mode-variant t) - ;; @r{These two lines are a feature added recently.} - (set (make-local-variable 'require-final-newline) - mode-require-final-newline) - (set (make-local-variable 'indent-line-function) 'indent-relative)) -@end group -@end smallexample - -@noindent -(The last line is redundant nowadays, since @code{indent-relative} is -the default value, and we'll delete it in a future version.) - - Here is how it was defined formerly, before -@code{define-derived-mode} existed: - -@smallexample -@group -;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} -(defvar text-mode-abbrev-table nil - "Abbrev table used while in text mode.") -(define-abbrev-table 'text-mode-abbrev-table ()) -@end group - -@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) - (use-local-map text-mode-map) -@end group -@group - (setq local-abbrev-table text-mode-abbrev-table) - (set-syntax-table text-mode-syntax-table) -@end group -@group - ;; @r{These four lines are absent from the current version} - ;; @r{not because this is done some other way, but rather} - ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} - (make-local-variable 'paragraph-start) - (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter)) - (make-local-variable 'paragraph-separate) - (setq paragraph-separate paragraph-start) - (make-local-variable 'indent-line-function) - (setq indent-line-function 'indent-relative-maybe) -@end group -@group - (setq mode-name "Text") - (setq major-mode 'text-mode) - (run-mode-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 lisp-mode-abbrev-table nil "") -@end group - -@group -(defvar emacs-lisp-mode-syntax-table - (let ((table (make-syntax-table))) - (let ((i 0)) -@end group - -@group - ;; @r{Set syntax of chars up to @samp{0} to say they are} - ;; @r{part of symbol names but not words.} - ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)} - (while (< i ?0) - (modify-syntax-entry i "_ " table) - (setq i (1+ i))) - ;; @r{@dots{} similar code follows for other character ranges.} -@end group -@group - ;; @r{Then set the syntax codes for characters that are special in Lisp.} - (modify-syntax-entry ? " " table) - (modify-syntax-entry ?\t " " table) - (modify-syntax-entry ?\f " " table) - (modify-syntax-entry ?\n "> " table) -@end group -@group - ;; @r{Give CR the same syntax as newline, for selective-display.} - (modify-syntax-entry ?\^m "> " table) - (modify-syntax-entry ?\; "< " table) - (modify-syntax-entry ?` "' " table) - (modify-syntax-entry ?' "' " table) - (modify-syntax-entry ?, "' " table) -@end group -@group - ;; @r{@dots{}likewise for many other characters@dots{}} - (modify-syntax-entry ?\( "() " table) - (modify-syntax-entry ?\) ")( " table) - (modify-syntax-entry ?\[ "(] " table) - (modify-syntax-entry ?\] ")[ " table)) - table)) -@end group -@group -;; @r{Create an abbrev table for lisp-mode.} -(define-abbrev-table 'lisp-mode-abbrev-table ()) -@end group -@end smallexample - - The three modes for Lisp share much of their code. For instance, -each calls the following function to set various variables: - -@smallexample -@group -(defun lisp-mode-variables (lisp-syntax) - (when lisp-syntax - (set-syntax-table lisp-mode-syntax-table)) - (setq local-abbrev-table lisp-mode-abbrev-table) - @dots{} -@end group -@end smallexample - - In Lisp and most programming languages, we want the paragraph -commands to treat only blank lines as paragraph separators. And the -modes should understand the Lisp conventions for comments. The rest of -@code{lisp-mode-variables} sets this up: - -@smallexample -@group - (make-local-variable 'paragraph-start) - (setq paragraph-start (concat page-delimiter "\\|$" )) - (make-local-variable 'paragraph-separate) - (setq paragraph-separate paragraph-start) - @dots{} -@end group -@group - (make-local-variable 'comment-indent-function) - (setq comment-indent-function 'lisp-comment-indent)) - @dots{} -@end group -@end smallexample - - Each of the different Lisp modes has a slightly different keymap. For -example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other -Lisp modes do not. However, all Lisp modes have some commands in -common. The following code sets up the common commands: - -@smallexample -@group -(defvar shared-lisp-mode-map () - "Keymap for commands shared by all sorts of Lisp modes.") - -;; @r{Putting this @code{if} after the @code{defvar} is an older style.} -(if shared-lisp-mode-map - () - (setq shared-lisp-mode-map (make-sparse-keymap)) - (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp) - (define-key shared-lisp-mode-map "\177" - 'backward-delete-char-untabify)) -@end group -@end smallexample - -@noindent -And here is the code to set up the keymap for Lisp mode: - -@smallexample -@group -(defvar lisp-mode-map () - "Keymap for ordinary Lisp mode...") - -(if lisp-mode-map - () - (setq lisp-mode-map (make-sparse-keymap)) - (set-keymap-parent lisp-mode-map shared-lisp-mode-map) - (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun) - (define-key lisp-mode-map "\C-c\C-z" 'run-lisp)) -@end group -@end smallexample - - Finally, here is the complete major mode function definition for -Lisp mode. - -@smallexample -@group -(defun lisp-mode () - "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. -Commands: -Delete converts tabs to spaces as it moves back. -Blank lines separate paragraphs. Semicolons start comments. -\\@{lisp-mode-map@} -Note that `run-lisp' may be used either to start an inferior Lisp job -or to switch back to an existing one. -@end group - -@group -Entry to this mode calls the value of `lisp-mode-hook' -if that value is non-nil." - (interactive) - (kill-all-local-variables) -@end group -@group - (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.} - (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}} - ; @r{finds out what to describe.} - (setq mode-name "Lisp") ; @r{This goes into the mode line.} - (lisp-mode-variables t) ; @r{This defines various variables.} - (make-local-variable 'comment-start-skip) - (setq comment-start-skip - "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") - (make-local-variable 'font-lock-keywords-case-fold-search) - (setq font-lock-keywords-case-fold-search t) -@end group -@group - (setq imenu-case-fold-search t) - (set-syntax-table lisp-mode-syntax-table) - (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} - ; @r{hook to customize the mode.} -@end group -@end smallexample - -@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 -would be unwieldy. - - A minor mode is not usually meant as a variation of a single major mode. -Usually they are general and can apply to many major modes. For -example, Auto Fill mode works with 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. A minor mode should be able to have its -desired effect regardless of the major mode and regardless of the other -minor modes in effect. - - 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 than it used to be. - -@defvar minor-mode-list -The value of this variable is a list of all minor mode commands. -@end defvar - -@menu -* 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. -@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, the use of a hook at the end of -the initialization function, and the use of keymaps and other tables. - - In addition, there are several conventions that are specific to -minor modes. (The easiest way to follow all the conventions is to use -the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.) - -@itemize @bullet -@item -@cindex mode variable -Make a variable whose name ends in @samp{-mode} to control the minor -mode. We call this the @dfn{mode variable}. The minor mode command -should set this variable (@code{nil} to disable; anything else to -enable). - -If possible, implement the mode so that setting the variable -automatically enables or disables the mode. Then the minor mode command -does not need to do anything except set the 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). It should turn the mode on if the argument is a -positive integer, the symbol @code{t}, or a list whose @sc{car} is one -of those. It should turn the mode off if the argument is a negative -integer or zero, the symbol @code{-}, or a list whose @sc{car} is a -negative integer or zero. The meaning of other arguments is not -specified. - -Here is an example taken from the definition of @code{transient-mark-mode}. -It shows the use of @code{transient-mark-mode} as a variable that enables or -disables the mode's behavior, and also shows the proper way to toggle, -enable or disable the minor mode based on the raw prefix argument value. - -@smallexample -@group -(setq transient-mark-mode - (if (null arg) (not transient-mark-mode) - (> (prefix-numeric-value arg) 0))) -@end group -@end smallexample - -@item -Add an element to @code{minor-mode-alist} for each minor mode -(@pxref{Definition of minor-mode-alist}), if you want to indicate the -minor mode in the mode line. 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 enabling 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 -(unless (assq 'leif-mode minor-mode-alist) - (setq minor-mode-alist - (cons '(leif-mode " Leif") minor-mode-alist))) -@end group -@end smallexample - -@noindent -or like this, using @code{add-to-list} (@pxref{List Variables}): - -@smallexample -@group -(add-to-list 'minor-mode-alist '(leif-mode " Leif")) -@end group -@end smallexample -@end itemize - - Global minor modes distributed with Emacs should if possible support -enabling and disabling via Custom (@pxref{Customization}). To do this, -the first step is to define the mode variable with @code{defcustom}, and -specify @code{:type boolean}. - - If just setting the variable is not sufficient to enable the mode, you -should also specify a @code{:set} method which enables the mode by -invoking the mode command. Note in the variable's documentation string that -setting the variable other than via Custom may not take effect. - - Also mark the definition with an autoload cookie (@pxref{autoload cookie}), -and specify a @code{:require} so that customizing the variable will load -the library that defines the mode. This will copy suitable definitions -into @file{loaddefs.el} so that users can use @code{customize-option} to -enable the mode. For example: - -@smallexample -@group - -;;;###autoload -(defcustom msb-mode nil - "Toggle msb-mode. -Setting this variable directly does not take effect; -use either \\[customize] or the function `msb-mode'." - :set 'custom-set-minor-mode - :initialize 'custom-initialize-default - :version "20.4" - :type 'boolean - :group 'msb - :require 'msb) -@end group -@end smallexample - -@node Keymaps and Minor Modes -@subsection Keymaps and Minor Modes - - Each minor mode can have its own keymap, which is active when the mode -is enabled. To set up a keymap for a minor mode, add an element to the -alist @code{minor-mode-map-alist}. @xref{Definition of 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.) - -The key sequences bound in a minor mode should consist of @kbd{C-c} -followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other -punctuation characters are reserved for major modes.) - -@node Defining Minor Modes -@subsection Defining Minor Modes - - The macro @code{define-minor-mode} offers a convenient way of -implementing a mode in one self-contained definition. - -@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} -This macro defines a new minor mode whose name is @var{mode} (a -symbol). It defines a command named @var{mode} to toggle the minor -mode, with @var{doc} as its documentation string. It also defines a -variable named @var{mode}, which is set to @code{t} or @code{nil} by -enabling or disabling the mode. The variable is initialized to -@var{init-value}. Except in unusual circumstances (see below), this -value must be @code{nil}. - -The string @var{lighter} says what to display in the mode line -when the mode is enabled; if it is @code{nil}, the mode is not displayed -in the mode line. - -The optional argument @var{keymap} specifies the keymap for the minor mode. -It can be a variable name, whose value is the keymap, or it can be an alist -specifying bindings in this form: - -@example -(@var{key-sequence} . @var{definition}) -@end example - -The above three arguments @var{init-value}, @var{lighter}, and -@var{keymap} can be (partially) omitted when @var{keyword-args} are -used. The @var{keyword-args} consist of keywords followed by -corresponding values. A few keywords have special meanings: - -@table @code -@item :group @var{group} -Custom group name to use in all generated @code{defcustom} forms. -Defaults to @var{mode} without the possible trailing @samp{-mode}. -@strong{Warning:} don't use this default group name unless you have -written a @code{defgroup} to define that group properly. @xref{Group -Definitions}. - -@item :global @var{global} -If non-@code{nil}, this specifies that the minor mode should be global -rather than buffer-local. It defaults to @code{nil}. - -One of the effects of making a minor mode global is that the -@var{mode} variable becomes a customization variable. Toggling it -through the Custom interface turns the mode on and off, and its value -can be saved for future Emacs sessions (@pxref{Saving -Customizations,,, emacs, The GNU Emacs Manual}. For the saved -variable to work, you should ensure that the @code{define-minor-mode} -form is evaluated each time Emacs starts; for packages that are not -part of Emacs, the easiest way to do this is to specify a -@code{:require} keyword. - -@item :init-value @var{init-value} -This is equivalent to specifying @var{init-value} positionally. - -@item :lighter @var{lighter} -This is equivalent to specifying @var{lighter} positionally. - -@item :keymap @var{keymap} -This is equivalent to specifying @var{keymap} positionally. -@end table - -Any other keyword arguments are passed directly to the -@code{defcustom} generated for the variable @var{mode}. - -The command named @var{mode} first performs the standard actions such -as setting the variable named @var{mode} and then executes the -@var{body} forms, if any. It finishes by running the mode hook -variable @code{@var{mode}-hook}. -@end defmac - - The initial value must be @code{nil} except in cases where (1) the -mode is preloaded in Emacs, or (2) it is painless for loading to -enable the mode even though the user did not request it. For -instance, if the mode has no effect unless something else is enabled, -and will always be loaded by that time, enabling it by default is -harmless. But these are unusual circumstances. Normally, the -initial value must be @code{nil}. - -@findex easy-mmode-define-minor-mode - The name @code{easy-mmode-define-minor-mode} is an alias -for this macro. - - Here is an example of using @code{define-minor-mode}: - -@smallexample -(define-minor-mode hungry-mode - "Toggle Hungry mode. -With no argument, this command toggles the mode. -Non-null prefix argument turns on the mode. -Null prefix argument turns off the mode. - -When Hungry mode is enabled, the control delete key -gobbles all preceding whitespace except the last. -See the command \\[hungry-electric-delete]." - ;; The initial value. - nil - ;; The indicator for the mode line. - " Hungry" - ;; The minor mode bindings. - '(("\C-\^?" . hungry-electric-delete)) - :group 'hunger) -@end smallexample - -@noindent -This defines a minor mode named ``Hungry mode,'' a command named -@code{hungry-mode} to toggle it, a variable named @code{hungry-mode} -which indicates whether the mode is enabled, and a variable named -@code{hungry-mode-map} which holds the keymap that is active when the -mode is enabled. It initializes the keymap with a key binding for -@kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into -custom group @code{hunger}. There are no @var{body} forms---many -minor modes don't need any. - - Here's an equivalent way to write it: - -@smallexample -(define-minor-mode hungry-mode - "Toggle Hungry mode. -With no argument, this command toggles the mode. -Non-null prefix argument turns on the mode. -Null prefix argument turns off the mode. - -When Hungry mode is enabled, the control delete key -gobbles all preceding whitespace except the last. -See the command \\[hungry-electric-delete]." - ;; The initial value. - :init-value nil - ;; The indicator for the mode line. - :lighter " Hungry" - ;; The minor mode bindings. - :keymap - '(("\C-\^?" . hungry-electric-delete) - ("\C-\M-\^?" - . (lambda () - (interactive) - (hungry-electric-delete t)))) - :group 'hunger) -@end smallexample - -@defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{} -This defines a global toggle named @var{global-mode} whose meaning is -to enable or disable the buffer-local minor mode @var{mode} in all -buffers. To turn on the minor mode in a buffer, it uses the function -@var{turn-on}; to turn off the minor mode, it calls @code{mode} with -@minus{}1 as argument. - -Globally enabling the mode also affects buffers subsequently created -by visiting files, and buffers that use a major mode other than -Fundamental mode; but it does not detect the creation of a new buffer -in Fundamental mode. - -This defines the customization option @var{global-mode} (@pxref{Customization}), -which can be toggled in the Custom interface to turn the minor mode on -and off. As with @code{define-minor-mode}, you should ensure that the -@code{define-globalized-minor-mode} form is evaluated each time Emacs -starts, for example by providing a @code{:require} keyword. - -Use @code{:group @var{group}} in @var{keyword-args} to specify the -custom group for the mode variable of the global minor mode. -@end defmac - -@node Mode Line Format -@section Mode-Line Format -@cindex mode line - - Each Emacs window (aside from minibuffer windows) typically has a mode -line at the bottom, 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 major and minor modes. A window can also have a @dfn{header -line}, which is much like the mode line but appears at the top of the -window. - - This section describes how to control the contents of the mode line -and header line. We include it in this chapter because much of the -information displayed in the mode line relates to the enabled major and -minor modes. - -@menu -* Base: Mode Line Basics. Basic ideas of mode line control. -* Data: Mode Line Data. The data structure that controls the mode line. -* Top: Mode Line Top. The top level variable, mode-line-format. -* 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. -@end menu - -@node Mode Line Basics -@subsection Mode Line Basics - - @code{mode-line-format} is a buffer-local variable that holds a -@dfn{mode line construct}, a kind of template, which controls what is -displayed on the mode line of the current buffer. The value of -@code{header-line-format} specifies the buffer's header line in the -same way. All windows for the same buffer use the same -@code{mode-line-format} and @code{header-line-format}. - - For efficiency, Emacs does not continuously recompute the mode -line and header line of a window. It does so when circumstances -appear to call for it---for instance, if you change the window -configuration, switch buffers, narrow or widen the buffer, scroll, or -change the buffer's modification status. If you modify any of the -variables referenced by @code{mode-line-format} (@pxref{Mode Line -Variables}), or any other variables and data structures that affect -how text is displayed (@pxref{Display}), you may want to force an -update of the mode line so as to display the new information or -display it in the new way. - -@defun force-mode-line-update &optional all -Force redisplay of the current buffer's mode line and header line. -The next redisplay will update the mode line and header line based on -the latest values of all relevant variables. With optional -non-@code{nil} @var{all}, force redisplay of all mode lines and header -lines. - -This function also forces recomputation of the menu bar menus -and the frame title. -@end defun - - The selected window's mode line is usually displayed in a different -color using the face @code{mode-line}. Other windows' mode lines -appear in the face @code{mode-line-inactive} instead. @xref{Faces}. - -@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 called a -@dfn{mode-line construct}, made up of lists, strings, symbols, and -numbers kept in buffer-local variables. Each data type has a specific -meaning for the mode-line appearance, as described below. The same -data structure is used for constructing frame titles (@pxref{Frame -Titles}) and header lines (@pxref{Header Lines}). - - A mode-line construct may be as simple as a fixed string of text, -but it usually specifies how to combine fixed strings with variables' -values to construct the text. Many of these variables are themselves -defined to have mode-line constructs as their values. - - Here are the meanings of various data types as mode-line constructs: - -@table @code -@cindex percent symbol in mode line -@item @var{string} -A string as a mode-line construct appears verbatim except for -@dfn{@code{%}-constructs} in it. These stand for substitution of -other data; see @ref{%-Constructs}. - -If parts of the string have @code{face} properties, they control -display of the text just as they would text in the buffer. Any -characters which have no @code{face} properties are displayed, by -default, in the face @code{mode-line} or @code{mode-line-inactive} -(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The -@code{help-echo} and @code{local-map} properties in @var{string} have -special meanings. @xref{Properties in Mode}. - -@item @var{symbol} -A symbol as a mode-line construct stands for its value. The value of -@var{symbol} is used as a mode-line construct, in place of @var{symbol}. -However, the symbols @code{t} and @code{nil} are ignored, as is any -symbol whose value is void. - -There is one exception: if the value of @var{symbol} is a string, it is -displayed verbatim: the @code{%}-constructs are not recognized. - -Unless @var{symbol} is marked as ``risky'' (i.e., it has a -non-@code{nil} @code{risky-local-variable} property), all text -properties specified in @var{symbol}'s value are ignored. This -includes the text properties of strings in @var{symbol}'s value, as -well as all @code{:eval} and @code{:propertize} forms in it. (The -reason for this is security: non-risky variables could be set -automatically from file variables without prompting the user.) - -@item (@var{string} @var{rest}@dots{}) -@itemx (@var{list} @var{rest}@dots{}) -A list whose first element is a string or list means to process all the -elements recursively and concatenate the results. This is the most -common form of mode-line construct. - -@item (:eval @var{form}) -A list whose first element is the symbol @code{:eval} says to evaluate -@var{form}, and use the result as a string to display. Make sure this -evaluation cannot load any files, as doing so could cause infinite -recursion. - -@item (:propertize @var{elt} @var{props}@dots{}) -A list whose first element is the symbol @code{:propertize} says to -process the mode-line construct @var{elt} recursively, then add the text -properties specified by @var{props} to the result. The argument -@var{props} should consist of zero or more pairs @var{text-property} -@var{value}. (This feature is new as of Emacs 22.1.) - -@item (@var{symbol} @var{then} @var{else}) -A list whose first element is a symbol that is not a keyword specifies -a conditional. Its meaning depends on the value of @var{symbol}. If -@var{symbol} has a non-@code{nil} value, the second element, -@var{then}, is processed recursively as a mode-line element. -Otherwise, the third element, @var{else}, is processed recursively. -You may omit @var{else}; then the mode-line element displays nothing -if the value of @var{symbol} is @code{nil} or void. - -@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. When @var{width} is positive, the result is -space filled on the right if its width is less than @var{width}. When -@var{width} is negative, the result is truncated on the right to -@minus{}@var{width} columns if its width exceeds @minus{}@var{width}. - -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 - -@node Mode Line Top -@subsection The Top Level of Mode Line Control - - The variable in overall control of the mode line is -@code{mode-line-format}. - -@defvar mode-line-format -The value of this variable is a mode-line construct that controls the -contents of the mode-line. It is always buffer-local in all buffers. - -If you set this variable to @code{nil} in a buffer, that buffer does -not have a mode line. (A window that is just one line tall never -displays a mode line.) -@end defvar - - The default value of @code{mode-line-format} is designed to use the -values of other variables such as @code{mode-line-position} and -@code{mode-line-modes} (which in turn incorporates the values of the -variables @code{mode-name} and @code{minor-mode-alist}). Very few -modes need to alter @code{mode-line-format} itself. For most -purposes, it is sufficient to alter some of the variables that -@code{mode-line-format} either directly or indirectly refers to. - - If you do alter @code{mode-line-format} itself, the new value should -use the same variables that appear in the default value (@pxref{Mode -Line Variables}), rather than duplicating their contents or displaying -the information in another fashion. This way, customizations made by -the user or by Lisp programs (such as @code{display-time} and major -modes) via changes to those variables remain effective. - - Here is an example of a @code{mode-line-format} that might be -useful for @code{shell-mode}, since it contains the host name and default -directory. - -@example -@group -(setq mode-line-format - (list "-" - 'mode-line-mule-info - 'mode-line-modified - 'mode-line-frame-identification - "%b--" -@end group -@group - ;; @r{Note that this is evaluated while making the list.} - ;; @r{It makes a mode-line construct which is just a string.} - (getenv "HOST") -@end group - ":" - 'default-directory - " " - 'global-mode-string - " %[(" - '(:eval (mode-line-mode-name)) - 'mode-line-process - 'minor-mode-alist - "%n" - ")%]--" -@group - '(which-func-mode ("" which-func-format "--")) - '(line-number-mode "L%l--") - '(column-number-mode "C%c--") - '(-3 "%p") - "-%-")) -@end group -@end example - -@noindent -(The variables @code{line-number-mode}, @code{column-number-mode} -and @code{which-func-mode} enable particular minor modes; as usual, -these variable names are also the minor mode command names.) - -@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}'s value were changed to use them. However, -various parts of Emacs set these variables on the understanding that -they will control parts of the mode line; therefore, practically -speaking, it is essential for the mode line to use them. - -@defvar mode-line-mule-info -This variable holds the value of the mode-line construct that displays -information about the language environment, buffer coding system, and -current input method. @xref{Non-ASCII Characters}. -@end defvar - -@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, @samp{%%} if the -buffer is read only, and @samp{%*} if the buffer is read only and -modified. - -Changing this variable does not force an update of the mode line. -@end defvar - -@defvar mode-line-frame-identification -This variable identifies the current frame. The default value is -@code{" "} if you are using a window system which can show multiple -frames, or @code{"-%F "} on an ordinary terminal which shows only one -frame at a time. -@end defvar - -@defvar mode-line-buffer-identification -This variable identifies the buffer being displayed in the window. Its -default value is @code{("%12b")}, which displays the buffer name, padded -with spaces to at least 12 columns. -@end defvar - -@defvar mode-line-position -This variable indicates the position in the buffer. Here is a -simplified version of its default value. The actual default value -also specifies addition of the @code{help-echo} text property. - -@example -@group -((-3 "%p") - (size-indication-mode (8 " of %I")) -@end group -@group - (line-number-mode - ((column-number-mode - (10 " (%l,%c)") - (6 " L%l"))) - ((column-number-mode - (5 " C%c"))))) -@end group -@end example - -This means that @code{mode-line-position} displays at least the buffer -percentage and possibly the buffer size, the line number and the column -number. -@end defvar - -@defvar vc-mode -The variable @code{vc-mode}, buffer-local in each buffer, records -whether the buffer's visited file is maintained with version control, -and, if so, which kind. Its value is a string that appears in the mode -line, or @code{nil} for no version control. -@end defvar - -@defvar mode-line-modes -This variable displays the buffer's major and minor modes. Here is a -simplified version of its default value. The real default value also -specifies addition of text properties. - -@example -@group -("%[(" mode-name - mode-line-process minor-mode-alist - "%n" ")%]--") -@end group -@end example - -So @code{mode-line-modes} normally also displays the recursive editing -level, information on the process status and whether narrowing is in -effect. -@end defvar - - The following three variables are used in @code{mode-line-modes}: - -@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 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 minor-mode-alist -@anchor{Definition of 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. - -@code{minor-mode-alist} itself is not buffer-local. Each variable -mentioned in the alist should be buffer-local if its minor mode can be -enabled separately in each buffer. -@end defvar - -@defvar global-mode-string -This variable holds a mode-line spec that, by default, appears in the -mode line just after the @code{which-func-mode} minor mode if set, -else after @code{mode-line-modes}. 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 that is obsolete, since the variable is -included in the mode line from @code{mode-line-format}. -@end defvar - - The variable @code{default-mode-line-format} is where -@code{mode-line-format} usually gets its value: - -@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)}. - -Here is a simplified version of the default value of -@code{default-mode-line-format}. The real default value also -specifies addition of text properties. - -@example -@group -("-" - mode-line-mule-info - mode-line-modified - mode-line-frame-identification - mode-line-buffer-identification -@end group - " " - mode-line-position - (vc-mode vc-mode) - " " -@group - mode-line-modes - (which-func-mode ("" which-func-format "--")) - (global-mode-string ("--" global-mode-string)) - "-%-") -@end group -@end example -@end defvar - -@node %-Constructs -@subsection @code{%}-Constructs in the Mode Line - - Strings used as mode-line constructs can use certain -@code{%}-constructs to substitute various kinds of data. Here is a -list of the defined @code{%}-constructs, and what they mean. In any -construct except @samp{%%}, you can add a decimal integer after the -@samp{%} to specify a minimum field width. If the width is less, the -field is padded with spaces to the right. - -@table @code -@item %b -The current buffer name, obtained with the @code{buffer-name} function. -@xref{Buffer Names}. - -@item %c -The current column number of point. - -@item %e -When Emacs is nearly out of memory for Lisp objects, a brief message -saying so. Otherwise, this is empty. - -@item %f -The visited file name, obtained with the @code{buffer-file-name} -function. @xref{Buffer File Name}. - -@item %F -The title (only on a window system) or the name of the selected frame. -@xref{Basic Parameters}. - -@item %i -The size of the accessible part of the current buffer; basically -@code{(- (point-max) (point-min))}. - -@item %I -Like @samp{%i}, but the size is printed in a more readable way by using -@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to -abbreviate. - -@item %l -The current line number of point, counting within the accessible portion -of the buffer. - -@item %n -@samp{Narrow} when narrowing is in effect; nothing otherwise (see -@code{narrow-to-region} in @ref{Narrowing}). - -@item %p -The percentage of the buffer text above the @strong{top} of window, or -@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default -mode-line specification truncates this to three characters. - -@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 %s -The status of the subprocess belonging to the current buffer, obtained with -@code{process-status}. @xref{Process Information}. - -@item %t -Whether the visited file is a text file or a binary file. This is a -meaningful distinction only on certain operating systems (@pxref{MS-DOS -File Types}). - -@item %z -The mnemonics of keyboard, terminal, and buffer coding systems. - -@item %Z -Like @samp{%z}, but including the end-of-line format. - -@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 (see @code{buffer-modified-p}); @* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{-} otherwise. This differs from @samp{%*} only for a modified -read-only buffer. @xref{Buffer Modification}. - -@item %& -@samp{*} if the buffer is modified, and @samp{-} otherwise. - -@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 %- -Dashes sufficient to fill the remainder of the mode line. - -@item %% -The character @samp{%}---this is how to include a literal @samp{%} in a -string in which @code{%}-constructs are allowed. -@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}. -@end table - -@node Properties in Mode -@subsection Properties in the Mode Line -@cindex text properties in the mode line - - Certain text properties are meaningful in the -mode line. The @code{face} property affects the appearance of text; the -@code{help-echo} property associates help strings with the text, and -@code{local-map} can make the text mouse-sensitive. - - There are four ways to specify text properties for text in the mode -line: - -@enumerate -@item -Put a string with a text property directly into the mode-line data -structure. - -@item -Put a text property on a mode-line %-construct such as @samp{%12b}; then -the expansion of the %-construct will have that same text property. - -@item -Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to -give @var{elt} a text property specified by @var{props}. - -@item -Use a list containing @code{:eval @var{form}} in the mode-line data -structure, and make @var{form} evaluate to a string that has a text -property. -@end enumerate - - You can use the @code{local-map} property to specify a keymap. This -keymap only takes real effect for mouse clicks; binding character keys -and function keys to it has no effect, since it is impossible to move -point into the mode line. - - When the mode line refers to a variable which does not have a -non-@code{nil} @code{risky-local-variable} property, any text -properties given or specified within that variable's values are -ignored. This is because such properties could otherwise specify -functions to be called, and those functions could come from file -local variables. - -@node Header Lines -@subsection Window Header Lines -@cindex header line (of a window) -@cindex window header line - - A window can have a @dfn{header line} at the -top, just as it can have a mode line at the bottom. The header line -feature works just like the mode-line feature, except that it's -controlled by different variables. - -@defvar header-line-format -This variable, local in every buffer, specifies how to display the -header line, for windows displaying the buffer. The format of the value -is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). -@end defvar - -@defvar default-header-line-format -This variable holds the default @code{header-line-format} for buffers -that do not override it. This is the same as @code{(default-value -'header-line-format)}. - -It is normally @code{nil}, so that ordinary buffers have no header line. -@end defvar - - A window that is just one line tall never displays a header line. A -window that is two lines tall cannot display both a mode line and a -header line at once; if it has a mode line, then it does not display a -header line. - -@node Emulating Mode Line -@subsection Emulating Mode-Line Formatting - - You can use the function @code{format-mode-line} to compute -the text that would appear in a mode line or header line -based on a certain mode-line specification. - -@defun format-mode-line format &optional face window buffer -This function formats a line of text according to @var{format} as if -it were generating the mode line for @var{window}, but instead of -displaying the text in the mode line or the header line, it returns -the text as a string. The argument @var{window} defaults to the -selected window. If @var{buffer} is non-@code{nil}, all the -information used is taken from @var{buffer}; by default, it comes from -@var{window}'s buffer. - -The value string normally has text properties that correspond to the -faces, keymaps, etc., that the mode line would have. And any character -for which no @code{face} property is specified gets a default -value which is usually @var{face}. (If @var{face} is @code{t}, -that stands for either @code{mode-line} if @var{window} is selected, -otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or -omitted, that stands for no face property.) - -However, if @var{face} is an integer, the value has no text properties. - -For example, @code{(format-mode-line header-line-format)} returns the -text that would appear in the selected window's header line (@code{""} -if it has no header line). @code{(format-mode-line header-line-format -'header-line)} returns the same text, with each character -carrying the face that it will have in the header line itself. -@end defun - -@node Imenu -@section Imenu - -@cindex Imenu - @dfn{Imenu} is a feature that lets users select a definition or -section in the buffer, from a menu which lists all of them, to go -directly to that location in the buffer. Imenu works by constructing -a buffer index which lists the names and buffer positions of the -definitions, or other named portions of the buffer; then the user can -choose one of them and move point to it. Major modes can add a menu -bar item to use Imenu using @code{imenu-add-to-menubar}. - -@defun imenu-add-to-menubar name -This function defines a local menu bar item named @var{name} -to run Imenu. -@end defun - - The user-level commands for using Imenu are described in the Emacs -Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section -explains how to customize Imenu's method of finding definitions or -buffer portions for a particular major mode. - - The usual and simplest way is to set the variable -@code{imenu-generic-expression}: - -@defvar imenu-generic-expression -This variable, if non-@code{nil}, is a list that specifies regular -expressions for finding definitions for Imenu. Simple elements of -@code{imenu-generic-expression} look like this: - -@example -(@var{menu-title} @var{regexp} @var{index}) -@end example - -Here, if @var{menu-title} is non-@code{nil}, it says that the matches -for this element should go in a submenu of the buffer index; -@var{menu-title} itself specifies the name for the submenu. If -@var{menu-title} is @code{nil}, the matches for this element go directly -in the top level of the buffer index. - -The second item in the list, @var{regexp}, is a regular expression -(@pxref{Regular Expressions}); anything in the buffer that it matches -is considered a definition, something to mention in the buffer index. -The third item, @var{index}, is a non-negative integer that indicates -which subexpression in @var{regexp} matches the definition's name. - -An element can also look like this: - -@example -(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{}) -@end example - -Each match for this element creates an index item, and when the index -item is selected by the user, it calls @var{function} with arguments -consisting of the item name, the buffer position, and @var{arguments}. - -For Emacs Lisp mode, @code{imenu-generic-expression} could look like -this: - -@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+] -@example -@group -((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2) -@end group -@group - ("*Vars*" "^\\s-*(def\\(var\\|const\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2) -@end group -@group - ("*Types*" - "^\\s-*\ -(def\\(type\\|struct\\|class\\|ine-condition\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2)) -@end group -@end example - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-case-fold-search -This variable controls whether matching against the regular -expressions in the value of @code{imenu-generic-expression} is -case-sensitive: @code{t}, the default, means matching should ignore -case. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-syntax-alist -This variable is an alist of syntax table modifiers to use while -processing @code{imenu-generic-expression}, to override the syntax table -of the current buffer. Each element should have this form: - -@example -(@var{characters} . @var{syntax-description}) -@end example - -The @sc{car}, @var{characters}, can be either a character or a string. -The element says to give that character or characters the syntax -specified by @var{syntax-description}, which is passed to -@code{modify-syntax-entry} (@pxref{Syntax Table Functions}). - -This feature is typically used to give word syntax to characters which -normally have symbol syntax, and thus to simplify -@code{imenu-generic-expression} and speed up matching. -For example, Fortran mode uses it this way: - -@example -(setq imenu-syntax-alist '(("_$" . "w"))) -@end example - -The @code{imenu-generic-expression} regular expressions can then use -@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this -technique may be inconvenient when the mode needs to limit the initial -character of a name to a smaller set of characters than are allowed in -the rest of a name. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - - Another way to customize Imenu for a major mode is to set the -variables @code{imenu-prev-index-position-function} and -@code{imenu-extract-index-name-function}: - -@defvar imenu-prev-index-position-function -If this variable is non-@code{nil}, its value should be a function that -finds the next ``definition'' to put in the buffer index, scanning -backward in the buffer from point. It should return @code{nil} if it -doesn't find another ``definition'' before point. Otherwise it should -leave point at the place it finds a ``definition'' and return any -non-@code{nil} value. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-extract-index-name-function -If this variable is non-@code{nil}, its value should be a function to -return the name for a definition, assuming point is in that definition -as the @code{imenu-prev-index-position-function} function would leave -it. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - - The last way to customize Imenu for a major mode is to set the -variable @code{imenu-create-index-function}: - -@defvar imenu-create-index-function -This variable specifies the function to use for creating a buffer -index. The function should take no arguments, and return an index -alist for the current buffer. It is called within -@code{save-excursion}, so where it leaves point makes no difference. - -The index alist can have three types of elements. Simple elements -look like this: - -@example -(@var{index-name} . @var{index-position}) -@end example - -Selecting a simple element has the effect of moving to position -@var{index-position} in the buffer. Special elements look like this: - -@example -(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{}) -@end example - -Selecting a special element performs: - -@example -(funcall @var{function} - @var{index-name} @var{index-position} @var{arguments}@dots{}) -@end example - -A nested sub-alist element looks like this: - -@example -(@var{menu-title} @var{sub-alist}) -@end example - -It creates the submenu @var{menu-title} specified by @var{sub-alist}. - -The default value of @code{imenu-create-index-function} is -@code{imenu-default-create-index-function}. This function calls the -value of @code{imenu-prev-index-position-function} and the value of -@code{imenu-extract-index-name-function} to produce the index alist. -However, if either of these two variables is @code{nil}, the default -function uses @code{imenu-generic-expression} instead. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@node Font Lock Mode -@section Font Lock Mode -@cindex Font Lock mode - - @dfn{Font Lock mode} is a feature that automatically attaches -@code{face} properties to certain parts of the buffer based on their -syntactic role. How it parses the buffer depends on the major mode; -most major modes define syntactic criteria for which faces to use in -which contexts. This section explains how to customize Font Lock for a -particular major mode. - - Font Lock mode finds text to highlight in two ways: through -syntactic parsing based on the syntax table, and through searching -(usually for regular expressions). Syntactic fontification happens -first; it finds comments and string constants and highlights them. -Search-based fontification happens second. - -@menu -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Setting Syntax Properties:: Defining character syntax based on context - using the Font Lock mechanism. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. -@end menu - -@node Font Lock Basics -@subsection Font Lock Basics - - There are several variables that control how Font Lock mode highlights -text. But major modes should not set any of these variables directly. -Instead, they should set @code{font-lock-defaults} as a buffer-local -variable. The value assigned to this variable is used, if and when Font -Lock mode is enabled, to set all the other variables. - -@defvar font-lock-defaults -This variable is set by major modes, as a buffer-local variable, to -specify how to fontify text in that mode. It automatically becomes -buffer-local when you set it. If its value is @code{nil}, Font-Lock -mode does no highlighting, and you can use the @samp{Faces} menu -(under @samp{Edit} and then @samp{Text Properties} in the menu bar) to -assign faces explicitly to text in the buffer. - -If non-@code{nil}, the value should look like this: - -@example -(@var{keywords} [@var{keywords-only} [@var{case-fold} - [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]]) -@end example - -The first element, @var{keywords}, indirectly specifies the value of -@code{font-lock-keywords} which directs search-based fontification. -It can be a symbol, a variable or a function whose value is the list -to use for @code{font-lock-keywords}. It can also be a list of -several such symbols, one for each possible level of fontification. -The first symbol specifies how to do level 1 fontification, the second -symbol how to do level 2, and so on. @xref{Levels of Font Lock}. - -The second element, @var{keywords-only}, specifies the value of the -variable @code{font-lock-keywords-only}. If this is omitted or -@code{nil}, syntactic fontification (of strings and comments) is also -performed. If this is non-@code{nil}, such fontification is not -performed. @xref{Syntactic Font Lock}. - -The third element, @var{case-fold}, specifies the value of -@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil}, -Font Lock mode ignores case when searching as directed by -@code{font-lock-keywords}. - -If the fourth element, @var{syntax-alist}, is non-@code{nil}, it -should be a list of cons cells of the form @code{(@var{char-or-string} -. @var{string})}. These are used to set up a syntax table for -syntactic fontification (@pxref{Syntax Table Functions}). The -resulting syntax table is stored in @code{font-lock-syntax-table}. - -The fifth element, @var{syntax-begin}, specifies the value of -@code{font-lock-beginning-of-syntax-function}. We recommend setting -this variable to @code{nil} and using @code{syntax-begin-function} -instead. - -All the remaining elements (if any) are collectively called -@var{other-vars}. Each of these elements should have the form -@code{(@var{variable} . @var{value})}---which means, make -@var{variable} buffer-local and then set it to @var{value}. You can -use these @var{other-vars} to set other variables that affect -fontification, aside from those you can control with the first five -elements. @xref{Other Font Lock Variables}. -@end defvar - - If your mode fontifies text explicitly by adding -@code{font-lock-face} properties, it can specify @code{(nil t)} for -@code{font-lock-defaults} to turn off all automatic fontification. -However, this is not required; it is possible to fontify some things -using @code{font-lock-face} properties and set up automatic -fontification for other parts of the text. - -@node Search-based Fontification -@subsection Search-based Fontification - - The most important variable for customizing Font Lock mode is -@code{font-lock-keywords}. It specifies the search criteria for -search-based fontification. You should specify the value of this -variable with @var{keywords} in @code{font-lock-defaults}. - -@defvar font-lock-keywords -This variable's value is a list of the keywords to highlight. Be -careful when composing regular expressions for this list; a poorly -written pattern can dramatically slow things down! -@end defvar - - Each element of @code{font-lock-keywords} specifies how to find -certain cases of text, and how to highlight those cases. Font Lock mode -processes the elements of @code{font-lock-keywords} one by one, and for -each element, it finds and handles all matches. Ordinarily, once -part of the text has been fontified already, this cannot be overridden -by a subsequent match in the same text; but you can specify different -behavior using the @var{override} element of a @var{subexp-highlighter}. - - Each element of @code{font-lock-keywords} should have one of these -forms: - -@table @code -@item @var{regexp} -Highlight all matches for @var{regexp} using -@code{font-lock-keyword-face}. For example, - -@example -;; @r{Highlight occurrences of the word @samp{foo}} -;; @r{using @code{font-lock-keyword-face}.} -"\\<foo\\>" -@end example - -The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful -for calculating optimal regular expressions to match a number of -different keywords. - -@item @var{function} -Find text by calling @var{function}, and highlight the matches -it finds using @code{font-lock-keyword-face}. - -When @var{function} is called, it receives one argument, the limit of -the search; it should begin searching at point, and not search beyond the -limit. It should return non-@code{nil} if it succeeds, and set the -match data to describe the match that was found. Returning @code{nil} -indicates failure of the search. - -Fontification will call @var{function} repeatedly with the same limit, -and with point where the previous invocation left it, until -@var{function} fails. On failure, @var{function} need not reset point -in any particular way. - -@item (@var{matcher} . @var{subexp}) -In this kind of element, @var{matcher} is either a regular -expression or a function, as described above. The @sc{cdr}, -@var{subexp}, specifies which subexpression of @var{matcher} should be -highlighted (instead of the entire text that @var{matcher} matched). - -@example -;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},} -;; @r{using @code{font-lock-keyword-face}.} -("fu\\(bar\\)" . 1) -@end example - -If you use @code{regexp-opt} to produce the regular expression -@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp -Functions}) to calculate the value for @var{subexp}. - -@item (@var{matcher} . @var{facespec}) -In this kind of element, @var{facespec} is an expression whose value -specifies the face to use for highlighting. In the simplest case, -@var{facespec} is a Lisp variable (a symbol) whose value is a face -name. - -@example -;; @r{Highlight occurrences of @samp{fubar},} -;; @r{using the face which is the value of @code{fubar-face}.} -("fubar" . fubar-face) -@end example - -However, @var{facespec} can also evaluate to a list of this form: - -@example -(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) -@end example - -@noindent -to specify the face @var{face} and various additional text properties -to put on the text that matches. If you do this, be sure to add the -other text property names that you set in this way to the value of -@code{font-lock-extra-managed-props} so that the properties will also -be cleared out when they are no longer appropriate. Alternatively, -you can set the variable @code{font-lock-unfontify-region-function} to -a function that clears these properties. @xref{Other Font Lock -Variables}. - -@item (@var{matcher} . @var{subexp-highlighter}) -In this kind of element, @var{subexp-highlighter} is a list -which specifies how to highlight matches found by @var{matcher}. -It has the form: - -@example -(@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]]) -@end example - -The @sc{car}, @var{subexp}, is an integer specifying which subexpression -of the match to fontify (0 means the entire matching text). The second -subelement, @var{facespec}, is an expression whose value specifies the -face, as described above. - -The last two values in @var{subexp-highlighter}, @var{override} and -@var{laxmatch}, are optional flags. If @var{override} is @code{t}, -this element can override existing fontification made by previous -elements of @code{font-lock-keywords}. If it is @code{keep}, then -each character is fontified if it has not been fontified already by -some other element. If it is @code{prepend}, the face specified by -@var{facespec} is added to the beginning of the @code{font-lock-face} -property. If it is @code{append}, the face is added to the end of the -@code{font-lock-face} property. - -If @var{laxmatch} is non-@code{nil}, it means there should be no error -if there is no subexpression numbered @var{subexp} in @var{matcher}. -Obviously, fontification of the subexpression numbered @var{subexp} will -not occur. However, fontification of other subexpressions (and other -regexps) will continue. If @var{laxmatch} is @code{nil}, and the -specified subexpression is missing, then an error is signaled which -terminates search-based fontification. - -Here are some examples of elements of this kind, and what they do: - -@smallexample -;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using} -;; @r{@code{foo-bar-face}, even if they have already been highlighted.} -;; @r{@code{foo-bar-face} should be a variable whose value is a face.} -("foo\\|bar" 0 foo-bar-face t) - -;; @r{Highlight the first subexpression within each occurrence} -;; @r{that the function @code{fubar-match} finds,} -;; @r{using the face which is the value of @code{fubar-face}.} -(fubar-match 1 fubar-face) -@end smallexample - -@item (@var{matcher} . @var{anchored-highlighter}) -In this kind of element, @var{anchored-highlighter} specifies how to -highlight text that follows a match found by @var{matcher}. So a -match found by @var{matcher} acts as the anchor for further searches -specified by @var{anchored-highlighter}. @var{anchored-highlighter} -is a list of the following form: - -@example -(@var{anchored-matcher} @var{pre-form} @var{post-form} - @var{subexp-highlighters}@dots{}) -@end example - -Here, @var{anchored-matcher}, like @var{matcher}, is either a regular -expression or a function. After a match of @var{matcher} is found, -point is at the end of the match. Now, Font Lock evaluates the form -@var{pre-form}. Then it searches for matches of -@var{anchored-matcher} and uses @var{subexp-highlighters} to highlight -these. A @var{subexp-highlighter} is as described above. Finally, -Font Lock evaluates @var{post-form}. - -The forms @var{pre-form} and @var{post-form} can be used to initialize -before, and cleanup after, @var{anchored-matcher} is used. Typically, -@var{pre-form} is used to move point to some position relative to the -match of @var{matcher}, before starting with @var{anchored-matcher}. -@var{post-form} might be used to move back, before resuming with -@var{matcher}. - -After Font Lock evaluates @var{pre-form}, it does not search for -@var{anchored-matcher} beyond the end of the line. However, if -@var{pre-form} returns a buffer position that is greater than the -position of point after @var{pre-form} is evaluated, then the position -returned by @var{pre-form} is used as the limit of the search instead. -It is generally a bad idea to return a position greater than the end -of the line; in other words, the @var{anchored-matcher} search should -not span lines. - -For example, - -@smallexample -;; @r{Highlight occurrences of the word @samp{item} following} -;; @r{an occurrence of the word @samp{anchor} (on the same line)} -;; @r{in the value of @code{item-face}.} -("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face)) -@end smallexample - -Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore -searching for @samp{item} starts at the end of the match of -@samp{anchor}, and searching for subsequent instances of @samp{anchor} -resumes from where searching for @samp{item} concluded. - -@item (@var{matcher} @var{highlighters}@dots{}) -This sort of element specifies several @var{highlighter} lists for a -single @var{matcher}. A @var{highlighter} list can be of the type -@var{subexp-highlighter} or @var{anchored-highlighter} as described -above. - -For example, - -@smallexample -;; @r{Highlight occurrences of the word @samp{anchor} in the value} -;; @r{of @code{anchor-face}, and subsequent occurrences of the word} -;; @r{@samp{item} (on the same line) in the value of @code{item-face}.} -("\\<anchor\\>" (0 anchor-face) - ("\\<item\\>" nil nil (0 item-face))) -@end smallexample - -@item (eval . @var{form}) -Here @var{form} is an expression to be evaluated the first time -this value of @code{font-lock-keywords} is used in a buffer. -Its value should have one of the forms described in this table. -@end table - -@strong{Warning:} Do not design an element of @code{font-lock-keywords} -to match text which spans lines; this does not work reliably. -For details, see @xref{Multiline Font Lock}. - -You can use @var{case-fold} in @code{font-lock-defaults} to specify -the value of @code{font-lock-keywords-case-fold-search} which says -whether search-based fontification should be case-insensitive. - -@defvar font-lock-keywords-case-fold-search -Non-@code{nil} means that regular expression matching for the sake of -@code{font-lock-keywords} should be case-insensitive. -@end defvar - -@node Customizing Keywords -@subsection Customizing Search-Based Fontification - - You can use @code{font-lock-add-keywords} to add additional -search-based fontification rules to a major mode, and -@code{font-lock-remove-keywords} to removes rules. - -@defun font-lock-add-keywords mode keywords &optional how -This function adds highlighting @var{keywords}, for the current buffer -or for major mode @var{mode}. The argument @var{keywords} should be a -list with the same format as the variable @code{font-lock-keywords}. - -If @var{mode} is a symbol which is a major mode command name, such as -@code{c-mode}, the effect is that enabling Font Lock mode in -@var{mode} will add @var{keywords} to @code{font-lock-keywords}. -Calling with a non-@code{nil} value of @var{mode} is correct only in -your @file{~/.emacs} file. - -If @var{mode} is @code{nil}, this function adds @var{keywords} to -@code{font-lock-keywords} in the current buffer. This way of calling -@code{font-lock-add-keywords} is usually used in mode hook functions. - -By default, @var{keywords} are added at the beginning of -@code{font-lock-keywords}. If the optional argument @var{how} is -@code{set}, they are used to replace the value of -@code{font-lock-keywords}. If @var{how} is any other non-@code{nil} -value, they are added at the end of @code{font-lock-keywords}. - -Some modes provide specialized support you can use in additional -highlighting patterns. See the variables -@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, -and @code{java-font-lock-extra-types}, for example. - -@strong{Warning:} major mode functions must not call -@code{font-lock-add-keywords} under any circumstances, either directly -or indirectly, except through their mode hooks. (Doing so would lead -to incorrect behavior for some minor modes.) They should set up their -rules for search-based fontification by setting -@code{font-lock-keywords}. -@end defun - -@defun font-lock-remove-keywords mode keywords -This function removes @var{keywords} from @code{font-lock-keywords} -for the current buffer or for major mode @var{mode}. As in -@code{font-lock-add-keywords}, @var{mode} should be a major mode -command name or @code{nil}. All the caveats and requirements for -@code{font-lock-add-keywords} apply here too. -@end defun - - For example, this code - -@smallexample -(font-lock-add-keywords 'c-mode - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) - ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) -@end smallexample - -@noindent -adds two fontification patterns for C mode: one to fontify the word -@samp{FIXME}, even in comments, and another to fontify the words -@samp{and}, @samp{or} and @samp{not} as keywords. - -@noindent -That example affects only C mode proper. To add the same patterns to -C mode @emph{and} all modes derived from it, do this instead: - -@smallexample -(add-hook 'c-mode-hook - (lambda () - (font-lock-add-keywords nil - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) - ("\\<\\(and\\|or\\|not\\)\\>" . - font-lock-keyword-face))))) -@end smallexample - -@node Other Font Lock Variables -@subsection Other Font Lock Variables - - This section describes additional variables that a major mode can -set by means of @var{other-vars} in @code{font-lock-defaults} -(@pxref{Font Lock Basics}). - -@defvar font-lock-mark-block-function -If this variable is non-@code{nil}, it should be a function that is -called with no arguments, to choose an enclosing range of text for -refontification for the command @kbd{M-o M-o} -(@code{font-lock-fontify-block}). - -The function should report its choice by placing the region around it. -A good choice is a range of text large enough to give proper results, -but not too large so that refontification becomes slow. Typical values -are @code{mark-defun} for programming modes or @code{mark-paragraph} for -textual modes. -@end defvar - -@defvar font-lock-extra-managed-props -This variable specifies additional properties (other than -@code{font-lock-face}) that are being managed by Font Lock mode. It -is used by @code{font-lock-default-unfontify-region}, which normally -only manages the @code{font-lock-face} property. If you want Font -Lock to manage other properties as well, you must specify them in a -@var{facespec} in @code{font-lock-keywords} as well as add them to -this list. @xref{Search-based Fontification}. -@end defvar - -@defvar font-lock-fontify-buffer-function -Function to use for fontifying the buffer. The default value is -@code{font-lock-default-fontify-buffer}. -@end defvar - -@defvar font-lock-unfontify-buffer-function -Function to use for unfontifying the buffer. This is used when -turning off Font Lock mode. The default value is -@code{font-lock-default-unfontify-buffer}. -@end defvar - -@defvar font-lock-fontify-region-function -Function to use for fontifying a region. It should take two -arguments, the beginning and end of the region, and an optional third -argument @var{verbose}. If @var{verbose} is non-@code{nil}, the -function should print status messages. The default value is -@code{font-lock-default-fontify-region}. -@end defvar - -@defvar font-lock-unfontify-region-function -Function to use for unfontifying a region. It should take two -arguments, the beginning and end of the region. The default value is -@code{font-lock-default-unfontify-region}. -@end defvar - -@ignore -@defvar font-lock-inhibit-thing-lock -List of Font Lock mode related modes that should not be turned on. -Currently, valid mode names are @code{fast-lock-mode}, -@code{jit-lock-mode} and @code{lazy-lock-mode}. -@end defvar -@end ignore - -@node Levels of Font Lock -@subsection Levels of Font Lock - - Many major modes offer three different levels of fontification. You -can define multiple levels by using a list of symbols for @var{keywords} -in @code{font-lock-defaults}. Each symbol specifies one level of -fontification; it is up to the user to choose one of these levels. The -chosen level's symbol value is used to initialize -@code{font-lock-keywords}. - - Here are the conventions for how to define the levels of -fontification: - -@itemize @bullet -@item -Level 1: highlight function declarations, file directives (such as include or -import directives), strings and comments. The idea is speed, so only -the most important and top-level components are fontified. - -@item -Level 2: in addition to level 1, highlight all language keywords, -including type names that act like keywords, as well as named constant -values. The idea is that all keywords (either syntactic or semantic) -should be fontified appropriately. - -@item -Level 3: in addition to level 2, highlight the symbols being defined in -function and variable declarations, and all builtin function names, -wherever they appear. -@end itemize - -@node Precalculated Fontification -@subsection Precalculated Fontification - - In addition to using @code{font-lock-defaults} for search-based -fontification, you may use the special character property -@code{font-lock-face} (@pxref{Special Properties}). This property -acts just like the explicit @code{face} property, but its activation -is toggled when the user calls @kbd{M-x font-lock-mode}. Using -@code{font-lock-face} is especially convenient for special modes -which construct their text programmatically, such as -@code{list-buffers} and @code{occur}. - -If your mode does not use any of the other machinery of Font Lock -(i.e. it only uses the @code{font-lock-face} property), it should not -set the variable @code{font-lock-defaults}. - -@node Faces for Font Lock -@subsection Faces for Font Lock -@cindex faces for font lock -@cindex font lock faces - - You can make Font Lock mode use any face, but several faces are -defined specifically for Font Lock mode. Each of these symbols is both -a face name, and a variable whose default value is the symbol itself. -Thus, the default value of @code{font-lock-comment-face} is -@code{font-lock-comment-face}. This means you can write -@code{font-lock-comment-face} in a context such as -@code{font-lock-keywords} where a face-name-valued expression is used. - -@table @code -@item font-lock-comment-face -@vindex font-lock-comment-face -Used (typically) for comments. - -@item font-lock-comment-delimiter-face -@vindex font-lock-comment-delimiter-face -Used (typically) for comments delimiters. - -@item font-lock-doc-face -@vindex font-lock-doc-face -Used (typically) for documentation strings in the code. - -@item font-lock-string-face -@vindex font-lock-string-face -Used (typically) for string constants. - -@item font-lock-keyword-face -@vindex font-lock-keyword-face -Used (typically) for keywords---names that have special syntactic -significance, like @code{for} and @code{if} in C. - -@item font-lock-builtin-face -@vindex font-lock-builtin-face -Used (typically) for built-in function names. - -@item font-lock-function-name-face -@vindex font-lock-function-name-face -Used (typically) for the name of a function being defined or declared, -in a function definition or declaration. - -@item font-lock-variable-name-face -@vindex font-lock-variable-name-face -Used (typically) for the name of a variable being defined or declared, -in a variable definition or declaration. - -@item font-lock-type-face -@vindex font-lock-type-face -Used (typically) for names of user-defined data types, -where they are defined and where they are used. - -@item font-lock-constant-face -@vindex font-lock-constant-face -Used (typically) for constant names. - -@item font-lock-preprocessor-face -@vindex font-lock-preprocessor-face -Used (typically) for preprocessor commands. - -@item font-lock-negation-char-face -@vindex font-lock-negation-char-face -Used (typically) for easily-overlooked negation characters. - -@item font-lock-warning-face -@vindex font-lock-warning-face -Used (typically) for constructs that are peculiar, or that greatly -change the meaning of other text. For example, this is used for -@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error} -directives in C. -@end table - -@node Syntactic Font Lock -@subsection Syntactic Font Lock -@cindex syntactic font lock - -Syntactic fontification uses the syntax table to find comments and -string constants (@pxref{Syntax Tables}). It highlights them using -@code{font-lock-comment-face} and @code{font-lock-string-face} -(@pxref{Faces for Font Lock}), or whatever -@code{font-lock-syntactic-face-function} chooses. There are several -variables that affect syntactic fontification; you should set them by -means of @code{font-lock-defaults} (@pxref{Font Lock Basics}). - -@defvar font-lock-keywords-only -Non-@code{nil} means Font Lock should not do syntactic fontification; -it should only fontify based on @code{font-lock-keywords}. The normal -way for a mode to set this variable to @code{t} is with -@var{keywords-only} in @code{font-lock-defaults}. -@end defvar - -@defvar font-lock-syntax-table -This variable holds the syntax table to use for fontification of -comments and strings. Specify it using @var{syntax-alist} in -@code{font-lock-defaults}. If this is @code{nil}, fontification uses -the buffer's syntax table. -@end defvar - -@defvar font-lock-beginning-of-syntax-function -If this variable is non-@code{nil}, it should be a function to move -point back to a position that is syntactically at ``top level'' and -outside of strings or comments. Font Lock uses this when necessary -to get the right results for syntactic fontification. - -This function is called with no arguments. It should leave point at -the beginning of any enclosing syntactic block. Typical values are -@code{beginning-of-line} (used when the start of the line is known to -be outside a syntactic block), or @code{beginning-of-defun} for -programming modes, or @code{backward-paragraph} for textual modes. - -If the value is @code{nil}, Font Lock uses -@code{syntax-begin-function} to move back outside of any comment, -string, or sexp. This variable is semi-obsolete; we recommend setting -@code{syntax-begin-function} instead. - -Specify this variable using @var{syntax-begin} in -@code{font-lock-defaults}. -@end defvar - -@defvar font-lock-syntactic-face-function -A function to determine which face to use for a given syntactic -element (a string or a comment). The function is called with one -argument, the parse state at point returned by -@code{parse-partial-sexp}, and should return a face. The default -value returns @code{font-lock-comment-face} for comments and -@code{font-lock-string-face} for strings. - -This can be used to highlighting different kinds of strings or -comments differently. It is also sometimes abused together with -@code{font-lock-syntactic-keywords} to highlight constructs that span -multiple lines, but this is too esoteric to document here. - -Specify this variable using @var{other-vars} in -@code{font-lock-defaults}. -@end defvar - -@node Setting Syntax Properties -@subsection Setting Syntax Properties - - Font Lock mode can be used to update @code{syntax-table} properties -automatically (@pxref{Syntax Properties}). This is useful in -languages for which a single syntax table by itself is not sufficient. - -@defvar font-lock-syntactic-keywords -This variable enables and controls updating @code{syntax-table} -properties by Font Lock. Its value should be a list of elements of -this form: - -@example -(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch}) -@end example - -The parts of this element have the same meanings as in the corresponding -sort of element of @code{font-lock-keywords}, - -@example -(@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch}) -@end example - -However, instead of specifying the value @var{facespec} to use for the -@code{face} property, it specifies the value @var{syntax} to use for -the @code{syntax-table} property. Here, @var{syntax} can be a string -(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell -(as returned by @code{string-to-syntax}), or an expression whose value -is one of those two types. @var{override} cannot be @code{prepend} or -@code{append}. - -For example, an element of the form: - -@example -("\\$\\(#\\)" 1 ".") -@end example - -highlights syntactically a hash character when following a dollar -character, with a SYNTAX of @code{"."} (meaning punctuation syntax). -Assuming that the buffer syntax table specifies hash characters to -have comment start syntax, the element will only highlight hash -characters that do not follow dollar characters as comments -syntactically. - -An element of the form: - -@example - ("\\('\\).\\('\\)" - (1 "\"") - (2 "\"")) -@end example - -highlights syntactically both single quotes which surround a single -character, with a SYNTAX of @code{"\""} (meaning string quote syntax). -Assuming that the buffer syntax table does not specify single quotes -to have quote syntax, the element will only highlight single quotes of -the form @samp{'@var{c}'} as strings syntactically. Other forms, such -as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as -strings. - -Major modes normally set this variable with @var{other-vars} in -@code{font-lock-defaults}. -@end defvar - -@node Multiline Font Lock -@subsection Multiline Font Lock Constructs -@cindex multiline font lock - - Normally, elements of @code{font-lock-keywords} should not match -across multiple lines; that doesn't work reliably, because Font Lock -usually scans just part of the buffer, and it can miss a multi-line -construct that crosses the line boundary where the scan starts. (The -scan normally starts at the beginning of a line.) - - Making elements that match multiline constructs work properly has -two aspects: correct @emph{identification} and correct -@emph{rehighlighting}. The first means that Font Lock finds all -multiline constructs. The second means that Font Lock will correctly -rehighlight all the relevant text when a multiline construct is -changed---for example, if some of the text that was previously part of -a multiline construct ceases to be part of it. The two aspects are -closely related, and often getting one of them to work will appear to -make the other also work. However, for reliable results you must -attend explicitly to both aspects. - - There are three ways to ensure correct identification of multiline -constructs: - -@itemize -@item -Add a function to @code{font-lock-extend-region-functions} that does -the @emph{identification} and extends the scan so that the scanned -text never starts or ends in the middle of a multiline construct. -@item -Use the @code{font-lock-fontify-region-function} hook similarly to -extend the scan so that the scanned text never starts or ends in the -middle of a multiline construct. -@item -Somehow identify the multiline construct right when it gets inserted -into the buffer (or at any point after that but before font-lock -tries to highlight it), and mark it with a @code{font-lock-multiline} -which will instruct font-lock not to start or end the scan in the -middle of the construct. -@end itemize - - There are three ways to do rehighlighting of multiline constructs: - -@itemize -@item -Place a @code{font-lock-multiline} property on the construct. This -will rehighlight the whole construct if any part of it is changed. In -some cases you can do this automatically by setting the -@code{font-lock-multiline} variable, which see. -@item -Make sure @code{jit-lock-contextually} is set and rely on it doing its -job. This will only rehighlight the part of the construct that -follows the actual change, and will do it after a short delay. -This only works if the highlighting of the various parts of your -multiline construct never depends on text in subsequent lines. -Since @code{jit-lock-contextually} is activated by default, this can -be an attractive solution. -@item -Place a @code{jit-lock-defer-multiline} property on the construct. -This works only if @code{jit-lock-contextually} is used, and with the -same delay before rehighlighting, but like @code{font-lock-multiline}, -it also handles the case where highlighting depends on -subsequent lines. -@end itemize - -@menu -* Font Lock Multiline:: Marking multiline chunks with a text property -* Region to Fontify:: Controlling which region gets refontified - after a buffer change. -@end menu - -@node Font Lock Multiline -@subsubsection Font Lock Multiline - - One way to ensure reliable rehighlighting of multiline Font Lock -constructs is to put on them the text property @code{font-lock-multiline}. -It should be present and non-@code{nil} for text that is part of a -multiline construct. - - When Font Lock is about to highlight a range of text, it first -extends the boundaries of the range as necessary so that they do not -fall within text marked with the @code{font-lock-multiline} property. -Then it removes any @code{font-lock-multiline} properties from the -range, and highlights it. The highlighting specification (mostly -@code{font-lock-keywords}) must reinstall this property each time, -whenever it is appropriate. - - @strong{Warning:} don't use the @code{font-lock-multiline} property -on large ranges of text, because that will make rehighlighting slow. - -@defvar font-lock-multiline -If the @code{font-lock-multiline} variable is set to @code{t}, Font -Lock will try to add the @code{font-lock-multiline} property -automatically on multiline constructs. This is not a universal -solution, however, since it slows down Font Lock somewhat. It can -miss some multiline constructs, or make the property larger or smaller -than necessary. - -For elements whose @var{matcher} is a function, the function should -ensure that submatch 0 covers the whole relevant multiline construct, -even if only a small subpart will be highlighted. It is often just as -easy to add the @code{font-lock-multiline} property by hand. -@end defvar - - The @code{font-lock-multiline} property is meant to ensure proper -refontification; it does not automatically identify new multiline -constructs. Identifying the requires that Font-Lock operate on large -enough chunks at a time. This will happen by accident on many cases, -which may give the impression that multiline constructs magically work. -If you set the @code{font-lock-multiline} variable non-@code{nil}, -this impression will be even stronger, since the highlighting of those -constructs which are found will be properly updated from then on. -But that does not work reliably. - - To find multiline constructs reliably, you must either manually -place the @code{font-lock-multiline} property on the text before -Font-Lock looks at it, or use -@code{font-lock-fontify-region-function}. - -@node Region to Fontify -@subsubsection Region to Fontify after a Buffer Change - - When a buffer is changed, the region that Font Lock refontifies is -by default the smallest sequence of whole lines that spans the change. -While this works well most of the time, sometimes it doesn't---for -example, when a change alters the syntactic meaning of text on an -earlier line. - - You can enlarge (or even reduce) the region to fontify by setting -one the following variables: - -@defvar font-lock-extend-after-change-region-function -This buffer-local variable is either @code{nil} or a function for -Font-Lock to call to determine the region to scan and fontify. - -The function is given three parameters, the standard @var{beg}, -@var{end}, and @var{old-len} from after-change-functions -(@pxref{Change Hooks}). It should return either a cons of the -beginning and end buffer positions (in that order) of the region to -fontify, or @code{nil} (which means choose the region in the standard -way). This function needs to preserve point, the match-data, and the -current restriction. The region it returns may start or end in the -middle of a line. - -Since this function is called after every buffer change, it should be -reasonably fast. -@end defvar - -@node Desktop Save Mode -@section Desktop Save Mode -@cindex desktop save mode - -@dfn{Desktop Save Mode} is a feature to save the state of Emacs from -one session to another. The user-level commands for using Desktop -Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs -Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit -a file, don't have to do anything to use this feature. - -For buffers not visiting a file to have their state saved, the major -mode must bind the buffer local variable @code{desktop-save-buffer} to -a non-@code{nil} value. - -@defvar desktop-save-buffer -If this buffer-local variable is non-@code{nil}, the buffer will have -its state saved in the desktop file at desktop save. If the value is -a function, it is called at desktop save with argument -@var{desktop-dirname}, and its value is saved in the desktop file along -with the state of the buffer for which it was called. When file names -are returned as part of the auxiliary information, they should be -formatted using the call - -@example -(desktop-file-name @var{file-name} @var{desktop-dirname}) -@end example - -@end defvar - -For buffers not visiting a file to be restored, the major mode must -define a function to do the job, and that function must be listed in -the alist @code{desktop-buffer-mode-handlers}. - -@defvar desktop-buffer-mode-handlers -Alist with elements - -@example -(@var{major-mode} . @var{restore-buffer-function}) -@end example - -The function @var{restore-buffer-function} will be called with -argument list - -@example -(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc}) -@end example - -and it should return the restored buffer. -Here @var{desktop-buffer-misc} is the value returned by the function -optionally bound to @code{desktop-save-buffer}. -@end defvar - -@ignore - arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e -@end ignore diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi deleted file mode 100644 index a8f45e9dd20..00000000000 --- a/lispref/nonascii.texi +++ /dev/null @@ -1,1504 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/characters -@node Non-ASCII Characters, Searching and Matching, Text, Top -@chapter Non-@acronym{ASCII} Characters -@cindex multibyte characters -@cindex characters, multi-byte -@cindex non-@acronym{ASCII} characters - - This chapter covers the special issues relating to non-@acronym{ASCII} -characters and how they are stored in strings and buffers. - -@menu -* 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 character 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. -@end menu - -@node Text Representations -@section Text Representations -@cindex text representations - - Emacs has two @dfn{text representations}---two ways to represent text -in a string or buffer. These are called @dfn{unibyte} and -@dfn{multibyte}. Each string, and each buffer, uses one of these two -representations. For most purposes, you can ignore the issue of -representations, because Emacs converts text between them as -appropriate. Occasionally in Lisp programming you will need to pay -attention to the difference. - -@cindex unibyte text - In unibyte representation, each character occupies one byte and -therefore the possible character codes range from 0 to 255. Codes 0 -through 127 are @acronym{ASCII} characters; the codes from 128 through 255 -are used for one non-@acronym{ASCII} character set (you can choose which -character set by setting the variable @code{nonascii-insert-offset}). - -@cindex leading code -@cindex multibyte text -@cindex trailing codes - In multibyte representation, a character may occupy more than one -byte, and as a result, the full range of Emacs character codes can be -stored. The first byte of a multibyte character is always in the range -128 through 159 (octal 0200 through 0237). These values are called -@dfn{leading codes}. The second and subsequent bytes of a multibyte -character are always in the range 160 through 255 (octal 0240 through -0377); these values are @dfn{trailing codes}. - - Some sequences of bytes are not valid in multibyte text: for example, -a single isolated byte in the range 128 through 159 is not allowed. But -character codes 128 through 159 can appear in multibyte text, -represented as two-byte sequences. All the character codes 128 through -255 are possible (though slightly abnormal) in multibyte text; they -appear in multibyte buffers and strings when you do explicit encoding -and decoding (@pxref{Explicit Encoding}). - - In a buffer, the buffer-local value of the variable -@code{enable-multibyte-characters} specifies the representation used. -The representation for a string is determined and recorded in the string -when the string is constructed. - -@defvar enable-multibyte-characters -This variable specifies the current buffer's text representation. -If it is non-@code{nil}, the buffer contains multibyte text; otherwise, -it contains unibyte text. - -You cannot set this variable directly; instead, use the function -@code{set-buffer-multibyte} to change a buffer's representation. -@end defvar - -@defvar default-enable-multibyte-characters -This variable's value is entirely equivalent to @code{(default-value -'enable-multibyte-characters)}, and setting this variable changes that -default value. Setting the local binding of -@code{enable-multibyte-characters} in a specific buffer is not allowed, -but changing the default value is supported, and it is a reasonable -thing to do, because it has no effect on existing buffers. - -The @samp{--unibyte} command line option does its job by setting the -default value to @code{nil} early in startup. -@end defvar - -@defun position-bytes position -Return the byte-position corresponding to buffer position -@var{position} in the current buffer. This is 1 at the start of the -buffer, and counts upward in bytes. If @var{position} is out of -range, the value is @code{nil}. -@end defun - -@defun byte-to-position byte-position -Return the buffer position corresponding to byte-position -@var{byte-position} in the current buffer. If @var{byte-position} is -out of range, the value is @code{nil}. -@end defun - -@defun multibyte-string-p string -Return @code{t} if @var{string} is a multibyte string. -@end defun - -@defun string-bytes string -@cindex string, number of bytes -This function returns the number of bytes in @var{string}. -If @var{string} is a multibyte string, this can be greater than -@code{(length @var{string})}. -@end defun - -@node Converting Representations -@section Converting Text Representations - - Emacs can convert unibyte text to multibyte; it can also convert -multibyte text to unibyte, though this conversion loses information. In -general these conversions happen when inserting text into a buffer, or -when putting text from several strings together in one string. You can -also explicitly convert a string's contents to either representation. - - Emacs chooses the representation for a string based on the text that -it is constructed from. The general rule is to convert unibyte text to -multibyte text when combining it with other multibyte text, because the -multibyte representation is more general and can hold whatever -characters the unibyte text has. - - When inserting text into a buffer, Emacs converts the text to the -buffer's representation, as specified by -@code{enable-multibyte-characters} in that buffer. In particular, when -you insert multibyte text into a unibyte buffer, Emacs converts the text -to unibyte, even though this conversion cannot in general preserve all -the characters that might be in the multibyte text. The other natural -alternative, to convert the buffer contents to multibyte, is not -acceptable because the buffer's representation is a choice made by the -user that cannot be overridden automatically. - - Converting unibyte text to multibyte text leaves @acronym{ASCII} characters -unchanged, and likewise character codes 128 through 159. It converts -the non-@acronym{ASCII} codes 160 through 255 by adding the value -@code{nonascii-insert-offset} to each character code. By setting this -variable, you specify which character set the unibyte characters -correspond to (@pxref{Character Sets}). For example, if -@code{nonascii-insert-offset} is 2048, which is @code{(- (make-char -'latin-iso8859-1) 128)}, then the unibyte non-@acronym{ASCII} characters -correspond to Latin 1. If it is 2688, which is @code{(- (make-char -'greek-iso8859-7) 128)}, then they correspond to Greek letters. - - Converting multibyte text to unibyte is simpler: it discards all but -the low 8 bits of each character code. If @code{nonascii-insert-offset} -has a reasonable value, corresponding to the beginning of some character -set, this conversion is the inverse of the other: converting unibyte -text to multibyte and back to unibyte reproduces the original unibyte -text. - -@defvar nonascii-insert-offset -This variable specifies the amount to add to a non-@acronym{ASCII} character -when converting unibyte text to multibyte. It also applies when -@code{self-insert-command} inserts a character in the unibyte -non-@acronym{ASCII} range, 128 through 255. However, the functions -@code{insert} and @code{insert-char} do not perform this conversion. - -The right value to use to select character set @var{cs} is @code{(- -(make-char @var{cs}) 128)}. If the value of -@code{nonascii-insert-offset} is zero, then conversion actually uses the -value for the Latin 1 character set, rather than zero. -@end defvar - -@defvar nonascii-translation-table -This variable provides a more general alternative to -@code{nonascii-insert-offset}. You can use it to specify independently -how to translate each code in the range of 128 through 255 into a -multibyte character. The value should be a char-table, or @code{nil}. -If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}. -@end defvar - -The next three functions either return the argument @var{string}, or a -newly created string with no text properties. - -@defun string-make-unibyte string -This function converts the text of @var{string} to unibyte -representation, if it isn't already, and returns the result. If -@var{string} is a unibyte string, it is returned unchanged. Multibyte -character codes are converted to unibyte according to -@code{nonascii-translation-table} or, if that is @code{nil}, using -@code{nonascii-insert-offset}. If the lookup in the translation table -fails, this function takes just the low 8 bits of each character. -@end defun - -@defun string-make-multibyte string -This function converts the text of @var{string} to multibyte -representation, if it isn't already, and returns the result. If -@var{string} is a multibyte string or consists entirely of -@acronym{ASCII} characters, it is returned unchanged. In particular, -if @var{string} is unibyte and entirely @acronym{ASCII}, the returned -string is unibyte. (When the characters are all @acronym{ASCII}, -Emacs primitives will treat the string the same way whether it is -unibyte or multibyte.) If @var{string} is unibyte and contains -non-@acronym{ASCII} characters, the function -@code{unibyte-char-to-multibyte} is used to convert each unibyte -character to a multibyte character. -@end defun - -@defun string-to-multibyte string -This function returns a multibyte string containing the same sequence -of character codes as @var{string}. Unlike -@code{string-make-multibyte}, this function unconditionally returns a -multibyte string. If @var{string} is a multibyte string, it is -returned unchanged. -@end defun - -@defun multibyte-char-to-unibyte char -This convert the multibyte character @var{char} to a unibyte -character, based on @code{nonascii-translation-table} and -@code{nonascii-insert-offset}. -@end defun - -@defun unibyte-char-to-multibyte char -This convert the unibyte character @var{char} to a multibyte -character, based on @code{nonascii-translation-table} and -@code{nonascii-insert-offset}. -@end defun - -@node Selecting a Representation -@section Selecting a Representation - - Sometimes it is useful to examine an existing buffer or string as -multibyte when it was unibyte, or vice versa. - -@defun set-buffer-multibyte multibyte -Set the representation type of the current buffer. If @var{multibyte} -is non-@code{nil}, the buffer becomes multibyte. If @var{multibyte} -is @code{nil}, the buffer becomes unibyte. - -This function leaves the buffer contents unchanged when viewed as a -sequence of bytes. As a consequence, it can change the contents viewed -as characters; a sequence of two bytes which is treated as one character -in multibyte representation will count as two characters in unibyte -representation. Character codes 128 through 159 are an exception. They -are represented by one byte in a unibyte buffer, but when the buffer is -set to multibyte, they are converted to two-byte sequences, and vice -versa. - -This function sets @code{enable-multibyte-characters} to record which -representation is in use. It also adjusts various data in the buffer -(including overlays, text properties and markers) so that they cover the -same text as they did before. - -You cannot use @code{set-buffer-multibyte} on an indirect buffer, -because indirect buffers always inherit the representation of the -base buffer. -@end defun - -@defun string-as-unibyte string -This function returns a string with the same bytes as @var{string} but -treating each byte as a character. This means that the value may have -more characters than @var{string} has. - -If @var{string} is already a unibyte string, then the value is -@var{string} itself. Otherwise it is a newly created string, with no -text properties. If @var{string} is multibyte, any characters it -contains of charset @code{eight-bit-control} or @code{eight-bit-graphic} -are converted to the corresponding single byte. -@end defun - -@defun string-as-multibyte string -This function returns a string with the same bytes as @var{string} but -treating each multibyte sequence as one character. This means that the -value may have fewer characters than @var{string} has. - -If @var{string} is already a multibyte string, then the value is -@var{string} itself. Otherwise it is a newly created string, with no -text properties. If @var{string} is unibyte and contains any individual -8-bit bytes (i.e.@: not part of a multibyte form), they are converted to -the corresponding multibyte character of charset @code{eight-bit-control} -or @code{eight-bit-graphic}. -@end defun - -@node Character Codes -@section Character Codes -@cindex character codes - - The unibyte and multibyte text representations use different character -codes. The valid character codes for unibyte representation range from -0 to 255---the values that can fit in one byte. The valid character -codes for multibyte representation range from 0 to 524287, but not all -values in that range are valid. The values 128 through 255 are not -entirely proper in multibyte text, but they can occur if you do explicit -encoding and decoding (@pxref{Explicit Encoding}). Some other character -codes cannot occur at all in multibyte text. Only the @acronym{ASCII} codes -0 through 127 are completely legitimate in both representations. - -@defun char-valid-p charcode &optional genericp -This returns @code{t} if @var{charcode} is valid (either for unibyte -text or for multibyte text). - -@example -(char-valid-p 65) - @result{} t -(char-valid-p 256) - @result{} nil -(char-valid-p 2248) - @result{} t -@end example - -If the optional argument @var{genericp} is non-@code{nil}, this -function also returns @code{t} if @var{charcode} is a generic -character (@pxref{Splitting Characters}). -@end defun - -@node Character Sets -@section Character Sets -@cindex character sets - - Emacs classifies characters into various @dfn{character sets}, each of -which has a name which is a symbol. Each character belongs to one and -only one character set. - - In general, there is one character set for each distinct script. For -example, @code{latin-iso8859-1} is one character set, -@code{greek-iso8859-7} is another, and @code{ascii} is another. An -Emacs character set can hold at most 9025 characters; therefore, in some -cases, characters that would logically be grouped together are split -into several character sets. For example, one set of Chinese -characters, generally known as Big 5, is divided into two Emacs -character sets, @code{chinese-big5-1} and @code{chinese-big5-2}. - - @acronym{ASCII} characters are in character set @code{ascii}. The -non-@acronym{ASCII} characters 128 through 159 are in character set -@code{eight-bit-control}, and codes 160 through 255 are in character set -@code{eight-bit-graphic}. - -@defun charsetp object -Returns @code{t} if @var{object} is a symbol that names a character set, -@code{nil} otherwise. -@end defun - -@defvar charset-list -The value is a list of all defined character set names. -@end defvar - -@defun charset-list -This function returns the value of @code{charset-list}. It is only -provided for backward compatibility. -@end defun - -@defun char-charset character -This function returns the name of the character set that @var{character} -belongs to, or the symbol @code{unknown} if @var{character} is not a -valid character. -@end defun - -@defun charset-plist charset -This function returns the charset property list of the character set -@var{charset}. Although @var{charset} is a symbol, this is not the same -as the property list of that symbol. Charset properties are used for -special purposes within Emacs. -@end defun - -@deffn Command list-charset-chars charset -This command displays a list of characters in the character set -@var{charset}. -@end deffn - -@node Chars and Bytes -@section Characters and Bytes -@cindex bytes and characters - -@cindex introduction sequence (of character) -@cindex dimension (of character set) - In multibyte representation, each character occupies one or more -bytes. Each character set has an @dfn{introduction sequence}, which is -normally one or two bytes long. (Exception: the @code{ascii} character -set and the @code{eight-bit-graphic} character set have a zero-length -introduction sequence.) The introduction sequence is the beginning of -the byte sequence for any character in the character set. The rest of -the character's bytes distinguish it from the other characters in the -same character set. Depending on the character set, there are either -one or two distinguishing bytes; the number of such bytes is called the -@dfn{dimension} of the character set. - -@defun charset-dimension charset -This function returns the dimension of @var{charset}; at present, the -dimension is always 1 or 2. -@end defun - -@defun charset-bytes charset -This function returns the number of bytes used to represent a character -in character set @var{charset}. -@end defun - - This is the simplest way to determine the byte length of a character -set's introduction sequence: - -@example -(- (charset-bytes @var{charset}) - (charset-dimension @var{charset})) -@end example - -@node Splitting Characters -@section Splitting Characters -@cindex character as bytes - - The functions in this section convert between characters and the byte -values used to represent them. For most purposes, there is no need to -be concerned with the sequence of bytes used to represent a character, -because Emacs translates automatically when necessary. - -@defun split-char character -Return a list containing the name of the character set of -@var{character}, followed by one or two byte values (integers) which -identify @var{character} within that character set. The number of byte -values is the character set's dimension. - -If @var{character} is invalid as a character code, @code{split-char} -returns a list consisting of the symbol @code{unknown} and @var{character}. - -@example -(split-char 2248) - @result{} (latin-iso8859-1 72) -(split-char 65) - @result{} (ascii 65) -(split-char 128) - @result{} (eight-bit-control 128) -@end example -@end defun - -@cindex generate characters in charsets -@defun make-char charset &optional code1 code2 -This function returns the character in character set @var{charset} whose -position codes are @var{code1} and @var{code2}. This is roughly the -inverse of @code{split-char}. Normally, you should specify either one -or both of @var{code1} and @var{code2} according to the dimension of -@var{charset}. For example, - -@example -(make-char 'latin-iso8859-1 72) - @result{} 2248 -@end example - -Actually, the eighth bit of both @var{code1} and @var{code2} is zeroed -before they are used to index @var{charset}. Thus you may use, for -instance, an ISO 8859 character code rather than subtracting 128, as -is necessary to index the corresponding Emacs charset. -@end defun - -@cindex generic characters - If you call @code{make-char} with no @var{byte-values}, the result is -a @dfn{generic character} which stands for @var{charset}. A generic -character is an integer, but it is @emph{not} valid for insertion in the -buffer as a character. It can be used in @code{char-table-range} to -refer to the whole character set (@pxref{Char-Tables}). -@code{char-valid-p} returns @code{nil} for generic characters. -For example: - -@example -(make-char 'latin-iso8859-1) - @result{} 2176 -(char-valid-p 2176) - @result{} nil -(char-valid-p 2176 t) - @result{} t -(split-char 2176) - @result{} (latin-iso8859-1 0) -@end example - -The character sets @code{ascii}, @code{eight-bit-control}, and -@code{eight-bit-graphic} don't have corresponding generic characters. If -@var{charset} is one of them and you don't supply @var{code1}, -@code{make-char} returns the character code corresponding to the -smallest code in @var{charset}. - -@node Scanning Charsets -@section Scanning for Character Sets - - Sometimes it is useful to find out which character sets appear in a -part of a buffer or a string. One use for this is in determining which -coding systems (@pxref{Coding Systems}) are capable of representing all -of the text in question. - -@defun charset-after &optional pos -This function return the charset of a character in the current buffer -at position @var{pos}. If @var{pos} is omitted or @code{nil}, it -defaults to the current value of point. If @var{pos} is out of range, -the value is @code{nil}. -@end defun - -@defun find-charset-region beg end &optional translation -This function returns a list of the character sets that appear in the -current buffer between positions @var{beg} and @var{end}. - -The optional argument @var{translation} specifies a translation table to -be used in scanning the text (@pxref{Translation of Characters}). If it -is non-@code{nil}, then each character in the region is translated -through this table, and the value returned describes the translated -characters instead of the characters actually in the buffer. -@end defun - -@defun find-charset-string string &optional translation -This function returns a list of the character sets that appear in the -string @var{string}. It is just like @code{find-charset-region}, except -that it applies to the contents of @var{string} instead of part of the -current buffer. -@end defun - -@node Translation of Characters -@section Translation of Characters -@cindex character translation tables -@cindex translation tables - - A @dfn{translation table} is a char-table that specifies a mapping -of characters into characters. These tables are used in encoding and -decoding, and for other purposes. Some coding systems specify their -own particular translation tables; there are also default translation -tables which apply to all other coding systems. - - For instance, the coding-system @code{utf-8} has a translation table -that maps characters of various charsets (e.g., -@code{latin-iso8859-@var{x}}) into Unicode character sets. This way, -it can encode Latin-2 characters into UTF-8. Meanwhile, -@code{unify-8859-on-decoding-mode} operates by specifying -@code{standard-translation-table-for-decode} to translate -Latin-@var{x} characters into corresponding Unicode characters. - -@defun make-translation-table &rest translations -This function returns a translation table based on the argument -@var{translations}. Each element of @var{translations} should be a -list of elements of the form @code{(@var{from} . @var{to})}; this says -to translate the character @var{from} into @var{to}. - -The arguments and the forms in each argument are processed in order, -and if a previous form already translates @var{to} to some other -character, say @var{to-alt}, @var{from} is also translated to -@var{to-alt}. - -You can also map one whole character set into another character set with -the same dimension. To do this, you specify a generic character (which -designates a character set) for @var{from} (@pxref{Splitting Characters}). -In this case, if @var{to} is also a generic character, its character -set should have the same dimension as @var{from}'s. Then the -translation table translates each character of @var{from}'s character -set into the corresponding character of @var{to}'s character set. If -@var{from} is a generic character and @var{to} is an ordinary -character, then the translation table translates every character of -@var{from}'s character set into @var{to}. -@end defun - - In decoding, the translation table's translations are applied to the -characters that result from ordinary decoding. If a coding system has -property @code{translation-table-for-decode}, that specifies the -translation table to use. (This is a property of the coding system, -as returned by @code{coding-system-get}, not a property of the symbol -that is the coding system's name. @xref{Coding System Basics,, Basic -Concepts of Coding Systems}.) Otherwise, if -@code{standard-translation-table-for-decode} is non-@code{nil}, -decoding uses that table. - - In encoding, the translation table's translations are applied to the -characters in the buffer, and the result of translation is actually -encoded. If a coding system has property -@code{translation-table-for-encode}, that specifies the translation -table to use. Otherwise the variable -@code{standard-translation-table-for-encode} specifies the translation -table. - -@defvar standard-translation-table-for-decode -This is the default translation table for decoding, for -coding systems that don't specify any other translation table. -@end defvar - -@defvar standard-translation-table-for-encode -This is the default translation table for encoding, for -coding systems that don't specify any other translation table. -@end defvar - -@defvar translation-table-for-input -Self-inserting characters are translated through this translation -table before they are inserted. Search commands also translate their -input through this table, so they can compare more reliably with -what's in the buffer. - -@code{set-buffer-file-coding-system} sets this variable so that your -keyboard input gets translated into the character sets that the buffer -is likely to contain. This variable automatically becomes -buffer-local when set. -@end defvar - -@node Coding Systems -@section Coding Systems - -@cindex coding system - When Emacs reads or writes a file, and when Emacs sends text to a -subprocess or receives text from a subprocess, it normally performs -character code conversion and end-of-line conversion as specified -by a particular @dfn{coding system}. - - How to define a coding system is an arcane matter, and is not -documented here. - -@menu -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. -@end menu - -@node Coding System Basics -@subsection Basic Concepts of Coding Systems - -@cindex character code conversion - @dfn{Character code conversion} involves conversion between the encoding -used inside Emacs and some other encoding. Emacs supports many -different encodings, in that it can convert to and from them. For -example, it can convert text to or from encodings such as Latin 1, Latin -2, Latin 3, Latin 4, Latin 5, and several variants of ISO 2022. In some -cases, Emacs supports several alternative encodings for the same -characters; for example, there are three coding systems for the Cyrillic -(Russian) alphabet: ISO, Alternativnyj, and KOI8. - - Most coding systems specify a particular character code for -conversion, but some of them leave the choice unspecified---to be chosen -heuristically for each file, based on the data. - - In general, a coding system doesn't guarantee roundtrip identity: -decoding a byte sequence using coding system, then encoding the -resulting text in the same coding system, can produce a different byte -sequence. However, the following coding systems do guarantee that the -byte sequence will be the same as what you originally decoded: - -@quotation -chinese-big5 chinese-iso-8bit cyrillic-iso-8bit emacs-mule -greek-iso-8bit hebrew-iso-8bit iso-latin-1 iso-latin-2 iso-latin-3 -iso-latin-4 iso-latin-5 iso-latin-8 iso-latin-9 iso-safe -japanese-iso-8bit japanese-shift-jis korean-iso-8bit raw-text -@end quotation - - Encoding buffer text and then decoding the result can also fail to -reproduce the original text. For instance, if you encode Latin-2 -characters with @code{utf-8} and decode the result using the same -coding system, you'll get Unicode characters (of charset -@code{mule-unicode-0100-24ff}). If you encode Unicode characters with -@code{iso-latin-2} and decode the result with the same coding system, -you'll get Latin-2 characters. - -@cindex EOL conversion -@cindex end-of-line conversion -@cindex line end conversion - @dfn{End of line conversion} handles three different conventions used -on various systems for representing end of line in files. The Unix -convention is to use the linefeed character (also called newline). The -DOS convention is to use a carriage-return and a linefeed at the end of -a line. The Mac convention is to use just carriage-return. - -@cindex base coding system -@cindex variant coding system - @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line -conversion unspecified, to be chosen based on the data. @dfn{Variant -coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and -@code{latin-1-mac} specify the end-of-line conversion explicitly as -well. Most base coding systems have three corresponding variants whose -names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}. - - The coding system @code{raw-text} is special in that it prevents -character code conversion, and causes the buffer visited with that -coding system to be a unibyte buffer. It does not specify the -end-of-line conversion, allowing that to be determined as usual by the -data, and has the usual three variants which specify the end-of-line -conversion. @code{no-conversion} is equivalent to @code{raw-text-unix}: -it specifies no conversion of either character codes or end-of-line. - - The coding system @code{emacs-mule} specifies that the data is -represented in the internal Emacs encoding. This is like -@code{raw-text} in that no code conversion happens, but different in -that the result is multibyte data. - -@defun coding-system-get coding-system property -This function returns the specified property of the coding system -@var{coding-system}. Most coding system properties exist for internal -purposes, but one that you might find useful is @code{mime-charset}. -That property's value is the name used in MIME for the character coding -which this coding system can read and write. Examples: - -@example -(coding-system-get 'iso-latin-1 'mime-charset) - @result{} iso-8859-1 -(coding-system-get 'iso-2022-cn 'mime-charset) - @result{} iso-2022-cn -(coding-system-get 'cyrillic-koi8 'mime-charset) - @result{} koi8-r -@end example - -The value of the @code{mime-charset} property is also defined -as an alias for the coding system. -@end defun - -@node Encoding and I/O -@subsection Encoding and I/O - - The principal purpose of coding systems is for use in reading and -writing files. The function @code{insert-file-contents} uses -a coding system for decoding the file data, and @code{write-region} -uses one to encode the buffer contents. - - You can specify the coding system to use either explicitly -(@pxref{Specifying Coding Systems}), or implicitly using a default -mechanism (@pxref{Default Coding Systems}). But these methods may not -completely specify what to do. For example, they may choose a coding -system such as @code{undefined} which leaves the character code -conversion to be determined from the data. In these cases, the I/O -operation finishes the job of choosing a coding system. Very often -you will want to find out afterwards which coding system was chosen. - -@defvar buffer-file-coding-system -This buffer-local variable records the coding system that was used to visit -the current buffer. It is used for saving the buffer, and for writing part -of the buffer with @code{write-region}. If the text to be written -cannot be safely encoded using the coding system specified by this -variable, these operations select an alternative encoding by calling -the function @code{select-safe-coding-system} (@pxref{User-Chosen -Coding Systems}). If selecting a different encoding requires to ask -the user to specify a coding system, @code{buffer-file-coding-system} -is updated to the newly selected coding system. - -@code{buffer-file-coding-system} does @emph{not} affect sending text -to a subprocess. -@end defvar - -@defvar save-buffer-coding-system -This variable specifies the coding system for saving the buffer (by -overriding @code{buffer-file-coding-system}). Note that it is not used -for @code{write-region}. - -When a command to save the buffer starts out to use -@code{buffer-file-coding-system} (or @code{save-buffer-coding-system}), -and that coding system cannot handle -the actual text in the buffer, the command asks the user to choose -another coding system (by calling @code{select-safe-coding-system}). -After that happens, the command also updates -@code{buffer-file-coding-system} to represent the coding system that -the user specified. -@end defvar - -@defvar last-coding-system-used -I/O operations for files and subprocesses set this variable to the -coding system name that was used. The explicit encoding and decoding -functions (@pxref{Explicit Encoding}) set it too. - -@strong{Warning:} Since receiving subprocess output sets this variable, -it can change whenever Emacs waits; therefore, you should copy the -value shortly after the function call that stores the value you are -interested in. -@end defvar - - The variable @code{selection-coding-system} specifies how to encode -selections for the window system. @xref{Window System Selections}. - -@defvar file-name-coding-system -The variable @code{file-name-coding-system} specifies the coding -system to use for encoding file names. Emacs encodes file names using -that coding system for all file operations. If -@code{file-name-coding-system} is @code{nil}, Emacs uses a default -coding system determined by the selected language environment. In the -default language environment, any non-@acronym{ASCII} characters in -file names are not encoded specially; they appear in the file system -using the internal Emacs representation. -@end defvar - - @strong{Warning:} if you change @code{file-name-coding-system} (or -the language environment) in the middle of an Emacs session, problems -can result if you have already visited files whose names were encoded -using the earlier coding system and are handled differently under the -new coding system. If you try to save one of these buffers under the -visited file name, saving may use the wrong file name, or it may get -an error. If such a problem happens, use @kbd{C-x C-w} to specify a -new file name for that buffer. - -@node Lisp and Coding Systems -@subsection Coding Systems in Lisp - - Here are the Lisp facilities for working with coding systems: - -@defun coding-system-list &optional base-only -This function returns a list of all coding system names (symbols). If -@var{base-only} is non-@code{nil}, the value includes only the -base coding systems. Otherwise, it includes alias and variant coding -systems as well. -@end defun - -@defun coding-system-p object -This function returns @code{t} if @var{object} is a coding system -name or @code{nil}. -@end defun - -@defun check-coding-system coding-system -This function checks the validity of @var{coding-system}. -If that is valid, it returns @var{coding-system}. -Otherwise it signals an error with condition @code{coding-system-error}. -@end defun - -@defun coding-system-eol-type coding-system -This function returns the type of end-of-line (a.k.a.@: @dfn{eol}) -conversion used by @var{coding-system}. If @var{coding-system} -specifies a certain eol conversion, the return value is an integer 0, -1, or 2, standing for @code{unix}, @code{dos}, and @code{mac}, -respectively. If @var{coding-system} doesn't specify eol conversion -explicitly, the return value is a vector of coding systems, each one -with one of the possible eol conversion types, like this: - -@lisp -(coding-system-eol-type 'latin-1) - @result{} [latin-1-unix latin-1-dos latin-1-mac] -@end lisp - -@noindent -If this function returns a vector, Emacs will decide, as part of the -text encoding or decoding process, what eol conversion to use. For -decoding, the end-of-line format of the text is auto-detected, and the -eol conversion is set to match it (e.g., DOS-style CRLF format will -imply @code{dos} eol conversion). For encoding, the eol conversion is -taken from the appropriate default coding system (e.g., -@code{default-buffer-file-coding-system} for -@code{buffer-file-coding-system}), or from the default eol conversion -appropriate for the underlying platform. -@end defun - -@defun coding-system-change-eol-conversion coding-system eol-type -This function returns a coding system which is like @var{coding-system} -except for its eol conversion, which is specified by @code{eol-type}. -@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or -@code{nil}. If it is @code{nil}, the returned coding system determines -the end-of-line conversion from the data. - -@var{eol-type} may also be 0, 1 or 2, standing for @code{unix}, -@code{dos} and @code{mac}, respectively. -@end defun - -@defun coding-system-change-text-conversion eol-coding text-coding -This function returns a coding system which uses the end-of-line -conversion of @var{eol-coding}, and the text conversion of -@var{text-coding}. If @var{text-coding} is @code{nil}, it returns -@code{undecided}, or one of its variants according to @var{eol-coding}. -@end defun - -@defun find-coding-systems-region from to -This function returns a list of coding systems that could be used to -encode a text between @var{from} and @var{to}. All coding systems in -the list can safely encode any multibyte characters in that portion of -the text. - -If the text contains no multibyte characters, the function returns the -list @code{(undecided)}. -@end defun - -@defun find-coding-systems-string string -This function returns a list of coding systems that could be used to -encode the text of @var{string}. All coding systems in the list can -safely encode any multibyte characters in @var{string}. If the text -contains no multibyte characters, this returns the list -@code{(undecided)}. -@end defun - -@defun find-coding-systems-for-charsets charsets -This function returns a list of coding systems that could be used to -encode all the character sets in the list @var{charsets}. -@end defun - -@defun detect-coding-region start end &optional highest -This function chooses a plausible coding system for decoding the text -from @var{start} to @var{end}. This text should be a byte sequence -(@pxref{Explicit Encoding}). - -Normally this function returns a list of coding systems that could -handle decoding the text that was scanned. They are listed in order of -decreasing priority. But if @var{highest} is non-@code{nil}, then the -return value is just one coding system, the one that is highest in -priority. - -If the region contains only @acronym{ASCII} characters except for such -ISO-2022 control characters ISO-2022 as @code{ESC}, the value is -@code{undecided} or @code{(undecided)}, or a variant specifying -end-of-line conversion, if that can be deduced from the text. -@end defun - -@defun detect-coding-string string &optional highest -This function is like @code{detect-coding-region} except that it -operates on the contents of @var{string} instead of bytes in the buffer. -@end defun - - @xref{Coding systems for a subprocess,, Process Information}, in -particular the description of the functions -@code{process-coding-system} and @code{set-process-coding-system}, for -how to examine or set the coding systems used for I/O to a subprocess. - -@node User-Chosen Coding Systems -@subsection User-Chosen Coding Systems - -@cindex select safe coding system -@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file -This function selects a coding system for encoding specified text, -asking the user to choose if necessary. Normally the specified text -is the text in the current buffer between @var{from} and @var{to}. If -@var{from} is a string, the string specifies the text to encode, and -@var{to} is ignored. - -If @var{default-coding-system} is non-@code{nil}, that is the first -coding system to try; if that can handle the text, -@code{select-safe-coding-system} returns that coding system. It can -also be a list of coding systems; then the function tries each of them -one by one. After trying all of them, it next tries the current -buffer's value of @code{buffer-file-coding-system} (if it is not -@code{undecided}), then the value of -@code{default-buffer-file-coding-system} and finally the user's most -preferred coding system, which the user can set using the command -@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing -Coding Systems, emacs, The GNU Emacs Manual}). - -If one of those coding systems can safely encode all the specified -text, @code{select-safe-coding-system} chooses it and returns it. -Otherwise, it asks the user to choose from a list of coding systems -which can encode all the text, and returns the user's choice. - -@var{default-coding-system} can also be a list whose first element is -t and whose other elements are coding systems. Then, if no coding -system in the list can handle the text, @code{select-safe-coding-system} -queries the user immediately, without trying any of the three -alternatives described above. - -The optional argument @var{accept-default-p}, if non-@code{nil}, -should be a function to determine whether a coding system selected -without user interaction is acceptable. @code{select-safe-coding-system} -calls this function with one argument, the base coding system of the -selected coding system. If @var{accept-default-p} returns @code{nil}, -@code{select-safe-coding-system} rejects the silently selected coding -system, and asks the user to select a coding system from a list of -possible candidates. - -@vindex select-safe-coding-system-accept-default-p -If the variable @code{select-safe-coding-system-accept-default-p} is -non-@code{nil}, its value overrides the value of -@var{accept-default-p}. - -As a final step, before returning the chosen coding system, -@code{select-safe-coding-system} checks whether that coding system is -consistent with what would be selected if the contents of the region -were read from a file. (If not, this could lead to data corruption in -a file subsequently re-visited and edited.) Normally, -@code{select-safe-coding-system} uses @code{buffer-file-name} as the -file for this purpose, but if @var{file} is non-@code{nil}, it uses -that file instead (this can be relevant for @code{write-region} and -similar functions). If it detects an apparent inconsistency, -@code{select-safe-coding-system} queries the user before selecting the -coding system. -@end defun - - Here are two functions you can use to let the user specify a coding -system, with completion. @xref{Completion}. - -@defun read-coding-system prompt &optional default -This function reads a coding system using the minibuffer, prompting with -string @var{prompt}, and returns the coding system name as a symbol. If -the user enters null input, @var{default} specifies which coding system -to return. It should be a symbol or a string. -@end defun - -@defun read-non-nil-coding-system prompt -This function reads a coding system using the minibuffer, prompting with -string @var{prompt}, and returns the coding system name as a symbol. If -the user tries to enter null input, it asks the user to try again. -@xref{Coding Systems}. -@end defun - -@node Default Coding Systems -@subsection Default Coding Systems - - This section describes variables that specify the default coding -system for certain files or when running certain subprograms, and the -function that I/O operations use to access them. - - The idea of these variables is that you set them once and for all to the -defaults you want, and then do not change them again. To specify a -particular coding system for a particular operation in a Lisp program, -don't change these variables; instead, override them using -@code{coding-system-for-read} and @code{coding-system-for-write} -(@pxref{Specifying Coding Systems}). - -@defvar auto-coding-regexp-alist -This variable is an alist of text patterns and corresponding coding -systems. Each element has the form @code{(@var{regexp} -. @var{coding-system})}; a file whose first few kilobytes match -@var{regexp} is decoded with @var{coding-system} when its contents are -read into a buffer. The settings in this alist take priority over -@code{coding:} tags in the files and the contents of -@code{file-coding-system-alist} (see below). The default value is set -so that Emacs automatically recognizes mail files in Babyl format and -reads them with no code conversions. -@end defvar - -@defvar file-coding-system-alist -This variable is an alist that specifies the coding systems to use for -reading and writing particular files. Each element has the form -@code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular -expression that matches certain file names. The element applies to file -names that match @var{pattern}. - -The @sc{cdr} of the element, @var{coding}, should be either a coding -system, a cons cell containing two coding systems, or a function name (a -symbol with a function definition). If @var{coding} is a coding system, -that coding system is used for both reading the file and writing it. If -@var{coding} is a cons cell containing two coding systems, its @sc{car} -specifies the coding system for decoding, and its @sc{cdr} specifies the -coding system for encoding. - -If @var{coding} is a function name, the function should take one -argument, a list of all arguments passed to -@code{find-operation-coding-system}. It must return a coding system -or a cons cell containing two coding systems. This value has the same -meaning as described above. - -If @var{coding} (or what returned by the above function) is -@code{undecided}, the normal code-detection is performed. -@end defvar - -@defvar process-coding-system-alist -This variable is an alist specifying which coding systems to use for a -subprocess, depending on which program is running in the subprocess. It -works like @code{file-coding-system-alist}, except that @var{pattern} is -matched against the program name used to start the subprocess. The coding -system or systems specified in this alist are used to initialize the -coding systems used for I/O to the subprocess, but you can specify -other coding systems later using @code{set-process-coding-system}. -@end defvar - - @strong{Warning:} Coding systems such as @code{undecided}, which -determine the coding system from the data, do not work entirely reliably -with asynchronous subprocess output. This is because Emacs handles -asynchronous subprocess output in batches, as it arrives. If the coding -system leaves the character code conversion unspecified, or leaves the -end-of-line conversion unspecified, Emacs must try to detect the proper -conversion from one batch at a time, and this does not always work. - - Therefore, with an asynchronous subprocess, if at all possible, use a -coding system which determines both the character code conversion and -the end of line conversion---that is, one like @code{latin-1-unix}, -rather than @code{undecided} or @code{latin-1}. - -@defvar network-coding-system-alist -This variable is an alist that specifies the coding system to use for -network streams. It works much like @code{file-coding-system-alist}, -with the difference that the @var{pattern} in an element may be either a -port number or a regular expression. If it is a regular expression, it -is matched against the network service name used to open the network -stream. -@end defvar - -@defvar default-process-coding-system -This variable specifies the coding systems to use for subprocess (and -network stream) input and output, when nothing else specifies what to -do. - -The value should be a cons cell of the form @code{(@var{input-coding} -. @var{output-coding})}. Here @var{input-coding} applies to input from -the subprocess, and @var{output-coding} applies to output to it. -@end defvar - -@defvar auto-coding-functions -This variable holds a list of functions that try to determine a -coding system for a file based on its undecoded contents. - -Each function in this list should be written to look at text in the -current buffer, but should not modify it in any way. The buffer will -contain undecoded text of parts of the file. Each function should -take one argument, @var{size}, which tells it how many characters to -look at, starting from point. If the function succeeds in determining -a coding system for the file, it should return that coding system. -Otherwise, it should return @code{nil}. - -If a file has a @samp{coding:} tag, that takes precedence, so these -functions won't be called. -@end defvar - -@defun find-operation-coding-system operation &rest arguments -This function returns the coding system to use (by default) for -performing @var{operation} with @var{arguments}. The value has this -form: - -@example -(@var{decoding-system} . @var{encoding-system}) -@end example - -The first element, @var{decoding-system}, is the coding system to use -for decoding (in case @var{operation} does decoding), and -@var{encoding-system} is the coding system for encoding (in case -@var{operation} does encoding). - -The argument @var{operation} is a symbol, one of @code{write-region}, -@code{start-process}, @code{call-process}, @code{call-process-region}, -@code{insert-file-contents}, or @code{open-network-stream}. These are -the names of the Emacs I/O primitives that can do character code and -eol conversion. - -The remaining arguments should be the same arguments that might be given -to the corresponding I/O primitive. Depending on the primitive, one -of those arguments is selected as the @dfn{target}. For example, if -@var{operation} does file I/O, whichever argument specifies the file -name is the target. For subprocess primitives, the process name is the -target. For @code{open-network-stream}, the target is the service name -or port number. - -Depending on @var{operation}, this function looks up the target in -@code{file-coding-system-alist}, @code{process-coding-system-alist}, -or @code{network-coding-system-alist}. If the target is found in the -alist, @code{find-operation-coding-system} returns its association in -the alist; otherwise it returns @code{nil}. - -If @var{operation} is @code{insert-file-contents}, the argument -corresponding to the target may be a cons cell of the form -@code{(@var{filename} . @var{buffer})}). In that case, @var{filename} -is a file name to look up in @code{file-coding-system-alist}, and -@var{buffer} is a buffer that contains the file's contents (not yet -decoded). If @code{file-coding-system-alist} specifies a function to -call for this file, and that function needs to examine the file's -contents (as it usually does), it should examine the contents of -@var{buffer} instead of reading the file. -@end defun - -@node Specifying Coding Systems -@subsection Specifying a Coding System for One Operation - - You can specify the coding system for a specific operation by binding -the variables @code{coding-system-for-read} and/or -@code{coding-system-for-write}. - -@defvar coding-system-for-read -If this variable is non-@code{nil}, it specifies the coding system to -use for reading a file, or for input from a synchronous subprocess. - -It also applies to any asynchronous subprocess or network stream, but in -a different way: the value of @code{coding-system-for-read} when you -start the subprocess or open the network stream specifies the input -decoding method for that subprocess or network stream. It remains in -use for that subprocess or network stream unless and until overridden. - -The right way to use this variable is to bind it with @code{let} for a -specific I/O operation. Its global value is normally @code{nil}, and -you should not globally set it to any other value. Here is an example -of the right way to use the variable: - -@example -;; @r{Read the file with no character code conversion.} -;; @r{Assume @acronym{crlf} represents end-of-line.} -(let ((coding-system-for-read 'emacs-mule-dos)) - (insert-file-contents filename)) -@end example - -When its value is non-@code{nil}, this variable takes precedence over -all other methods of specifying a coding system to use for input, -including @code{file-coding-system-alist}, -@code{process-coding-system-alist} and -@code{network-coding-system-alist}. -@end defvar - -@defvar coding-system-for-write -This works much like @code{coding-system-for-read}, except that it -applies to output rather than input. It affects writing to files, -as well as sending output to subprocesses and net connections. - -When a single operation does both input and output, as do -@code{call-process-region} and @code{start-process}, both -@code{coding-system-for-read} and @code{coding-system-for-write} -affect it. -@end defvar - -@defvar inhibit-eol-conversion -When this variable is non-@code{nil}, no end-of-line conversion is done, -no matter which coding system is specified. This applies to all the -Emacs I/O and subprocess primitives, and to the explicit encoding and -decoding functions (@pxref{Explicit Encoding}). -@end defvar - -@node Explicit Encoding -@subsection Explicit Encoding and Decoding -@cindex encoding in coding systems -@cindex decoding in coding systems - - All the operations that transfer text in and out of Emacs have the -ability to use a coding system to encode or decode the text. -You can also explicitly encode and decode text using the functions -in this section. - - The result of encoding, and the input to decoding, are not ordinary -text. They logically consist of a series of byte values; that is, a -series of characters whose codes are in the range 0 through 255. In a -multibyte buffer or string, character codes 128 through 159 are -represented by multibyte sequences, but this is invisible to Lisp -programs. - - The usual way to read a file into a buffer as a sequence of bytes, so -you can decode the contents explicitly, is with -@code{insert-file-contents-literally} (@pxref{Reading from Files}); -alternatively, specify a non-@code{nil} @var{rawfile} argument when -visiting a file with @code{find-file-noselect}. These methods result in -a unibyte buffer. - - The usual way to use the byte sequence that results from explicitly -encoding text is to copy it to a file or process---for example, to write -it with @code{write-region} (@pxref{Writing to Files}), and suppress -encoding by binding @code{coding-system-for-write} to -@code{no-conversion}. - - Here are the functions to perform explicit encoding or decoding. The -encoding functions produce sequences of bytes; the decoding functions -are meant to operate on sequences of bytes. All of these functions -discard text properties. - -@deffn Command encode-coding-region start end coding-system -This command encodes the text from @var{start} to @var{end} according -to coding system @var{coding-system}. The encoded text replaces the -original text in the buffer. The result of encoding is logically a -sequence of bytes, but the buffer remains multibyte if it was multibyte -before. - -This command returns the length of the encoded text. -@end deffn - -@defun encode-coding-string string coding-system &optional nocopy -This function encodes the text in @var{string} according to coding -system @var{coding-system}. It returns a new string containing the -encoded text, except when @var{nocopy} is non-@code{nil}, in which -case the function may return @var{string} itself if the encoding -operation is trivial. The result of encoding is a unibyte string. -@end defun - -@deffn Command decode-coding-region start end coding-system -This command decodes the text from @var{start} to @var{end} according -to coding system @var{coding-system}. The decoded text replaces the -original text in the buffer. To make explicit decoding useful, the text -before decoding ought to be a sequence of byte values, but both -multibyte and unibyte buffers are acceptable. - -This command returns the length of the decoded text. -@end deffn - -@defun decode-coding-string string coding-system &optional nocopy -This function decodes the text in @var{string} according to coding -system @var{coding-system}. It returns a new string containing the -decoded text, except when @var{nocopy} is non-@code{nil}, in which -case the function may return @var{string} itself if the decoding -operation is trivial. To make explicit decoding useful, the contents -of @var{string} ought to be a sequence of byte values, but a multibyte -string is acceptable. -@end defun - -@defun decode-coding-inserted-region from to filename &optional visit beg end replace -This function decodes the text from @var{from} to @var{to} as if -it were being read from file @var{filename} using @code{insert-file-contents} -using the rest of the arguments provided. - -The normal way to use this function is after reading text from a file -without decoding, if you decide you would rather have decoded it. -Instead of deleting the text and reading it again, this time with -decoding, you can call this function. -@end defun - -@node Terminal I/O Encoding -@subsection Terminal I/O Encoding - - Emacs can decode keyboard input using a coding system, and encode -terminal output. This is useful for terminals that transmit or display -text using a particular encoding such as Latin-1. Emacs does not set -@code{last-coding-system-used} for encoding or decoding for the -terminal. - -@defun keyboard-coding-system -This function returns the coding system that is in use for decoding -keyboard input---or @code{nil} if no coding system is to be used. -@end defun - -@deffn Command set-keyboard-coding-system coding-system -This command specifies @var{coding-system} as the coding system to -use for decoding keyboard input. If @var{coding-system} is @code{nil}, -that means do not decode keyboard input. -@end deffn - -@defun terminal-coding-system -This function returns the coding system that is in use for encoding -terminal output---or @code{nil} for no encoding. -@end defun - -@deffn Command set-terminal-coding-system coding-system -This command specifies @var{coding-system} as the coding system to use -for encoding terminal output. If @var{coding-system} is @code{nil}, -that means do not encode terminal output. -@end deffn - -@node MS-DOS File Types -@subsection MS-DOS File Types -@cindex DOS file types -@cindex MS-DOS file types -@cindex Windows file types -@cindex file types on MS-DOS and Windows -@cindex text files and binary files -@cindex binary files and text files - - On MS-DOS and Microsoft Windows, Emacs guesses the appropriate -end-of-line conversion for a file by looking at the file's name. This -feature classifies files as @dfn{text files} and @dfn{binary files}. By -``binary file'' we mean a file of literal byte values that are not -necessarily meant to be characters; Emacs does no end-of-line conversion -and no character code conversion for them. On the other hand, the bytes -in a text file are intended to represent characters; when you create a -new file whose name implies that it is a text file, Emacs uses DOS -end-of-line conversion. - -@defvar buffer-file-type -This variable, automatically buffer-local in each buffer, records the -file type of the buffer's visited file. When a buffer does not specify -a coding system with @code{buffer-file-coding-system}, this variable is -used to determine which coding system to use when writing the contents -of the buffer. It should be @code{nil} for text, @code{t} for binary. -If it is @code{t}, the coding system is @code{no-conversion}. -Otherwise, @code{undecided-dos} is used. - -Normally this variable is set by visiting a file; it is set to -@code{nil} if the file was visited without any actual conversion. -@end defvar - -@defopt file-name-buffer-file-type-alist -This variable holds an alist for recognizing text and binary files. -Each element has the form (@var{regexp} . @var{type}), where -@var{regexp} is matched against the file name, and @var{type} may be -@code{nil} for text, @code{t} for binary, or a function to call to -compute which. If it is a function, then it is called with a single -argument (the file name) and should return @code{t} or @code{nil}. - -When running on MS-DOS or MS-Windows, Emacs checks this alist to decide -which coding system to use when reading a file. For a text file, -@code{undecided-dos} is used. For a binary file, @code{no-conversion} -is used. - -If no element in this alist matches a given file name, then -@code{default-buffer-file-type} says how to treat the file. -@end defopt - -@defopt default-buffer-file-type -This variable says how to handle files for which -@code{file-name-buffer-file-type-alist} says nothing about the type. - -If this variable is non-@code{nil}, then these files are treated as -binary: the coding system @code{no-conversion} is used. Otherwise, -nothing special is done for them---the coding system is deduced solely -from the file contents, in the usual Emacs fashion. -@end defopt - -@node Input Methods -@section Input Methods -@cindex input methods - - @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII} -characters from the keyboard. Unlike coding systems, which translate -non-@acronym{ASCII} characters to and from encodings meant to be read by -programs, input methods provide human-friendly commands. (@xref{Input -Methods,,, emacs, The GNU Emacs Manual}, for information on how users -use input methods to enter text.) How to define input methods is not -yet documented in this manual, but here we describe how to use them. - - Each input method has a name, which is currently a string; -in the future, symbols may also be usable as input method names. - -@defvar current-input-method -This variable holds the name of the input method now active in the -current buffer. (It automatically becomes local in each buffer when set -in any fashion.) It is @code{nil} if no input method is active in the -buffer now. -@end defvar - -@defopt default-input-method -This variable holds the default input method for commands that choose an -input method. Unlike @code{current-input-method}, this variable is -normally global. -@end defopt - -@deffn Command set-input-method input-method -This command activates input method @var{input-method} for the current -buffer. It also sets @code{default-input-method} to @var{input-method}. -If @var{input-method} is @code{nil}, this command deactivates any input -method for the current buffer. -@end deffn - -@defun read-input-method-name prompt &optional default inhibit-null -This function reads an input method name with the minibuffer, prompting -with @var{prompt}. If @var{default} is non-@code{nil}, that is returned -by default, if the user enters empty input. However, if -@var{inhibit-null} is non-@code{nil}, empty input signals an error. - -The returned value is a string. -@end defun - -@defvar input-method-alist -This variable defines all the supported input methods. -Each element defines one input method, and should have the form: - -@example -(@var{input-method} @var{language-env} @var{activate-func} - @var{title} @var{description} @var{args}...) -@end example - -Here @var{input-method} is the input method name, a string; -@var{language-env} is another string, the name of the language -environment this input method is recommended for. (That serves only for -documentation purposes.) - -@var{activate-func} is a function to call to activate this method. The -@var{args}, if any, are passed as arguments to @var{activate-func}. All -told, the arguments to @var{activate-func} are @var{input-method} and -the @var{args}. - -@var{title} is a string to display in the mode line while this method is -active. @var{description} is a string describing this method and what -it is good for. -@end defvar - - The fundamental interface to input methods is through the -variable @code{input-method-function}. @xref{Reading One Event}, -and @ref{Invoking the Input Method}. - -@node Locales -@section Locales -@cindex locale - - POSIX defines a concept of ``locales'' which control which language -to use in language-related features. These Emacs variables control -how Emacs interacts with these features. - -@defvar locale-coding-system -@cindex keyboard input decoding on X -This variable specifies the coding system to use for decoding system -error messages and---on X Window system only---keyboard input, for -encoding the format argument to @code{format-time-string}, and for -decoding the return value of @code{format-time-string}. -@end defvar - -@defvar system-messages-locale -This variable specifies the locale to use for generating system error -messages. Changing the locale can cause messages to come out in a -different language or in a different orthography. If the variable is -@code{nil}, the locale is specified by environment variables in the -usual POSIX fashion. -@end defvar - -@defvar system-time-locale -This variable specifies the locale to use for formatting time values. -Changing the locale can cause messages to appear according to the -conventions of a different language. If the variable is @code{nil}, the -locale is specified by environment variables in the usual POSIX fashion. -@end defvar - -@defun locale-info item -This function returns locale data @var{item} for the current POSIX -locale, if available. @var{item} should be one of these symbols: - -@table @code -@item codeset -Return the character set as a string (locale item @code{CODESET}). - -@item days -Return a 7-element vector of day names (locale items -@code{DAY_1} through @code{DAY_7}); - -@item months -Return a 12-element vector of month names (locale items @code{MON_1} -through @code{MON_12}). - -@item paper -Return a list @code{(@var{width} @var{height})} for the default paper -size measured in millimeters (locale items @code{PAPER_WIDTH} and -@code{PAPER_HEIGHT}). -@end table - -If the system can't provide the requested information, or if -@var{item} is not one of those symbols, the value is @code{nil}. All -strings in the return value are decoded using -@code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual}, -for more information about locales and locale items. -@end defun - -@ignore - arch-tag: be705bf8-941b-4c35-84fc-ad7d20ddb7cb -@end ignore diff --git a/lispref/numbers.texi b/lispref/numbers.texi deleted file mode 100644 index 4d7f3e7578a..00000000000 --- a/lispref/numbers.texi +++ /dev/null @@ -1,1211 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/numbers -@node Numbers, Strings and Characters, Lisp Data Types, Top -@chapter Numbers -@cindex integers -@cindex numbers - - GNU Emacs supports two numeric data types: @dfn{integers} and -@dfn{floating point numbers}. Integers are whole numbers such as -@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point -numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or -2.71828. They can also be expressed in exponential notation: 1.5e2 -equals 150; in this example, @samp{e2} stands for ten to the second -power, and that is multiplied by 1.5. Floating point values are not -exact; they have a fixed, limited amount of precision. - -@menu -* 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. -@end menu - -@node Integer Basics -@comment node-name, next, previous, up -@section Integer Basics - - The range of values for an integer depends on the machine. The -minimum range is @minus{}268435456 to 268435455 (29 bits; i.e., -@ifnottex --2**28 -@end ifnottex -@tex -@math{-2^{28}} -@end tex -to -@ifnottex -2**28 - 1), -@end ifnottex -@tex -@math{2^{28}-1}), -@end tex -but some machines may provide a wider range. Many examples in this -chapter assume an integer has 29 bits. -@cindex overflow - - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. - -@example - 1 ; @r{The integer 1.} - 1. ; @r{The integer 1.} -+1 ; @r{Also the integer 1.} --1 ; @r{The integer @minus{}1.} - 536870913 ; @r{Also the integer 1, due to overflow.} - 0 ; @r{The integer 0.} --0 ; @r{The integer 0.} -@end example - -@cindex integers in specific radix -@cindex radix for reading an integer -@cindex base for reading an integer -@cindex hex numbers -@cindex octal numbers -@cindex reading numbers in hex, octal, and binary - The syntax for integers in bases other than 10 uses @samp{#} -followed by a letter that specifies the radix: @samp{b} for binary, -@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to -specify radix @var{radix}. Case is not significant for the letter -that specifies the radix. Thus, @samp{#b@var{integer}} reads -@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads -@var{integer} in radix @var{radix}. Allowed values of @var{radix} run -from 2 to 36. For example: - -@example -#b101100 @result{} 44 -#o54 @result{} 44 -#x2c @result{} 44 -#24r1k @result{} 44 -@end example - - To understand how various functions work on integers, especially the -bitwise operators (@pxref{Bitwise Operations}), it is often helpful to -view the numbers in their binary form. - - In 29-bit binary, the decimal integer 5 looks like this: - -@example -0 0000 0000 0000 0000 0000 0000 0101 -@end example - -@noindent -(We have inserted spaces between groups of 4 bits, and two spaces -between groups of 8 bits, to make the binary integer easier to read.) - - The integer @minus{}1 looks like this: - -@example -1 1111 1111 1111 1111 1111 1111 1111 -@end example - -@noindent -@cindex two's complement -@minus{}1 is represented as 29 ones. (This is called @dfn{two's -complement} notation.) - - The negative integer, @minus{}5, is creating by subtracting 4 from -@minus{}1. In binary, the decimal integer 4 is 100. Consequently, -@minus{}5 looks like this: - -@example -1 1111 1111 1111 1111 1111 1111 1011 -@end example - - In this implementation, the largest 29-bit binary integer value is -268,435,455 in decimal. In binary, it looks like this: - -@example -0 1111 1111 1111 1111 1111 1111 1111 -@end example - - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 268,435,455, the value is the -negative integer @minus{}268,435,456: - -@example -(+ 1 268435455) - @result{} -268435456 - @result{} 1 0000 0000 0000 0000 0000 0000 0000 -@end example - - Many of the functions described in this chapter accept markers for -arguments in place of numbers. (@xref{Markers}.) Since the actual -arguments to such functions may be either numbers or markers, we often -give these arguments the name @var{number-or-marker}. When the argument -value is a marker, its position value is used and its buffer is ignored. - -@defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp -can handle. -@end defvar - -@defvar most-negative-fixnum -The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. -@end defvar - -@node Float Basics -@section Floating Point Basics - - Floating point numbers are useful for representing numbers that are -not integral. The precise range of floating point numbers is -machine-specific; it is the same as the range of the C data type -@code{double} on the machine you are using. - - The read-syntax for floating point numbers requires either a decimal -point (with at least one digit following), an exponent, or both. For -example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and -@samp{.15e4} are five ways of writing a floating point number whose -value is 1500. They are all equivalent. You can also use a minus sign -to write negative floating point numbers, as in @samp{-1.0}. - -@cindex @acronym{IEEE} floating point -@cindex positive infinity -@cindex negative infinity -@cindex infinity -@cindex NaN - Most modern computers support the @acronym{IEEE} floating point standard, -which provides for positive infinity and negative infinity as floating point -values. It also provides for a class of values called NaN or -``not-a-number''; numerical functions return such values in cases where -there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a -NaN. For practical purposes, there's no significant difference between -different NaN values in Emacs Lisp, and there's no rule for precisely -which NaN value should be used in a particular case, so Emacs Lisp -doesn't try to distinguish them (but it does report the sign, if you -print it). Here are the read syntaxes for these special floating -point values: - -@table @asis -@item positive infinity -@samp{1.0e+INF} -@item negative infinity -@samp{-1.0e+INF} -@item Not-a-number -@samp{0.0e+NaN} or @samp{-0.0e+NaN}. -@end table - - To test whether a floating point value is a NaN, compare it with -itself using @code{=}. That returns @code{nil} for a NaN, and -@code{t} for any other floating point value. - - The value @code{-0.0} is distinguishable from ordinary zero in -@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and -@code{=} consider them equal values. - - You can use @code{logb} to extract the binary exponent of a floating -point number (or estimate the logarithm of an integer): - -@defun logb number -This function returns the binary exponent of @var{number}. More -precisely, the value is the logarithm of @var{number} base 2, rounded -down to an integer. - -@example -(logb 10) - @result{} 3 -(logb 10.0e20) - @result{} 69 -@end example -@end defun - -@node Predicates on Numbers -@section Type Predicates for Numbers -@cindex predicates for numbers - - The functions in this section test for numbers, or for a specific -type of number. The functions @code{integerp} and @code{floatp} can -take any type of Lisp object as argument (they would not be of much -use otherwise), but the @code{zerop} predicate requires a number as -its argument. See also @code{integer-or-marker-p} and -@code{number-or-marker-p}, in @ref{Predicates on Markers}. - -@defun floatp object -This predicate tests whether its argument is a floating point -number and returns @code{t} if so, @code{nil} otherwise. - -@code{floatp} does not exist in Emacs versions 18 and earlier. -@end defun - -@defun integerp object -This predicate tests whether its argument is an integer, and returns -@code{t} if so, @code{nil} otherwise. -@end defun - -@defun numberp object -This predicate tests whether its argument is a number (either integer or -floating point), and returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun wholenump object -@cindex natural numbers -The @code{wholenump} predicate (whose name comes from the phrase -``whole-number-p'') tests to see whether its argument is a nonnegative -integer, and returns @code{t} if so, @code{nil} otherwise. 0 is -considered non-negative. - -@findex natnump -@code{natnump} is an obsolete synonym for @code{wholenump}. -@end defun - -@defun zerop number -This predicate tests whether its argument is zero, and returns @code{t} -if so, @code{nil} otherwise. The argument must be a number. - -@code{(zerop x)} is equivalent to @code{(= x 0)}. -@end defun - -@node Comparison of Numbers -@section Comparison of Numbers -@cindex number comparison -@cindex comparing numbers - - To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating point -number objects with the same numeric value. If you use @code{eq} to -compare them, then you test whether two values are the same -@emph{object}. By contrast, @code{=} compares only the numeric values -of the objects. - - At present, each integer value has a unique Lisp object in Emacs Lisp. -Therefore, @code{eq} is equivalent to @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing an -unknown value with an integer, because @code{eq} does not report an -error if the unknown value is not a number---it accepts arguments of any -type. By contrast, @code{=} signals an error if the arguments are not -numbers or markers. However, it is a good idea to use @code{=} if you -can, even for comparing integers, just in case we change the -representation of integers in a future Emacs version. - - Sometimes it is useful to compare numbers with @code{equal}; it -treats two numbers as equal if they have the same data type (both -integers, or both floating point) and the same value. By contrast, -@code{=} can treat an integer and a floating point number as equal. -@xref{Equality Predicates}. - - There is another wrinkle: because floating point arithmetic is not -exact, it is often a bad idea to check for equality of two floating -point values. Usually it is better to test for approximate equality. -Here's a function to do this: - -@example -(defvar fuzz-factor 1.0e-6) -(defun approx-equal (x y) - (or (and (= x 0) (= y 0)) - (< (/ (abs (- x y)) - (max (abs x) (abs y))) - fuzz-factor))) -@end example - -@cindex CL note---integers vrs @code{eq} -@quotation -@b{Common Lisp note:} Comparing numbers in Common Lisp always requires -@code{=} because Common Lisp implements multi-word integers, and two -distinct integer objects can have the same numeric value. Emacs Lisp -can have just one integer object for any given value because it has a -limited range of integer values. -@end quotation - -@defun = number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun eql value1 value2 -This function acts like @code{eq} except when both arguments are -numbers. It compares numbers by type and numeric value, so that -@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and -@code{(eql 1 1)} both return @code{t}. -@end defun - -@defun /= number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if they are not, and @code{nil} if they are. -@end defun - -@defun < number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly less than -its second argument. It returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun <= number-or-marker1 number-or-marker2 -This function tests whether its first argument is less than or equal -to its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun > number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly greater -than its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun >= number-or-marker1 number-or-marker2 -This function tests whether its first argument is greater than or -equal to its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun max number-or-marker &rest numbers-or-markers -This function returns the largest of its arguments. -If any of the arguments is floating-point, the value is returned -as floating point, even if it was given as an integer. - -@example -(max 20) - @result{} 20 -(max 1 2.5) - @result{} 2.5 -(max 1 3 2.5) - @result{} 3.0 -@end example -@end defun - -@defun min number-or-marker &rest numbers-or-markers -This function returns the smallest of its arguments. -If any of the arguments is floating-point, the value is returned -as floating point, even if it was given as an integer. - -@example -(min -4 1) - @result{} -4 -@end example -@end defun - -@defun abs number -This function returns the absolute value of @var{number}. -@end defun - -@node Numeric Conversions -@section Numeric Conversions -@cindex rounding in conversions -@cindex number conversions -@cindex converting numbers - -To convert an integer to floating point, use the function @code{float}. - -@defun float number -This returns @var{number} converted to floating point. -If @var{number} is already a floating point number, @code{float} returns -it unchanged. -@end defun - -There are four functions to convert floating point numbers to integers; -they differ in how they round. All accept an argument @var{number} -and an optional argument @var{divisor}. Both arguments may be -integers or floating point numbers. @var{divisor} may also be -@code{nil}. If @var{divisor} is @code{nil} or omitted, these -functions convert @var{number} to an integer, or return it unchanged -if it already is an integer. If @var{divisor} is non-@code{nil}, they -divide @var{number} by @var{divisor} and convert the result to an -integer. An @code{arith-error} results if @var{divisor} is 0. - -@defun truncate number &optional divisor -This returns @var{number}, converted to an integer by rounding towards -zero. - -@example -(truncate 1.2) - @result{} 1 -(truncate 1.7) - @result{} 1 -(truncate -1.2) - @result{} -1 -(truncate -1.7) - @result{} -1 -@end example -@end defun - -@defun floor number &optional divisor -This returns @var{number}, converted to an integer by rounding downward -(towards negative infinity). - -If @var{divisor} is specified, this uses the kind of division -operation that corresponds to @code{mod}, rounding downward. - -@example -(floor 1.2) - @result{} 1 -(floor 1.7) - @result{} 1 -(floor -1.2) - @result{} -2 -(floor -1.7) - @result{} -2 -(floor 5.99 3) - @result{} 1 -@end example -@end defun - -@defun ceiling number &optional divisor -This returns @var{number}, converted to an integer by rounding upward -(towards positive infinity). - -@example -(ceiling 1.2) - @result{} 2 -(ceiling 1.7) - @result{} 2 -(ceiling -1.2) - @result{} -1 -(ceiling -1.7) - @result{} -1 -@end example -@end defun - -@defun round number &optional divisor -This returns @var{number}, converted to an integer by rounding towards the -nearest integer. Rounding a value equidistant between two integers -may choose the integer closer to zero, or it may prefer an even integer, -depending on your machine. - -@example -(round 1.2) - @result{} 1 -(round 1.7) - @result{} 2 -(round -1.2) - @result{} -1 -(round -1.7) - @result{} -2 -@end example -@end defun - -@node Arithmetic Operations -@section Arithmetic Operations -@cindex arithmetic operations - - Emacs Lisp provides the traditional four arithmetic operations: -addition, subtraction, multiplication, and division. Remainder and modulus -functions supplement the division functions. The functions to -add or subtract 1 are provided because they are traditional in Lisp and -commonly used. - - All of these functions except @code{%} return a floating point value -if any argument is floating. - - It is important to note that in Emacs Lisp, arithmetic functions -do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to -@minus{}268435456, depending on your hardware. - -@defun 1+ number-or-marker -This function returns @var{number-or-marker} plus 1. -For example, - -@example -(setq foo 4) - @result{} 4 -(1+ foo) - @result{} 5 -@end example - -This function is not analogous to the C operator @code{++}---it does not -increment a variable. It just computes a sum. Thus, if we continue, - -@example -foo - @result{} 4 -@end example - -If you want to increment the variable, you must use @code{setq}, -like this: - -@example -(setq foo (1+ foo)) - @result{} 5 -@end example -@end defun - -@defun 1- number-or-marker -This function returns @var{number-or-marker} minus 1. -@end defun - -@defun + &rest numbers-or-markers -This function adds its arguments together. When given no arguments, -@code{+} returns 0. - -@example -(+) - @result{} 0 -(+ 1) - @result{} 1 -(+ 1 2 3 4) - @result{} 10 -@end example -@end defun - -@defun - &optional number-or-marker &rest more-numbers-or-markers -The @code{-} function serves two purposes: negation and subtraction. -When @code{-} has a single argument, the value is the negative of the -argument. When there are multiple arguments, @code{-} subtracts each of -the @var{more-numbers-or-markers} from @var{number-or-marker}, -cumulatively. If there are no arguments, the result is 0. - -@example -(- 10 1 2 3 4) - @result{} 0 -(- 10) - @result{} -10 -(-) - @result{} 0 -@end example -@end defun - -@defun * &rest numbers-or-markers -This function multiplies its arguments together, and returns the -product. When given no arguments, @code{*} returns 1. - -@example -(*) - @result{} 1 -(* 1) - @result{} 1 -(* 1 2 3 4) - @result{} 24 -@end example -@end defun - -@defun / dividend divisor &rest divisors -This function divides @var{dividend} by @var{divisor} and returns the -quotient. If there are additional arguments @var{divisors}, then it -divides @var{dividend} by each divisor in turn. Each argument may be a -number or a marker. - -If all the arguments are integers, then the result is an integer too. -This means the result has to be rounded. On most machines, the result -is rounded towards zero after each division, but some machines may round -differently with negative arguments. This is because the Lisp function -@code{/} is implemented using the C division operator, which also -permits machine-dependent rounding. As a practical matter, all known -machines round in the standard fashion. - -@cindex @code{arith-error} in division -If you divide an integer by 0, an @code{arith-error} error is signaled. -(@xref{Errors}.) Floating point division by zero returns either -infinity or a NaN if your machine supports @acronym{IEEE} floating point; -otherwise, it signals an @code{arith-error} error. - -@example -@group -(/ 6 2) - @result{} 3 -@end group -(/ 5 2) - @result{} 2 -(/ 5.0 2) - @result{} 2.5 -(/ 5 2.0) - @result{} 2.5 -(/ 5.0 2.0) - @result{} 2.5 -(/ 25 3 2) - @result{} 4 -@group -(/ -17 6) - @result{} -2 @r{(could in theory be @minus{}3 on some machines)} -@end group -@end example -@end defun - -@defun % dividend divisor -@cindex remainder -This function returns the integer remainder after division of @var{dividend} -by @var{divisor}. The arguments must be integers or markers. - -For negative arguments, the remainder is in principle machine-dependent -since the quotient is; but in practice, all known machines behave alike. - -An @code{arith-error} results if @var{divisor} is 0. - -@example -(% 9 4) - @result{} 1 -(% -9 4) - @result{} -1 -(% 9 -4) - @result{} 1 -(% -9 -4) - @result{} -1 -@end example - -For any two integers @var{dividend} and @var{divisor}, - -@example -@group -(+ (% @var{dividend} @var{divisor}) - (* (/ @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}. -@end defun - -@defun mod dividend divisor -@cindex modulus -This function returns the value of @var{dividend} modulo @var{divisor}; -in other words, the remainder after division of @var{dividend} -by @var{divisor}, but with the same sign as @var{divisor}. -The arguments must be numbers or markers. - -Unlike @code{%}, @code{mod} returns a well-defined result for negative -arguments. It also permits floating point arguments; it rounds the -quotient downward (towards minus infinity) to an integer, and uses that -quotient to compute the remainder. - -An @code{arith-error} results if @var{divisor} is 0. - -@example -@group -(mod 9 4) - @result{} 1 -@end group -@group -(mod -9 4) - @result{} 3 -@end group -@group -(mod 9 -4) - @result{} -3 -@end group -@group -(mod -9 -4) - @result{} -1 -@end group -@group -(mod 5.5 2.5) - @result{} .5 -@end group -@end example - -For any two numbers @var{dividend} and @var{divisor}, - -@example -@group -(+ (mod @var{dividend} @var{divisor}) - (* (floor @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}, subject to rounding error if either -argument is floating point. For @code{floor}, see @ref{Numeric -Conversions}. -@end defun - -@node Rounding Operations -@section Rounding Operations -@cindex rounding without conversion - -The functions @code{ffloor}, @code{fceiling}, @code{fround}, and -@code{ftruncate} take a floating point argument and return a floating -point result whose value is a nearby integer. @code{ffloor} returns the -nearest integer below; @code{fceiling}, the nearest integer above; -@code{ftruncate}, the nearest integer in the direction towards zero; -@code{fround}, the nearest integer. - -@defun ffloor float -This function rounds @var{float} to the next lower integral value, and -returns that value as a floating point number. -@end defun - -@defun fceiling float -This function rounds @var{float} to the next higher integral value, and -returns that value as a floating point number. -@end defun - -@defun ftruncate float -This function rounds @var{float} towards zero to an integral value, and -returns that value as a floating point number. -@end defun - -@defun fround float -This function rounds @var{float} to the nearest integral value, -and returns that value as a floating point number. -@end defun - -@node Bitwise Operations -@section Bitwise Operations on Integers -@cindex bitwise arithmetic -@cindex logical arithmetic - - In a computer, an integer is represented as a binary number, a -sequence of @dfn{bits} (digits which are either zero or one). A bitwise -operation acts on the individual bits of such a sequence. For example, -@dfn{shifting} moves the whole sequence left or right one or more places, -reproducing the same pattern ``moved over.'' - - The bitwise operations in Emacs Lisp apply only to integers. - -@defun lsh integer1 count -@cindex logical shift -@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the -bits in @var{integer1} to the left @var{count} places, or to the right -if @var{count} is negative, bringing zeros into the vacated bits. If -@var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if -@var{integer1} is negative. Contrast this with @code{ash}, below. - -Here are two examples of @code{lsh}, shifting a pattern of bits one -place to the left. We show only the low-order eight bits of the binary -pattern; the rest are all zero. - -@example -@group -(lsh 5 1) - @result{} 10 -;; @r{Decimal 5 becomes decimal 10.} -00000101 @result{} 00001010 - -(lsh 7 1) - @result{} 14 -;; @r{Decimal 7 becomes decimal 14.} -00000111 @result{} 00001110 -@end group -@end example - -@noindent -As the examples illustrate, shifting the pattern of bits one place to -the left produces a number that is twice the value of the previous -number. - -Shifting a pattern of bits two places to the left produces results -like this (with 8-bit binary numbers): - -@example -@group -(lsh 3 2) - @result{} 12 -;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 -@end group -@end example - -On the other hand, shifting one place to the right looks like this: - -@example -@group -(lsh 6 -1) - @result{} 3 -;; @r{Decimal 6 becomes decimal 3.} -00000110 @result{} 00000011 -@end group - -@group -(lsh 5 -1) - @result{} 2 -;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 -@end group -@end example - -@noindent -As the example illustrates, shifting one place to the right divides the -value of a positive integer by two, rounding downward. - -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -268,435,455 produces @minus{}2 on a 29-bit machine: - -@example -(lsh 268435455 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, in the 29-bit implementation, the argument looks like this: - -@example -@group -;; @r{Decimal 268,435,455} -0 1111 1111 1111 1111 1111 1111 1111 -@end group -@end example - -@noindent -which becomes the following when left shifted: - -@example -@group -;; @r{Decimal @minus{}2} -1 1111 1111 1111 1111 1111 1111 1110 -@end group -@end example -@end defun - -@defun ash integer1 count -@cindex arithmetic shift -@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} -to the left @var{count} places, or to the right if @var{count} -is negative. - -@code{ash} gives the same results as @code{lsh} except when -@var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts ones in the empty bit positions on the left, while -@code{lsh} puts zeros in those bit positions. - -Thus, with @code{ash}, shifting the pattern of bits one place to the right -looks like this: - -@example -@group -(ash -6 -1) @result{} -3 -;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1 1111 1111 1111 1111 1111 1111 1010 - @result{} -1 1111 1111 1111 1111 1111 1111 1101 -@end group -@end example - -In contrast, shifting the pattern of bits one place to the right with -@code{lsh} looks like this: - -@example -@group -(lsh -6 -1) @result{} 268435453 -;; @r{Decimal @minus{}6 becomes decimal 268,435,453.} -1 1111 1111 1111 1111 1111 1111 1010 - @result{} -0 1111 1111 1111 1111 1111 1111 1101 -@end group -@end example - -Here are other examples: - -@c !!! Check if lined up in smallbook format! XDVI shows problem -@c with smallbook but not with regular book! --rjc 16mar92 -@smallexample -@group - ; @r{ 29-bit binary values} - -(lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100} -@end group -@group -(ash 5 2) - @result{} 20 -(lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} - @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100} -(ash -5 2) - @result{} -20 -@end group -@group -(lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001} -@end group -@group -(ash 5 -2) - @result{} 1 -@end group -@group -(lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} - @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110} -@end group -@group -(ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} - @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110} -@end group -@end smallexample -@end defun - -@defun logand &rest ints-or-markers -This function returns the ``logical and'' of the arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in all the arguments. (``Set'' means that the value of the bit is 1 -rather than 0.) - -For example, using 4-bit binary numbers, the ``logical and'' of 13 and -12 is 12: 1101 combined with 1100 produces 1100. -In both the binary numbers, the leftmost two bits are set (i.e., they -are 1's), so the leftmost two bits of the returned value are set. -However, for the rightmost two bits, each is zero in at least one of -the arguments, so the rightmost two bits of the returned value are 0's. - -@noindent -Therefore, - -@example -@group -(logand 13 12) - @result{} 12 -@end group -@end example - -If @code{logand} is not passed any argument, it returns a value of -@minus{}1. This number is an identity element for @code{logand} -because its binary representation consists entirely of ones. If -@code{logand} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 29-bit binary values} - -(logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} - @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} -@end group - -@group -(logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} - ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} - @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} -@end group - -@group -(logand) - @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111} -@end group -@end smallexample -@end defun - -@defun logior &rest ints-or-markers -This function returns the ``inclusive or'' of its arguments: the @var{n}th bit -is set in the result if, and only if, the @var{n}th bit is set in at least -one of the arguments. If there are no arguments, the result is zero, -which is an identity element for this operation. If @code{logior} is -passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 29-bit binary values} - -(logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} -@end group - -@group -(logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} - @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111} -@end group -@end smallexample -@end defun - -@defun logxor &rest ints-or-markers -This function returns the ``exclusive or'' of its arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in an odd number of the arguments. If there are no arguments, the -result is 0, which is an identity element for this operation. If -@code{logxor} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 29-bit binary values} - -(logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001} -@end group - -@group -(logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} - @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} -@end group -@end smallexample -@end defun - -@defun lognot integer -This function returns the logical complement of its argument: the @var{n}th -bit is one in the result if, and only if, the @var{n}th bit is zero in -@var{integer}, and vice-versa. - -@example -(lognot 5) - @result{} -6 -;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} -;; @r{becomes} -;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010} -@end example -@end defun - -@node Math Functions -@section Standard Mathematical Functions -@cindex transcendental functions -@cindex mathematical functions -@cindex floating-point functions - - These mathematical functions allow integers as well as floating point -numbers as arguments. - -@defun sin arg -@defunx cos arg -@defunx tan arg -These are the ordinary trigonometric functions, with argument measured -in radians. -@end defun - -@defun asin arg -The value of @code{(asin @var{arg})} is a number between -@ifnottex -@minus{}pi/2 -@end ifnottex -@tex -@math{-\pi/2} -@end tex -and -@ifnottex -pi/2 -@end ifnottex -@tex -@math{\pi/2} -@end tex -(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of -range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. -@end defun - -@defun acos arg -The value of @code{(acos @var{arg})} is a number between 0 and -@ifnottex -pi -@end ifnottex -@tex -@math{\pi} -@end tex -(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out -of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. -@end defun - -@defun atan y &optional x -The value of @code{(atan @var{y})} is a number between -@ifnottex -@minus{}pi/2 -@end ifnottex -@tex -@math{-\pi/2} -@end tex -and -@ifnottex -pi/2 -@end ifnottex -@tex -@math{\pi/2} -@end tex -(exclusive) whose tangent is @var{y}. If the optional second -argument @var{x} is given, the value of @code{(atan y x)} is the -angle in radians between the vector @code{[@var{x}, @var{y}]} and the -@code{X} axis. -@end defun - -@defun exp arg -This is the exponential function; it returns -@tex -@math{e} -@end tex -@ifnottex -@i{e} -@end ifnottex -to the power @var{arg}. -@tex -@math{e} -@end tex -@ifnottex -@i{e} -@end ifnottex -is a fundamental mathematical constant also called the base of natural -logarithms. -@end defun - -@defun log arg &optional base -This function returns the logarithm of @var{arg}, with base @var{base}. -If you don't specify @var{base}, the base -@tex -@math{e} -@end tex -@ifnottex -@i{e} -@end ifnottex -is used. If @var{arg} is negative, it signals a @code{domain-error} -error. -@end defun - -@ignore -@defun expm1 arg -This function returns @code{(1- (exp @var{arg}))}, but it is more -accurate than that when @var{arg} is negative and @code{(exp @var{arg})} -is close to 1. -@end defun - -@defun log1p arg -This function returns @code{(log (1+ @var{arg}))}, but it is more -accurate than that when @var{arg} is so small that adding 1 to it would -lose accuracy. -@end defun -@end ignore - -@defun log10 arg -This function returns the logarithm of @var{arg}, with base 10. If -@var{arg} is negative, it signals a @code{domain-error} error. -@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least -approximately. -@end defun - -@defun expt x y -This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an -integer; in this case, overflow causes truncation, so watch out. -@end defun - -@defun sqrt arg -This returns the square root of @var{arg}. If @var{arg} is negative, -it signals a @code{domain-error} error. -@end defun - -@node Random Numbers -@section Random Numbers -@cindex random numbers - -A deterministic computer program cannot generate true random numbers. -For most purposes, @dfn{pseudo-random numbers} suffice. A series of -pseudo-random numbers is generated in a deterministic fashion. The -numbers are not truly random, but they have certain properties that -mimic a random series. For example, all possible values occur equally -often in a pseudo-random series. - -In Emacs, pseudo-random numbers are generated from a ``seed'' number. -Starting from any given seed, the @code{random} function always -generates the same sequence of numbers. Emacs always starts with the -same seed value, so the sequence of values of @code{random} is actually -the same in each Emacs run! For example, in one operating system, the -first call to @code{(random)} after you start Emacs always returns -@minus{}1457731, and the second one always returns @minus{}7692030. This -repeatability is helpful for debugging. - -If you want random numbers that don't always come out the same, execute -@code{(random t)}. This chooses a new seed based on the current time of -day and on Emacs's process @acronym{ID} number. - -@defun random &optional limit -This function returns a pseudo-random integer. Repeated calls return a -series of pseudo-random integers. - -If @var{limit} is a positive integer, the value is chosen to be -nonnegative and less than @var{limit}. - -If @var{limit} is @code{t}, it means to choose a new seed based on the -current time of day and on Emacs's process @acronym{ID} number. -@c "Emacs'" is incorrect usage! - -On some machines, any integer representable in Lisp may be the result -of @code{random}. On other machines, the result can never be larger -than a certain maximum or less than a certain (negative) minimum. -@end defun - -@ignore - arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e -@end ignore diff --git a/lispref/objects.texi b/lispref/objects.texi deleted file mode 100644 index e75cde70202..00000000000 --- a/lispref/objects.texi +++ /dev/null @@ -1,2036 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/objects -@node Lisp Data Types, Numbers, Introduction, Top -@chapter Lisp Data Types -@cindex object -@cindex Lisp object -@cindex type -@cindex data type - - A Lisp @dfn{object} is a piece of data used and manipulated by Lisp -programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of -possible objects. - - Every object belongs to at least one type. Objects of the same type -have similar structures and may usually be used in the same contexts. -Types can overlap, and objects can belong to two or more types. -Consequently, we can ask whether an object belongs to a particular type, -but not for ``the'' type of an object. - -@cindex primitive type - A few fundamental object types are built into Emacs. These, from -which all other types are constructed, are called @dfn{primitive types}. -Each object belongs to one and only one primitive type. These types -include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol}, -@dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and -@dfn{byte-code function}, plus several special types, such as -@dfn{buffer}, that are related to editing. (@xref{Editing Types}.) - - Each primitive type has a corresponding Lisp function that checks -whether an object is a member of that type. - - Note that Lisp is unlike many other languages in that Lisp objects are -@dfn{self-typing}: the primitive type of the object is implicit in the -object itself. For example, if an object is a vector, nothing can treat -it as a number; Lisp knows it is a vector, not a number. - - In most languages, the programmer must declare the data type of each -variable, and the type is known by the compiler but not represented in -the data. Such type declarations do not exist in Emacs Lisp. A Lisp -variable can have any type of value, and it remembers whatever value -you store in it, type and all. (Actually, a small number of Emacs -Lisp variables can only take on values of a certain type. -@xref{Variables with Restricted Values}.) - - This chapter describes the purpose, printed representation, and read -syntax of each of the standard types in GNU Emacs Lisp. Details on how -to use these types can be found in later chapters. - -@menu -* 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. -@end menu - -@node Printed Representation -@comment node-name, next, previous, up -@section Printed Representation and Read Syntax -@cindex printed representation -@cindex read syntax - - The @dfn{printed representation} of an object is the format of the -output generated by the Lisp printer (the function @code{prin1}) for -that object. Every data type has a unique printed representation. -The @dfn{read syntax} of an object is the format of the input accepted -by the Lisp reader (the function @code{read}) for that object. This -is not necessarily unique; many kinds of object have more than one -syntax. @xref{Read and Print}. - -@cindex hash notation - In most cases, an object's printed representation is also a read -syntax for the object. However, some types have no read syntax, since -it does not make sense to enter objects of these types as constants in -a Lisp program. These objects are printed in @dfn{hash notation}, -which consists of the characters @samp{#<}, a descriptive string -(typically the type name followed by the name of the object), and a -closing @samp{>}. For example: - -@example -(current-buffer) - @result{} #<buffer objects.texi> -@end example - -@noindent -Hash notation cannot be read at all, so the Lisp reader signals the -error @code{invalid-read-syntax} whenever it encounters @samp{#<}. -@kindex invalid-read-syntax - - In other languages, an expression is text; it has no other form. In -Lisp, an expression is primarily a Lisp object and only secondarily the -text that is the object's read syntax. Often there is no need to -emphasize this distinction, but you must keep it in the back of your -mind, or you will occasionally be very confused. - - When you evaluate an expression interactively, the Lisp interpreter -first reads the textual representation of it, producing a Lisp object, -and then evaluates that object (@pxref{Evaluation}). However, -evaluation and reading are separate activities. Reading returns the -Lisp object represented by the text that is read; the object may or may -not be evaluated later. @xref{Input Functions}, for a description of -@code{read}, the basic function for reading objects. - -@node Comments -@comment node-name, next, previous, up -@section Comments -@cindex comments -@cindex @samp{;} in comment - - A @dfn{comment} is text that is written in a program only for the sake -of humans that read the program, and that has no effect on the meaning -of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it -is not within a string or character constant. The comment continues to -the end of line. The Lisp reader discards comments; they do not become -part of the Lisp objects which represent the program within the Lisp -system. - - The @samp{#@@@var{count}} construct, which skips the next @var{count} -characters, is useful for program-generated comments containing binary -data. The Emacs Lisp byte compiler uses this in its output files -(@pxref{Byte Compilation}). It isn't meant for source files, however. - - @xref{Comment Tips}, for conventions for formatting comments. - -@node Programming Types -@section Programming Types -@cindex programming types - - There are two general categories of types in Emacs Lisp: those having -to do with Lisp programming, and those having to do with editing. The -former exist in many Lisp implementations, in one form or another. The -latter are unique to Emacs Lisp. - -@menu -* 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, or property list, and has a unique identity. -* 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. -@end menu - -@node Integer Type -@subsection Integer Type - - The range of values for integers in Emacs Lisp is @minus{}268435456 to -268435455 (29 bits; i.e., -@ifnottex --2**28 -@end ifnottex -@tex -@math{-2^{28}} -@end tex -to -@ifnottex -2**28 - 1) -@end ifnottex -@tex -@math{2^{28}-1}) -@end tex -on most machines. (Some machines may provide a wider range.) It is -important to note that the Emacs Lisp arithmetic functions do not check -for overflow. Thus @code{(1+ 268435455)} is @minus{}268435456 on most -machines. - - The read syntax for integers is a sequence of (base ten) digits with an -optional sign at the beginning and an optional period at the end. The -printed representation produced by the Lisp interpreter never has a -leading @samp{+} or a final @samp{.}. - -@example -@group --1 ; @r{The integer -1.} -1 ; @r{The integer 1.} -1. ; @r{Also the integer 1.} -+1 ; @r{Also the integer 1.} -536870913 ; @r{Also the integer 1 on a 29-bit implementation.} -@end group -@end example - - @xref{Numbers}, for more information. - -@node Floating Point Type -@subsection Floating Point Type - - Floating point numbers are the computer equivalent of scientific -notation; you can think of a floating point number as a fraction -together with a power of ten. The precise number of significant -figures and the range of possible exponents is machine-specific; Emacs -uses the C data type @code{double} to store the value, and internally -this records a power of 2 rather than a power of 10. - - The printed representation for floating point numbers requires either -a decimal point (with at least one digit following), an exponent, or -both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, -@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point -number whose value is 1500. They are all equivalent. - - @xref{Numbers}, for more information. - -@node Character Type -@subsection Character Type -@cindex @acronym{ASCII} character codes - - A @dfn{character} in Emacs Lisp is nothing more than an integer. In -other words, characters are represented by their character codes. For -example, the character @kbd{A} is represented as the @w{integer 65}. - - Individual characters are used occasionally in programs, but it is -more common to work with @emph{strings}, which are sequences composed -of characters. @xref{String Type}. - - Characters in strings, buffers, and files are currently limited to -the range of 0 to 524287---nineteen bits. But not all values in that -range are valid character codes. Codes 0 through 127 are -@acronym{ASCII} codes; the rest are non-@acronym{ASCII} -(@pxref{Non-ASCII Characters}). Characters that represent keyboard -input have a much wider range, to encode modifier keys such as -Control, Meta and Shift. - - There are special functions for producing a human-readable textual -description of a character for the sake of messages. @xref{Describing -Characters}. - -@menu -* Basic Char Syntax:: -* General Escape Syntax:: -* Ctl-Char Syntax:: -* Meta-Char Syntax:: -* Other Char Bits:: -@end menu - -@node Basic Char Syntax -@subsubsection Basic Char Syntax -@cindex read syntax for characters -@cindex printed representation for characters -@cindex syntax for characters -@cindex @samp{?} in character constant -@cindex question mark in character constant - - Since characters are really integers, the printed representation of -a character is a decimal number. This is also a possible read syntax -for a character, but writing characters that way in Lisp programs is -not clear programming. You should @emph{always} use the special read -syntax formats that Emacs Lisp provides for characters. These syntax -formats start with a question mark. - - The usual read syntax for alphanumeric characters is a question mark -followed by the character; thus, @samp{?A} for the character -@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the -character @kbd{a}. - - For example: - -@example -?Q @result{} 81 ?q @result{} 113 -@end example - - You can use the same syntax for punctuation characters, but it is -often a good idea to add a @samp{\} so that the Emacs commands for -editing Lisp code don't get confused. For example, @samp{?\(} is the -way to write the open-paren character. If the character is @samp{\}, -you @emph{must} use a second @samp{\} to quote it: @samp{?\\}. - -@cindex whitespace -@cindex bell character -@cindex @samp{\a} -@cindex backspace -@cindex @samp{\b} -@cindex tab (ASCII character) -@cindex @samp{\t} -@cindex vertical tab -@cindex @samp{\v} -@cindex formfeed -@cindex @samp{\f} -@cindex newline -@cindex @samp{\n} -@cindex return (ASCII character) -@cindex @samp{\r} -@cindex escape (ASCII character) -@cindex @samp{\e} -@cindex space (ASCII character) -@cindex @samp{\s} - You can express the characters control-g, backspace, tab, newline, -vertical tab, formfeed, space, return, del, and escape as @samp{?\a}, -@samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, -@samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively. -(@samp{?\s} followed by a dash has a different meaning---it applies -the ``super'' modifier to the following character.) Thus, - -@example -?\a @result{} 7 ; @r{control-g, @kbd{C-g}} -?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}} -?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}} -?\n @result{} 10 ; @r{newline, @kbd{C-j}} -?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}} -?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}} -?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}} -?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}} -?\s @result{} 32 ; @r{space character, @key{SPC}} -?\\ @result{} 92 ; @r{backslash character, @kbd{\}} -?\d @result{} 127 ; @r{delete character, @key{DEL}} -@end example - -@cindex escape sequence - These sequences which start with backslash are also known as -@dfn{escape sequences}, because backslash plays the role of an -``escape character''; this terminology has nothing to do with the -character @key{ESC}. @samp{\s} is meant for use in character -constants; in string constants, just write the space. - - A backslash is allowed, and harmless, preceding any character without -a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}. -There is no reason to add a backslash before most characters. However, -you should add a backslash before any of the characters -@samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing -Lisp code. You can also add a backslash before whitespace characters such as -space, tab, newline and formfeed. However, it is cleaner to use one of -the easily readable escape sequences, such as @samp{\t} or @samp{\s}, -instead of an actual whitespace character such as a tab or a space. -(If you do write backslash followed by a space, you should write -an extra space after the character constant to separate it from the -following text.) - -@node General Escape Syntax -@subsubsection General Escape Syntax - - In addition to the specific excape sequences for special important -control characters, Emacs provides general categories of escape syntax -that you can use to specify non-ASCII text characters. - -@cindex unicode character escape - For instance, you can specify characters by their Unicode values. -@code{?\u@var{nnnn}} represents a character that maps to the Unicode -code point @samp{U+@var{nnnn}}. There is a slightly different syntax -for specifying characters with code points above @code{#xFFFF}; -@code{\U00@var{nnnnnn}} represents the character whose Unicode code -point is @samp{U+@var{nnnnnn}}, if such a character is supported by -Emacs. If the corresponding character is not supported, Emacs signals -an error. - - This peculiar and inconvenient syntax was adopted for compatibility -with other programming languages. Unlike some other languages, Emacs -Lisp supports this syntax in only character literals and strings. - -@cindex @samp{\} in character constant -@cindex backslash in character constant -@cindex octal character code - The most general read syntax for a character represents the -character code in either octal or hex. To use octal, write a question -mark followed by a backslash and the octal character code (up to three -octal digits); thus, @samp{?\101} for the character @kbd{A}, -@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the -character @kbd{C-b}. Although this syntax can represent any -@acronym{ASCII} character, it is preferred only when the precise octal -value is more important than the @acronym{ASCII} representation. - -@example -@group -?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10 -?\101 @result{} 65 ?A @result{} 65 -@end group -@end example - - To use hex, write a question mark followed by a backslash, @samp{x}, -and the hexadecimal character code. You can use any number of hex -digits, so you can represent any character code in this way. -Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the -character @kbd{C-a}, and @code{?\x8e0} for the Latin-1 character -@iftex -@samp{@`a}. -@end iftex -@ifnottex -@samp{a} with grave accent. -@end ifnottex - -@node Ctl-Char Syntax -@subsubsection Control-Character Syntax - -@cindex control characters - Control characters can be represented using yet another read syntax. -This consists of a question mark followed by a backslash, caret, and the -corresponding non-control character, in either upper or lower case. For -example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the -character @kbd{C-i}, the character whose value is 9. - - Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is -equivalent to @samp{?\^I} and to @samp{?\^i}: - -@example -?\^I @result{} 9 ?\C-I @result{} 9 -@end example - - In strings and buffers, the only control characters allowed are those -that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn -any character into a control character with @samp{C-}. The character -codes for these non-@acronym{ASCII} control characters include the -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -bit as well as the code for the corresponding non-control -character. Ordinary terminals have no way of generating non-@acronym{ASCII} -control characters, but you can generate them straightforwardly using X -and other window systems. - - For historical reasons, Emacs treats the @key{DEL} character as -the control equivalent of @kbd{?}: - -@example -?\^? @result{} 127 ?\C-? @result{} 127 -@end example - -@noindent -As a result, it is currently not possible to represent the character -@kbd{Control-?}, which is a meaningful input character under X, using -@samp{\C-}. It is not easy to change this, as various Lisp files refer -to @key{DEL} in this way. - - For representing control characters to be found in files or strings, -we recommend the @samp{^} syntax; for control characters in keyboard -input, we prefer the @samp{C-} syntax. Which one you use does not -affect the meaning of the program, but may guide the understanding of -people who read it. - -@node Meta-Char Syntax -@subsubsection Meta-Character Syntax - -@cindex meta characters - A @dfn{meta character} is a character typed with the @key{META} -modifier key. The integer that represents such a character has the -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit set. We use high bits for this and other modifiers to make -possible a wide range of basic character codes. - - In a string, the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit attached to an @acronym{ASCII} character indicates a meta -character; thus, the meta characters that can fit in a string have -codes in the range from 128 to 255, and are the meta versions of the -ordinary @acronym{ASCII} characters. (In Emacs versions 18 and older, -this convention was used for characters outside of strings as well.) - - The read syntax for meta characters uses @samp{\M-}. For example, -@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with -octal character codes (see below), with @samp{\C-}, or with any other -syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A}, -or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as -@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}. - -@node Other Char Bits -@subsubsection Other Character Modifier Bits - - The case of a graphic character is indicated by its character code; -for example, @acronym{ASCII} distinguishes between the characters @samp{a} -and @samp{A}. But @acronym{ASCII} has no way to represent whether a control -character is upper case or lower case. Emacs uses the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit to indicate that the shift key was used in typing a control -character. This distinction is possible only when you use X terminals -or other special terminals; ordinary terminals do not report the -distinction to the computer in any way. The Lisp syntax for -the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O} -represents the shifted-control-o character. - -@cindex hyper characters -@cindex super characters -@cindex alt characters - The X Window System defines three other -@anchor{modifier bits}modifier bits that can be set -in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes -for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is -significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents -@kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-} -represents the space character.) -@tex -Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}} -for super and @math{2^{24}} for hyper. -@end tex -@ifnottex -Numerically, the -bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper. -@end ifnottex - -@node Symbol Type -@subsection Symbol Type - - A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The -symbol name serves as the printed representation of the symbol. In -ordinary Lisp use, with one single obarray (@pxref{Creating Symbols}, -a symbol's name is unique---no two symbols have the same name. - - A symbol can serve as a variable, as a function name, or to hold a -property list. Or it may serve only to be distinct from all other Lisp -objects, so that its presence in a data structure may be recognized -reliably. In a given context, usually only one of these uses is -intended. But you can use one symbol in all of these ways, -independently. - - A symbol whose name starts with a colon (@samp{:}) is called a -@dfn{keyword symbol}. These symbols automatically act as constants, and -are normally used only by comparing an unknown symbol with a few -specific alternatives. - -@cindex @samp{\} in symbols -@cindex backslash in symbols - A symbol name can contain any characters whatever. Most symbol names -are written with letters, digits, and the punctuation characters -@samp{-+=*/}. Such names require no special punctuation; the characters -of the name suffice as long as the name does not look like a number. -(If it does, write a @samp{\} at the beginning of the name to force -interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are -less often used but also require no special punctuation. Any other -characters may be included in a symbol's name by escaping them with a -backslash. In contrast to its use in strings, however, a backslash in -the name of a symbol simply quotes the single character that follows the -backslash. For example, in a string, @samp{\t} represents a tab -character; in the name of a symbol, however, @samp{\t} merely quotes the -letter @samp{t}. To have a symbol with a tab character in its name, you -must actually use a tab (preceded with a backslash). But it's rare to -do such a thing. - -@cindex CL note---case of letters -@quotation -@b{Common Lisp note:} In Common Lisp, lower case letters are always -``folded'' to upper case, unless they are explicitly escaped. In Emacs -Lisp, upper case and lower case letters are distinct. -@end quotation - - Here are several examples of symbol names. Note that the @samp{+} in -the fifth example is escaped to prevent it from being read as a number. -This is not necessary in the fourth example because the rest of the name -makes it invalid as a number. - -@example -@group -foo ; @r{A symbol named @samp{foo}.} -FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} -char-to-string ; @r{A symbol named @samp{char-to-string}.} -@end group -@group -1+ ; @r{A symbol named @samp{1+}} - ; @r{(not @samp{+1}, which is an integer).} -@end group -@group -\+1 ; @r{A symbol named @samp{+1}} - ; @r{(not a very readable name).} -@end group -@group -\(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).} -@c the @'s in this next line use up three characters, hence the -@c apparent misalignment of the comment. -+-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.} - ; @r{These characters need not be escaped.} -@end group -@end example - -@ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu -@cindex @samp{#@var{colon}} read syntax -@end ifinfo -@ifnotinfo -@cindex @samp{#:} read syntax -@end ifnotinfo - Normally the Lisp reader interns all symbols (@pxref{Creating -Symbols}). To prevent interning, you can write @samp{#:} before the -name of the symbol. - -@node Sequence Type -@subsection Sequence Types - - A @dfn{sequence} is a Lisp object that represents an ordered set of -elements. There are two kinds of sequence in Emacs Lisp, lists and -arrays. Thus, an object of type list or of type array is also -considered a sequence. - - Arrays are further subdivided into strings, vectors, char-tables and -bool-vectors. Vectors can hold elements of any type, but string -elements must be characters, and bool-vector elements must be @code{t} -or @code{nil}. Char-tables are like vectors except that they are -indexed by any valid character code. The characters in a string can -have text properties like characters in a buffer (@pxref{Text -Properties}), but vectors do not support text properties, even when -their elements happen to be characters. - - Lists, strings and the other array types are different, but they have -important similarities. For example, all have a length @var{l}, and all -have elements which can be indexed from zero to @var{l} minus one. -Several functions, called sequence functions, accept any kind of -sequence. For example, the function @code{elt} can be used to extract -an element of a sequence, given its index. @xref{Sequences Arrays -Vectors}. - - It is generally impossible to read the same sequence twice, since -sequences are always created anew upon reading. If you read the read -syntax for a sequence twice, you get two sequences with equal contents. -There is one exception: the empty list @code{()} always stands for the -same object, @code{nil}. - -@node Cons Cell Type -@subsection Cons Cell and List Types -@cindex address field of register -@cindex decrement field of register -@cindex pointers - - A @dfn{cons cell} is an object that consists of two slots, called the -@sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or -@dfn{refer to} any Lisp object. We also say that ``the @sc{car} of -this cons cell is'' whatever object its @sc{car} slot currently holds, -and likewise for the @sc{cdr}. - -@quotation -A note to C programmers: in Lisp, we do not distinguish between -``holding'' a value and ``pointing to'' the value, because pointers in -Lisp are implicit. -@end quotation - - A @dfn{list} is a series of cons cells, linked together so that the -@sc{cdr} slot of each cons cell holds either the next cons cell or the -empty list. The empty list is actually the symbol @code{nil}. -@xref{Lists}, for functions that work on lists. Because most cons -cells are used as part of lists, the phrase @dfn{list structure} has -come to refer to any structure made out of cons cells. - -@cindex atoms - Because cons cells are so central to Lisp, we also have a word for -``an object which is not a cons cell.'' These objects are called -@dfn{atoms}. - -@cindex parenthesis -@cindex @samp{(@dots{})} in lists - The read syntax and printed representation for lists are identical, and -consist of a left parenthesis, an arbitrary number of elements, and a -right parenthesis. Here are examples of lists: - -@example -(A 2 "A") ; @r{A list of three elements.} -() ; @r{A list of no elements (the empty list).} -nil ; @r{A list of no elements (the empty list).} -("A ()") ; @r{A list of one element: the string @code{"A ()"}.} -(A ()) ; @r{A list of two elements: @code{A} and the empty list.} -(A nil) ; @r{Equivalent to the previous.} -((A B C)) ; @r{A list of one element} - ; @r{(which is a list of three elements).} -@end example - - Upon reading, each object inside the parentheses becomes an element -of the list. That is, a cons cell is made for each element. The -@sc{car} slot of the cons cell holds the element, and its @sc{cdr} -slot refers to the next cons cell of the list, which holds the next -element in the list. The @sc{cdr} slot of the last cons cell is set to -hold @code{nil}. - - The names @sc{car} and @sc{cdr} derive from the history of Lisp. The -original Lisp implementation ran on an @w{IBM 704} computer which -divided words into two parts, called the ``address'' part and the -``decrement''; @sc{car} was an instruction to extract the contents of -the address part of a register, and @sc{cdr} an instruction to extract -the contents of the decrement. By contrast, ``cons cells'' are named -for the function @code{cons} that creates them, which in turn was named -for its purpose, the construction of cells. - -@menu -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. -@end menu - -@node Box Diagrams -@subsubsection Drawing Lists as Box Diagrams -@cindex box diagrams, for lists -@cindex diagrams, boxed, for lists - - A list can be illustrated by a diagram in which the cons cells are -shown as pairs of boxes, like dominoes. (The Lisp reader cannot read -such an illustration; unlike the textual notation, which can be -understood by both humans and computers, the box illustrations can be -understood only by humans.) This picture represents the three-element -list @code{(rose violet buttercup)}: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example - - In this diagram, each box represents a slot that can hold or refer to -any Lisp object. Each pair of boxes represents a cons cell. Each arrow -represents a reference to a Lisp object, either an atom or another cons -cell. - - In this example, the first box, which holds the @sc{car} of the first -cons cell, refers to or ``holds'' @code{rose} (a symbol). The second -box, holding the @sc{cdr} of the first cons cell, refers to the next -pair of boxes, the second cons cell. The @sc{car} of the second cons -cell is @code{violet}, and its @sc{cdr} is the third cons cell. The -@sc{cdr} of the third (and last) cons cell is @code{nil}. - - Here is another diagram of the same list, @code{(rose violet -buttercup)}, sketched in a different manner: - -@smallexample -@group - --------------- ---------------- ------------------- -| car | cdr | | car | cdr | | car | cdr | -| rose | o-------->| violet | o-------->| buttercup | nil | -| | | | | | | | | - --------------- ---------------- ------------------- -@end group -@end smallexample - -@cindex @code{nil} as a list -@cindex empty list - A list with no elements in it is the @dfn{empty list}; it is identical -to the symbol @code{nil}. In other words, @code{nil} is both a symbol -and a list. - - Here is the list @code{(A ())}, or equivalently @code{(A nil)}, -depicted with boxes and arrows: - -@example -@group - --- --- --- --- - | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> A --> nil -@end group -@end example - - Here is a more complex illustration, showing the three-element list, -@code{((pine needles) oak maple)}, the first element of which is a -two-element list: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - | --> oak --> maple - | - | --- --- --- --- - --> | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> pine --> needles -@end group -@end example - - The same list represented in the second box notation looks like this: - -@example -@group - -------------- -------------- -------------- -| car | cdr | | car | cdr | | car | cdr | -| o | o------->| oak | o------->| maple | nil | -| | | | | | | | | | - -- | --------- -------------- -------------- - | - | - | -------------- ---------------- - | | car | cdr | | car | cdr | - ------>| pine | o------->| needles | nil | - | | | | | | - -------------- ---------------- -@end group -@end example - -@node Dotted Pair Notation -@subsubsection Dotted Pair Notation -@cindex dotted pair notation -@cindex @samp{.} in lists - - @dfn{Dotted pair notation} is a general syntax for cons cells that -represents the @sc{car} and @sc{cdr} explicitly. In this syntax, -@code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is -the object @var{a} and whose @sc{cdr} is the object @var{b}. Dotted -pair notation is more general than list syntax because the @sc{cdr} -does not have to be a list. However, it is more cumbersome in cases -where list syntax would work. In dotted pair notation, the list -@samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For -@code{nil}-terminated lists, you can use either notation, but list -notation is usually clearer and more convenient. When printing a -list, the dotted pair notation is only used if the @sc{cdr} of a cons -cell is not a list. - - Here's an example using boxes to illustrate dotted pair notation. -This example shows the pair @code{(rose . violet)}: - -@example -@group - --- --- - | | |--> violet - --- --- - | - | - --> rose -@end group -@end example - - You can combine dotted pair notation with list notation to represent -conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}. -You write a dot after the last element of the list, followed by the -@sc{cdr} of the final cons cell. For example, @code{(rose violet -. buttercup)} is equivalent to @code{(rose . (violet . buttercup))}. -The object looks like this: - -@example -@group - --- --- --- --- - | | |--> | | |--> buttercup - --- --- --- --- - | | - | | - --> rose --> violet -@end group -@end example - - The syntax @code{(rose .@: violet .@: buttercup)} is invalid because -there is nothing that it could mean. If anything, it would say to put -@code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already -used for @code{violet}. - - The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}, -and looks like this: - -@example -@group - --- --- --- --- - | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> rose --> violet -@end group -@end example - - Similarly, the three-element list @code{(rose violet buttercup)} -is equivalent to @code{(rose . (violet . (buttercup)))}. -@ifnottex -It looks like this: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example -@end ifnottex - -@node Association List Type -@comment node-name, next, previous, up -@subsubsection Association List Type - - An @dfn{association list} or @dfn{alist} is a specially-constructed -list whose elements are cons cells. In each element, the @sc{car} is -considered a @dfn{key}, and the @sc{cdr} is considered an -@dfn{associated value}. (In some cases, the associated value is stored -in the @sc{car} of the @sc{cdr}.) Association lists are often used as -stacks, since it is easy to add or remove associations at the front of -the list. - - For example, - -@example -(setq alist-of-colors - '((rose . red) (lily . white) (buttercup . yellow))) -@end example - -@noindent -sets the variable @code{alist-of-colors} to an alist of three elements. In the -first element, @code{rose} is the key and @code{red} is the value. - - @xref{Association Lists}, for a further explanation of alists and for -functions that work on alists. @xref{Hash Tables}, for another kind of -lookup table, which is much faster for handling a large number of keys. - -@node Array Type -@subsection Array Type - - An @dfn{array} is composed of an arbitrary number of slots for -holding or referring to other Lisp objects, arranged in a contiguous block of -memory. Accessing any element of an array takes approximately the same -amount of time. In contrast, accessing an element of a list requires -time proportional to the position of the element in the list. (Elements -at the end of a list take longer to access than elements at the -beginning of a list.) - - Emacs defines four types of array: strings, vectors, bool-vectors, and -char-tables. - - A string is an array of characters and a vector is an array of -arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}. -These kinds of array may have any length up to the largest integer. -Char-tables are sparse arrays indexed by any valid character code; they -can hold arbitrary objects. - - The first element of an array has index zero, the second element has -index 1, and so on. This is called @dfn{zero-origin} indexing. For -example, an array of four elements has indices 0, 1, 2, @w{and 3}. The -largest possible index value is one less than the length of the array. -Once an array is created, its length is fixed. - - All Emacs Lisp arrays are one-dimensional. (Most other programming -languages support multidimensional arrays, but they are not essential; -you can get the same effect with nested one-dimensional arrays.) Each -type of array has its own read syntax; see the following sections for -details. - - The array type is a subset of the sequence type, and contains the -string type, the vector type, the bool-vector type, and the char-table -type. - -@node String Type -@subsection String Type - - A @dfn{string} is an array of characters. Strings are used for many -purposes in Emacs, as can be expected in a text editor; for example, as -the names of Lisp symbols, as messages for the user, and to represent -text extracted from buffers. Strings in Lisp are constants: evaluation -of a string returns the same string. - - @xref{Strings and Characters}, for functions that operate on strings. - -@menu -* Syntax for Strings:: -* Non-ASCII in Strings:: -* Nonprinting Characters:: -* Text Props and Strings:: -@end menu - -@node Syntax for Strings -@subsubsection Syntax for Strings - -@cindex @samp{"} in strings -@cindex double-quote in strings -@cindex @samp{\} in strings -@cindex backslash in strings - The read syntax for strings is a double-quote, an arbitrary number of -characters, and another double-quote, @code{"like this"}. To include a -double-quote in a string, precede it with a backslash; thus, @code{"\""} -is a string containing just a single double-quote character. Likewise, -you can include a backslash by preceding it with another backslash, like -this: @code{"this \\ is a single embedded backslash"}. - -@cindex newline in strings - The newline character is not special in the read syntax for strings; -if you write a new line between the double-quotes, it becomes a -character in the string. But an escaped newline---one that is preceded -by @samp{\}---does not become part of the string; i.e., the Lisp reader -ignores an escaped newline while reading a string. An escaped space -@w{@samp{\ }} is likewise ignored. - -@example -"It is useful to include newlines -in documentation strings, -but the newline is \ -ignored if escaped." - @result{} "It is useful to include newlines -in documentation strings, -but the newline is ignored if escaped." -@end example - -@node Non-ASCII in Strings -@subsubsection Non-@acronym{ASCII} Characters in Strings - - You can include a non-@acronym{ASCII} international character in a string -constant by writing it literally. There are two text representations -for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte -and multibyte. If the string constant is read from a multibyte source, -such as a multibyte buffer or string, or a file that would be visited as -multibyte, then the character is read as a multibyte character, and that -makes the string multibyte. If the string constant is read from a -unibyte source, then the character is read as unibyte and that makes the -string unibyte. - - You can also represent a multibyte non-@acronym{ASCII} character with its -character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many -digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all -greater than 256.) Any character which is not a valid hex digit -terminates this construct. If the next character in the string could be -interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to -terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents -one character, @samp{a} with grave accent. @w{@samp{\ }} in a string -constant is just like backslash-newline; it does not contribute any -character to the string, but it does terminate the preceding hex escape. - - You can represent a unibyte non-@acronym{ASCII} character with its -character code, which must be in the range from 128 (0200 octal) to -255 (0377 octal). If you write all such character codes in octal and -the string contains no other characters forcing it to be multibyte, -this produces a unibyte string. However, using any hex escape in a -string (even for an @acronym{ASCII} character) forces the string to be -multibyte. - - You can also specify characters in a string by their numeric values -in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}). - - @xref{Text Representations}, for more information about the two -text representations. - -@node Nonprinting Characters -@subsubsection Nonprinting Characters in Strings - - You can use the same backslash escape-sequences in a string constant -as in character literals (but do not use the question mark that begins a -character constant). For example, you can write a string containing the -nonprinting characters tab and @kbd{C-a}, with commas and spaces between -them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a -description of the read syntax for characters. - - However, not all of the characters you can write with backslash -escape-sequences are valid in strings. The only control characters that -a string can hold are the @acronym{ASCII} control characters. Strings do not -distinguish case in @acronym{ASCII} control characters. - - Properly speaking, strings cannot hold meta characters; but when a -string is to be used as a key sequence, there is a special convention -that provides a way to represent meta versions of @acronym{ASCII} -characters in a string. If you use the @samp{\M-} syntax to indicate -a meta character in a string constant, this sets the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit of the character in the string. If the string is used in -@code{define-key} or @code{lookup-key}, this numeric code is translated -into the equivalent meta character. @xref{Character Type}. - - Strings cannot hold characters that have the hyper, super, or alt -modifiers. - -@node Text Props and Strings -@subsubsection Text Properties in Strings - - A string can hold properties for the characters it contains, in -addition to the characters themselves. This enables programs that copy -text between strings and buffers to copy the text's properties with no -special effort. @xref{Text Properties}, for an explanation of what text -properties mean. Strings with text properties use a special read and -print syntax: - -@example -#("@var{characters}" @var{property-data}...) -@end example - -@noindent -where @var{property-data} consists of zero or more elements, in groups -of three as follows: - -@example -@var{beg} @var{end} @var{plist} -@end example - -@noindent -The elements @var{beg} and @var{end} are integers, and together specify -a range of indices in the string; @var{plist} is the property list for -that range. For example, - -@example -#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic)) -@end example - -@noindent -represents a string whose textual contents are @samp{foo bar}, in which -the first three characters have a @code{face} property with value -@code{bold}, and the last three have a @code{face} property with value -@code{italic}. (The fourth character has no text properties, so its -property list is @code{nil}. It is not actually necessary to mention -ranges with @code{nil} as the property list, since any characters not -mentioned in any range will default to having no properties.) - -@node Vector Type -@subsection Vector Type - - A @dfn{vector} is a one-dimensional array of elements of any type. It -takes a constant amount of time to access any element of a vector. (In -a list, the access time of an element is proportional to the distance of -the element from the beginning of the list.) - - The printed representation of a vector consists of a left square -bracket, the elements, and a right square bracket. This is also the -read syntax. Like numbers and strings, vectors are considered constants -for evaluation. - -@example -[1 "two" (three)] ; @r{A vector of three elements.} - @result{} [1 "two" (three)] -@end example - - @xref{Vectors}, for functions that work with vectors. - -@node Char-Table Type -@subsection Char-Table Type - - A @dfn{char-table} is a one-dimensional array of elements of any type, -indexed by character codes. Char-tables have certain extra features to -make them more useful for many jobs that involve assigning information -to character codes---for example, a char-table can have a parent to -inherit from, a default value, and a small number of extra slots to use for -special purposes. A char-table can also specify a single value for -a whole character set. - - The printed representation of a char-table is like a vector -except that there is an extra @samp{#^} at the beginning. - - @xref{Char-Tables}, for special functions to operate on char-tables. -Uses of char-tables include: - -@itemize @bullet -@item -Case tables (@pxref{Case Tables}). - -@item -Character category tables (@pxref{Categories}). - -@item -Display tables (@pxref{Display Tables}). - -@item -Syntax tables (@pxref{Syntax Tables}). -@end itemize - -@node Bool-Vector Type -@subsection Bool-Vector Type - - A @dfn{bool-vector} is a one-dimensional array of elements that -must be @code{t} or @code{nil}. - - The printed representation of a bool-vector is like a string, except -that it begins with @samp{#&} followed by the length. The string -constant that follows actually specifies the contents of the bool-vector -as a bitmap---each ``character'' in the string contains 8 bits, which -specify the next 8 elements of the bool-vector (1 stands for @code{t}, -and 0 for @code{nil}). The least significant bits of the character -correspond to the lowest indices in the bool-vector. - -@example -(make-bool-vector 3 t) - @result{} #&3"^G" -(make-bool-vector 3 nil) - @result{} #&3"^@@" -@end example - -@noindent -These results make sense, because the binary code for @samp{C-g} is -111 and @samp{C-@@} is the character with code 0. - - If the length is not a multiple of 8, the printed representation -shows extra elements, but these extras really make no difference. For -instance, in the next example, the two bool-vectors are equal, because -only the first 3 bits are used: - -@example -(equal #&3"\377" #&3"\007") - @result{} t -@end example - -@node Hash Table Type -@subsection Hash Table Type - - A hash table is a very fast kind of lookup table, somewhat like an -alist in that it maps keys to corresponding values, but much faster. -Hash tables have no read syntax, and print using hash notation. -@xref{Hash Tables}, for functions that operate on hash tables. - -@example -(make-hash-table) - @result{} #<hash-table 'eql nil 0/65 0x83af980> -@end example - -@node Function Type -@subsection Function Type - - Lisp functions are executable code, just like functions in other -programming languages. In Lisp, unlike most languages, functions are -also Lisp objects. A non-compiled function in Lisp is a lambda -expression: that is, a list whose first element is the symbol -@code{lambda} (@pxref{Lambda Expressions}). - - In most programming languages, it is impossible to have a function -without a name. In Lisp, a function has no intrinsic name. A lambda -expression can be called as a function even though it has no name; to -emphasize this, we also call it an @dfn{anonymous function} -(@pxref{Anonymous Functions}). A named function in Lisp is just a -symbol with a valid function in its function cell (@pxref{Defining -Functions}). - - Most of the time, functions are called when their names are written in -Lisp expressions in Lisp programs. However, you can construct or obtain -a function object at run time and then call it with the primitive -functions @code{funcall} and @code{apply}. @xref{Calling Functions}. - -@node Macro Type -@subsection Macro Type - - A @dfn{Lisp macro} is a user-defined construct that extends the Lisp -language. It is represented as an object much like a function, but with -different argument-passing semantics. A Lisp macro has the form of a -list whose first element is the symbol @code{macro} and whose @sc{cdr} -is a Lisp function object, including the @code{lambda} symbol. - - Lisp macro objects are usually defined with the built-in -@code{defmacro} function, but any list that begins with @code{macro} is -a macro as far as Emacs is concerned. @xref{Macros}, for an explanation -of how to write a macro. - - @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard -Macros}) are entirely different things. When we use the word ``macro'' -without qualification, we mean a Lisp macro, not a keyboard macro. - -@node Primitive Function Type -@subsection Primitive Function Type -@cindex special forms - - A @dfn{primitive function} is a function callable from Lisp but -written in the C programming language. Primitive functions are also -called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is -derived from ``subroutine.'') Most primitive functions evaluate all -their arguments when they are called. A primitive function that does -not evaluate all its arguments is called a @dfn{special form} -(@pxref{Special Forms}).@refill - - It does not matter to the caller of a function whether the function is -primitive. However, this does matter if you try to redefine a primitive -with a function written in Lisp. The reason is that the primitive -function may be called directly from C code. Calls to the redefined -function from Lisp will use the new definition, but calls from C code -may still use the built-in definition. Therefore, @strong{we discourage -redefinition of primitive functions}. - - The term @dfn{function} refers to all Emacs functions, whether written -in Lisp or C. @xref{Function Type}, for information about the -functions written in Lisp. - - Primitive functions have no read syntax and print in hash notation -with the name of the subroutine. - -@example -@group -(symbol-function 'car) ; @r{Access the function cell} - ; @r{of the symbol.} - @result{} #<subr car> -(subrp (symbol-function 'car)) ; @r{Is this a primitive function?} - @result{} t ; @r{Yes.} -@end group -@end example - -@node Byte-Code Type -@subsection Byte-Code Function Type - -The byte compiler produces @dfn{byte-code function objects}. -Internally, a byte-code function object is much like a vector; however, -the evaluator handles this data type specially when it appears as a -function to be called. @xref{Byte Compilation}, for information about -the byte compiler. - -The printed representation and read syntax for a byte-code function -object is like that for a vector, with an additional @samp{#} before the -opening @samp{[}. - -@node Autoload Type -@subsection Autoload Type - - An @dfn{autoload object} is a list whose first element is the symbol -@code{autoload}. It is stored as the function definition of a symbol, -where it serves as a placeholder for the real definition. The autoload -object says that the real definition is found in a file of Lisp code -that should be loaded when necessary. It contains the name of the file, -plus some other information about the real definition. - - After the file has been loaded, the symbol should have a new function -definition that is not an autoload object. The new definition is then -called as if it had been there to begin with. From the user's point of -view, the function call works as expected, using the function definition -in the loaded file. - - An autoload object is usually created with the function -@code{autoload}, which stores the object in the function cell of a -symbol. @xref{Autoload}, for more details. - -@node Editing Types -@section Editing Types -@cindex editing types - - The types in the previous section are used for general programming -purposes, and most of them are common to most Lisp dialects. Emacs Lisp -provides several additional data types for purposes connected with -editing. - -@menu -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* 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. -@end menu - -@node Buffer Type -@subsection Buffer Type - - A @dfn{buffer} is an object that holds text that can be edited -(@pxref{Buffers}). Most buffers hold the contents of a disk file -(@pxref{Files}) so they can be edited, but some are used for other -purposes. Most buffers are also meant to be seen by the user, and -therefore displayed, at some time, in a window (@pxref{Windows}). But a -buffer need not be displayed in any window. - - The contents of a buffer are much like a string, but buffers are not -used like strings in Emacs Lisp, and the available operations are -different. For example, you can insert text efficiently into an -existing buffer, altering the buffer's contents, whereas ``inserting'' -text into a string requires concatenating substrings, and the result is -an entirely new string object. - - Each buffer has a designated position called @dfn{point} -(@pxref{Positions}). At any time, one buffer is the @dfn{current -buffer}. Most editing commands act on the contents of the current -buffer in the neighborhood of point. Many of the standard Emacs -functions manipulate or test the characters in the current buffer; a -whole chapter in this manual is devoted to describing these functions -(@pxref{Text}). - - Several other data structures are associated with each buffer: - -@itemize @bullet -@item -a local syntax table (@pxref{Syntax Tables}); - -@item -a local keymap (@pxref{Keymaps}); and, - -@item -a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}). - -@item -overlays (@pxref{Overlays}). - -@item -text properties for the text in the buffer (@pxref{Text Properties}). -@end itemize - -@noindent -The local keymap and variable list contain entries that individually -override global bindings or values. These are used to customize the -behavior of programs in different buffers, without actually changing the -programs. - - A buffer may be @dfn{indirect}, which means it shares the text -of another buffer, but presents it differently. @xref{Indirect Buffers}. - - Buffers have no read syntax. They print in hash notation, showing the -buffer name. - -@example -@group -(current-buffer) - @result{} #<buffer objects.texi> -@end group -@end example - -@node Marker Type -@subsection Marker Type - - A @dfn{marker} denotes a position in a specific buffer. Markers -therefore have two components: one for the buffer, and one for the -position. Changes in the buffer's text automatically relocate the -position value as necessary to ensure that the marker always points -between the same two characters in the buffer. - - Markers have no read syntax. They print in hash notation, giving the -current character position and the name of the buffer. - -@example -@group -(point-marker) - @result{} #<marker at 10779 in objects.texi> -@end group -@end example - -@xref{Markers}, for information on how to test, create, copy, and move -markers. - -@node Window Type -@subsection Window Type - - A @dfn{window} describes the portion of the terminal screen that Emacs -uses to display a buffer. Every window has one associated buffer, whose -contents appear in the window. By contrast, a given buffer may appear -in one window, no window, or several windows. - - Though many windows may exist simultaneously, at any time one window -is designated the @dfn{selected window}. This is the window where the -cursor is (usually) displayed when Emacs is ready for a command. The -selected window usually displays the current buffer, but this is not -necessarily the case. - - Windows are grouped on the screen into frames; each window belongs to -one and only one frame. @xref{Frame Type}. - - Windows have no read syntax. They print in hash notation, giving the -window number and the name of the buffer being displayed. The window -numbers exist to identify windows uniquely, since the buffer displayed -in any given window can change frequently. - -@example -@group -(selected-window) - @result{} #<window 1 on objects.texi> -@end group -@end example - - @xref{Windows}, for a description of the functions that work on windows. - -@node Frame Type -@subsection Frame Type - - A @dfn{frame} is a screen area that contains one or more Emacs -windows; we also use the term ``frame'' to refer to the Lisp object -that Emacs uses to refer to the screen area. - - Frames have no read syntax. They print in hash notation, giving the -frame's title, plus its address in core (useful to identify the frame -uniquely). - -@example -@group -(selected-frame) - @result{} #<frame emacs@@psilocin.gnu.org 0xdac80> -@end group -@end example - - @xref{Frames}, for a description of the functions that work on frames. - -@node Window Configuration Type -@subsection Window Configuration Type -@cindex window layout in a frame - - A @dfn{window configuration} stores information about the positions, -sizes, and contents of the windows in a frame, so you can recreate the -same arrangement of windows later. - - Window configurations do not have a read syntax; their print syntax -looks like @samp{#<window-configuration>}. @xref{Window -Configurations}, for a description of several functions related to -window configurations. - -@node Frame Configuration Type -@subsection Frame Configuration Type -@cindex screen layout -@cindex window layout, all frames - - A @dfn{frame configuration} stores information about the positions, -sizes, and contents of the windows in all frames. It is actually -a list whose @sc{car} is @code{frame-configuration} and whose -@sc{cdr} is an alist. Each alist element describes one frame, -which appears as the @sc{car} of that element. - - @xref{Frame Configurations}, for a description of several functions -related to frame configurations. - -@node Process Type -@subsection Process Type - - The word @dfn{process} usually means a running program. Emacs itself -runs in a process of this sort. However, in Emacs Lisp, a process is a -Lisp object that designates a subprocess created by the Emacs process. -Programs such as shells, GDB, ftp, and compilers, running in -subprocesses of Emacs, extend the capabilities of Emacs. - - An Emacs subprocess takes textual input from Emacs and returns textual -output to Emacs for further manipulation. Emacs can also send signals -to the subprocess. - - Process objects have no read syntax. They print in hash notation, -giving the name of the process: - -@example -@group -(process-list) - @result{} (#<process shell>) -@end group -@end example - -@xref{Processes}, for information about functions that create, delete, -return information about, send input or signals to, and receive output -from processes. - -@node Stream Type -@subsection Stream Type - - A @dfn{stream} is an object that can be used as a source or sink for -characters---either to supply characters for input or to accept them as -output. Many different types can be used this way: markers, buffers, -strings, and functions. Most often, input streams (character sources) -obtain characters from the keyboard, a buffer, or a file, and output -streams (character sinks) send characters to a buffer, such as a -@file{*Help*} buffer, or to the echo area. - - The object @code{nil}, in addition to its other meanings, may be used -as a stream. It stands for the value of the variable -@code{standard-input} or @code{standard-output}. Also, the object -@code{t} as a stream specifies input using the minibuffer -(@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo -Area}). - - Streams have no special printed representation or read syntax, and -print as whatever primitive type they are. - - @xref{Read and Print}, for a description of functions -related to streams, including parsing and printing functions. - -@node Keymap Type -@subsection Keymap Type - - A @dfn{keymap} maps keys typed by the user to commands. This mapping -controls how the user's command input is executed. A keymap is actually -a list whose @sc{car} is the symbol @code{keymap}. - - @xref{Keymaps}, for information about creating keymaps, handling prefix -keys, local as well as global keymaps, and changing key bindings. - -@node Overlay Type -@subsection Overlay Type - - An @dfn{overlay} specifies properties that apply to a part of a -buffer. Each overlay applies to a specified range of the buffer, and -contains a property list (a list whose elements are alternating property -names and values). Overlay properties are used to present parts of the -buffer temporarily in a different display style. Overlays have no read -syntax, and print in hash notation, giving the buffer name and range of -positions. - - @xref{Overlays}, for how to create and use overlays. - -@node Circular Objects -@section Read Syntax for Circular Objects -@cindex circular structure, read syntax -@cindex shared structure, read syntax -@cindex @samp{#@var{n}=} read syntax -@cindex @samp{#@var{n}#} read syntax - - To represent shared or circular structures within a complex of Lisp -objects, you can use the reader constructs @samp{#@var{n}=} and -@samp{#@var{n}#}. - - Use @code{#@var{n}=} before an object to label it for later reference; -subsequently, you can use @code{#@var{n}#} to refer the same object in -another place. Here, @var{n} is some integer. For example, here is how -to make a list in which the first element recurs as the third element: - -@example -(#1=(a) b #1#) -@end example - -@noindent -This differs from ordinary syntax such as this - -@example -((a) b (a)) -@end example - -@noindent -which would result in a list whose first and third elements -look alike but are not the same Lisp object. This shows the difference: - -@example -(prog1 nil - (setq x '(#1=(a) b #1#))) -(eq (nth 0 x) (nth 2 x)) - @result{} t -(setq x '((a) b (a))) -(eq (nth 0 x) (nth 2 x)) - @result{} nil -@end example - - You can also use the same syntax to make a circular structure, which -appears as an ``element'' within itself. Here is an example: - -@example -#1=(a #1#) -@end example - -@noindent -This makes a list whose second element is the list itself. -Here's how you can see that it really works: - -@example -(prog1 nil - (setq x '#1=(a #1#))) -(eq x (cadr x)) - @result{} t -@end example - - The Lisp printer can produce this syntax to record circular and shared -structure in a Lisp object, if you bind the variable @code{print-circle} -to a non-@code{nil} value. @xref{Output Variables}. - -@node Type Predicates -@section Type Predicates -@cindex type checking -@kindex wrong-type-argument - - The Emacs Lisp interpreter itself does not perform type checking on -the actual arguments passed to functions when they are called. It could -not do so, since function arguments in Lisp do not have declared data -types, as they do in other programming languages. It is therefore up to -the individual function to test whether each actual argument belongs to -a type that the function can use. - - All built-in functions do check the types of their actual arguments -when appropriate, and signal a @code{wrong-type-argument} error if an -argument is of the wrong type. For example, here is what happens if you -pass an argument to @code{+} that it cannot handle: - -@example -@group -(+ 2 'a) - @error{} Wrong type argument: number-or-marker-p, a -@end group -@end example - -@cindex type predicates -@cindex testing types - If you want your program to handle different types differently, you -must do explicit type checking. The most common way to check the type -of an object is to call a @dfn{type predicate} function. Emacs has a -type predicate for each type, as well as some predicates for -combinations of types. - - A type predicate function takes one argument; it returns @code{t} if -the argument belongs to the appropriate type, and @code{nil} otherwise. -Following a general Lisp convention for predicate functions, most type -predicates' names end with @samp{p}. - - Here is an example which uses the predicates @code{listp} to check for -a list and @code{symbolp} to check for a symbol. - -@example -(defun add-on (x) - (cond ((symbolp x) - ;; If X is a symbol, put it on LIST. - (setq list (cons x list))) - ((listp x) - ;; If X is a list, add its elements to LIST. - (setq list (append x list))) - (t - ;; We handle only symbols and lists. - (error "Invalid argument %s in add-on" x)))) -@end example - - Here is a table of predefined type predicates, in alphabetical order, -with references to further information. - -@table @code -@item atom -@xref{List-related Predicates, atom}. - -@item arrayp -@xref{Array Functions, arrayp}. - -@item bool-vector-p -@xref{Bool-Vectors, bool-vector-p}. - -@item bufferp -@xref{Buffer Basics, bufferp}. - -@item byte-code-function-p -@xref{Byte-Code Type, byte-code-function-p}. - -@item case-table-p -@xref{Case Tables, case-table-p}. - -@item char-or-string-p -@xref{Predicates for Strings, char-or-string-p}. - -@item char-table-p -@xref{Char-Tables, char-table-p}. - -@item commandp -@xref{Interactive Call, commandp}. - -@item consp -@xref{List-related Predicates, consp}. - -@item display-table-p -@xref{Display Tables, display-table-p}. - -@item floatp -@xref{Predicates on Numbers, floatp}. - -@item frame-configuration-p -@xref{Frame Configurations, frame-configuration-p}. - -@item frame-live-p -@xref{Deleting Frames, frame-live-p}. - -@item framep -@xref{Frames, framep}. - -@item functionp -@xref{Functions, functionp}. - -@item hash-table-p -@xref{Other Hash, hash-table-p}. - -@item integer-or-marker-p -@xref{Predicates on Markers, integer-or-marker-p}. - -@item integerp -@xref{Predicates on Numbers, integerp}. - -@item keymapp -@xref{Creating Keymaps, keymapp}. - -@item keywordp -@xref{Constant Variables}. - -@item listp -@xref{List-related Predicates, listp}. - -@item markerp -@xref{Predicates on Markers, markerp}. - -@item wholenump -@xref{Predicates on Numbers, wholenump}. - -@item nlistp -@xref{List-related Predicates, nlistp}. - -@item numberp -@xref{Predicates on Numbers, numberp}. - -@item number-or-marker-p -@xref{Predicates on Markers, number-or-marker-p}. - -@item overlayp -@xref{Overlays, overlayp}. - -@item processp -@xref{Processes, processp}. - -@item sequencep -@xref{Sequence Functions, sequencep}. - -@item stringp -@xref{Predicates for Strings, stringp}. - -@item subrp -@xref{Function Cells, subrp}. - -@item symbolp -@xref{Symbols, symbolp}. - -@item syntax-table-p -@xref{Syntax Tables, syntax-table-p}. - -@item user-variable-p -@xref{Defining Variables, user-variable-p}. - -@item vectorp -@xref{Vectors, vectorp}. - -@item window-configuration-p -@xref{Window Configurations, window-configuration-p}. - -@item window-live-p -@xref{Deleting Windows, window-live-p}. - -@item windowp -@xref{Basic Windows, windowp}. - -@item booleanp -@xref{nil and t, booleanp}. - -@item string-or-null-p -@xref{Predicates for Strings, string-or-null-p}. -@end table - - The most general way to check the type of an object is to call the -function @code{type-of}. Recall that each object belongs to one and -only one primitive type; @code{type-of} tells you which one (@pxref{Lisp -Data Types}). But @code{type-of} knows nothing about non-primitive -types. In most cases, it is more convenient to use type predicates than -@code{type-of}. - -@defun type-of object -This function returns a symbol naming the primitive type of -@var{object}. The value is one of the symbols @code{symbol}, -@code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector}, -@code{char-table}, @code{bool-vector}, @code{hash-table}, @code{subr}, -@code{compiled-function}, @code{marker}, @code{overlay}, @code{window}, -@code{buffer}, @code{frame}, @code{process}, or -@code{window-configuration}. - -@example -(type-of 1) - @result{} integer -@group -(type-of 'nil) - @result{} symbol -(type-of '()) ; @r{@code{()} is @code{nil}.} - @result{} symbol -(type-of '(x)) - @result{} cons -@end group -@end example -@end defun - -@node Equality Predicates -@section Equality Predicates -@cindex equality - - Here we describe two functions that test for equality between any two -objects. Other functions test equality between objects of specific -types, e.g., strings. For these predicates, see the appropriate chapter -describing the data type. - -@defun eq object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} are -the same object, @code{nil} otherwise. - -@code{eq} returns @code{t} if @var{object1} and @var{object2} are -integers with the same value. Also, since symbol names are normally -unique, if the arguments are symbols with the same name, they are -@code{eq}. For other types (e.g., lists, vectors, strings), two -arguments with the same contents or elements are not necessarily -@code{eq} to each other: they are @code{eq} only if they are the same -object, meaning that a change in the contents of one will be reflected -by the same change in the contents of the other. - -@example -@group -(eq 'foo 'foo) - @result{} t -@end group - -@group -(eq 456 456) - @result{} t -@end group - -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(setq foo '(1 (2 (3)))) - @result{} (1 (2 (3))) -(eq foo foo) - @result{} t -(eq foo '(1 (2 (3)))) - @result{} nil -@end group - -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -The @code{make-symbol} function returns an uninterned symbol, distinct -from the symbol that is used if you write the name in a Lisp expression. -Distinct symbols with the same name are not @code{eq}. @xref{Creating -Symbols}. - -@example -@group -(eq (make-symbol "foo") 'foo) - @result{} nil -@end group -@end example -@end defun - -@defun equal object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} have -equal components, @code{nil} otherwise. Whereas @code{eq} tests if its -arguments are the same object, @code{equal} looks inside nonidentical -arguments to see if their elements or contents are the same. So, if two -objects are @code{eq}, they are @code{equal}, but the converse is not -always true. - -@example -@group -(equal 'foo 'foo) - @result{} t -@end group - -@group -(equal 456 456) - @result{} t -@end group - -@group -(equal "asdf" "asdf") - @result{} t -@end group -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(equal '(1 (2 (3))) '(1 (2 (3)))) - @result{} t -@end group -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(equal [(1 2) 3] [(1 2) 3]) - @result{} t -@end group -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(equal (point-marker) (point-marker)) - @result{} t -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -Comparison of strings is case-sensitive, but does not take account of -text properties---it compares only the characters in the strings. For -technical reasons, a unibyte string and a multibyte string are -@code{equal} if and only if they contain the same sequence of -character codes and all these codes are either in the range 0 through -127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). -(@pxref{Text Representations}). - -@example -@group -(equal "asdf" "ASDF") - @result{} nil -@end group -@end example - -However, two distinct buffers are never considered @code{equal}, even if -their textual contents are the same. -@end defun - - The test for equality is implemented recursively; for example, given -two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})} -returns @code{t} if and only if both the expressions below return -@code{t}: - -@example -(equal (car @var{x}) (car @var{y})) -(equal (cdr @var{x}) (cdr @var{y})) -@end example - -Because of this recursive method, circular lists may therefore cause -infinite recursion (leading to an error). - -@ignore - arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096 -@end ignore diff --git a/lispref/os.texi b/lispref/os.texi deleted file mode 100644 index 08f94b427eb..00000000000 --- a/lispref/os.texi +++ /dev/null @@ -1,2004 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/os -@node System Interface, Antinews, Display, Top -@chapter Operating System Interface - - This chapter is about starting and getting out of Emacs, access to -values in the operating system environment, and terminal input, output, -and flow control. - - @xref{Building Emacs}, for related information. See also -@ref{Display}, for additional operating system status information -pertaining to the terminal and the screen. - -@menu -* Starting Up:: Customizing Emacs startup 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 calendrical data, and 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. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording 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. -@end menu - -@node Starting Up -@section Starting Up Emacs - - This section describes what Emacs does when it is started, and how you -can customize these actions. - -@menu -* Startup Summary:: Sequence of actions Emacs performs at startup. -* 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. -@end menu - -@node Startup Summary -@subsection Summary: Sequence of Actions at Startup -@cindex initialization of Emacs -@cindex startup of Emacs -@cindex @file{startup.el} - - The order of operations performed (in @file{startup.el}) by Emacs when -it is started up is as follows: - -@enumerate -@item -It adds subdirectories to @code{load-path}, by running the file named -@file{subdirs.el} in each directory in the list. Normally this file -adds the directory's subdirectories to the list, and these will be -scanned in their turn. The files @file{subdirs.el} are normally -generated automatically by Emacs installation. - -@item -It sets the language environment and the terminal coding system, -if requested by environment variables such as @code{LANG}. - -@item -It loads the initialization library for the window system, if you are -using a window system. This library's name is -@file{term/@var{windowsystem}-win.el}. - -@item -It processes the initial options. (Some of them are handled -even earlier than this.) - -@item -It initializes the window frame and faces, if appropriate. - -@item -It runs the normal hook @code{before-init-hook}. - -@item -It loads the library @file{site-start} (if any), unless the option -@samp{-Q} (or @samp{--no-site-file}) was specified. The library's file -name is usually @file{site-start.el}. -@cindex @file{site-start.el} - -@item -It loads your init file (usually @file{~/.emacs}), unless the option -@samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was -specified on the command line. The @samp{-u} option can specify -another user whose home directory should be used instead of @file{~}. - -@item -It loads the library @file{default} (if any), unless -@code{inhibit-default-init} is non-@code{nil}. (This is not done in -@samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on the -command line.) The library's file name is usually @file{default.el}. -@cindex @file{default.el} - -@item -It runs the normal hook @code{after-init-hook}. - -@item -It sets the major mode according to @code{initial-major-mode}, provided -the buffer @samp{*scratch*} is still current and still in Fundamental -mode. - -@item -It loads the terminal-specific Lisp file, if any, except when in batch -mode or using a window system. - -@item -It displays the initial echo area message, unless you have suppressed -that with @code{inhibit-startup-echo-area-message}. - -@item -It processes the action arguments from the command line. - -@item -It runs @code{emacs-startup-hook} and then @code{term-setup-hook}. - -@item -It calls @code{frame-notice-user-settings}, which modifies the -parameters of the selected frame according to whatever the init files -specify. - -@item -It runs @code{window-setup-hook}. @xref{Window Systems}. - -@item -It displays copyleft, nonwarranty, and basic use information, provided -the value of @code{inhibit-startup-message} is @code{nil}, you didn't -specify @samp{--no-splash} or @samp{-Q}. -@end enumerate - -@defopt inhibit-startup-message -This variable inhibits the initial startup messages (the nonwarranty, -etc.). If it is non-@code{nil}, then the messages are not printed. - -This variable exists so you can set it in your personal init file, once -you are familiar with the contents of the startup message. Do not set -this variable in the init file of a new user, or in a way that affects -more than one user, because that would prevent new users from receiving -the information they are supposed to see. -@end defopt - -@defopt inhibit-startup-echo-area-message -This variable controls the display of the startup echo area message. -You can suppress the startup echo area message by adding text with this -form to your init file: - -@example -(setq inhibit-startup-echo-area-message - "@var{your-login-name}") -@end example - -Emacs explicitly checks for an expression as shown above in your init -file; your login name must appear in the expression as a Lisp string -constant. Other methods of setting -@code{inhibit-startup-echo-area-message} to the same value do not -inhibit the startup message. - -This way, you can easily inhibit the message for yourself if you wish, -but thoughtless copying of your init file will not inhibit the message -for someone else. -@end defopt - -@node Init File -@subsection The Init File, @file{.emacs} -@cindex init file -@cindex @file{.emacs} - - When you start Emacs, it normally attempts to load your @dfn{init -file}, a file in your home directory. Its normal name is -@file{.emacs}, but you can also call it @file{.emacs.el}. -Alternatively, you can use a file named @file{init.el} in a -subdirectory @file{.emacs.d}. Whichever place you use, you can also -compile the file (@pxref{Byte Compilation}); then the actual file -loaded will be @file{.emacs.elc} or @file{init.elc}. - - The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u} -control whether and where to find the init file; @samp{-q} (and the -stronger @samp{-Q}) says not to load an init file, while @samp{-u -@var{user}} says to load @var{user}'s init file instead of yours. -@xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither -option is specified, Emacs uses the @code{LOGNAME} environment -variable, or the @code{USER} (most systems) or @code{USERNAME} (MS -systems) variable, to find your home directory and thus your init -file; this way, even if you have su'd, Emacs still loads your own init -file. If those environment variables are absent, though, Emacs uses -your user-id to find your home directory. - -@cindex default init file - A site may have a @dfn{default init file}, which is the library -named @file{default.el}. Emacs finds the @file{default.el} file -through the standard search path for libraries (@pxref{How Programs Do -Loading}). The Emacs distribution does not come with this file; sites -may provide one for local customizations. If the default init file -exists, it is loaded whenever you start Emacs, except in batch mode or -if @samp{-q} (or @samp{-Q}) is specified. But your own personal init -file, if any, is loaded first; if it sets @code{inhibit-default-init} -to a non-@code{nil} value, then Emacs does not subsequently load the -@file{default.el} file. - - Another file for site-customization is @file{site-start.el}. Emacs -loads this @emph{before} the user's init file. You can inhibit the -loading of this file with the option @samp{--no-site-file}. - -@defvar site-run-file -This variable specifies the site-customization file to load before the -user's init file. Its normal value is @code{"site-start"}. The only -way you can change it with real effect is to do so before dumping -Emacs. -@end defvar - - @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for -examples of how to make various commonly desired customizations in your -@file{.emacs} file. - -@defopt inhibit-default-init -This variable prevents Emacs from loading the default initialization -library file for your session of Emacs. If its value is non-@code{nil}, -then the default library is not loaded. The default value is -@code{nil}. -@end defopt - -@defvar before-init-hook -This normal hook is run, once, just before loading all the init files -(the user's init file, @file{default.el}, and/or @file{site-start.el}). -(The only way to change it with real effect is before dumping Emacs.) -@end defvar - -@defvar after-init-hook -This normal hook is run, once, just after loading all the init files -(the user's init file, @file{default.el}, and/or @file{site-start.el}), -before loading the terminal-specific library and processing the -command-line action arguments. -@end defvar - -@defvar emacs-startup-hook -This normal hook is run, once, just after handling the command line -arguments, just before @code{term-setup-hook}. -@end defvar - -@defvar user-init-file -This variable holds the absolute file name of the user's init file. If the -actual init file loaded is a compiled file, such as @file{.emacs.elc}, -the value refers to the corresponding source file. -@end defvar - -@defvar user-emacs-directory -This variable holds the name of the @file{.emacs.d} directory. It is -ordinarily @file{~/.emacs.d}, but differs on some platforms. -@end defvar - -@node Terminal-Specific -@subsection Terminal-Specific Initialization -@cindex terminal-specific initialization - - Each terminal type can have its own Lisp library that Emacs loads when -run on that type of terminal. The library's name is constructed by -concatenating the value of the variable @code{term-file-prefix} and the -terminal type (specified by the environment variable @code{TERM}). -Normally, @code{term-file-prefix} has the value -@code{"term/"}; changing this is not recommended. Emacs finds the file -in the normal manner, by searching the @code{load-path} directories, and -trying the @samp{.elc} and @samp{.el} suffixes. - -@cindex Termcap - The usual function of a terminal-specific library is to enable -special keys to send sequences that Emacs can recognize. It may also -need to set or add to @code{function-key-map} if the Termcap or -Terminfo entry does not specify all the terminal's function keys. -@xref{Terminal Input}. - - When the name of the terminal type contains a hyphen, and no library -is found whose name is identical to the terminal's name, Emacs strips -from the terminal's name the last hyphen and everything that follows -it, and tries again. This process is repeated until Emacs finds a -matching library or until there are no more hyphens in the name (the -latter means the terminal doesn't have any library specific to it). -Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30} -libraries, Emacs will try the same library @file{term/aaa.el} for -terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the -library can evaluate @code{(getenv "TERM")} to find the full name of -the terminal type.@refill - - Your init file can prevent the loading of the -terminal-specific library by setting the variable -@code{term-file-prefix} to @code{nil}. This feature is useful when -experimenting with your own peculiar customizations. - - You can also arrange to override some of the actions of the -terminal-specific library by setting the variable -@code{term-setup-hook}. This is a normal hook which Emacs runs using -@code{run-hooks} at the end of Emacs initialization, after loading both -your init file and any terminal-specific libraries. You can -use this variable to define initializations for terminals that do not -have their own libraries. @xref{Hooks}. - -@defvar term-file-prefix -@cindex @code{TERM} environment variable -If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads -a terminal-specific initialization file as follows: - -@example -(load (concat term-file-prefix (getenv "TERM"))) -@end example - -@noindent -You may set the @code{term-file-prefix} variable to @code{nil} in your -init file if you do not wish to load the -terminal-initialization file. To do this, put the following in -your init file: @code{(setq term-file-prefix nil)}. - -On MS-DOS, if the environment variable @code{TERM} is not set, Emacs -uses @samp{internal} as the terminal type. -@end defvar - -@defvar term-setup-hook -This variable is a normal hook that Emacs runs after loading your -init file, the default initialization file (if any) and the -terminal-specific Lisp file. - -You can use @code{term-setup-hook} to override the definitions made by a -terminal-specific file. -@end defvar - - See @code{window-setup-hook} in @ref{Window Systems}, for a related -feature. - -@node Command-Line Arguments -@subsection Command-Line Arguments -@cindex command-line arguments - - You can use command-line arguments to request various actions when you -start Emacs. Since you do not need to start Emacs more than once per -day, and will often leave your Emacs session running longer than that, -command-line arguments are hardly ever used. As a practical matter, it -is best to avoid making the habit of using them, since this habit would -encourage you to kill and restart Emacs unnecessarily often. These -options exist for two reasons: to be compatible with other editors (for -invocation by other programs) and to enable shell scripts to run -specific Lisp programs. - - This section describes how Emacs processes command-line arguments, -and how you can customize them. - -@ignore - (Note that some other editors require you to start afresh each time -you want to edit a file. With this kind of editor, you will probably -specify the file as a command-line argument. The recommended way to -use GNU Emacs is to start it only once, just after you log in, and do -all your editing in the same Emacs process. Each time you want to edit -a different file, you visit it with the existing Emacs, which eventually -comes to have many files in it ready for editing. Usually you do not -kill the Emacs until you are about to log out.) -@end ignore - -@defun command-line -This function parses the command line that Emacs was called with, -processes it, loads the user's init file and displays the -startup messages. -@end defun - -@defvar command-line-processed -The value of this variable is @code{t} once the command line has been -processed. - -If you redump Emacs by calling @code{dump-emacs}, you may wish to set -this variable to @code{nil} first in order to cause the new dumped Emacs -to process its new command-line arguments. -@end defvar - -@defvar command-switch-alist -@cindex switches on command line -@cindex options on command line -@cindex command-line options -The value of this variable is an alist of user-defined command-line -options and associated handler functions. This variable exists so you -can add elements to it. - -A @dfn{command-line option} is an argument on the command line, which -has the form: - -@example --@var{option} -@end example - -The elements of the @code{command-switch-alist} look like this: - -@example -(@var{option} . @var{handler-function}) -@end example - -The @sc{car}, @var{option}, is a string, the name of a command-line -option (not including the initial hyphen). The @var{handler-function} -is called to handle @var{option}, and receives the option name as its -sole argument. - -In some cases, the option is followed in the command line by an -argument. In these cases, the @var{handler-function} can find all the -remaining command-line arguments in the variable -@code{command-line-args-left}. (The entire list of command-line -arguments is in @code{command-line-args}.) - -The command-line arguments are parsed by the @code{command-line-1} -function in the @file{startup.el} file. See also @ref{Emacs -Invocation, , Command Line Arguments for Emacs Invocation, emacs, The -GNU Emacs Manual}. -@end defvar - -@defvar command-line-args -The value of this variable is the list of command-line arguments passed -to Emacs. -@end defvar - -@defvar command-line-functions -This variable's value is a list of functions for handling an -unrecognized command-line argument. Each time the next argument to be -processed has no special meaning, the functions in this list are called, -in order of appearance, until one of them returns a non-@code{nil} -value. - -These functions are called with no arguments. They can access the -command-line argument under consideration through the variable -@code{argi}, which is bound temporarily at this point. The remaining -arguments (not including the current one) are in the variable -@code{command-line-args-left}. - -When a function recognizes and processes the argument in @code{argi}, it -should return a non-@code{nil} value to say it has dealt with that -argument. If it has also dealt with some of the following arguments, it -can indicate that by deleting them from @code{command-line-args-left}. - -If all of these functions return @code{nil}, then the argument is used -as a file name to visit. -@end defvar - -@node Getting Out -@section Getting Out of Emacs -@cindex exiting Emacs - - There are two ways to get out of Emacs: you can kill the Emacs job, -which exits permanently, or you can suspend it, which permits you to -reenter the Emacs process later. As a practical matter, you seldom kill -Emacs---only when you are about to log out. Suspending is much more -common. - -@menu -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. -@end menu - -@node Killing Emacs -@comment node-name, next, previous, up -@subsection Killing Emacs -@cindex killing Emacs - - Killing Emacs means ending the execution of the Emacs process. The -parent process normally resumes control. The low-level primitive for -killing Emacs is @code{kill-emacs}. - -@defun kill-emacs &optional exit-data -This function exits the Emacs process and kills it. - -If @var{exit-data} is an integer, then it is used as the exit status -of the Emacs process. (This is useful primarily in batch operation; see -@ref{Batch Mode}.) - -If @var{exit-data} is a string, its contents are stuffed into the -terminal input buffer so that the shell (or whatever program next reads -input) can read them. -@end defun - - All the information in the Emacs process, aside from files that have -been saved, is lost when the Emacs process is killed. Because killing -Emacs inadvertently can lose a lot of work, Emacs queries for -confirmation before actually terminating if you have buffers that need -saving or subprocesses that are running. This is done in the function -@code{save-buffers-kill-emacs}, the higher level function from which -@code{kill-emacs} is usually called. - -@defvar kill-emacs-query-functions -After asking the standard questions, @code{save-buffers-kill-emacs} -calls the functions in the list @code{kill-emacs-query-functions}, in -order of appearance, with no arguments. These functions can ask for -additional confirmation from the user. If any of them returns -@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and -does not run the remaining functions in this hook. Calling -@code{kill-emacs} directly does not run this hook. -@end defvar - -@defvar kill-emacs-hook -This variable is a normal hook; once @code{save-buffers-kill-emacs} is -finished with all file saving and confirmation, it calls -@code{kill-emacs} which runs the functions in this hook. -@code{kill-emacs} does not run this hook in batch mode. - -@code{kill-emacs} may be invoked directly (that is not via -@code{save-buffers-kill-emacs}) if the terminal is disconnected, or in -similar situations where interaction with the user is not possible. -Thus, if your hook needs to interact with the user, put it on -@code{kill-emacs-query-functions}; if it needs to run regardless of -how Emacs is killed, put it on @code{kill-emacs-hook}. -@end defvar - -@node Suspending Emacs -@subsection Suspending Emacs -@cindex suspending Emacs - - @dfn{Suspending Emacs} means stopping Emacs temporarily and returning -control to its superior process, which is usually the shell. This -allows you to resume editing later in the same Emacs process, with the -same buffers, the same kill ring, the same undo history, and so on. To -resume Emacs, use the appropriate command in the parent shell---most -likely @code{fg}. - - Some operating systems do not support suspension of jobs; on these -systems, ``suspension'' actually creates a new shell temporarily as a -subprocess of Emacs. Then you would exit the shell to return to Emacs. - - Suspension is not useful with window systems, because the Emacs job -may not have a parent that can resume it again, and in any case you can -give input to some other job such as a shell merely by moving to a -different window. Therefore, suspending is not allowed when Emacs is using -a window system (X, MS Windows, or Mac). - -@defun suspend-emacs &optional string -This function stops Emacs and returns control to the superior process. -If and when the superior process resumes Emacs, @code{suspend-emacs} -returns @code{nil} to its caller in Lisp. - -If @var{string} is non-@code{nil}, its characters are sent to be read -as terminal input by Emacs's superior shell. The characters in -@var{string} are not echoed by the superior shell; only the results -appear. - -Before suspending, @code{suspend-emacs} runs the normal hook -@code{suspend-hook}. - -After the user resumes Emacs, @code{suspend-emacs} runs the normal hook -@code{suspend-resume-hook}. @xref{Hooks}. - -The next redisplay after resumption will redraw the entire screen, -unless the variable @code{no-redraw-on-reenter} is non-@code{nil} -(@pxref{Refresh Screen}). - -In the following example, note that @samp{pwd} is not echoed after -Emacs is suspended. But it is read and executed by the shell. - -@smallexample -@group -(suspend-emacs) - @result{} nil -@end group - -@group -(add-hook 'suspend-hook - (function (lambda () - (or (y-or-n-p - "Really suspend? ") - (error "Suspend canceled"))))) - @result{} (lambda nil - (or (y-or-n-p "Really suspend? ") - (error "Suspend canceled"))) -@end group -@group -(add-hook 'suspend-resume-hook - (function (lambda () (message "Resumed!")))) - @result{} (lambda nil (message "Resumed!")) -@end group -@group -(suspend-emacs "pwd") - @result{} nil -@end group -@group ----------- Buffer: Minibuffer ---------- -Really suspend? @kbd{y} ----------- Buffer: Minibuffer ---------- -@end group - -@group ----------- Parent Shell ---------- -lewis@@slug[23] % /user/lewis/manual -lewis@@slug[24] % fg -@end group - -@group ----------- Echo Area ---------- -Resumed! -@end group -@end smallexample -@end defun - -@defvar suspend-hook -This variable is a normal hook that Emacs runs before suspending. -@end defvar - -@defvar suspend-resume-hook -This variable is a normal hook that Emacs runs on resuming -after a suspension. -@end defvar - -@node System Environment -@section Operating System Environment -@cindex operating system environment - - Emacs provides access to variables in the operating system environment -through various functions. These variables include the name of the -system, the user's @acronym{UID}, and so on. - -@defvar system-configuration -This variable holds the standard GNU configuration name for the -hardware/software configuration of your system, as a string. The -convenient way to test parts of this string is with -@code{string-match}. -@end defvar - -@cindex system type and name -@defvar system-type -The value of this variable is a symbol indicating the type of operating -system Emacs is operating on. Here is a table of the possible values: - -@table @code -@item alpha-vms -VMS on the Alpha. - -@item aix-v3 -AIX. - -@item berkeley-unix -Berkeley BSD. - -@item cygwin -Cygwin. - -@item dgux -Data General DGUX operating system. - -@item gnu -the GNU system (using the GNU kernel, which consists of the HURD and Mach). - -@item gnu/linux -A GNU/Linux system---that is, a variant GNU system, using the Linux -kernel. (These systems are the ones people often call ``Linux,'' but -actually Linux is just the kernel, not the whole system.) - -@item hpux -Hewlett-Packard HPUX operating system. - -@item irix -Silicon Graphics Irix system. - -@item ms-dos -Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for -MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on -MS-Windows. - -@item next-mach -NeXT Mach-based system. - -@item rtu -Masscomp RTU, UCB universe. - -@item unisoft-unix -UniSoft UniPlus. - -@item usg-unix-v -AT&T System V. - -@item vax-vms -VAX VMS. - -@item windows-nt -Microsoft windows NT. The same executable supports Windows 9X, but the -value of @code{system-type} is @code{windows-nt} in either case. - -@item xenix -SCO Xenix 386. -@end table - -We do not wish to add new symbols to make finer distinctions unless it -is absolutely necessary! In fact, we hope to eliminate some of these -alternatives in the future. We recommend using -@code{system-configuration} to distinguish between different operating -systems. -@end defvar - -@defun system-name -This function returns the name of the machine you are running on. -@example -(system-name) - @result{} "www.gnu.org" -@end example -@end defun - - The symbol @code{system-name} is a variable as well as a function. In -fact, the function returns whatever value the variable -@code{system-name} currently holds. Thus, you can set the variable -@code{system-name} in case Emacs is confused about the name of your -system. The variable is also useful for constructing frame titles -(@pxref{Frame Titles}). - -@defvar mail-host-address -If this variable is non-@code{nil}, it is used instead of -@code{system-name} for purposes of generating email addresses. For -example, it is used when constructing the default value of -@code{user-mail-address}. @xref{User Identification}. (Since this is -done when Emacs starts up, the value actually used is the one saved when -Emacs was dumped. @xref{Building Emacs}.) -@end defvar - -@deffn Command getenv var -@cindex environment variable access -This function returns the value of the environment variable @var{var}, -as a string. @var{var} should be a string. If @var{var} is undefined -in the environment, @code{getenv} returns @code{nil}. If returns -@samp{""} if @var{var} is set but null. Within Emacs, the environment -variable values are kept in the Lisp variable @code{process-environment}. - -@example -@group -(getenv "USER") - @result{} "lewis" -@end group - -@group -lewis@@slug[10] % printenv -PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin -USER=lewis -@end group -@group -TERM=ibmapa16 -SHELL=/bin/csh -HOME=/user/lewis -@end group -@end example -@end deffn - -@c Emacs 19 feature -@deffn Command setenv variable &optional value -This command sets the value of the environment variable named -@var{variable} to @var{value}. @var{variable} should be a string. -Internally, Emacs Lisp can handle any string. However, normally -@var{variable} should be a valid shell identifier, that is, a sequence -of letters, digits and underscores, starting with a letter or -underscore. Otherwise, errors may occur if subprocesses of Emacs try -to access the value of @var{variable}. If @var{value} is omitted or -@code{nil}, @code{setenv} removes @var{variable} from the environment. -Otherwise, @var{value} should be a string. - -@code{setenv} works by modifying @code{process-environment}; binding -that variable with @code{let} is also reasonable practice. - -@code{setenv} returns the new value of @var{variable}, or @code{nil} -if it removed @var{variable} from the environment. -@end deffn - -@defvar process-environment -This variable is a list of strings, each describing one environment -variable. The functions @code{getenv} and @code{setenv} work by means -of this variable. - -@smallexample -@group -process-environment -@result{} ("l=/usr/stanford/lib/gnuemacs/lisp" - "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" - "USER=lewis" -@end group -@group - "TERM=ibmapa16" - "SHELL=/bin/csh" - "HOME=/user/lewis") -@end group -@end smallexample - -If @code{process-environment} contains ``duplicate'' elements that -specify the same environment variable, the first of these elements -specifies the variable, and the other ``duplicates'' are ignored. -@end defvar - -@defvar path-separator -This variable holds a string which says which character separates -directories in a search path (as found in an environment variable). Its -value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS -and MS-Windows. -@end defvar - -@defun parse-colon-path path -This function takes a search path string such as would be the value of -the @code{PATH} environment variable, and splits it at the separators, -returning a list of directory names. @code{nil} in this list stands for -``use the current directory.'' Although the function's name says -``colon,'' it actually uses the value of @code{path-separator}. - -@example -(parse-colon-path ":/foo:/bar") - @result{} (nil "/foo/" "/bar/") -@end example -@end defun - -@defvar invocation-name -This variable holds the program name under which Emacs was invoked. The -value is a string, and does not include a directory name. -@end defvar - -@defvar invocation-directory -This variable holds the directory from which the Emacs executable was -invoked, or perhaps @code{nil} if that directory cannot be determined. -@end defvar - -@defvar installation-directory -If non-@code{nil}, this is a directory within which to look for the -@file{lib-src} and @file{etc} subdirectories. This is non-@code{nil} -when Emacs can't find those directories in their standard installed -locations, but can find them in a directory related somehow to the one -containing the Emacs executable. -@end defvar - -@defun load-average &optional use-float -This function returns the current 1-minute, 5-minute, and 15-minute load -averages, in a list. - -By default, the values are integers that are 100 times the system load -averages, which indicate the average number of processes trying to run. -If @var{use-float} is non-@code{nil}, then they are returned -as floating point numbers and without multiplying by 100. - -If it is impossible to obtain the load average, this function signals -an error. On some platforms, access to load averages requires -installing Emacs as setuid or setgid so that it can read kernel -information, and that usually isn't advisable. - -If the 1-minute load average is available, but the 5- or 15-minute -averages are not, this function returns a shortened list containing -the available averages. - -@example -@group -(load-average) - @result{} (169 48 36) -@end group -@group -(load-average t) - @result{} (1.69 0.48 0.36) -@end group - -@group -lewis@@rocky[5] % uptime - 11:55am up 1 day, 19:37, 3 users, - load average: 1.69, 0.48, 0.36 -@end group -@end example -@end defun - -@defun emacs-pid -This function returns the process @acronym{ID} of the Emacs process, -as an integer. -@end defun - -@defvar tty-erase-char -This variable holds the erase character that was selected -in the system's terminal driver, before Emacs was started. -The value is @code{nil} if Emacs is running under a window system. -@end defvar - -@defun setprv privilege-name &optional setp getprv -This function sets or resets a VMS privilege. (It does not exist on -other systems.) The first argument is the privilege name, as a string. -The second argument, @var{setp}, is @code{t} or @code{nil}, indicating -whether the privilege is to be turned on or off. Its default is -@code{nil}. The function returns @code{t} if successful, @code{nil} -otherwise. - -If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv} -does not change the privilege, but returns @code{t} or @code{nil} -indicating whether the privilege is currently enabled. -@end defun - -@node User Identification -@section User Identification -@cindex user identification - -@defvar init-file-user -This variable says which user's init files should be used by -Emacs---or @code{nil} if none. @code{""} stands for the user who -originally logged in. The value reflects command-line options such as -@samp{-q} or @samp{-u @var{user}}. - -Lisp packages that load files of customizations, or any other sort of -user profile, should obey this variable in deciding where to find it. -They should load the profile of the user name found in this variable. -If @code{init-file-user} is @code{nil}, meaning that the @samp{-q} -option was used, then Lisp packages should not load any customization -files or user profile. -@end defvar - -@defvar user-mail-address -This holds the nominal email address of the user who is using Emacs. -Emacs normally sets this variable to a default value after reading your -init files, but not if you have already set it. So you can set the -variable to some other value in your init file if you do not -want to use the default value. -@end defvar - -@defun user-login-name &optional uid -If you don't specify @var{uid}, this function returns the name under -which the user is logged in. If the environment variable @code{LOGNAME} -is set, that value is used. Otherwise, if the environment variable -@code{USER} is set, that value is used. Otherwise, the value is based -on the effective @acronym{UID}, not the real @acronym{UID}. - -If you specify @var{uid}, the value is the user name that corresponds -to @var{uid} (which should be an integer), or @code{nil} if there is -no such user. - -@example -@group -(user-login-name) - @result{} "lewis" -@end group -@end example -@end defun - -@defun user-real-login-name -This function returns the user name corresponding to Emacs's real -@acronym{UID}. This ignores the effective @acronym{UID} and ignores the -environment variables @code{LOGNAME} and @code{USER}. -@end defun - -@defun user-full-name &optional uid -This function returns the full name of the logged-in user---or the value -of the environment variable @code{NAME}, if that is set. - -@c "Bil" is the correct spelling. -@example -@group -(user-full-name) - @result{} "Bil Lewis" -@end group -@end example - -If the Emacs job's user-id does not correspond to any known user (and -provided @code{NAME} is not set), the value is @code{"unknown"}. - -If @var{uid} is non-@code{nil}, then it should be a number (a user-id) -or a string (a login name). Then @code{user-full-name} returns the full -name corresponding to that user-id or login name. If you specify a -user-id or login name that isn't defined, it returns @code{nil}. -@end defun - -@vindex user-full-name -@vindex user-real-login-name -@vindex user-login-name - The symbols @code{user-login-name}, @code{user-real-login-name} and -@code{user-full-name} are variables as well as functions. The functions -return the same values that the variables hold. These variables allow -you to ``fake out'' Emacs by telling the functions what to return. The -variables are also useful for constructing frame titles (@pxref{Frame -Titles}). - -@defun user-real-uid -This function returns the real @acronym{UID} of the user. -The value may be a floating point number. - -@example -@group -(user-real-uid) - @result{} 19 -@end group -@end example -@end defun - -@defun user-uid -This function returns the effective @acronym{UID} of the user. -The value may be a floating point number. -@end defun - -@node Time of Day -@section Time of Day - - This section explains how to determine the current time and the time -zone. - -@defun current-time-string &optional time-value -This function returns the current time and date as a human-readable -string. The format of the string is unvarying; the number of characters -used for each part is always the same, so you can reliably use -@code{substring} to extract pieces of it. It is wise to count the -characters from the beginning of the string rather than from the end, as -additional information may some day be added at the end. - -@c Emacs 19 feature -The argument @var{time-value}, if given, specifies a time to format -instead of the current time. The argument should be a list whose first -two elements are integers. Thus, you can use times obtained from -@code{current-time} (see below) and from @code{file-attributes} -(@pxref{Definition of file-attributes}). @var{time-value} can also be -a cons of two integers, but this is considered obsolete. - -@example -@group -(current-time-string) - @result{} "Wed Oct 14 22:21:05 1987" -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun current-time -This function returns the system's time value as a list of three -integers: @code{(@var{high} @var{low} @var{microsec})}. The integers -@var{high} and @var{low} combine to give the number of seconds since -0:00 January 1, 1970 UTC (Coordinated Universal Time), which is -@ifnottex -@var{high} * 2**16 + @var{low}. -@end ifnottex -@tex -$high*2^{16}+low$. -@end tex - -The third element, @var{microsec}, gives the microseconds since the -start of the current second (or 0 for systems that return time with -the resolution of only one second). - -The first two elements can be compared with file time values such as you -get with the function @code{file-attributes}. -@xref{Definition of file-attributes}. -@end defun - -@c Emacs 19 feature -@defun current-time-zone &optional time-value -This function returns a list describing the time zone that the user is -in. - -The value has the form @code{(@var{offset} @var{name})}. Here -@var{offset} is an integer giving the number of seconds ahead of UTC -(east of Greenwich). A negative value means west of Greenwich. The -second element, @var{name}, is a string giving the name of the time -zone. Both elements change when daylight saving time begins or ends; -if the user has specified a time zone that does not use a seasonal time -adjustment, then the value is constant through time. - -If the operating system doesn't supply all the information necessary to -compute the value, the unknown elements of the list are @code{nil}. - -The argument @var{time-value}, if given, specifies a time to analyze -instead of the current time. The argument should have the same form -as for @code{current-time-string} (see above). Thus, you can use -times obtained from @code{current-time} (see above) and from -@code{file-attributes}. @xref{Definition of file-attributes}. -@end defun - -@defun set-time-zone-rule tz -This function specifies the local time zone according to @var{tz}. If -@var{tz} is @code{nil}, that means to use an implementation-defined -default time zone. If @var{tz} is @code{t}, that means to use -Universal Time. Otherwise, @var{tz} should be a string specifying a -time zone rule. -@end defun - -@defun float-time &optional time-value -This function returns the current time as a floating-point number of -seconds since the epoch. The argument @var{time-value}, if given, -specifies a time to convert instead of the current time. The argument -should have the same form as for @code{current-time-string} (see -above). Thus, it accepts the output of @code{current-time} and -@code{file-attributes}. - -@emph{Warning}: Since the result is floating point, it may not be -exact. Do not use this function if precise time stamps are required. -@end defun - -@node Time Conversion -@section Time Conversion - - These functions convert time values (lists of two or three integers) -to calendrical information and vice versa. You can get time values -from the functions @code{current-time} (@pxref{Time of Day}) and -@code{file-attributes} (@pxref{Definition of file-attributes}). - - Many operating systems are limited to time values that contain 32 bits -of information; these systems typically handle only the times from -1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some -operating systems have larger time values, and can represent times far -in the past or future. - - Time conversion functions always use the Gregorian calendar, even -for dates before the Gregorian calendar was introduced. Year numbers -count the number of years since the year 1 B.C., and do not skip zero -as traditional Gregorian years do; for example, the year number -@minus{}37 represents the Gregorian year 38 B.C@. - -@defun decode-time &optional time -This function converts a time value into calendrical information. If -you don't specify @var{time}, it decodes the current time. The return -value is a list of nine elements, as follows: - -@example -(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) -@end example - -Here is what the elements mean: - -@table @var -@item seconds -The number of seconds past the minute, as an integer between 0 and 59. -On some operating systems, this is 60 for leap seconds. -@item minutes -The number of minutes past the hour, as an integer between 0 and 59. -@item hour -The hour of the day, as an integer between 0 and 23. -@item day -The day of the month, as an integer between 1 and 31. -@item month -The month of the year, as an integer between 1 and 12. -@item year -The year, an integer typically greater than 1900. -@item dow -The day of week, as an integer between 0 and 6, where 0 stands for -Sunday. -@item dst -@code{t} if daylight saving time is effect, otherwise @code{nil}. -@item zone -An integer indicating the time zone, as the number of seconds east of -Greenwich. -@end table - -@strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{zone}. -@end defun - -@defun encode-time seconds minutes hour day month year &optional zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a time value. For the meanings of the -arguments, see the table above under @code{decode-time}. - -Year numbers less than 100 are not treated specially. If you want them -to stand for years above 1900, or years above 2000, you must alter them -yourself before you call @code{encode-time}. - -The optional argument @var{zone} defaults to the current time zone and -its daylight saving time rules. If specified, it can be either a list -(as you would get from @code{current-time-zone}), a string as in the -@code{TZ} environment variable, @code{t} for Universal Time, or an -integer (as you would get from @code{decode-time}). The specified -zone is used without any further alteration for daylight saving time. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: - -@example -(apply 'encode-time (decode-time @dots{})) -@end example - -You can perform simple date arithmetic by using out-of-range values for -the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} -arguments; for example, day 0 means the day preceding the given month. - -The operating system puts limits on the range of possible time values; -if you try to encode a time that is out of range, an error results. -For instance, years before 1970 do not work on some systems; -on others, years as early as 1901 do work. -@end defun - -@node Time Parsing -@section Parsing and Formatting Times - - These functions convert time values (lists of two or three integers) -to text in a string, and vice versa. - -@defun date-to-time string -This function parses the time-string @var{string} and returns the -corresponding time value. -@end defun - -@defun format-time-string format-string &optional time universal -This function converts @var{time} (or the current time, if @var{time} is -omitted) to a string according to @var{format-string}. The argument -@var{format-string} may contain @samp{%}-sequences which say to -substitute parts of the time. Here is a table of what the -@samp{%}-sequences mean: - -@table @samp -@item %a -This stands for the abbreviated name of the day of week. -@item %A -This stands for the full name of the day of week. -@item %b -This stands for the abbreviated name of the month. -@item %B -This stands for the full name of the month. -@item %c -This is a synonym for @samp{%x %X}. -@item %C -This has a locale-specific meaning. In the default locale (named C), it -is equivalent to @samp{%A, %B %e, %Y}. -@item %d -This stands for the day of month, zero-padded. -@item %D -This is a synonym for @samp{%m/%d/%y}. -@item %e -This stands for the day of month, blank-padded. -@item %h -This is a synonym for @samp{%b}. -@item %H -This stands for the hour (00-23). -@item %I -This stands for the hour (01-12). -@item %j -This stands for the day of the year (001-366). -@item %k -This stands for the hour (0-23), blank padded. -@item %l -This stands for the hour (1-12), blank padded. -@item %m -This stands for the month (01-12). -@item %M -This stands for the minute (00-59). -@item %n -This stands for a newline. -@item %p -This stands for @samp{AM} or @samp{PM}, as appropriate. -@item %r -This is a synonym for @samp{%I:%M:%S %p}. -@item %R -This is a synonym for @samp{%H:%M}. -@item %S -This stands for the seconds (00-59). -@item %t -This stands for a tab character. -@item %T -This is a synonym for @samp{%H:%M:%S}. -@item %U -This stands for the week of the year (01-52), assuming that weeks -start on Sunday. -@item %w -This stands for the numeric day of week (0-6). Sunday is day 0. -@item %W -This stands for the week of the year (01-52), assuming that weeks -start on Monday. -@item %x -This has a locale-specific meaning. In the default locale (named -@samp{C}), it is equivalent to @samp{%D}. -@item %X -This has a locale-specific meaning. In the default locale (named -@samp{C}), it is equivalent to @samp{%T}. -@item %y -This stands for the year without century (00-99). -@item %Y -This stands for the year with century. -@item %Z -This stands for the time zone abbreviation (e.g., @samp{EST}). -@item %z -This stands for the time zone numerical offset (e.g., @samp{-0500}). -@end table - -You can also specify the field width and type of padding for any of -these @samp{%}-sequences. This works as in @code{printf}: you write -the field width as digits in the middle of a @samp{%}-sequences. If you -start the field width with @samp{0}, it means to pad with zeros. If you -start the field width with @samp{_}, it means to pad with spaces. - -For example, @samp{%S} specifies the number of seconds since the minute; -@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to -pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros, -because that is how @samp{%S} normally pads to two positions. - -The characters @samp{E} and @samp{O} act as modifiers when used between -@samp{%} and one of the letters in the table above. @samp{E} specifies -using the current locale's ``alternative'' version of the date and time. -In a Japanese locale, for example, @code{%Ex} might yield a date format -based on the Japanese Emperors' reigns. @samp{E} is allowed in -@samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and -@samp{%EY}. - -@samp{O} means to use the current locale's ``alternative'' -representation of numbers, instead of the ordinary decimal digits. This -is allowed with most letters, all the ones that output numbers. - -If @var{universal} is non-@code{nil}, that means to describe the time as -Universal Time; @code{nil} means describe it using what Emacs believes -is the local time zone (see @code{current-time-zone}). - -This function uses the C library function @code{strftime} -(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference -Manual}) to do most of the work. In order to communicate with that -function, it first encodes its argument using the coding system -specified by @code{locale-coding-system} (@pxref{Locales}); after -@code{strftime} returns the resulting string, -@code{format-time-string} decodes the string using that same coding -system. -@end defun - -@defun seconds-to-time seconds -This function converts @var{seconds}, a floating point number of -seconds since the epoch, to a time value and returns that. To perform -the inverse conversion, use @code{float-time}. -@end defun - -@node Processor Run Time -@section Processor Run time -@cindex processor run time - -@defun get-internal-run-time -This function returns the processor run time used by Emacs as a list -of three integers: @code{(@var{high} @var{low} @var{microsec})}. The -integers @var{high} and @var{low} combine to give the number of -seconds, which is -@ifnottex -@var{high} * 2**16 + @var{low}. -@end ifnottex -@tex -$high*2^{16}+low$. -@end tex - -The third element, @var{microsec}, gives the microseconds (or 0 for -systems that return time with the resolution of only one second). - -If the system doesn't provide a way to determine the processor run -time, get-internal-run-time returns the same time as current-time. -@end defun - -@node Time Calculations -@section Time Calculations - - These functions perform calendrical computations using time values -(the kind of list that @code{current-time} returns). - -@defun time-less-p t1 t2 -This returns @code{t} if time value @var{t1} is less than time value -@var{t2}. -@end defun - -@defun time-subtract t1 t2 -This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, in the same format as a time value. -@end defun - -@defun time-add t1 t2 -This returns the sum of two time values, one of which ought to -represent a time difference rather than a point in time. -Here is how to add a number of seconds to a time value: - -@example -(time-add @var{time} (seconds-to-time @var{seconds})) -@end example -@end defun - -@defun time-to-days time -This function returns the number of days between the beginning of year -1 and @var{time}. -@end defun - -@defun time-to-day-in-year time -This returns the day number within the year corresponding to @var{time}. -@end defun - -@defun date-leap-year-p year -This function returns @code{t} if @var{year} is a leap year. -@end defun - -@node Timers -@section Timers for Delayed Execution -@cindex timer - - You can set up a @dfn{timer} to call a function at a specified -future time or after a certain length of idleness. - - Emacs cannot run timers at any arbitrary point in a Lisp program; it -can run them only when Emacs could accept output from a subprocess: -namely, while waiting or inside certain primitive functions such as -@code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a -timer's execution may be delayed if Emacs is busy. However, the time of -execution is very precise if Emacs is idle. - - Emacs binds @code{inhibit-quit} to @code{t} before calling the timer -function, because quitting out of many timer functions can leave -things in an inconsistent state. This is normally unproblematical -because most timer functions don't do a lot of work. Indeed, for a -timer to call a function that takes substantial time to run is likely -to be annoying. If a timer function needs to allow quitting, it -should use @code{with-local-quit} (@pxref{Quitting}). For example, if -a timer function calls @code{accept-process-output} to receive output -from an external process, that call should be wrapped inside -@code{with-local-quit}, to ensure that @kbd{C-g} works if the external -process hangs. - - It is usually a bad idea for timer functions to alter buffer -contents. When they do, they usually should call @code{undo-boundary} -both before and after changing the buffer, to separate the timer's -changes from user commands' changes and prevent a single undo entry -from growing to be quite large. - - Timer functions should also avoid calling functions that cause Emacs -to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to -unpredictable effects, since other timers (or even the same timer) can -run while waiting. If a timer function needs to perform an action -after a certain time has elapsed, it can do this by scheduling a new -timer. - - If a timer function calls functions that can change the match data, -it should save and restore the match data. @xref{Saving Match Data}. - -@deffn Command run-at-time time repeat function &rest args -This sets up a timer that calls the function @var{function} with -arguments @var{args} at time @var{time}. If @var{repeat} is a number -(integer or floating point), the timer is scheduled to run again every -@var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil}, -the timer runs only once. - -@var{time} may specify an absolute or a relative time. - -Absolute times may be specified using a string with a limited variety -of formats, and are taken to be times @emph{today}, even if already in -the past. The recognized forms are @samp{@var{xxxx}}, -@samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time), -and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm}, -@samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am}, -@samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or -@samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon -to separate the hour and minute parts. - -To specify a relative time as a string, use numbers followed by units. -For example: - -@table @samp -@item 1 min -denotes 1 minute from now. -@item 1 min 5 sec -denotes 65 seconds from now. -@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year -denotes exactly 103 months, 123 days, and 10862 seconds from now. -@end table - -For relative time values, Emacs considers a month to be exactly thirty -days, and a year to be exactly 365.25 days. - -Not all convenient formats are strings. If @var{time} is a number -(integer or floating point), that specifies a relative time measured in -seconds. The result of @code{encode-time} can also be used to specify -an absolute value for @var{time}. - -In most cases, @var{repeat} has no effect on when @emph{first} call -takes place---@var{time} alone specifies that. There is one exception: -if @var{time} is @code{t}, then the timer runs whenever the time is a -multiple of @var{repeat} seconds after the epoch. This is useful for -functions like @code{display-time}. - -The function @code{run-at-time} returns a timer value that identifies -the particular scheduled future action. You can use this value to call -@code{cancel-timer} (see below). -@end deffn - - A repeating timer nominally ought to run every @var{repeat} seconds, -but remember that any invocation of a timer can be late. Lateness of -one repetition has no effect on the scheduled time of the next -repetition. For instance, if Emacs is busy computing for long enough -to cover three scheduled repetitions of the timer, and then starts to -wait, it will immediately call the timer function three times in -immediate succession (presuming no other timers trigger before or -between them). If you want a timer to run again no less than @var{n} -seconds after the last invocation, don't use the @var{repeat} argument. -Instead, the timer function should explicitly reschedule the timer. - -@defvar timer-max-repeats -This variable's value specifies the maximum number of times to repeat -calling a timer function in a row, when many previously scheduled -calls were unavoidably delayed. -@end defvar - -@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{} -Execute @var{body}, but give up after @var{seconds} seconds. If -@var{body} finishes before the time is up, @code{with-timeout} returns -the value of the last form in @var{body}. If, however, the execution of -@var{body} is cut short by the timeout, then @code{with-timeout} -executes all the @var{timeout-forms} and returns the value of the last -of them. - -This macro works by setting a timer to run after @var{seconds} seconds. If -@var{body} finishes before that time, it cancels the timer. If the -timer actually runs, it terminates execution of @var{body}, then -executes @var{timeout-forms}. - -Since timers can run within a Lisp program only when the program calls a -primitive that can wait, @code{with-timeout} cannot stop executing -@var{body} while it is in the midst of a computation---only when it -calls one of those primitives. So use @code{with-timeout} only with a -@var{body} that waits for input, not one that does a long computation. -@end defmac - - The function @code{y-or-n-p-with-timeout} provides a simple way to use -a timer to avoid waiting too long for an answer. @xref{Yes-or-No -Queries}. - -@defun cancel-timer timer -This cancels the requested action for @var{timer}, which should be a -timer---usually, one previously returned by @code{run-at-time} or -@code{run-with-idle-timer}. This cancels the effect of that call to -one of these functions; the arrival of the specified time will not -cause anything special to happen. -@end defun - -@node Idle Timers -@section Idle Timers - - Here is how to set up a timer that runs when Emacs is idle for a -certain length of time. Aside from how to set them up, idle timers -work just like ordinary timers. - -@deffn Command run-with-idle-timer secs repeat function &rest args -Set up a timer which runs when Emacs has been idle for @var{secs} -seconds. The value of @var{secs} may be an integer or a floating point -number; a value of the type returned by @code{current-idle-time} -is also allowed. - -If @var{repeat} is @code{nil}, the timer runs just once, the first time -Emacs remains idle for a long enough time. More often @var{repeat} is -non-@code{nil}, which means to run the timer @emph{each time} Emacs -remains idle for @var{secs} seconds. - -The function @code{run-with-idle-timer} returns a timer value which you -can use in calling @code{cancel-timer} (@pxref{Timers}). -@end deffn - -@cindex idleness - Emacs becomes ``idle'' when it starts waiting for user input, and it -remains idle until the user provides some input. If a timer is set for -five seconds of idleness, it runs approximately five seconds after Emacs -first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer -will not run again as long as Emacs remains idle, because the duration -of idleness will continue to increase and will not go down to five -seconds again. - - Emacs can do various things while idle: garbage collect, autosave or -handle data from a subprocess. But these interludes during idleness do -not interfere with idle timers, because they do not reset the clock of -idleness to zero. An idle timer set for 600 seconds will run when ten -minutes have elapsed since the last user command was finished, even if -subprocess output has been accepted thousands of times within those ten -minutes, and even if there have been garbage collections and autosaves. - - When the user supplies input, Emacs becomes non-idle while executing the -input. Then it becomes idle again, and all the idle timers that are -set up to repeat will subsequently run another time, one by one. - -@c Emacs 19 feature -@defun current-idle-time -This function returns the length of time Emacs has been idle, as a -list of three integers: @code{(@var{high} @var{low} @var{microsec})}. -The integers @var{high} and @var{low} combine to give the number of -seconds of idleness, which is -@ifnottex -@var{high} * 2**16 + @var{low}. -@end ifnottex -@tex -$high*2^{16}+low$. -@end tex - -The third element, @var{microsec}, gives the microseconds since the -start of the current second (or 0 for systems that return time with -the resolution of only one second). - -The main use of this function is when an idle timer function wants to -``take a break'' for a while. It can set up another idle timer to -call the same function again, after a few seconds more idleness. -Here's an example: - -@smallexample -(defvar resume-timer nil - "Timer that `timer-function' used to reschedule itself, or nil.") - -(defun timer-function () - ;; @r{If the user types a command while @code{resume-timer}} - ;; @r{is active, the next time this function is called from} - ;; @r{its main idle timer, deactivate @code{resume-timer}.} - (when resume-timer - (cancel-timer resume-timer)) - ...@var{do the work for a while}... - (when @var{taking-a-break} - (setq resume-timer - (run-with-idle-timer - ;; Compute an idle time @var{break-length} - ;; more than the current value. - (time-add (current-idle-time) - (seconds-to-time @var{break-length})) - nil - 'timer-function)))) -@end smallexample -@end defun - - Some idle timer functions in user Lisp packages have a loop that -does a certain amount of processing each time around, and exits when -@code{(input-pending-p)} is non-@code{nil}. That approach seems very -natural but has two problems: - -@itemize -@item -It blocks out all process output (since Emacs accepts process output -only while waiting). - -@item -It blocks out any idle timers that ought to run during that time. -@end itemize - -@noindent -To avoid these problems, don't use that technique. Instead, write -such idle timers to reschedule themselves after a brief pause, using -the method in the @code{timer-function} example above. - -@node Terminal Input -@section Terminal Input -@cindex terminal input - - This section describes functions and variables for recording or -manipulating terminal input. See @ref{Display}, for related -functions. - -@menu -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. -@end menu - -@node Input Modes -@subsection Input Modes -@cindex input modes -@cindex terminal input modes - -@defun set-input-mode interrupt flow meta &optional quit-char -This function sets the mode for reading keyboard input. If -@var{interrupt} is non-null, then Emacs uses input interrupts. If it is -@code{nil}, then it uses @sc{cbreak} mode. The default setting is -system-dependent. Some systems always use @sc{cbreak} mode regardless -of what is specified. - -When Emacs communicates directly with X, it ignores this argument and -uses interrupts if that is the way it knows how to communicate. - -If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} -(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This -has no effect except in @sc{cbreak} mode. - -@c Emacs 19 feature -The argument @var{meta} controls support for input character codes -above 127. If @var{meta} is @code{t}, Emacs converts characters with -the 8th bit set into Meta characters. If @var{meta} is @code{nil}, -Emacs disregards the 8th bit; this is necessary when the terminal uses -it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, -Emacs uses all 8 bits of input unchanged. This is good for terminals -that use 8-bit character sets. - -@c Emacs 19 feature -If @var{quit-char} is non-@code{nil}, it specifies the character to -use for quitting. Normally this character is @kbd{C-g}. -@xref{Quitting}. -@end defun - -The @code{current-input-mode} function returns the input mode settings -Emacs is currently using. - -@c Emacs 19 feature -@defun current-input-mode -This function returns the current mode for reading keyboard input. It -returns a list, corresponding to the arguments of @code{set-input-mode}, -of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in -which: -@table @var -@item interrupt -is non-@code{nil} when Emacs is using interrupt-driven input. If -@code{nil}, Emacs is using @sc{cbreak} mode. -@item flow -is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) -flow control for output to the terminal. This value is meaningful only -when @var{interrupt} is @code{nil}. -@item meta -is @code{t} if Emacs treats the eighth bit of input characters as -the meta bit; @code{nil} means Emacs clears the eighth bit of every -input character; any other value means Emacs uses all eight bits as the -basic character code. -@item quit -is the character Emacs currently uses for quitting, usually @kbd{C-g}. -@end table -@end defun - -@node Recording Input -@subsection Recording Input -@cindex recording input - -@defun recent-keys -This function returns a vector containing the last 300 input events from -the keyboard or mouse. All input events are included, whether or not -they were used as parts of key sequences. Thus, you always get the last -100 input events, not counting events generated by keyboard macros. -(These are excluded because they are less interesting for debugging; it -should be enough to see the events that invoked the macros.) - -A call to @code{clear-this-command-keys} (@pxref{Command Loop Info}) -causes this function to return an empty vector immediately afterward. -@end defun - -@deffn Command open-dribble-file filename -@cindex dribble file -This function opens a @dfn{dribble file} named @var{filename}. When a -dribble file is open, each input event from the keyboard or mouse (but -not those from keyboard macros) is written in that file. A -non-character event is expressed using its printed representation -surrounded by @samp{<@dots{}>}. - -You close the dribble file by calling this function with an argument -of @code{nil}. - -This function is normally used to record the input necessary to -trigger an Emacs bug, for the sake of a bug report. - -@example -@group -(open-dribble-file "~/dribble") - @result{} nil -@end group -@end example -@end deffn - - See also the @code{open-termscript} function (@pxref{Terminal Output}). - -@node Terminal Output -@section Terminal Output -@cindex terminal output - - The terminal output functions send output to a text terminal, or keep -track of output sent to the terminal. The variable @code{baud-rate} -tells you what Emacs thinks is the output speed of the terminal. - -@defvar baud-rate -This variable's value is the output speed of the terminal, as far as -Emacs knows. Setting this variable does not change the speed of actual -data transmission, but the value is used for calculations such as -padding. - - It also affects decisions about whether to scroll part of the -screen or repaint on text terminals. @xref{Forcing Redisplay}, -for the corresponding functionality on graphical terminals. - -The value is measured in baud. -@end defvar - - If you are running across a network, and different parts of the -network work at different baud rates, the value returned by Emacs may be -different from the value used by your local terminal. Some network -protocols communicate the local terminal speed to the remote machine, so -that Emacs and other programs can get the proper value, but others do -not. If Emacs has the wrong value, it makes decisions that are less -than optimal. To fix the problem, set @code{baud-rate}. - -@defun baud-rate -This obsolete function returns the value of the variable -@code{baud-rate}. -@end defun - -@defun send-string-to-terminal string -This function sends @var{string} to the terminal without alteration. -Control characters in @var{string} have terminal-dependent effects. -This function operates only on text terminals. - -One use of this function is to define function keys on terminals that -have downloadable function key definitions. For example, this is how (on -certain terminals) to define function key 4 to move forward four -characters (by transmitting the characters @kbd{C-u C-f} to the -computer): - -@example -@group -(send-string-to-terminal "\eF4\^U\^F") - @result{} nil -@end group -@end example -@end defun - -@deffn Command open-termscript filename -@cindex termscript file -This function is used to open a @dfn{termscript file} that will record -all the characters sent by Emacs to the terminal. It returns -@code{nil}. Termscript files are useful for investigating problems -where Emacs garbles the screen, problems that are due to incorrect -Termcap entries or to undesirable settings of terminal options more -often than to actual Emacs bugs. Once you are certain which characters -were actually output, you can determine reliably whether they correspond -to the Termcap specifications in use. - -You close the termscript file by calling this function with an -argument of @code{nil}. - -See also @code{open-dribble-file} in @ref{Recording Input}. - -@example -@group -(open-termscript "../junk/termscript") - @result{} nil -@end group -@end example -@end deffn - -@node Sound Output -@section Sound Output -@cindex sound - - To play sound using Emacs, use the function @code{play-sound}. Only -certain systems are supported; if you call @code{play-sound} on a system -which cannot really do the job, it gives an error. Emacs version 20 and -earlier did not support sound at all. - - The sound must be stored as a file in RIFF-WAVE format (@samp{.wav}) -or Sun Audio format (@samp{.au}). - -@defun play-sound sound -This function plays a specified sound. The argument, @var{sound}, has -the form @code{(sound @var{properties}...)}, where the @var{properties} -consist of alternating keywords (particular symbols recognized -specially) and values corresponding to them. - -Here is a table of the keywords that are currently meaningful in -@var{sound}, and their meanings: - -@table @code -@item :file @var{file} -This specifies the file containing the sound to play. -If the file name is not absolute, it is expanded against -the directory @code{data-directory}. - -@item :data @var{data} -This specifies the sound to play without need to refer to a file. The -value, @var{data}, should be a string containing the same bytes as a -sound file. We recommend using a unibyte string. - -@item :volume @var{volume} -This specifies how loud to play the sound. It should be a number in the -range of 0 to 1. The default is to use whatever volume has been -specified before. - -@item :device @var{device} -This specifies the system device on which to play the sound, as a -string. The default device is system-dependent. -@end table - -Before actually playing the sound, @code{play-sound} -calls the functions in the list @code{play-sound-functions}. -Each function is called with one argument, @var{sound}. -@end defun - -@defun play-sound-file file &optional volume device -This function is an alternative interface to playing a sound @var{file} -specifying an optional @var{volume} and @var{device}. -@end defun - -@defvar play-sound-functions -A list of functions to be called before playing a sound. Each function -is called with one argument, a property list that describes the sound. -@end defvar - -@node X11 Keysyms -@section Operating on X11 Keysyms -@cindex X11 keysyms - -To define system-specific X11 keysyms, set the variable -@code{system-key-alist}. - -@defvar system-key-alist -This variable's value should be an alist with one element for each -system-specific keysym. Each element has the form @code{(@var{code} -. @var{symbol})}, where @var{code} is the numeric keysym code (not -including the ``vendor specific'' bit, -@ifnottex --2**28), -@end ifnottex -@tex -$-2^{28}$), -@end tex -and @var{symbol} is the name for the function key. - -For example @code{(168 . mute-acute)} defines a system-specific key (used -by HP X servers) whose numeric code is -@ifnottex --2**28 -@end ifnottex -@tex -$-2^{28}$ -@end tex -+ 168. - -It is not crucial to exclude from the alist the keysyms of other X -servers; those do no harm, as long as they don't conflict with the ones -used by the X server actually in use. - -The variable is always local to the current terminal, and cannot be -buffer-local. @xref{Multiple Displays}. -@end defvar - -You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables: - -@defvar x-alt-keysym -@defvarx x-meta-keysym -@defvarx x-hyper-keysym -@defvarx x-super-keysym -The name of the keysym that should stand for the Alt modifier -(respectively, for Meta, Hyper, and Super). For example, here is -how to swap the Meta and Alt modifiers within Emacs: -@lisp -(setq x-alt-keysym 'meta) -(setq x-meta-keysym 'alt) -@end lisp -@end defvar - -@node Batch Mode -@section Batch Mode -@cindex batch mode - - The command-line option @samp{-batch} causes Emacs to run -noninteractively. In this mode, Emacs does not read commands from the -terminal, it does not alter the terminal modes, and it does not expect -to be outputting to an erasable screen. The idea is that you specify -Lisp programs to run; when they are finished, Emacs should exit. The -way to specify the programs to run is with @samp{-l @var{file}}, which -loads the library named @var{file}, or @samp{-f @var{function}}, which -calls @var{function} with no arguments, or @samp{--eval @var{form}}. - - Any Lisp program output that would normally go to the echo area, -either using @code{message}, or using @code{prin1}, etc., with @code{t} -as the stream, goes instead to Emacs's standard error descriptor when -in batch mode. Similarly, input that would normally come from the -minibuffer is read from the standard input descriptor. -Thus, Emacs behaves much like a noninteractive -application program. (The echo area output that Emacs itself normally -generates, such as command echoing, is suppressed entirely.) - -@defvar noninteractive -This variable is non-@code{nil} when Emacs is running in batch mode. -@end defvar - -@node Session Management -@section Session Management -@cindex session manager - -Emacs supports the X Session Management Protocol for suspension and -restart of applications. In the X Window System, a program called the -@dfn{session manager} has the responsibility to keep track of the -applications that are running. During shutdown, the session manager -asks applications to save their state, and delays the actual shutdown -until they respond. An application can also cancel the shutdown. - -When the session manager restarts a suspended session, it directs -these applications to individually reload their saved state. It does -this by specifying a special command-line argument that says what -saved session to restore. For Emacs, this argument is @samp{--smid -@var{session}}. - -@defvar emacs-save-session-functions -Emacs supports saving state by using a hook called -@code{emacs-save-session-functions}. Each function in this hook is -called when the session manager tells Emacs that the window system is -shutting down. The functions are called with no arguments and with the -current buffer set to a temporary buffer. Each function can use -@code{insert} to add Lisp code to this buffer. At the end, Emacs -saves the buffer in a file that a subsequent Emacs invocation will -load in order to restart the saved session. - -If a function in @code{emacs-save-session-functions} returns -non-@code{nil}, Emacs tells the session manager to cancel the -shutdown. -@end defvar - -Here is an example that just inserts some text into @samp{*scratch*} when -Emacs is restarted by the session manager. - -@example -@group -(add-hook 'emacs-save-session-functions 'save-yourself-test) -@end group - -@group -(defun save-yourself-test () - (insert "(save-excursion - (switch-to-buffer \"*scratch*\") - (insert \"I am restored\"))") - nil) -@end group -@end example - -@ignore - arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7 -@end ignore diff --git a/lispref/positions.texi b/lispref/positions.texi deleted file mode 100644 index 939b3f75fc1..00000000000 --- a/lispref/positions.texi +++ /dev/null @@ -1,1004 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/positions -@node Positions, Markers, Frames, Top -@chapter Positions -@cindex position (in buffer) - - A @dfn{position} is the index of a character in the text of a buffer. -More precisely, a position identifies the place between two characters -(or before the first character, or after the last character), so we can -speak of the character before or after a given position. However, we -often speak of the character ``at'' a position, meaning the character -after that position. - - Positions are usually represented as integers starting from 1, but -can also be represented as @dfn{markers}---special objects that -relocate automatically when text is inserted or deleted so they stay -with the surrounding characters. Functions that expect an argument to -be a position (an integer), but accept a marker as a substitute, -normally ignore which buffer the marker points into; they convert the -marker to an integer, and use that integer, exactly as if you had -passed the integer as the argument, even if the marker points to the -``wrong'' buffer. A marker that points nowhere cannot convert to an -integer; using it instead of an integer causes an error. -@xref{Markers}. - - See also the ``field'' feature (@pxref{Fields}), which provides -functions that are used by many cursor-motion commands. - -@menu -* 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. -@end menu - -@node Point -@section Point -@cindex point - - @dfn{Point} is a special buffer position used by many editing -commands, including the self-inserting typed characters and text -insertion functions. Other commands move point through the text -to allow editing and insertion at different places. - - Like other positions, point designates a place between two characters -(or before the first character, or after the last character), rather -than a particular character. Usually terminals display the cursor over -the character that immediately follows point; point is actually before -the character on which the cursor sits. - -@cindex point with narrowing - The value of point is a number no less than 1, and no greater than the -buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then -point is constrained to fall within the accessible portion of the buffer -(possibly at one end of it). - - Each buffer has its own value of point, which is independent of the -value of point in other buffers. Each window also has a value of point, -which is independent of the value of point in other windows on the same -buffer. This is why point can have different values in various windows -that display the same buffer. When a buffer appears in only one window, -the buffer's point and the window's point normally have the same value, -so the distinction is rarely important. @xref{Window Point}, for more -details. - -@defun point -@cindex current buffer position -This function returns the value of point in the current buffer, -as an integer. - -@need 700 -@example -@group -(point) - @result{} 175 -@end group -@end example -@end defun - -@defun point-min -This function returns the minimum accessible value of point in the -current buffer. This is normally 1, but if narrowing is in effect, it -is the position of the start of the region that you narrowed to. -(@xref{Narrowing}.) -@end defun - -@defun point-max -This function returns the maximum accessible value of point in the -current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is -in effect, in which case it is the position of the end of the region -that you narrowed to. (@xref{Narrowing}.) -@end defun - -@defun buffer-end flag -This function returns @code{(point-max)} if @var{flag} is greater than -0, @code{(point-min)} otherwise. The argument @var{flag} must be a -number. -@end defun - -@defun buffer-size &optional buffer -This function returns the total number of characters in the current -buffer. In the absence of any narrowing (@pxref{Narrowing}), -@code{point-max} returns a value one larger than this. - -If you specify a buffer, @var{buffer}, then the value is the -size of @var{buffer}. - -@example -@group -(buffer-size) - @result{} 35 -@end group -@group -(point-max) - @result{} 36 -@end group -@end example -@end defun - -@node Motion -@section Motion -@cindex motion by chars, words, lines, lists - - Motion functions change the value of point, either relative to the -current value of point, relative to the beginning or end of the buffer, -or relative to the edges of the selected window. @xref{Point}. - -@menu -* 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. -@end menu - -@node Character Motion -@subsection Motion by Characters - - These functions move point based on a count of characters. -@code{goto-char} is the fundamental primitive; the other functions use -that. - -@deffn Command goto-char position -This function sets point in the current buffer to the value -@var{position}. If @var{position} is less than 1, it moves point to the -beginning of the buffer. If @var{position} is greater than the length -of the buffer, it moves point to the end. - -If narrowing is in effect, @var{position} still counts from the -beginning of the buffer, but point cannot go outside the accessible -portion. If @var{position} is out of range, @code{goto-char} moves -point to the beginning or the end of the accessible portion. - -When this function is called interactively, @var{position} is the -numeric prefix argument, if provided; otherwise it is read from the -minibuffer. - -@code{goto-char} returns @var{position}. -@end deffn - -@deffn Command forward-char &optional count -@c @kindex beginning-of-buffer -@c @kindex end-of-buffer -This function moves point @var{count} characters forward, towards the -end of the buffer (or backward, towards the beginning of the buffer, if -@var{count} is negative). If @var{count} is @code{nil}, the default -is 1. - -If this attempts to move past the beginning or end of the buffer (or -the limits of the accessible portion, when narrowing is in effect), it -signals an error with error symbol @code{beginning-of-buffer} or -@code{end-of-buffer}. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@deffn Command backward-char &optional count -This is just like @code{forward-char} except that it moves -in the opposite direction. -@end deffn - -@node Word Motion -@subsection Motion by Words - - These functions for parsing words use the syntax table to decide -whether a given character is part of a word. @xref{Syntax Tables}. - -@deffn Command forward-word &optional count -This function moves point forward @var{count} words (or backward if -@var{count} is negative). If @var{count} is @code{nil}, it moves -forward one word. - -``Moving one word'' means moving until point crosses a -word-constituent character and then encounters a word-separator -character. However, this function cannot move point past the boundary -of the accessible portion of the buffer, or across a field boundary -(@pxref{Fields}). The most common case of a field boundary is the end -of the prompt in the minibuffer. - -If it is possible to move @var{count} words, without being stopped -prematurely by the buffer boundary or a field boundary, the value is -@code{t}. Otherwise, the return value is @code{nil} and point stops at -the buffer boundary or field boundary. - -If @code{inhibit-field-text-motion} is non-@code{nil}, -this function ignores field boundaries. - -In an interactive call, @var{count} is specified by the numeric prefix -argument. If @var{count} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@deffn Command backward-word &optional count -This function is just like @code{forward-word}, except that it moves -backward until encountering the front of a word, rather than forward. -@end deffn - -@defvar words-include-escapes -@c Emacs 19 feature -This variable affects the behavior of @code{forward-word} and everything -that uses it. If it is non-@code{nil}, then characters in the -``escape'' and ``character quote'' syntax classes count as part of -words. Otherwise, they do not. -@end defvar - -@defvar inhibit-field-text-motion -If this variable is non-@code{nil}, certain motion functions including -@code{forward-word}, @code{forward-sentence}, and -@code{forward-paragraph} ignore field boundaries. -@end defvar - -@node Buffer End Motion -@subsection Motion to an End of the Buffer -@cindex move to beginning or end of buffer - - To move point to the beginning of the buffer, write: - -@example -@group -(goto-char (point-min)) -@end group -@end example - -@noindent -Likewise, to move to the end of the buffer, use: - -@example -@group -(goto-char (point-max)) -@end group -@end example - - Here are two commands that users use to do these things. They are -documented here to warn you not to use them in Lisp programs, because -they set the mark and display messages in the echo area. - -@deffn Command beginning-of-buffer &optional n -This function moves point to the beginning of the buffer (or the limits -of the accessible portion, when narrowing is in effect), setting the -mark at the previous position (except in Transient Mark mode, if -the mark is already active, it does not set the mark.) - -If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the -way from the beginning of the accessible portion of the buffer. In an -interactive call, @var{n} is the numeric prefix argument, if provided; -otherwise @var{n} defaults to @code{nil}. - -@strong{Warning:} Don't use this function in Lisp programs! -@end deffn - -@deffn Command end-of-buffer &optional n -This function moves point to the end of the buffer (or the limits of -the accessible portion, when narrowing is in effect), setting the mark -at the previous position (except in Transient Mark mode when the mark -is already active). If @var{n} is non-@code{nil}, then it puts point -@var{n} tenths of the way from the end of the accessible portion of -the buffer. - -In an interactive call, @var{n} is the numeric prefix argument, -if provided; otherwise @var{n} defaults to @code{nil}. - -@strong{Warning:} Don't use this function in Lisp programs! -@end deffn - -@node Text Lines -@subsection Motion by Text Lines -@cindex lines - - Text lines are portions of the buffer delimited by newline characters, -which are regarded as part of the previous line. The first text line -begins at the beginning of the buffer, and the last text line ends at -the end of the buffer whether or not the last character is a newline. -The division of the buffer into text lines is not affected by the width -of the window, by line continuation in display, or by how tabs and -control characters are displayed. - -@deffn Command goto-line line -This function moves point to the front of the @var{line}th line, -counting from line 1 at beginning of the buffer. If @var{line} is less -than 1, it moves point to the beginning of the buffer. If @var{line} is -greater than the number of lines in the buffer, it moves point to the -end of the buffer---that is, the @emph{end of the last line} of the -buffer. This is the only case in which @code{goto-line} does not -necessarily move to the beginning of a line. - -If narrowing is in effect, then @var{line} still counts from the -beginning of the buffer, but point cannot go outside the accessible -portion. So @code{goto-line} moves point to the beginning or end of the -accessible portion, if the line number specifies an inaccessible -position. - -The return value of @code{goto-line} is the difference between -@var{line} and the line number of the line to which point actually was -able to move (in the full buffer, before taking account of narrowing). -Thus, the value is positive if the scan encounters the real end of the -buffer before finding the specified line. The value is zero if scan -encounters the end of the accessible portion but not the real end of the -buffer. - -In an interactive call, @var{line} is the numeric prefix argument if -one has been provided. Otherwise @var{line} is read in the minibuffer. -@end deffn - -@deffn Command beginning-of-line &optional count -This function moves point to the beginning of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the beginning of the line. - -This function does not move point across a field boundary -(@pxref{Fields}) unless doing so would move beyond there to a -different line; therefore, if @var{count} is @code{nil} or 1, and -point starts at a field boundary, point does not move. To ignore -field boundaries, either bind @code{inhibit-field-text-motion} to -@code{t}, or use the @code{forward-line} function instead. For -instance, @code{(forward-line 0)} does the same thing as -@code{(beginning-of-line)}, except that it ignores field boundaries. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@defun line-beginning-position &optional count -Return the position that @code{(beginning-of-line @var{count})} -would move to. -@end defun - -@deffn Command end-of-line &optional count -This function moves point to the end of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the end of the line. - -This function does not move point across a field boundary -(@pxref{Fields}) unless doing so would move beyond there to a -different line; therefore, if @var{count} is @code{nil} or 1, and -point starts at a field boundary, point does not move. To ignore -field boundaries, bind @code{inhibit-field-text-motion} to @code{t}. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@defun line-end-position &optional count -Return the position that @code{(end-of-line @var{count})} -would move to. -@end defun - -@deffn Command forward-line &optional count -@cindex beginning of line -This function moves point forward @var{count} lines, to the beginning of -the line. If @var{count} is negative, it moves point -@minus{}@var{count} lines backward, to the beginning of a line. If -@var{count} is zero, it moves point to the beginning of the current -line. If @var{count} is @code{nil}, that means 1. - -If @code{forward-line} encounters the beginning or end of the buffer (or -of the accessible portion) before finding that many lines, it sets point -there. No error is signaled. - -@code{forward-line} returns the difference between @var{count} and the -number of lines actually moved. If you attempt to move down five lines -from the beginning of a buffer that has only three lines, point stops at -the end of the last line, and the value will be 2. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@defun count-lines start end -@cindex lines in region -@anchor{Definition of count-lines} -This function returns the number of lines between the positions -@var{start} and @var{end} in the current buffer. If @var{start} and -@var{end} are equal, then it returns 0. Otherwise it returns at least -1, even if @var{start} and @var{end} are on the same line. This is -because the text between them, considered in isolation, must contain at -least one line unless it is empty. - -Here is an example of using @code{count-lines}: - -@example -@group -(defun current-line () - "Return the vertical position of point@dots{}" - (+ (count-lines (window-start) (point)) - (if (= (current-column) 0) 1 0))) -@end group -@end example -@end defun - -@defun line-number-at-pos &optional pos -@cindex line number -This function returns the line number in the current buffer -corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil} -or omitted, the current buffer position is used. -@end defun - -@ignore -@c ================ -The @code{previous-line} and @code{next-line} commands are functions -that should not be used in programs. They are for users and are -mentioned here only for completeness. - -@deffn Command previous-line count -@cindex goal column -This function moves point up @var{count} lines (down if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} with a negative argument instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@deffn Command next-line count -This function moves point down @var{count} lines (up if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In the case where the @var{count} is 1, and point is on the last -line of the buffer (or clipped region), a new empty line is inserted at the -end of the buffer (or clipped region) and point moved there. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@c ================ -@end ignore - - Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}. -These functions do not move point, but test whether it is already at the -beginning or end of a line. - -@node Screen Lines -@subsection Motion by Screen Lines - - The line functions in the previous section count text lines, delimited -only by newline characters. By contrast, these functions count screen -lines, which are defined by the way the text appears on the screen. A -text line is a single screen line if it is short enough to fit the width -of the selected window, but otherwise it may occupy several screen -lines. - - In some cases, text lines are truncated on the screen rather than -continued onto additional screen lines. In these cases, -@code{vertical-motion} moves point much like @code{forward-line}. -@xref{Truncation}. - - Because the width of a given string depends on the flags that control -the appearance of certain characters, @code{vertical-motion} behaves -differently, for a given piece of text, depending on the buffer it is -in, and even on the selected window (because the width, the truncation -flag, and display table may vary between windows). @xref{Usual -Display}. - - These functions scan text to determine where screen lines break, and -thus take time proportional to the distance scanned. If you intend to -use them heavily, Emacs provides caches which may improve the -performance of your code. @xref{Truncation, cache-long-line-scans}. - -@defun vertical-motion count &optional window -This function moves point to the start of the screen line @var{count} -screen lines down from the screen line containing point. If @var{count} -is negative, it moves up instead. - -@code{vertical-motion} returns the number of screen lines over which it -moved point. The value may be less in absolute value than @var{count} -if the beginning or end of the buffer was reached. - -The window @var{window} is used for obtaining parameters such as the -width, the horizontal scrolling, and the display table. But -@code{vertical-motion} always operates on the current buffer, even if -@var{window} currently displays some other buffer. -@end defun - -@defun count-screen-lines &optional beg end count-final-newline window -This function returns the number of screen lines in the text from -@var{beg} to @var{end}. The number of screen lines may be different -from the number of actual lines, due to line continuation, the display -table, etc. If @var{beg} and @var{end} are @code{nil} or omitted, -they default to the beginning and end of the accessible portion of the -buffer. - -If the region ends with a newline, that is ignored unless the optional -third argument @var{count-final-newline} is non-@code{nil}. - -The optional fourth argument @var{window} specifies the window for -obtaining parameters such as width, horizontal scrolling, and so on. -The default is to use the selected window's parameters. - -Like @code{vertical-motion}, @code{count-screen-lines} always uses the -current buffer, regardless of which buffer is displayed in -@var{window}. This makes possible to use @code{count-screen-lines} in -any buffer, whether or not it is currently displayed in some window. -@end defun - -@deffn Command move-to-window-line count -This function moves point with respect to the text currently displayed -in the selected window. It moves point to the beginning of the screen -line @var{count} screen lines from the top of the window. If -@var{count} is negative, that specifies a position -@w{@minus{}@var{count}} lines from the bottom (or the last line of the -buffer, if the buffer ends above the specified screen position). - -If @var{count} is @code{nil}, then point moves to the beginning of the -line in the middle of the window. If the absolute value of @var{count} -is greater than the size of the window, then point moves to the place -that would appear on that screen line if the window were tall enough. -This will probably cause the next redisplay to scroll to bring that -location onto the screen. - -In an interactive call, @var{count} is the numeric prefix argument. - -The value returned is the window line number point has moved to, with -the top line in the window numbered 0. -@end deffn - -@defun compute-motion from frompos to topos width offsets window -This function scans the current buffer, calculating screen positions. -It scans the buffer forward from position @var{from}, assuming that is -at screen coordinates @var{frompos}, to position @var{to} or coordinates -@var{topos}, whichever comes first. It returns the ending buffer -position and screen coordinates. - -The coordinate arguments @var{frompos} and @var{topos} are cons cells of -the form @code{(@var{hpos} . @var{vpos})}. - -The argument @var{width} is the number of columns available to display -text; this affects handling of continuation lines. @code{nil} means -the actual number of usable text columns in the window, which is -equivalent to the value returned by @code{(window-width window)}. - -The argument @var{offsets} is either @code{nil} or a cons cell of the -form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is -the number of columns not being displayed at the left margin; most -callers get this by calling @code{window-hscroll}. Meanwhile, -@var{tab-offset} is the offset between column numbers on the screen and -column numbers in the buffer. This can be nonzero in a continuation -line, when the previous screen lines' widths do not add up to a multiple -of @code{tab-width}. It is always zero in a non-continuation line. - -The window @var{window} serves only to specify which display table to -use. @code{compute-motion} always operates on the current buffer, -regardless of what buffer is displayed in @var{window}. - -The return value is a list of five elements: - -@example -(@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin}) -@end example - -@noindent -Here @var{pos} is the buffer position where the scan stopped, @var{vpos} -is the vertical screen position, and @var{hpos} is the horizontal screen -position. - -The result @var{prevhpos} is the horizontal position one character back -from @var{pos}. The result @var{contin} is @code{t} if the last line -was continued after (or within) the previous character. - -For example, to find the buffer position of column @var{col} of screen line -@var{line} of a certain window, pass the window's display start location -as @var{from} and the window's upper-left coordinates as @var{frompos}. -Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to -the end of the accessible portion of the buffer, and pass @var{line} and -@var{col} as @var{topos}. Here's a function that does this: - -@example -(defun coordinates-of-position (col line) - (car (compute-motion (window-start) - '(0 . 0) - (point-max) - (cons col line) - (window-width) - (cons (window-hscroll) 0) - (selected-window)))) -@end example - -When you use @code{compute-motion} for the minibuffer, you need to use -@code{minibuffer-prompt-width} to get the horizontal position of the -beginning of the first screen line. @xref{Minibuffer Contents}. -@end defun - -@node List Motion -@comment node-name, next, previous, up -@subsection Moving over Balanced Expressions -@cindex sexp motion -@cindex Lisp expression motion -@cindex list motion -@cindex balanced parenthesis motion - - Here are several functions concerned with balanced-parenthesis -expressions (also called @dfn{sexps} in connection with moving across -them in Emacs). The syntax table controls how these functions interpret -various characters; see @ref{Syntax Tables}. @xref{Parsing -Expressions}, for lower-level primitives for scanning sexps or parts of -sexps. For user-level commands, see @ref{Parentheses,, Commands for -Editing with Parentheses, emacs, The GNU Emacs Manual}. - -@deffn Command forward-list &optional arg -This function moves forward across @var{arg} (default 1) balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command backward-list &optional arg -This function moves backward across @var{arg} (default 1) balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command up-list &optional arg -This function moves forward out of @var{arg} (default 1) levels of parentheses. -A negative argument means move backward but still to a less deep spot. -@end deffn - -@deffn Command down-list &optional arg -This function moves forward into @var{arg} (default 1) levels of -parentheses. A negative argument means move backward but still go -deeper in parentheses (@minus{}@var{arg} levels). -@end deffn - -@deffn Command forward-sexp &optional arg -This function moves forward across @var{arg} (default 1) balanced expressions. -Balanced expressions include both those delimited by parentheses and -other kinds, such as words and string constants. -@xref{Parsing Expressions}. For example, - -@example -@group ----------- Buffer: foo ---------- -(concat@point{} "foo " (car x) y z) ----------- Buffer: foo ---------- -@end group - -@group -(forward-sexp 3) - @result{} nil - ----------- Buffer: foo ---------- -(concat "foo " (car x) y@point{} z) ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command backward-sexp &optional arg -This function moves backward across @var{arg} (default 1) balanced expressions. -@end deffn - -@deffn Command beginning-of-defun &optional arg -This function moves back to the @var{arg}th beginning of a defun. If -@var{arg} is negative, this actually moves forward, but it still moves -to the beginning of a defun, not to the end of one. @var{arg} defaults -to 1. -@end deffn - -@deffn Command end-of-defun &optional arg -This function moves forward to the @var{arg}th end of a defun. If -@var{arg} is negative, this actually moves backward, but it still moves -to the end of a defun, not to the beginning of one. @var{arg} defaults -to 1. -@end deffn - -@defopt defun-prompt-regexp -If non-@code{nil}, this buffer-local variable holds a regular -expression that specifies what text can appear before the -open-parenthesis that starts a defun. That is to say, a defun begins -on a line that starts with a match for this regular expression, -followed by a character with open-parenthesis syntax. -@end defopt - -@defopt open-paren-in-column-0-is-defun-start -If this variable's value is non-@code{nil}, an open parenthesis in -column 0 is considered to be the start of a defun. If it is -@code{nil}, an open parenthesis in column 0 has no special meaning. -The default is @code{t}. -@end defopt - -@defvar beginning-of-defun-function -If non-@code{nil}, this variable holds a function for finding the -beginning of a defun. The function @code{beginning-of-defun} -calls this function instead of using its normal method. -@end defvar - -@defvar end-of-defun-function -If non-@code{nil}, this variable holds a function for finding the end of -a defun. The function @code{end-of-defun} calls this function instead -of using its normal method. -@end defvar - -@node Skipping Characters -@comment node-name, next, previous, up -@subsection Skipping Characters -@cindex skipping characters - - The following two functions move point over a specified set of -characters. For example, they are often used to skip whitespace. For -related functions, see @ref{Motion and Syntax}. - -These functions convert the set string to multibyte if the buffer is -multibyte, and they convert it to unibyte if the buffer is unibyte, as -the search functions do (@pxref{Searching and Matching}). - -@defun skip-chars-forward character-set &optional limit -This function moves point in the current buffer forward, skipping over a -given set of characters. It examines the character following point, -then advances point if the character matches @var{character-set}. This -continues until it reaches a character that does not match. The -function returns the number of characters moved over. - -The argument @var{character-set} is a string, like the inside of a -@samp{[@dots{}]} in a regular expression except that @samp{]} does not -terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. -Thus, @code{"a-zA-Z"} skips over all letters, stopping before the -first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before -the first letter. See @xref{Regular Expressions}. Character classes -can also be used, e.g. @code{"[:alnum:]"}. See @pxref{Char Classes}. - -If @var{limit} is supplied (it must be a number or a marker), it -specifies the maximum position in the buffer that point can be skipped -to. Point will stop at or before @var{limit}. - -In the following example, point is initially located directly before the -@samp{T}. After the form is evaluated, point is located at the end of -that line (between the @samp{t} of @samp{hat} and the newline). The -function skips all letters and spaces, but not newlines. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(skip-chars-forward "a-zA-Z ") - @result{} nil - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end defun - -@defun skip-chars-backward character-set &optional limit -This function moves point backward, skipping characters that match -@var{character-set}, until @var{limit}. It is just like -@code{skip-chars-forward} except for the direction of motion. - -The return value indicates the distance traveled. It is an integer that -is zero or less. -@end defun - -@node Excursions -@section Excursions -@cindex excursion - - It is often useful to move point ``temporarily'' within a localized -portion of the program, or to switch buffers temporarily. This is -called an @dfn{excursion}, and it is done with the @code{save-excursion} -special form. This construct initially remembers the identity of the -current buffer, and its values of point and the mark, and restores them -after the completion of the excursion. - - The forms for saving and restoring the configuration of windows are -described elsewhere (see @ref{Window Configurations}, and @pxref{Frame -Configurations}). - -@defspec save-excursion body@dots{} -@cindex mark excursion -@cindex point excursion -The @code{save-excursion} special form saves the identity of the current -buffer and the values of point and the mark in it, evaluates -@var{body}, and finally restores the buffer and its saved values of -point and the mark. All three saved values are restored even in case of -an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). - -The @code{save-excursion} special form is the standard way to switch -buffers or move point within one part of a program and avoid affecting -the rest of the program. It is used more than 4000 times in the Lisp -sources of Emacs. - -@code{save-excursion} does not save the values of point and the mark for -other buffers, so changes in other buffers remain in effect after -@code{save-excursion} exits. - -@cindex window excursions -Likewise, @code{save-excursion} does not restore window-buffer -correspondences altered by functions such as @code{switch-to-buffer}. -One way to restore these correspondences, and the selected window, is to -use @code{save-window-excursion} inside @code{save-excursion} -(@pxref{Window Configurations}). - -The value returned by @code{save-excursion} is the result of the last -form in @var{body}, or @code{nil} if no body forms were given. - -@example -@group -(save-excursion @var{forms}) -@equiv{} -(let ((old-buf (current-buffer)) - (old-pnt (point-marker)) -@end group - (old-mark (copy-marker (mark-marker)))) - (unwind-protect - (progn @var{forms}) - (set-buffer old-buf) -@group - (goto-char old-pnt) - (set-marker (mark-marker) old-mark))) -@end group -@end example -@end defspec - - @strong{Warning:} Ordinary insertion of text adjacent to the saved -point value relocates the saved value, just as it relocates all markers. -More precisely, the saved value is a marker with insertion type -@code{nil}. @xref{Marker Insertion Types}. Therefore, when the saved -point value is restored, it normally comes before the inserted text. - - Although @code{save-excursion} saves the location of the mark, it does -not prevent functions which modify the buffer from setting -@code{deactivate-mark}, and thus causing the deactivation of the mark -after the command finishes. @xref{The Mark}. - -@node Narrowing -@section Narrowing -@cindex narrowing -@cindex restriction (in a buffer) -@cindex accessible portion (of a buffer) - - @dfn{Narrowing} means limiting the text addressable by Emacs editing -commands to a limited range of characters in a buffer. The text that -remains addressable is called the @dfn{accessible portion} of the -buffer. - - Narrowing is specified with two buffer positions which become the -beginning and end of the accessible portion. For most editing commands -and most Emacs primitives, these positions replace the values of the -beginning and end of the buffer. While narrowing is in effect, no text -outside the accessible portion is displayed, and point cannot move -outside the accessible portion. - - Values such as positions or line numbers, which usually count from the -beginning of the buffer, do so despite narrowing, but the functions -which use them refuse to operate on text that is inaccessible. - - The commands for saving buffers are unaffected by narrowing; they save -the entire buffer regardless of any narrowing. - -@deffn Command narrow-to-region start end -This function sets the accessible portion of the current buffer to start -at @var{start} and end at @var{end}. Both arguments should be character -positions. - -In an interactive call, @var{start} and @var{end} are set to the bounds -of the current region (point and the mark, with the smallest first). -@end deffn - -@deffn Command narrow-to-page &optional move-count -This function sets the accessible portion of the current buffer to -include just the current page. An optional first argument -@var{move-count} non-@code{nil} means to move forward or backward by -@var{move-count} pages and then narrow to one page. The variable -@code{page-delimiter} specifies where pages start and end -(@pxref{Standard Regexps}). - -In an interactive call, @var{move-count} is set to the numeric prefix -argument. -@end deffn - -@deffn Command widen -@cindex widening -This function cancels any narrowing in the current buffer, so that the -entire contents are accessible. This is called @dfn{widening}. -It is equivalent to the following expression: - -@example -(narrow-to-region 1 (1+ (buffer-size))) -@end example -@end deffn - -@defspec save-restriction body@dots{} -This special form saves the current bounds of the accessible portion, -evaluates the @var{body} forms, and finally restores the saved bounds, -thus restoring the same state of narrowing (or absence thereof) formerly -in effect. The state of narrowing is restored even in the event of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). -Therefore, this construct is a clean way to narrow a buffer temporarily. - -The value returned by @code{save-restriction} is that returned by the -last form in @var{body}, or @code{nil} if no body forms were given. - -@c Wordy to avoid overfull hbox. --rjc 16mar92 -@strong{Caution:} it is easy to make a mistake when using the -@code{save-restriction} construct. Read the entire description here -before you try it. - -If @var{body} changes the current buffer, @code{save-restriction} still -restores the restrictions on the original buffer (the buffer whose -restrictions it saved from), but it does not restore the identity of the -current buffer. - -@code{save-restriction} does @emph{not} restore point and the mark; use -@code{save-excursion} for that. If you use both @code{save-restriction} -and @code{save-excursion} together, @code{save-excursion} should come -first (on the outside). Otherwise, the old point value would be -restored with temporary narrowing still in effect. If the old point -value were outside the limits of the temporary narrowing, this would -fail to restore it accurately. - -Here is a simple example of correct use of @code{save-restriction}: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo -This is the contents of foo -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group - -@group -(save-excursion - (save-restriction - (goto-char 1) - (forward-line 2) - (narrow-to-region 1 (point)) - (goto-char (point-min)) - (replace-string "foo" "bar"))) - ----------- Buffer: foo ---------- -This is the contents of bar -This is the contents of bar -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group -@end example -@end defspec - -@ignore - arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87 -@end ignore diff --git a/lispref/processes.texi b/lispref/processes.texi deleted file mode 100644 index f7be990b85e..00000000000 --- a/lispref/processes.texi +++ /dev/null @@ -1,2561 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/processes -@node Processes, Display, Abbrevs, Top -@chapter Processes -@cindex child process -@cindex parent process -@cindex subprocess -@cindex process - - In the terminology of operating systems, a @dfn{process} is a space in -which a program can execute. Emacs runs in a process. Emacs Lisp -programs can invoke other programs in processes of their own. These are -called @dfn{subprocesses} or @dfn{child processes} of the Emacs process, -which is their @dfn{parent process}. - - A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous}, -depending on how it is created. When you create a synchronous -subprocess, the Lisp program waits for the subprocess to terminate -before continuing execution. When you create an asynchronous -subprocess, it can run in parallel with the Lisp program. This kind of -subprocess is represented within Emacs by a Lisp object which is also -called a ``process.'' Lisp programs can use this object to communicate -with the subprocess or to control it. For example, you can send -signals, obtain status information, receive output from the process, or -send input to it. - -@defun processp object -This function returns @code{t} if @var{object} is a process, -@code{nil} otherwise. -@end defun - -@menu -* 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. -@end menu - -@node Subprocess Creation -@section Functions that Create Subprocesses - - There are three functions that create a new subprocess in which to run -a program. One of them, @code{start-process}, creates an asynchronous -process and returns a process object (@pxref{Asynchronous Processes}). -The other two, @code{call-process} and @code{call-process-region}, -create a synchronous process and do not return a process object -(@pxref{Synchronous Processes}). - - Synchronous and asynchronous processes are explained in the following -sections. Since the three functions are all called in a similar -fashion, their common arguments are described here. - -@cindex execute program -@cindex @code{PATH} environment variable -@cindex @code{HOME} environment variable - In all cases, the function's @var{program} argument specifies the -program to be run. An error is signaled if the file is not found or -cannot be executed. If the file name is relative, the variable -@code{exec-path} contains a list of directories to search. Emacs -initializes @code{exec-path} when it starts up, based on the value of -the environment variable @code{PATH}. The standard file name -constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as -usual in @code{exec-path}, but environment variable substitutions -(@samp{$HOME}, etc.) are not recognized; use -@code{substitute-in-file-name} to perform them (@pxref{File Name -Expansion}). @code{nil} in this list refers to -@code{default-directory}. - - Executing a program can also try adding suffixes to the specified -name: - -@defvar exec-suffixes -This variable is a list of suffixes (strings) to try adding to the -specified program file name. The list should include @code{""} if you -want the name to be tried exactly as specified. The default value is -system-dependent. -@end defvar - - @strong{Please note:} The argument @var{program} contains only the -name of the program; it may not contain any command-line arguments. You -must use @var{args} to provide those. - - Each of the subprocess-creating functions has a @var{buffer-or-name} -argument which specifies where the standard output from the program will -go. It should be a buffer or a buffer name; if it is a buffer name, -that will create the buffer if it does not already exist. It can also -be @code{nil}, which says to discard the output unless a filter function -handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) -Normally, you should avoid having multiple processes send output to the -same buffer because their output would be intermixed randomly. - -@cindex program arguments - All three of the subprocess-creating functions have a @code{&rest} -argument, @var{args}. The @var{args} must all be strings, and they are -supplied to @var{program} as separate command line arguments. Wildcard -characters and other shell constructs have no special meanings in these -strings, since the strings are passed directly to the specified program. - - The subprocess gets its current directory from the value of -@code{default-directory} (@pxref{File Name Expansion}). - -@cindex environment variables, subprocesses - The subprocess inherits its environment from Emacs, but you can -specify overrides for it with @code{process-environment}. @xref{System -Environment}. - -@defvar exec-directory -@pindex movemail -The value of this variable is a string, the name of a directory that -contains programs that come with GNU Emacs, programs intended for Emacs -to invoke. The program @code{movemail} is an example of such a program; -Rmail uses it to fetch new mail from an inbox. -@end defvar - -@defopt exec-path -The value of this variable is a list of directories to search for -programs to run in subprocesses. Each element is either the name of a -directory (i.e., a string), or @code{nil}, which stands for the default -directory (which is the value of @code{default-directory}). -@cindex program directories - -The value of @code{exec-path} is used by @code{call-process} and -@code{start-process} when the @var{program} argument is not an absolute -file name. -@end defopt - -@node Shell Arguments -@section Shell Arguments -@cindex arguments for shell commands -@cindex shell command arguments - - Lisp programs sometimes need to run a shell and give it a command -that contains file names that were specified by the user. These -programs ought to be able to support any valid file name. But the shell -gives special treatment to certain characters, and if these characters -occur in the file name, they will confuse the shell. To handle these -characters, use the function @code{shell-quote-argument}: - -@defun shell-quote-argument argument -This function returns a string which represents, in shell syntax, -an argument whose actual contents are @var{argument}. It should -work reliably to concatenate the return value into a shell command -and then pass it to a shell for execution. - -Precisely what this function does depends on your operating system. The -function is designed to work with the syntax of your system's standard -shell; if you use an unusual shell, you will need to redefine this -function. - -@example -;; @r{This example shows the behavior on GNU and Unix systems.} -(shell-quote-argument "foo > bar") - @result{} "foo\\ \\>\\ bar" - -;; @r{This example shows the behavior on MS-DOS and MS-Windows.} -(shell-quote-argument "foo > bar") - @result{} "\"foo > bar\"" -@end example - -Here's an example of using @code{shell-quote-argument} to construct -a shell command: - -@example -(concat "diff -c " - (shell-quote-argument oldfile) - " " - (shell-quote-argument newfile)) -@end example -@end defun - -@node Synchronous Processes -@section Creating a Synchronous Process -@cindex synchronous subprocess - - After a @dfn{synchronous process} is created, Emacs waits for the -process to terminate before continuing. Starting Dired on GNU or -Unix@footnote{On other systems, Emacs uses a Lisp emulation of -@code{ls}; see @ref{Contents of Directories}.} is an example of this: it -runs @code{ls} in a synchronous process, then modifies the output -slightly. Because the process is synchronous, the entire directory -listing arrives in the buffer before Emacs tries to do anything with it. - - While Emacs waits for the synchronous subprocess to terminate, the -user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill -the subprocess with a @code{SIGINT} signal; but it waits until the -subprocess actually terminates before quitting. If during that time the -user types another @kbd{C-g}, that kills the subprocess instantly with -@code{SIGKILL} and quits immediately (except on MS-DOS, where killing -other processes doesn't work). @xref{Quitting}. - - The synchronous subprocess functions return an indication of how the -process terminated. - - The output from a synchronous subprocess is generally decoded using a -coding system, much like text read from a file. The input sent to a -subprocess by @code{call-process-region} is encoded using a coding -system, much like text written into a file. @xref{Coding Systems}. - -@defun call-process program &optional infile destination display &rest args -This function calls @var{program} in a separate process and waits for -it to finish. - -The standard input for the process comes from file @var{infile} if -@var{infile} is not @code{nil}, and from the null device otherwise. -The argument @var{destination} says where to put the process output. -Here are the possibilities: - -@table @asis -@item a buffer -Insert the output in that buffer, before point. This includes both the -standard output stream and the standard error stream of the process. - -@item a string -Insert the output in a buffer with that name, before point. - -@item @code{t} -Insert the output in the current buffer, before point. - -@item @code{nil} -Discard the output. - -@item 0 -Discard the output, and return @code{nil} immediately without waiting -for the subprocess to finish. - -In this case, the process is not truly synchronous, since it can run in -parallel with Emacs; but you can think of it as synchronous in that -Emacs is essentially finished with the subprocess as soon as this -function returns. - -MS-DOS doesn't support asynchronous subprocesses, so this option doesn't -work there. - -@item @code{(@var{real-destination} @var{error-destination})} -Keep the standard output stream separate from the standard error stream; -deal with the ordinary output as specified by @var{real-destination}, -and dispose of the error output according to @var{error-destination}. -If @var{error-destination} is @code{nil}, that means to discard the -error output, @code{t} means mix it with the ordinary output, and a -string specifies a file name to redirect error output into. - -You can't directly specify a buffer to put the error output in; that is -too difficult to implement. But you can achieve this result by sending -the error output to a temporary file and then inserting the file into a -buffer. -@end table - -If @var{display} is non-@code{nil}, then @code{call-process} redisplays -the buffer as output is inserted. (However, if the coding system chosen -for decoding output is @code{undecided}, meaning deduce the encoding -from the actual data, then redisplay sometimes cannot continue once -non-@acronym{ASCII} characters are encountered. There are fundamental -reasons why it is hard to fix this; see @ref{Output from Processes}.) - -Otherwise the function @code{call-process} does no redisplay, and the -results become visible on the screen only when Emacs redisplays that -buffer in the normal course of events. - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -The value returned by @code{call-process} (unless you told it not to -wait) indicates the reason for process termination. A number gives the -exit status of the subprocess; 0 means success, and any other value -means failure. If the process terminated with a signal, -@code{call-process} returns a string describing the signal. - -In the examples below, the buffer @samp{foo} is current. - -@smallexample -@group -(call-process "pwd" nil t) - @result{} 0 - ----------- Buffer: foo ---------- -/usr/user/lewis/manual ----------- Buffer: foo ---------- -@end group - -@group -(call-process "grep" nil "bar" nil "lewis" "/etc/passwd") - @result{} 0 - ----------- Buffer: bar ---------- -lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh - ----------- Buffer: bar ---------- -@end group -@end smallexample - -Here is a good example of the use of @code{call-process}, which used to -be found in the definition of @code{insert-directory}: - -@smallexample -@group -(call-process insert-directory-program nil t nil @var{switches} - (if full-directory-p - (concat (file-name-as-directory file) ".") - file)) -@end group -@end smallexample -@end defun - -@defun process-file program &optional infile buffer display &rest args -This function processes files synchronously in a separate process. It -is similar to @code{call-process} but may invoke a file handler based -on the value of the variable @code{default-directory}. The current -working directory of the subprocess is @code{default-directory}. - -The arguments are handled in almost the same way as for -@code{call-process}, with the following differences: - -Some file handlers may not support all combinations and forms of the -arguments @var{infile}, @var{buffer}, and @var{display}. For example, -some file handlers might behave as if @var{display} were @code{nil}, -regardless of the value actually passed. As another example, some -file handlers might not support separating standard output and error -output by way of the @var{buffer} argument. - -If a file handler is invoked, it determines the program to run based -on the first argument @var{program}. For instance, consider that a -handler for remote files is invoked. Then the path that is used for -searching the program might be different than @code{exec-path}. - -The second argument @var{infile} may invoke a file handler. The file -handler could be different from the handler chosen for the -@code{process-file} function itself. (For example, -@code{default-directory} could be on a remote host, whereas -@var{infile} is on another remote host. Or @code{default-directory} -could be non-special, whereas @var{infile} is on a remote host.) - -If @var{buffer} is a list of the form @code{(@var{real-destination} -@var{error-destination})}, and @var{error-destination} names a file, -then the same remarks as for @var{infile} apply. - -The remaining arguments (@var{args}) will be passed to the process -verbatim. Emacs is not involved in processing file names that are -present in @var{args}. To avoid confusion, it may be best to avoid -absolute file names in @var{args}, but rather to specify all file -names as relative to @code{default-directory}. The function -@code{file-relative-name} is useful for constructing such relative -file names. -@end defun - -@defun call-process-region start end program &optional delete destination display &rest args -This function sends the text from @var{start} to @var{end} as -standard input to a process running @var{program}. It deletes the text -sent if @var{delete} is non-@code{nil}; this is useful when -@var{destination} is @code{t}, to insert the output in the current -buffer in place of the input. - -The arguments @var{destination} and @var{display} control what to do -with the output from the subprocess, and whether to update the display -as it comes in. For details, see the description of -@code{call-process}, above. If @var{destination} is the integer 0, -@code{call-process-region} discards the output and returns @code{nil} -immediately, without waiting for the subprocess to finish (this only -works if asynchronous subprocesses are supported). - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -The return value of @code{call-process-region} is just like that of -@code{call-process}: @code{nil} if you told it to return without -waiting; otherwise, a number or string which indicates how the -subprocess terminated. - -In the following example, we use @code{call-process-region} to run the -@code{cat} utility, with standard input being the first five characters -in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its -standard input into its standard output. Since the argument -@var{destination} is @code{t}, this output is inserted in the current -buffer. - -@smallexample -@group ----------- Buffer: foo ---------- -input@point{} ----------- Buffer: foo ---------- -@end group - -@group -(call-process-region 1 6 "cat" nil t) - @result{} 0 - ----------- Buffer: foo ---------- -inputinput@point{} ----------- Buffer: foo ---------- -@end group -@end smallexample - - The @code{shell-command-on-region} command uses -@code{call-process-region} like this: - -@smallexample -@group -(call-process-region - start end - shell-file-name ; @r{Name of program.} - nil ; @r{Do not delete region.} - buffer ; @r{Send output to @code{buffer}.} - nil ; @r{No redisplay during output.} - "-c" command) ; @r{Arguments for the shell.} -@end group -@end smallexample -@end defun - -@defun call-process-shell-command command &optional infile destination display &rest args -This function executes the shell command @var{command} synchronously -in a separate process. The final arguments @var{args} are additional -arguments to add at the end of @var{command}. The other arguments -are handled as in @code{call-process}. -@end defun - -@defun process-file-shell-command command &optional infile destination display &rest args -This function is like @code{call-process-shell-command}, but uses -@code{process-file} internally. Depending on @code{default-directory}, -@var{command} can be executed also on remote hosts. -@end defun - -@defun shell-command-to-string command -This function executes @var{command} (a string) as a shell command, -then returns the command's output as a string. -@end defun - -@node Asynchronous Processes -@section Creating an Asynchronous Process -@cindex asynchronous subprocess - - After an @dfn{asynchronous process} is created, Emacs and the subprocess -both continue running immediately. The process thereafter runs -in parallel with Emacs, and the two can communicate with each other -using the functions described in the following sections. However, -communication is only partially asynchronous: Emacs sends data to the -process only when certain functions are called, and Emacs accepts data -from the process only when Emacs is waiting for input or for a time -delay. - - Here we describe how to create an asynchronous process. - -@defun start-process name buffer-or-name program &rest args -This function creates a new asynchronous subprocess and starts the -program @var{program} running in it. It returns a process object that -stands for the new subprocess in Lisp. The argument @var{name} -specifies the name for the process object; if a process with this name -already exists, then @var{name} is modified (by appending @samp{<1>}, -etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to -associate with the process. - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -In the example below, the first process is started and runs (rather, -sleeps) for 100 seconds. Meanwhile, the second process is started, and -given the name @samp{my-process<1>} for the sake of uniqueness. It -inserts the directory listing at the end of the buffer @samp{foo}, -before the first process finishes. Then it finishes, and a message to -that effect is inserted in the buffer. Much later, the first process -finishes, and another message is inserted in the buffer for it. - -@smallexample -@group -(start-process "my-process" "foo" "sleep" "100") - @result{} #<process my-process> -@end group - -@group -(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") - @result{} #<process my-process<1>> - ----------- Buffer: foo ---------- -total 2 -lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs --rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon - -Process my-process<1> finished - -Process my-process finished ----------- Buffer: foo ---------- -@end group -@end smallexample -@end defun - -@defun start-file-process name buffer-or-name program &rest args -Like @code{start-process}, this function starts a new asynchronous -subprocess running @var{program} in it, and returns its process -object---when @code{default-directory} is not a magic file name. - -If @code{default-directory} is magic, the function invokes its file -handler instead. This handler ought to run @var{program}, perhaps on -the local host, perhaps on a remote host that corresponds to -@code{default-directory}. In the latter case, the local part of -@code{default-directory} becomes the working directory of the process. - -This function does not try to invoke file name handlers for -@var{program} or for the @var{program-args}. - -Depending on the implementation of the file handler, it might not be -possible to apply @code{process-filter} or @code{process-sentinel} to -the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}). - -Some file handlers may not support @code{start-file-process} (for -example @code{ange-ftp-hook-function}). In such cases, the function -does nothing and returns @code{nil}. -@end defun - -@defun start-process-shell-command name buffer-or-name command &rest command-args -This function is like @code{start-process} except that it uses a shell -to execute the specified command. The argument @var{command} is a shell -command name, and @var{command-args} are the arguments for the shell -command. The variable @code{shell-file-name} specifies which shell to -use. - -The point of running a program through the shell, rather than directly -with @code{start-process}, is so that you can employ shell features such -as wildcards in the arguments. It follows that if you include an -arbitrary user-specified arguments in the command, you should quote it -with @code{shell-quote-argument} first, so that any special shell -characters do @emph{not} have their special shell meanings. @xref{Shell -Arguments}. -@end defun - -@defun start-file-process-shell-command name buffer-or-name command &rest command-args -This function is like @code{start-process-shell-command}, but uses -@code{start-file-process} internally. By this, @var{command} can be -executed also on remote hosts, depending on @code{default-directory}. -@end defun - -@defvar process-connection-type -@cindex pipes -@cindex @acronym{PTY}s -This variable controls the type of device used to communicate with -asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are -used, when available. Otherwise, pipes are used. - -@acronym{PTY}s are usually preferable for processes visible to the user, as -in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z}, -etc.) to work between the process and its children, whereas pipes do -not. For subprocesses used for internal purposes by programs, it is -often better to use a pipe, because they are more efficient. In -addition, the total number of @acronym{PTY}s is limited on many systems and -it is good not to waste them. - -The value of @code{process-connection-type} takes effect when -@code{start-process} is called. So you can specify how to communicate -with one subprocess by binding the variable around the call to -@code{start-process}. - -@smallexample -@group -(let ((process-connection-type nil)) ; @r{Use a pipe.} - (start-process @dots{})) -@end group -@end smallexample - -To determine whether a given subprocess actually got a pipe or a -@acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process -Information}). -@end defvar - -@node Deleting Processes -@section Deleting Processes -@cindex deleting processes - - @dfn{Deleting a process} disconnects Emacs immediately from the -subprocess. Processes are deleted automatically after they terminate, -but not necessarily right away. You can delete a process explicitly -at any time. If you delete a terminated process explicitly before it -is deleted automatically, no harm results. Deleting a running -process sends a signal to terminate it (and its child processes if -any), and calls the process sentinel if it has one. @xref{Sentinels}. - - When a process is deleted, the process object itself continues to -exist as long as other Lisp objects point to it. All the Lisp -primitives that work on process objects accept deleted processes, but -those that do I/O or send signals will report an error. The process -mark continues to point to the same place as before, usually into a -buffer where output from the process was being inserted. - -@defopt delete-exited-processes -This variable controls automatic deletion of processes that have -terminated (due to calling @code{exit} or to a signal). If it is -@code{nil}, then they continue to exist until the user runs -@code{list-processes}. Otherwise, they are deleted immediately after -they exit. -@end defopt - -@defun delete-process process -This function deletes a process, killing it with a @code{SIGKILL} -signal. The argument may be a process, the name of a process, a -buffer, or the name of a buffer. (A buffer or buffer-name stands for -the process that @code{get-buffer-process} returns.) Calling -@code{delete-process} on a running process terminates it, updates the -process status, and runs the sentinel (if any) immediately. If the -process has already terminated, calling @code{delete-process} has no -effect on its status, or on the running of its sentinel (which will -happen sooner or later). - -@smallexample -@group -(delete-process "*shell*") - @result{} nil -@end group -@end smallexample -@end defun - -@node Process Information -@section Process Information - - Several functions return information about processes. -@code{list-processes} is provided for interactive use. - -@deffn Command list-processes &optional query-only -This command displays a listing of all living processes. In addition, -it finally deletes any process whose status was @samp{Exited} or -@samp{Signaled}. It returns @code{nil}. - -If @var{query-only} is non-@code{nil} then it lists only processes -whose query flag is non-@code{nil}. @xref{Query Before Exit}. -@end deffn - -@defun process-list -This function returns a list of all processes that have not been deleted. - -@smallexample -@group -(process-list) - @result{} (#<process display-time> #<process shell>) -@end group -@end smallexample -@end defun - -@defun get-process name -This function returns the process named @var{name}, or @code{nil} if -there is none. An error is signaled if @var{name} is not a string. - -@smallexample -@group -(get-process "shell") - @result{} #<process shell> -@end group -@end smallexample -@end defun - -@defun process-command process -This function returns the command that was executed to start -@var{process}. This is a list of strings, the first string being the -program executed and the rest of the strings being the arguments that -were given to the program. - -@smallexample -@group -(process-command (get-process "shell")) - @result{} ("/bin/csh" "-i") -@end group -@end smallexample -@end defun - -@defun process-id process -This function returns the @acronym{PID} of @var{process}. This is an -integer that distinguishes the process @var{process} from all other -processes running on the same computer at the current time. The -@acronym{PID} of a process is chosen by the operating system kernel when the -process is started and remains constant as long as the process exists. -@end defun - -@defun process-name process -This function returns the name of @var{process}. -@end defun - -@defun process-status process-name -This function returns the status of @var{process-name} as a symbol. -The argument @var{process-name} must be a process, a buffer, a -process name (string) or a buffer name (string). - -The possible values for an actual subprocess are: - -@table @code -@item run -for a process that is running. -@item stop -for a process that is stopped but continuable. -@item exit -for a process that has exited. -@item signal -for a process that has received a fatal signal. -@item open -for a network connection that is open. -@item closed -for a network connection that is closed. Once a connection -is closed, you cannot reopen it, though you might be able to open -a new connection to the same place. -@item connect -for a non-blocking connection that is waiting to complete. -@item failed -for a non-blocking connection that has failed to complete. -@item listen -for a network server that is listening. -@item nil -if @var{process-name} is not the name of an existing process. -@end table - -@smallexample -@group -(process-status "shell") - @result{} run -@end group -@group -(process-status (get-buffer "*shell*")) - @result{} run -@end group -@group -x - @result{} #<process xx<1>> -(process-status x) - @result{} exit -@end group -@end smallexample - -For a network connection, @code{process-status} returns one of the symbols -@code{open} or @code{closed}. The latter means that the other side -closed the connection, or Emacs did @code{delete-process}. -@end defun - -@defun process-exit-status process -This function returns the exit status of @var{process} or the signal -number that killed it. (Use the result of @code{process-status} to -determine which of those it is.) If @var{process} has not yet -terminated, the value is 0. -@end defun - -@defun process-tty-name process -This function returns the terminal name that @var{process} is using for -its communication with Emacs---or @code{nil} if it is using pipes -instead of a terminal (see @code{process-connection-type} in -@ref{Asynchronous Processes}). -@end defun - -@defun process-coding-system process -@anchor{Coding systems for a subprocess} -This function returns a cons cell describing the coding systems in use -for decoding output from @var{process} and for encoding input to -@var{process} (@pxref{Coding Systems}). The value has this form: - -@example -(@var{coding-system-for-decoding} . @var{coding-system-for-encoding}) -@end example -@end defun - -@defun set-process-coding-system process &optional decoding-system encoding-system -This function specifies the coding systems to use for subsequent output -from and input to @var{process}. It will use @var{decoding-system} to -decode subprocess output, and @var{encoding-system} to encode subprocess -input. -@end defun - - Every process also has a property list that you can use to store -miscellaneous values associated with the process. - -@defun process-get process propname -This function returns the value of the @var{propname} property -of @var{process}. -@end defun - -@defun process-put process propname value -This function sets the value of the @var{propname} property -of @var{process} to @var{value}. -@end defun - -@defun process-plist process -This function returns the process plist of @var{process}. -@end defun - -@defun set-process-plist process plist -This function sets the process plist of @var{process} to @var{plist}. -@end defun - -@node Input to Processes -@section Sending Input to Processes -@cindex process input - - Asynchronous subprocesses receive input when it is sent to them by -Emacs, which is done with the functions in this section. You must -specify the process to send input to, and the input data to send. The -data appears on the ``standard input'' of the subprocess. - - Some operating systems have limited space for buffered input in a -@acronym{PTY}. On these systems, Emacs sends an @acronym{EOF} -periodically amidst the other characters, to force them through. For -most programs, these @acronym{EOF}s do no harm. - - Subprocess input is normally encoded using a coding system before the -subprocess receives it, much like text written into a file. You can use -@code{set-process-coding-system} to specify which coding system to use -(@pxref{Process Information}). Otherwise, the coding system comes from -@code{coding-system-for-write}, if that is non-@code{nil}; or else from -the defaulting mechanism (@pxref{Default Coding Systems}). - - Sometimes the system is unable to accept input for that process, -because the input buffer is full. When this happens, the send functions -wait a short while, accepting output from subprocesses, and then try -again. This gives the subprocess a chance to read more of its pending -input and make space in the buffer. It also allows filters, sentinels -and timers to run---so take account of that in writing your code. - - In these functions, the @var{process} argument can be a process or -the name of a process, or a buffer or buffer name (which stands -for a process via @code{get-buffer-process}). @code{nil} means -the current buffer's process. - -@defun process-send-string process string -This function sends @var{process} the contents of @var{string} as -standard input. If it is @code{nil}, the current buffer's process is used. - - The function returns @code{nil}. - -@smallexample -@group -(process-send-string "shell<1>" "ls\n") - @result{} nil -@end group - - -@group ----------- Buffer: *shell* ---------- -... -introduction.texi syntax-tables.texi~ -introduction.texi~ text.texi -introduction.txt text.texi~ -... ----------- Buffer: *shell* ---------- -@end group -@end smallexample -@end defun - -@defun process-send-region process start end -This function sends the text in the region defined by @var{start} and -@var{end} as standard input to @var{process}. - -An error is signaled unless both @var{start} and @var{end} are -integers or markers that indicate positions in the current buffer. (It -is unimportant which number is larger.) -@end defun - -@defun process-send-eof &optional process -This function makes @var{process} see an end-of-file in its -input. The @acronym{EOF} comes after any text already sent to it. - -The function returns @var{process}. - -@smallexample -@group -(process-send-eof "shell") - @result{} "shell" -@end group -@end smallexample -@end defun - -@defun process-running-child-p process -This function will tell you whether a subprocess has given control of -its terminal to its own child process. The value is @code{t} if this is -true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain -that this is not so. -@end defun - -@node Signals to Processes -@section Sending Signals to Processes -@cindex process signals -@cindex sending signals -@cindex signals - - @dfn{Sending a signal} to a subprocess is a way of interrupting its -activities. There are several different signals, each with its own -meaning. The set of signals and their names is defined by the operating -system. For example, the signal @code{SIGINT} means that the user has -typed @kbd{C-c}, or that some analogous thing has happened. - - Each signal has a standard effect on the subprocess. Most signals -kill the subprocess, but some stop or resume execution instead. Most -signals can optionally be handled by programs; if the program handles -the signal, then we can say nothing in general about its effects. - - You can send signals explicitly by calling the functions in this -section. Emacs also sends signals automatically at certain times: -killing a buffer sends a @code{SIGHUP} signal to all its associated -processes; killing Emacs sends a @code{SIGHUP} signal to all remaining -processes. (@code{SIGHUP} is a signal that usually indicates that the -user hung up the phone.) - - Each of the signal-sending functions takes two optional arguments: -@var{process} and @var{current-group}. - - The argument @var{process} must be either a process, a process -name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name -stands for a process through @code{get-buffer-process}. @code{nil} -stands for the process associated with the current buffer. An error -is signaled if @var{process} does not identify a process. - - The argument @var{current-group} is a flag that makes a difference -when you are running a job-control shell as an Emacs subprocess. If it -is non-@code{nil}, then the signal is sent to the current process-group -of the terminal that Emacs uses to communicate with the subprocess. If -the process is a job-control shell, this means the shell's current -subjob. If it is @code{nil}, the signal is sent to the process group of -the immediate subprocess of Emacs. If the subprocess is a job-control -shell, this is the shell itself. - - The flag @var{current-group} has no effect when a pipe is used to -communicate with the subprocess, because the operating system does not -support the distinction in the case of pipes. For the same reason, -job-control shells won't work when a pipe is used. See -@code{process-connection-type} in @ref{Asynchronous Processes}. - -@defun interrupt-process &optional process current-group -This function interrupts the process @var{process} by sending the -signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt -character'' (normally @kbd{C-c} on some systems, and @code{DEL} on -others) sends this signal. When the argument @var{current-group} is -non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' -on the terminal by which Emacs talks to the subprocess. -@end defun - -@defun kill-process &optional process current-group -This function kills the process @var{process} by sending the -signal @code{SIGKILL}. This signal kills the subprocess immediately, -and cannot be handled by the subprocess. -@end defun - -@defun quit-process &optional process current-group -This function sends the signal @code{SIGQUIT} to the process -@var{process}. This signal is the one sent by the ``quit -character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside -Emacs. -@end defun - -@defun stop-process &optional process current-group -This function stops the process @var{process} by sending the -signal @code{SIGTSTP}. Use @code{continue-process} to resume its -execution. - -Outside of Emacs, on systems with job control, the ``stop character'' -(usually @kbd{C-z}) normally sends this signal. When -@var{current-group} is non-@code{nil}, you can think of this function as -``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the -subprocess. -@end defun - -@defun continue-process &optional process current-group -This function resumes execution of the process @var{process} by sending -it the signal @code{SIGCONT}. This presumes that @var{process} was -stopped previously. -@end defun - -@c Emacs 19 feature -@defun signal-process process signal -This function sends a signal to process @var{process}. The argument -@var{signal} specifies which signal to send; it should be an integer. - -The @var{process} argument can be a system process @acronym{ID}; that -allows you to send signals to processes that are not children of -Emacs. -@end defun - -@node Output from Processes -@section Receiving Output from Processes -@cindex process output -@cindex output from processes - - There are two ways to receive the output that a subprocess writes to -its standard output stream. The output can be inserted in a buffer, -which is called the associated buffer of the process, or a function -called the @dfn{filter function} can be called to act on the output. If -the process has no buffer and no filter function, its output is -discarded. - - When a subprocess terminates, Emacs reads any pending output, -then stops reading output from that subprocess. Therefore, if the -subprocess has children that are still live and still producing -output, Emacs won't receive that output. - - Output from a subprocess can arrive only while Emacs is waiting: when -reading terminal input, in @code{sit-for} and @code{sleep-for} -(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting -Output}). This minimizes the problem of timing errors that usually -plague parallel programming. For example, you can safely create a -process and only then specify its buffer or filter function; no output -can arrive before you finish, if the code in between does not call any -primitive that waits. - -@defvar process-adaptive-read-buffering -On some systems, when Emacs reads the output from a subprocess, the -output data is read in very small blocks, potentially resulting in -very poor performance. This behavior can be remedied to some extent -by setting the variable @var{process-adaptive-read-buffering} to a -non-@code{nil} value (the default), as it will automatically delay reading -from such processes, thus allowing them to produce more output before -Emacs tries to read it. -@end defvar - - It is impossible to separate the standard output and standard error -streams of the subprocess, because Emacs normally spawns the subprocess -inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If -you want to keep the output to those streams separate, you should -redirect one of them to a file---for example, by using an appropriate -shell command. - -@menu -* 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. -@end menu - -@node Process Buffers -@subsection Process Buffers - - A process can (and usually does) have an @dfn{associated buffer}, -which is an ordinary Emacs buffer that is used for two purposes: storing -the output from the process, and deciding when to kill the process. You -can also use the buffer to identify a process to operate on, since in -normal practice only one process is associated with any given buffer. -Many applications of processes also use the buffer for editing input to -be sent to the process, but this is not built into Emacs Lisp. - - Unless the process has a filter function (@pxref{Filter Functions}), -its output is inserted in the associated buffer. The position to insert -the output is determined by the @code{process-mark}, which is then -updated to point to the end of the text just inserted. Usually, but not -always, the @code{process-mark} is at the end of the buffer. - -@defun process-buffer process -This function returns the associated buffer of the process -@var{process}. - -@smallexample -@group -(process-buffer (get-process "shell")) - @result{} #<buffer *shell*> -@end group -@end smallexample -@end defun - -@defun process-mark process -This function returns the process marker for @var{process}, which is the -marker that says where to insert output from the process. - -If @var{process} does not have a buffer, @code{process-mark} returns a -marker that points nowhere. - -Insertion of process output in a buffer uses this marker to decide where -to insert, and updates it to point after the inserted text. That is why -successive batches of output are inserted consecutively. - -Filter functions normally should use this marker in the same fashion -as is done by direct insertion of output in the buffer. A good -example of a filter function that uses @code{process-mark} is found at -the end of the following section. - -When the user is expected to enter input in the process buffer for -transmission to the process, the process marker separates the new input -from previous output. -@end defun - -@defun set-process-buffer process buffer -This function sets the buffer associated with @var{process} to -@var{buffer}. If @var{buffer} is @code{nil}, the process becomes -associated with no buffer. -@end defun - -@defun get-buffer-process buffer-or-name -This function returns a nondeleted process associated with the buffer -specified by @var{buffer-or-name}. If there are several processes -associated with it, this function chooses one (currently, the one most -recently created, but don't count on that). Deletion of a process -(see @code{delete-process}) makes it ineligible for this function to -return. - -It is usually a bad idea to have more than one process associated with -the same buffer. - -@smallexample -@group -(get-buffer-process "*shell*") - @result{} #<process shell> -@end group -@end smallexample - -Killing the process's buffer deletes the process, which kills the -subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). -@end defun - -@node Filter Functions -@subsection Process Filter Functions -@cindex filter function -@cindex process filter - - A process @dfn{filter function} is a function that receives the -standard output from the associated process. If a process has a filter, -then @emph{all} output from that process is passed to the filter. The -process buffer is used directly for output from the process only when -there is no filter. - - The filter function can only be called when Emacs is waiting for -something, because process output arrives only at such times. Emacs -waits when reading terminal input, in @code{sit-for} and -@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output} -(@pxref{Accepting Output}). - - A filter function must accept two arguments: the associated process -and a string, which is output just received from it. The function is -then free to do whatever it chooses with the output. - - Quitting is normally inhibited within a filter function---otherwise, -the effect of typing @kbd{C-g} at command level or to quit a user -command would be unpredictable. If you want to permit quitting inside -a filter function, bind @code{inhibit-quit} to @code{nil}. In most -cases, the right way to do this is with the macro -@code{with-local-quit}. @xref{Quitting}. - - If an error happens during execution of a filter function, it is -caught automatically, so that it doesn't stop the execution of whatever -program was running when the filter function was started. However, if -@code{debug-on-error} is non-@code{nil}, the error-catching is turned -off. This makes it possible to use the Lisp debugger to debug the -filter function. @xref{Debugger}. - - Many filter functions sometimes or always insert the text in the -process's buffer, mimicking the actions of Emacs when there is no -filter. Such filter functions need to use @code{set-buffer} in order to -be sure to insert in that buffer. To avoid setting the current buffer -semipermanently, these filter functions must save and restore the -current buffer. They should also update the process marker, and in some -cases update the value of point. Here is how to do these things: - -@smallexample -@group -(defun ordinary-insertion-filter (proc string) - (with-current-buffer (process-buffer proc) - (let ((moving (= (point) (process-mark proc)))) -@end group -@group - (save-excursion - ;; @r{Insert the text, advancing the process marker.} - (goto-char (process-mark proc)) - (insert string) - (set-marker (process-mark proc) (point))) - (if moving (goto-char (process-mark proc)))))) -@end group -@end smallexample - -@noindent -The reason to use @code{with-current-buffer}, rather than using -@code{save-excursion} to save and restore the current buffer, is so as -to preserve the change in point made by the second call to -@code{goto-char}. - - To make the filter force the process buffer to be visible whenever new -text arrives, insert the following line just before the -@code{with-current-buffer} construct: - -@smallexample -(display-buffer (process-buffer proc)) -@end smallexample - - To force point to the end of the new output, no matter where it was -previously, eliminate the variable @code{moving} and call -@code{goto-char} unconditionally. - - In earlier Emacs versions, every filter function that did regular -expression searching or matching had to explicitly save and restore the -match data. Now Emacs does this automatically for filter functions; -they never need to do it explicitly. @xref{Match Data}. - - A filter function that writes the output into the buffer of the -process should check whether the buffer is still alive. If it tries to -insert into a dead buffer, it will get an error. The expression -@code{(buffer-name (process-buffer @var{process}))} returns @code{nil} -if the buffer is dead. - - The output to the function may come in chunks of any size. A program -that produces the same output twice in a row may send it as one batch of -200 characters one time, and five batches of 40 characters the next. If -the filter looks for certain text strings in the subprocess output, make -sure to handle the case where one of these strings is split across two -or more batches of output. - -@defun set-process-filter process filter -This function gives @var{process} the filter function @var{filter}. If -@var{filter} is @code{nil}, it gives the process no filter. -@end defun - -@defun process-filter process -This function returns the filter function of @var{process}, or @code{nil} -if it has none. -@end defun - - Here is an example of use of a filter function: - -@smallexample -@group -(defun keep-output (process output) - (setq kept (cons output kept))) - @result{} keep-output -@end group -@group -(setq kept nil) - @result{} nil -@end group -@group -(set-process-filter (get-process "shell") 'keep-output) - @result{} keep-output -@end group -@group -(process-send-string "shell" "ls ~/other\n") - @result{} nil -kept - @result{} ("lewis@@slug[8] % " -@end group -@group -"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ -address.txt backup.psf kolstad.psf -backup.bib~ david.mss resume-Dec-86.mss~ -backup.err david.psf resume-Dec.psf -backup.mss dland syllabus.mss -" -"#backups.mss# backup.mss~ kolstad.mss -") -@end group -@end smallexample - -@ignore @c The code in this example doesn't show the right way to do things. -Here is another, more realistic example, which demonstrates how to use -the process mark to do insertion in the same fashion as is done when -there is no filter function: - -@smallexample -@group -;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} -;; @r{and make sure that buffer is shown in some window.} -(defun my-process-filter (proc str) - (let ((cur (selected-window)) - (pop-up-windows t)) - (pop-to-buffer my-shell-buffer) -@end group -@group - (goto-char (point-max)) - (insert str) - (set-marker (process-mark proc) (point-max)) - (select-window cur))) -@end group -@end smallexample -@end ignore - -@node Decoding Output -@subsection Decoding Process Output -@cindex decode process output - - When Emacs writes process output directly into a multibyte buffer, -it decodes the output according to the process output coding system. -If the coding system is @code{raw-text} or @code{no-conversion}, Emacs -converts the unibyte output to multibyte using -@code{string-to-multibyte}, and inserts the resulting multibyte text. - - You can use @code{set-process-coding-system} to specify which coding -system to use (@pxref{Process Information}). Otherwise, the coding -system comes from @code{coding-system-for-read}, if that is -non-@code{nil}; or else from the defaulting mechanism (@pxref{Default -Coding Systems}). - - @strong{Warning:} Coding systems such as @code{undecided} which -determine the coding system from the data do not work entirely -reliably with asynchronous subprocess output. This is because Emacs -has to process asynchronous subprocess output in batches, as it -arrives. Emacs must try to detect the proper coding system from one -batch at a time, and this does not always work. Therefore, if at all -possible, specify a coding system that determines both the character -code conversion and the end of line conversion---that is, one like -@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}. - -@cindex filter multibyte flag, of process -@cindex process filter multibyte flag - When Emacs calls a process filter function, it provides the process -output as a multibyte string or as a unibyte string according to the -process's filter multibyte flag. If the flag is non-@code{nil}, Emacs -decodes the output according to the process output coding system to -produce a multibyte string, and passes that to the process. If the -flag is @code{nil}, Emacs puts the output into a unibyte string, with -no decoding, and passes that. - - When you create a process, the filter multibyte flag takes its -initial value from @code{default-enable-multibyte-characters}. If you -want to change the flag later on, use -@code{set-process-filter-multibyte}. - -@defun set-process-filter-multibyte process multibyte -This function sets the filter multibyte flag of @var{process} -to @var{multibyte}. -@end defun - -@defun process-filter-multibyte-p process -This function returns the filter multibyte flag of @var{process}. -@end defun - -@node Accepting Output -@subsection Accepting Output from Processes -@cindex accept input from processes - - Output from asynchronous subprocesses normally arrives only while -Emacs is waiting for some sort of external event, such as elapsed time -or terminal input. Occasionally it is useful in a Lisp program to -explicitly permit output to arrive at a specific point, or even to wait -until output arrives from a process. - -@defun accept-process-output &optional process seconds millisec just-this-one -This function allows Emacs to read pending output from processes. The -output is inserted in the associated buffers or given to their filter -functions. If @var{process} is non-@code{nil} then this function does -not return until some output has been received from @var{process}. - -@c Emacs 19 feature -The arguments @var{seconds} and @var{millisec} let you specify timeout -periods. The former specifies a period measured in seconds and the -latter specifies one measured in milliseconds. The two time periods -thus specified are added together, and @code{accept-process-output} -returns after that much time, whether or not there has been any -subprocess output. - -The argument @var{millisec} is semi-obsolete nowadays because -@var{seconds} can be a floating point number to specify waiting a -fractional number of seconds. If @var{seconds} is 0, the function -accepts whatever output is pending but does not wait. - -@c Emacs 22.1 feature -If @var{process} is a process, and the argument @var{just-this-one} is -non-@code{nil}, only output from that process is handled, suspending output -from other processes until some output has been received from that -process or the timeout expires. If @var{just-this-one} is an integer, -also inhibit running timers. This feature is generally not -recommended, but may be necessary for specific applications, such as -speech synthesis. - -The function @code{accept-process-output} returns non-@code{nil} if it -did get some output, or @code{nil} if the timeout expired before output -arrived. -@end defun - -@node Sentinels -@section Sentinels: Detecting Process Status Changes -@cindex process sentinel -@cindex sentinel (of process) - - A @dfn{process sentinel} is a function that is called whenever the -associated process changes status for any reason, including signals -(whether sent by Emacs or caused by the process's own actions) that -terminate, stop, or continue the process. The process sentinel is -also called if the process exits. The sentinel receives two -arguments: the process for which the event occurred, and a string -describing the type of event. - - The string describing the event looks like one of the following: - -@itemize @bullet -@item -@code{"finished\n"}. - -@item -@code{"exited abnormally with code @var{exitcode}\n"}. - -@item -@code{"@var{name-of-signal}\n"}. - -@item -@code{"@var{name-of-signal} (core dumped)\n"}. -@end itemize - - A sentinel runs only while Emacs is waiting (e.g., for terminal -input, or for time to elapse, or for process output). This avoids the -timing errors that could result from running them at random places in -the middle of other Lisp programs. A program can wait, so that -sentinels will run, by calling @code{sit-for} or @code{sleep-for} -(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting -Output}). Emacs also allows sentinels to run when the command loop is -reading input. @code{delete-process} calls the sentinel when it -terminates a running process. - - Emacs does not keep a queue of multiple reasons to call the sentinel -of one process; it records just the current status and the fact that -there has been a change. Therefore two changes in status, coming in -quick succession, can call the sentinel just once. However, process -termination will always run the sentinel exactly once. This is -because the process status can't change again after termination. - - Emacs explicitly checks for output from the process before running -the process sentinel. Once the sentinel runs due to process -termination, no further output can arrive from the process. - - A sentinel that writes the output into the buffer of the process -should check whether the buffer is still alive. If it tries to insert -into a dead buffer, it will get an error. If the buffer is dead, -@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. - - Quitting is normally inhibited within a sentinel---otherwise, the -effect of typing @kbd{C-g} at command level or to quit a user command -would be unpredictable. If you want to permit quitting inside a -sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the -right way to do this is with the macro @code{with-local-quit}. -@xref{Quitting}. - - If an error happens during execution of a sentinel, it is caught -automatically, so that it doesn't stop the execution of whatever -programs was running when the sentinel was started. However, if -@code{debug-on-error} is non-@code{nil}, the error-catching is turned -off. This makes it possible to use the Lisp debugger to debug the -sentinel. @xref{Debugger}. - - While a sentinel is running, the process sentinel is temporarily -set to @code{nil} so that the sentinel won't run recursively. -For this reason it is not possible for a sentinel to specify -a new sentinel. - - In earlier Emacs versions, every sentinel that did regular expression -searching or matching had to explicitly save and restore the match data. -Now Emacs does this automatically for sentinels; they never need to do -it explicitly. @xref{Match Data}. - -@defun set-process-sentinel process sentinel -This function associates @var{sentinel} with @var{process}. If -@var{sentinel} is @code{nil}, then the process will have no sentinel. -The default behavior when there is no sentinel is to insert a message in -the process's buffer when the process status changes. - -Changes in process sentinel take effect immediately---if the sentinel -is slated to be run but has not been called yet, and you specify a new -sentinel, the eventual call to the sentinel will use the new one. - -@smallexample -@group -(defun msg-me (process event) - (princ - (format "Process: %s had the event `%s'" process event))) -(set-process-sentinel (get-process "shell") 'msg-me) - @result{} msg-me -@end group -@group -(kill-process (get-process "shell")) - @print{} Process: #<process shell> had the event `killed' - @result{} #<process shell> -@end group -@end smallexample -@end defun - -@defun process-sentinel process -This function returns the sentinel of @var{process}, or @code{nil} if it -has none. -@end defun - -@defun waiting-for-user-input-p -While a sentinel or filter function is running, this function returns -non-@code{nil} if Emacs was waiting for keyboard input from the user at -the time the sentinel or filter function was called, @code{nil} if it -was not. -@end defun - -@node Query Before Exit -@section Querying Before Exit - - When Emacs exits, it terminates all its subprocesses by sending them -the @code{SIGHUP} signal. Because subprocesses may be doing -valuable work, Emacs normally asks the user to confirm that it is ok -to terminate them. Each process has a query flag which, if -non-@code{nil}, says that Emacs should ask for confirmation before -exiting and thus killing that process. The default for the query flag -is @code{t}, meaning @emph{do} query. - -@defun process-query-on-exit-flag process -This returns the query flag of @var{process}. -@end defun - -@defun set-process-query-on-exit-flag process flag -This function sets the query flag of @var{process} to @var{flag}. It -returns @var{flag}. - -@smallexample -@group -;; @r{Don't query about the shell process} -(set-process-query-on-exit-flag (get-process "shell") nil) - @result{} t -@end group -@end smallexample -@end defun - -@defun process-kill-without-query process &optional do-query -This function clears the query flag of @var{process}, so that -Emacs will not query the user on account of that process. - -Actually, the function does more than that: it returns the old value of -the process's query flag, and sets the query flag to @var{do-query}. -Please don't use this function to do those things any more---please -use the newer, cleaner functions @code{process-query-on-exit-flag} and -@code{set-process-query-on-exit-flag} in all but the simplest cases. -The only way you should use @code{process-kill-without-query} nowadays -is like this: - -@smallexample -@group -;; @r{Don't query about the shell process} -(process-kill-without-query (get-process "shell")) -@end group -@end smallexample -@end defun - -@node Transaction Queues -@section Transaction Queues -@cindex transaction queue - -You can use a @dfn{transaction queue} to communicate with a subprocess -using transactions. First use @code{tq-create} to create a transaction -queue communicating with a specified process. Then you can call -@code{tq-enqueue} to send a transaction. - -@defun tq-create process -This function creates and returns a transaction queue communicating with -@var{process}. The argument @var{process} should be a subprocess -capable of sending and receiving streams of bytes. It may be a child -process, or it may be a TCP connection to a server, possibly on another -machine. -@end defun - -@defun tq-enqueue queue question regexp closure fn &optional delay-question -This function sends a transaction to queue @var{queue}. Specifying the -queue has the effect of specifying the subprocess to talk to. - -The argument @var{question} is the outgoing message that starts the -transaction. The argument @var{fn} is the function to call when the -corresponding answer comes back; it is called with two arguments: -@var{closure}, and the answer received. - -The argument @var{regexp} is a regular expression that should match -text at the end of the entire answer, but nothing before; that's how -@code{tq-enqueue} determines where the answer ends. - -If the argument @var{delay-question} is non-nil, delay sending this -question until the process has finished replying to any previous -questions. This produces more reliable results with some processes. - -The return value of @code{tq-enqueue} itself is not meaningful. -@end defun - -@defun tq-close queue -Shut down transaction queue @var{queue}, waiting for all pending transactions -to complete, and then terminate the connection or child process. -@end defun - -Transaction queues are implemented by means of a filter function. -@xref{Filter Functions}. - -@node Network -@section Network Connections -@cindex network connection -@cindex TCP -@cindex UDP - - Emacs Lisp programs can open stream (TCP) and datagram (UDP) network -connections to other processes on the same machine or other machines. -A network connection is handled by Lisp much like a subprocess, and is -represented by a process object. However, the process you are -communicating with is not a child of the Emacs process, so it has no -process @acronym{ID}, and you can't kill it or send it signals. All you -can do is send and receive data. @code{delete-process} closes the -connection, but does not kill the program at the other end; that -program must decide what to do about closure of the connection. - - Lisp programs can listen for connections by creating network -servers. A network server is also represented by a kind of process -object, but unlike a network connection, the network server never -transfers data itself. When it receives a connection request, it -creates a new network connection to represent the connection just -made. (The network connection inherits certain information, including -the process plist, from the server.) The network server then goes -back to listening for more connection requests. - - Network connections and servers are created by calling -@code{make-network-process} with an argument list consisting of -keyword/argument pairs, for example @code{:server t} to create a -server process, or @code{:type 'datagram} to create a datagram -connection. @xref{Low-Level Network}, for details. You can also use -the @code{open-network-stream} function described below. - - You can distinguish process objects representing network connections -and servers from those representing subprocesses with the -@code{process-status} function. The possible status values for -network connections are @code{open}, @code{closed}, @code{connect}, -and @code{failed}. For a network server, the status is always -@code{listen}. None of those values is possible for a real -subprocess. @xref{Process Information}. - - You can stop and resume operation of a network process by calling -@code{stop-process} and @code{continue-process}. For a server -process, being stopped means not accepting new connections. (Up to 5 -connection requests will be queued for when you resume the server; you -can increase this limit, unless it is imposed by the operating -system.) For a network stream connection, being stopped means not -processing input (any arriving input waits until you resume the -connection). For a datagram connection, some number of packets may be -queued but input may be lost. You can use the function -@code{process-command} to determine whether a network connection or -server is stopped; a non-@code{nil} value means yes. - -@defun open-network-stream name buffer-or-name host service -This function opens a TCP connection, and returns a process object -that represents the connection. - -The @var{name} argument specifies the name for the process object. It -is modified as necessary to make it unique. - -The @var{buffer-or-name} argument is the buffer to associate with the -connection. Output from the connection is inserted in the buffer, -unless you specify a filter function to handle the output. If -@var{buffer-or-name} is @code{nil}, it means that the connection is not -associated with any buffer. - -The arguments @var{host} and @var{service} specify where to connect to; -@var{host} is the host name (a string), and @var{service} is the name of -a defined network service (a string) or a port number (an integer). -@end defun - -@defun process-contact process &optional key -This function returns information about how a network process was set -up. For a connection, when @var{key} is @code{nil}, it returns -@code{(@var{hostname} @var{service})} which specifies what you -connected to. - -If @var{key} is @code{t}, the value is the complete status information -for the connection or server; that is, the list of keywords and values -specified in @code{make-network-process}, except that some of the -values represent the current status instead of what you specified: - -@table @code -@item :buffer -The associated value is the process buffer. -@item :filter -The associated value is the process filter function. -@item :sentinel -The associated value is the process sentinel function. -@item :remote -In a connection, the address in internal format of the remote peer. -@item :local -The local address, in internal format. -@item :service -In a server, if you specified @code{t} for @var{service}, -this value is the actual port number. -@end table - -@code{:local} and @code{:remote} are included even if they were not -specified explicitly in @code{make-network-process}. - -If @var{key} is a keyword, the function returns the value corresponding -to that keyword. - -For an ordinary child process, this function always returns @code{t}. -@end defun - -@node Network Servers -@section Network Servers -@cindex network servers - - You create a server by calling @code{make-network-process} with -@code{:server t}. The server will listen for connection requests from -clients. When it accepts a client connection request, that creates a -new network connection, itself a process object, with the following -parameters: - -@itemize @bullet -@item -The connection's process name is constructed by concatenating the -server process' @var{name} with a client identification string. The -client identification string for an IPv4 connection looks like -@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a -unique number in brackets, as in @samp{<@var{nnn}>}. The number -is unique for each connection in the Emacs session. - -@item -If the server's filter is non-@code{nil}, the connection process does -not get a separate process buffer; otherwise, Emacs creates a new -buffer for the purpose. The buffer name is the server's buffer name -or process name, concatenated with the client identification string. - -The server's process buffer value is never used directly by Emacs, but -it is passed to the log function, which can log connections by -inserting text there. - -@item -The communication type and the process filter and sentinel are -inherited from those of the server. The server never directly -uses its filter and sentinel; their sole purpose is to initialize -connections made to the server. - -@item -The connection's process contact info is set according to the client's -addressing information (typically an IP address and a port number). -This information is associated with the @code{process-contact} -keywords @code{:host}, @code{:service}, @code{:remote}. - -@item -The connection's local address is set up according to the port -number used for the connection. - -@item -The client process' plist is initialized from the server's plist. -@end itemize - -@node Datagrams -@section Datagrams -@cindex datagrams - - A datagram connection communicates with individual packets rather -than streams of data. Each call to @code{process-send} sends one -datagram packet (@pxref{Input to Processes}), and each datagram -received results in one call to the filter function. - - The datagram connection doesn't have to talk with the same remote -peer all the time. It has a @dfn{remote peer address} which specifies -where to send datagrams to. Each time an incoming datagram is passed -to the filter function, the peer address is set to the address that -datagram came from; that way, if the filter function sends a datagram, -it will go back to that place. You can specify the remote peer -address when you create the datagram connection using the -@code{:remote} keyword. You can change it later on by calling -@code{set-process-datagram-address}. - -@defun process-datagram-address process -If @var{process} is a datagram connection or server, this function -returns its remote peer address. -@end defun - -@defun set-process-datagram-address process address -If @var{process} is a datagram connection or server, this function -sets its remote peer address to @var{address}. -@end defun - -@node Low-Level Network -@section Low-Level Network Access - - You can also create network connections by operating at a lower -level than that of @code{open-network-stream}, using -@code{make-network-process}. - -@menu -* Proc: Network Processes. Using @code{make-network-process}. -* Options: Network Options. Further control over network connections. -* Features: Network Feature Testing. - Determining which network features work on - the machine you are using. -@end menu - -@node Network Processes -@subsection @code{make-network-process} - - The basic function for creating network connections and network -servers is @code{make-network-process}. It can do either of those -jobs, depending on the arguments you give it. - -@defun make-network-process &rest args -This function creates a network connection or server and returns the -process object that represents it. The arguments @var{args} are a -list of keyword/argument pairs. Omitting a keyword is always -equivalent to specifying it with value @code{nil}, except for -@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here -are the meaningful keywords: - -@table @asis -@item :name @var{name} -Use the string @var{name} as the process name. It is modified if -necessary to make it unique. - -@item :type @var{type} -Specify the communication type. A value of @code{nil} specifies a -stream connection (the default); @code{datagram} specifies a datagram -connection. Both connections and servers can be of either type. - -@item :server @var{server-flag} -If @var{server-flag} is non-@code{nil}, create a server. Otherwise, -create a connection. For a stream type server, @var{server-flag} may -be an integer which then specifies the length of the queue of pending -connections to the server. The default queue length is 5. - -@item :host @var{host} -Specify the host to connect to. @var{host} should be a host name or -Internet address, as a string, or the symbol @code{local} to specify -the local host. If you specify @var{host} for a server, it must -specify a valid address for the local host, and only clients -connecting to that address will be accepted. - -@item :service @var{service} -@var{service} specifies a port number to connect to, or, for a server, -the port number to listen on. It should be a service name that -translates to a port number, or an integer specifying the port number -directly. For a server, it can also be @code{t}, which means to let -the system select an unused port number. - -@item :family @var{family} -@var{family} specifies the address (and protocol) family for -communication. @code{nil} means determine the proper address family -automatically for the given @var{host} and @var{service}. -@code{local} specifies a Unix socket, in which case @var{host} is -ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6 -respectively. - -@item :local @var{local-address} -For a server process, @var{local-address} is the address to listen on. -It overrides @var{family}, @var{host} and @var{service}, and you -may as well not specify them. - -@item :remote @var{remote-address} -For a connection, @var{remote-address} is the address to connect to. -It overrides @var{family}, @var{host} and @var{service}, and you -may as well not specify them. - -For a datagram server, @var{remote-address} specifies the initial -setting of the remote datagram address. - -The format of @var{local-address} or @var{remote-address} depends on -the address family: - -@itemize - -@item -An IPv4 address is represented as a five-element vector of four 8-bit -integers and one 16-bit integer -@code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to -numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number -@var{p}. - -@item -An IPv6 address is represented as a nine-element vector of 16-bit -integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f} -@var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address -@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and -port number @var{p}. - -@item -A local address is represented as a string which specifies the address -in the local address space. - -@item -An ``unsupported family'' address is represented by a cons -@code{(@var{f} . @var{av})}, where @var{f} is the family number and -@var{av} is a vector specifying the socket address using one element -per address data byte. Do not rely on this format in portable code, -as it may depend on implementation defined constants, data sizes, and -data structure alignment. -@end itemize - -@item :nowait @var{bool} -If @var{bool} is non-@code{nil} for a stream connection, return -without waiting for the connection to complete. When the connection -succeeds or fails, Emacs will call the sentinel function, with a -second argument matching @code{"open"} (if successful) or -@code{"failed"}. The default is to block, so that -@code{make-network-process} does not return until the connection -has succeeded or failed. - -@item :stop @var{stopped} -Start the network connection or server in the `stopped' state if -@var{stopped} is non-@code{nil}. - -@item :buffer @var{buffer} -Use @var{buffer} as the process buffer. - -@item :coding @var{coding} -Use @var{coding} as the coding system for this process. To specify -different coding systems for decoding data from the connection and for -encoding data sent to it, specify @code{(@var{decoding} . -@var{encoding})} for @var{coding}. - -If you don't specify this keyword at all, the default -is to determine the coding systems from the data. - -@item :noquery @var{query-flag} -Initialize the process query flag to @var{query-flag}. -@xref{Query Before Exit}. - -@item :filter @var{filter} -Initialize the process filter to @var{filter}. - -@item :filter-multibyte @var{bool} -If @var{bool} is non-@code{nil}, strings given to the process filter -are multibyte, otherwise they are unibyte. If you don't specify this -keyword at all, the default is that the strings are multibyte if -@code{default-enable-multibyte-characters} is non-@code{nil}. - -@item :sentinel @var{sentinel} -Initialize the process sentinel to @var{sentinel}. - -@item :log @var{log} -Initialize the log function of a server process to @var{log}. The log -function is called each time the server accepts a network connection -from a client. The arguments passed to the log function are -@var{server}, @var{connection}, and @var{message}, where @var{server} -is the server process, @var{connection} is the new process for the -connection, and @var{message} is a string describing what has -happened. - -@item :plist @var{plist} -Initialize the process plist to @var{plist}. -@end table - -The original argument list, modified with the actual connection -information, is available via the @code{process-contact} function. -@end defun - -@node Network Options -@subsection Network Options - - The following network options can be specified when you create a -network process. Except for @code{:reuseaddr}, you can also set or -modify these options later, using @code{set-network-process-option}. - - For a server process, the options specified with -@code{make-network-process} are not inherited by the client -connections, so you will need to set the necessary options for each -child connection as it is created. - -@table @asis -@item :bindtodevice @var{device-name} -If @var{device-name} is a non-empty string identifying a network -interface name (see @code{network-interface-list}), only handle -packets received on that interface. If @var{device-name} is @code{nil} -(the default), handle packets received on any interface. - -Using this option may require special privileges on some systems. - -@item :broadcast @var{broadcast-flag} -If @var{broadcast-flag} is non-@code{nil} for a datagram process, the -process will receive datagram packet sent to a broadcast address, and -be able to send packets to a broadcast address. Ignored for a stream -connection. - -@item :dontroute @var{dontroute-flag} -If @var{dontroute-flag} is non-@code{nil}, the process can only send -to hosts on the same network as the local host. - -@item :keepalive @var{keepalive-flag} -If @var{keepalive-flag} is non-@code{nil} for a stream connection, -enable exchange of low-level keep-alive messages. - -@item :linger @var{linger-arg} -If @var{linger-arg} is non-@code{nil}, wait for successful -transmission of all queued packets on the connection before it is -deleted (see @code{delete-process}). If @var{linger-arg} is an -integer, it specifies the maximum time in seconds to wait for queued -packets to be sent before closing the connection. Default is -@code{nil} which means to discard unsent queued packets when the -process is deleted. - -@item :oobinline @var{oobinline-flag} -If @var{oobinline-flag} is non-@code{nil} for a stream connection, -receive out-of-band data in the normal data stream. Otherwise, ignore -out-of-band data. - -@item :priority @var{priority} -Set the priority for packets sent on this connection to the integer -@var{priority}. The interpretation of this number is protocol -specific, such as setting the TOS (type of service) field on IP -packets sent on this connection. It may also have system dependent -effects, such as selecting a specific output queue on the network -interface. - -@item :reuseaddr @var{reuseaddr-flag} -If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream -server process, allow this server to reuse a specific port number (see -@code{:service}) unless another process on this host is already -listening on that port. If @var{reuseaddr-flag} is @code{nil}, there -may be a period of time after the last use of that port (by any -process on the host), where it is not possible to make a new server on -that port. -@end table - -@defun set-network-process-option process option value -This function sets or modifies a network option for network process -@var{process}. See @code{make-network-process} for details of options -@var{option} and their corresponding values @var{value}. - -The current setting of an option is available via the -@code{process-contact} function. -@end defun - -@node Network Feature Testing -@subsection Testing Availability of Network Features - - To test for the availability of a given network feature, use -@code{featurep} like this: - -@example -(featurep 'make-network-process '(@var{keyword} @var{value})) -@end example - -@noindent -The result of the first form is @code{t} if it works to specify -@var{keyword} with value @var{value} in @code{make-network-process}. -The result of the second form is @code{t} if @var{keyword} is -supported by @code{make-network-process}. Here are some of the -@var{keyword}---@var{value} pairs you can test in -this way. - -@table @code -@item (:nowait t) -Non-@code{nil} if non-blocking connect is supported. -@item (:type datagram) -Non-@code{nil} if datagrams are supported. -@item (:family local) -Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported. -@item (:family ipv6) -Non-@code{nil} if IPv6 is supported. -@item (:service t) -Non-@code{nil} if the system can select the port for a server. -@end table - - To test for the availability of a given network option, use -@code{featurep} like this: - -@example -(featurep 'make-network-process '@var{keyword}) -@end example - -@noindent -Here are some of the options you can test in this way. - -@table @code -@item :bindtodevice -@itemx :broadcast -@itemx :dontroute -@itemx :keepalive -@itemx :linger -@itemx :oobinline -@itemx :priority -@itemx :reuseaddr -That particular network option is supported by -@code{make-network-process} and @code{set-network-process-option}. -@end table - -@node Misc Network -@section Misc Network Facilities - - These additional functions are useful for creating and operating -on network connections. - -@defun network-interface-list -This function returns a list describing the network interfaces -of the machine you are using. The value is an alist whose -elements have the form @code{(@var{name} . @var{address})}. -@var{address} has the same form as the @var{local-address} -and @var{remote-address} arguments to @code{make-network-process}. -@end defun - -@defun network-interface-info ifname -This function returns information about the network interface named -@var{ifname}. The value is a list of the form -@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}. - -@table @var -@item addr -The Internet protocol address. -@item bcast -The broadcast address. -@item netmask -The network mask. -@item hwaddr -The layer 2 address (Ethernet MAC address, for instance). -@item flags -The current flags of the interface. -@end table -@end defun - -@defun format-network-address address &optional omit-port -This function converts the Lisp representation of a network address to -a string. - -A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} -represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port -number @var{p}. @code{format-network-address} converts that to the -string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}. - -A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e} -@var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along -with a port number. @code{format-network-address} converts that to -the string -@code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}. - -If the vector does not include the port number, @var{p}, or if -@var{omit-port} is non-@code{nil}, the result does not include the -@code{:@var{p}} suffix. -@end defun - -@node Byte Packing -@section Packing and Unpacking Byte Arrays -@cindex byte packing and unpacking - - This section describes how to pack and unpack arrays of bytes, -usually for binary network protocols. These functions convert byte arrays -to alists, and vice versa. The byte array can be represented as a -unibyte string or as a vector of integers, while the alist associates -symbols either with fixed-size objects or with recursive sub-alists. - -@cindex serializing -@cindex deserializing -@cindex packing -@cindex unpacking - Conversion from byte arrays to nested alists is also known as -@dfn{deserializing} or @dfn{unpacking}, while going in the opposite -direction is also known as @dfn{serializing} or @dfn{packing}. - -@menu -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! -@end menu - -@node Bindat Spec -@subsection Describing Data Layout - - To control unpacking and packing, you write a @dfn{data layout -specification}, a special nested list describing named and typed -@dfn{fields}. This specification controls length of each field to be -processed, and how to pack or unpack it. We normally keep bindat specs -in variables whose names end in @samp{-bindat-spec}; that kind of name -is automatically recognized as ``risky.'' - -@cindex endianness -@cindex big endian -@cindex little endian -@cindex network byte ordering - A field's @dfn{type} describes the size (in bytes) of the object -that the field represents and, in the case of multibyte fields, how -the bytes are ordered within the field. The two possible orderings -are ``big endian'' (also known as ``network byte ordering'') and -``little endian.'' For instance, the number @code{#x23cd} (decimal -9165) in big endian would be the two bytes @code{#x23} @code{#xcd}; -and in little endian, @code{#xcd} @code{#x23}. Here are the possible -type values: - -@table @code -@item u8 -@itemx byte -Unsigned byte, with length 1. - -@item u16 -@itemx word -@itemx short -Unsigned integer in network byte order, with length 2. - -@item u24 -Unsigned integer in network byte order, with length 3. - -@item u32 -@itemx dword -@itemx long -Unsigned integer in network byte order, with length 4. -Note: These values may be limited by Emacs' integer implementation limits. - -@item u16r -@itemx u24r -@itemx u32r -Unsigned integer in little endian order, with length 2, 3 and 4, respectively. - -@item str @var{len} -String of length @var{len}. - -@item strz @var{len} -Zero-terminated string, in a fixed-size field with length @var{len}. - -@item vec @var{len} [@var{type}] -Vector of @var{len} elements of type @var{type}, or bytes if not -@var{type} is specified. -The @var{type} is any of the simple types above, or another vector -specified as a list @code{(vec @var{len} [@var{type}])}. - -@item ip -Four-byte vector representing an Internet address. For example: -@code{[127 0 0 1]} for localhost. - -@item bits @var{len} -List of set bits in @var{len} bytes. The bytes are taken in big -endian order and the bits are numbered starting with @code{8 * -@var{len} @minus{} 1} and ending with zero. For example: @code{bits -2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and -@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}. - -@item (eval @var{form}) -@var{form} is a Lisp expression evaluated at the moment the field is -unpacked or packed. The result of the evaluation should be one of the -above-listed type specifications. -@end table - -For a fixed-size field, the length @var{len} is given as an integer -specifying the number of bytes in the field. - -When the length of a field is not fixed, it typically depends on the -value of a preceding field. In this case, the length @var{len} can be -given either as a list @code{(@var{name} ...)} identifying a -@dfn{field name} in the format specified for @code{bindat-get-field} -below, or by an expression @code{(eval @var{form})} where @var{form} -should evaluate to an integer, specifying the field length. - -A field specification generally has the form @code{([@var{name}] -@var{handler})}. The square braces indicate that @var{name} is -optional. (Don't use names that are symbols meaningful as type -specifications (above) or handler specifications (below), since that -would be ambiguous.) @var{name} can be a symbol or the expression -@code{(eval @var{form})}, in which case @var{form} should evaluate to -a symbol. - -@var{handler} describes how to unpack or pack the field and can be one -of the following: - -@table @code -@item @var{type} -Unpack/pack this field according to the type specification @var{type}. - -@item eval @var{form} -Evaluate @var{form}, a Lisp expression, for side-effect only. If the -field name is specified, the value is bound to that field name. - -@item fill @var{len} -Skip @var{len} bytes. In packing, this leaves them unchanged, -which normally means they remain zero. In unpacking, this means -they are ignored. - -@item align @var{len} -Skip to the next multiple of @var{len} bytes. - -@item struct @var{spec-name} -Process @var{spec-name} as a sub-specification. This describes a -structure nested within another structure. - -@item union @var{form} (@var{tag} @var{spec})@dots{} -@c ??? I don't see how one would actually use this. -@c ??? what kind of expression would be useful for @var{form}? -Evaluate @var{form}, a Lisp expression, find the first @var{tag} -that matches it, and process its associated data layout specification -@var{spec}. Matching can occur in one of three ways: - -@itemize -@item -If a @var{tag} has the form @code{(eval @var{expr})}, evaluate -@var{expr} with the variable @code{tag} dynamically bound to the value -of @var{form}. A non-@code{nil} result indicates a match. - -@item -@var{tag} matches if it is @code{equal} to the value of @var{form}. - -@item -@var{tag} matches unconditionally if it is @code{t}. -@end itemize - -@item repeat @var{count} @var{field-specs}@dots{} -Process the @var{field-specs} recursively, in order, then repeat -starting from the first one, processing all the specs @var{count} -times overall. The @var{count} is given using the same formats as a -field length---if an @code{eval} form is used, it is evaluated just once. -For correct operation, each spec in @var{field-specs} must include a name. -@end table - -For the @code{(eval @var{form})} forms used in a bindat specification, -the @var{form} can access and update these dynamically bound variables -during evaluation: - -@table @code -@item last -Value of the last field processed. - -@item bindat-raw -The data as a byte array. - -@item bindat-idx -Current index (within @code{bindat-raw}) for unpacking or packing. - -@item struct -The alist containing the structured data that have been unpacked so -far, or the entire structure being packed. You can use -@code{bindat-get-field} to access specific fields of this structure. - -@item count -@itemx index -Inside a @code{repeat} block, these contain the maximum number of -repetitions (as specified by the @var{count} parameter), and the -current repetition number (counting from 0). Setting @code{count} to -zero will terminate the inner-most repeat block after the current -repetition has completed. -@end table - -@node Bindat Functions -@subsection Functions to Unpack and Pack Bytes - - In the following documentation, @var{spec} refers to a data layout -specification, @code{bindat-raw} to a byte array, and @var{struct} to an -alist representing unpacked field data. - -@defun bindat-unpack spec bindat-raw &optional bindat-idx -This function unpacks data from the unibyte string or byte -array @code{bindat-raw} -according to @var{spec}. Normally this starts unpacking at the -beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it -specifies a zero-based starting position to use instead. - -The value is an alist or nested alist in which each element describes -one unpacked field. -@end defun - -@defun bindat-get-field struct &rest name -This function selects a field's data from the nested alist -@var{struct}. Usually @var{struct} was returned by -@code{bindat-unpack}. If @var{name} corresponds to just one argument, -that means to extract a top-level field value. Multiple @var{name} -arguments specify repeated lookup of sub-structures. An integer name -acts as an array index. - -For example, if @var{name} is @code{(a b 2 c)}, that means to find -field @code{c} in the third element of subfield @code{b} of field -@code{a}. (This corresponds to @code{struct.a.b[2].c} in C.) -@end defun - - Although packing and unpacking operations change the organization of -data (in memory), they preserve the data's @dfn{total length}, which is -the sum of all the fields' lengths, in bytes. This value is not -generally inherent in either the specification or alist alone; instead, -both pieces of information contribute to its calculation. Likewise, the -length of a string or array being unpacked may be longer than the data's -total length as described by the specification. - -@defun bindat-length spec struct -This function returns the total length of the data in @var{struct}, -according to @var{spec}. -@end defun - -@defun bindat-pack spec struct &optional bindat-raw bindat-idx -This function returns a byte array packed according to @var{spec} from -the data in the alist @var{struct}. Normally it creates and fills a -new byte array starting at the beginning. However, if @var{bindat-raw} -is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to -pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting -offset for packing into @code{bindat-raw}. - -When pre-allocating, you should make sure @code{(length @var{bindat-raw})} -meets or exceeds the total length to avoid an out-of-range error. -@end defun - -@defun bindat-ip-to-string ip -Convert the Internet address vector @var{ip} to a string in the usual -dotted notation. - -@example -(bindat-ip-to-string [127 0 0 1]) - @result{} "127.0.0.1" -@end example -@end defun - -@node Bindat Examples -@subsection Examples of Byte Unpacking and Packing - - Here is a complete example of byte unpacking and packing: - -@lisp -(defvar fcookie-index-spec - '((:version u32) - (:count u32) - (:longest u32) - (:shortest u32) - (:flags u32) - (:delim u8) - (:ignored fill 3) - (:offset repeat (:count) - (:foo u32))) - "Description of a fortune cookie index file's contents.") - -(defun fcookie (cookies &optional index) - "Display a random fortune cookie from file COOKIES. -Optional second arg INDEX specifies the associated index -filename, which is by default constructed by appending -\".dat\" to COOKIES. Display cookie text in possibly -new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME -is COOKIES without the directory part." - (interactive "fCookies file: ") - (let* ((info (with-temp-buffer - (insert-file-contents-literally - (or index (concat cookies ".dat"))) - (bindat-unpack fcookie-index-spec - (buffer-string)))) - (sel (random (bindat-get-field info :count))) - (beg (cdar (bindat-get-field info :offset sel))) - (end (or (cdar (bindat-get-field info - :offset (1+ sel))) - (nth 7 (file-attributes cookies))))) - (switch-to-buffer - (get-buffer-create - (format "*Fortune Cookie: %s*" - (file-name-nondirectory cookies)))) - (erase-buffer) - (insert-file-contents-literally - cookies nil beg (- end 3)))) - -(defun fcookie-create-index (cookies &optional index delim) - "Scan file COOKIES, and write out its index file. -Optional second arg INDEX specifies the index filename, -which is by default constructed by appending \".dat\" to -COOKIES. Optional third arg DELIM specifies the unibyte -character which, when found on a line of its own in -COOKIES, indicates the border between entries." - (interactive "fCookies file: ") - (setq delim (or delim ?%)) - (let ((delim-line (format "\n%c\n" delim)) - (count 0) - (max 0) - min p q len offsets) - (unless (= 3 (string-bytes delim-line)) - (error "Delimiter cannot be represented in one byte")) - (with-temp-buffer - (insert-file-contents-literally cookies) - (while (and (setq p (point)) - (search-forward delim-line (point-max) t) - (setq len (- (point) 3 p))) - (setq count (1+ count) - max (max max len) - min (min (or min max) len) - offsets (cons (1- p) offsets)))) - (with-temp-buffer - (set-buffer-multibyte nil) - (insert - (bindat-pack - fcookie-index-spec - `((:version . 2) - (:count . ,count) - (:longest . ,max) - (:shortest . ,min) - (:flags . 0) - (:delim . ,delim) - (:offset . ,(mapcar (lambda (o) - (list (cons :foo o))) - (nreverse offsets)))))) - (let ((coding-system-for-write 'raw-text-unix)) - (write-file (or index (concat cookies ".dat"))))))) -@end lisp - -Following is an example of defining and unpacking a complex structure. -Consider the following C structures: - -@example -struct header @{ - unsigned long dest_ip; - unsigned long src_ip; - unsigned short dest_port; - unsigned short src_port; -@}; - -struct data @{ - unsigned char type; - unsigned char opcode; - unsigned short length; /* In network byte order */ - unsigned char id[8]; /* null-terminated string */ - unsigned char data[/* (length + 3) & ~3 */]; -@}; - -struct packet @{ - struct header header; - unsigned long counters[2]; /* In little endian order */ - unsigned char items; - unsigned char filler[3]; - struct data item[/* items */]; - -@}; -@end example - -The corresponding data layout specification: - -@lisp -(setq header-spec - '((dest-ip ip) - (src-ip ip) - (dest-port u16) - (src-port u16))) - -(setq data-spec - '((type u8) - (opcode u8) - (length u16) ;; network byte order - (id strz 8) - (data vec (length)) - (align 4))) - -(setq packet-spec - '((header struct header-spec) - (counters vec 2 u32r) ;; little endian order - (items u8) - (fill 3) - (item repeat (items) - (struct data-spec)))) -@end lisp - -A binary data representation: - -@lisp -(setq binary-data - [ 192 168 1 100 192 168 1 101 01 28 21 32 - 160 134 1 0 5 1 0 0 2 0 0 0 - 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 - 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) -@end lisp - -The corresponding decoded structure: - -@lisp -(setq decoded (bindat-unpack packet-spec binary-data)) - @result{} -((header - (dest-ip . [192 168 1 100]) - (src-ip . [192 168 1 101]) - (dest-port . 284) - (src-port . 5408)) - (counters . [100000 261]) - (items . 2) - (item ((data . [1 2 3 4 5]) - (id . "ABCDEF") - (length . 5) - (opcode . 3) - (type . 2)) - ((data . [6 7 8 9 10 11 12]) - (id . "BCDEFG") - (length . 7) - (opcode . 4) - (type . 1)))) -@end lisp - -Fetching data from this structure: - -@lisp -(bindat-get-field decoded 'item 1 'id) - @result{} "BCDEFG" -@end lisp - -@ignore - arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a -@end ignore diff --git a/lispref/searching.texi b/lispref/searching.texi deleted file mode 100644 index 70926478ea7..00000000000 --- a/lispref/searching.texi +++ /dev/null @@ -1,1766 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/searching -@node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top -@chapter Searching and Matching -@cindex searching - - GNU Emacs provides two ways to search through a buffer for specified -text: exact string searches and regular expression searches. After a -regular expression search, you can examine the @dfn{match data} to -determine which text matched the whole regular expression or various -portions of it. - -@menu -* 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,... -@end menu - - The @samp{skip-chars@dots{}} functions also perform a kind of searching. -@xref{Skipping Characters}. To search for changes in character -properties, see @ref{Property Search}. - -@node String Search -@section Searching for Strings -@cindex string search - - These are the primitive functions for searching through the text in a -buffer. They are meant for use in programs, but you may call them -interactively. If you do so, they prompt for the search string; the -arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat} -is 1. - - These search functions convert the search string to multibyte if the -buffer is multibyte; they convert the search string to unibyte if the -buffer is unibyte. @xref{Text Representations}. - -@deffn Command search-forward string &optional limit noerror repeat -This function searches forward from point for an exact match for -@var{string}. If successful, it sets point to the end of the occurrence -found, and returns the new value of point. If no match is found, the -value and side effects depend on @var{noerror} (see below). -@c Emacs 19 feature - -In the following example, point is initially at the beginning of the -line. Then @code{(search-forward "fox")} moves point after the last -letter of @samp{fox}: - -@example -@group ----------- Buffer: foo ---------- -@point{}The quick brown fox jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group - -@group -(search-forward "fox") - @result{} 20 - ----------- Buffer: foo ---------- -The quick brown fox@point{} jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group -@end example - -The argument @var{limit} specifies the upper bound to the search. (It -must be a position in the current buffer.) No match extending after -that position is accepted. If @var{limit} is omitted or @code{nil}, it -defaults to the end of the accessible portion of the buffer. - -@kindex search-failed -What happens when the search fails depends on the value of -@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed} -error is signaled. If @var{noerror} is @code{t}, @code{search-forward} -returns @code{nil} and does nothing. If @var{noerror} is neither -@code{nil} nor @code{t}, then @code{search-forward} moves point to the -upper bound and returns @code{nil}. (It would be more consistent now to -return the new position of point in that case, but some existing -programs may depend on a value of @code{nil}.) - -The argument @var{noerror} only affects valid searches which fail to -find a match. Invalid arguments cause errors regardless of -@var{noerror}. - -If @var{repeat} is supplied (it must be a positive number), then the -search is repeated that many times (each time starting at the end of the -previous time's match). If these successive searches succeed, the -function succeeds, moving point and returning its new value. Otherwise -the search fails, with results depending on the value of -@var{noerror}, as described above. -@end deffn - -@deffn Command search-backward string &optional limit noerror repeat -This function searches backward from point for @var{string}. It is -just like @code{search-forward} except that it searches backwards and -leaves point at the beginning of the match. -@end deffn - -@deffn Command word-search-forward string &optional limit noerror repeat -@c @cindex word search Redundant -This function searches forward from point for a ``word'' match for -@var{string}. If it finds a match, it sets point to the end of the -match found, and returns the new value of point. -@c Emacs 19 feature - -Word matching regards @var{string} as a sequence of words, disregarding -punctuation that separates them. It searches the buffer for the same -sequence of words. Each word must be distinct in the buffer (searching -for the word @samp{ball} does not match the word @samp{balls}), but the -details of punctuation and spacing are ignored (searching for @samp{ball -boy} does match @samp{ball. Boy!}). - -In this example, point is initially at the beginning of the buffer; the -search leaves it between the @samp{y} and the @samp{!}. - -@example -@group ----------- Buffer: foo ---------- -@point{}He said "Please! Find -the ball boy!" ----------- Buffer: foo ---------- -@end group - -@group -(word-search-forward "Please find the ball, boy.") - @result{} 35 - ----------- Buffer: foo ---------- -He said "Please! Find -the ball boy@point{}!" ----------- Buffer: foo ---------- -@end group -@end example - -If @var{limit} is non-@code{nil}, it must be a position in the current -buffer; it specifies the upper bound to the search. The match found -must not extend after that position. - -If @var{noerror} is @code{nil}, then @code{word-search-forward} signals -an error if the search fails. If @var{noerror} is @code{t}, then it -returns @code{nil} instead of signaling an error. If @var{noerror} is -neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the -end of the accessible portion of the buffer) and returns @code{nil}. - -If @var{repeat} is non-@code{nil}, then the search is repeated that many -times. Point is positioned at the end of the last match. -@end deffn - -@deffn Command word-search-backward string &optional limit noerror repeat -This function searches backward from point for a word match to -@var{string}. This function is just like @code{word-search-forward} -except that it searches backward and normally leaves point at the -beginning of the match. -@end deffn - -@node Searching and Case -@section Searching and Case -@cindex searching and case - - By default, searches in Emacs ignore the case of the text they are -searching through; if you specify searching for @samp{FOO}, then -@samp{Foo} or @samp{foo} is also considered a match. This applies to -regular expressions, too; thus, @samp{[aB]} would match @samp{a} or -@samp{A} or @samp{b} or @samp{B}. - - If you do not want this feature, set the variable -@code{case-fold-search} to @code{nil}. Then all letters must match -exactly, including case. This is a buffer-local variable; altering the -variable affects only the current buffer. (@xref{Intro to -Buffer-Local}.) Alternatively, you may change the value of -@code{default-case-fold-search}, which is the default value of -@code{case-fold-search} for buffers that do not override it. - - Note that the user-level incremental search feature handles case -distinctions differently. When given a lower case letter, it looks for -a match of either case, but when given an upper case letter, it looks -for an upper case letter only. But this has nothing to do with the -searching functions used in Lisp code. - -@defopt case-replace -This variable determines whether the higher level replacement -functions should preserve case. If the variable is @code{nil}, that -means to use the replacement text verbatim. A non-@code{nil} value -means to convert the case of the replacement text according to the -text being replaced. - -This variable is used by passing it as an argument to the function -@code{replace-match}. @xref{Replacing Match}. -@end defopt - -@defopt case-fold-search -This buffer-local variable determines whether searches should ignore -case. If the variable is @code{nil} they do not ignore case; otherwise -they do ignore case. -@end defopt - -@defvar default-case-fold-search -The value of this variable is the default value for -@code{case-fold-search} in buffers that do not override it. This is the -same as @code{(default-value 'case-fold-search)}. -@end defvar - -@node Regular Expressions -@section Regular Expressions -@cindex regular expression -@cindex regexp - - A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that -denotes a (possibly infinite) set of strings. Searching for matches for -a regexp is a very powerful operation. This section explains how to write -regexps; the following section says how to search for them. - -@findex re-builder -@cindex regular expressions, developing - For convenient interactive development of regular expressions, you -can use the @kbd{M-x re-builder} command. It provides a convenient -interface for creating regular expressions, by giving immediate visual -feedback in a separate buffer. As you edit the regexp, all its -matches in the target buffer are highlighted. Each parenthesized -sub-expression of the regexp is shown in a distinct face, which makes -it easier to verify even very complex regexps. - -@menu -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. -@end menu - -@node Syntax of Regexps -@subsection Syntax of Regular Expressions - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are @dfn{ordinary}. An ordinary -character is a simple regular expression that matches that character -and nothing else. The special characters are @samp{.}, @samp{*}, -@samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new -special characters will be defined in the future. The character -@samp{]} is special if it ends a character alternative (see later). -The character @samp{-} is special inside a character alternative. A -@samp{[:} and balancing @samp{:]} enclose a character class inside a -character alternative. Any other character appearing in a regular -expression is ordinary, unless a @samp{\} precedes it. - - For example, @samp{f} is not a special character, so it is ordinary, and -therefore @samp{f} is a regular expression that matches the string -@samp{f} and no other string. (It does @emph{not} match the string -@samp{fg}, but it does match a @emph{part} of that string.) Likewise, -@samp{o} is a regular expression that matches only @samp{o}.@refill - - Any two regular expressions @var{a} and @var{b} can be concatenated. The -result is a regular expression that matches a string if @var{a} matches -some amount of the beginning of that string and @var{b} matches the rest of -the string.@refill - - As a simple example, we can concatenate the regular expressions @samp{f} -and @samp{o} to get the regular expression @samp{fo}, which matches only -the string @samp{fo}. Still trivial. To do something more powerful, you -need to use one of the special regular expression constructs. - -@menu -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. -@end menu - -@node Regexp Special -@subsubsection Special Characters in Regular Expressions - - Here is a list of the characters that are special in a regular -expression. - -@need 800 -@table @asis -@item @samp{.}@: @r{(Period)} -@cindex @samp{.} in regexp -is a special character that matches any single character except a newline. -Using concatenation, we can make regular expressions like @samp{a.b}, which -matches any three-character string that begins with @samp{a} and ends with -@samp{b}.@refill - -@item @samp{*} -@cindex @samp{*} in regexp -is not a construct by itself; it is a postfix operator that means to -match the preceding regular expression repetitively as many times as -possible. Thus, @samp{o*} matches any number of @samp{o}s (including no -@samp{o}s). - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating -@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. - -The matcher processes a @samp{*} construct by matching, immediately, as -many repetitions as can be found. Then it continues with the rest of -the pattern. If that fails, backtracking occurs, discarding some of the -matches of the @samp{*}-modified construct in the hope that that will -make it possible to match the rest of the pattern. For example, in -matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} -first tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. With -this choice, the rest of the regexp matches successfully. - -@strong{Warning:} Nested repetition operators can run for an -indefinitely long time, if they lead to ambiguous matching. For -example, trying to match the regular expression @samp{\(x+y*\)*a} -against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could -take hours before it ultimately fails. Emacs must try each way of -grouping the @samp{x}s before concluding that none of them can work. -Even worse, @samp{\(x*\)*} can match the null string in infinitely -many ways, so it causes an infinite loop. To avoid these problems, -check nested repetitions carefully, to make sure that they do not -cause combinatorial explosions in backtracking. - -@item @samp{+} -@cindex @samp{+} in regexp -is a postfix operator, similar to @samp{*} except that it must match -the preceding expression at least once. So, for example, @samp{ca+r} -matches the strings @samp{car} and @samp{caaaar} but not the string -@samp{cr}, whereas @samp{ca*r} matches all three strings. - -@item @samp{?} -@cindex @samp{?} in regexp -is a postfix operator, similar to @samp{*} except that it must match the -preceding expression either once or not at all. For example, -@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. - -@item @samp{*?}, @samp{+?}, @samp{??} -These are ``non-greedy'' variants of the operators @samp{*}, @samp{+} -and @samp{?}. Where those operators match the largest possible -substring (consistent with matching the entire containing expression), -the non-greedy variants match the smallest possible substring -(consistent with matching the entire containing expression). - -For example, the regular expression @samp{c[ad]*a} when applied to the -string @samp{cdaaada} matches the whole string; but the regular -expression @samp{c[ad]*?a}, applied to that same string, matches just -@samp{cda}. (The smallest possible match here for @samp{[ad]*?} that -permits the whole expression to match is @samp{d}.) - -@item @samp{[ @dots{} ]} -@cindex character alternative (in regexp) -@cindex @samp{[} in regexp -@cindex @samp{]} in regexp -is a @dfn{character alternative}, which begins with @samp{[} and is -terminated by @samp{]}. In the simplest case, the characters between -the two brackets are what this character alternative can match. - -Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and -@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s -(including the empty string), from which it follows that @samp{c[ad]*r} -matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. - -You can also include character ranges in a character alternative, by -writing the starting and ending characters with a @samp{-} between them. -Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter. -Ranges may be intermixed freely with individual characters, as in -@samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter -or @samp{$}, @samp{%} or period. - -Note that the usual regexp special characters are not special inside a -character alternative. A completely different set of characters is -special inside character alternatives: @samp{]}, @samp{-} and @samp{^}. - -To include a @samp{]} in a character alternative, you must make it the -first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. -To include a @samp{-}, write @samp{-} as the first or last character of -the character alternative, or put it after a range. Thus, @samp{[]-]} -matches both @samp{]} and @samp{-}. - -To include @samp{^} in a character alternative, put it anywhere but at -the beginning. - -The beginning and end of a range of multibyte characters must be in -the same character set (@pxref{Character Sets}). Thus, -@code{"[\x8e0-\x97c]"} is invalid because character 0x8e0 (@samp{a} -with grave accent) is in the Emacs character set for Latin-1 but the -character 0x97c (@samp{u} with diaeresis) is in the Emacs character -set for Latin-2. (We use Lisp string syntax to write that example, -and a few others in the next few paragraphs, in order to include hex -escape sequences in them.) - -If a range starts with a unibyte character @var{c} and ends with a -multibyte character @var{c2}, the range is divided into two parts: one -is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where -@var{c1} is the first character of the charset to which @var{c2} -belongs. - -You cannot always match all non-@acronym{ASCII} characters with the regular -expression @code{"[\200-\377]"}. This works when searching a unibyte -buffer or string (@pxref{Text Representations}), but not in a multibyte -buffer or string, because many non-@acronym{ASCII} characters have codes -above octal 0377. However, the regular expression @code{"[^\000-\177]"} -does match all non-@acronym{ASCII} characters (see below regarding @samp{^}), -in both multibyte and unibyte representations, because only the -@acronym{ASCII} characters are excluded. - -A character alternative can also specify named -character classes (@pxref{Char Classes}). This is a POSIX feature whose -syntax is @samp{[:@var{class}:]}. Using a character class is equivalent -to mentioning each of the characters in that class; but the latter is -not feasible in practice, since some classes include thousands of -different characters. - -@item @samp{[^ @dots{} ]} -@cindex @samp{^} in regexp -@samp{[^} begins a @dfn{complemented character alternative}. This -matches any character except the ones specified. Thus, -@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and -digits. - -@samp{^} is not special in a character alternative unless it is the first -character. The character following the @samp{^} is treated as if it -were first (in other words, @samp{-} and @samp{]} are not special there). - -A complemented character alternative can match a newline, unless newline is -mentioned as one of the characters not to match. This is in contrast to -the handling of regexps in programs such as @code{grep}. - -@item @samp{^} -@cindex beginning of line in regexp -When matching a buffer, @samp{^} matches the empty string, but only at the -beginning of a line in the text being matched (or the beginning of the -accessible portion of the buffer). Otherwise it fails to match -anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the -beginning of a line. - -When matching a string instead of a buffer, @samp{^} matches at the -beginning of the string or after a newline character. - -For historical compatibility reasons, @samp{^} can be used only at the -beginning of the regular expression, or after @samp{\(}, @samp{\(?:} -or @samp{\|}. - -@item @samp{$} -@cindex @samp{$} in regexp -@cindex end of line in regexp -is similar to @samp{^} but matches only at the end of a line (or the -end of the accessible portion of the buffer). Thus, @samp{x+$} -matches a string of one @samp{x} or more at the end of a line. - -When matching a string instead of a buffer, @samp{$} matches at the end -of the string or before a newline character. - -For historical compatibility reasons, @samp{$} can be used only at the -end of the regular expression, or before @samp{\)} or @samp{\|}. - -@item @samp{\} -@cindex @samp{\} in regexp -has two functions: it quotes the special characters (including -@samp{\}), and it introduces additional special constructs. - -Because @samp{\} quotes special characters, @samp{\$} is a regular -expression that matches only @samp{$}, and @samp{\[} is a regular -expression that matches only @samp{[}, and so on. - -Note that @samp{\} also has special meaning in the read syntax of Lisp -strings (@pxref{String Type}), and must be quoted with @samp{\}. For -example, the regular expression that matches the @samp{\} character is -@samp{\\}. To write a Lisp string that contains the characters -@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another -@samp{\}. Therefore, the read syntax for a regular expression matching -@samp{\} is @code{"\\\\"}.@refill -@end table - -@strong{Please note:} For historical compatibility, special characters -are treated as ordinary ones if they are in contexts where their special -meanings make no sense. For example, @samp{*foo} treats @samp{*} as -ordinary since there is no preceding expression on which the @samp{*} -can act. It is poor practice to depend on this behavior; quote the -special character anyway, regardless of where it appears.@refill - -As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. - -In practice, most @samp{]} that occur in regular expressions close a -character alternative and hence are special. However, occasionally a -regular expression may try to match a complex pattern of literal -@samp{[} and @samp{]}. In such situations, it sometimes may be -necessary to carefully parse the regexp from the start to determine -which square brackets enclose a character alternative. For example, -@samp{[^][]]} consists of the complemented character alternative -@samp{[^][]} (which matches any single character that is not a square -bracket), followed by a literal @samp{]}. - -The exact rules are that at the beginning of a regexp, @samp{[} is -special and @samp{]} not. This lasts until the first unquoted -@samp{[}, after which we are in a character alternative; @samp{[} is -no longer special (except when it starts a character class) but @samp{]} -is special, unless it immediately follows the special @samp{[} or that -@samp{[} followed by a @samp{^}. This lasts until the next special -@samp{]} that does not end a character class. This ends the character -alternative and restores the ordinary syntax of regular expressions; -an unquoted @samp{[} is special again and a @samp{]} not. - -@node Char Classes -@subsubsection Character Classes -@cindex character classes in regexp - - Here is a table of the classes you can use in a character alternative, -and what they mean: - -@table @samp -@item [:ascii:] -This matches any @acronym{ASCII} character (codes 0--127). -@item [:alnum:] -This matches any letter or digit. (At present, for multibyte -characters, it matches anything that has word syntax.) -@item [:alpha:] -This matches any letter. (At present, for multibyte characters, it -matches anything that has word syntax.) -@item [:blank:] -This matches space and tab only. -@item [:cntrl:] -This matches any @acronym{ASCII} control character. -@item [:digit:] -This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]} -matches any digit, as well as @samp{+} and @samp{-}. -@item [:graph:] -This matches graphic characters---everything except @acronym{ASCII} control -characters, space, and the delete character. -@item [:lower:] -This matches any lower-case letter, as determined by -the current case table (@pxref{Case Tables}). -@item [:multibyte:] -This matches any multibyte character (@pxref{Text Representations}). -@item [:nonascii:] -This matches any non-@acronym{ASCII} character. -@item [:print:] -This matches printing characters---everything except @acronym{ASCII} control -characters and the delete character. -@item [:punct:] -This matches any punctuation character. (At present, for multibyte -characters, it matches anything that has non-word syntax.) -@item [:space:] -This matches any character that has whitespace syntax -(@pxref{Syntax Class Table}). -@item [:unibyte:] -This matches any unibyte character (@pxref{Text Representations}). -@item [:upper:] -This matches any upper-case letter, as determined by -the current case table (@pxref{Case Tables}). -@item [:word:] -This matches any character that has word syntax (@pxref{Syntax Class -Table}). -@item [:xdigit:] -This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a} -through @samp{f} and @samp{A} through @samp{F}. -@end table - -@node Regexp Backslash -@subsubsection Backslash Constructs in Regular Expressions - - For the most part, @samp{\} followed by any character matches only -that character. However, there are several exceptions: certain -two-character sequences starting with @samp{\} that have special -meanings. (The character after the @samp{\} in such a sequence is -always ordinary when used on its own.) Here is a table of the special -@samp{\} constructs. - -@table @samp -@item \| -@cindex @samp{|} in regexp -@cindex regexp alternative -specifies an alternative. -Two regular expressions @var{a} and @var{b} with @samp{\|} in -between form an expression that matches anything that either @var{a} or -@var{b} matches.@refill - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill - -If you need full backtracking capability to handle multiple uses of -@samp{\|}, use the POSIX regular expression functions (@pxref{POSIX -Regexps}). - -@item \@{@var{m}\@} -is a postfix operator that repeats the previous pattern exactly @var{m} -times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx} -and nothing else. @samp{c[ad]\@{3\@}r} matches string such as -@samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on. - -@item \@{@var{m},@var{n}\@} -is a more general postfix operator that specifies repetition with a -minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m} -is omitted, the minimum is 0; if @var{n} is omitted, there is no -maximum. - -For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car}, -@samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and -nothing else.@* -@samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}. @* -@samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}. @* -@samp{\@{1,\@}} is equivalent to @samp{+}. - -@item \( @dots{} \) -@cindex @samp{(} in regexp -@cindex @samp{)} in regexp -@cindex regexp grouping -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. Thus, -the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox} -or @samp{barx}. - -@item -To enclose a complicated expression for the postfix operators @samp{*}, -@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches -@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any -number (zero or more) of @samp{na} strings. - -@item -To record a matched substring for future reference with -@samp{\@var{digit}} (see below). -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that was assigned as a -second meaning to the same @samp{\( @dots{} \)} construct because, in -practice, there was usually no conflict between the two meanings. But -occasionally there is a conflict, and that led to the introduction of -shy groups. - -@item \(?: @dots{} \) -is the @dfn{shy group} construct. A shy group serves the first two -purposes of an ordinary group (controlling the nesting of other -operators), but it does not get a number, so you cannot refer back to -its value with @samp{\@var{digit}}. - -Shy groups are particularly useful for mechanically-constructed regular -expressions because they can be added automatically without altering the -numbering of any ordinary, non-shy groups. - -@item \(?@var{num}: @dots{} \) -is the @dfn{explicitly numbered group} construct. Normal groups get -their number implicitly, based on their position, which can be -inconvenient. This construct allows you to force a particular group -number. There is no particular restriction on the numbering, -e.g.@: you can have several groups with the same number in which case -the last one to match (i.e.@: the rightmost match) will win. -Implicitly numbered groups always get the smallest integer larger than -the one of any previous group. - -@item \@var{digit} -matches the same text that matched the @var{digit}th occurrence of a -grouping (@samp{\( @dots{} \)}) construct. - -In other words, after the end of a group, the matcher remembers the -beginning and end of the text matched by that group. Later on in the -regular expression you can use @samp{\} followed by @var{digit} to -match that same text, whatever it may have been. - -The strings matching the first nine grouping constructs appearing in -the entire regular expression passed to a search or matching function -are assigned numbers 1 through 9 in the order that the open -parentheses appear in the regular expression. So you can use -@samp{\1} through @samp{\9} to refer to the text matched by the -corresponding grouping constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -If a @samp{\( @dots{} \)} construct matches more than once (which can -happen, for instance, if it is followed by @samp{*}), only the last -match is recorded. - -If a particular grouping construct in the regular expression was never -matched---for instance, if it appears inside of an alternative that -wasn't used, or inside of a repetition that repeated zero times---then -the corresponding @samp{\@var{digit}} construct never matches -anything. To use an artificial example,, @samp{\(foo\(b*\)\|lose\)\2} -cannot match @samp{lose}: the second alternative inside the larger -group matches it, but then @samp{\2} is undefined and can't match -anything. But it can match @samp{foobb}, because the first -alternative matches @samp{foob} and @samp{\2} matches @samp{b}. - -@item \w -@cindex @samp{\w} in regexp -matches any word-constituent character. The editor syntax table -determines which characters these are. @xref{Syntax Tables}. - -@item \W -@cindex @samp{\W} in regexp -matches any character that is not a word constituent. - -@item \s@var{code} -@cindex @samp{\s} in regexp -matches any character whose syntax is @var{code}. Here @var{code} is a -character that represents a syntax code: thus, @samp{w} for word -constituent, @samp{-} for whitespace, @samp{(} for open parenthesis, -etc. To represent whitespace syntax, use either @samp{-} or a space -character. @xref{Syntax Class Table}, for a list of syntax codes and -the characters that stand for them. - -@item \S@var{code} -@cindex @samp{\S} in regexp -matches any character whose syntax is not @var{code}. - -@item \c@var{c} -matches any character whose category is @var{c}. Here @var{c} is a -character that represents a category: thus, @samp{c} for Chinese -characters or @samp{g} for Greek characters in the standard category -table. - -@item \C@var{c} -matches any character whose category is not @var{c}. -@end table - - The following regular expression constructs match the empty string---that is, -they don't use up any characters---but whether they match depends on the -context. For all, the beginning and end of the accessible portion of -the buffer are treated as if they were the actual beginning and end of -the buffer. - -@table @samp -@item \` -@cindex @samp{\`} in regexp -matches the empty string, but only at the beginning -of the buffer or string being matched against. - -@item \' -@cindex @samp{\'} in regexp -matches the empty string, but only at the end of -the buffer or string being matched against. - -@item \= -@cindex @samp{\=} in regexp -matches the empty string, but only at point. -(This construct is not defined when matching against a string.) - -@item \b -@cindex @samp{\b} in regexp -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill - -@samp{\b} matches at the beginning or end of the buffer (or string) -regardless of what text appears next to it. - -@item \B -@cindex @samp{\B} in regexp -matches the empty string, but @emph{not} at the beginning or -end of a word, nor at the beginning or end of the buffer (or string). - -@item \< -@cindex @samp{\<} in regexp -matches the empty string, but only at the beginning of a word. -@samp{\<} matches at the beginning of the buffer (or string) only if a -word-constituent character follows. - -@item \> -@cindex @samp{\>} in regexp -matches the empty string, but only at the end of a word. @samp{\>} -matches at the end of the buffer (or string) only if the contents end -with a word-constituent character. - -@item \_< -@cindex @samp{\_<} in regexp -matches the empty string, but only at the beginning of a symbol. A -symbol is a sequence of one or more word or symbol constituent -characters. @samp{\_<} matches at the beginning of the buffer (or -string) only if a symbol-constituent character follows. - -@item \_> -@cindex @samp{\_>} in regexp -matches the empty string, but only at the end of a symbol. @samp{\_>} -matches at the end of the buffer (or string) only if the contents end -with a symbol-constituent character. -@end table - -@kindex invalid-regexp - Not every string is a valid regular expression. For example, a string -that ends inside a character alternative without terminating @samp{]} -is invalid, and so is a string that ends with a single @samp{\}. If -an invalid regular expression is passed to any of the search functions, -an @code{invalid-regexp} error is signaled. - -@node Regexp Example -@comment node-name, next, previous, up -@subsection Complex Regexp Example - - Here is a complicated regexp which was formerly used by Emacs to -recognize the end of a sentence together with any whitespace that -follows. (Nowadays Emacs uses a similar but more complex default -regexp constructed by the function @code{sentence-end}. -@xref{Standard Regexps}.) - - First, we show the regexp as a string in Lisp syntax to distinguish -spaces from tab characters. The string constant begins and ends with a -double-quote. @samp{\"} stands for a double-quote as part of the -string, @samp{\\} for a backslash as part of the string, @samp{\t} for a -tab and @samp{\n} for a newline. - -@example -"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*" -@end example - -@noindent -In contrast, if you evaluate this string, you will see the following: - -@example -@group -"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*" - @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[ -]*" -@end group -@end example - -@noindent -In this output, tab and newline appear as themselves. - - This regular expression contains four parts in succession and can be -deciphered as follows: - -@table @code -@item [.?!] -The first part of the pattern is a character alternative that matches -any one of three characters: period, question mark, and exclamation -mark. The match must begin with one of these three characters. (This -is one point where the new default regexp used by Emacs differs from -the old. The new value also allows some non-@acronym{ASCII} -characters that end a sentence without any following whitespace.) - -@item []\"')@}]* -The second part of the pattern matches any closing braces and quotation -marks, zero or more of them, that may follow the period, question mark -or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in -a string. The @samp{*} at the end indicates that the immediately -preceding regular expression (a character alternative, in this case) may be -repeated zero or more times. - -@item \\($\\|@ $\\|\t\\|@ @ \\) -The third part of the pattern matches the whitespace that follows the -end of a sentence: the end of a line (optionally with a space), or a -tab, or two spaces. The double backslashes mark the parentheses and -vertical bars as regular expression syntax; the parentheses delimit a -group and the vertical bars separate alternatives. The dollar sign is -used to match the end of a line. - -@item [ \t\n]* -Finally, the last part of the pattern matches any additional whitespace -beyond the minimum needed to end a sentence. -@end table - -@node Regexp Functions -@subsection Regular Expression Functions - - These functions operate on regular expressions. - -@defun regexp-quote string -This function returns a regular expression whose only exact match is -@var{string}. Using this regular expression in @code{looking-at} will -succeed only if the next characters in the buffer are @var{string}; -using it in a search function will succeed if the text being searched -contains @var{string}. - -This allows you to request an exact string match or search when calling -a function that wants a regular expression. - -@example -@group -(regexp-quote "^The cat$") - @result{} "\\^The cat\\$" -@end group -@end example - -One use of @code{regexp-quote} is to combine an exact string match with -context described as a regular expression. For example, this searches -for the string that is the value of @var{string}, surrounded by -whitespace: - -@example -@group -(re-search-forward - (concat "\\s-" (regexp-quote string) "\\s-")) -@end group -@end example -@end defun - -@defun regexp-opt strings &optional paren -This function returns an efficient regular expression that will match -any of the strings in the list @var{strings}. This is useful when you -need to make matching or searching as fast as possible---for example, -for Font Lock mode. - -If the optional argument @var{paren} is non-@code{nil}, then the -returned regular expression is always enclosed by at least one -parentheses-grouping construct. If @var{paren} is @code{words}, then -that construct is additionally surrounded by @samp{\<} and @samp{\>}. - -This simplified definition of @code{regexp-opt} produces a -regular expression which is equivalent to the actual value -(but not as efficient): - -@example -(defun regexp-opt (strings paren) - (let ((open-paren (if paren "\\(" "")) - (close-paren (if paren "\\)" ""))) - (concat open-paren - (mapconcat 'regexp-quote strings "\\|") - close-paren))) -@end example -@end defun - -@defun regexp-opt-depth regexp -This function returns the total number of grouping constructs -(parenthesized expressions) in @var{regexp}. (This does not include -shy groups.) -@end defun - -@node Regexp Search -@section Regular Expression Searching -@cindex regular expression searching -@cindex regexp searching -@cindex searching for regexp - - In GNU Emacs, you can search for the next match for a regular -expression either incrementally or not. For incremental search -commands, see @ref{Regexp Search, , Regular Expression Search, emacs, -The GNU Emacs Manual}. Here we describe only the search functions -useful in programs. The principal one is @code{re-search-forward}. - - These search functions convert the regular expression to multibyte if -the buffer is multibyte; they convert the regular expression to unibyte -if the buffer is unibyte. @xref{Text Representations}. - -@deffn Command re-search-forward regexp &optional limit noerror repeat -This function searches forward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}. The -function skips over any amount of text that is not matched by -@var{regexp}, and leaves point at the end of the first match found. -It returns the new value of point. - -If @var{limit} is non-@code{nil}, it must be a position in the current -buffer. It specifies the upper bound to the search. No match -extending after that position is accepted. - -If @var{repeat} is supplied, it must be a positive number; the search -is repeated that many times; each repetition starts at the end of the -previous match. If all these successive searches succeed, the search -succeeds, moving point and returning its new value. Otherwise the -search fails. What @code{re-search-forward} does when the search -fails depends on the value of @var{noerror}: - -@table @asis -@item @code{nil} -Signal a @code{search-failed} error. -@item @code{t} -Do nothing and return @code{nil}. -@item anything else -Move point to @var{limit} (or the end of the accessible portion of the -buffer) and return @code{nil}. -@end table - -In the following example, point is initially before the @samp{T}. -Evaluating the search call moves point to the end of that line (between -the @samp{t} of @samp{hat} and the newline). - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(re-search-forward "[a-z]+" nil t 5) - @result{} 27 - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command re-search-backward regexp &optional limit noerror repeat -This function searches backward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}, leaving -point at the beginning of the first text found. - -This function is analogous to @code{re-search-forward}, but they are not -simple mirror images. @code{re-search-forward} finds the match whose -beginning is as close as possible to the starting point. If -@code{re-search-backward} were a perfect mirror image, it would find the -match whose end is as close as possible. However, in fact it finds the -match whose beginning is as close as possible (and yet ends before the -starting point). The reason for this is that matching a regular -expression at a given spot always works from beginning to end, and -starts at a specified beginning position. - -A true mirror-image of @code{re-search-forward} would require a special -feature for matching regular expressions from end to beginning. It's -not worth the trouble of implementing that. -@end deffn - -@defun string-match regexp string &optional start -This function returns the index of the start of the first match for -the regular expression @var{regexp} in @var{string}, or @code{nil} if -there is no match. If @var{start} is non-@code{nil}, the search starts -at that index in @var{string}. - -For example, - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly.") - @result{} 4 -@end group -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group -@end example - -@noindent -The index of the first character of the -string is 0, the index of the second character is 1, and so on. - -After this function returns, the index of the first character beyond -the match is available as @code{(match-end 0)}. @xref{Match Data}. - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group - -@group -(match-end 0) - @result{} 32 -@end group -@end example -@end defun - -@defun looking-at regexp -This function determines whether the text in the current buffer directly -following point matches the regular expression @var{regexp}. ``Directly -following'' means precisely that: the search is ``anchored'' and it can -succeed only starting with the first character following point. The -result is @code{t} if so, @code{nil} otherwise. - -This function does not move point, but it updates the match data, which -you can access using @code{match-beginning} and @code{match-end}. -@xref{Match Data}. - -In this example, point is located directly before the @samp{T}. If it -were anywhere else, the result would be @code{nil}. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- - -(looking-at "The cat in the hat$") - @result{} t -@end group -@end example -@end defun - -@defun looking-back regexp &optional limit -This function returns @code{t} if @var{regexp} matches text before -point, ending at point, and @code{nil} otherwise. - -Because regular expression matching works only going forward, this is -implemented by searching backwards from point for a match that ends at -point. That can be quite slow if it has to search a long distance. -You can bound the time required by specifying @var{limit}, which says -not to search before @var{limit}. In this case, the match that is -found must begin at or after @var{limit}. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- - -(looking-back "read \"" 3) - @result{} t -(looking-back "read \"" 4) - @result{} nil -@end group -@end example -@end defun - -@defvar search-spaces-regexp -If this variable is non-@code{nil}, it should be a regular expression -that says how to search for whitespace. In that case, any group of -spaces in a regular expression being searched for stands for use of -this regular expression. However, spaces inside of constructs such as -@samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by -@code{search-spaces-regexp}. - -Since this variable affects all regular expression search and match -constructs, you should bind it temporarily for as small as possible -a part of the code. -@end defvar - -@node POSIX Regexps -@section POSIX Regular Expression Searching - - The usual regular expression functions do backtracking when necessary -to handle the @samp{\|} and repetition constructs, but they continue -this only until they find @emph{some} match. Then they succeed and -report the first match found. - - This section describes alternative search functions which perform the -full backtracking specified by the POSIX standard for regular expression -matching. They continue backtracking until they have tried all -possibilities and found all matches, so they can report the longest -match, as required by POSIX. This is much slower, so use these -functions only when you really need the longest match. - - The POSIX search and match functions do not properly support the -non-greedy repetition operators. This is because POSIX backtracking -conflicts with the semantics of non-greedy repetition. - -@defun posix-search-forward regexp &optional limit noerror repeat -This is like @code{re-search-forward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@defun posix-search-backward regexp &optional limit noerror repeat -This is like @code{re-search-backward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@defun posix-looking-at regexp -This is like @code{looking-at} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@defun posix-string-match regexp string &optional start -This is like @code{string-match} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@node Match Data -@section The Match Data -@cindex match data - - Emacs keeps track of the start and end positions of the segments of -text found during a search; this is called the @dfn{match data}. -Thanks to the match data, you can search for a complex pattern, such -as a date in a mail message, and then extract parts of the match under -control of the pattern. - - Because the match data normally describe the most recent search only, -you must be careful not to do another search inadvertently between the -search you wish to refer back to and the use of the match data. If you -can't avoid another intervening search, you must save and restore the -match data around it, to prevent it from being overwritten. - -@menu -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. -@end menu - -@node Replacing Match -@subsection Replacing the Text that Matched -@cindex replace matched text - - This function replaces all or part of the text matched by the last -search. It works by means of the match data. - -@cindex case in replacements -@defun replace-match replacement &optional fixedcase literal string subexp -This function replaces the text in the buffer (or in @var{string}) that -was matched by the last search. It replaces that text with -@var{replacement}. - -If you did the last search in a buffer, you should specify @code{nil} -for @var{string} and make sure that the current buffer when you call -@code{replace-match} is the one in which you did the searching or -matching. Then @code{replace-match} does the replacement by editing -the buffer; it leaves point at the end of the replacement text, and -returns @code{t}. - -If you did the search in a string, pass the same string as @var{string}. -Then @code{replace-match} does the replacement by constructing and -returning a new string. - -If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses -the replacement text without case conversion; otherwise, it converts -the replacement text depending upon the capitalization of the text to -be replaced. If the original text is all upper case, this converts -the replacement text to upper case. If all words of the original text -are capitalized, this capitalizes all the words of the replacement -text. If all the words are one-letter and they are all upper case, -they are treated as capitalized words rather than all-upper-case -words. - -If @var{literal} is non-@code{nil}, then @var{replacement} is inserted -exactly as it is, the only alterations being case changes as needed. -If it is @code{nil} (the default), then the character @samp{\} is treated -specially. If a @samp{\} appears in @var{replacement}, then it must be -part of one of the following sequences: - -@table @asis -@item @samp{\&} -@cindex @samp{&} in replacement -@samp{\&} stands for the entire text being replaced. - -@item @samp{\@var{n}} -@cindex @samp{\@var{n}} in replacement -@samp{\@var{n}}, where @var{n} is a digit, stands for the text that -matched the @var{n}th subexpression in the original regexp. -Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}. -If the @var{n}th subexpression never matched, an empty string is substituted. - -@item @samp{\\} -@cindex @samp{\} in replacement -@samp{\\} stands for a single @samp{\} in the replacement text. -@end table - -These substitutions occur after case conversion, if any, -so the strings they substitute are never case-converted. - -If @var{subexp} is non-@code{nil}, that says to replace just -subexpression number @var{subexp} of the regexp that was matched, not -the entire match. For example, after matching @samp{foo \(ba*r\)}, -calling @code{replace-match} with 1 as @var{subexp} means to replace -just the text that matched @samp{\(ba*r\)}. -@end defun - -@node Simple Match Data -@subsection Simple Match Data Access - - This section explains how to use the match data to find out what was -matched by the last search or match operation, if it succeeded. - - You can ask about the entire matching text, or about a particular -parenthetical subexpression of a regular expression. The @var{count} -argument in the functions below specifies which. If @var{count} is -zero, you are asking about the entire match. If @var{count} is -positive, it specifies which subexpression you want. - - Recall that the subexpressions of a regular expression are those -expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The -@var{count}th subexpression is found by counting occurrences of -@samp{\(} from the beginning of the whole regular expression. The first -subexpression is numbered 1, the second 2, and so on. Only regular -expressions can have subexpressions---after a simple string search, the -only information available is about the entire match. - - Every successful search sets the match data. Therefore, you should -query the match data immediately after searching, before calling any -other function that might perform another search. Alternatively, you -may save and restore the match data (@pxref{Saving Match Data}) around -the call to functions that could perform another search. - - A search which fails may or may not alter the match data. In the -past, a failing search did not do this, but we may change it in the -future. So don't try to rely on the value of the match data after -a failing search. - -@defun match-string count &optional in-string -This function returns, as a string, the text matched in the last search -or match operation. It returns the entire text if @var{count} is zero, -or just the portion corresponding to the @var{count}th parenthetical -subexpression, if @var{count} is positive. - -If the last such operation was done against a string with -@code{string-match}, then you should pass the same string as the -argument @var{in-string}. After a buffer search or match, -you should omit @var{in-string} or pass @code{nil} for it; but you -should make sure that the current buffer when you call -@code{match-string} is the one in which you did the searching or -matching. - -The value is @code{nil} if @var{count} is out of range, or for a -subexpression inside a @samp{\|} alternative that wasn't used or a -repetition that repeated zero times. -@end defun - -@defun match-string-no-properties count &optional in-string -This function is like @code{match-string} except that the result -has no text properties. -@end defun - -@defun match-beginning count -This function returns the position of the start of text matched by the -last regular expression searched for, or a subexpression of it. - -If @var{count} is zero, then the value is the position of the start of -the entire match. Otherwise, @var{count} specifies a subexpression in -the regular expression, and the value of the function is the starting -position of the match for that subexpression. - -The value is @code{nil} for a subexpression inside a @samp{\|} -alternative that wasn't used or a repetition that repeated zero times. -@end defun - -@defun match-end count -This function is like @code{match-beginning} except that it returns the -position of the end of the match, rather than the position of the -beginning. -@end defun - - Here is an example of using the match data, with a comment showing the -positions within the text: - -@example -@group -(string-match "\\(qu\\)\\(ick\\)" - "The quick fox jumped quickly.") - ;0123456789 - @result{} 4 -@end group - -@group -(match-string 0 "The quick fox jumped quickly.") - @result{} "quick" -(match-string 1 "The quick fox jumped quickly.") - @result{} "qu" -(match-string 2 "The quick fox jumped quickly.") - @result{} "ick" -@end group - -@group -(match-beginning 1) ; @r{The beginning of the match} - @result{} 4 ; @r{with @samp{qu} is at index 4.} -@end group - -@group -(match-beginning 2) ; @r{The beginning of the match} - @result{} 6 ; @r{with @samp{ick} is at index 6.} -@end group - -@group -(match-end 1) ; @r{The end of the match} - @result{} 6 ; @r{with @samp{qu} is at index 6.} - -(match-end 2) ; @r{The end of the match} - @result{} 9 ; @r{with @samp{ick} is at index 9.} -@end group -@end example - - Here is another example. Point is initially located at the beginning -of the line. Searching moves point to between the space and the word -@samp{in}. The beginning of the entire match is at the 9th character of -the buffer (@samp{T}), and the beginning of the match for the first -subexpression is at the 13th character (@samp{c}). - -@example -@group -(list - (re-search-forward "The \\(cat \\)") - (match-beginning 0) - (match-beginning 1)) - @result{} (9 9 13) -@end group - -@group ----------- Buffer: foo ---------- -I read "The cat @point{}in the hat comes back" twice. - ^ ^ - 9 13 ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -(In this case, the index returned is a buffer position; the first -character of the buffer counts as 1.) - -@node Entire Match Data -@subsection Accessing the Entire Match Data - - The functions @code{match-data} and @code{set-match-data} read or -write the entire match data, all at once. - -@defun match-data &optional integers reuse reseat -This function returns a list of positions (markers or integers) that -record all the information on what text the last search matched. -Element zero is the position of the beginning of the match for the -whole expression; element one is the position of the end of the match -for the expression. The next two elements are the positions of the -beginning and end of the match for the first subexpression, and so on. -In general, element -@ifnottex -number 2@var{n} -@end ifnottex -@tex -number {\mathsurround=0pt $2n$} -@end tex -corresponds to @code{(match-beginning @var{n})}; and -element -@ifnottex -number 2@var{n} + 1 -@end ifnottex -@tex -number {\mathsurround=0pt $2n+1$} -@end tex -corresponds to @code{(match-end @var{n})}. - -Normally all the elements are markers or @code{nil}, but if -@var{integers} is non-@code{nil}, that means to use integers instead -of markers. (In that case, the buffer itself is appended as an -additional element at the end of the list, to facilitate complete -restoration of the match data.) If the last match was done on a -string with @code{string-match}, then integers are always used, -since markers can't point into a string. - -If @var{reuse} is non-@code{nil}, it should be a list. In that case, -@code{match-data} stores the match data in @var{reuse}. That is, -@var{reuse} is destructively modified. @var{reuse} does not need to -have the right length. If it is not long enough to contain the match -data, it is extended. If it is too long, the length of @var{reuse} -stays the same, but the elements that were not used are set to -@code{nil}. The purpose of this feature is to reduce the need for -garbage collection. - -If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list -are reseated to point to nowhere. - -As always, there must be no possibility of intervening searches between -the call to a search function and the call to @code{match-data} that is -intended to access the match data for that search. - -@example -@group -(match-data) - @result{} (#<marker at 9 in foo> - #<marker at 17 in foo> - #<marker at 13 in foo> - #<marker at 17 in foo>) -@end group -@end example -@end defun - -@defun set-match-data match-list &optional reseat -This function sets the match data from the elements of @var{match-list}, -which should be a list that was the value of a previous call to -@code{match-data}. (More precisely, anything that has the same format -will work.) - -If @var{match-list} refers to a buffer that doesn't exist, you don't get -an error; that sets the match data in a meaningless but harmless way. - -If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list -are reseated to point to nowhere. - -@findex store-match-data -@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}. -@end defun - -@node Saving Match Data -@subsection Saving and Restoring the Match Data - - When you call a function that may do a search, you may need to save -and restore the match data around that call, if you want to preserve the -match data from an earlier search for later use. Here is an example -that shows the problem that arises if you fail to save the match data: - -@example -@group -(re-search-forward "The \\(cat \\)") - @result{} 48 -(foo) ; @r{Perhaps @code{foo} does} - ; @r{more searching.} -(match-end 0) - @result{} 61 ; @r{Unexpected result---not 48!} -@end group -@end example - - You can save and restore the match data with @code{save-match-data}: - -@defmac save-match-data body@dots{} -This macro executes @var{body}, saving and restoring the match -data around it. The return value is the value of the last form in -@var{body}. -@end defmac - - You could use @code{set-match-data} together with @code{match-data} to -imitate the effect of the special form @code{save-match-data}. Here is -how: - -@example -@group -(let ((data (match-data))) - (unwind-protect - @dots{} ; @r{Ok to change the original match data.} - (set-match-data data))) -@end group -@end example - - Emacs automatically saves and restores the match data when it runs -process filter functions (@pxref{Filter Functions}) and process -sentinels (@pxref{Sentinels}). - -@ignore - Here is a function which restores the match data provided the buffer -associated with it still exists. - -@smallexample -@group -(defun restore-match-data (data) -@c It is incorrect to split the first line of a doc string. -@c If there's a problem here, it should be solved in some other way. - "Restore the match data DATA unless the buffer is missing." - (catch 'foo - (let ((d data)) -@end group - (while d - (and (car d) - (null (marker-buffer (car d))) -@group - ;; @file{match-data} @r{buffer is deleted.} - (throw 'foo nil)) - (setq d (cdr d))) - (set-match-data data)))) -@end group -@end smallexample -@end ignore - -@node Search and Replace -@section Search and Replace -@cindex replacement after search -@cindex searching and replacing - - If you want to find all matches for a regexp in part of the buffer, -and replace them, the best way is to write an explicit loop using -@code{re-search-forward} and @code{replace-match}, like this: - -@example -(while (re-search-forward "foo[ \t]+bar" nil t) - (replace-match "foobar")) -@end example - -@noindent -@xref{Replacing Match,, Replacing the Text that Matched}, for a -description of @code{replace-match}. - - However, replacing matches in a string is more complex, especially -if you want to do it efficiently. So Emacs provides a function to do -this. - -@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start -This function copies @var{string} and searches it for matches for -@var{regexp}, and replaces them with @var{rep}. It returns the -modified copy. If @var{start} is non-@code{nil}, the search for -matches starts at that index in @var{string}, so matches starting -before that index are not changed. - -This function uses @code{replace-match} to do the replacement, and it -passes the optional arguments @var{fixedcase}, @var{literal} and -@var{subexp} along to @code{replace-match}. - -Instead of a string, @var{rep} can be a function. In that case, -@code{replace-regexp-in-string} calls @var{rep} for each match, -passing the text of the match as its sole argument. It collects the -value @var{rep} returns and passes that to @code{replace-match} as the -replacement string. The match-data at this point are the result -of matching @var{regexp} against a substring of @var{string}. -@end defun - - If you want to write a command along the lines of @code{query-replace}, -you can use @code{perform-replace} to do the work. - -@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end -This function is the guts of @code{query-replace} and related -commands. It searches for occurrences of @var{from-string} in the -text between positions @var{start} and @var{end} and replaces some or -all of them. If @var{start} is @code{nil} (or omitted), point is used -instead, and the end of the buffer's accessible portion is used for -@var{end}. - -If @var{query-flag} is @code{nil}, it replaces all -occurrences; otherwise, it asks the user what to do about each one. - -If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is -considered a regular expression; otherwise, it must match literally. If -@var{delimited-flag} is non-@code{nil}, then only replacements -surrounded by word boundaries are considered. - -The argument @var{replacements} specifies what to replace occurrences -with. If it is a string, that string is used. It can also be a list of -strings, to be used in cyclic order. - -If @var{replacements} is a cons cell, @code{(@var{function} -. @var{data})}, this means to call @var{function} after each match to -get the replacement text. This function is called with two arguments: -@var{data}, and the number of replacements already made. - -If @var{repeat-count} is non-@code{nil}, it should be an integer. Then -it specifies how many times to use each of the strings in the -@var{replacements} list before advancing cyclically to the next one. - -If @var{from-string} contains upper-case letters, then -@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and -it uses the @code{replacements} without altering the case of them. - -Normally, the keymap @code{query-replace-map} defines the possible -user responses for queries. The argument @var{map}, if -non-@code{nil}, specifies a keymap to use instead of -@code{query-replace-map}. -@end defun - -@defvar query-replace-map -This variable holds a special keymap that defines the valid user -responses for @code{perform-replace} and the commands that use it, as -well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual -in two ways: - -@itemize @bullet -@item -The ``key bindings'' are not commands, just symbols that are meaningful -to the functions that use this map. - -@item -Prefix keys are not supported; each key binding must be for a -single-event key sequence. This is because the functions don't use -@code{read-key-sequence} to get the input; instead, they read a single -event and look it up ``by hand.'' -@end itemize -@end defvar - -Here are the meaningful ``bindings'' for @code{query-replace-map}. -Several of them are meaningful only for @code{query-replace} and -friends. - -@table @code -@item act -Do take the action being considered---in other words, ``yes.'' - -@item skip -Do not take action for this question---in other words, ``no.'' - -@item exit -Answer this question ``no,'' and give up on the entire series of -questions, assuming that the answers will be ``no.'' - -@item act-and-exit -Answer this question ``yes,'' and give up on the entire series of -questions, assuming that subsequent answers will be ``no.'' - -@item act-and-show -Answer this question ``yes,'' but show the results---don't advance yet -to the next question. - -@item automatic -Answer this question and all subsequent questions in the series with -``yes,'' without further user interaction. - -@item backup -Move back to the previous place that a question was asked about. - -@item edit -Enter a recursive edit to deal with this question---instead of any -other action that would normally be taken. - -@item delete-and-edit -Delete the text being considered, then enter a recursive edit to replace -it. - -@item recenter -Redisplay and center the window, then ask the same question again. - -@item quit -Perform a quit right away. Only @code{y-or-n-p} and related functions -use this answer. - -@item help -Display some help, then ask again. -@end table - -@node Standard Regexps -@section Standard Regular Expressions Used in Editing -@cindex regexps used standardly in editing -@cindex standard regexps used in editing - - This section describes some variables that hold regular expressions -used for certain purposes in editing: - -@defvar page-delimiter -This is the regular expression describing line-beginnings that separate -pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or -@code{"^\C-l"}); this matches a line that starts with a formfeed -character. -@end defvar - - The following two regular expressions should @emph{not} assume the -match always starts at the beginning of a line; they should not use -@samp{^} to anchor the match. Most often, the paragraph commands do -check for a match only at the beginning of a line, which means that -@samp{^} would be superfluous. When there is a nonzero left margin, -they accept matches that start after the left margin. In that case, a -@samp{^} would be incorrect. However, a @samp{^} is harmless in modes -where a left margin is never used. - -@defvar paragraph-separate -This is the regular expression for recognizing the beginning of a line -that separates paragraphs. (If you change this, you may have to -change @code{paragraph-start} also.) The default value is -@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of -spaces, tabs, and form feeds (after its left margin). -@end defvar - -@defvar paragraph-start -This is the regular expression for recognizing the beginning of a line -that starts @emph{or} separates paragraphs. The default value is -@w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only -whitespace or starting with a form feed (after its left margin). -@end defvar - -@defvar sentence-end -If non-@code{nil}, the value should be a regular expression describing -the end of a sentence, including the whitespace following the -sentence. (All paragraph boundaries also end sentences, regardless.) - -If the value is @code{nil}, the default, then the function -@code{sentence-end} has to construct the regexp. That is why you -should always call the function @code{sentence-end} to obtain the -regexp to be used to recognize the end of a sentence. -@end defvar - -@defun sentence-end -This function returns the value of the variable @code{sentence-end}, -if non-@code{nil}. Otherwise it returns a default value based on the -values of the variables @code{sentence-end-double-space} -(@pxref{Definition of sentence-end-double-space}), -@code{sentence-end-without-period} and -@code{sentence-end-without-space}. -@end defun - -@ignore - arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f -@end ignore diff --git a/lispref/sequences.texi b/lispref/sequences.texi deleted file mode 100644 index 7e66549412b..00000000000 --- a/lispref/sequences.texi +++ /dev/null @@ -1,734 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/sequences -@node Sequences Arrays Vectors, Hash Tables, Lists, Top -@chapter Sequences, Arrays, and Vectors -@cindex sequence - - Recall that the @dfn{sequence} type is the union of two other Lisp -types: lists and arrays. In other words, any list is a sequence, and -any array is a sequence. The common property that all sequences have is -that each is an ordered collection of elements. - - An @dfn{array} is a single primitive object that has a slot for each -of its elements. All the elements are accessible in constant time, but -the length of an existing array cannot be changed. Strings, vectors, -char-tables and bool-vectors are the four types of arrays. - - A list is a sequence of elements, but it is not a single primitive -object; it is made of cons cells, one cell per element. Finding the -@var{n}th element requires looking through @var{n} cons cells, so -elements farther from the beginning of the list take longer to access. -But it is possible to add elements to the list, or remove elements. - - The following diagram shows the relationship between these types: - -@example -@group - _____________________________________________ - | | - | Sequence | - | ______ ________________________________ | - | | | | | | - | | List | | Array | | - | | | | ________ ________ | | - | |______| | | | | | | | - | | | Vector | | String | | | - | | |________| |________| | | - | | ____________ _____________ | | - | | | | | | | | - | | | Char-table | | Bool-vector | | | - | | |____________| |_____________| | | - | |________________________________| | - |_____________________________________________| -@end group -@end example - - The elements of vectors and lists may be any Lisp objects. The -elements of strings are all characters. - -@menu -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. -@end menu - -@node Sequence Functions -@section Sequences - - In Emacs Lisp, a @dfn{sequence} is either a list or an array. The -common property of all sequences is that they are ordered collections of -elements. This section describes functions that accept any kind of -sequence. - -@defun sequencep object -Returns @code{t} if @var{object} is a list, vector, string, -bool-vector, or char-table, @code{nil} otherwise. -@end defun - -@defun length sequence -@cindex string length -@cindex list length -@cindex vector length -@cindex sequence length -@cindex char-table length -This function returns the number of elements in @var{sequence}. If -@var{sequence} is a dotted list, a @code{wrong-type-argument} error is -signaled. Circular lists may cause an infinite loop. For a -char-table, the value returned is always one more than the maximum -Emacs character code. - -@xref{Definition of safe-length}, for the related function @code{safe-length}. - -@example -@group -(length '(1 2 3)) - @result{} 3 -@end group -@group -(length ()) - @result{} 0 -@end group -@group -(length "foobar") - @result{} 6 -@end group -@group -(length [1 2 3]) - @result{} 3 -@end group -@group -(length (make-bool-vector 5 nil)) - @result{} 5 -@end group -@end example -@end defun - -@noindent -See also @code{string-bytes}, in @ref{Text Representations}. - -@defun elt sequence index -@cindex elements of sequences -This function returns the element of @var{sequence} indexed by -@var{index}. Legitimate values of @var{index} are integers ranging -from 0 up to one less than the length of @var{sequence}. If -@var{sequence} is a list, out-of-range values behave as for -@code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values -trigger an @code{args-out-of-range} error. - -@example -@group -(elt [1 2 3 4] 2) - @result{} 3 -@end group -@group -(elt '(1 2 3 4) 2) - @result{} 3 -@end group -@group -;; @r{We use @code{string} to show clearly which character @code{elt} returns.} -(string (elt "1234" 2)) - @result{} "3" -@end group -@group -(elt [1 2 3 4] 4) - @error{} Args out of range: [1 2 3 4], 4 -@end group -@group -(elt [1 2 3 4] -1) - @error{} Args out of range: [1 2 3 4], -1 -@end group -@end example - -This function generalizes @code{aref} (@pxref{Array Functions}) and -@code{nth} (@pxref{Definition of nth}). -@end defun - -@defun copy-sequence sequence -@cindex copying sequences -Returns a copy of @var{sequence}. The copy is the same type of object -as the original sequence, and it has the same elements in the same order. - -Storing a new element into the copy does not affect the original -@var{sequence}, and vice versa. However, the elements of the new -sequence are not copies; they are identical (@code{eq}) to the elements -of the original. Therefore, changes made within these elements, as -found via the copied sequence, are also visible in the original -sequence. - -If the sequence is a string with text properties, the property list in -the copy is itself a copy, not shared with the original's property -list. However, the actual values of the properties are shared. -@xref{Text Properties}. - -This function does not work for dotted lists. Trying to copy a -circular list may cause an infinite loop. - -See also @code{append} in @ref{Building Lists}, @code{concat} in -@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions}, -for other ways to copy sequences. - -@example -@group -(setq bar '(1 2)) - @result{} (1 2) -@end group -@group -(setq x (vector 'foo bar)) - @result{} [foo (1 2)] -@end group -@group -(setq y (copy-sequence x)) - @result{} [foo (1 2)] -@end group - -@group -(eq x y) - @result{} nil -@end group -@group -(equal x y) - @result{} t -@end group -@group -(eq (elt x 1) (elt y 1)) - @result{} t -@end group - -@group -;; @r{Replacing an element of one sequence.} -(aset x 0 'quux) -x @result{} [quux (1 2)] -y @result{} [foo (1 2)] -@end group - -@group -;; @r{Modifying the inside of a shared element.} -(setcar (aref x 1) 69) -x @result{} [quux (69 2)] -y @result{} [foo (69 2)] -@end group -@end example -@end defun - -@node Arrays -@section Arrays -@cindex array - - An @dfn{array} object has slots that hold a number of other Lisp -objects, called the elements of the array. Any element of an array may -be accessed in constant time. In contrast, an element of a list -requires access time that is proportional to the position of the element -in the list. - - Emacs defines four types of array, all one-dimensional: @dfn{strings}, -@dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}. A vector is a -general array; its elements can be any Lisp objects. A string is a -specialized array; its elements must be characters. Each type of array -has its own read syntax. -@xref{String Type}, and @ref{Vector Type}. - - All four kinds of array share these characteristics: - -@itemize @bullet -@item -The first element of an array has index zero, the second element has -index 1, and so on. This is called @dfn{zero-origin} indexing. For -example, an array of four elements has indices 0, 1, 2, @w{and 3}. - -@item -The length of the array is fixed once you create it; you cannot -change the length of an existing array. - -@item -For purposes of evaluation, the array is a constant---in other words, -it evaluates to itself. - -@item -The elements of an array may be referenced or changed with the functions -@code{aref} and @code{aset}, respectively (@pxref{Array Functions}). -@end itemize - - When you create an array, other than a char-table, you must specify -its length. You cannot specify the length of a char-table, because that -is determined by the range of character codes. - - In principle, if you want an array of text characters, you could use -either a string or a vector. In practice, we always choose strings for -such applications, for four reasons: - -@itemize @bullet -@item -They occupy one-fourth the space of a vector of the same elements. - -@item -Strings are printed in a way that shows the contents more clearly -as text. - -@item -Strings can hold text properties. @xref{Text Properties}. - -@item -Many of the specialized editing and I/O facilities of Emacs accept only -strings. For example, you cannot insert a vector of characters into a -buffer the way you can insert a string. @xref{Strings and Characters}. -@end itemize - - By contrast, for an array of keyboard input characters (such as a key -sequence), a vector may be necessary, because many keyboard input -characters are outside the range that will fit in a string. @xref{Key -Sequence Input}. - -@node Array Functions -@section Functions that Operate on Arrays - - In this section, we describe the functions that accept all types of -arrays. - -@defun arrayp object -This function returns @code{t} if @var{object} is an array (i.e., a -vector, a string, a bool-vector or a char-table). - -@example -@group -(arrayp [a]) - @result{} t -(arrayp "asdf") - @result{} t -(arrayp (syntax-table)) ;; @r{A char-table.} - @result{} t -@end group -@end example -@end defun - -@defun aref array index -@cindex array elements -This function returns the @var{index}th element of @var{array}. The -first element is at index zero. - -@example -@group -(setq primes [2 3 5 7 11 13]) - @result{} [2 3 5 7 11 13] -(aref primes 4) - @result{} 11 -@end group -@group -(aref "abcdefg" 1) - @result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.} -@end group -@end example - -See also the function @code{elt}, in @ref{Sequence Functions}. -@end defun - -@defun aset array index object -This function sets the @var{index}th element of @var{array} to be -@var{object}. It returns @var{object}. - -@example -@group -(setq w [foo bar baz]) - @result{} [foo bar baz] -(aset w 0 'fu) - @result{} fu -w - @result{} [fu bar baz] -@end group - -@group -(setq x "asdfasfd") - @result{} "asdfasfd" -(aset x 3 ?Z) - @result{} 90 -x - @result{} "asdZasfd" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. The function converts a -unibyte string to multibyte if necessary to insert a character. -@end defun - -@defun fillarray array object -This function fills the array @var{array} with @var{object}, so that -each element of @var{array} is @var{object}. It returns @var{array}. - -@example -@group -(setq a [a b c d e f g]) - @result{} [a b c d e f g] -(fillarray a 0) - @result{} [0 0 0 0 0 0 0] -a - @result{} [0 0 0 0 0 0 0] -@end group -@group -(setq s "When in the course") - @result{} "When in the course" -(fillarray s ?-) - @result{} "------------------" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. -@end defun - -The general sequence functions @code{copy-sequence} and @code{length} -are often useful for objects known to be arrays. @xref{Sequence Functions}. - -@node Vectors -@section Vectors -@cindex vector (type) - - Arrays in Lisp, like arrays in most languages, are blocks of memory -whose elements can be accessed in constant time. A @dfn{vector} is a -general-purpose array of specified length; its elements can be any Lisp -objects. (By contrast, a string can hold only characters as elements.) -Vectors in Emacs are used for obarrays (vectors of symbols), and as part -of keymaps (vectors of commands). They are also used internally as part -of the representation of a byte-compiled function; if you print such a -function, you will see a vector in it. - - In Emacs Lisp, the indices of the elements of a vector start from zero -and count up from there. - - Vectors are printed with square brackets surrounding the elements. -Thus, a vector whose elements are the symbols @code{a}, @code{b} and -@code{a} is printed as @code{[a b a]}. You can write vectors in the -same way in Lisp input. - - A vector, like a string or a number, is considered a constant for -evaluation: the result of evaluating it is the same vector. This does -not evaluate or even examine the elements of the vector. -@xref{Self-Evaluating Forms}. - - Here are examples illustrating these principles: - -@example -@group -(setq avector [1 two '(three) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(eval avector) - @result{} [1 two (quote (three)) "four" [five]] -(eq avector (eval avector)) - @result{} t -@end group -@end example - -@node Vector Functions -@section Functions for Vectors - - Here are some functions that relate to vectors: - -@defun vectorp object -This function returns @code{t} if @var{object} is a vector. - -@example -@group -(vectorp [a]) - @result{} t -(vectorp "asdf") - @result{} nil -@end group -@end example -@end defun - -@defun vector &rest objects -This function creates and returns a vector whose elements are the -arguments, @var{objects}. - -@example -@group -(vector 'foo 23 [bar baz] "rats") - @result{} [foo 23 [bar baz] "rats"] -(vector) - @result{} [] -@end group -@end example -@end defun - -@defun make-vector length object -This function returns a new vector consisting of @var{length} elements, -each initialized to @var{object}. - -@example -@group -(setq sleepy (make-vector 9 'Z)) - @result{} [Z Z Z Z Z Z Z Z Z] -@end group -@end example -@end defun - -@defun vconcat &rest sequences -@cindex copying vectors -This function returns a new vector containing all the elements of the -@var{sequences}. The arguments @var{sequences} may be true lists, -vectors, strings or bool-vectors. If no @var{sequences} are given, an -empty vector is returned. - -The value is a newly constructed vector that is not @code{eq} to any -existing vector. - -@example -@group -(setq a (vconcat '(A B C) '(D E F))) - @result{} [A B C D E F] -(eq a (vconcat a)) - @result{} nil -@end group -@group -(vconcat) - @result{} [] -(vconcat [A B C] "aa" '(foo (6 7))) - @result{} [A B C 97 97 foo (6 7)] -@end group -@end example - -The @code{vconcat} function also allows byte-code function objects as -arguments. This is a special feature to make it easy to access the entire -contents of a byte-code function object. @xref{Byte-Code Objects}. - -In Emacs versions before 21, the @code{vconcat} function allowed -integers as arguments, converting them to strings of digits, but that -feature has been eliminated. The proper way to convert an integer to -a decimal number in this way is with @code{format} (@pxref{Formatting -Strings}) or @code{number-to-string} (@pxref{String Conversion}). - -For other concatenation functions, see @code{mapconcat} in @ref{Mapping -Functions}, @code{concat} in @ref{Creating Strings}, and @code{append} -in @ref{Building Lists}. -@end defun - - The @code{append} function also provides a way to convert a vector into a -list with the same elements: - -@example -@group -(setq avector [1 two (quote (three)) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(append avector nil) - @result{} (1 two (quote (three)) "four" [five]) -@end group -@end example - -@node Char-Tables -@section Char-Tables -@cindex char-tables -@cindex extra slots of char-table - - A char-table is much like a vector, except that it is indexed by -character codes. Any valid character code, without modifiers, can be -used as an index in a char-table. You can access a char-table's -elements with @code{aref} and @code{aset}, as with any array. In -addition, a char-table can have @dfn{extra slots} to hold additional -data not associated with particular character codes. Char-tables are -constants when evaluated. - -@cindex subtype of char-table - Each char-table has a @dfn{subtype} which is a symbol. The subtype -has two purposes: to distinguish char-tables meant for different uses, -and to control the number of extra slots. For example, display tables -are char-tables with @code{display-table} as the subtype, and syntax -tables are char-tables with @code{syntax-table} as the subtype. A valid -subtype must have a @code{char-table-extra-slots} property which is an -integer between 0 and 10. This integer specifies the number of -@dfn{extra slots} in the char-table. - -@cindex parent of char-table - A char-table can have a @dfn{parent}, which is another char-table. If -it does, then whenever the char-table specifies @code{nil} for a -particular character @var{c}, it inherits the value specified in the -parent. In other words, @code{(aref @var{char-table} @var{c})} returns -the value from the parent of @var{char-table} if @var{char-table} itself -specifies @code{nil}. - -@cindex default value of char-table - A char-table can also have a @dfn{default value}. If so, then -@code{(aref @var{char-table} @var{c})} returns the default value -whenever the char-table does not specify any other non-@code{nil} value. - -@defun make-char-table subtype &optional init -Return a newly created char-table, with subtype @var{subtype}. Each -element is initialized to @var{init}, which defaults to @code{nil}. You -cannot alter the subtype of a char-table after the char-table is -created. - -There is no argument to specify the length of the char-table, because -all char-tables have room for any valid character code as an index. -@end defun - -@defun char-table-p object -This function returns @code{t} if @var{object} is a char-table, -otherwise @code{nil}. -@end defun - -@defun char-table-subtype char-table -This function returns the subtype symbol of @var{char-table}. -@end defun - -@defun set-char-table-default char-table char new-default -This function sets the default value of generic character @var{char} -in @var{char-table} to @var{new-default}. - -There is no special function to access default values in a char-table. -To do that, use @code{char-table-range} (see below). -@end defun - -@defun char-table-parent char-table -This function returns the parent of @var{char-table}. The parent is -always either @code{nil} or another char-table. -@end defun - -@defun set-char-table-parent char-table new-parent -This function sets the parent of @var{char-table} to @var{new-parent}. -@end defun - -@defun char-table-extra-slot char-table n -This function returns the contents of extra slot @var{n} of -@var{char-table}. The number of extra slots in a char-table is -determined by its subtype. -@end defun - -@defun set-char-table-extra-slot char-table n value -This function stores @var{value} in extra slot @var{n} of -@var{char-table}. -@end defun - - A char-table can specify an element value for a single character code; -it can also specify a value for an entire character set. - -@defun char-table-range char-table range -This returns the value specified in @var{char-table} for a range of -characters @var{range}. Here are the possibilities for @var{range}: - -@table @asis -@item @code{nil} -Refers to the default value. - -@item @var{char} -Refers to the element for character @var{char} -(supposing @var{char} is a valid character code). - -@item @var{charset} -Refers to the value specified for the whole character set -@var{charset} (@pxref{Character Sets}). - -@item @var{generic-char} -A generic character stands for a character set, or a row of a -character set; specifying the generic character as argument is -equivalent to specifying the character set name. @xref{Splitting -Characters}, for a description of generic characters. -@end table -@end defun - -@defun set-char-table-range char-table range value -This function sets the value in @var{char-table} for a range of -characters @var{range}. Here are the possibilities for @var{range}: - -@table @asis -@item @code{nil} -Refers to the default value. - -@item @code{t} -Refers to the whole range of character codes. - -@item @var{char} -Refers to the element for character @var{char} -(supposing @var{char} is a valid character code). - -@item @var{charset} -Refers to the value specified for the whole character set -@var{charset} (@pxref{Character Sets}). - -@item @var{generic-char} -A generic character stands for a character set; specifying the generic -character as argument is equivalent to specifying the character set -name. @xref{Splitting Characters}, for a description of generic characters. -@end table -@end defun - -@defun map-char-table function char-table -This function calls @var{function} for each element of @var{char-table}. -@var{function} is called with two arguments, a key and a value. The key -is a possible @var{range} argument for @code{char-table-range}---either -a valid character or a generic character---and the value is -@code{(char-table-range @var{char-table} @var{key})}. - -Overall, the key-value pairs passed to @var{function} describe all the -values stored in @var{char-table}. - -The return value is always @code{nil}; to make this function useful, -@var{function} should have side effects. For example, -here is how to examine each element of the syntax table: - -@example -(let (accumulator) - (map-char-table - #'(lambda (key value) - (setq accumulator - (cons (list key value) accumulator))) - (syntax-table)) - accumulator) -@result{} -((475008 nil) (474880 nil) (474752 nil) (474624 nil) - ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3))) -@end example -@end defun - -@node Bool-Vectors -@section Bool-vectors -@cindex Bool-vectors - - A bool-vector is much like a vector, except that it stores only the -values @code{t} and @code{nil}. If you try to store any non-@code{nil} -value into an element of the bool-vector, the effect is to store -@code{t} there. As with all arrays, bool-vector indices start from 0, -and the length cannot be changed once the bool-vector is created. -Bool-vectors are constants when evaluated. - - There are two special functions for working with bool-vectors; aside -from that, you manipulate them with same functions used for other kinds -of arrays. - -@defun make-bool-vector length initial -Return a new bool-vector of @var{length} elements, -each one initialized to @var{initial}. -@end defun - -@defun bool-vector-p object -This returns @code{t} if @var{object} is a bool-vector, -and @code{nil} otherwise. -@end defun - - Here is an example of creating, examining, and updating a -bool-vector. Note that the printed form represents up to 8 boolean -values as a single character. - -@example -(setq bv (make-bool-vector 5 t)) - @result{} #&5"^_" -(aref bv 1) - @result{} t -(aset bv 3 nil) - @result{} nil -bv - @result{} #&5"^W" -@end example - -@noindent -These results make sense because the binary codes for control-_ and -control-W are 11111 and 10111, respectively. - -@ignore - arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386 -@end ignore diff --git a/lispref/spellfile b/lispref/spellfile deleted file mode 100644 index b373d00bebf..00000000000 --- a/lispref/spellfile +++ /dev/null @@ -1,738 +0,0 @@ -ARPA -Abbrev -Acknowledgements -Alan -Arnold -Autoloading -BAppend -Backquote -Beeping -Beverly -Boyes -Brian -CL -CSWKg -Carl -Carroll -Chris -Cleanups -DEC -DStandard -Dan -Dired's -Disassembly -Duff -EMAC -EMACSLOADPATH -Eckelkamp -Edward -Eirik -Emacses -Eric -Erlebacher -Fcar -Fcdr -Fcons -Fcoordinates -Feval -Frazzle -Frederick -Fri -Gardiner -Gentlemen -HAL -HATTED -HS -HU -Hanchrow -Hartzell -Hess -Hewlett -IBM -ISBN -Impl -Interning -Ithought -J's -Jacobson -Jak -Joe -Jones -Jr -Jul -Keymaps -Kimmo -Kirman -Knighten -Korz -Krawitz -LTsHm -LaLiberte -LaTeX -Lammens -Local' -MAC -MONIES -MSS -Maclisp -Magill -Marick -Matthew -Minibuf -Misc -Miscellany -Mocklisp -Montanaro -Myers -NFS -Nathan -Nope -OS -OSITIONS -Oct -Ovwrt -PURESIZE -Packard -Qlistp -Qnil -RMAIL -Raul -Resizing -Robbins -Rockwell -SCO -SIGCONT -SIGHUP -SIGINT -SIGKILL -SIGQUIT -SIGTSTP -SLOAD -Scoordinates -Set' -Setcar -Setcdr -Shinichirou -Snarf -Sor -SourceFile -Stops' -Subprocess -Sugou -Sunview -Suominen -T's -TCP -ThXs -Tharp -Thu -Trost -UCB -UNEVALLED -UNGCPRO -UniPlus -UniSoft's -VMS -Vip -Void' -Warren -Welty -Wethought -Wilding -Worley -Wright -XDVI -XFASTINT -XINT -XWINDOW -Xs -Yo -Zuhn -aB -aa -aaa -abbrevname -abbrevs -abc -abcdefg -abcxyz -abd -above' -abracadabra -address' -after' -alist -alists -anchored' -and' -ar -aref -arg'th -argdecl -arith -arrayp -arrow' -asa -asdZasfd -asdf -asdfasfd -aset -assoc -assq -at' -aug -autoload -automatic' -automatically' -avector -bBuffer -bFrobnicate -ba -back' -bananana -barfoo -barx -bballs -before' -beforep -bfoo -bil -binding's -bish -bobp -bolp -bottommost -boundp -brief' -buf -buffer' -bufferp -buttercup -ca -caaaar -caaar -caddaar -cadr -callable -cbreak -ce -cell' -cells' -cf -chaprm -character' -childp -chistory -ck -column' -commandp -concat -cond -conses -consing -consp -constant' -contains' -continuable -convert' -copyleft -correct' -counterintuitive -cr -creatable -customie -deactivate -deactivated -deassigns -decrement' -deffnx -definition' -defmacro -defsubr -deletable -deletion' -delq -depiction -descendents -deselecting -destructive' -destructively' -diffs -ding -directory' -dired -dirname -disassembler -dland -docfile -docstring -doesnt -dont -down' -downcasing -downloadable -dribble -dup -ef -efg -electric' -elided -elt -enablement -endkeyfun -endrecfun -environment' -eobp -eof -eol -eolp -eq -eqlsign -erminal -erste -etags -eval -evalled -evals -evaluate' -excess' -exec -exitcode -expression' -extendible -extra' -fails' -fascist -fboundp -featurep -ff -fg -fi -file' -filespec -filesystems -fillarray -firstchar -firstonly -fixedcase -fixit -fixup -floatp -fmakunbound -fns -fo -fol -folded' -following' -fooba -foobaz -foox -for' -formfeed -forms' -forw -forwa -found' -frob -from' -front' -fset -fstab -ftp -fu -funtions -garbles -gc -gcpro -gd -getenv -getprv -gid -gnuemacs -gp -grep -gtr -halves' -hand' -hashes' -hd -hexadecimal -hf -hfil -hookvar -horsechestnut -hostname -hpux -hscroll -ibmapa -ick -id -idiom -ii -indrm -inode -input' -inputinput -inserting' -integerp -intermixed -ints -inturned -irreversibly -jum -keymapp -kill' -killed' -killp -kludge -kolstad -language' -lastchar -lcl -ledit -leif -lessp -level' -lewis -library' -link' -lisplib -listexp -loadable -loadst -loadup -logand -logior -lognot -logxor -long' -loop's -lru -lrwxrwxrwx -ls -lsh -m's -macroexpand -makunbound -malloc -mapatoms -mapconcat -mapvar -mark' -marker's -markerp -mathsurround -medit -memq -mh -mim -mini -minibuffer's -minibuffers -misalignment -misnamed -mode's -modename -modes' -mods -modtime -mqueue -msg -multicharacter -myfile -nCount -nXExpression -na -name's -natnump -nb -nbBuffer -nconc -newdef -newelt -newname -nextrecfun -nfsusr -ninett -nlines -nlinks -nlistp -noconfirm -nodigits -noerror -noforce -nomessage -nominees -nomsg -nonblank -nonconstant -nondestructive -nondirectory -nonidentical -noninteractive -noninteractively -nonletter -nonletters -nonlocally -nonoverlapping -nonprinting -nonselected -nonsequentially -nonvoid -nonwarranty -nonwritable -noop -noprint -norecord -normal' -noselect -nosuffix -nots -noundo -nr -nreverse -ns -nsRename -nth -nthcdr -num -number' -numberp -nums -obarray -obarrays -object' -oldbuf -olddef -oldname -oo -oops -op -or' -otl -out' -over' -overful -overfullrule -overstrike -overstriking -overstruck -p' -paren -part' -passwd -pe -ped -perverse -pid -plist -pnt -pointer' -pointm -pos -preallocate -predicale -preload -prepend -prepended -prepends -pretty' -prin -princ -print' -printenv -printer' -proc -process' -processp -programmer' -prolog -protect' -ps -psf -psychotherapy -pty -purecopy -qu -quux -rassq -reader' -readin -rebind -rec -rechecking -recursively' -recycler' -redo -redrawing -redraws -redump -reenabled -reexposed -reg -region' -reindent -reindents -reinitialization -reinitialize -reinitialized -reinstall -reinstalled -resize -resized -resizes -reversibly -reworded -rhetorical -right' -ring' -risky -rmailedit -rms -rplaca -rplacd -rtu -runnable -rw -rwxrwxrwx -sDescribe -sans -se -searching' -section' -seed' -sequence' -sequencep -setp -setplist -setprv -settable -setuid -sexp -sexps -shape' -shell's -sideline -special' -specpdl -st -stanford -startkeyfun -str -stringp -stty -subcategories -subcommands -subexp -subform -subforms -subjob -submap -subprocesses -subr -subr' -subroutine' -subrp -subrs -subwindows -sugar' -suid -supersession -suspension' -symbolp -symlink -syms -syntatic -tabname -temacs -temporarily' -tempvar -tenths -termcap -termcaps -terminfo -termscript -termtype -terpri -text' -textrm -textsl -texttt -than' -the' -tildes -time's -to' -towars -transportable -txt -types' -uid -unbind -unbinding -unbinds -unchanged' -unclutters -undefine -undefines -underfull -undo's -undodata -unevaluated' -unexec -unexpand -unhesitatingly -uninterned -unisoft -unpaired -unread -unreadable -unreading -unsaved -untyped -ununderline -up' -uptime -usecount -used' -user' -userlock -usg -val -varbind -varname -varref -vars -varset -vb -vconcat -vectorp -vfil -vi -vn -voidness -vrs -vt -window' -windowing -windowp -wrapped' -xSpecify -xcoord -xcssun -xemacs -xenix -xf -xfirst -xoff -xon -xx -xxxxx -xxxxxxxxx -xy -xyz -ycoord -yes' -zA -zap -zerop diff --git a/lispref/streams.texi b/lispref/streams.texi deleted file mode 100644 index 7356c119a1e..00000000000 --- a/lispref/streams.texi +++ /dev/null @@ -1,837 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/streams -@node Read and Print, Minibuffers, Debugging, Top -@comment node-name, next, previous, up -@chapter Reading and Printing Lisp Objects - - @dfn{Printing} and @dfn{reading} are the operations of converting Lisp -objects to textual form and vice versa. They use the printed -representations and read syntax described in @ref{Lisp Data Types}. - - This chapter describes the Lisp functions for reading and printing. -It also describes @dfn{streams}, which specify where to get the text (if -reading) or where to put it (if printing). - -@menu -* 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. -@end menu - -@node Streams Intro -@section Introduction to Reading and Printing -@cindex Lisp reader -@cindex printing -@cindex reading - - @dfn{Reading} a Lisp object means parsing a Lisp expression in textual -form and producing a corresponding Lisp object. This is how Lisp -programs get into Lisp from files of Lisp code. We call the text the -@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)} -is the read syntax for a cons cell whose @sc{car} is @code{a} and whose -@sc{cdr} is the number 5. - - @dfn{Printing} a Lisp object means producing text that represents that -object---converting the object to its @dfn{printed representation} -(@pxref{Printed Representation}). Printing the cons cell described -above produces the text @samp{(a .@: 5)}. - - Reading and printing are more or less inverse operations: printing the -object that results from reading a given piece of text often produces -the same text, and reading the text that results from printing an object -usually produces a similar-looking object. For example, printing the -symbol @code{foo} produces the text @samp{foo}, and reading that text -returns the symbol @code{foo}. Printing a list whose elements are -@code{a} and @code{b} produces the text @samp{(a b)}, and reading that -text produces a list (but not the same list) with elements @code{a} -and @code{b}. - - However, these two operations are not precisely inverse to each other. -There are three kinds of exceptions: - -@itemize @bullet -@item -Printing can produce text that cannot be read. For example, buffers, -windows, frames, subprocesses and markers print as text that starts -with @samp{#}; if you try to read this text, you get an error. There is -no way to read those data types. - -@item -One object can have multiple textual representations. For example, -@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and -@samp{(a .@: (b))} represent the same list. Reading will accept any of -the alternatives, but printing must choose one of them. - -@item -Comments can appear at certain points in the middle of an object's -read sequence without affecting the result of reading it. -@end itemize - -@node Input Streams -@section Input Streams -@cindex stream (for reading) -@cindex input stream - - Most of the Lisp functions for reading text take an @dfn{input stream} -as an argument. The input stream specifies where or how to get the -characters of the text to be read. Here are the possible types of input -stream: - -@table @asis -@item @var{buffer} -@cindex buffer input stream -The input characters are read from @var{buffer}, starting with the -character directly after point. Point advances as characters are read. - -@item @var{marker} -@cindex marker input stream -The input characters are read from the buffer that @var{marker} is in, -starting with the character directly after the marker. The marker -position advances as characters are read. The value of point in the -buffer has no effect when the stream is a marker. - -@item @var{string} -@cindex string input stream -The input characters are taken from @var{string}, starting at the first -character in the string and using as many characters as required. - -@item @var{function} -@cindex function input stream -The input characters are generated by @var{function}, which must support -two kinds of calls: - -@itemize @bullet -@item -When it is called with no arguments, it should return the next character. - -@item -When it is called with one argument (always a character), @var{function} -should save the argument and arrange to return it on the next call. -This is called @dfn{unreading} the character; it happens when the Lisp -reader reads one character too many and wants to ``put it back where it -came from.'' In this case, it makes no difference what value -@var{function} returns. -@end itemize - -@item @code{t} -@cindex @code{t} input stream -@code{t} used as a stream means that the input is read from the -minibuffer. In fact, the minibuffer is invoked once and the text -given by the user is made into a string that is then used as the -input stream. If Emacs is running in batch mode, standard input is used -instead of the minibuffer. For example, -@example -(message "%s" (read t)) -@end example -will read a Lisp expression from standard input and print the result -to standard output. - -@item @code{nil} -@cindex @code{nil} input stream -@code{nil} supplied as an input stream means to use the value of -@code{standard-input} instead; that value is the @dfn{default input -stream}, and must be a non-@code{nil} input stream. - -@item @var{symbol} -A symbol as input stream is equivalent to the symbol's function -definition (if any). -@end table - - Here is an example of reading from a stream that is a buffer, showing -where point is located before and after: - -@example -@group ----------- Buffer: foo ---------- -This@point{} is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(read (get-buffer "foo")) - @result{} is -@end group -@group -(read (get-buffer "foo")) - @result{} the -@end group - -@group ----------- Buffer: foo ---------- -This is the@point{} contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -Note that the first read skips a space. Reading skips any amount of -whitespace preceding the significant text. - - Here is an example of reading from a stream that is a marker, -initially positioned at the beginning of the buffer shown. The value -read is the symbol @code{This}. - -@example -@group - ----------- Buffer: foo ---------- -This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(setq m (set-marker (make-marker) 1 (get-buffer "foo"))) - @result{} #<marker at 1 in foo> -@end group -@group -(read m) - @result{} This -@end group -@group -m - @result{} #<marker at 5 in foo> ;; @r{Before the first space.} -@end group -@end example - - Here we read from the contents of a string: - -@example -@group -(read "(When in) the course") - @result{} (When in) -@end group -@end example - - The following example reads from the minibuffer. The -prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt -used when you read from the stream @code{t}.) The user's input is shown -following the prompt. - -@example -@group -(read t) - @result{} 23 ----------- Buffer: Minibuffer ---------- -Lisp expression: @kbd{23 @key{RET}} ----------- Buffer: Minibuffer ---------- -@end group -@end example - - Finally, here is an example of a stream that is a function, named -@code{useless-stream}. Before we use the stream, we initialize the -variable @code{useless-list} to a list of characters. Then each call to -the function @code{useless-stream} obtains the next character in the list -or unreads a character by adding it to the front of the list. - -@example -@group -(setq useless-list (append "XY()" nil)) - @result{} (88 89 40 41) -@end group - -@group -(defun useless-stream (&optional unread) - (if unread - (setq useless-list (cons unread useless-list)) - (prog1 (car useless-list) - (setq useless-list (cdr useless-list))))) - @result{} useless-stream -@end group -@end example - -@noindent -Now we read using the stream thus constructed: - -@example -@group -(read 'useless-stream) - @result{} XY -@end group - -@group -useless-list - @result{} (40 41) -@end group -@end example - -@noindent -Note that the open and close parentheses remain in the list. The Lisp -reader encountered the open parenthesis, decided that it ended the -input, and unread it. Another attempt to read from the stream at this -point would read @samp{()} and return @code{nil}. - -@defun get-file-char -This function is used internally as an input stream to read from the -input file opened by the function @code{load}. Don't use this function -yourself. -@end defun - -@node Input Functions -@section Input Functions - - This section describes the Lisp functions and variables that pertain -to reading. - - In the functions below, @var{stream} stands for an input stream (see -the previous section). If @var{stream} is @code{nil} or omitted, it -defaults to the value of @code{standard-input}. - -@kindex end-of-file - An @code{end-of-file} error is signaled if reading encounters an -unterminated list, vector, or string. - -@defun read &optional stream -This function reads one textual Lisp expression from @var{stream}, -returning it as a Lisp object. This is the basic Lisp input function. -@end defun - -@defun read-from-string string &optional start end -@cindex string to object -This function reads the first textual Lisp expression from the text in -@var{string}. It returns a cons cell whose @sc{car} is that expression, -and whose @sc{cdr} is an integer giving the position of the next -remaining character in the string (i.e., the first one not read). - -If @var{start} is supplied, then reading begins at index @var{start} in -the string (where the first character is at index 0). If you specify -@var{end}, then reading is forced to stop just before that index, as if -the rest of the string were not there. - -For example: - -@example -@group -(read-from-string "(setq x 55) (setq y 5)") - @result{} ((setq x 55) . 11) -@end group -@group -(read-from-string "\"A short string\"") - @result{} ("A short string" . 16) -@end group - -@group -;; @r{Read starting at the first character.} -(read-from-string "(list 112)" 0) - @result{} ((list 112) . 10) -@end group -@group -;; @r{Read starting at the second character.} -(read-from-string "(list 112)" 1) - @result{} (list . 5) -@end group -@group -;; @r{Read starting at the seventh character,} -;; @r{and stopping at the ninth.} -(read-from-string "(list 112)" 6 8) - @result{} (11 . 8) -@end group -@end example -@end defun - -@defvar standard-input -This variable holds the default input stream---the stream that -@code{read} uses when the @var{stream} argument is @code{nil}. -The default is @code{t}, meaning use the minibuffer. -@end defvar - -@node Output Streams -@section Output Streams -@cindex stream (for printing) -@cindex output stream - - An output stream specifies what to do with the characters produced -by printing. Most print functions accept an output stream as an -optional argument. Here are the possible types of output stream: - -@table @asis -@item @var{buffer} -@cindex buffer output stream -The output characters are inserted into @var{buffer} at point. -Point advances as characters are inserted. - -@item @var{marker} -@cindex marker output stream -The output characters are inserted into the buffer that @var{marker} -points into, at the marker position. The marker position advances as -characters are inserted. The value of point in the buffer has no effect -on printing when the stream is a marker, and this kind of printing -does not move point (except that if the marker points at or before the -position of point, point advances with the surrounding text, as -usual). - -@item @var{function} -@cindex function output stream -The output characters are passed to @var{function}, which is responsible -for storing them away. It is called with a single character as -argument, as many times as there are characters to be output, and -is responsible for storing the characters wherever you want to put them. - -@item @code{t} -@cindex @code{t} output stream -The output characters are displayed in the echo area. - -@item @code{nil} -@cindex @code{nil} output stream -@code{nil} specified as an output stream means to use the value of -@code{standard-output} instead; that value is the @dfn{default output -stream}, and must not be @code{nil}. - -@item @var{symbol} -A symbol as output stream is equivalent to the symbol's function -definition (if any). -@end table - - Many of the valid output streams are also valid as input streams. The -difference between input and output streams is therefore more a matter -of how you use a Lisp object, than of different types of object. - - Here is an example of a buffer used as an output stream. Point is -initially located as shown immediately before the @samp{h} in -@samp{the}. At the end, point is located directly before that same -@samp{h}. - -@cindex print example -@example -@group ----------- Buffer: foo ---------- -This is t@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group - -(print "This is the output" (get-buffer "foo")) - @result{} "This is the output" - -@group ----------- Buffer: foo ---------- -This is t -"This is the output" -@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - - Now we show a use of a marker as an output stream. Initially, the -marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in -the word @samp{the}. At the end, the marker has advanced over the -inserted text so that it remains positioned before the same @samp{h}. -Note that the location of point, shown in the usual fashion, has no -effect. - -@example -@group ----------- Buffer: foo ---------- -This is the @point{}output ----------- Buffer: foo ---------- -@end group - -@group -(setq m (copy-marker 10)) - @result{} #<marker at 10 in foo> -@end group - -@group -(print "More output for foo." m) - @result{} "More output for foo." -@end group - -@group ----------- Buffer: foo ---------- -This is t -"More output for foo." -he @point{}output ----------- Buffer: foo ---------- -@end group - -@group -m - @result{} #<marker at 34 in foo> -@end group -@end example - - The following example shows output to the echo area: - -@example -@group -(print "Echo Area output" t) - @result{} "Echo Area output" ----------- Echo Area ---------- -"Echo Area output" ----------- Echo Area ---------- -@end group -@end example - - Finally, we show the use of a function as an output stream. The -function @code{eat-output} takes each character that it is given and -conses it onto the front of the list @code{last-output} (@pxref{Building -Lists}). At the end, the list contains all the characters output, but -in reverse order. - -@example -@group -(setq last-output nil) - @result{} nil -@end group - -@group -(defun eat-output (c) - (setq last-output (cons c last-output))) - @result{} eat-output -@end group - -@group -(print "This is the output" 'eat-output) - @result{} "This is the output" -@end group - -@group -last-output - @result{} (10 34 116 117 112 116 117 111 32 101 104 - 116 32 115 105 32 115 105 104 84 34 10) -@end group -@end example - -@noindent -Now we can put the output in the proper order by reversing the list: - -@example -@group -(concat (nreverse last-output)) - @result{} " -\"This is the output\" -" -@end group -@end example - -@noindent -Calling @code{concat} converts the list to a string so you can see its -contents more clearly. - -@node Output Functions -@section Output Functions - - This section describes the Lisp functions for printing Lisp -objects---converting objects into their printed representation. - -@cindex @samp{"} in printing -@cindex @samp{\} in printing -@cindex quoting characters in printing -@cindex escape characters in printing - Some of the Emacs printing functions add quoting characters to the -output when necessary so that it can be read properly. The quoting -characters used are @samp{"} and @samp{\}; they distinguish strings from -symbols, and prevent punctuation characters in strings and symbols from -being taken as delimiters when reading. @xref{Printed Representation}, -for full details. You specify quoting or no quoting by the choice of -printing function. - - If the text is to be read back into Lisp, then you should print with -quoting characters to avoid ambiguity. Likewise, if the purpose is to -describe a Lisp object clearly for a Lisp programmer. However, if the -purpose of the output is to look nice for humans, then it is usually -better to print without quoting. - - Lisp objects can refer to themselves. Printing a self-referential -object in the normal way would require an infinite amount of text, and -the attempt could cause infinite recursion. Emacs detects such -recursion and prints @samp{#@var{level}} instead of recursively printing -an object already being printed. For example, here @samp{#0} indicates -a recursive reference to the object at level 0 of the current print -operation: - -@example -(setq foo (list nil)) - @result{} (nil) -(setcar foo foo) - @result{} (#0) -@end example - - In the functions below, @var{stream} stands for an output stream. -(See the previous section for a description of output streams.) If -@var{stream} is @code{nil} or omitted, it defaults to the value of -@code{standard-output}. - -@defun print object &optional stream -@cindex Lisp printer -The @code{print} function is a convenient way of printing. It outputs -the printed representation of @var{object} to @var{stream}, printing in -addition one newline before @var{object} and another after it. Quoting -characters are used. @code{print} returns @var{object}. For example: - -@example -@group -(progn (print 'The\ cat\ in) - (print "the hat") - (print " came back")) - @print{} - @print{} The\ cat\ in - @print{} - @print{} "the hat" - @print{} - @print{} " came back" - @result{} " came back" -@end group -@end example -@end defun - -@defun prin1 object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It does not print newlines to separate output as -@code{print} does, but it does use quoting characters just like -@code{print}. It returns @var{object}. - -@example -@group -(progn (prin1 'The\ cat\ in) - (prin1 "the hat") - (prin1 " came back")) - @print{} The\ cat\ in"the hat"" came back" - @result{} " came back" -@end group -@end example -@end defun - -@defun princ object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It returns @var{object}. - -This function is intended to produce output that is readable by people, -not by @code{read}, so it doesn't insert quoting characters and doesn't -put double-quotes around the contents of strings. It does not add any -spacing between calls. - -@example -@group -(progn - (princ 'The\ cat) - (princ " in the \"hat\"")) - @print{} The cat in the "hat" - @result{} " in the \"hat\"" -@end group -@end example -@end defun - -@defun terpri &optional stream -@cindex newline in print -This function outputs a newline to @var{stream}. The name stands -for ``terminate print.'' -@end defun - -@defun write-char character &optional stream -This function outputs @var{character} to @var{stream}. It returns -@var{character}. -@end defun - -@defun prin1-to-string object &optional noescape -@cindex object to string -This function returns a string containing the text that @code{prin1} -would have printed for the same argument. - -@example -@group -(prin1-to-string 'foo) - @result{} "foo" -@end group -@group -(prin1-to-string (mark-marker)) - @result{} "#<marker at 2773 in strings.texi>" -@end group -@end example - -If @var{noescape} is non-@code{nil}, that inhibits use of quoting -characters in the output. (This argument is supported in Emacs versions -19 and later.) - -@example -@group -(prin1-to-string "foo") - @result{} "\"foo\"" -@end group -@group -(prin1-to-string "foo" t) - @result{} "foo" -@end group -@end example - -See @code{format}, in @ref{Formatting Strings}, for other ways to obtain -the printed representation of a Lisp object as a string. -@end defun - -@defmac with-output-to-string body@dots{} -This macro executes the @var{body} forms with @code{standard-output} set -up to feed output into a string. Then it returns that string. - -For example, if the current buffer name is @samp{foo}, - -@example -(with-output-to-string - (princ "The buffer is ") - (princ (buffer-name))) -@end example - -@noindent -returns @code{"The buffer is foo"}. -@end defmac - -@node Output Variables -@section Variables Affecting Output -@cindex output-controlling variables - -@defvar standard-output -The value of this variable is the default output stream---the stream -that print functions use when the @var{stream} argument is @code{nil}. -The default is @code{t}, meaning display in the echo area. -@end defvar - -@defvar print-quoted -If this is non-@code{nil}, that means to print quoted forms using -abbreviated reader syntax. @code{(quote foo)} prints as @code{'foo}, -@code{(function foo)} as @code{#'foo}, and backquoted forms print -using modern backquote syntax. -@end defvar - -@defvar print-escape-newlines -@cindex @samp{\n} in print -@cindex escape characters -If this variable is non-@code{nil}, then newline characters in strings -are printed as @samp{\n} and formfeeds are printed as @samp{\f}. -Normally these characters are printed as actual newlines and formfeeds. - -This variable affects the print functions @code{prin1} and @code{print} -that print with quoting. It does not affect @code{princ}. Here is an -example using @code{prin1}: - -@example -@group -(prin1 "a\nb") - @print{} "a - @print{} b" - @result{} "a -b" -@end group - -@group -(let ((print-escape-newlines t)) - (prin1 "a\nb")) - @print{} "a\nb" - @result{} "a -b" -@end group -@end example - -@noindent -In the second expression, the local binding of -@code{print-escape-newlines} is in effect during the call to -@code{prin1}, but not during the printing of the result. -@end defvar - -@defvar print-escape-nonascii -If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII} -characters in strings are unconditionally printed as backslash sequences -by the print functions @code{prin1} and @code{print} that print with -quoting. - -Those functions also use backslash sequences for unibyte non-@acronym{ASCII} -characters, regardless of the value of this variable, when the output -stream is a multibyte buffer or a marker pointing into one. -@end defvar - -@defvar print-escape-multibyte -If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII} -characters in strings are unconditionally printed as backslash sequences -by the print functions @code{prin1} and @code{print} that print with -quoting. - -Those functions also use backslash sequences for multibyte -non-@acronym{ASCII} characters, regardless of the value of this variable, -when the output stream is a unibyte buffer or a marker pointing into -one. -@end defvar - -@defvar print-length -@cindex printing limits -The value of this variable is the maximum number of elements to print in -any list, vector or bool-vector. If an object being printed has more -than this many elements, it is abbreviated with an ellipsis. - -If the value is @code{nil} (the default), then there is no limit. - -@example -@group -(setq print-length 2) - @result{} 2 -@end group -@group -(print '(1 2 3 4 5)) - @print{} (1 2 ...) - @result{} (1 2 ...) -@end group -@end example -@end defvar - -@defvar print-level -The value of this variable is the maximum depth of nesting of -parentheses and brackets when printed. Any list or vector at a depth -exceeding this limit is abbreviated with an ellipsis. A value of -@code{nil} (which is the default) means no limit. -@end defvar - -@defopt eval-expression-print-length -@defoptx eval-expression-print-level -These are the values for @code{print-length} and @code{print-level} -used by @code{eval-expression}, and thus, indirectly, by many -interactive evaluation commands (@pxref{Lisp Eval,, Evaluating -Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}). -@end defopt - - These variables are used for detecting and reporting circular -and shared structure: - -@defvar print-circle -If non-@code{nil}, this variable enables detection of circular -and shared structure in printing. -@end defvar - -@defvar print-gensym -If non-@code{nil}, this variable enables detection of uninterned symbols -(@pxref{Creating Symbols}) in printing. When this is enabled, -uninterned symbols print with the prefix @samp{#:}, which tells the Lisp -reader to produce an uninterned symbol. -@end defvar - -@defvar print-continuous-numbering -If non-@code{nil}, that means number continuously across print calls. -This affects the numbers printed for @samp{#@var{n}=} labels and -@samp{#@var{m}#} references. - -Don't set this variable with @code{setq}; you should only bind it -temporarily to @code{t} with @code{let}. When you do that, you should -also bind @code{print-number-table} to @code{nil}. -@end defvar - -@defvar print-number-table -This variable holds a vector used internally by printing to implement -the @code{print-circle} feature. You should not use it except -to bind it to @code{nil} when you bind @code{print-continuous-numbering}. -@end defvar - -@defvar float-output-format -This variable specifies how to print floating point numbers. Its -default value is @code{nil}, meaning use the shortest output -that represents the number without losing information. - -To control output format more precisely, you can put a string in this -variable. The string should hold a @samp{%}-specification to be used -in the C function @code{sprintf}. For further restrictions on what -you can use, see the variable's documentation string. -@end defvar - -@ignore - arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434 -@end ignore diff --git a/lispref/strings.texi b/lispref/strings.texi deleted file mode 100644 index af5a2fa14d3..00000000000 --- a/lispref/strings.texi +++ /dev/null @@ -1,1163 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/strings -@node Strings and Characters, Lists, Numbers, Top -@comment node-name, next, previous, up -@chapter Strings and Characters -@cindex strings -@cindex character arrays -@cindex characters -@cindex bytes - - A string in Emacs Lisp is an array that contains an ordered sequence -of characters. Strings are used as names of symbols, buffers, and -files; to send messages to users; to hold text being copied between -buffers; and for many other purposes. Because strings are so important, -Emacs Lisp has many functions expressly for manipulating them. Emacs -Lisp programs use strings more often than individual characters. - - @xref{Strings of Events}, for special considerations for strings of -keyboard character events. - -@menu -* Basics: 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 to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. -@end menu - -@node String Basics -@section String and Character Basics - - Characters are represented in Emacs Lisp as integers; -whether an integer is a character or not is determined only by how it is -used. Thus, strings really contain integers. - - The length of a string (like any array) is fixed, and cannot be -altered once the string exists. Strings in Lisp are @emph{not} -terminated by a distinguished character code. (By contrast, strings in -C are terminated by a character with @acronym{ASCII} code 0.) - - Since strings are arrays, and therefore sequences as well, you can -operate on them with the general array and sequence functions. -(@xref{Sequences Arrays Vectors}.) For example, you can access or -change individual characters in a string using the functions @code{aref} -and @code{aset} (@pxref{Array Functions}). - - There are two text representations for non-@acronym{ASCII} characters in -Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text -Representations}). An @acronym{ASCII} character always occupies one byte in a -string; in fact, when a string is all @acronym{ASCII}, there is no real -difference between the unibyte and multibyte representations. -For most Lisp programming, you don't need to be concerned with these two -representations. - - Sometimes key sequences are represented as strings. When a string is -a key sequence, string elements in the range 128 to 255 represent meta -characters (which are large integers) rather than character -codes in the range 128 to 255. - - Strings cannot hold characters that have the hyper, super or alt -modifiers; they can hold @acronym{ASCII} control characters, but no other -control characters. They do not distinguish case in @acronym{ASCII} control -characters. If you want to store such characters in a sequence, such as -a key sequence, you must use a vector instead of a string. -@xref{Character Type}, for more information about the representation of meta -and other modifiers for keyboard input characters. - - Strings are useful for holding regular expressions. You can also -match regular expressions against strings with @code{string-match} -(@pxref{Regexp Search}). The functions @code{match-string} -(@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing -Match}) are useful for decomposing and modifying strings after -matching regular expressions against them. - - Like a buffer, a string can contain text properties for the characters -in it, as well as the characters themselves. @xref{Text Properties}. -All the Lisp primitives that copy text from strings to buffers or other -strings also copy the properties of the characters being copied. - - @xref{Text}, for information about functions that display strings or -copy them into buffers. @xref{Character Type}, and @ref{String Type}, -for information about the syntax of characters and strings. -@xref{Non-ASCII Characters}, for functions to convert between text -representations and to encode and decode character codes. - -@node Predicates for Strings -@section The Predicates for Strings - -For more information about general sequence and array predicates, -see @ref{Sequences Arrays Vectors}, and @ref{Arrays}. - -@defun stringp object -This function returns @code{t} if @var{object} is a string, @code{nil} -otherwise. -@end defun - -@defun string-or-null-p object -This function returns @code{t} if @var{object} is a string or nil, -@code{nil} otherwise. -@end defun - -@defun char-or-string-p object -This function returns @code{t} if @var{object} is a string or a -character (i.e., an integer), @code{nil} otherwise. -@end defun - -@node Creating Strings -@section Creating Strings - - The following functions create strings, either from scratch, or by -putting strings together, or by taking them apart. - -@defun make-string count character -This function returns a string made up of @var{count} repetitions of -@var{character}. If @var{count} is negative, an error is signaled. - -@example -(make-string 5 ?x) - @result{} "xxxxx" -(make-string 0 ?x) - @result{} "" -@end example - - Other functions to compare with this one include @code{char-to-string} -(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and -@code{make-list} (@pxref{Building Lists}). -@end defun - -@defun string &rest characters -This returns a string containing the characters @var{characters}. - -@example -(string ?a ?b ?c) - @result{} "abc" -@end example -@end defun - -@defun substring string start &optional end -This function returns a new string which consists of those characters -from @var{string} in the range from (and including) the character at the -index @var{start} up to (but excluding) the character at the index -@var{end}. The first character is at index zero. - -@example -@group -(substring "abcdefg" 0 3) - @result{} "abc" -@end group -@end example - -@noindent -Here the index for @samp{a} is 0, the index for @samp{b} is 1, and the -index for @samp{c} is 2. Thus, three letters, @samp{abc}, are copied -from the string @code{"abcdefg"}. The index 3 marks the character -position up to which the substring is copied. The character whose index -is 3 is actually the fourth character in the string. - -A negative number counts from the end of the string, so that @minus{}1 -signifies the index of the last character of the string. For example: - -@example -@group -(substring "abcdefg" -3 -1) - @result{} "ef" -@end group -@end example - -@noindent -In this example, the index for @samp{e} is @minus{}3, the index for -@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1. -Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded. - -When @code{nil} is used for @var{end}, it stands for the length of the -string. Thus, - -@example -@group -(substring "abcdefg" -3 nil) - @result{} "efg" -@end group -@end example - -Omitting the argument @var{end} is equivalent to specifying @code{nil}. -It follows that @code{(substring @var{string} 0)} returns a copy of all -of @var{string}. - -@example -@group -(substring "abcdefg" 0) - @result{} "abcdefg" -@end group -@end example - -@noindent -But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence -Functions}). - -If the characters copied from @var{string} have text properties, the -properties are copied into the new string also. @xref{Text Properties}. - -@code{substring} also accepts a vector for the first argument. -For example: - -@example -(substring [a b (c) "d"] 1 3) - @result{} [b (c)] -@end example - -A @code{wrong-type-argument} error is signaled if @var{start} is not -an integer or if @var{end} is neither an integer nor @code{nil}. An -@code{args-out-of-range} error is signaled if @var{start} indicates a -character following @var{end}, or if either integer is out of range -for @var{string}. - -Contrast this function with @code{buffer-substring} (@pxref{Buffer -Contents}), which returns a string containing a portion of the text in -the current buffer. The beginning of a string is at index 0, but the -beginning of a buffer is at index 1. -@end defun - -@defun substring-no-properties string &optional start end -This works like @code{substring} but discards all text properties from -the value. Also, @var{start} may be omitted or @code{nil}, which is -equivalent to 0. Thus, @w{@code{(substring-no-properties -@var{string})}} returns a copy of @var{string}, with all text -properties removed. -@end defun - -@defun concat &rest sequences -@cindex copying strings -@cindex concatenating strings -This function returns a new string consisting of the characters in the -arguments passed to it (along with their text properties, if any). The -arguments may be strings, lists of numbers, or vectors of numbers; they -are not themselves changed. If @code{concat} receives no arguments, it -returns an empty string. - -@example -(concat "abc" "-def") - @result{} "abc-def" -(concat "abc" (list 120 121) [122]) - @result{} "abcxyz" -;; @r{@code{nil} is an empty sequence.} -(concat "abc" nil "-def") - @result{} "abc-def" -(concat "The " "quick brown " "fox.") - @result{} "The quick brown fox." -(concat) - @result{} "" -@end example - -@noindent -The @code{concat} function always constructs a new string that is -not @code{eq} to any existing string. - -In Emacs versions before 21, when an argument was an integer (not a -sequence of integers), it was converted to a string of digits making up -the decimal printed representation of the integer. This obsolete usage -no longer works. The proper way to convert an integer to its decimal -printed form is with @code{format} (@pxref{Formatting Strings}) or -@code{number-to-string} (@pxref{String Conversion}). - -For information about other concatenation functions, see the -description of @code{mapconcat} in @ref{Mapping Functions}, -@code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building -Lists}. -@end defun - -@defun split-string string &optional separators omit-nulls -This function splits @var{string} into substrings at matches for the -regular expression @var{separators}. Each match for @var{separators} -defines a splitting point; the substrings between the splitting points -are made into a list, which is the value returned by -@code{split-string}. - -If @var{omit-nulls} is @code{nil}, the result contains null strings -whenever there are two consecutive matches for @var{separators}, or a -match is adjacent to the beginning or end of @var{string}. If -@var{omit-nulls} is @code{t}, these null strings are omitted from the -result. - -If @var{separators} is @code{nil} (or omitted), -the default is the value of @code{split-string-default-separators}. - -As a special case, when @var{separators} is @code{nil} (or omitted), -null strings are always omitted from the result. Thus: - -@example -(split-string " two words ") - @result{} ("two" "words") -@end example - -The result is not @code{("" "two" "words" "")}, which would rarely be -useful. If you need such a result, use an explicit value for -@var{separators}: - -@example -(split-string " two words " - split-string-default-separators) - @result{} ("" "two" "words" "") -@end example - -More examples: - -@example -(split-string "Soup is good food" "o") - @result{} ("S" "up is g" "" "d f" "" "d") -(split-string "Soup is good food" "o" t) - @result{} ("S" "up is g" "d f" "d") -(split-string "Soup is good food" "o+") - @result{} ("S" "up is g" "d f" "d") -@end example - -Empty matches do count, except that @code{split-string} will not look -for a final empty match when it already reached the end of the string -using a non-empty match or when @var{string} is empty: - -@example -(split-string "aooob" "o*") - @result{} ("" "a" "" "b" "") -(split-string "ooaboo" "o*") - @result{} ("" "" "a" "b" "") -(split-string "" "") - @result{} ("") -@end example - -However, when @var{separators} can match the empty string, -@var{omit-nulls} is usually @code{t}, so that the subtleties in the -three previous examples are rarely relevant: - -@example -(split-string "Soup is good food" "o*" t) - @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d") -(split-string "Nice doggy!" "" t) - @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!") -(split-string "" "" t) - @result{} nil -@end example - -Somewhat odd, but predictable, behavior can occur for certain -``non-greedy'' values of @var{separators} that can prefer empty -matches over non-empty matches. Again, such values rarely occur in -practice: - -@example -(split-string "ooo" "o*" t) - @result{} nil -(split-string "ooo" "\\|o+" t) - @result{} ("o" "o" "o") -@end example -@end defun - -@defvar split-string-default-separators -The default value of @var{separators} for @code{split-string}. Its -usual value is @w{@code{"[ \f\t\n\r\v]+"}}. -@end defvar - -@node Modifying Strings -@section Modifying Strings - - The most basic way to alter the contents of an existing string is with -@code{aset} (@pxref{Array Functions}). @code{(aset @var{string} -@var{idx} @var{char})} stores @var{char} into @var{string} at index -@var{idx}. Each character occupies one or more bytes, and if @var{char} -needs a different number of bytes from the character already present at -that index, @code{aset} signals an error. - - A more powerful function is @code{store-substring}: - -@defun store-substring string idx obj -This function alters part of the contents of the string @var{string}, by -storing @var{obj} starting at index @var{idx}. The argument @var{obj} -may be either a character or a (smaller) string. - -Since it is impossible to change the length of an existing string, it is -an error if @var{obj} doesn't fit within @var{string}'s actual length, -or if any new character requires a different number of bytes from the -character currently present at that point in @var{string}. -@end defun - - To clear out a string that contained a password, use -@code{clear-string}: - -@defun clear-string string -This makes @var{string} a unibyte string and clears its contents to -zeros. It may also change @var{string}'s length. -@end defun - -@need 2000 -@node Text Comparison -@section Comparison of Characters and Strings -@cindex string equality - -@defun char-equal character1 character2 -This function returns @code{t} if the arguments represent the same -character, @code{nil} otherwise. This function ignores differences -in case if @code{case-fold-search} is non-@code{nil}. - -@example -(char-equal ?x ?x) - @result{} t -(let ((case-fold-search nil)) - (char-equal ?x ?X)) - @result{} nil -@end example -@end defun - -@defun string= string1 string2 -This function returns @code{t} if the characters of the two strings -match exactly. Symbols are also allowed as arguments, in which case -their print names are used. -Case is always significant, regardless of @code{case-fold-search}. - -@example -(string= "abc" "abc") - @result{} t -(string= "abc" "ABC") - @result{} nil -(string= "ab" "ABC") - @result{} nil -@end example - -The function @code{string=} ignores the text properties of the two -strings. When @code{equal} (@pxref{Equality Predicates}) compares two -strings, it uses @code{string=}. - -For technical reasons, a unibyte and a multibyte string are -@code{equal} if and only if they contain the same sequence of -character codes and all these codes are either in the range 0 through -127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). -However, when a unibyte string gets converted to a multibyte string, -all characters with codes in the range 160 through 255 get converted -to characters with higher codes, whereas @acronym{ASCII} characters -remain unchanged. Thus, a unibyte string and its conversion to -multibyte are only @code{equal} if the string is all @acronym{ASCII}. -Character codes 160 through 255 are not entirely proper in multibyte -text, even though they can occur. As a consequence, the situation -where a unibyte and a multibyte string are @code{equal} without both -being all @acronym{ASCII} is a technical oddity that very few Emacs -Lisp programmers ever get confronted with. @xref{Text -Representations}. -@end defun - -@defun string-equal string1 string2 -@code{string-equal} is another name for @code{string=}. -@end defun - -@cindex lexical comparison -@defun string< string1 string2 -@c (findex string< causes problems for permuted index!!) -This function compares two strings a character at a time. It -scans both the strings at the same time to find the first pair of corresponding -characters that do not match. If the lesser character of these two is -the character from @var{string1}, then @var{string1} is less, and this -function returns @code{t}. If the lesser character is the one from -@var{string2}, then @var{string1} is greater, and this function returns -@code{nil}. If the two strings match entirely, the value is @code{nil}. - -Pairs of characters are compared according to their character codes. -Keep in mind that lower case letters have higher numeric values in the -@acronym{ASCII} character set than their upper case counterparts; digits and -many punctuation characters have a lower numeric value than upper case -letters. An @acronym{ASCII} character is less than any non-@acronym{ASCII} -character; a unibyte non-@acronym{ASCII} character is always less than any -multibyte non-@acronym{ASCII} character (@pxref{Text Representations}). - -@example -@group -(string< "abc" "abd") - @result{} t -(string< "abd" "abc") - @result{} nil -(string< "123" "abc") - @result{} t -@end group -@end example - -When the strings have different lengths, and they match up to the -length of @var{string1}, then the result is @code{t}. If they match up -to the length of @var{string2}, the result is @code{nil}. A string of -no characters is less than any other string. - -@example -@group -(string< "" "abc") - @result{} t -(string< "ab" "abc") - @result{} t -(string< "abc" "") - @result{} nil -(string< "abc" "ab") - @result{} nil -(string< "" "") - @result{} nil -@end group -@end example - -Symbols are also allowed as arguments, in which case their print names -are used. -@end defun - -@defun string-lessp string1 string2 -@code{string-lessp} is another name for @code{string<}. -@end defun - -@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case -This function compares the specified part of @var{string1} with the -specified part of @var{string2}. The specified part of @var{string1} -runs from index @var{start1} up to index @var{end1} (@code{nil} means -the end of the string). The specified part of @var{string2} runs from -index @var{start2} up to index @var{end2} (@code{nil} means the end of -the string). - -The strings are both converted to multibyte for the comparison -(@pxref{Text Representations}) so that a unibyte string and its -conversion to multibyte are always regarded as equal. If -@var{ignore-case} is non-@code{nil}, then case is ignored, so that -upper case letters can be equal to lower case letters. - -If the specified portions of the two strings match, the value is -@code{t}. Otherwise, the value is an integer which indicates how many -leading characters agree, and which string is less. Its absolute value -is one plus the number of characters that agree at the beginning of the -two strings. The sign is negative if @var{string1} (or its specified -portion) is less. -@end defun - -@defun assoc-string key alist &optional case-fold -This function works like @code{assoc}, except that @var{key} must be a -string or symbol, and comparison is done using @code{compare-strings}. -Symbols are converted to strings before testing. -If @var{case-fold} is non-@code{nil}, it ignores case differences. -Unlike @code{assoc}, this function can also match elements of the alist -that are strings or symbols rather than conses. In particular, @var{alist} can -be a list of strings or symbols rather than an actual alist. -@xref{Association Lists}. -@end defun - - See also the @code{compare-buffer-substrings} function in -@ref{Comparing Text}, for a way to compare text in buffers. The -function @code{string-match}, which matches a regular expression -against a string, can be used for a kind of string comparison; see -@ref{Regexp Search}. - -@node String Conversion -@comment node-name, next, previous, up -@section Conversion of Characters and Strings -@cindex conversion of strings - - This section describes functions for conversions between characters, -strings and integers. @code{format} (@pxref{Formatting Strings}) -and @code{prin1-to-string} -(@pxref{Output Functions}) can also convert Lisp objects into strings. -@code{read-from-string} (@pxref{Input Functions}) can ``convert'' a -string representation of a Lisp object into an object. The functions -@code{string-make-multibyte} and @code{string-make-unibyte} convert the -text representation of a string (@pxref{Converting Representations}). - - @xref{Documentation}, for functions that produce textual descriptions -of text characters and general input events -(@code{single-key-description} and @code{text-char-description}). These -are used primarily for making help messages. - -@defun char-to-string character -@cindex character to string -This function returns a new string containing one character, -@var{character}. This function is semi-obsolete because the function -@code{string} is more general. @xref{Creating Strings}. -@end defun - -@defun string-to-char string -@cindex string to character - This function returns the first character in @var{string}. If the -string is empty, the function returns 0. The value is also 0 when the -first character of @var{string} is the null character, @acronym{ASCII} code -0. - -@example -(string-to-char "ABC") - @result{} 65 - -(string-to-char "xyz") - @result{} 120 -(string-to-char "") - @result{} 0 -@group -(string-to-char "\000") - @result{} 0 -@end group -@end example - -This function may be eliminated in the future if it does not seem useful -enough to retain. -@end defun - -@defun number-to-string number -@cindex integer to string -@cindex integer to decimal -This function returns a string consisting of the printed base-ten -representation of @var{number}, which may be an integer or a floating -point number. The returned value starts with a minus sign if the argument is -negative. - -@example -(number-to-string 256) - @result{} "256" -@group -(number-to-string -23) - @result{} "-23" -@end group -(number-to-string -23.5) - @result{} "-23.5" -@end example - -@cindex int-to-string -@code{int-to-string} is a semi-obsolete alias for this function. - -See also the function @code{format} in @ref{Formatting Strings}. -@end defun - -@defun string-to-number string &optional base -@cindex string to number -This function returns the numeric value of the characters in -@var{string}. If @var{base} is non-@code{nil}, it must be an integer -between 2 and 16 (inclusive), and integers are converted in that base. -If @var{base} is @code{nil}, then base ten is used. Floating point -conversion only works in base ten; we have not implemented other -radices for floating point numbers, because that would be much more -work and does not seem useful. If @var{string} looks like an integer -but its value is too large to fit into a Lisp integer, -@code{string-to-number} returns a floating point result. - -The parsing skips spaces and tabs at the beginning of @var{string}, -then reads as much of @var{string} as it can interpret as a number in -the given base. (On some systems it ignores other whitespace at the -beginning, not just spaces and tabs.) If the first character after -the ignored whitespace is neither a digit in the given base, nor a -plus or minus sign, nor the leading dot of a floating point number, -this function returns 0. - -@example -(string-to-number "256") - @result{} 256 -(string-to-number "25 is a perfect square.") - @result{} 25 -(string-to-number "X256") - @result{} 0 -(string-to-number "-4.5") - @result{} -4.5 -(string-to-number "1e5") - @result{} 100000.0 -@end example - -@findex string-to-int -@code{string-to-int} is an obsolete alias for this function. -@end defun - - Here are some other functions that can convert to or from a string: - -@table @code -@item concat -@code{concat} can convert a vector or a list into a string. -@xref{Creating Strings}. - -@item vconcat -@code{vconcat} can convert a string into a vector. @xref{Vector -Functions}. - -@item append -@code{append} can convert a string into a list. @xref{Building Lists}. -@end table - -@node Formatting Strings -@comment node-name, next, previous, up -@section Formatting Strings -@cindex formatting strings -@cindex strings, formatting them - - @dfn{Formatting} means constructing a string by substitution of -computed values at various places in a constant string. This constant string -controls how the other values are printed, as well as where they appear; -it is called a @dfn{format string}. - - Formatting is often useful for computing messages to be displayed. In -fact, the functions @code{message} and @code{error} provide the same -formatting feature described here; they differ from @code{format} only -in how they use the result of formatting. - -@defun format string &rest objects -This function returns a new string that is made by copying -@var{string} and then replacing any format specification -in the copy with encodings of the corresponding @var{objects}. The -arguments @var{objects} are the computed values to be formatted. - -The characters in @var{string}, other than the format specifications, -are copied directly into the output, including their text properties, -if any. -@end defun - -@cindex @samp{%} in format -@cindex format specification - A format specification is a sequence of characters beginning with a -@samp{%}. Thus, if there is a @samp{%d} in @var{string}, the -@code{format} function replaces it with the printed representation of -one of the values to be formatted (one of the arguments @var{objects}). -For example: - -@example -@group -(format "The value of fill-column is %d." fill-column) - @result{} "The value of fill-column is 72." -@end group -@end example - - Since @code{format} interprets @samp{%} characters as format -specifications, you should @emph{never} pass an arbitrary string as -the first argument. This is particularly true when the string is -generated by some Lisp code. Unless the string is @emph{known} to -never include any @samp{%} characters, pass @code{"%s"}, described -below, as the first argument, and the string as the second, like this: - -@example - (format "%s" @var{arbitrary-string}) -@end example - - If @var{string} contains more than one format specification, the -format specifications correspond to successive values from -@var{objects}. Thus, the first format specification in @var{string} -uses the first such value, the second format specification uses the -second such value, and so on. Any extra format specifications (those -for which there are no corresponding values) cause an error. Any -extra values to be formatted are ignored. - - Certain format specifications require values of particular types. If -you supply a value that doesn't fit the requirements, an error is -signaled. - - Here is a table of valid format specifications: - -@table @samp -@item %s -Replace the specification with the printed representation of the object, -made without quoting (that is, using @code{princ}, not -@code{prin1}---@pxref{Output Functions}). Thus, strings are represented -by their contents alone, with no @samp{"} characters, and symbols appear -without @samp{\} characters. - -If the object is a string, its text properties are -copied into the output. The text properties of the @samp{%s} itself -are also copied, but those of the object take priority. - -@item %S -Replace the specification with the printed representation of the object, -made with quoting (that is, using @code{prin1}---@pxref{Output -Functions}). Thus, strings are enclosed in @samp{"} characters, and -@samp{\} characters appear where necessary before special characters. - -@item %o -@cindex integer to octal -Replace the specification with the base-eight representation of an -integer. - -@item %d -Replace the specification with the base-ten representation of an -integer. - -@item %x -@itemx %X -@cindex integer to hexadecimal -Replace the specification with the base-sixteen representation of an -integer. @samp{%x} uses lower case and @samp{%X} uses upper case. - -@item %c -Replace the specification with the character which is the value given. - -@item %e -Replace the specification with the exponential notation for a floating -point number. - -@item %f -Replace the specification with the decimal-point notation for a floating -point number. - -@item %g -Replace the specification with notation for a floating point number, -using either exponential notation or decimal-point notation, whichever -is shorter. - -@item %% -Replace the specification with a single @samp{%}. This format -specification is unusual in that it does not use a value. For example, -@code{(format "%% %d" 30)} returns @code{"% 30"}. -@end table - - Any other format character results in an @samp{Invalid format -operation} error. - - Here are several examples: - -@example -@group -(format "The name of this buffer is %s." (buffer-name)) - @result{} "The name of this buffer is strings.texi." - -(format "The buffer object prints as %s." (current-buffer)) - @result{} "The buffer object prints as strings.texi." - -(format "The octal value of %d is %o, - and the hex value is %x." 18 18 18) - @result{} "The octal value of 18 is 22, - and the hex value is 12." -@end group -@end example - -@cindex field width -@cindex padding - A specification can have a @dfn{width}, which is a signed decimal -number between the @samp{%} and the specification character. If the -printed representation of the object contains fewer characters than -this width, @code{format} extends it with padding. The padding goes -on the left if the width is positive (or starts with zero) and on the -right if the width is negative. The padding character is normally a -space, but it's @samp{0} if the width starts with a zero. - - Some of these conventions are ignored for specification characters -for which they do not make sense. That is, @samp{%s}, @samp{%S} and -@samp{%c} accept a width starting with 0, but still pad with -@emph{spaces} on the left. Also, @samp{%%} accepts a width, but -ignores it. Here are some examples of padding: - -@example -(format "%06d is padded on the left with zeros" 123) - @result{} "000123 is padded on the left with zeros" - -(format "%-6d is padded on the right" 123) - @result{} "123 is padded on the right" -@end example - -@noindent -If the width is too small, @code{format} does not truncate the -object's printed representation. Thus, you can use a width to specify -a minimum spacing between columns with no risk of losing information. - - In the following three examples, @samp{%7s} specifies a minimum -width of 7. In the first case, the string inserted in place of -@samp{%7s} has only 3 letters, it needs 4 blank spaces as padding. In -the second case, the string @code{"specification"} is 13 letters wide -but is not truncated. In the third case, the padding is on the right. - -@smallexample -@group -(format "The word `%7s' actually has %d letters in it." - "foo" (length "foo")) - @result{} "The word ` foo' actually has 3 letters in it." -@end group - -@group -(format "The word `%7s' actually has %d letters in it." - "specification" (length "specification")) - @result{} "The word `specification' actually has 13 letters in it." -@end group - -@group -(format "The word `%-7s' actually has %d letters in it." - "foo" (length "foo")) - @result{} "The word `foo ' actually has 3 letters in it." -@end group -@end smallexample - -@cindex precision in format specifications - All the specification characters allow an optional @dfn{precision} -before the character (after the width, if present). The precision is -a decimal-point @samp{.} followed by a digit-string. For the -floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the -precision specifies how many decimal places to show; if zero, the -decimal-point itself is also omitted. For @samp{%s} and @samp{%S}, -the precision truncates the string to the given width, so @samp{%.3s} -shows only the first three characters of the representation for -@var{object}. Precision has no effect for other specification -characters. - -@cindex flags in format specifications - Immediately after the @samp{%} and before the optional width and -precision, you can put certain ``flag'' characters. - - @samp{+} as a flag inserts a plus sign before a positive number, so -that it always has a sign. A space character as flag inserts a space -before a positive number. (Otherwise, positive numbers start with the -first digit.) Either of these two flags ensures that positive numbers -and negative numbers use the same number of columns. These flags are -ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if -both flags are used, the @samp{+} takes precedence. - - The flag @samp{#} specifies an ``alternate form'' which depends on -the format in use. For @samp{%o} it ensures that the result begins -with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result -with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g}, -the @samp{#} flag means include a decimal point even if the precision -is zero. - -@node Case Conversion -@comment node-name, next, previous, up -@section Case Conversion in Lisp -@cindex upper case -@cindex lower case -@cindex character case -@cindex case conversion in Lisp - - The character case functions change the case of single characters or -of the contents of strings. The functions normally convert only -alphabetic characters (the letters @samp{A} through @samp{Z} and -@samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other -characters are not altered. You can specify a different case -conversion mapping by specifying a case table (@pxref{Case Tables}). - - These functions do not modify the strings that are passed to them as -arguments. - - The examples below use the characters @samp{X} and @samp{x} which have -@acronym{ASCII} codes 88 and 120 respectively. - -@defun downcase string-or-char -This function converts a character or a string to lower case. - -When the argument to @code{downcase} is a string, the function creates -and returns a new string in which each letter in the argument that is -upper case is converted to lower case. When the argument to -@code{downcase} is a character, @code{downcase} returns the -corresponding lower case character. This value is an integer. If the -original character is lower case, or is not a letter, then the value -equals the original character. - -@example -(downcase "The cat in the hat") - @result{} "the cat in the hat" - -(downcase ?X) - @result{} 120 -@end example -@end defun - -@defun upcase string-or-char -This function converts a character or a string to upper case. - -When the argument to @code{upcase} is a string, the function creates -and returns a new string in which each letter in the argument that is -lower case is converted to upper case. - -When the argument to @code{upcase} is a character, @code{upcase} -returns the corresponding upper case character. This value is an integer. -If the original character is upper case, or is not a letter, then the -value returned equals the original character. - -@example -(upcase "The cat in the hat") - @result{} "THE CAT IN THE HAT" - -(upcase ?x) - @result{} 88 -@end example -@end defun - -@defun capitalize string-or-char -@cindex capitalization -This function capitalizes strings or characters. If -@var{string-or-char} is a string, the function creates and returns a new -string, whose contents are a copy of @var{string-or-char} in which each -word has been capitalized. This means that the first character of each -word is converted to upper case, and the rest are converted to lower -case. - -The definition of a word is any sequence of consecutive characters that -are assigned to the word constituent syntax class in the current syntax -table (@pxref{Syntax Class Table}). - -When the argument to @code{capitalize} is a character, @code{capitalize} -has the same result as @code{upcase}. - -@example -@group -(capitalize "The cat in the hat") - @result{} "The Cat In The Hat" -@end group - -@group -(capitalize "THE 77TH-HATTED CAT") - @result{} "The 77th-Hatted Cat" -@end group - -@group -(capitalize ?x) - @result{} 88 -@end group -@end example -@end defun - -@defun upcase-initials string-or-char -If @var{string-or-char} is a string, this function capitalizes the -initials of the words in @var{string-or-char}, without altering any -letters other than the initials. It returns a new string whose -contents are a copy of @var{string-or-char}, in which each word has -had its initial letter converted to upper case. - -The definition of a word is any sequence of consecutive characters that -are assigned to the word constituent syntax class in the current syntax -table (@pxref{Syntax Class Table}). - -When the argument to @code{upcase-initials} is a character, -@code{upcase-initials} has the same result as @code{upcase}. - -@example -@group -(upcase-initials "The CAT in the hAt") - @result{} "The CAT In The HAt" -@end group -@end example -@end defun - - @xref{Text Comparison}, for functions that compare strings; some of -them ignore case differences, or can optionally ignore case differences. - -@node Case Tables -@section The Case Table - - You can customize case conversion by installing a special @dfn{case -table}. A case table specifies the mapping between upper case and lower -case letters. It affects both the case conversion functions for Lisp -objects (see the previous section) and those that apply to text in the -buffer (@pxref{Case Changes}). Each buffer has a case table; there is -also a standard case table which is used to initialize the case table -of new buffers. - - A case table is a char-table (@pxref{Char-Tables}) whose subtype is -@code{case-table}. This char-table maps each character into the -corresponding lower case character. It has three extra slots, which -hold related tables: - -@table @var -@item upcase -The upcase table maps each character into the corresponding upper -case character. -@item canonicalize -The canonicalize table maps all of a set of case-related characters -into a particular member of that set. -@item equivalences -The equivalences table maps each one of a set of case-related characters -into the next character in that set. -@end table - - In simple cases, all you need to specify is the mapping to lower-case; -the three related tables will be calculated automatically from that one. - - For some languages, upper and lower case letters are not in one-to-one -correspondence. There may be two different lower case letters with the -same upper case equivalent. In these cases, you need to specify the -maps for both lower case and upper case. - - The extra table @var{canonicalize} maps each character to a canonical -equivalent; any two characters that are related by case-conversion have -the same canonical equivalent character. For example, since @samp{a} -and @samp{A} are related by case-conversion, they should have the same -canonical equivalent character (which should be either @samp{a} for both -of them, or @samp{A} for both of them). - - The extra table @var{equivalences} is a map that cyclically permutes -each equivalence class (of characters with the same canonical -equivalent). (For ordinary @acronym{ASCII}, this would map @samp{a} into -@samp{A} and @samp{A} into @samp{a}, and likewise for each set of -equivalent characters.) - - When you construct a case table, you can provide @code{nil} for -@var{canonicalize}; then Emacs fills in this slot from the lower case -and upper case mappings. You can also provide @code{nil} for -@var{equivalences}; then Emacs fills in this slot from -@var{canonicalize}. In a case table that is actually in use, those -components are non-@code{nil}. Do not try to specify @var{equivalences} -without also specifying @var{canonicalize}. - - Here are the functions for working with case tables: - -@defun case-table-p object -This predicate returns non-@code{nil} if @var{object} is a valid case -table. -@end defun - -@defun set-standard-case-table table -This function makes @var{table} the standard case table, so that it will -be used in any buffers created subsequently. -@end defun - -@defun standard-case-table -This returns the standard case table. -@end defun - -@defun current-case-table -This function returns the current buffer's case table. -@end defun - -@defun set-case-table table -This sets the current buffer's case table to @var{table}. -@end defun - -@defmac with-case-table table body@dots{} -The @code{with-case-table} macro saves the current case table, makes -@var{table} the current case table, evaluates the @var{body} forms, -and finally restores the case table. The return value is the value of -the last form in @var{body}. The case table is restored even in case -of an abnormal exit via @code{throw} or error (@pxref{Nonlocal -Exits}). -@end defmac - - Some language environments may modify the case conversions of -@acronym{ASCII} characters; for example, in the Turkish language -environment, the @acronym{ASCII} character @samp{I} is downcased into -a Turkish ``dotless i''. This can interfere with code that requires -ordinary ASCII case conversion, such as implementations of -@acronym{ASCII}-based network protocols. In that case, use the -@code{with-case-table} macro with the variable @var{ascii-case-table}, -which stores the unmodified case table for the @acronym{ASCII} -character set. - -@defvar ascii-case-table -The case table for the @acronym{ASCII} character set. This should not be -modified by any language environment settings. -@end defvar - - The following three functions are convenient subroutines for packages -that define non-@acronym{ASCII} character sets. They modify the specified -case table @var{case-table}; they also modify the standard syntax table. -@xref{Syntax Tables}. Normally you would use these functions to change -the standard case table. - -@defun set-case-syntax-pair uc lc case-table -This function specifies a pair of corresponding letters, one upper case -and one lower case. -@end defun - -@defun set-case-syntax-delims l r case-table -This function makes characters @var{l} and @var{r} a matching pair of -case-invariant delimiters. -@end defun - -@defun set-case-syntax char syntax case-table -This function makes @var{char} case-invariant, with syntax -@var{syntax}. -@end defun - -@deffn Command describe-buffer-case-table -This command displays a description of the contents of the current -buffer's case table. -@end deffn - -@ignore - arch-tag: 700b8e95-7aa5-4b52-9eb3-8f2e1ea152b4 -@end ignore diff --git a/lispref/symbols.texi b/lispref/symbols.texi deleted file mode 100644 index 7234a75bd59..00000000000 --- a/lispref/symbols.texi +++ /dev/null @@ -1,598 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/symbols -@node Symbols, Evaluation, Hash Tables, Top -@chapter Symbols -@cindex symbol - - A @dfn{symbol} is an object with a unique name. This chapter -describes symbols, their components, their property lists, and how they -are created and interned. Separate chapters describe the use of symbols -as variables and as function names; see @ref{Variables}, and -@ref{Functions}. For the precise read syntax for symbols, see -@ref{Symbol Type}. - - You can test whether an arbitrary Lisp object is a symbol -with @code{symbolp}: - -@defun symbolp object -This function returns @code{t} if @var{object} is a symbol, @code{nil} -otherwise. -@end defun - -@menu -* 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. -@end menu - -@node Symbol Components, Definitions, Symbols, Symbols -@section Symbol Components -@cindex symbol components - - Each symbol has four components (or ``cells''), each of which -references another object: - -@table @asis -@item Print name -@cindex print name cell -The @dfn{print name cell} holds a string that names the symbol for -reading and printing. See @code{symbol-name} in @ref{Creating Symbols}. - -@item Value -@cindex value cell -The @dfn{value cell} holds the current value of the symbol as a -variable. When a symbol is used as a form, the value of the form is the -contents of the symbol's value cell. See @code{symbol-value} in -@ref{Accessing Variables}. - -@item Function -@cindex function cell -The @dfn{function cell} holds the function definition of the symbol. -When a symbol is used as a function, its function definition is used in -its place. This cell is also used to make a symbol stand for a keymap -or a keyboard macro, for editor command execution. Because each symbol -has separate value and function cells, variables names and function names do -not conflict. See @code{symbol-function} in @ref{Function Cells}. - -@item Property list -@cindex property list cell -The @dfn{property list cell} holds the property list of the symbol. See -@code{symbol-plist} in @ref{Property Lists}. -@end table - - The print name cell always holds a string, and cannot be changed. The -other three cells can be set individually to any specified Lisp object. - - The print name cell holds the string that is the name of the symbol. -Since symbols are represented textually by their names, it is important -not to have two symbols with the same name. The Lisp reader ensures -this: every time it reads a symbol, it looks for an existing symbol with -the specified name before it creates a new one. (In GNU Emacs Lisp, -this lookup uses a hashing algorithm and an obarray; see @ref{Creating -Symbols}.) - - The value cell holds the symbol's value as a variable -(@pxref{Variables}). That is what you get if you evaluate the symbol as -a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate -value. Certain symbols have values that cannot be changed; these -include @code{nil} and @code{t}, and any symbol whose name starts with -@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}. - - We often refer to ``the function @code{foo}'' when we really mean -the function stored in the function cell of the symbol @code{foo}. We -make the distinction explicit only when necessary. In normal -usage, the function cell usually contains a function -(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the -Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard -macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and -autoload objects (@pxref{Autoloading}) are also sometimes stored in -the function cells of symbols. - - The property list cell normally should hold a correctly formatted -property list (@pxref{Property Lists}), as a number of functions expect -to see a property list there. - - The function cell or the value cell may be @dfn{void}, which means -that the cell does not reference any object. (This is not the same -thing as holding the symbol @code{void}, nor the same as holding the -symbol @code{nil}.) Examining a function or value cell that is void -results in an error, such as @samp{Symbol's value as variable is void}. - - The four functions @code{symbol-name}, @code{symbol-value}, -@code{symbol-plist}, and @code{symbol-function} return the contents of -the four cells of a symbol. Here as an example we show the contents of -the four cells of the symbol @code{buffer-file-name}: - -@example -(symbol-name 'buffer-file-name) - @result{} "buffer-file-name" -(symbol-value 'buffer-file-name) - @result{} "/gnu/elisp/symbols.texi" -(symbol-function 'buffer-file-name) - @result{} #<subr buffer-file-name> -(symbol-plist 'buffer-file-name) - @result{} (variable-documentation 29529) -@end example - -@noindent -Because this symbol is the variable which holds the name of the file -being visited in the current buffer, the value cell contents we see are -the name of the source file of this chapter of the Emacs Lisp Manual. -The property list cell contains the list @code{(variable-documentation -29529)} which tells the documentation functions where to find the -documentation string for the variable @code{buffer-file-name} in the -@file{DOC-@var{version}} file. (29529 is the offset from the beginning -of the @file{DOC-@var{version}} file to where that documentation string -begins---see @ref{Documentation Basics}.) The function cell contains -the function for returning the name of the file. -@code{buffer-file-name} names a primitive function, which has no read -syntax and prints in hash notation (@pxref{Primitive Function Type}). A -symbol naming a function written in Lisp would have a lambda expression -(or a byte-code object) in this cell. - -@node Definitions, Creating Symbols, Symbol Components, Symbols -@section Defining Symbols -@cindex definitions of symbols - - A @dfn{definition} in Lisp is a special form that announces your -intention to use a certain symbol in a particular way. In Emacs Lisp, -you can define a symbol as a variable, or define it as a function (or -macro), or both independently. - - A definition construct typically specifies a value or meaning for the -symbol for one kind of use, plus documentation for its meaning when used -in this way. Thus, when you define a symbol as a variable, you can -supply an initial value for the variable, plus documentation for the -variable. - - @code{defvar} and @code{defconst} are special forms that define a -symbol as a global variable. They are documented in detail in -@ref{Defining Variables}. For defining user option variables that can -be customized, use @code{defcustom} (@pxref{Customization}). - - @code{defun} defines a symbol as a function, creating a lambda -expression and storing it in the function cell of the symbol. This -lambda expression thus becomes the function definition of the symbol. -(The term ``function definition,'' meaning the contents of the function -cell, is derived from the idea that @code{defun} gives the symbol its -definition as a function.) @code{defsubst} and @code{defalias} are two -other ways of defining a function. @xref{Functions}. - - @code{defmacro} defines a symbol as a macro. It creates a macro -object and stores it in the function cell of the symbol. Note that a -given symbol can be a macro or a function, but not both at once, because -both macro and function definitions are kept in the function cell, and -that cell can hold only one Lisp object at any given time. -@xref{Macros}. - - In Emacs Lisp, a definition is not required in order to use a symbol -as a variable or function. Thus, you can make a symbol a global -variable with @code{setq}, whether you define it first or not. The real -purpose of definitions is to guide programmers and programming tools. -They inform programmers who read the code that certain symbols are -@emph{intended} to be used as variables, or as functions. In addition, -utilities such as @file{etags} and @file{make-docfile} recognize -definitions, and add appropriate information to tag tables and the -@file{DOC-@var{version}} file. @xref{Accessing Documentation}. - -@node Creating Symbols, Property Lists, Definitions, Symbols -@section Creating and Interning Symbols -@cindex reading symbols - - To understand how symbols are created in GNU Emacs Lisp, you must know -how Lisp reads them. Lisp must ensure that it finds the same symbol -every time it reads the same set of characters. Failure to do so would -cause complete confusion. - -@cindex symbol name hashing -@cindex hashing -@cindex obarray -@cindex bucket (in obarray) - When the Lisp reader encounters a symbol, it reads all the characters -of the name. Then it ``hashes'' those characters to find an index in a -table called an @dfn{obarray}. Hashing is an efficient method of -looking something up. For example, instead of searching a telephone -book cover to cover when looking up Jan Jones, you start with the J's -and go from there. That is a simple version of hashing. Each element -of the obarray is a @dfn{bucket} which holds all the symbols with a -given hash code; to look for a given name, it is sufficient to look -through all the symbols in the bucket for that name's hash code. (The -same idea is used for general Emacs hash tables, but they are a -different data type; see @ref{Hash Tables}.) - -@cindex interning - If a symbol with the desired name is found, the reader uses that -symbol. If the obarray does not contain a symbol with that name, the -reader makes a new symbol and adds it to the obarray. Finding or adding -a symbol with a certain name is called @dfn{interning} it, and the -symbol is then called an @dfn{interned symbol}. - - Interning ensures that each obarray has just one symbol with any -particular name. Other like-named symbols may exist, but not in the -same obarray. Thus, the reader gets the same symbols for the same -names, as long as you keep reading with the same obarray. - - Interning usually happens automatically in the reader, but sometimes -other programs need to do it. For example, after the @kbd{M-x} command -obtains the command name as a string using the minibuffer, it then -interns the string, to get the interned symbol with that name. - -@cindex symbol equality -@cindex uninterned symbol - No obarray contains all symbols; in fact, some symbols are not in any -obarray. They are called @dfn{uninterned symbols}. An uninterned -symbol has the same four cells as other symbols; however, the only way -to gain access to it is by finding it in some other object or as the -value of a variable. - - Creating an uninterned symbol is useful in generating Lisp code, -because an uninterned symbol used as a variable in the code you generate -cannot clash with any variables used in other Lisp programs. - - In Emacs Lisp, an obarray is actually a vector. Each element of the -vector is a bucket; its value is either an interned symbol whose name -hashes to that bucket, or 0 if the bucket is empty. Each interned -symbol has an internal link (invisible to the user) to the next symbol -in the bucket. Because these links are invisible, there is no way to -find all the symbols in an obarray except using @code{mapatoms} (below). -The order of symbols in a bucket is not significant. - - In an empty obarray, every element is 0, so you can create an obarray -with @code{(make-vector @var{length} 0)}. @strong{This is the only -valid way to create an obarray.} Prime numbers as lengths tend -to result in good hashing; lengths one less than a power of two are also -good. - - @strong{Do not try to put symbols in an obarray yourself.} This does -not work---only @code{intern} can enter a symbol in an obarray properly. - -@cindex CL note---symbol in obarrays -@quotation -@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in -several obarrays. -@end quotation - - Most of the functions below take a name and sometimes an obarray as -arguments. A @code{wrong-type-argument} error is signaled if the name -is not a string, or if the obarray is not a vector. - -@defun symbol-name symbol -This function returns the string that is @var{symbol}'s name. For example: - -@example -@group -(symbol-name 'foo) - @result{} "foo" -@end group -@end example - -@strong{Warning:} Changing the string by substituting characters does -change the name of the symbol, but fails to update the obarray, so don't -do it! -@end defun - -@defun make-symbol name -This function returns a newly-allocated, uninterned symbol whose name is -@var{name} (which must be a string). Its value and function definition -are void, and its property list is @code{nil}. In the example below, -the value of @code{sym} is not @code{eq} to @code{foo} because it is a -distinct uninterned symbol whose name is also @samp{foo}. - -@example -(setq sym (make-symbol "foo")) - @result{} foo -(eq sym 'foo) - @result{} nil -@end example -@end defun - -@defun intern name &optional obarray -This function returns the interned symbol whose name is @var{name}. If -there is no such symbol in the obarray @var{obarray}, @code{intern} -creates a new one, adds it to the obarray, and returns it. If -@var{obarray} is omitted, the value of the global variable -@code{obarray} is used. - -@example -(setq sym (intern "foo")) - @result{} foo -(eq sym 'foo) - @result{} t - -(setq sym1 (intern "foo" other-obarray)) - @result{} foo -(eq sym1 'foo) - @result{} nil -@end example -@end defun - -@cindex CL note---interning existing symbol -@quotation -@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol -in an obarray. In Emacs Lisp, you cannot do this, because the argument -to @code{intern} must be a string, not a symbol. -@end quotation - -@defun intern-soft name &optional obarray -This function returns the symbol in @var{obarray} whose name is -@var{name}, or @code{nil} if @var{obarray} has no symbol with that name. -Therefore, you can use @code{intern-soft} to test whether a symbol with -a given name is already interned. If @var{obarray} is omitted, the -value of the global variable @code{obarray} is used. - -The argument @var{name} may also be a symbol; in that case, -the function returns @var{name} if @var{name} is interned -in the specified obarray, and otherwise @code{nil}. - -@smallexample -(intern-soft "frazzle") ; @r{No such symbol exists.} - @result{} nil -(make-symbol "frazzle") ; @r{Create an uninterned one.} - @result{} frazzle -@group -(intern-soft "frazzle") ; @r{That one cannot be found.} - @result{} nil -@end group -@group -(setq sym (intern "frazzle")) ; @r{Create an interned one.} - @result{} frazzle -@end group -@group -(intern-soft "frazzle") ; @r{That one can be found!} - @result{} frazzle -@end group -@group -(eq sym 'frazzle) ; @r{And it is the same one.} - @result{} t -@end group -@end smallexample -@end defun - -@defvar obarray -This variable is the standard obarray for use by @code{intern} and -@code{read}. -@end defvar - -@defun mapatoms function &optional obarray -@anchor{Definition of mapatoms} -This function calls @var{function} once with each symbol in the obarray -@var{obarray}. Then it returns @code{nil}. If @var{obarray} is -omitted, it defaults to the value of @code{obarray}, the standard -obarray for ordinary symbols. - -@smallexample -(setq count 0) - @result{} 0 -(defun count-syms (s) - (setq count (1+ count))) - @result{} count-syms -(mapatoms 'count-syms) - @result{} nil -count - @result{} 1871 -@end smallexample - -See @code{documentation} in @ref{Accessing Documentation}, for another -example using @code{mapatoms}. -@end defun - -@defun unintern symbol &optional obarray -This function deletes @var{symbol} from the obarray @var{obarray}. If -@code{symbol} is not actually in the obarray, @code{unintern} does -nothing. If @var{obarray} is @code{nil}, the current obarray is used. - -If you provide a string instead of a symbol as @var{symbol}, it stands -for a symbol name. Then @code{unintern} deletes the symbol (if any) in -the obarray which has that name. If there is no such symbol, -@code{unintern} does nothing. - -If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise -it returns @code{nil}. -@end defun - -@node Property Lists,, Creating Symbols, Symbols -@section Property Lists -@cindex property list -@cindex plist - - A @dfn{property list} (@dfn{plist} for short) is a list of paired -elements stored in the property list cell of a symbol. Each of the -pairs associates a property name (usually a symbol) with a property or -value. Property lists are generally used to record information about a -symbol, such as its documentation as a variable, the name of the file -where it was defined, or perhaps even the grammatical class of the -symbol (representing a word) in a language-understanding system. - - Character positions in a string or buffer can also have property lists. -@xref{Text Properties}. - - The property names and values in a property list can be any Lisp -objects, but the names are usually symbols. Property list functions -compare the property names using @code{eq}. Here is an example of a -property list, found on the symbol @code{progn} when the compiler is -loaded: - -@example -(lisp-indent-function 0 byte-compile byte-compile-progn) -@end example - -@noindent -Here @code{lisp-indent-function} and @code{byte-compile} are property -names, and the other two elements are the corresponding values. - -@menu -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. -@end menu - -@node Plists and Alists -@subsection Property Lists and Association Lists -@cindex plist vs. alist -@cindex alist vs. plist - -@cindex property lists vs association lists - Association lists (@pxref{Association Lists}) are very similar to -property lists. In contrast to association lists, the order of the -pairs in the property list is not significant since the property names -must be distinct. - - Property lists are better than association lists for attaching -information to various Lisp function names or variables. If your -program keeps all of its associations in one association list, it will -typically need to search that entire list each time it checks for an -association. This could be slow. By contrast, if you keep the same -information in the property lists of the function names or variables -themselves, each search will scan only the length of one property list, -which is usually short. This is why the documentation for a variable is -recorded in a property named @code{variable-documentation}. The byte -compiler likewise uses properties to record those functions needing -special treatment. - - However, association lists have their own advantages. Depending on -your application, it may be faster to add an association to the front of -an association list than to update a property. All properties for a -symbol are stored in the same property list, so there is a possibility -of a conflict between different uses of a property name. (For this -reason, it is a good idea to choose property names that are probably -unique, such as by beginning the property name with the program's usual -name-prefix for variables and functions.) An association list may be -used like a stack where associations are pushed on the front of the list -and later discarded; this is not possible with a property list. - -@node Symbol Plists -@subsection Property List Functions for Symbols - -@defun symbol-plist symbol -This function returns the property list of @var{symbol}. -@end defun - -@defun setplist symbol plist -This function sets @var{symbol}'s property list to @var{plist}. -Normally, @var{plist} should be a well-formed property list, but this is -not enforced. The return value is @var{plist}. - -@smallexample -(setplist 'foo '(a 1 b (2 3) c nil)) - @result{} (a 1 b (2 3) c nil) -(symbol-plist 'foo) - @result{} (a 1 b (2 3) c nil) -@end smallexample - -For symbols in special obarrays, which are not used for ordinary -purposes, it may make sense to use the property list cell in a -nonstandard fashion; in fact, the abbrev mechanism does so -(@pxref{Abbrevs}). -@end defun - -@defun get symbol property -This function finds the value of the property named @var{property} in -@var{symbol}'s property list. If there is no such property, @code{nil} -is returned. Thus, there is no distinction between a value of -@code{nil} and the absence of the property. - -The name @var{property} is compared with the existing property names -using @code{eq}, so any object is a legitimate property. - -See @code{put} for an example. -@end defun - -@defun put symbol property value -This function puts @var{value} onto @var{symbol}'s property list under -the property name @var{property}, replacing any previous property value. -The @code{put} function returns @var{value}. - -@smallexample -(put 'fly 'verb 'transitive) - @result{}'transitive -(put 'fly 'noun '(a buzzing little bug)) - @result{} (a buzzing little bug) -(get 'fly 'verb) - @result{} transitive -(symbol-plist 'fly) - @result{} (verb transitive noun (a buzzing little bug)) -@end smallexample -@end defun - -@node Other Plists -@subsection Property Lists Outside Symbols - - These functions are useful for manipulating property lists -that are stored in places other than symbols: - -@defun plist-get plist property -This returns the value of the @var{property} property -stored in the property list @var{plist}. For example, - -@example -(plist-get '(foo 4) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'bar) - @result{} @code{wrong-type-argument} error -@end example - -It accepts a malformed @var{plist} argument and always returns @code{nil} -if @var{property} is not found in the @var{plist}. For example, - -@example -(plist-get '(foo 4 bad) 'bar) - @result{} nil -@end example -@end defun - -@defun plist-put plist property value -This stores @var{value} as the value of the @var{property} property in -the property list @var{plist}. It may modify @var{plist} destructively, -or it may construct a new list structure without altering the old. The -function returns the modified property list, so you can store that back -in the place where you got @var{plist}. For example, - -@example -(setq my-plist '(bar t foo 4)) - @result{} (bar t foo 4) -(setq my-plist (plist-put my-plist 'foo 69)) - @result{} (bar t foo 69) -(setq my-plist (plist-put my-plist 'quux '(a))) - @result{} (bar t foo 69 quux (a)) -@end example -@end defun - - You could define @code{put} in terms of @code{plist-put} as follows: - -@example -(defun put (symbol prop value) - (setplist symbol - (plist-put (symbol-plist symbol) prop value))) -@end example - -@defun lax-plist-get plist property -Like @code{plist-get} except that it compares properties -using @code{equal} instead of @code{eq}. -@end defun - -@defun lax-plist-put plist property value -Like @code{plist-put} except that it compares properties -using @code{equal} instead of @code{eq}. -@end defun - -@defun plist-member plist property -This returns non-@code{nil} if @var{plist} contains the given -@var{property}. Unlike @code{plist-get}, this allows you to distinguish -between a missing property and a property with the value @code{nil}. -The value is actually the tail of @var{plist} whose @code{car} is -@var{property}. -@end defun - -@ignore - arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce -@end ignore diff --git a/lispref/syntax.texi b/lispref/syntax.texi deleted file mode 100644 index 340f74632bd..00000000000 --- a/lispref/syntax.texi +++ /dev/null @@ -1,1185 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/syntax -@node Syntax Tables, Abbrevs, Searching and Matching, Top -@chapter Syntax Tables -@cindex parsing buffer text -@cindex syntax table -@cindex text parsing - - A @dfn{syntax table} specifies the syntactic textual function of each -character. This information is used by the @dfn{parsing functions}, the -complex movement commands, and others to determine where words, symbols, -and other syntactic constructs begin and end. The current syntax table -controls the meaning of the word motion functions (@pxref{Word Motion}) -and the list motion functions (@pxref{List Motion}), as well as the -functions in this chapter. - -@menu -* Basics: Syntax Basics. Basic concepts of syntax tables. -* Desc: 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. -@end menu - -@node Syntax Basics -@section Syntax Table Concepts - -@ifnottex - A @dfn{syntax table} provides Emacs with the information that -determines the syntactic use of each character in a buffer. This -information is used by the parsing commands, the complex movement -commands, and others to determine where words, symbols, and other -syntactic constructs begin and end. The current syntax table controls -the meaning of the word motion functions (@pxref{Word Motion}) and the -list motion functions (@pxref{List Motion}) as well as the functions in -this chapter. -@end ifnottex - - A syntax table is a char-table (@pxref{Char-Tables}). The element at -index @var{c} describes the character with code @var{c}. The element's -value should be a list that encodes the syntax of the character in -question. - - Syntax tables are used only for moving across text, not for the Emacs -Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp -expressions, and these rules cannot be changed. (Some Lisp systems -provide ways to redefine the read syntax, but we decided to leave this -feature out of Emacs Lisp for simplicity.) - - Each buffer has its own major mode, and each major mode has its own -idea of the syntactic class of various characters. For example, in Lisp -mode, the character @samp{;} begins a comment, but in C mode, it -terminates a statement. To support these variations, Emacs makes the -choice of syntax table local to each buffer. Typically, each major -mode has its own syntax table and installs that table in each buffer -that uses that mode. Changing this table alters the syntax in all -those buffers as well as in any buffers subsequently put in that mode. -Occasionally several similar modes share one syntax table. -@xref{Example Major Modes}, for an example of how to set up a syntax -table. - -A syntax table can inherit the data for some characters from the -standard syntax table, while specifying other characters itself. The -``inherit'' syntax class means ``inherit this character's syntax from -the standard syntax table.'' Just changing the standard syntax for a -character affects all syntax tables that inherit from it. - -@defun syntax-table-p object -This function returns @code{t} if @var{object} is a syntax table. -@end defun - -@node Syntax Descriptors -@section Syntax Descriptors -@cindex syntax class - - This section describes the syntax classes and flags that denote the -syntax of a character, and how they are represented as a @dfn{syntax -descriptor}, which is a Lisp string that you pass to -@code{modify-syntax-entry} to specify the syntax you want. - - The syntax table specifies a syntax class for each character. There -is no necessary relationship between the class of a character in one -syntax table and its class in any other table. - - Each class is designated by a mnemonic character, which serves as the -name of the class when you need to specify a class. Usually the -designator character is one that is often assigned that class; however, -its meaning as a designator is unvarying and independent of what syntax -that character currently has. Thus, @samp{\} as a designator character -always gives ``escape character'' syntax, regardless of what syntax -@samp{\} currently has. - -@cindex syntax descriptor - A syntax descriptor is a Lisp string that specifies a syntax class, a -matching character (used only for the parenthesis classes) and flags. -The first character is the designator for a syntax class. The second -character is the character to match; if it is unused, put a space there. -Then come the characters for any desired flags. If no matching -character or flags are needed, one character is sufficient. - - For example, the syntax descriptor for the character @samp{*} in C -mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot -unused, second character of a comment-starter, first character of a -comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e., -punctuation, matching character slot unused, first character of a -comment-starter, second character of a comment-ender). - -@menu -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. -@end menu - -@node Syntax Class Table -@subsection Table of Syntax Classes - - Here is a table of syntax classes, the characters that stand for them, -their meanings, and examples of their use. - -@deffn {Syntax class} @w{whitespace character} -@dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-}) -separate symbols and words from each other. Typically, whitespace -characters have no other syntactic significance, and multiple whitespace -characters are syntactically equivalent to a single one. Space, tab, -newline and formfeed are classified as whitespace in almost all major -modes. -@end deffn - -@deffn {Syntax class} @w{word constituent} -@dfn{Word constituents} (designated by @samp{w}) are parts of words in -human languages, and are typically used in variable and command names -in programs. All upper- and lower-case letters, and the digits, are -typically word constituents. -@end deffn - -@deffn {Syntax class} @w{symbol constituent} -@dfn{Symbol constituents} (designated by @samp{_}) are the extra -characters that are used in variable and command names along with word -constituents. For example, the symbol constituents class is used in -Lisp mode to indicate that certain characters may be part of symbol -names even though they are not part of English words. These characters -are @samp{$&*+-_<>}. In standard C, the only non-word-constituent -character that is valid in symbols is underscore (@samp{_}). -@end deffn - -@deffn {Syntax class} @w{punctuation character} -@dfn{Punctuation characters} (designated by @samp{.}) are those -characters that are used as punctuation in English, or are used in some -way in a programming language to separate symbols from one another. -Some programming language modes, such as Emacs Lisp mode, have no -characters in this class since the few characters that are not symbol or -word constituents all have other uses. Other programming language modes, -such as C mode, use punctuation syntax for operators. -@end deffn - -@deffn {Syntax class} @w{open parenthesis character} -@deffnx {Syntax class} @w{close parenthesis character} -@cindex parenthesis syntax -Open and close @dfn{parenthesis characters} are characters used in -dissimilar pairs to surround sentences or expressions. Such a grouping -is begun with an open parenthesis character and terminated with a close. -Each open parenthesis character matches a particular close parenthesis -character, and vice versa. Normally, Emacs indicates momentarily the -matching open parenthesis when you insert a close parenthesis. -@xref{Blinking}. - -The class of open parentheses is designated by @samp{(}, and that of -close parentheses by @samp{)}. - -In English text, and in C code, the parenthesis pairs are @samp{()}, -@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists and -vectors (@samp{()} and @samp{[]}) are classified as parenthesis -characters. -@end deffn - -@deffn {Syntax class} @w{string quote} -@dfn{String quote characters} (designated by @samp{"}) are used in -many languages, including Lisp and C, to delimit string constants. The -same string quote character appears at the beginning and the end of a -string. Such quoted strings do not nest. - -The parsing facilities of Emacs consider a string as a single token. -The usual syntactic meanings of the characters in the string are -suppressed. - -The Lisp modes have two string quote characters: double-quote (@samp{"}) -and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it -is used in Common Lisp. C also has two string quote characters: -double-quote for strings, and single-quote (@samp{'}) for character -constants. - -English text has no string quote characters because English is not a -programming language. Although quotation marks are used in English, -we do not want them to turn off the usual syntactic properties of -other characters in the quotation. -@end deffn - -@deffn {Syntax class} @w{escape-syntax character} -An @dfn{escape character} (designated by @samp{\}) starts an escape -sequence such as is used in C string and character constants. The -character @samp{\} belongs to this class in both C and Lisp. (In C, it -is used thus only inside strings, but it turns out to cause no trouble -to treat it this way throughout C code.) - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. -@end deffn - -@deffn {Syntax class} @w{character quote} -A @dfn{character quote character} (designated by @samp{/}) quotes the -following character so that it loses its normal syntactic meaning. This -differs from an escape character in that only the character immediately -following is ever affected. - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. - -This class is used for backslash in @TeX{} mode. -@end deffn - -@deffn {Syntax class} @w{paired delimiter} -@dfn{Paired delimiter characters} (designated by @samp{$}) are like -string quote characters except that the syntactic properties of the -characters between the delimiters are not suppressed. Only @TeX{} mode -uses a paired delimiter presently---the @samp{$} that both enters and -leaves math mode. -@end deffn - -@deffn {Syntax class} @w{expression prefix} -An @dfn{expression prefix operator} (designated by @samp{'}) is used for -syntactic operators that are considered as part of an expression if they -appear next to one. In Lisp modes, these characters include the -apostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used in -macros), and @samp{#} (used in the read syntax for certain data types). -@end deffn - -@deffn {Syntax class} @w{comment starter} -@deffnx {Syntax class} @w{comment ender} -@cindex comment syntax -The @dfn{comment starter} and @dfn{comment ender} characters are used in -various languages to delimit comments. These classes are designated -by @samp{<} and @samp{>}, respectively. - -English text has no comment characters. In Lisp, the semicolon -(@samp{;}) starts a comment and a newline or formfeed ends one. -@end deffn - -@deffn {Syntax class} @w{inherit standard syntax} -This syntax class does not specify a particular syntax. It says to look -in the standard syntax table to find the syntax of this character. The -designator for this syntax class is @samp{@@}. -@end deffn - -@deffn {Syntax class} @w{generic comment delimiter} -A @dfn{generic comment delimiter} (designated by @samp{!}) starts -or ends a special kind of comment. @emph{Any} generic comment delimiter -matches @emph{any} generic comment delimiter, but they cannot match -a comment starter or comment ender; generic comment delimiters can only -match each other. - -This syntax class is primarily meant for use with the -@code{syntax-table} text property (@pxref{Syntax Properties}). You can -mark any range of characters as forming a comment, by giving the first -and last characters of the range @code{syntax-table} properties -identifying them as generic comment delimiters. -@end deffn - -@deffn {Syntax class} @w{generic string delimiter} -A @dfn{generic string delimiter} (designated by @samp{|}) starts or ends -a string. This class differs from the string quote class in that @emph{any} -generic string delimiter can match any other generic string delimiter; but -they do not match ordinary string quote characters. - -This syntax class is primarily meant for use with the -@code{syntax-table} text property (@pxref{Syntax Properties}). You can -mark any range of characters as forming a string constant, by giving the -first and last characters of the range @code{syntax-table} properties -identifying them as generic string delimiters. -@end deffn - -@node Syntax Flags -@subsection Syntax Flags -@cindex syntax flags - - In addition to the classes, entries for characters in a syntax table -can specify flags. There are seven possible flags, represented by the -characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{n}, -and @samp{p}. - - All the flags except @samp{n} and @samp{p} are used to describe -multi-character comment delimiters. The digit flags indicate that a -character can @emph{also} be part of a comment sequence, in addition to -the syntactic properties associated with its character class. The flags -are independent of the class and each other for the sake of characters -such as @samp{*} in C mode, which is a punctuation character, @emph{and} -the second character of a start-of-comment sequence (@samp{/*}), -@emph{and} the first character of an end-of-comment sequence -(@samp{*/}). - - Here is a table of the possible flags for a character @var{c}, -and what they mean: - -@itemize @bullet -@item -@samp{1} means @var{c} is the start of a two-character comment-start -sequence. - -@item -@samp{2} means @var{c} is the second character of such a sequence. - -@item -@samp{3} means @var{c} is the start of a two-character comment-end -sequence. - -@item -@samp{4} means @var{c} is the second character of such a sequence. - -@item -@c Emacs 19 feature -@samp{b} means that @var{c} as a comment delimiter belongs to the -alternative ``b'' comment style. - -Emacs supports two comment styles simultaneously in any one syntax -table. This is for the sake of C++. Each style of comment syntax has -its own comment-start sequence and its own comment-end sequence. Each -comment must stick to one style or the other; thus, if it starts with -the comment-start sequence of style ``b,'' it must also end with the -comment-end sequence of style ``b.'' - -The two comment-start sequences must begin with the same character; only -the second character may differ. Mark the second character of the -``b''-style comment-start sequence with the @samp{b} flag. - -A comment-end sequence (one or two characters) applies to the ``b'' -style if its first character has the @samp{b} flag set; otherwise, it -applies to the ``a'' style. - -The appropriate comment syntax settings for C++ are as follows: - -@table @asis -@item @samp{/} -@samp{124b} -@item @samp{*} -@samp{23} -@item newline -@samp{>b} -@end table - -This defines four comment-delimiting sequences: - -@table @asis -@item @samp{/*} -This is a comment-start sequence for ``a'' style because the -second character, @samp{*}, does not have the @samp{b} flag. - -@item @samp{//} -This is a comment-start sequence for ``b'' style because the second -character, @samp{/}, does have the @samp{b} flag. - -@item @samp{*/} -This is a comment-end sequence for ``a'' style because the first -character, @samp{*}, does not have the @samp{b} flag. - -@item newline -This is a comment-end sequence for ``b'' style, because the newline -character has the @samp{b} flag. -@end table - -@item -@samp{n} on a comment delimiter character specifies -that this kind of comment can be nested. For a two-character -comment delimiter, @samp{n} on either character makes it -nestable. - -@item -@c Emacs 19 feature -@samp{p} identifies an additional ``prefix character'' for Lisp syntax. -These characters are treated as whitespace when they appear between -expressions. When they appear within an expression, they are handled -according to their usual syntax classes. - -The function @code{backward-prefix-chars} moves back over these -characters, as well as over characters whose primary syntax class is -prefix (@samp{'}). @xref{Motion and Syntax}. -@end itemize - -@node Syntax Table Functions -@section Syntax Table Functions - - In this section we describe functions for creating, accessing and -altering syntax tables. - -@defun make-syntax-table &optional table -This function creates a new syntax table, with all values initialized -to @code{nil}. If @var{table} is non-@code{nil}, it becomes the -parent of the new syntax table, otherwise the standard syntax table is -the parent. Like all char-tables, a syntax table inherits from its -parent. Thus the original syntax of all characters in the returned -syntax table is determined by the parent. @xref{Char-Tables}. - -Most major mode syntax tables are created in this way. -@end defun - -@defun copy-syntax-table &optional table -This function constructs a copy of @var{table} and returns it. If -@var{table} is not supplied (or is @code{nil}), it returns a copy of the -standard syntax table. Otherwise, an error is signaled if @var{table} is -not a syntax table. -@end defun - -@deffn Command modify-syntax-entry char syntax-descriptor &optional table -This function sets the syntax entry for @var{char} according to -@var{syntax-descriptor}. The syntax is changed only for @var{table}, -which defaults to the current buffer's syntax table, and not in any -other syntax table. The argument @var{syntax-descriptor} specifies the -desired syntax; this is a string beginning with a class designator -character, and optionally containing a matching character and flags as -well. @xref{Syntax Descriptors}. - -This function always returns @code{nil}. The old syntax information in -the table for this character is discarded. - -An error is signaled if the first character of the syntax descriptor is not -one of the seventeen syntax class designator characters. An error is also -signaled if @var{char} is not a character. - -@example -@group -@exdent @r{Examples:} - -;; @r{Put the space character in class whitespace.} -(modify-syntax-entry ?\s " ") - @result{} nil -@end group - -@group -;; @r{Make @samp{$} an open parenthesis character,} -;; @r{with @samp{^} as its matching close.} -(modify-syntax-entry ?$ "(^") - @result{} nil -@end group - -@group -;; @r{Make @samp{^} a close parenthesis character,} -;; @r{with @samp{$} as its matching open.} -(modify-syntax-entry ?^ ")$") - @result{} nil -@end group - -@group -;; @r{Make @samp{/} a punctuation character,} -;; @r{the first character of a start-comment sequence,} -;; @r{and the second character of an end-comment sequence.} -;; @r{This is used in C mode.} -(modify-syntax-entry ?/ ". 14") - @result{} nil -@end group -@end example -@end deffn - -@defun char-syntax character -This function returns the syntax class of @var{character}, represented -by its mnemonic designator character. This returns @emph{only} the -class, not any matching parenthesis or flags. - -An error is signaled if @var{char} is not a character. - -The following examples apply to C mode. The first example shows that -the syntax class of space is whitespace (represented by a space). The -second example shows that the syntax of @samp{/} is punctuation. This -does not show the fact that it is also part of comment-start and -end -sequences. The third example shows that open parenthesis is in the class -of open parentheses. This does not show the fact that it has a matching -character, @samp{)}. - -@example -@group -(string (char-syntax ?\s)) - @result{} " " -@end group - -@group -(string (char-syntax ?/)) - @result{} "." -@end group - -@group -(string (char-syntax ?\()) - @result{} "(" -@end group -@end example - -We use @code{string} to make it easier to see the character returned by -@code{char-syntax}. -@end defun - -@defun set-syntax-table table -This function makes @var{table} the syntax table for the current buffer. -It returns @var{table}. -@end defun - -@defun syntax-table -This function returns the current syntax table, which is the table for -the current buffer. -@end defun - -@defmac with-syntax-table @var{table} @var{body}@dots{} -This macro executes @var{body} using @var{table} as the current syntax -table. It returns the value of the last form in @var{body}, after -restoring the old current syntax table. - -Since each buffer has its own current syntax table, we should make that -more precise: @code{with-syntax-table} temporarily alters the current -syntax table of whichever buffer is current at the time the macro -execution starts. Other buffers are not affected. -@end defmac - -@node Syntax Properties -@section Syntax Properties -@kindex syntax-table @r{(text property)} - -When the syntax table is not flexible enough to specify the syntax of -a language, you can use @code{syntax-table} text properties to -override the syntax table for specific character occurrences in the -buffer. @xref{Text Properties}. You can use Font Lock mode to set -@code{syntax-table} text properties. @xref{Setting Syntax -Properties}. - -The valid values of @code{syntax-table} text property are: - -@table @asis -@item @var{syntax-table} -If the property value is a syntax table, that table is used instead of -the current buffer's syntax table to determine the syntax for this -occurrence of the character. - -@item @code{(@var{syntax-code} . @var{matching-char})} -A cons cell of this format specifies the syntax for this -occurrence of the character. (@pxref{Syntax Table Internals}) - -@item @code{nil} -If the property is @code{nil}, the character's syntax is determined from -the current syntax table in the usual way. -@end table - -@defvar parse-sexp-lookup-properties -If this is non-@code{nil}, the syntax scanning functions pay attention -to syntax text properties. Otherwise they use only the current syntax -table. -@end defvar - -@node Motion and Syntax -@section Motion and Syntax - - This section describes functions for moving across characters that -have certain syntax classes. - -@defun skip-syntax-forward syntaxes &optional limit -This function moves point forward across characters having syntax -classes mentioned in @var{syntaxes} (a string of syntax class -characters). It stops when it encounters the end of the buffer, or -position @var{limit} (if specified), or a character it is not supposed -to skip. - -If @var{syntaxes} starts with @samp{^}, then the function skips -characters whose syntax is @emph{not} in @var{syntaxes}. - -The return value is the distance traveled, which is a nonnegative -integer. -@end defun - -@defun skip-syntax-backward syntaxes &optional limit -This function moves point backward across characters whose syntax -classes are mentioned in @var{syntaxes}. It stops when it encounters -the beginning of the buffer, or position @var{limit} (if specified), or -a character it is not supposed to skip. - -If @var{syntaxes} starts with @samp{^}, then the function skips -characters whose syntax is @emph{not} in @var{syntaxes}. - -The return value indicates the distance traveled. It is an integer that -is zero or less. -@end defun - -@defun backward-prefix-chars -This function moves point backward over any number of characters with -expression prefix syntax. This includes both characters in the -expression prefix syntax class, and characters with the @samp{p} flag. -@end defun - -@node Parsing Expressions -@section Parsing Expressions - - This section describes functions for parsing and scanning balanced -expressions, also known as @dfn{sexps}. Basically, a sexp is either a -balanced parenthetical grouping, a string, or a symbol name (a -sequence of characters whose syntax is either word constituent or -symbol constituent). However, characters whose syntax is expression -prefix are treated as part of the sexp if they appear next to it. - - The syntax table controls the interpretation of characters, so these -functions can be used for Lisp expressions when in Lisp mode and for C -expressions when in C mode. @xref{List Motion}, for convenient -higher-level functions for moving over balanced expressions. - - A character's syntax controls how it changes the state of the -parser, rather than describing the state itself. For example, a -string delimiter character toggles the parser state between -``in-string'' and ``in-code,'' but the syntax of characters does not -directly say whether they are inside a string. For example (note that -15 is the syntax code for generic string delimiters), - -@example -(put-text-property 1 9 'syntax-table '(15 . nil)) -@end example - -@noindent -does not tell Emacs that the first eight chars of the current buffer -are a string, but rather that they are all string delimiters. As a -result, Emacs treats them as four consecutive empty string constants. - -@menu -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. -@end menu - -@node Motion via Parsing -@subsection Motion Commands Based on Parsing - - This section describes simple point-motion functions that operate -based on parsing expressions. - -@defun scan-lists from count depth -This function scans forward @var{count} balanced parenthetical groupings -from position @var{from}. It returns the position where the scan stops. -If @var{count} is negative, the scan moves backwards. - -If @var{depth} is nonzero, parenthesis depth counting begins from that -value. The only candidates for stopping are places where the depth in -parentheses becomes zero; @code{scan-lists} counts @var{count} such -places and then stops. Thus, a positive value for @var{depth} means go -out @var{depth} levels of parenthesis. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of the buffer (or its -accessible portion), and the depth is not zero, an error is signaled. -If the depth is zero but the count is not used up, @code{nil} is -returned. -@end defun - -@defun scan-sexps from count -This function scans forward @var{count} sexps from position @var{from}. -It returns the position where the scan stops. If @var{count} is -negative, the scan moves backwards. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of (the accessible part of) the -buffer while in the middle of a parenthetical grouping, an error is -signaled. If it reaches the beginning or end between groupings but -before count is used up, @code{nil} is returned. -@end defun - -@defun forward-comment count -This function moves point forward across @var{count} complete comments - (that is, including the starting delimiter and the terminating -delimiter if any), plus any whitespace encountered on the way. It -moves backward if @var{count} is negative. If it encounters anything -other than a comment or whitespace, it stops, leaving point at the -place where it stopped. This includes (for instance) finding the end -of a comment when moving forward and expecting the beginning of one. -The function also stops immediately after moving over the specified -number of complete comments. If @var{count} comments are found as -expected, with nothing except whitespace between them, it returns -@code{t}; otherwise it returns @code{nil}. - -This function cannot tell whether the ``comments'' it traverses are -embedded within a string. If they look like comments, it treats them -as comments. -@end defun - -To move forward over all comments and whitespace following point, use -@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a good -argument to use, because the number of comments in the buffer cannot -exceed that many. - -@node Position Parse -@subsection Finding the Parse State for a Position - - For syntactic analysis, such as in indentation, often the useful -thing is to compute the syntactic state corresponding to a given buffer -position. This function does that conveniently. - -@defun syntax-ppss &optional pos -This function returns the parser state (see next section) that the -parser would reach at position @var{pos} starting from the beginning -of the buffer. This is equivalent to @code{(parse-partial-sexp -(point-min) @var{pos})}, except that @code{syntax-ppss} uses a cache -to speed up the computation. Due to this optimization, the 2nd value -(previous complete subexpression) and 6th value (minimum parenthesis -depth) of the returned parser state are not meaningful. -@end defun - - @code{syntax-ppss} automatically hooks itself to -@code{before-change-functions} to keep its cache consistent. But -updating can fail if @code{syntax-ppss} is called while -@code{before-change-functions} is temporarily let-bound, or if the -buffer is modified without obeying the hook, such as when using -@code{inhibit-modification-hooks}. For this reason, it is sometimes -necessary to flush the cache manually. - -@defun syntax-ppss-flush-cache beg -This function flushes the cache used by @code{syntax-ppss}, starting at -position @var{beg}. -@end defun - - Major modes can make @code{syntax-ppss} run faster by specifying -where it needs to start parsing. - -@defvar syntax-begin-function -If this is non-@code{nil}, it should be a function that moves to an -earlier buffer position where the parser state is equivalent to -@code{nil}---in other words, a position outside of any comment, -string, or parenthesis. @code{syntax-ppss} uses it to further -optimize its computations, when the cache gives no help. -@end defvar - -@node Parser State -@subsection Parser State -@cindex parser state - - A @dfn{parser state} is a list of ten elements describing the final -state of parsing text syntactically as part of an expression. The -parsing functions in the following sections return a parser state as -the value, and in some cases accept one as an argument also, so that -you can resume parsing after it stops. Here are the meanings of the -elements of the parser state: - -@enumerate 0 -@item -The depth in parentheses, counting from 0. @strong{Warning:} this can -be negative if there are more close parens than open parens between -the start of the defun and point. - -@item -@cindex innermost containing parentheses -The character position of the start of the innermost parenthetical -grouping containing the stopping point; @code{nil} if none. - -@item -@cindex previous complete subexpression -The character position of the start of the last complete subexpression -terminated; @code{nil} if none. - -@item -@cindex inside string -Non-@code{nil} if inside a string. More precisely, this is the -character that will terminate the string, or @code{t} if a generic -string delimiter character should terminate it. - -@item -@cindex inside comment -@code{t} if inside a comment (of either style), -or the comment nesting level if inside a kind of comment -that can be nested. - -@item -@cindex quote character -@code{t} if point is just after a quote character. - -@item -The minimum parenthesis depth encountered during this scan. - -@item -What kind of comment is active: @code{nil} for a comment of style -``a'' or when not inside a comment, @code{t} for a comment of style -``b,'' and @code{syntax-table} for a comment that should be ended by a -generic comment delimiter character. - -@item -The string or comment start position. While inside a comment, this is -the position where the comment began; while inside a string, this is the -position where the string began. When outside of strings and comments, -this element is @code{nil}. - -@item -Internal data for continuing the parsing. The meaning of this -data is subject to change; it is used if you pass this list -as the @var{state} argument to another call. -@end enumerate - - Elements 1, 2, and 6 are ignored in a state which you pass as an -argument to continue parsing, and elements 8 and 9 are used only in -trivial cases. Those elements serve primarily to convey information -to the Lisp program which does the parsing. - - One additional piece of useful information is available from a -parser state using this function: - -@defun syntax-ppss-toplevel-pos state -This function extracts, from parser state @var{state}, the last -position scanned in the parse which was at top level in grammatical -structure. ``At top level'' means outside of any parentheses, -comments, or strings. - -The value is @code{nil} if @var{state} represents a parse which has -arrived at a top level position. -@end defun - - We have provided this access function rather than document how the -data is represented in the state, because we plan to change the -representation in the future. - -@node Low-Level Parsing -@subsection Low-Level Parsing - - The most basic way to use the expression parser is to tell it -to start at a given position with a certain state, and parse up to -a specified end position. - -@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment -This function parses a sexp in the current buffer starting at -@var{start}, not scanning past @var{limit}. It stops at position -@var{limit} or when certain criteria described below are met, and sets -point to the location where parsing stops. It returns a parser state -describing the status of the parse at the point where it stops. - -@cindex parenthesis depth -If the third argument @var{target-depth} is non-@code{nil}, parsing -stops if the depth in parentheses becomes equal to @var{target-depth}. -The depth starts at 0, or at whatever is given in @var{state}. - -If the fourth argument @var{stop-before} is non-@code{nil}, parsing -stops when it comes to any character that starts a sexp. If -@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the -start of a comment. If @var{stop-comment} is the symbol -@code{syntax-table}, parsing stops after the start of a comment or a -string, or the end of a comment or a string, whichever comes first. - -If @var{state} is @code{nil}, @var{start} is assumed to be at the top -level of parenthesis structure, such as the beginning of a function -definition. Alternatively, you might wish to resume parsing in the -middle of the structure. To do this, you must provide a @var{state} -argument that describes the initial status of parsing. The value -returned by a previous call to @code{parse-partial-sexp} will do -nicely. -@end defun - -@node Control Parsing -@subsection Parameters to Control Parsing - -@defvar multibyte-syntax-as-symbol -If this variable is non-@code{nil}, @code{scan-sexps} treats all -non-@acronym{ASCII} characters as symbol constituents regardless -of what the syntax table says about them. (However, text properties -can still override the syntax.) -@end defvar - -@defopt parse-sexp-ignore-comments -@cindex skipping comments -If the value is non-@code{nil}, then comments are treated as -whitespace by the functions in this section and by @code{forward-sexp}, -@code{scan-lists} and @code{scan-sexps}. -@end defopt - -@vindex parse-sexp-lookup-properties -The behavior of @code{parse-partial-sexp} is also affected by -@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}). - -You can use @code{forward-comment} to move forward or backward over -one comment or several comments. - -@node Standard Syntax Tables -@section Some Standard Syntax Tables - - Most of the major modes in Emacs have their own syntax tables. Here -are several of them: - -@defun standard-syntax-table -This function returns the standard syntax table, which is the syntax -table used in Fundamental mode. -@end defun - -@defvar text-mode-syntax-table -The value of this variable is the syntax table used in Text mode. -@end defvar - -@defvar c-mode-syntax-table -The value of this variable is the syntax table for C-mode buffers. -@end defvar - -@defvar emacs-lisp-mode-syntax-table -The value of this variable is the syntax table used in Emacs Lisp mode -by editing commands. (It has no effect on the Lisp @code{read} -function.) -@end defvar - -@node Syntax Table Internals -@section Syntax Table Internals -@cindex syntax table internals - - Lisp programs don't usually work with the elements directly; the -Lisp-level syntax table functions usually work with syntax descriptors -(@pxref{Syntax Descriptors}). Nonetheless, here we document the -internal format. This format is used mostly when manipulating -syntax properties. - - Each element of a syntax table is a cons cell of the form -@code{(@var{syntax-code} . @var{matching-char})}. The @sc{car}, -@var{syntax-code}, is an integer that encodes the syntax class, and any -flags. The @sc{cdr}, @var{matching-char}, is non-@code{nil} if -a character to match was specified. - - This table gives the value of @var{syntax-code} which corresponds -to each syntactic type. - -@multitable @columnfractions .05 .3 .3 .31 -@item -@tab -@i{Integer} @i{Class} -@tab -@i{Integer} @i{Class} -@tab -@i{Integer} @i{Class} -@item -@tab -0 @ @ whitespace -@tab -5 @ @ close parenthesis -@tab -10 @ @ character quote -@item -@tab -1 @ @ punctuation -@tab -6 @ @ expression prefix -@tab -11 @ @ comment-start -@item -@tab -2 @ @ word -@tab -7 @ @ string quote -@tab -12 @ @ comment-end -@item -@tab -3 @ @ symbol -@tab -8 @ @ paired delimiter -@tab -13 @ @ inherit -@item -@tab -4 @ @ open parenthesis -@tab -9 @ @ escape -@tab -14 @ @ generic comment -@item -@tab -15 @ generic string -@end multitable - - For example, the usual syntax value for @samp{(} is @code{(4 . 41)}. -(41 is the character code for @samp{)}.) - - The flags are encoded in higher order bits, starting 16 bits from the -least significant bit. This table gives the power of two which -corresponds to each syntax flag. - -@multitable @columnfractions .05 .3 .3 .3 -@item -@tab -@i{Prefix} @i{Flag} -@tab -@i{Prefix} @i{Flag} -@tab -@i{Prefix} @i{Flag} -@item -@tab -@samp{1} @ @ @code{(lsh 1 16)} -@tab -@samp{4} @ @ @code{(lsh 1 19)} -@tab -@samp{b} @ @ @code{(lsh 1 21)} -@item -@tab -@samp{2} @ @ @code{(lsh 1 17)} -@tab -@samp{p} @ @ @code{(lsh 1 20)} -@tab -@samp{n} @ @ @code{(lsh 1 22)} -@item -@tab -@samp{3} @ @ @code{(lsh 1 18)} -@end multitable - -@defun string-to-syntax @var{desc} -This function returns the internal form corresponding to the syntax -descriptor @var{desc}, a cons cell @code{(@var{syntax-code} -. @var{matching-char})}. -@end defun - -@defun syntax-after pos -This function returns the syntax code of the character in the buffer -after position @var{pos}, taking account of syntax properties as well -as the syntax table. If @var{pos} is outside the buffer's accessible -portion (@pxref{Narrowing, accessible portion}), this function returns -@code{nil}. -@end defun - -@defun syntax-class syntax -This function returns the syntax class of the syntax code -@var{syntax}. (It masks off the high 16 bits that hold the flags -encoded in the syntax descriptor.) If @var{syntax} is @code{nil}, it -returns @code{nil}; this is so evaluating the expression - -@example -(syntax-class (syntax-after pos)) -@end example - -@noindent -where @code{pos} is outside the buffer's accessible portion, will -yield @code{nil} without throwing errors or producing wrong syntax -class codes. -@end defun - -@node Categories -@section Categories -@cindex categories of characters -@cindex character categories - - @dfn{Categories} provide an alternate way of classifying characters -syntactically. You can define several categories as needed, then -independently assign each character to one or more categories. Unlike -syntax classes, categories are not mutually exclusive; it is normal for -one character to belong to several categories. - -@cindex category table - Each buffer has a @dfn{category table} which records which categories -are defined and also which characters belong to each category. Each -category table defines its own categories, but normally these are -initialized by copying from the standard categories table, so that the -standard categories are available in all modes. - - Each category has a name, which is an @acronym{ASCII} printing character in -the range @w{@samp{ }} to @samp{~}. You specify the name of a category -when you define it with @code{define-category}. - - The category table is actually a char-table (@pxref{Char-Tables}). -The element of the category table at index @var{c} is a @dfn{category -set}---a bool-vector---that indicates which categories character @var{c} -belongs to. In this category set, if the element at index @var{cat} is -@code{t}, that means category @var{cat} is a member of the set, and that -character @var{c} belongs to category @var{cat}. - -For the next three functions, the optional argument @var{table} -defaults to the current buffer's category table. - -@defun define-category char docstring &optional table -This function defines a new category, with name @var{char} and -documentation @var{docstring}, for the category table @var{table}. -@end defun - -@defun category-docstring category &optional table -This function returns the documentation string of category @var{category} -in category table @var{table}. - -@example -(category-docstring ?a) - @result{} "ASCII" -(category-docstring ?l) - @result{} "Latin" -@end example -@end defun - -@defun get-unused-category &optional table -This function returns a category name (a character) which is not -currently defined in @var{table}. If all possible categories are in use -in @var{table}, it returns @code{nil}. -@end defun - -@defun category-table -This function returns the current buffer's category table. -@end defun - -@defun category-table-p object -This function returns @code{t} if @var{object} is a category table, -otherwise @code{nil}. -@end defun - -@defun standard-category-table -This function returns the standard category table. -@end defun - -@defun copy-category-table &optional table -This function constructs a copy of @var{table} and returns it. If -@var{table} is not supplied (or is @code{nil}), it returns a copy of the -standard category table. Otherwise, an error is signaled if @var{table} -is not a category table. -@end defun - -@defun set-category-table table -This function makes @var{table} the category table for the current -buffer. It returns @var{table}. -@end defun - -@defun make-category-table -This creates and returns an empty category table. In an empty category -table, no categories have been allocated, and no characters belong to -any categories. -@end defun - -@defun make-category-set categories -This function returns a new category set---a bool-vector---whose initial -contents are the categories listed in the string @var{categories}. The -elements of @var{categories} should be category names; the new category -set has @code{t} for each of those categories, and @code{nil} for all -other categories. - -@example -(make-category-set "al") - @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -@end example -@end defun - -@defun char-category-set char -This function returns the category set for character @var{char} in the -current buffer's category table. This is the bool-vector which -records which categories the character @var{char} belongs to. The -function @code{char-category-set} does not allocate storage, because -it returns the same bool-vector that exists in the category table. - -@example -(char-category-set ?a) - @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -@end example -@end defun - -@defun category-set-mnemonics category-set -This function converts the category set @var{category-set} into a string -containing the characters that designate the categories that are members -of the set. - -@example -(category-set-mnemonics (char-category-set ?a)) - @result{} "al" -@end example -@end defun - -@defun modify-category-entry character category &optional table reset -This function modifies the category set of @var{character} in category -table @var{table} (which defaults to the current buffer's category -table). - -Normally, it modifies the category set by adding @var{category} to it. -But if @var{reset} is non-@code{nil}, then it deletes @var{category} -instead. -@end defun - -@deffn Command describe-categories &optional buffer-or-name -This function describes the category specifications in the current -category table. It inserts the descriptions in a buffer, and then -displays that buffer. If @var{buffer-or-name} is non-@code{nil}, it -describes the category table of that buffer instead. -@end deffn - -@ignore - arch-tag: 4d914e96-0283-445c-9233-75d33662908c -@end ignore diff --git a/lispref/text.texi b/lispref/text.texi deleted file mode 100644 index 430c48133ee..00000000000 --- a/lispref/text.texi +++ /dev/null @@ -1,4303 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/text -@node Text, Non-ASCII Characters, Markers, Top -@chapter Text -@cindex text - - This chapter describes the functions that deal with the text in a -buffer. Most examine, insert, or delete text in the current buffer, -often operating at point or on text adjacent to point. Many are -interactive. All the functions that change the text provide for undoing -the changes (@pxref{Undo}). - - Many text-related functions operate on a region of text defined by two -buffer positions passed in arguments named @var{start} and @var{end}. -These arguments should be either markers (@pxref{Markers}) or numeric -character positions (@pxref{Positions}). The order of these arguments -does not matter; it is all right for @var{start} to be the end of the -region and @var{end} the beginning. For example, @code{(delete-region 1 -10)} and @code{(delete-region 10 1)} are equivalent. An -@code{args-out-of-range} error is signaled if either @var{start} or -@var{end} is outside the accessible portion of the buffer. In an -interactive call, point and the mark are used for these arguments. - -@cindex buffer contents - Throughout this chapter, ``text'' refers to the characters in the -buffer, together with their properties (when relevant). Keep in mind -that point is always between two characters, and the cursor appears on -the character after point. - -@menu -* 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. -@end menu - -@node Near Point -@section Examining Text Near Point -@cindex text near point - - Many functions are provided to look at the characters around point. -Several simple functions are described here. See also @code{looking-at} -in @ref{Regexp Search}. - -In the following four functions, ``beginning'' or ``end'' of buffer -refers to the beginning or end of the accessible portion. - -@defun char-after &optional position -This function returns the character in the current buffer at (i.e., -immediately after) position @var{position}. If @var{position} is out of -range for this purpose, either before the beginning of the buffer, or at -or beyond the end, then the value is @code{nil}. The default for -@var{position} is point. - -In the following example, assume that the first character in the -buffer is @samp{@@}: - -@example -@group -(char-to-string (char-after 1)) - @result{} "@@" -@end group -@end example -@end defun - -@defun char-before &optional position -This function returns the character in the current buffer immediately -before position @var{position}. If @var{position} is out of range for -this purpose, either at or before the beginning of the buffer, or beyond -the end, then the value is @code{nil}. The default for -@var{position} is point. -@end defun - -@defun following-char -This function returns the character following point in the current -buffer. This is similar to @code{(char-after (point))}. However, if -point is at the end of the buffer, then @code{following-char} returns 0. - -Remember that point is always between characters, and the cursor -normally appears over the character following point. Therefore, the -character returned by @code{following-char} is the character the -cursor is over. - -In this example, point is between the @samp{a} and the @samp{c}. - -@example -@group ----------- Buffer: foo ---------- -Gentlemen may cry ``Pea@point{}ce! Peace!,'' -but there is no peace. ----------- Buffer: foo ---------- -@end group - -@group -(char-to-string (preceding-char)) - @result{} "a" -(char-to-string (following-char)) - @result{} "c" -@end group -@end example -@end defun - -@defun preceding-char -This function returns the character preceding point in the current -buffer. See above, under @code{following-char}, for an example. If -point is at the beginning of the buffer, @code{preceding-char} returns -0. -@end defun - -@defun bobp -This function returns @code{t} if point is at the beginning of the -buffer. If narrowing is in effect, this means the beginning of the -accessible portion of the text. See also @code{point-min} in -@ref{Point}. -@end defun - -@defun eobp -This function returns @code{t} if point is at the end of the buffer. -If narrowing is in effect, this means the end of accessible portion of -the text. See also @code{point-max} in @xref{Point}. -@end defun - -@defun bolp -This function returns @code{t} if point is at the beginning of a line. -@xref{Text Lines}. The beginning of the buffer (or of its accessible -portion) always counts as the beginning of a line. -@end defun - -@defun eolp -This function returns @code{t} if point is at the end of a line. The -end of the buffer (or of its accessible portion) is always considered -the end of a line. -@end defun - -@node Buffer Contents -@section Examining Buffer Contents - - This section describes functions that allow a Lisp program to -convert any portion of the text in the buffer into a string. - -@defun buffer-substring start end -This function returns a string containing a copy of the text of the -region defined by positions @var{start} and @var{end} in the current -buffer. If the arguments are not positions in the accessible portion of -the buffer, @code{buffer-substring} signals an @code{args-out-of-range} -error. - -It is not necessary for @var{start} to be less than @var{end}; the -arguments can be given in either order. But most often the smaller -argument is written first. - -Here's an example which assumes Font-Lock mode is not enabled: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of buffer foo - ----------- Buffer: foo ---------- -@end group - -@group -(buffer-substring 1 10) - @result{} "This is t" -@end group -@group -(buffer-substring (point-max) 10) - @result{} "he contents of buffer foo\n" -@end group -@end example - -If the text being copied has any text properties, these are copied into -the string along with the characters they belong to. @xref{Text -Properties}. However, overlays (@pxref{Overlays}) in the buffer and -their properties are ignored, not copied. - -For example, if Font-Lock mode is enabled, you might get results like -these: - -@example -@group -(buffer-substring 1 10) - @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t)) -@end group -@end example -@end defun - -@defun buffer-substring-no-properties start end -This is like @code{buffer-substring}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -@end defun - -@defun filter-buffer-substring start end &optional delete noprops -This function passes the buffer text between @var{start} and @var{end} -through the filter functions specified by the variable -@code{buffer-substring-filters}, and returns the value from the last -filter function. If @code{buffer-substring-filters} is @code{nil}, -the value is the unaltered text from the buffer, what -@code{buffer-substring} would return. - -If @var{delete} is non-@code{nil}, this function deletes the text -between @var{start} and @var{end} after copying it, like -@code{delete-and-extract-region}. - -If @var{noprops} is non-@code{nil}, the final string returned does not -include text properties, while the string passed through the filters -still includes text properties from the buffer text. - -Lisp code should use this function instead of @code{buffer-substring}, -@code{buffer-substring-no-properties}, -or @code{delete-and-extract-region} when copying into user-accessible -data structures such as the kill-ring, X clipboard, and registers. -Major and minor modes can add functions to -@code{buffer-substring-filters} to alter such text as it is copied out -of the buffer. -@end defun - -@defvar buffer-substring-filters -This variable should be a list of functions that accept a single -argument, a string, and return a string. -@code{filter-buffer-substring} passes the buffer substring to the -first function in this list, and the return value of each function is -passed to the next function. The return value of the last function is -used as the return value of @code{filter-buffer-substring}. - -As a special convention, point is set to the start of the buffer text -being operated on (i.e., the @var{start} argument for -@code{filter-buffer-substring}) before these functions are called. - -If this variable is @code{nil}, no filtering is performed. -@end defvar - -@defun buffer-string -This function returns the contents of the entire accessible portion of -the current buffer as a string. It is equivalent to - -@example -(buffer-substring (point-min) (point-max)) -@end example - -@example -@group ----------- Buffer: foo ---------- -This is the contents of buffer foo - ----------- Buffer: foo ---------- - -(buffer-string) - @result{} "This is the contents of buffer foo\n" -@end group -@end example -@end defun - -@defun current-word &optional strict really-word -This function returns the symbol (or word) at or near point, as a string. -The return value includes no text properties. - -If the optional argument @var{really-word} is non-@code{nil}, it finds a -word; otherwise, it finds a symbol (which includes both word -characters and symbol constituent characters). - -If the optional argument @var{strict} is non-@code{nil}, then point -must be in or next to the symbol or word---if no symbol or word is -there, the function returns @code{nil}. Otherwise, a nearby symbol or -word on the same line is acceptable. -@end defun - -@defun thing-at-point thing -Return the @var{thing} around or next to point, as a string. - -The argument @var{thing} is a symbol which specifies a kind of syntactic -entity. Possibilities include @code{symbol}, @code{list}, @code{sexp}, -@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence}, -@code{whitespace}, @code{line}, @code{page}, and others. - -@example ----------- Buffer: foo ---------- -Gentlemen may cry ``Pea@point{}ce! Peace!,'' -but there is no peace. ----------- Buffer: foo ---------- - -(thing-at-point 'word) - @result{} "Peace" -(thing-at-point 'line) - @result{} "Gentlemen may cry ``Peace! Peace!,''\n" -(thing-at-point 'whitespace) - @result{} nil -@end example -@end defun - -@node Comparing Text -@section Comparing Text -@cindex comparing buffer text - - This function lets you compare portions of the text in a buffer, without -copying them into strings first. - -@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 -This function lets you compare two substrings of the same buffer or two -different buffers. The first three arguments specify one substring, -giving a buffer (or a buffer name) and two positions within the -buffer. The last three arguments specify the other substring in the -same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or -both to stand for the current buffer. - -The value is negative if the first substring is less, positive if the -first is greater, and zero if they are equal. The absolute value of -the result is one plus the index of the first differing characters -within the substrings. - -This function ignores case when comparing characters -if @code{case-fold-search} is non-@code{nil}. It always ignores -text properties. - -Suppose the current buffer contains the text @samp{foobarbar -haha!rara!}; then in this example the two substrings are @samp{rbar } -and @samp{rara!}. The value is 2 because the first substring is greater -at the second character. - -@example -(compare-buffer-substrings nil 6 11 nil 16 21) - @result{} 2 -@end example -@end defun - -@node Insertion -@section Inserting Text -@cindex insertion of text -@cindex text insertion - -@cindex insertion before point -@cindex before point, insertion - @dfn{Insertion} means adding new text to a buffer. The inserted text -goes at point---between the character before point and the character -after point. Some insertion functions leave point before the inserted -text, while other functions leave it after. We call the former -insertion @dfn{after point} and the latter insertion @dfn{before point}. - - Insertion relocates markers that point at positions after the -insertion point, so that they stay with the surrounding text -(@pxref{Markers}). When a marker points at the place of insertion, -insertion may or may not relocate the marker, depending on the marker's -insertion type (@pxref{Marker Insertion Types}). Certain special -functions such as @code{insert-before-markers} relocate all such markers -to point after the inserted text, regardless of the markers' insertion -type. - - Insertion functions signal an error if the current buffer is -read-only or if they insert within read-only text. - - These functions copy text characters from strings and buffers along -with their properties. The inserted characters have exactly the same -properties as the characters they were copied from. By contrast, -characters specified as separate arguments, not part of a string or -buffer, inherit their text properties from the neighboring text. - - The insertion functions convert text from unibyte to multibyte in -order to insert in a multibyte buffer, and vice versa---if the text -comes from a string or from a buffer. However, they do not convert -unibyte character codes 128 through 255 to multibyte characters, not -even if the current buffer is a multibyte buffer. @xref{Converting -Representations}. - -@defun insert &rest args -This function inserts the strings and/or characters @var{args} into the -current buffer, at point, moving point forward. In other words, it -inserts the text before point. An error is signaled unless all -@var{args} are either strings or characters. The value is @code{nil}. -@end defun - -@defun insert-before-markers &rest args -This function inserts the strings and/or characters @var{args} into the -current buffer, at point, moving point forward. An error is signaled -unless all @var{args} are either strings or characters. The value is -@code{nil}. - -This function is unlike the other insertion functions in that it -relocates markers initially pointing at the insertion point, to point -after the inserted text. If an overlay begins at the insertion point, -the inserted text falls outside the overlay; if a nonempty overlay -ends at the insertion point, the inserted text falls inside that -overlay. -@end defun - -@defun insert-char character count &optional inherit -This function inserts @var{count} instances of @var{character} into the -current buffer before point. The argument @var{count} should be an -integer, and @var{character} must be a character. The value is @code{nil}. - -This function does not convert unibyte character codes 128 through 255 -to multibyte characters, not even if the current buffer is a multibyte -buffer. @xref{Converting Representations}. - -If @var{inherit} is non-@code{nil}, then the inserted characters inherit -sticky text properties from the two characters before and after the -insertion point. @xref{Sticky Properties}. -@end defun - -@defun insert-buffer-substring from-buffer-or-name &optional start end -This function inserts a portion of buffer @var{from-buffer-or-name} -(which must already exist) into the current buffer before point. The -text inserted is the region between @var{start} and @var{end}. (These -arguments default to the beginning and end of the accessible portion of -that buffer.) This function returns @code{nil}. - -In this example, the form is executed with buffer @samp{bar} as the -current buffer. We assume that buffer @samp{bar} is initially empty. - -@example -@group ----------- Buffer: foo ---------- -We hold these truths to be self-evident, that all ----------- Buffer: foo ---------- -@end group - -@group -(insert-buffer-substring "foo" 1 20) - @result{} nil - ----------- Buffer: bar ---------- -We hold these truth@point{} ----------- Buffer: bar ---------- -@end group -@end example -@end defun - -@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end -This is like @code{insert-buffer-substring} except that it does not -copy any text properties. -@end defun - - @xref{Sticky Properties}, for other insertion functions that inherit -text properties from the nearby text in addition to inserting it. -Whitespace inserted by indentation functions also inherits text -properties. - -@node Commands for Insertion -@section User-Level Insertion Commands - - This section describes higher-level commands for inserting text, -commands intended primarily for the user but useful also in Lisp -programs. - -@deffn Command insert-buffer from-buffer-or-name -This command inserts the entire accessible contents of -@var{from-buffer-or-name} (which must exist) into the current buffer -after point. It leaves the mark after the inserted text. The value -is @code{nil}. -@end deffn - -@deffn Command self-insert-command count -@cindex character insertion -@cindex self-insertion -This command inserts the last character typed; it does so @var{count} -times, before point, and returns @code{nil}. Most printing characters -are bound to this command. In routine use, @code{self-insert-command} -is the most frequently called function in Emacs, but programs rarely use -it except to install it on a keymap. - -In an interactive call, @var{count} is the numeric prefix argument. - -Self-insertion translates the input character through -@code{translation-table-for-input}. @xref{Translation of Characters}. - -This command calls @code{auto-fill-function} whenever that is -non-@code{nil} and the character inserted is in the table -@code{auto-fill-chars} (@pxref{Auto Filling}). - -@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 -This command performs abbrev expansion if Abbrev mode is enabled and -the inserted character does not have word-constituent -syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also -responsible for calling @code{blink-paren-function} when the inserted -character has close parenthesis syntax (@pxref{Blinking}). - -Do not try substituting your own definition of -@code{self-insert-command} for the standard one. The editor command -loop handles this function specially. -@end deffn - -@deffn Command newline &optional number-of-newlines -This command inserts newlines into the current buffer before point. -If @var{number-of-newlines} is supplied, that many newline characters -are inserted. - -@cindex newline and Auto Fill mode -This function calls @code{auto-fill-function} if the current column -number is greater than the value of @code{fill-column} and -@var{number-of-newlines} is @code{nil}. Typically what -@code{auto-fill-function} does is insert a newline; thus, the overall -result in this case is to insert two newlines at different places: one -at point, and another earlier in the line. @code{newline} does not -auto-fill if @var{number-of-newlines} is non-@code{nil}. - -This command indents to the left margin if that is not zero. -@xref{Margins}. - -The value returned is @code{nil}. In an interactive call, @var{count} -is the numeric prefix argument. -@end deffn - -@defvar overwrite-mode -This variable controls whether overwrite mode is in effect. The value -should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, -or @code{nil}. @code{overwrite-mode-textual} specifies textual -overwrite mode (treats newlines and tabs specially), and -@code{overwrite-mode-binary} specifies binary overwrite mode (treats -newlines and tabs like any other characters). -@end defvar - -@node Deletion -@section Deleting Text -@cindex text deletion - -@cindex deleting text vs killing - Deletion means removing part of the text in a buffer, without saving -it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be -yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). -Some deletion functions do save text in the kill ring in some special -cases. - - All of the deletion functions operate on the current buffer. - -@deffn Command erase-buffer -This function deletes the entire text of the current buffer -(@emph{not} just the accessible portion), leaving it -empty. If the buffer is read-only, it signals a @code{buffer-read-only} -error; if some of the text in it is read-only, it signals a -@code{text-read-only} error. Otherwise, it deletes the text without -asking for any confirmation. It returns @code{nil}. - -Normally, deleting a large amount of text from a buffer inhibits further -auto-saving of that buffer ``because it has shrunk.'' However, -@code{erase-buffer} does not do this, the idea being that the future -text is not really related to the former text, and its size should not -be compared with that of the former text. -@end deffn - -@deffn Command delete-region start end -This command deletes the text between positions @var{start} and -@var{end} in the current buffer, and returns @code{nil}. If point was -inside the deleted region, its value afterward is @var{start}. -Otherwise, point relocates with the surrounding text, as markers do. -@end deffn - -@defun delete-and-extract-region start end -This function deletes the text between positions @var{start} and -@var{end} in the current buffer, and returns a string containing the -text just deleted. - -If point was inside the deleted region, its value afterward is -@var{start}. Otherwise, point relocates with the surrounding text, as -markers do. -@end defun - -@deffn Command delete-char count &optional killp -This command deletes @var{count} characters directly after point, or -before point if @var{count} is negative. If @var{killp} is -non-@code{nil}, then it saves the deleted characters in the kill ring. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@deffn Command delete-backward-char count &optional killp -@cindex deleting previous char -This command deletes @var{count} characters directly before point, or -after point if @var{count} is negative. If @var{killp} is -non-@code{nil}, then it saves the deleted characters in the kill ring. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@deffn Command backward-delete-char-untabify count &optional killp -@cindex tab deletion -This command deletes @var{count} characters backward, changing tabs -into spaces. When the next character to be deleted is a tab, it is -first replaced with the proper number of spaces to preserve alignment -and then one of those spaces is deleted instead of the tab. If -@var{killp} is non-@code{nil}, then the command saves the deleted -characters in the kill ring. - -Conversion of tabs to spaces happens only if @var{count} is positive. -If it is negative, exactly @minus{}@var{count} characters after point -are deleted. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@defopt backward-delete-char-untabify-method -This option specifies how @code{backward-delete-char-untabify} should -deal with whitespace. Possible values include @code{untabify}, the -default, meaning convert a tab to many spaces and delete one; -@code{hungry}, meaning delete all tabs and spaces before point with -one command; @code{all} meaning delete all tabs, spaces and newlines -before point, and @code{nil}, meaning do nothing special for -whitespace characters. -@end defopt - -@node User-Level Deletion -@section User-Level Deletion Commands - - This section describes higher-level commands for deleting text, -commands intended primarily for the user but useful also in Lisp -programs. - -@deffn Command delete-horizontal-space &optional backward-only -@cindex deleting whitespace -This function deletes all spaces and tabs around point. It returns -@code{nil}. - -If @var{backward-only} is non-@code{nil}, the function deletes -spaces and tabs before point, but not after point. - -In the following examples, we call @code{delete-horizontal-space} four -times, once on each line, with point between the second and third -characters on the line each time. - -@example -@group ----------- Buffer: foo ---------- -I @point{}thought -I @point{} thought -We@point{} thought -Yo@point{}u thought ----------- Buffer: foo ---------- -@end group - -@group -(delete-horizontal-space) ; @r{Four times.} - @result{} nil - ----------- Buffer: foo ---------- -Ithought -Ithought -Wethought -You thought ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command delete-indentation &optional join-following-p -This function joins the line point is on to the previous line, deleting -any whitespace at the join and in some cases replacing it with one -space. If @var{join-following-p} is non-@code{nil}, -@code{delete-indentation} joins this line to the following line -instead. The function returns @code{nil}. - -If there is a fill prefix, and the second of the lines being joined -starts with the prefix, then @code{delete-indentation} deletes the -fill prefix before joining the lines. @xref{Margins}. - -In the example below, point is located on the line starting -@samp{events}, and it makes no difference if there are trailing spaces -in the preceding line. - -@smallexample -@group ----------- Buffer: foo ---------- -When in the course of human -@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group - -(delete-indentation) - @result{} nil - -@group ----------- Buffer: foo ---------- -When in the course of human@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group -@end smallexample - -After the lines are joined, the function @code{fixup-whitespace} is -responsible for deciding whether to leave a space at the junction. -@end deffn - -@deffn Command fixup-whitespace -This function replaces all the horizontal whitespace surrounding point -with either one space or no space, according to the context. It -returns @code{nil}. - -At the beginning or end of a line, the appropriate amount of space is -none. Before a character with close parenthesis syntax, or after a -character with open parenthesis or expression-prefix syntax, no space is -also appropriate. Otherwise, one space is appropriate. @xref{Syntax -Class Table}. - -In the example below, @code{fixup-whitespace} is called the first time -with point before the word @samp{spaces} in the first line. For the -second invocation, point is directly after the @samp{(}. - -@smallexample -@group ----------- Buffer: foo ---------- -This has too many @point{}spaces -This has too many spaces at the start of (@point{} this list) ----------- Buffer: foo ---------- -@end group - -@group -(fixup-whitespace) - @result{} nil -(fixup-whitespace) - @result{} nil -@end group - -@group ----------- Buffer: foo ---------- -This has too many spaces -This has too many spaces at the start of (this list) ----------- Buffer: foo ---------- -@end group -@end smallexample -@end deffn - -@deffn Command just-one-space &optional n -@comment !!SourceFile simple.el -This command replaces any spaces and tabs around point with a single -space, or @var{n} spaces if @var{n} is specified. It returns -@code{nil}. -@end deffn - -@deffn Command delete-blank-lines -This function deletes blank lines surrounding point. If point is on a -blank line with one or more blank lines before or after it, then all but -one of them are deleted. If point is on an isolated blank line, then it -is deleted. If point is on a nonblank line, the command deletes all -blank lines immediately following it. - -A blank line is defined as a line containing only tabs and spaces. - -@code{delete-blank-lines} returns @code{nil}. -@end deffn - -@node The Kill Ring -@section The Kill Ring -@cindex kill ring - - @dfn{Kill functions} delete text like the deletion functions, but save -it so that the user can reinsert it by @dfn{yanking}. Most of these -functions have @samp{kill-} in their name. By contrast, the functions -whose names start with @samp{delete-} normally do not save text for -yanking (though they can still be undone); these are ``deletion'' -functions. - - Most of the kill commands are primarily for interactive use, and are -not described here. What we do describe are the functions provided for -use in writing such commands. You can use these functions to write -commands for killing text. When you need to delete text for internal -purposes within a Lisp function, you should normally use deletion -functions, so as not to disturb the kill ring contents. -@xref{Deletion}. - - Killed text is saved for later yanking in the @dfn{kill ring}. This -is a list that holds a number of recent kills, not just the last text -kill. We call this a ``ring'' because yanking treats it as having -elements in a cyclic order. The list is kept in the variable -@code{kill-ring}, and can be operated on with the usual functions for -lists; there are also specialized functions, described in this section, -that treat it as a ring. - - Some people think this use of the word ``kill'' is unfortunate, since -it refers to operations that specifically @emph{do not} destroy the -entities ``killed.'' This is in sharp contrast to ordinary life, in -which death is permanent and ``killed'' entities do not come back to -life. Therefore, other metaphors have been proposed. For example, the -term ``cut ring'' makes sense to people who, in pre-computer days, used -scissors and paste to cut up and rearrange manuscripts. However, it -would be difficult to change the terminology now. - -@menu -* 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. -@end menu - -@node Kill Ring Concepts -@comment node-name, next, previous, up -@subsection Kill Ring Concepts - - The kill ring records killed text as strings in a list, most recent -first. A short kill ring, for example, might look like this: - -@example -("some text" "a different piece of text" "even older text") -@end example - -@noindent -When the list reaches @code{kill-ring-max} entries in length, adding a -new entry automatically deletes the last entry. - - When kill commands are interwoven with other commands, each kill -command makes a new entry in the kill ring. Multiple kill commands in -succession build up a single kill ring entry, which would be yanked as a -unit; the second and subsequent consecutive kill commands add text to -the entry made by the first one. - - For yanking, one entry in the kill ring is designated the ``front'' of -the ring. Some yank commands ``rotate'' the ring by designating a -different element as the ``front.'' But this virtual rotation doesn't -change the list itself---the most recent entry always comes first in the -list. - -@node Kill Functions -@comment node-name, next, previous, up -@subsection Functions for Killing - - @code{kill-region} is the usual subroutine for killing text. Any -command that calls this function is a ``kill command'' (and should -probably have @samp{kill} in its name). @code{kill-region} puts the -newly killed text in a new element at the beginning of the kill ring or -adds it to the most recent element. It determines automatically (using -@code{last-command}) whether the previous command was a kill command, -and if so appends the killed text to the most recent entry. - -@deffn Command kill-region start end &optional yank-handler -This function kills the text in the region defined by @var{start} and -@var{end}. The text is deleted but saved in the kill ring, along with -its text properties. The value is always @code{nil}. - -In an interactive call, @var{start} and @var{end} are point and -the mark. - -@c Emacs 19 feature -If the buffer or text is read-only, @code{kill-region} modifies the kill -ring just the same, then signals an error without modifying the buffer. -This is convenient because it lets the user use a series of kill -commands to copy text from a read-only buffer into the kill ring. - -If @var{yank-handler} is non-@code{nil}, this puts that value onto -the string of killed text, as a @code{yank-handler} text property. -@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any -@code{yank-handler} properties present on the killed text are copied -onto the kill ring, like other text properties. -@end deffn - -@defopt kill-read-only-ok -If this option is non-@code{nil}, @code{kill-region} does not signal an -error if the buffer or text is read-only. Instead, it simply returns, -updating the kill ring but not changing the buffer. -@end defopt - -@deffn Command copy-region-as-kill start end -This command saves the region defined by @var{start} and @var{end} on -the kill ring (including text properties), but does not delete the text -from the buffer. It returns @code{nil}. - -The command does not set @code{this-command} to @code{kill-region}, so a -subsequent kill command does not append to the same kill ring entry. - -Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to -support Emacs 18. For newer Emacs versions, it is better to use -@code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill -Ring}. -@end deffn - -@node Yanking -@subsection Yanking - - Yanking means inserting text from the kill ring, but it does -not insert the text blindly. Yank commands and some other commands -use @code{insert-for-yank} to perform special processing on the -text that they copy into the buffer. - -@defun insert-for-yank string -This function normally works like @code{insert} except that it doesn't -insert the text properties in the @code{yank-excluded-properties} -list. However, if any part of @var{string} has a non-@code{nil} -@code{yank-handler} text property, that property can do various -special processing on that part of the text being inserted. -@end defun - -@defun insert-buffer-substring-as-yank buf &optional start end -This function resembles @code{insert-buffer-substring} except that it -doesn't insert the text properties in the -@code{yank-excluded-properties} list. -@end defun - - You can put a @code{yank-handler} text property on all or part of -the text to control how it will be inserted if it is yanked. The -@code{insert-for-yank} function looks for that property. The property -value must be a list of one to four elements, with the following -format (where elements after the first may be omitted): - -@example -(@var{function} @var{param} @var{noexclude} @var{undo}) -@end example - - Here is what the elements do: - -@table @var -@item function -When @var{function} is present and non-@code{nil}, it is called instead of -@code{insert} to insert the string. @var{function} takes one -argument---the string to insert. - -@item param -If @var{param} is present and non-@code{nil}, it replaces @var{string} -(or the part of @var{string} being processed) as the object passed to -@var{function} (or @code{insert}); for example, if @var{function} is -@code{yank-rectangle}, @var{param} should be a list of strings to -insert as a rectangle. - -@item noexclude -If @var{noexclude} is present and non-@code{nil}, the normal removal of the -yank-excluded-properties is not performed; instead @var{function} is -responsible for removing those properties. This may be necessary -if @var{function} adjusts point before or after inserting the object. - -@item undo -If @var{undo} is present and non-@code{nil}, it is a function that will be -called by @code{yank-pop} to undo the insertion of the current object. -It is called with two arguments, the start and end of the current -region. @var{function} can set @code{yank-undo-function} to override -the @var{undo} value. -@end table - -@node Yank Commands -@comment node-name, next, previous, up -@subsection Functions for Yanking - - This section describes higher-level commands for yanking, which are -intended primarily for the user but useful also in Lisp programs. -Both @code{yank} and @code{yank-pop} honor the -@code{yank-excluded-properties} variable and @code{yank-handler} text -property (@pxref{Yanking}). - -@deffn Command yank &optional arg -@cindex inserting killed text -This command inserts before point the text at the front of the -kill ring. It positions the mark at the beginning of that text, and -point at the end. - -If @var{arg} is a non-@code{nil} list (which occurs interactively when -the user types @kbd{C-u} with no digits), then @code{yank} inserts the -text as described above, but puts point before the yanked text and -puts the mark after it. - -If @var{arg} is a number, then @code{yank} inserts the @var{arg}th -most recently killed text---the @var{arg}th element of the kill ring -list, counted cyclically from the front, which is considered the -first element for this purpose. - -@code{yank} does not alter the contents of the kill ring, unless it -used text provided by another program, in which case it pushes that text -onto the kill ring. However if @var{arg} is an integer different from -one, it rotates the kill ring to place the yanked string at the front. - -@code{yank} returns @code{nil}. -@end deffn - -@deffn Command yank-pop &optional arg -This command replaces the just-yanked entry from the kill ring with a -different entry from the kill ring. - -This is allowed only immediately after a @code{yank} or another -@code{yank-pop}. At such a time, the region contains text that was just -inserted by yanking. @code{yank-pop} deletes that text and inserts in -its place a different piece of killed text. It does not add the deleted -text to the kill ring, since it is already in the kill ring somewhere. -It does however rotate the kill ring to place the newly yanked string at -the front. - -If @var{arg} is @code{nil}, then the replacement text is the previous -element of the kill ring. If @var{arg} is numeric, the replacement is -the @var{arg}th previous kill. If @var{arg} is negative, a more recent -kill is the replacement. - -The sequence of kills in the kill ring wraps around, so that after the -oldest one comes the newest one, and before the newest one goes the -oldest. - -The return value is always @code{nil}. -@end deffn - -@defvar yank-undo-function -If this variable is non-@code{nil}, the function @code{yank-pop} uses -its value instead of @code{delete-region} to delete the text -inserted by the previous @code{yank} or -@code{yank-pop} command. The value must be a function of two -arguments, the start and end of the current region. - -The function @code{insert-for-yank} automatically sets this variable -according to the @var{undo} element of the @code{yank-handler} -text property, if there is one. -@end defvar - -@node Low-Level Kill Ring -@subsection Low-Level Kill Ring - - These functions and variables provide access to the kill ring at a -lower level, but still convenient for use in Lisp programs, because they -take care of interaction with window system selections -(@pxref{Window System Selections}). - -@defun current-kill n &optional do-not-move -The function @code{current-kill} rotates the yanking pointer, which -designates the ``front'' of the kill ring, by @var{n} places (from newer -kills to older ones), and returns the text at that place in the ring. - -If the optional second argument @var{do-not-move} is non-@code{nil}, -then @code{current-kill} doesn't alter the yanking pointer; it just -returns the @var{n}th kill, counting from the current yanking pointer. - -If @var{n} is zero, indicating a request for the latest kill, -@code{current-kill} calls the value of -@code{interprogram-paste-function} (documented below) before -consulting the kill ring. If that value is a function and calling it -returns a string, @code{current-kill} pushes that string onto the kill -ring and returns it. It also sets the yanking pointer to point to -that new entry, regardless of the value of @var{do-not-move}. -Otherwise, @code{current-kill} does not treat a zero value for @var{n} -specially: it returns the entry pointed at by the yanking pointer and -does not move the yanking pointer. -@end defun - -@defun kill-new string &optional replace yank-handler -This function pushes the text @var{string} onto the kill ring and -makes the yanking pointer point to it. It discards the oldest entry -if appropriate. It also invokes the value of -@code{interprogram-cut-function} (see below). - -If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the -first element of the kill ring with @var{string}, rather than pushing -@var{string} onto the kill ring. - -If @var{yank-handler} is non-@code{nil}, this puts that value onto -the string of killed text, as a @code{yank-handler} property. -@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then -@code{kill-new} copies any @code{yank-handler} properties present on -@var{string} onto the kill ring, as it does with other text properties. -@end defun - -@defun kill-append string before-p &optional yank-handler -This function appends the text @var{string} to the first entry in the -kill ring and makes the yanking pointer point to the combined entry. -Normally @var{string} goes at the end of the entry, but if -@var{before-p} is non-@code{nil}, it goes at the beginning. This -function also invokes the value of @code{interprogram-cut-function} -(see below). This handles @var{yank-handler} just like -@code{kill-new}, except that if @var{yank-handler} is different from -the @code{yank-handler} property of the first entry of the kill ring, -@code{kill-append} pushes the concatenated string onto the kill ring, -instead of replacing the original first entry with it. -@end defun - -@defvar interprogram-paste-function -This variable provides a way of transferring killed text from other -programs, when you are using a window system. Its value should be -@code{nil} or a function of no arguments. - -If the value is a function, @code{current-kill} calls it to get the -``most recent kill.'' If the function returns a non-@code{nil} value, -then that value is used as the ``most recent kill.'' If it returns -@code{nil}, then the front of the kill ring is used. - -The normal use of this hook is to get the window system's primary -selection as the most recent kill, even if the selection belongs to -another application. @xref{Window System Selections}. -@end defvar - -@defvar interprogram-cut-function -This variable provides a way of communicating killed text to other -programs, when you are using a window system. Its value should be -@code{nil} or a function of one required and one optional argument. - -If the value is a function, @code{kill-new} and @code{kill-append} call -it with the new first element of the kill ring as the first argument. -The second, optional, argument has the same meaning as the @var{push} -argument to @code{x-set-cut-buffer} (@pxref{Definition of -x-set-cut-buffer}) and only affects the second and later cut buffers. - -The normal use of this hook is to set the window system's primary -selection (and first cut buffer) from the newly killed text. -@xref{Window System Selections}. -@end defvar - -@node Internals of Kill Ring -@comment node-name, next, previous, up -@subsection Internals of the Kill Ring - - The variable @code{kill-ring} holds the kill ring contents, in the -form of a list of strings. The most recent kill is always at the front -of the list. - - The @code{kill-ring-yank-pointer} variable points to a link in the -kill ring list, whose @sc{car} is the text to yank next. We say it -identifies the ``front'' of the ring. Moving -@code{kill-ring-yank-pointer} to a different link is called -@dfn{rotating the kill ring}. We call the kill ring a ``ring'' because -the functions that move the yank pointer wrap around from the end of the -list to the beginning, or vice-versa. Rotation of the kill ring is -virtual; it does not change the value of @code{kill-ring}. - - Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp -variables whose values are normally lists. The word ``pointer'' in the -name of the @code{kill-ring-yank-pointer} indicates that the variable's -purpose is to identify one element of the list for use by the next yank -command. - - The value of @code{kill-ring-yank-pointer} is always @code{eq} to one -of the links in the kill ring list. The element it identifies is the -@sc{car} of that link. Kill commands, which change the kill ring, also -set this variable to the value of @code{kill-ring}. The effect is to -rotate the ring so that the newly killed text is at the front. - - Here is a diagram that shows the variable @code{kill-ring-yank-pointer} -pointing to the second entry in the kill ring @code{("some text" "a -different piece of text" "yet older text")}. - -@example -@group -kill-ring ---- kill-ring-yank-pointer - | | - | v - | --- --- --- --- --- --- - --> | | |------> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - | | -->"yet older text" - | | - | --> "a different piece of text" - | - --> "some text" -@end group -@end example - -@noindent -This state of affairs might occur after @kbd{C-y} (@code{yank}) -immediately followed by @kbd{M-y} (@code{yank-pop}). - -@defvar kill-ring -This variable holds the list of killed text sequences, most recently -killed first. -@end defvar - -@defvar kill-ring-yank-pointer -This variable's value indicates which element of the kill ring is at the -``front'' of the ring for yanking. More precisely, the value is a tail -of the value of @code{kill-ring}, and its @sc{car} is the kill string -that @kbd{C-y} should yank. -@end defvar - -@defopt kill-ring-max -The value of this variable is the maximum length to which the kill -ring can grow, before elements are thrown away at the end. The default -value for @code{kill-ring-max} is 60. -@end defopt - -@node Undo -@comment node-name, next, previous, up -@section Undo -@cindex redo - - Most buffers have an @dfn{undo list}, which records all changes made -to the buffer's text so that they can be undone. (The buffers that -don't have one are usually special-purpose buffers for which Emacs -assumes that undoing is not useful. In particular, any buffer whose -name begins with a space has its undo recording off by default; -see @ref{Buffer Names}.) All the primitives that modify the -text in the buffer automatically add elements to the front of the undo -list, which is in the variable @code{buffer-undo-list}. - -@defvar buffer-undo-list -This buffer-local variable's value is the undo list of the current -buffer. A value of @code{t} disables the recording of undo information. -@end defvar - -Here are the kinds of elements an undo list can have: - -@table @code -@item @var{position} -This kind of element records a previous value of point; undoing this -element moves point to @var{position}. Ordinary cursor motion does not -make any sort of undo record, but deletion operations use these entries -to record where point was before the command. - -@item (@var{beg} . @var{end}) -This kind of element indicates how to delete text that was inserted. -Upon insertion, the text occupied the range @var{beg}--@var{end} in the -buffer. - -@item (@var{text} . @var{position}) -This kind of element indicates how to reinsert text that was deleted. -The deleted text itself is the string @var{text}. The place to -reinsert it is @code{(abs @var{position})}. If @var{position} is -positive, point was at the beginning of the deleted text, otherwise it -was at the end. - -@item (t @var{high} . @var{low}) -This kind of element indicates that an unmodified buffer became -modified. The elements @var{high} and @var{low} are two integers, each -recording 16 bits of the visited file's modification time as of when it -was previously visited or saved. @code{primitive-undo} uses those -values to determine whether to mark the buffer as unmodified once again; -it does so only if the file's modification time matches those numbers. - -@item (nil @var{property} @var{value} @var{beg} . @var{end}) -This kind of element records a change in a text property. -Here's how you might undo the change: - -@example -(put-text-property @var{beg} @var{end} @var{property} @var{value}) -@end example - -@item (@var{marker} . @var{adjustment}) -This kind of element records the fact that the marker @var{marker} was -relocated due to deletion of surrounding text, and that it moved -@var{adjustment} character positions. Undoing this element moves -@var{marker} @minus{} @var{adjustment} characters. - -@item (apply @var{funname} . @var{args}) -This is an extensible undo item, which is undone by calling -@var{funname} with arguments @var{args}. - -@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args}) -This is an extensible undo item, which records a change limited to the -range @var{beg} to @var{end}, which increased the size of the buffer -by @var{delta}. It is undone by calling @var{funname} with arguments -@var{args}. - -This kind of element enables undo limited to a region to determine -whether the element pertains to that region. - -@item nil -This element is a boundary. The elements between two boundaries are -called a @dfn{change group}; normally, each change group corresponds to -one keyboard command, and undo commands normally undo an entire group as -a unit. -@end table - -@defun undo-boundary -This function places a boundary element in the undo list. The undo -command stops at such a boundary, and successive undo commands undo -to earlier and earlier boundaries. This function returns @code{nil}. - -The editor command loop automatically creates an undo boundary before -each key sequence is executed. Thus, each undo normally undoes the -effects of one command. Self-inserting input characters are an -exception. The command loop makes a boundary for the first such -character; the next 19 consecutive self-inserting input characters do -not make boundaries, and then the 20th does, and so on as long as -self-inserting characters continue. - -All buffer modifications add a boundary whenever the previous undoable -change was made in some other buffer. This is to ensure that -each command makes a boundary in each buffer where it makes changes. - -Calling this function explicitly is useful for splitting the effects of -a command into more than one unit. For example, @code{query-replace} -calls @code{undo-boundary} after each replacement, so that the user can -undo individual replacements one by one. -@end defun - -@defvar undo-in-progress -This variable is normally @code{nil}, but the undo commands bind it to -@code{t}. This is so that various kinds of change hooks can tell when -they're being called for the sake of undoing. -@end defvar - -@defun primitive-undo count list -This is the basic function for undoing elements of an undo list. -It undoes the first @var{count} elements of @var{list}, returning -the rest of @var{list}. - -@code{primitive-undo} adds elements to the buffer's undo list when it -changes the buffer. Undo commands avoid confusion by saving the undo -list value at the beginning of a sequence of undo operations. Then the -undo operations use and update the saved value. The new elements added -by undoing are not part of this saved value, so they don't interfere with -continuing to undo. - -This function does not bind @code{undo-in-progress}. -@end defun - -@node Maintaining Undo -@section Maintaining Undo Lists - - This section describes how to enable and disable undo information for -a given buffer. It also explains how the undo list is truncated -automatically so it doesn't get too big. - - Recording of undo information in a newly created buffer is normally -enabled to start with; but if the buffer name starts with a space, the -undo recording is initially disabled. You can explicitly enable or -disable undo recording with the following two functions, or by setting -@code{buffer-undo-list} yourself. - -@deffn Command buffer-enable-undo &optional buffer-or-name -This command enables recording undo information for buffer -@var{buffer-or-name}, so that subsequent changes can be undone. If no -argument is supplied, then the current buffer is used. This function -does nothing if undo recording is already enabled in the buffer. It -returns @code{nil}. - -In an interactive call, @var{buffer-or-name} is the current buffer. -You cannot specify any other buffer. -@end deffn - -@deffn Command buffer-disable-undo &optional buffer-or-name -@cindex disabling undo -This function discards the undo list of @var{buffer-or-name}, and disables -further recording of undo information. As a result, it is no longer -possible to undo either previous changes or any subsequent changes. If -the undo list of @var{buffer-or-name} is already disabled, this function -has no effect. - -This function returns @code{nil}. -@end deffn - - As editing continues, undo lists get longer and longer. To prevent -them from using up all available memory space, garbage collection trims -them back to size limits you can set. (For this purpose, the ``size'' -of an undo list measures the cons cells that make up the list, plus the -strings of deleted text.) Three variables control the range of acceptable -sizes: @code{undo-limit}, @code{undo-strong-limit} and -@code{undo-outer-limit}. In these variables, size is counted as the -number of bytes occupied, which includes both saved text and other -data. - -@defopt undo-limit -This is the soft limit for the acceptable size of an undo list. The -change group at which this size is exceeded is the last one kept. -@end defopt - -@defopt undo-strong-limit -This is the upper limit for the acceptable size of an undo list. The -change group at which this size is exceeded is discarded itself (along -with all older change groups). There is one exception: the very latest -change group is only discarded if it exceeds @code{undo-outer-limit}. -@end defopt - -@defopt undo-outer-limit -If at garbage collection time the undo info for the current command -exceeds this limit, Emacs discards the info and displays a warning. -This is a last ditch limit to prevent memory overflow. -@end defopt - -@defopt undo-ask-before-discard -If this variable is non-@code{nil}, when the undo info exceeds -@code{undo-outer-limit}, Emacs asks in the echo area whether to -discard the info. The default value is @code{nil}, which means to -discard it automatically. - -This option is mainly intended for debugging. Garbage collection is -inhibited while the question is asked, which means that Emacs might -leak memory if the user waits too long before answering the question. -@end defopt - -@node Filling -@comment node-name, next, previous, up -@section Filling -@cindex filling text - - @dfn{Filling} means adjusting the lengths of lines (by moving the line -breaks) so that they are nearly (but no greater than) a specified -maximum width. Additionally, lines can be @dfn{justified}, which means -inserting spaces to make the left and/or right margins line up -precisely. The width is controlled by the variable @code{fill-column}. -For ease of reading, lines should be no longer than 70 or so columns. - - You can use Auto Fill mode (@pxref{Auto Filling}) to fill text -automatically as you insert it, but changes to existing text may leave -it improperly filled. Then you must fill the text explicitly. - - Most of the commands in this section return values that are not -meaningful. All the functions that do filling take note of the current -left margin, current right margin, and current justification style -(@pxref{Margins}). If the current justification style is -@code{none}, the filling functions don't actually do anything. - - Several of the filling functions have an argument @var{justify}. -If it is non-@code{nil}, that requests some kind of justification. It -can be @code{left}, @code{right}, @code{full}, or @code{center}, to -request a specific style of justification. If it is @code{t}, that -means to use the current justification style for this part of the text -(see @code{current-justification}, below). Any other value is treated -as @code{full}. - - When you call the filling functions interactively, using a prefix -argument implies the value @code{full} for @var{justify}. - -@deffn Command fill-paragraph justify -This command fills the paragraph at or after point. If -@var{justify} is non-@code{nil}, each line is justified as well. -It uses the ordinary paragraph motion commands to find paragraph -boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}. -@end deffn - -@deffn Command fill-region start end &optional justify nosqueeze to-eop -This command fills each of the paragraphs in the region from @var{start} -to @var{end}. It justifies as well if @var{justify} is -non-@code{nil}. - -If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace -other than line breaks untouched. If @var{to-eop} is non-@code{nil}, -that means to keep filling to the end of the paragraph---or the next hard -newline, if @code{use-hard-newlines} is enabled (see below). - -The variable @code{paragraph-separate} controls how to distinguish -paragraphs. @xref{Standard Regexps}. -@end deffn - -@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp -This command fills each paragraph in the region according to its -individual fill prefix. Thus, if the lines of a paragraph were indented -with spaces, the filled paragraph will remain indented in the same -fashion. - -The first two arguments, @var{start} and @var{end}, are the beginning -and end of the region to be filled. The third and fourth arguments, -@var{justify} and @var{citation-regexp}, are optional. If -@var{justify} is non-@code{nil}, the paragraphs are justified as -well as filled. If @var{citation-regexp} is non-@code{nil}, it means the -function is operating on a mail message and therefore should not fill -the header lines. If @var{citation-regexp} is a string, it is used as -a regular expression; if it matches the beginning of a line, that line -is treated as a citation marker. - -Ordinarily, @code{fill-individual-paragraphs} regards each change in -indentation as starting a new paragraph. If -@code{fill-individual-varying-indent} is non-@code{nil}, then only -separator lines separate paragraphs. That mode can handle indented -paragraphs with additional indentation on the first line. -@end deffn - -@defopt fill-individual-varying-indent -This variable alters the action of @code{fill-individual-paragraphs} as -described above. -@end defopt - -@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after -This command considers a region of text as a single paragraph and fills -it. If the region was made up of many paragraphs, the blank lines -between paragraphs are removed. This function justifies as well as -filling when @var{justify} is non-@code{nil}. - -If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace -other than line breaks untouched. If @var{squeeze-after} is -non-@code{nil}, it specifies a position in the region, and means don't -canonicalize spaces before that position. - -In Adaptive Fill mode, this command calls @code{fill-context-prefix} to -choose a fill prefix by default. @xref{Adaptive Fill}. -@end deffn - -@deffn Command justify-current-line &optional how eop nosqueeze -This command inserts spaces between the words of the current line so -that the line ends exactly at @code{fill-column}. It returns -@code{nil}. - -The argument @var{how}, if non-@code{nil} specifies explicitly the style -of justification. It can be @code{left}, @code{right}, @code{full}, -@code{center}, or @code{none}. If it is @code{t}, that means to do -follow specified justification style (see @code{current-justification}, -below). @code{nil} means to do full justification. - -If @var{eop} is non-@code{nil}, that means do only left-justification -if @code{current-justification} specifies full justification. This is -used for the last line of a paragraph; even if the paragraph as a -whole is fully justified, the last line should not be. - -If @var{nosqueeze} is non-@code{nil}, that means do not change interior -whitespace. -@end deffn - -@defopt default-justification -This variable's value specifies the style of justification to use for -text that doesn't specify a style with a text property. The possible -values are @code{left}, @code{right}, @code{full}, @code{center}, or -@code{none}. The default value is @code{left}. -@end defopt - -@defun current-justification -This function returns the proper justification style to use for filling -the text around point. - -This returns the value of the @code{justification} text property at -point, or the variable @var{default-justification} if there is no such -text property. However, it returns @code{nil} rather than @code{none} -to mean ``don't justify''. -@end defun - -@defopt sentence-end-double-space -@anchor{Definition of sentence-end-double-space} -If this variable is non-@code{nil}, a period followed by just one space -does not count as the end of a sentence, and the filling functions -avoid breaking the line at such a place. -@end defopt - -@defopt sentence-end-without-period -If this variable is non-@code{nil}, a sentence can end without a -period. This is used for languages like Thai, where sentences end -with a double space but without a period. -@end defopt - -@defopt sentence-end-without-space -If this variable is non-@code{nil}, it should be a string of -characters that can end a sentence without following spaces. -@end defopt - -@defvar fill-paragraph-function -This variable provides a way for major modes to override the filling of -paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls -this function to do the work. If the function returns a non-@code{nil} -value, @code{fill-paragraph} assumes the job is done, and immediately -returns that value. - -The usual use of this feature is to fill comments in programming -language modes. If the function needs to fill a paragraph in the usual -way, it can do so as follows: - -@example -(let ((fill-paragraph-function nil)) - (fill-paragraph arg)) -@end example -@end defvar - -@defvar use-hard-newlines -If this variable is non-@code{nil}, the filling functions do not delete -newlines that have the @code{hard} text property. These ``hard -newlines'' act as paragraph separators. -@end defvar - -@node Margins -@section Margins for Filling - -@defopt fill-prefix -This buffer-local variable, if non-@code{nil}, specifies a string of -text that appears at the beginning of normal text lines and should be -disregarded when filling them. Any line that fails to start with the -fill prefix is considered the start of a paragraph; so is any line -that starts with the fill prefix followed by additional whitespace. -Lines that start with the fill prefix but no additional whitespace are -ordinary text lines that can be filled together. The resulting filled -lines also start with the fill prefix. - -The fill prefix follows the left margin whitespace, if any. -@end defopt - -@defopt fill-column -This buffer-local variable specifies the maximum width of filled lines. -Its value should be an integer, which is a number of columns. All the -filling, justification, and centering commands are affected by this -variable, including Auto Fill mode (@pxref{Auto Filling}). - -As a practical matter, if you are writing text for other people to -read, you should set @code{fill-column} to no more than 70. Otherwise -the line will be too long for people to read comfortably, and this can -make the text seem clumsy. -@end defopt - -@defvar default-fill-column -The value of this variable is the default value for @code{fill-column} in -buffers that do not override it. This is the same as -@code{(default-value 'fill-column)}. - -The default value for @code{default-fill-column} is 70. -@end defvar - -@deffn Command set-left-margin from to margin -This sets the @code{left-margin} property on the text from @var{from} to -@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this -command also refills the region to fit the new margin. -@end deffn - -@deffn Command set-right-margin from to margin -This sets the @code{right-margin} property on the text from @var{from} -to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, -this command also refills the region to fit the new margin. -@end deffn - -@defun current-left-margin -This function returns the proper left margin value to use for filling -the text around point. The value is the sum of the @code{left-margin} -property of the character at the start of the current line (or zero if -none), and the value of the variable @code{left-margin}. -@end defun - -@defun current-fill-column -This function returns the proper fill column value to use for filling -the text around point. The value is the value of the @code{fill-column} -variable, minus the value of the @code{right-margin} property of the -character after point. -@end defun - -@deffn Command move-to-left-margin &optional n force -This function moves point to the left margin of the current line. The -column moved to is determined by calling the function -@code{current-left-margin}. If the argument @var{n} is non-@code{nil}, -@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first. - -If @var{force} is non-@code{nil}, that says to fix the line's -indentation if that doesn't match the left margin value. -@end deffn - -@defun delete-to-left-margin &optional from to -This function removes left margin indentation from the text between -@var{from} and @var{to}. The amount of indentation to delete is -determined by calling @code{current-left-margin}. In no case does this -function delete non-whitespace. If @var{from} and @var{to} are omitted, -they default to the whole buffer. -@end defun - -@defun indent-to-left-margin -This function adjusts the indentation at the beginning of the current -line to the value specified by the variable @code{left-margin}. (That -may involve either inserting or deleting whitespace.) This function -is value of @code{indent-line-function} in Paragraph-Indent Text mode. -@end defun - -@defvar left-margin -This variable specifies the base left margin column. In Fundamental -mode, @kbd{C-j} indents to this column. This variable automatically -becomes buffer-local when set in any fashion. -@end defvar - -@defvar fill-nobreak-predicate -This variable gives major modes a way to specify not to break a line -at certain places. Its value should be a list of functions. Whenever -filling considers breaking the line at a certain place in the buffer, -it calls each of these functions with no arguments and with point -located at that place. If any of the functions returns -non-@code{nil}, then the line won't be broken there. -@end defvar - -@node Adaptive Fill -@section Adaptive Fill Mode -@c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent. - - When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill -prefix automatically from the text in each paragraph being filled -rather than using a predetermined value. During filling, this fill -prefix gets inserted at the start of the second and subsequent lines -of the paragraph as described in @ref{Filling}, and in @ref{Auto -Filling}. - -@defopt adaptive-fill-mode -Adaptive Fill mode is enabled when this variable is non-@code{nil}. -It is @code{t} by default. -@end defopt - -@defun fill-context-prefix from to -This function implements the heart of Adaptive Fill mode; it chooses a -fill prefix based on the text between @var{from} and @var{to}, -typically the start and end of a paragraph. It does this by looking -at the first two lines of the paragraph, based on the variables -described below. -@c The optional argument first-line-regexp is not documented -@c because it exists for internal purposes and might be eliminated -@c in the future. - -Usually, this function returns the fill prefix, a string. However, -before doing this, the function makes a final check (not specially -mentioned in the following) that a line starting with this prefix -wouldn't look like the start of a paragraph. Should this happen, the -function signals the anomaly by returning @code{nil} instead. - -In detail, @code{fill-context-prefix} does this: - -@enumerate -@item -It takes a candidate for the fill prefix from the first line---it -tries first the function in @code{adaptive-fill-function} (if any), -then the regular expression @code{adaptive-fill-regexp} (see below). -The first non-@code{nil} result of these, or the empty string if -they're both @code{nil}, becomes the first line's candidate. -@item -If the paragraph has as yet only one line, the function tests the -validity of the prefix candidate just found. The function then -returns the candidate if it's valid, or a string of spaces otherwise. -(see the description of @code{adaptive-fill-first-line-regexp} below). -@item -When the paragraph already has two lines, the function next looks for -a prefix candidate on the second line, in just the same way it did for -the first line. If it doesn't find one, it returns @code{nil}. -@item -The function now compares the two candidate prefixes heuristically: if -the non-whitespace characters in the line 2 candidate occur in the -same order in the line 1 candidate, the function returns the line 2 -candidate. Otherwise, it returns the largest initial substring which -is common to both candidates (which might be the empty string). -@end enumerate -@end defun - -@defopt adaptive-fill-regexp -Adaptive Fill mode matches this regular expression against the text -starting after the left margin whitespace (if any) on a line; the -characters it matches are that line's candidate for the fill prefix. - -The default value matches whitespace with certain punctuation -characters intermingled. -@end defopt - -@defopt adaptive-fill-first-line-regexp -Used only in one-line paragraphs, this regular expression acts as an -additional check of the validity of the one available candidate fill -prefix: the candidate must match this regular expression, or match -@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} -replaces the candidate with a string of spaces ``of the same width'' -as it. - -The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which -matches only a string of whitespace. The effect of this default is to -force the fill prefixes found in one-line paragraphs always to be pure -whitespace. -@end defopt - -@defopt adaptive-fill-function -You can specify more complex ways of choosing a fill prefix -automatically by setting this variable to a function. The function is -called with point after the left margin (if any) of a line, and it -must preserve point. It should return either ``that line's'' fill -prefix or @code{nil}, meaning it has failed to determine a prefix. -@end defopt - -@node Auto Filling -@comment node-name, next, previous, up -@section Auto Filling -@cindex filling, automatic -@cindex Auto Fill mode - - Auto Fill mode is a minor mode that fills lines automatically as text -is inserted. This section describes the hook used by Auto Fill mode. -For a description of functions that you can call explicitly to fill and -justify existing text, see @ref{Filling}. - - Auto Fill mode also enables the functions that change the margins and -justification style to refill portions of the text. @xref{Margins}. - -@defvar auto-fill-function -The value of this buffer-local variable should be a function (of no -arguments) to be called after self-inserting a character from the table -@code{auto-fill-chars}. It may be @code{nil}, in which case nothing -special is done in that case. - -The value of @code{auto-fill-function} is @code{do-auto-fill} when -Auto-Fill mode is enabled. That is a function whose sole purpose is to -implement the usual strategy for breaking a line. - -@quotation -In older Emacs versions, this variable was named @code{auto-fill-hook}, -but since it is not called with the standard convention for hooks, it -was renamed to @code{auto-fill-function} in version 19. -@end quotation -@end defvar - -@defvar normal-auto-fill-function -This variable specifies the function to use for -@code{auto-fill-function}, if and when Auto Fill is turned on. Major -modes can set buffer-local values for this variable to alter how Auto -Fill works. -@end defvar - -@defvar auto-fill-chars -A char table of characters which invoke @code{auto-fill-function} when -self-inserted---space and newline in most language environments. They -have an entry @code{t} in the table. -@end defvar - -@node Sorting -@section Sorting Text -@cindex sorting text - - The sorting functions described in this section all rearrange text in -a buffer. This is in contrast to the function @code{sort}, which -rearranges the order of the elements of a list (@pxref{Rearrangement}). -The values returned by these functions are not meaningful. - -@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate -This function is the general text-sorting routine that subdivides a -buffer into records and then sorts them. Most of the commands in this -section use this function. - -To understand how @code{sort-subr} works, consider the whole accessible -portion of the buffer as being divided into disjoint pieces called -@dfn{sort records}. The records may or may not be contiguous, but they -must not overlap. A portion of each sort record (perhaps all of it) is -designated as the sort key. Sorting rearranges the records in order by -their sort keys. - -Usually, the records are rearranged in order of ascending sort key. -If the first argument to the @code{sort-subr} function, @var{reverse}, -is non-@code{nil}, the sort records are rearranged in order of -descending sort key. - -The next four arguments to @code{sort-subr} are functions that are -called to move point across a sort record. They are called many times -from within @code{sort-subr}. - -@enumerate -@item -@var{nextrecfun} is called with point at the end of a record. This -function moves point to the start of the next record. The first record -is assumed to start at the position of point when @code{sort-subr} is -called. Therefore, you should usually move point to the beginning of -the buffer before calling @code{sort-subr}. - -This function can indicate there are no more sort records by leaving -point at the end of the buffer. - -@item -@var{endrecfun} is called with point within a record. It moves point to -the end of the record. - -@item -@var{startkeyfun} is called to move point from the start of a record to -the start of the sort key. This argument is optional; if it is omitted, -the whole record is the sort key. If supplied, the function should -either return a non-@code{nil} value to be used as the sort key, or -return @code{nil} to indicate that the sort key is in the buffer -starting at point. In the latter case, @var{endkeyfun} is called to -find the end of the sort key. - -@item -@var{endkeyfun} is called to move point from the start of the sort key -to the end of the sort key. This argument is optional. If -@var{startkeyfun} returns @code{nil} and this argument is omitted (or -@code{nil}), then the sort key extends to the end of the record. There -is no need for @var{endkeyfun} if @var{startkeyfun} returns a -non-@code{nil} value. -@end enumerate - -The argument @var{predicate} is the function to use to compare keys. -If keys are numbers, it defaults to @code{<}; otherwise it defaults to -@code{string<}. - -As an example of @code{sort-subr}, here is the complete function -definition for @code{sort-lines}: - -@example -@group -;; @r{Note that the first two lines of doc string} -;; @r{are effectively one line when viewed by a user.} -(defun sort-lines (reverse beg end) - "Sort lines in region alphabetically;\ - argument means descending order. -Called from a program, there are three arguments: -@end group -@group -REVERSE (non-nil means reverse order),\ - BEG and END (region to sort). -The variable `sort-fold-case' determines\ - whether alphabetic case affects -the sort order." -@end group -@group - (interactive "P\nr") - (save-excursion - (save-restriction - (narrow-to-region beg end) - (goto-char (point-min)) - (let ((inhibit-field-text-motion t)) - (sort-subr reverse 'forward-line 'end-of-line))))) -@end group -@end example - -Here @code{forward-line} moves point to the start of the next record, -and @code{end-of-line} moves point to the end of record. We do not pass -the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire -record is used as the sort key. - -The @code{sort-paragraphs} function is very much the same, except that -its @code{sort-subr} call looks like this: - -@example -@group -(sort-subr reverse - (function - (lambda () - (while (and (not (eobp)) - (looking-at paragraph-separate)) - (forward-line 1)))) - 'forward-paragraph) -@end group -@end example - -Markers pointing into any sort records are left with no useful -position after @code{sort-subr} returns. -@end defun - -@defopt sort-fold-case -If this variable is non-@code{nil}, @code{sort-subr} and the other -buffer sorting functions ignore case when comparing strings. -@end defopt - -@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end -This command sorts the region between @var{start} and @var{end} -alphabetically as specified by @var{record-regexp} and @var{key-regexp}. -If @var{reverse} is a negative integer, then sorting is in reverse -order. - -Alphabetical sorting means that two sort keys are compared by -comparing the first characters of each, the second characters of each, -and so on. If a mismatch is found, it means that the sort keys are -unequal; the sort key whose character is less at the point of first -mismatch is the lesser sort key. The individual characters are compared -according to their numerical character codes in the Emacs character set. - -The value of the @var{record-regexp} argument specifies how to divide -the buffer into sort records. At the end of each record, a search is -done for this regular expression, and the text that matches it is taken -as the next record. For example, the regular expression @samp{^.+$}, -which matches lines with at least one character besides a newline, would -make each such line into a sort record. @xref{Regular Expressions}, for -a description of the syntax and meaning of regular expressions. - -The value of the @var{key-regexp} argument specifies what part of each -record is the sort key. The @var{key-regexp} could match the whole -record, or only a part. In the latter case, the rest of the record has -no effect on the sorted order of records, but it is carried along when -the record moves to its new position. - -The @var{key-regexp} argument can refer to the text matched by a -subexpression of @var{record-regexp}, or it can be a regular expression -on its own. - -If @var{key-regexp} is: - -@table @asis -@item @samp{\@var{digit}} -then the text matched by the @var{digit}th @samp{\(...\)} parenthesis -grouping in @var{record-regexp} is the sort key. - -@item @samp{\&} -then the whole record is the sort key. - -@item a regular expression -then @code{sort-regexp-fields} searches for a match for the regular -expression within the record. If such a match is found, it is the sort -key. If there is no match for @var{key-regexp} within a record then -that record is ignored, which means its position in the buffer is not -changed. (The other records may move around it.) -@end table - -For example, if you plan to sort all the lines in the region by the -first word on each line starting with the letter @samp{f}, you should -set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to -@samp{\<f\w*\>}. The resulting expression looks like this: - -@example -@group -(sort-regexp-fields nil "^.*$" "\\<f\\w*\\>" - (region-beginning) - (region-end)) -@end group -@end example - -If you call @code{sort-regexp-fields} interactively, it prompts for -@var{record-regexp} and @var{key-regexp} in the minibuffer. -@end deffn - -@deffn Command sort-lines reverse start end -This command alphabetically sorts lines in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-paragraphs reverse start end -This command alphabetically sorts paragraphs in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-pages reverse start end -This command alphabetically sorts pages in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-fields field start end -This command sorts lines in the region between @var{start} and -@var{end}, comparing them alphabetically by the @var{field}th field -of each line. Fields are separated by whitespace and numbered starting -from 1. If @var{field} is negative, sorting is by the -@w{@minus{}@var{field}th} field from the end of the line. This command -is useful for sorting tables. -@end deffn - -@deffn Command sort-numeric-fields field start end -This command sorts lines in the region between @var{start} and -@var{end}, comparing them numerically by the @var{field}th field of -each line. Fields are separated by whitespace and numbered starting -from 1. The specified field must contain a number in each line of the -region. Numbers starting with 0 are treated as octal, and numbers -starting with @samp{0x} are treated as hexadecimal. - -If @var{field} is negative, sorting is by the -@w{@minus{}@var{field}th} field from the end of the line. This -command is useful for sorting tables. -@end deffn - -@defopt sort-numeric-base -This variable specifies the default radix for -@code{sort-numeric-fields} to parse numbers. -@end defopt - -@deffn Command sort-columns reverse &optional beg end -This command sorts the lines in the region between @var{beg} and -@var{end}, comparing them alphabetically by a certain range of -columns. The column positions of @var{beg} and @var{end} bound the -range of columns to sort on. - -If @var{reverse} is non-@code{nil}, the sort is in reverse order. - -One unusual thing about this command is that the entire line -containing position @var{beg}, and the entire line containing position -@var{end}, are included in the region sorted. - -Note that @code{sort-columns} rejects text that contains tabs, because -tabs could be split across the specified columns. Use @kbd{M-x -untabify} to convert tabs to spaces before sorting. - -When possible, this command actually works by calling the @code{sort} -utility program. -@end deffn - -@node Columns -@comment node-name, next, previous, up -@section Counting Columns -@cindex columns -@cindex counting columns -@cindex horizontal position - - The column functions convert between a character position (counting -characters from the beginning of the buffer) and a column position -(counting screen characters from the beginning of a line). - - These functions count each character according to the number of -columns it occupies on the screen. This means control characters count -as occupying 2 or 4 columns, depending upon the value of -@code{ctl-arrow}, and tabs count as occupying a number of columns that -depends on the value of @code{tab-width} and on the column where the tab -begins. @xref{Usual Display}. - - Column number computations ignore the width of the window and the -amount of horizontal scrolling. Consequently, a column value can be -arbitrarily high. The first (or leftmost) column is numbered 0. They -also ignore overlays and text properties, aside from invisibility. - -@defun current-column -This function returns the horizontal position of point, measured in -columns, counting from 0 at the left margin. The column position is the -sum of the widths of all the displayed representations of the characters -between the start of the current line and point. - -For an example of using @code{current-column}, see the description of -@code{count-lines} in @ref{Text Lines}. -@end defun - -@defun move-to-column column &optional force -This function moves point to @var{column} in the current line. The -calculation of @var{column} takes into account the widths of the -displayed representations of the characters between the start of the -line and point. - -If column @var{column} is beyond the end of the line, point moves to the -end of the line. If @var{column} is negative, point moves to the -beginning of the line. - -If it is impossible to move to column @var{column} because that is in -the middle of a multicolumn character such as a tab, point moves to the -end of that character. However, if @var{force} is non-@code{nil}, and -@var{column} is in the middle of a tab, then @code{move-to-column} -converts the tab into spaces so that it can move precisely to column -@var{column}. Other multicolumn characters can cause anomalies despite -@var{force}, since there is no way to split them. - -The argument @var{force} also has an effect if the line isn't long -enough to reach column @var{column}; if it is @code{t}, that means to -add whitespace at the end of the line to reach that column. - -If @var{column} is not an integer, an error is signaled. - -The return value is the column number actually moved to. -@end defun - -@node Indentation -@section Indentation -@cindex indentation - - The indentation functions are used to examine, move to, and change -whitespace that is at the beginning of a line. Some of the functions -can also change whitespace elsewhere on a line. Columns and indentation -count from zero at the left margin. - -@menu -* 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. -@end menu - -@node Primitive Indent -@subsection Indentation Primitives - - This section describes the primitive functions used to count and -insert indentation. The functions in the following sections use these -primitives. @xref{Width}, for related functions. - -@defun current-indentation -@comment !!Type Primitive Function -@comment !!SourceFile indent.c -This function returns the indentation of the current line, which is -the horizontal position of the first nonblank character. If the -contents are entirely blank, then this is the horizontal position of the -end of the line. -@end defun - -@deffn Command indent-to column &optional minimum -@comment !!Type Primitive Function -@comment !!SourceFile indent.c -This function indents from point with tabs and spaces until @var{column} -is reached. If @var{minimum} is specified and non-@code{nil}, then at -least that many spaces are inserted even if this requires going beyond -@var{column}. Otherwise the function does nothing if point is already -beyond @var{column}. The value is the column at which the inserted -indentation ends. - -The inserted whitespace characters inherit text properties from the -surrounding text (usually, from the preceding text only). @xref{Sticky -Properties}. -@end deffn - -@defopt indent-tabs-mode -@comment !!SourceFile indent.c -If this variable is non-@code{nil}, indentation functions can insert -tabs as well as spaces. Otherwise, they insert only spaces. Setting -this variable automatically makes it buffer-local in the current buffer. -@end defopt - -@node Mode-Specific Indent -@subsection Indentation Controlled by Major Mode - - An important function of each major mode is to customize the @key{TAB} -key to indent properly for the language being edited. This section -describes the mechanism of the @key{TAB} key and how to control it. -The functions in this section return unpredictable values. - -@defvar indent-line-function -This variable's value is the function to be used by @key{TAB} (and -various commands) to indent the current line. The command -@code{indent-according-to-mode} does no more than call this function. - -In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C -mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}. -The default value is @code{indent-relative}. -@end defvar - -@deffn Command indent-according-to-mode -This command calls the function in @code{indent-line-function} to -indent the current line in a way appropriate for the current major mode. -@end deffn - -@deffn Command indent-for-tab-command -This command calls the function in @code{indent-line-function} to indent -the current line; however, if that function is -@code{indent-to-left-margin}, @code{insert-tab} is called instead. (That -is a trivial command that inserts a tab character.) -@end deffn - -@deffn Command newline-and-indent -@comment !!SourceFile simple.el -This function inserts a newline, then indents the new line (the one -following the newline just inserted) according to the major mode. - -It does indentation by calling the current @code{indent-line-function}. -In programming language modes, this is the same thing @key{TAB} does, -but in some text modes, where @key{TAB} inserts a tab, -@code{newline-and-indent} indents to the column specified by -@code{left-margin}. -@end deffn - -@deffn Command reindent-then-newline-and-indent -@comment !!SourceFile simple.el -This command reindents the current line, inserts a newline at point, -and then indents the new line (the one following the newline just -inserted). - -This command does indentation on both lines according to the current -major mode, by calling the current value of @code{indent-line-function}. -In programming language modes, this is the same thing @key{TAB} does, -but in some text modes, where @key{TAB} inserts a tab, -@code{reindent-then-newline-and-indent} indents to the column specified -by @code{left-margin}. -@end deffn - -@node Region Indent -@subsection Indenting an Entire Region - - This section describes commands that indent all the lines in the -region. They return unpredictable values. - -@deffn Command indent-region start end to-column -This command indents each nonblank line starting between @var{start} -(inclusive) and @var{end} (exclusive). If @var{to-column} is -@code{nil}, @code{indent-region} indents each nonblank line by calling -the current mode's indentation function, the value of -@code{indent-line-function}. - -If @var{to-column} is non-@code{nil}, it should be an integer -specifying the number of columns of indentation; then this function -gives each line exactly that much indentation, by either adding or -deleting whitespace. - -If there is a fill prefix, @code{indent-region} indents each line -by making it start with the fill prefix. -@end deffn - -@defvar indent-region-function -The value of this variable is a function that can be used by -@code{indent-region} as a short cut. It should take two arguments, the -start and end of the region. You should design the function so -that it will produce the same results as indenting the lines of the -region one by one, but presumably faster. - -If the value is @code{nil}, there is no short cut, and -@code{indent-region} actually works line by line. - -A short-cut function is useful in modes such as C mode and Lisp mode, -where the @code{indent-line-function} must scan from the beginning of -the function definition: applying it to each line would be quadratic in -time. The short cut can update the scan information as it moves through -the lines indenting them; this takes linear time. In a mode where -indenting a line individually is fast, there is no need for a short cut. - -@code{indent-region} with a non-@code{nil} argument @var{to-column} has -a different meaning and does not use this variable. -@end defvar - -@deffn Command indent-rigidly start end count -@comment !!SourceFile indent.el -This command indents all lines starting between @var{start} -(inclusive) and @var{end} (exclusive) sideways by @var{count} columns. -This ``preserves the shape'' of the affected region, moving it as a -rigid unit. Consequently, this command is useful not only for indenting -regions of unindented text, but also for indenting regions of formatted -code. - -For example, if @var{count} is 3, this command adds 3 columns of -indentation to each of the lines beginning in the region specified. - -In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses -@code{indent-rigidly} to indent the text copied from the message being -replied to. -@end deffn - -@defun indent-code-rigidly start end columns &optional nochange-regexp -This is like @code{indent-rigidly}, except that it doesn't alter lines -that start within strings or comments. - -In addition, it doesn't alter a line if @var{nochange-regexp} matches at -the beginning of the line (if @var{nochange-regexp} is non-@code{nil}). -@end defun - -@node Relative Indent -@subsection Indentation Relative to Previous Lines - - This section describes two commands that indent the current line -based on the contents of previous lines. - -@deffn Command indent-relative &optional unindented-ok -This command inserts whitespace at point, extending to the same -column as the next @dfn{indent point} of the previous nonblank line. An -indent point is a non-whitespace character following whitespace. The -next indent point is the first one at a column greater than the current -column of point. For example, if point is underneath and to the left of -the first non-blank character of a line of text, it moves to that column -by inserting whitespace. - -If the previous nonblank line has no next indent point (i.e., none at a -great enough column position), @code{indent-relative} either does -nothing (if @var{unindented-ok} is non-@code{nil}) or calls -@code{tab-to-tab-stop}. Thus, if point is underneath and to the right -of the last column of a short line of text, this command ordinarily -moves point to the next tab stop by inserting whitespace. - -The return value of @code{indent-relative} is unpredictable. - -In the following example, point is at the beginning of the second -line: - -@example -@group - This line is indented twelve spaces. -@point{}The quick brown fox jumped. -@end group -@end example - -@noindent -Evaluation of the expression @code{(indent-relative nil)} produces the -following: - -@example -@group - This line is indented twelve spaces. - @point{}The quick brown fox jumped. -@end group -@end example - - In this next example, point is between the @samp{m} and @samp{p} of -@samp{jumped}: - -@example -@group - This line is indented twelve spaces. -The quick brown fox jum@point{}ped. -@end group -@end example - -@noindent -Evaluation of the expression @code{(indent-relative nil)} produces the -following: - -@example -@group - This line is indented twelve spaces. -The quick brown fox jum @point{}ped. -@end group -@end example -@end deffn - -@deffn Command indent-relative-maybe -@comment !!SourceFile indent.el -This command indents the current line like the previous nonblank line, -by calling @code{indent-relative} with @code{t} as the -@var{unindented-ok} argument. The return value is unpredictable. - -If the previous nonblank line has no indent points beyond the current -column, this command does nothing. -@end deffn - -@node Indent Tabs -@comment node-name, next, previous, up -@subsection Adjustable ``Tab Stops'' -@cindex tabs stops for indentation - - This section explains the mechanism for user-specified ``tab stops'' -and the mechanisms that use and set them. The name ``tab stops'' is -used because the feature is similar to that of the tab stops on a -typewriter. The feature works by inserting an appropriate number of -spaces and tab characters to reach the next tab stop column; it does not -affect the display of tab characters in the buffer (@pxref{Usual -Display}). Note that the @key{TAB} character as input uses this tab -stop feature only in a few major modes, such as Text mode. -@xref{Tab Stops,,, emacs, The GNU Emacs Manual}. - -@deffn Command tab-to-tab-stop -This command inserts spaces or tabs before point, up to the next tab -stop column defined by @code{tab-stop-list}. It searches the list for -an element greater than the current column number, and uses that element -as the column to indent to. It does nothing if no such element is -found. -@end deffn - -@defopt tab-stop-list -This variable is the list of tab stop columns used by -@code{tab-to-tab-stops}. The elements should be integers in increasing -order. The tab stop columns need not be evenly spaced. - -Use @kbd{M-x edit-tab-stops} to edit the location of tab stops -interactively. -@end defopt - -@node Motion by Indent -@subsection Indentation-Based Motion Commands - - These commands, primarily for interactive use, act based on the -indentation in the text. - -@deffn Command back-to-indentation -@comment !!SourceFile simple.el -This command moves point to the first non-whitespace character in the -current line (which is the line in which point is located). It returns -@code{nil}. -@end deffn - -@deffn Command backward-to-indentation &optional arg -@comment !!SourceFile simple.el -This command moves point backward @var{arg} lines and then to the -first nonblank character on that line. It returns @code{nil}. -If @var{arg} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@deffn Command forward-to-indentation &optional arg -@comment !!SourceFile simple.el -This command moves point forward @var{arg} lines and then to the first -nonblank character on that line. It returns @code{nil}. -If @var{arg} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@node Case Changes -@comment node-name, next, previous, up -@section Case Changes -@cindex case conversion in buffers - - The case change commands described here work on text in the current -buffer. @xref{Case Conversion}, for case conversion functions that work -on strings and characters. @xref{Case Tables}, for how to customize -which characters are upper or lower case and how to convert them. - -@deffn Command capitalize-region start end -This function capitalizes all words in the region defined by -@var{start} and @var{end}. To capitalize means to convert each word's -first character to upper case and convert the rest of each word to lower -case. The function returns @code{nil}. - -If one end of the region is in the middle of a word, the part of the -word within the region is treated as an entire word. - -When @code{capitalize-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. - -@example -@group ----------- Buffer: foo ---------- -This is the contents of the 5th foo. ----------- Buffer: foo ---------- -@end group - -@group -(capitalize-region 1 44) -@result{} nil - ----------- Buffer: foo ---------- -This Is The Contents Of The 5th Foo. ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command downcase-region start end -This function converts all of the letters in the region defined by -@var{start} and @var{end} to lower case. The function returns -@code{nil}. - -When @code{downcase-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. -@end deffn - -@deffn Command upcase-region start end -This function converts all of the letters in the region defined by -@var{start} and @var{end} to upper case. The function returns -@code{nil}. - -When @code{upcase-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. -@end deffn - -@deffn Command capitalize-word count -This function capitalizes @var{count} words after point, moving point -over as it does. To capitalize means to convert each word's first -character to upper case and convert the rest of each word to lower case. -If @var{count} is negative, the function capitalizes the -@minus{}@var{count} previous words but does not move point. The value -is @code{nil}. - -If point is in the middle of a word, the part of the word before point -is ignored when moving forward. The rest is treated as an entire word. - -When @code{capitalize-word} is called interactively, @var{count} is -set to the numeric prefix argument. -@end deffn - -@deffn Command downcase-word count -This function converts the @var{count} words after point to all lower -case, moving point over as it does. If @var{count} is negative, it -converts the @minus{}@var{count} previous words but does not move point. -The value is @code{nil}. - -When @code{downcase-word} is called interactively, @var{count} is set -to the numeric prefix argument. -@end deffn - -@deffn Command upcase-word count -This function converts the @var{count} words after point to all upper -case, moving point over as it does. If @var{count} is negative, it -converts the @minus{}@var{count} previous words but does not move point. -The value is @code{nil}. - -When @code{upcase-word} is called interactively, @var{count} is set to -the numeric prefix argument. -@end deffn - -@node Text Properties -@section Text Properties -@cindex text properties -@cindex attributes of text -@cindex properties of text - - Each character position in a buffer or a string can have a @dfn{text -property list}, much like the property list of a symbol (@pxref{Property -Lists}). The properties belong to a particular character at a -particular place, such as, the letter @samp{T} at the beginning of this -sentence or the first @samp{o} in @samp{foo}---if the same character -occurs in two different places, the two occurrences in general have -different properties. - - Each property has a name and a value. Both of these can be any Lisp -object, but the name is normally a symbol. Typically each property -name symbol is used for a particular purpose; for instance, the text -property @code{face} specifies the faces for displaying the character -(@pxref{Special Properties}). The usual way to access the property -list is to specify a name and ask what value corresponds to it. - - If a character has a @code{category} property, we call it the -@dfn{property category} of the character. It should be a symbol. The -properties of the symbol serve as defaults for the properties of the -character. - - Copying text between strings and buffers preserves the properties -along with the characters; this includes such diverse functions as -@code{substring}, @code{insert}, and @code{buffer-substring}. - -@menu -* 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. -* 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. -@end menu - -@node Examining Properties -@subsection Examining Text Properties - - The simplest way to examine text properties is to ask for the value of -a particular property of a particular character. For that, use -@code{get-text-property}. Use @code{text-properties-at} to get the -entire property list of a character. @xref{Property Search}, for -functions to examine the properties of a number of characters at once. - - These functions handle both strings and buffers. Keep in mind that -positions in a string start from 0, whereas positions in a buffer start -from 1. - -@defun get-text-property pos prop &optional object -This function returns the value of the @var{prop} property of the -character after position @var{pos} in @var{object} (a buffer or -string). The argument @var{object} is optional and defaults to the -current buffer. - -If there is no @var{prop} property strictly speaking, but the character -has a property category that is a symbol, then @code{get-text-property} returns -the @var{prop} property of that symbol. -@end defun - -@defun get-char-property position prop &optional object -This function is like @code{get-text-property}, except that it checks -overlays first and then text properties. @xref{Overlays}. - -The argument @var{object} may be a string, a buffer, or a window. If it -is a window, then the buffer displayed in that window is used for text -properties and overlays, but only the overlays active for that window -are considered. If @var{object} is a buffer, then all overlays in that -buffer are considered, as well as text properties. If @var{object} is a -string, only text properties are considered, since strings never have -overlays. -@end defun - -@defun get-char-property-and-overlay position prop &optional object -This is like @code{get-char-property}, but gives extra information -about the overlay that the property value comes from. - -Its value is a cons cell whose @sc{car} is the property value, the -same value @code{get-char-property} would return with the same -arguments. Its @sc{cdr} is the overlay in which the property was -found, or @code{nil}, if it was found as a text property or not found -at all. - -If @var{position} is at the end of @var{object}, both the @sc{car} and -the @sc{cdr} of the value are @code{nil}. -@end defun - -@defvar char-property-alias-alist -This variable holds an alist which maps property names to a list of -alternative property names. If a character does not specify a direct -value for a property, the alternative property names are consulted in -order; the first non-@code{nil} value is used. This variable takes -precedence over @code{default-text-properties}, and @code{category} -properties take precedence over this variable. -@end defvar - -@defun text-properties-at position &optional object -This function returns the entire property list of the character at -@var{position} in the string or buffer @var{object}. If @var{object} is -@code{nil}, it defaults to the current buffer. -@end defun - -@defvar default-text-properties -This variable holds a property list giving default values for text -properties. Whenever a character does not specify a value for a -property, neither directly, through a category symbol, or through -@code{char-property-alias-alist}, the value stored in this list is -used instead. Here is an example: - -@example -(setq default-text-properties '(foo 69) - char-property-alias-alist nil) -;; @r{Make sure character 1 has no properties of its own.} -(set-text-properties 1 2 nil) -;; @r{What we get, when we ask, is the default value.} -(get-text-property 1 'foo) - @result{} 69 -@end example -@end defvar - -@node Changing Properties -@subsection Changing Text Properties - - The primitives for changing properties apply to a specified range of -text in a buffer or string. The function @code{set-text-properties} -(see end of section) sets the entire property list of the text in that -range; more often, it is useful to add, change, or delete just certain -properties specified by name. - - Since text properties are considered part of the contents of the -buffer (or string), and can affect how a buffer looks on the screen, -any change in buffer text properties marks the buffer as modified. -Buffer text property changes are undoable also (@pxref{Undo}). -Positions in a string start from 0, whereas positions in a buffer -start from 1. - -@defun put-text-property start end prop value &optional object -This function sets the @var{prop} property to @var{value} for the text -between @var{start} and @var{end} in the string or buffer @var{object}. -If @var{object} is @code{nil}, it defaults to the current buffer. -@end defun - -@defun add-text-properties start end props &optional object -This function adds or overrides text properties for the text between -@var{start} and @var{end} in the string or buffer @var{object}. If -@var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} specifies which properties to add. It should -have the form of a property list (@pxref{Property Lists}): a list whose -elements include the property names followed alternately by the -corresponding values. - -The return value is @code{t} if the function actually changed some -property's value; @code{nil} otherwise (if @var{props} is @code{nil} or -its values agree with those in the text). - -For example, here is how to set the @code{comment} and @code{face} -properties of a range of text: - -@example -(add-text-properties @var{start} @var{end} - '(comment t face highlight)) -@end example -@end defun - -@defun remove-text-properties start end props &optional object -This function deletes specified text properties from the text between -@var{start} and @var{end} in the string or buffer @var{object}. If -@var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} specifies which properties to delete. It -should have the form of a property list (@pxref{Property Lists}): a list -whose elements are property names alternating with corresponding values. -But only the names matter---the values that accompany them are ignored. -For example, here's how to remove the @code{face} property. - -@example -(remove-text-properties @var{start} @var{end} '(face nil)) -@end example - -The return value is @code{t} if the function actually changed some -property's value; @code{nil} otherwise (if @var{props} is @code{nil} or -if no character in the specified text had any of those properties). - -To remove all text properties from certain text, use -@code{set-text-properties} and specify @code{nil} for the new property -list. -@end defun - -@defun remove-list-of-text-properties start end list-of-properties &optional object -Like @code{remove-text-properties} except that -@var{list-of-properties} is a list of property names only, not an -alternating list of property names and values. -@end defun - -@defun set-text-properties start end props &optional object -This function completely replaces the text property list for the text -between @var{start} and @var{end} in the string or buffer @var{object}. -If @var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} is the new property list. It should be a list -whose elements are property names alternating with corresponding values. - -After @code{set-text-properties} returns, all the characters in the -specified range have identical properties. - -If @var{props} is @code{nil}, the effect is to get rid of all properties -from the specified range of text. Here's an example: - -@example -(set-text-properties @var{start} @var{end} nil) -@end example - -Do not rely on the return value of this function. -@end defun - - The easiest way to make a string with text properties -is with @code{propertize}: - -@defun propertize string &rest properties -This function returns a copy of @var{string} which has the text -properties @var{properties}. These properties apply to all the -characters in the string that is returned. Here is an example that -constructs a string with a @code{face} property and a @code{mouse-face} -property: - -@smallexample -(propertize "foo" 'face 'italic - 'mouse-face 'bold-italic) - @result{} #("foo" 0 3 (mouse-face bold-italic face italic)) -@end smallexample - -To put different properties on various parts of a string, you can -construct each part with @code{propertize} and then combine them with -@code{concat}: - -@smallexample -(concat - (propertize "foo" 'face 'italic - 'mouse-face 'bold-italic) - " and " - (propertize "bar" 'face 'italic - 'mouse-face 'bold-italic)) - @result{} #("foo and bar" - 0 3 (face italic mouse-face bold-italic) - 3 8 nil - 8 11 (face italic mouse-face bold-italic)) -@end smallexample -@end defun - - See also the function @code{buffer-substring-no-properties} -(@pxref{Buffer Contents}) which copies text from the buffer -but does not copy its properties. - -@node Property Search -@subsection Text Property Search Functions - - In typical use of text properties, most of the time several or many -consecutive characters have the same value for a property. Rather than -writing your programs to examine characters one by one, it is much -faster to process chunks of text that have the same property value. - - Here are functions you can use to do this. They use @code{eq} for -comparing property values. In all cases, @var{object} defaults to the -current buffer. - - For high performance, it's very important to use the @var{limit} -argument to these functions, especially the ones that search for a -single property---otherwise, they may spend a long time scanning to the -end of the buffer, if the property you are interested in does not change. - - These functions do not move point; instead, they return a position (or -@code{nil}). Remember that a position is always between two characters; -the position returned by these functions is between two characters with -different properties. - -@defun next-property-change pos &optional object limit -The function scans the text forward from position @var{pos} in the -string or buffer @var{object} till it finds a change in some text -property, then returns the position of the change. In other words, it -returns the position of the first character beyond @var{pos} whose -properties are not identical to those of the character just after -@var{pos}. - -If @var{limit} is non-@code{nil}, then the scan ends at position -@var{limit}. If there is no property change before that point, -@code{next-property-change} returns @var{limit}. - -The value is @code{nil} if the properties remain unchanged all the way -to the end of @var{object} and @var{limit} is @code{nil}. If the value -is non-@code{nil}, it is a position greater than or equal to @var{pos}. -The value equals @var{pos} only when @var{limit} equals @var{pos}. - -Here is an example of how to scan the buffer by chunks of text within -which all properties are constant: - -@smallexample -(while (not (eobp)) - (let ((plist (text-properties-at (point))) - (next-change - (or (next-property-change (point) (current-buffer)) - (point-max)))) - @r{Process text from point to @var{next-change}@dots{}} - (goto-char next-change))) -@end smallexample -@end defun - -@defun previous-property-change pos &optional object limit -This is like @code{next-property-change}, but scans back from @var{pos} -instead of forward. If the value is non-@code{nil}, it is a position -less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} -equals @var{pos}. -@end defun - -@defun next-single-property-change pos prop &optional object limit -The function scans text for a change in the @var{prop} property, then -returns the position of the change. The scan goes forward from -position @var{pos} in the string or buffer @var{object}. In other -words, this function returns the position of the first character -beyond @var{pos} whose @var{prop} property differs from that of the -character just after @var{pos}. - -If @var{limit} is non-@code{nil}, then the scan ends at position -@var{limit}. If there is no property change before that point, -@code{next-single-property-change} returns @var{limit}. - -The value is @code{nil} if the property remains unchanged all the way to -the end of @var{object} and @var{limit} is @code{nil}. If the value is -non-@code{nil}, it is a position greater than or equal to @var{pos}; it -equals @var{pos} only if @var{limit} equals @var{pos}. -@end defun - -@defun previous-single-property-change pos prop &optional object limit -This is like @code{next-single-property-change}, but scans back from -@var{pos} instead of forward. If the value is non-@code{nil}, it is a -position less than or equal to @var{pos}; it equals @var{pos} only if -@var{limit} equals @var{pos}. -@end defun - -@defun next-char-property-change pos &optional limit -This is like @code{next-property-change} except that it considers -overlay properties as well as text properties, and if no change is -found before the end of the buffer, it returns the maximum buffer -position rather than @code{nil} (in this sense, it resembles the -corresponding overlay function @code{next-overlay-change}, rather than -@code{next-property-change}). There is no @var{object} operand -because this function operates only on the current buffer. It returns -the next address at which either kind of property changes. -@end defun - -@defun previous-char-property-change pos &optional limit -This is like @code{next-char-property-change}, but scans back from -@var{pos} instead of forward, and returns the minimum buffer -position if no change is found. -@end defun - -@defun next-single-char-property-change pos prop &optional object limit -This is like @code{next-single-property-change} except that it -considers overlay properties as well as text properties, and if no -change is found before the end of the @var{object}, it returns the -maximum valid position in @var{object} rather than @code{nil}. Unlike -@code{next-char-property-change}, this function @emph{does} have an -@var{object} operand; if @var{object} is not a buffer, only -text-properties are considered. -@end defun - -@defun previous-single-char-property-change pos prop &optional object limit -This is like @code{next-single-char-property-change}, but scans back -from @var{pos} instead of forward, and returns the minimum valid -position in @var{object} if no change is found. -@end defun - -@defun text-property-any start end prop value &optional object -This function returns non-@code{nil} if at least one character between -@var{start} and @var{end} has a property @var{prop} whose value is -@var{value}. More precisely, it returns the position of the first such -character. Otherwise, it returns @code{nil}. - -The optional fifth argument, @var{object}, specifies the string or -buffer to scan. Positions are relative to @var{object}. The default -for @var{object} is the current buffer. -@end defun - -@defun text-property-not-all start end prop value &optional object -This function returns non-@code{nil} if at least one character between -@var{start} and @var{end} does not have a property @var{prop} with value -@var{value}. More precisely, it returns the position of the first such -character. Otherwise, it returns @code{nil}. - -The optional fifth argument, @var{object}, specifies the string or -buffer to scan. Positions are relative to @var{object}. The default -for @var{object} is the current buffer. -@end defun - -@node Special Properties -@subsection Properties with Special Meanings - - Here is a table of text property names that have special built-in -meanings. The following sections list a few additional special property -names that control filling and property inheritance. All other names -have no standard meaning, and you can use them as you like. - - Note: the properties @code{composition}, @code{display}, -@code{invisible} and @code{intangible} can also cause point to move to -an acceptable place, after each Emacs command. @xref{Adjusting -Point}. - -@table @code -@cindex property category of text character -@kindex category @r{(text property)} -@item category -If a character has a @code{category} property, we call it the -@dfn{property category} of the character. It should be a symbol. The -properties of this symbol serve as defaults for the properties of the -character. - -@item face -@cindex face codes of text -@kindex face @r{(text property)} -You can use the property @code{face} to control the font and color of -text. @xref{Faces}, for more information. - -In the simplest case, the value is a face name. It can also be a list; -then each element can be any of these possibilities; - -@itemize @bullet -@item -A face name (a symbol or string). - -@item -A property list of face attributes. This has the -form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a -face attribute name and @var{value} is a meaningful value for that -attribute. With this feature, you do not need to create a face each -time you want to specify a particular attribute for certain text. -@xref{Face Attributes}. - -@item -A cons cell with the form @code{(foreground-color . @var{color-name})} or -@code{(background-color . @var{color-name})}. These elements specify -just the foreground color or just the background color. @xref{Color -Names}, for the supported forms of @var{color-name}. - -A cons cell of @code{(foreground-color . @var{color-name})} is equivalent to -specifying @code{(:foreground @var{color-name})}; likewise for the -background. -@end itemize - -You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically -update @code{face} properties based on the contents of the text. - -@item font-lock-face -@kindex font-lock-face @r{(text property)} -The @code{font-lock-face} property is the same in all respects as the -@code{face} property, but its state of activation is controlled by -@code{font-lock-mode}. This can be advantageous for special buffers -which are not intended to be user-editable, or for static areas of -text which are always fontified in the same way. -@xref{Precalculated Fontification}. - -Strictly speaking, @code{font-lock-face} is not a built-in text -property; rather, it is implemented in Font Lock mode using -@code{char-property-alias-alist}. @xref{Examining Properties}. - -This property is new in Emacs 22.1. - -@item mouse-face -@kindex mouse-face @r{(text property)} -The property @code{mouse-face} is used instead of @code{face} when the -mouse is on or near the character. For this purpose, ``near'' means -that all text between the character and where the mouse is have the same -@code{mouse-face} property value. - -@item fontified -@kindex fontified @r{(text property)} -This property says whether the text is ready for display. If -@code{nil}, Emacs's redisplay routine calls the functions in -@code{fontification-functions} (@pxref{Auto Faces}) to prepare this -part of the buffer before it is displayed. It is used internally by -the ``just in time'' font locking code. - -@item display -This property activates various features that change the -way text is displayed. For example, it can make text appear taller -or shorter, higher or lower, wider or narrow, or replaced with an image. -@xref{Display Property}. - -@item help-echo -@kindex help-echo @r{(text property)} -@cindex tooltip -@anchor{Text help-echo} -If text has a string as its @code{help-echo} property, then when you -move the mouse onto that text, Emacs displays that string in the echo -area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs -Manual}). - -If the value of the @code{help-echo} property is a function, that -function is called with three arguments, @var{window}, @var{object} and -@var{pos} and should return a help string or @code{nil} for -none. The first argument, @var{window} is the window in which -the help was found. The second, @var{object}, is the buffer, overlay or -string which had the @code{help-echo} property. The @var{pos} -argument is as follows: - -@itemize @bullet{} -@item -If @var{object} is a buffer, @var{pos} is the position in the buffer. -@item -If @var{object} is an overlay, that overlay has a @code{help-echo} -property, and @var{pos} is the position in the overlay's buffer. -@item -If @var{object} is a string (an overlay string or a string displayed -with the @code{display} property), @var{pos} is the position in that -string. -@end itemize - -If the value of the @code{help-echo} property is neither a function nor -a string, it is evaluated to obtain a help string. - -You can alter the way help text is displayed by setting the variable -@code{show-help-function} (@pxref{Help display}). - -This feature is used in the mode line and for other active text. - -@item keymap -@cindex keymap of character -@kindex keymap @r{(text property)} -The @code{keymap} property specifies an additional keymap for -commands. When this keymap applies, it is used for key lookup before -the minor mode keymaps and before the buffer's local map. -@xref{Active Keymaps}. If the property value is a symbol, the -symbol's function definition is used as the keymap. - -The property's value for the character before point applies if it is -non-@code{nil} and rear-sticky, and the property's value for the -character after point applies if it is non-@code{nil} and -front-sticky. (For mouse clicks, the position of the click is used -instead of the position of point.) - -@item local-map -@kindex local-map @r{(text property)} -This property works like @code{keymap} except that it specifies a -keymap to use @emph{instead of} the buffer's local map. For most -purposes (perhaps all purposes), it is better to use the @code{keymap} -property. - -@item syntax-table -The @code{syntax-table} property overrides what the syntax table says -about this particular character. @xref{Syntax Properties}. - -@item read-only -@cindex read-only character -@kindex read-only @r{(text property)} -If a character has the property @code{read-only}, then modifying that -character is not allowed. Any command that would do so gets an error, -@code{text-read-only}. If the property value is a string, that string -is used as the error message. - -Insertion next to a read-only character is an error if inserting -ordinary text there would inherit the @code{read-only} property due to -stickiness. Thus, you can control permission to insert next to -read-only text by controlling the stickiness. @xref{Sticky Properties}. - -Since changing properties counts as modifying the buffer, it is not -possible to remove a @code{read-only} property unless you know the -special trick: bind @code{inhibit-read-only} to a non-@code{nil} value -and then remove the property. @xref{Read Only Buffers}. - -@item invisible -@kindex invisible @r{(text property)} -A non-@code{nil} @code{invisible} property can make a character invisible -on the screen. @xref{Invisible Text}, for details. - -@item intangible -@kindex intangible @r{(text property)} -If a group of consecutive characters have equal and non-@code{nil} -@code{intangible} properties, then you cannot place point between them. -If you try to move point forward into the group, point actually moves to -the end of the group. If you try to move point backward into the group, -point actually moves to the start of the group. - -If consecutive characters have unequal non-@code{nil} -@code{intangible} properties, they belong to separate groups; each -group is separately treated as described above. - -When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, -the @code{intangible} property is ignored. - -@item field -@kindex field @r{(text property)} -Consecutive characters with the same @code{field} property constitute a -@dfn{field}. Some motion functions including @code{forward-word} and -@code{beginning-of-line} stop moving at a field boundary. -@xref{Fields}. - -@item cursor -@kindex cursor @r{(text property)} -Normally, the cursor is displayed at the end of any overlay and text -property strings present at the current window position. You can -place the cursor on any desired character of these strings by giving -that character a non-@code{nil} @var{cursor} text property. - -@item pointer -@kindex pointer @r{(text property)} -This specifies a specific pointer shape when the mouse pointer is over -this text or image. @xref{Pointer Shape}, for possible pointer -shapes. - -@item line-spacing -@kindex line-spacing @r{(text property)} -A newline can have a @code{line-spacing} text or overlay property that -controls the height of the display line ending with that newline. The -property value overrides the default frame line spacing and the buffer -local @code{line-spacing} variable. @xref{Line Height}. - -@item line-height -@kindex line-height @r{(text property)} -A newline can have a @code{line-height} text or overlay property that -controls the total height of the display line ending in that newline. -@xref{Line Height}. - -@item modification-hooks -@cindex change hooks for a character -@cindex hooks for changing a character -@kindex modification-hooks @r{(text property)} -If a character has the property @code{modification-hooks}, then its -value should be a list of functions; modifying that character calls all -of those functions. Each function receives two arguments: the beginning -and end of the part of the buffer being modified. Note that if a -particular modification hook function appears on several characters -being modified by a single primitive, you can't predict how many times -the function will be called. - -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. - -Overlays also support the @code{modification-hooks} property, but the -details are somewhat different (@pxref{Overlay Properties}). - -@item insert-in-front-hooks -@itemx insert-behind-hooks -@kindex insert-in-front-hooks @r{(text property)} -@kindex insert-behind-hooks @r{(text property)} -The operation of inserting text in a buffer also calls the functions -listed in the @code{insert-in-front-hooks} property of the following -character and in the @code{insert-behind-hooks} property of the -preceding character. These functions receive two arguments, the -beginning and end of the inserted text. The functions are called -@emph{after} the actual insertion takes place. - -See also @ref{Change Hooks}, for other hooks that are called -when you change text in a buffer. - -@item point-entered -@itemx point-left -@cindex hooks for motion of point -@kindex point-entered @r{(text property)} -@kindex point-left @r{(text property)} -The special properties @code{point-entered} and @code{point-left} -record hook functions that report motion of point. Each time point -moves, Emacs compares these two property values: - -@itemize @bullet -@item -the @code{point-left} property of the character after the old location, -and -@item -the @code{point-entered} property of the character after the new -location. -@end itemize - -@noindent -If these two values differ, each of them is called (if not @code{nil}) -with two arguments: the old value of point, and the new one. - -The same comparison is made for the characters before the old and new -locations. The result may be to execute two @code{point-left} functions -(which may be the same function) and/or two @code{point-entered} -functions (which may be the same function). In any case, all the -@code{point-left} functions are called first, followed by all the -@code{point-entered} functions. - -It is possible with @code{char-after} to examine characters at various -buffer positions without moving point to those positions. Only an -actual change in the value of point runs these hook functions. - -@defvar inhibit-point-motion-hooks -When this variable is non-@code{nil}, @code{point-left} and -@code{point-entered} hooks are not run, and the @code{intangible} -property has no effect. Do not set this variable globally; bind it with -@code{let}. -@end defvar - -@defvar show-help-function -@anchor{Help display} If this variable is non-@code{nil}, it specifies a -function called to display help strings. These may be @code{help-echo} -properties, menu help strings (@pxref{Simple Menu Items}, -@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool -Bar}). The specified function is called with one argument, the help -string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs -Manual}) provides an example. -@end defvar - -@item composition -@kindex composition @r{(text property)} -This text property is used to display a sequence of characters as a -single glyph composed from components. But the value of the property -itself is completely internal to Emacs and should not be manipulated -directly by, for instance, @code{put-text-property}. - -@end table - -@node Format Properties -@subsection Formatted Text Properties - - These text properties affect the behavior of the fill commands. They -are used for representing formatted text. @xref{Filling}, and -@ref{Margins}. - -@table @code -@item hard -If a newline character has this property, it is a ``hard'' newline. -The fill commands do not alter hard newlines and do not move words -across them. However, this property takes effect only if the -@code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft -Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. - -@item right-margin -This property specifies an extra right margin for filling this part of the -text. - -@item left-margin -This property specifies an extra left margin for filling this part of the -text. - -@item justification -This property specifies the style of justification for filling this part -of the text. -@end table - -@node Sticky Properties -@subsection Stickiness of Text Properties -@cindex sticky text properties -@cindex inheritance of text properties - - Self-inserting characters normally take on the same properties as the -preceding character. This is called @dfn{inheritance} of properties. - - In a Lisp program, you can do insertion with inheritance or without, -depending on your choice of insertion primitive. The ordinary text -insertion functions such as @code{insert} do not inherit any properties. -They insert text with precisely the properties of the string being -inserted, and no others. This is correct for programs that copy text -from one context to another---for example, into or out of the kill ring. -To insert with inheritance, use the special primitives described in this -section. Self-inserting characters inherit properties because they work -using these primitives. - - When you do insertion with inheritance, @emph{which} properties are -inherited, and from where, depends on which properties are @dfn{sticky}. -Insertion after a character inherits those of its properties that are -@dfn{rear-sticky}. Insertion before a character inherits those of its -properties that are @dfn{front-sticky}. When both sides offer different -sticky values for the same property, the previous character's value -takes precedence. - - By default, a text property is rear-sticky but not front-sticky; thus, -the default is to inherit all the properties of the preceding character, -and nothing from the following character. - - You can control the stickiness of various text properties with two -specific text properties, @code{front-sticky} and @code{rear-nonsticky}, -and with the variable @code{text-property-default-nonsticky}. You can -use the variable to specify a different default for a given property. -You can use those two text properties to make any specific properties -sticky or nonsticky in any particular part of the text. - - If a character's @code{front-sticky} property is @code{t}, then all -its properties are front-sticky. If the @code{front-sticky} property is -a list, then the sticky properties of the character are those whose -names are in the list. For example, if a character has a -@code{front-sticky} property whose value is @code{(face read-only)}, -then insertion before the character can inherit its @code{face} property -and its @code{read-only} property, but no others. - - The @code{rear-nonsticky} property works the opposite way. Most -properties are rear-sticky by default, so the @code{rear-nonsticky} -property says which properties are @emph{not} rear-sticky. If a -character's @code{rear-nonsticky} property is @code{t}, then none of its -properties are rear-sticky. If the @code{rear-nonsticky} property is a -list, properties are rear-sticky @emph{unless} their names are in the -list. - -@defvar text-property-default-nonsticky -This variable holds an alist which defines the default rear-stickiness -of various text properties. Each element has the form -@code{(@var{property} . @var{nonstickiness})}, and it defines the -stickiness of a particular text property, @var{property}. - -If @var{nonstickiness} is non-@code{nil}, this means that the property -@var{property} is rear-nonsticky by default. Since all properties are -front-nonsticky by default, this makes @var{property} nonsticky in both -directions by default. - -The text properties @code{front-sticky} and @code{rear-nonsticky}, when -used, take precedence over the default @var{nonstickiness} specified in -@code{text-property-default-nonsticky}. -@end defvar - - Here are the functions that insert text with inheritance of properties: - -@defun insert-and-inherit &rest strings -Insert the strings @var{strings}, just like the function @code{insert}, -but inherit any sticky properties from the adjoining text. -@end defun - -@defun insert-before-markers-and-inherit &rest strings -Insert the strings @var{strings}, just like the function -@code{insert-before-markers}, but inherit any sticky properties from the -adjoining text. -@end defun - - @xref{Insertion}, for the ordinary insertion functions which do not -inherit. - -@node Lazy Properties -@subsection Lazy Computation of Text Properties - - Instead of computing text properties for all the text in the buffer, -you can arrange to compute the text properties for parts of the text -when and if something depends on them. - - The primitive that extracts text from the buffer along with its -properties is @code{buffer-substring}. Before examining the properties, -this function runs the abnormal hook @code{buffer-access-fontify-functions}. - -@defvar buffer-access-fontify-functions -This variable holds a list of functions for computing text properties. -Before @code{buffer-substring} copies the text and text properties for a -portion of the buffer, it calls all the functions in this list. Each of -the functions receives two arguments that specify the range of the -buffer being accessed. (The buffer itself is always the current -buffer.) -@end defvar - - The function @code{buffer-substring-no-properties} does not call these -functions, since it ignores text properties anyway. - - In order to prevent the hook functions from being called more than -once for the same part of the buffer, you can use the variable -@code{buffer-access-fontified-property}. - -@defvar buffer-access-fontified-property -If this variable's value is non-@code{nil}, it is a symbol which is used -as a text property name. A non-@code{nil} value for that text property -means, ``the other text properties for this character have already been -computed.'' - -If all the characters in the range specified for @code{buffer-substring} -have a non-@code{nil} value for this property, @code{buffer-substring} -does not call the @code{buffer-access-fontify-functions} functions. It -assumes these characters already have the right text properties, and -just copies the properties they already have. - -The normal way to use this feature is that the -@code{buffer-access-fontify-functions} functions add this property, as -well as others, to the characters they operate on. That way, they avoid -being called over and over for the same text. -@end defvar - -@node Clickable Text -@subsection Defining Clickable Text -@cindex clickable text - - @dfn{Clickable text} is text that can be clicked, with either the -the mouse or via keyboard commands, to produce some result. Many -major modes use clickable text to implement features such as -hyper-links. The @code{button} package provides an easy way to insert -and manipulate clickable text. @xref{Buttons}. - - In this section, we will explain how to manually set up clickable -text in a buffer using text properties. This involves two things: (1) -indicating clickability when the mouse moves over the text, and (2) -making @kbd{RET} or a mouse click on that text do something. - - Indicating clickability usually involves highlighting the text, and -often involves displaying helpful information about the action, such -as which mouse button to press, or a short summary of the action. -This can be done with the @code{mouse-face} and @code{help-echo} -text properties. @xref{Special Properties}. -Here is an example of how Dired does it: - -@smallexample -(condition-case nil - (if (dired-move-to-filename) - (add-text-properties - (point) - (save-excursion - (dired-move-to-end-of-filename) - (point)) - '(mouse-face highlight - help-echo "mouse-2: visit this file in other window"))) - (error nil)) -@end smallexample - -@noindent -The first two arguments to @code{add-text-properties} specify the -beginning and end of the text. - - The usual way to make the mouse do something when you click it -on this text is to define @code{mouse-2} in the major mode's -keymap. The job of checking whether the click was on clickable text -is done by the command definition. Here is how Dired does it: - -@smallexample -(defun dired-mouse-find-file-other-window (event) - "In Dired, visit the file or directory name you click on." - (interactive "e") - (let (window pos file) - (save-excursion - (setq window (posn-window (event-end event)) - pos (posn-point (event-end event))) - (if (not (windowp window)) - (error "No file chosen")) - (set-buffer (window-buffer window)) - (goto-char pos) - (setq file (dired-get-file-for-visit))) - (if (file-directory-p file) - (or (and (cdr dired-subdir-alist) - (dired-goto-subdir file)) - (progn - (select-window window) - (dired-other-window file))) - (select-window window) - (find-file-other-window (file-name-sans-versions file t))))) -@end smallexample - -@noindent -The reason for the @code{save-excursion} construct is to avoid -changing the current buffer. In this case, -Dired uses the functions @code{posn-window} and @code{posn-point} -to determine which buffer the click happened in and where, and -in that buffer, @code{dired-get-file-for-visit} to determine which -file to visit. - - Instead of defining a mouse command for the major mode, you can define -a key binding for the clickable text itself, using the @code{keymap} -text property: - -@example -(let ((map (make-sparse-keymap))) - (define-key map [mouse-2] 'operate-this-button) - (put-text-property (point) - (save-excursion - (dired-move-to-end-of-filename) - (point)) - 'keymap map)) -@end example - -@noindent -This method makes it possible to define different commands for various -clickable pieces of text. Also, the major mode definition (or the -global definition) remains available for the rest of the text in the -buffer. - -@node Links and Mouse-1 -@subsection Links and Mouse-1 -@cindex follow links -@cindex mouse-1 - - The normal Emacs command for activating text in read-only buffers is -@key{Mouse-2}, which includes following textual links. However, most -graphical applications use @key{Mouse-1} for following links. For -compatibility, @key{Mouse-1} follows links in Emacs too, when you -click on a link quickly without moving the mouse. The user can -customize this behavior through the variable -@code{mouse-1-click-follows-link}. - - To define text as a link at the Lisp level, you should bind the -@code{mouse-2} event to a command to follow the link. Then, to indicate that -@key{Mouse-1} should also follow the link, you should specify a -@code{follow-link} condition either as a text property or as a key -binding: - -@table @asis -@item @code{follow-link} property -If the clickable text has a non-@code{nil} @code{follow-link} text or overlay -property, that specifies the condition. - -@item @code{follow-link} event -If there is a binding for the @code{follow-link} event, either on the -clickable text or in the local keymap, the binding is the condition. -@end table - - Regardless of how you set the @code{follow-link} condition, its -value is used as follows to determine whether the given position is -inside a link, and (if so) to compute an @dfn{action code} saying how -@key{Mouse-1} should handle the link. - -@table @asis -@item @code{mouse-face} -If the condition is @code{mouse-face}, a position is inside a link if -there is a non-@code{nil} @code{mouse-face} property at that position. -The action code is always @code{t}. - -For example, here is how Info mode handles @key{Mouse-1}: - -@smallexample -(define-key Info-mode-map [follow-link] 'mouse-face) -@end smallexample - -@item a function -If the condition is a valid function, @var{func}, then a position -@var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates -to non-@code{nil}. The value returned by @var{func} serves as the -action code. - -For example, here is how pcvs enables @key{Mouse-1} to follow links on -file names only: - -@smallexample -(define-key map [follow-link] - (lambda (pos) - (eq (get-char-property pos 'face) 'cvs-filename-face))) -@end smallexample - -@item anything else -If the condition value is anything else, then the position is inside a -link and the condition itself is the action code. Clearly you should -only specify this kind of condition on the text that constitutes a -link. -@end table - -@noindent -The action code tells @key{Mouse-1} how to follow the link: - -@table @asis -@item a string or vector -If the action code is a string or vector, the @key{Mouse-1} event is -translated into the first element of the string or vector; i.e., the -action of the @key{Mouse-1} click is the local or global binding of -that character or symbol. Thus, if the action code is @code{"foo"}, -@key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, -@key{Mouse-1} translates into @key{foo}. - -@item anything else -For any other non-@code{nil} action code, the @code{mouse-1} event is -translated into a @code{mouse-2} event at the same position. -@end table - - To define @key{Mouse-1} to activate a button defined with -@code{define-button-type}, give the button a @code{follow-link} -property with a value as specified above to determine how to follow -the link. For example, here is how Help mode handles @key{Mouse-1}: - -@smallexample -(define-button-type 'help-xref - 'follow-link t - 'action #'help-button-action) -@end smallexample - - To define @key{Mouse-1} on a widget defined with -@code{define-widget}, give the widget a @code{:follow-link} property -with a value as specified above to determine how to follow the link. - -For example, here is how the @code{link} widget specifies that -a @key{Mouse-1} click shall be translated to @key{RET}: - -@smallexample -(define-widget 'link 'item - "An embedded link." - :button-prefix 'widget-link-prefix - :button-suffix 'widget-link-suffix - :follow-link "\C-m" - :help-echo "Follow the link." - :format "%[%t%]") -@end smallexample - -@defun mouse-on-link-p pos -This function returns non-@code{nil} if position @var{pos} in the -current buffer is on a link. @var{pos} can also be a mouse event -location, as returned by @code{event-start} (@pxref{Accessing Events}). -@end defun - -@node Fields -@subsection Defining and Using Fields -@cindex fields - - A field is a range of consecutive characters in the buffer that are -identified by having the same value (comparing with @code{eq}) of the -@code{field} property (either a text-property or an overlay property). -This section describes special functions that are available for -operating on fields. - - You specify a field with a buffer position, @var{pos}. We think of -each field as containing a range of buffer positions, so the position -you specify stands for the field containing that position. - - When the characters before and after @var{pos} are part of the same -field, there is no doubt which field contains @var{pos}: the one those -characters both belong to. When @var{pos} is at a boundary between -fields, which field it belongs to depends on the stickiness of the -@code{field} properties of the two surrounding characters (@pxref{Sticky -Properties}). The field whose property would be inherited by text -inserted at @var{pos} is the field that contains @var{pos}. - - There is an anomalous case where newly inserted text at @var{pos} -would not inherit the @code{field} property from either side. This -happens if the previous character's @code{field} property is not -rear-sticky, and the following character's @code{field} property is not -front-sticky. In this case, @var{pos} belongs to neither the preceding -field nor the following field; the field functions treat it as belonging -to an empty field whose beginning and end are both at @var{pos}. - - In all of these functions, if @var{pos} is omitted or @code{nil}, the -value of point is used by default. If narrowing is in effect, then -@var{pos} should fall within the accessible portion. @xref{Narrowing}. - -@defun field-beginning &optional pos escape-from-edge limit -This function returns the beginning of the field specified by @var{pos}. - -If @var{pos} is at the beginning of its field, and -@var{escape-from-edge} is non-@code{nil}, then the return value is -always the beginning of the preceding field that @emph{ends} at @var{pos}, -regardless of the stickiness of the @code{field} properties around -@var{pos}. - -If @var{limit} is non-@code{nil}, it is a buffer position; if the -beginning of the field is before @var{limit}, then @var{limit} will be -returned instead. -@end defun - -@defun field-end &optional pos escape-from-edge limit -This function returns the end of the field specified by @var{pos}. - -If @var{pos} is at the end of its field, and @var{escape-from-edge} is -non-@code{nil}, then the return value is always the end of the following -field that @emph{begins} at @var{pos}, regardless of the stickiness of -the @code{field} properties around @var{pos}. - -If @var{limit} is non-@code{nil}, it is a buffer position; if the end -of the field is after @var{limit}, then @var{limit} will be returned -instead. -@end defun - -@defun field-string &optional pos -This function returns the contents of the field specified by @var{pos}, -as a string. -@end defun - -@defun field-string-no-properties &optional pos -This function returns the contents of the field specified by @var{pos}, -as a string, discarding text properties. -@end defun - -@defun delete-field &optional pos -This function deletes the text of the field specified by @var{pos}. -@end defun - -@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property -This function ``constrains'' @var{new-pos} to the field that -@var{old-pos} belongs to---in other words, it returns the position -closest to @var{new-pos} that is in the same field as @var{old-pos}. - -If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses -the value of point instead, and moves point to the resulting position -as well as returning it. - -If @var{old-pos} is at the boundary of two fields, then the acceptable -final positions depend on the argument @var{escape-from-edge}. If -@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in -the field whose @code{field} property equals what new characters -inserted at @var{old-pos} would inherit. (This depends on the -stickiness of the @code{field} property for the characters before and -after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil}, -@var{new-pos} can be anywhere in the two adjacent fields. -Additionally, if two fields are separated by another field with the -special value @code{boundary}, then any point within this special -field is also considered to be ``on the boundary.'' - -Commands like @kbd{C-a} with no argumemt, that normally move backward -to a specific kind of location and stay there once there, probably -should specify @code{nil} for @var{escape-from-edge}. Other motion -commands that check fields should probably pass @code{t}. - -If the optional argument @var{only-in-line} is non-@code{nil}, and -constraining @var{new-pos} in the usual way would move it to a different -line, @var{new-pos} is returned unconstrained. This used in commands -that move by line, such as @code{next-line} and -@code{beginning-of-line}, so that they respect field boundaries only in -the case where they can still move to the right line. - -If the optional argument @var{inhibit-capture-property} is -non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that -name, then any field boundaries are ignored. - -You can cause @code{constrain-to-field} to ignore all field boundaries -(and so never constrain anything) by binding the variable -@code{inhibit-field-text-motion} to a non-@code{nil} value. -@end defun - -@node Not Intervals -@subsection Why Text Properties are not Intervals -@cindex intervals - - Some editors that support adding attributes to text in the buffer do -so by letting the user specify ``intervals'' within the text, and adding -the properties to the intervals. Those editors permit the user or the -programmer to determine where individual intervals start and end. We -deliberately provided a different sort of interface in Emacs Lisp to -avoid certain paradoxical behavior associated with text modification. - - If the actual subdivision into intervals is meaningful, that means you -can distinguish between a buffer that is just one interval with a -certain property, and a buffer containing the same text subdivided into -two intervals, both of which have that property. - - Suppose you take the buffer with just one interval and kill part of -the text. The text remaining in the buffer is one interval, and the -copy in the kill ring (and the undo list) becomes a separate interval. -Then if you yank back the killed text, you get two intervals with the -same properties. Thus, editing does not preserve the distinction -between one interval and two. - - Suppose we ``fix'' this problem by coalescing the two intervals when -the text is inserted. That works fine if the buffer originally was a -single interval. But suppose instead that we have two adjacent -intervals with the same properties, and we kill the text of one interval -and yank it back. The same interval-coalescence feature that rescues -the other case causes trouble in this one: after yanking, we have just -one interval. One again, editing does not preserve the distinction -between one interval and two. - - Insertion of text at the border between intervals also raises -questions that have no satisfactory answer. - - However, it is easy to arrange for editing to behave consistently for -questions of the form, ``What are the properties of this character?'' -So we have decided these are the only questions that make sense; we have -not implemented asking questions about where intervals start or end. - - In practice, you can usually use the text property search functions in -place of explicit interval boundaries. You can think of them as finding -the boundaries of intervals, assuming that intervals are always -coalesced whenever possible. @xref{Property Search}. - - Emacs also provides explicit intervals as a presentation feature; see -@ref{Overlays}. - -@node Substitution -@section Substituting for a Character Code - - The following functions replace characters within a specified region -based on their character codes. - -@defun subst-char-in-region start end old-char new-char &optional noundo -@cindex replace characters -This function replaces all occurrences of the character @var{old-char} -with the character @var{new-char} in the region of the current buffer -defined by @var{start} and @var{end}. - -@cindex undo avoidance -If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does -not record the change for undo and does not mark the buffer as modified. -This was useful for controlling the old selective display feature -(@pxref{Selective Display}). - -@code{subst-char-in-region} does not move point and returns -@code{nil}. - -@example -@group ----------- Buffer: foo ---------- -This is the contents of the buffer before. ----------- Buffer: foo ---------- -@end group - -@group -(subst-char-in-region 1 20 ?i ?X) - @result{} nil - ----------- Buffer: foo ---------- -ThXs Xs the contents of the buffer before. ----------- Buffer: foo ---------- -@end group -@end example -@end defun - -@defun translate-region start end table -This function applies a translation table to the characters in the -buffer between positions @var{start} and @var{end}. - -The translation table @var{table} is a string or a char-table; -@code{(aref @var{table} @var{ochar})} gives the translated character -corresponding to @var{ochar}. If @var{table} is a string, any -characters with codes larger than the length of @var{table} are not -altered by the translation. - -The return value of @code{translate-region} is the number of -characters that were actually changed by the translation. This does -not count characters that were mapped into themselves in the -translation table. -@end defun - -@node Registers -@section Registers -@cindex registers - - A register is a sort of variable used in Emacs editing that can hold a -variety of different kinds of values. Each register is named by a -single character. All @acronym{ASCII} characters and their meta variants -(but with the exception of @kbd{C-g}) can be used to name registers. -Thus, there are 255 possible registers. A register is designated in -Emacs Lisp by the character that is its name. - -@defvar register-alist -This variable is an alist of elements of the form @code{(@var{name} . -@var{contents})}. Normally, there is one element for each Emacs -register that has been used. - -The object @var{name} is a character (an integer) identifying the -register. -@end defvar - - The @var{contents} of a register can have several possible types: - -@table @asis -@item a number -A number stands for itself. If @code{insert-register} finds a number -in the register, it converts the number to decimal. - -@item a marker -A marker represents a buffer position to jump to. - -@item a string -A string is text saved in the register. - -@item a rectangle -A rectangle is represented by a list of strings. - -@item @code{(@var{window-configuration} @var{position})} -This represents a window configuration to restore in one frame, and a -position to jump to in the current buffer. - -@item @code{(@var{frame-configuration} @var{position})} -This represents a frame configuration to restore, and a position -to jump to in the current buffer. - -@item (file @var{filename}) -This represents a file to visit; jumping to this value visits file -@var{filename}. - -@item (file-query @var{filename} @var{position}) -This represents a file to visit and a position in it; jumping to this -value visits file @var{filename} and goes to buffer position -@var{position}. Restoring this type of position asks the user for -confirmation first. -@end table - - The functions in this section return unpredictable values unless -otherwise stated. - -@defun get-register reg -This function returns the contents of the register -@var{reg}, or @code{nil} if it has no contents. -@end defun - -@defun set-register reg value -This function sets the contents of register @var{reg} to @var{value}. -A register can be set to any value, but the other register functions -expect only certain data types. The return value is @var{value}. -@end defun - -@deffn Command view-register reg -This command displays what is contained in register @var{reg}. -@end deffn - -@ignore -@deffn Command point-to-register reg -This command stores both the current location of point and the current -buffer in register @var{reg} as a marker. -@end deffn - -@deffn Command jump-to-register reg -@deffnx Command register-to-point reg -@comment !!SourceFile register.el -This command restores the status recorded in register @var{reg}. - -If @var{reg} contains a marker, it moves point to the position stored in -the marker. Since both the buffer and the location within the buffer -are stored by the @code{point-to-register} function, this command can -switch you to another buffer. - -If @var{reg} contains a window configuration or a frame configuration. -@code{jump-to-register} restores that configuration. -@end deffn -@end ignore - -@deffn Command insert-register reg &optional beforep -This command inserts contents of register @var{reg} into the current -buffer. - -Normally, this command puts point before the inserted text, and the -mark after it. However, if the optional second argument @var{beforep} -is non-@code{nil}, it puts the mark before and point after. -You can pass a non-@code{nil} second argument @var{beforep} to this -function interactively by supplying any prefix argument. - -If the register contains a rectangle, then the rectangle is inserted -with its upper left corner at point. This means that text is inserted -in the current line and underneath it on successive lines. - -If the register contains something other than saved text (a string) or -a rectangle (a list), currently useless things happen. This may be -changed in the future. -@end deffn - -@ignore -@deffn Command copy-to-register reg start end &optional delete-flag -This command copies the region from @var{start} to @var{end} into -register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes -the region from the buffer after copying it into the register. -@end deffn - -@deffn Command prepend-to-register reg start end &optional delete-flag -This command prepends the region from @var{start} to @var{end} into -register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes -the region from the buffer after copying it to the register. -@end deffn - -@deffn Command append-to-register reg start end &optional delete-flag -This command appends the region from @var{start} to @var{end} to the -text already in register @var{reg}. If @var{delete-flag} is -non-@code{nil}, it deletes the region from the buffer after copying it -to the register. -@end deffn - -@deffn Command copy-rectangle-to-register reg start end &optional delete-flag -This command copies a rectangular region from @var{start} to @var{end} -into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it -deletes the region from the buffer after copying it to the register. -@end deffn - -@deffn Command window-configuration-to-register reg -This function stores the window configuration of the selected frame in -register @var{reg}. -@end deffn - -@deffn Command frame-configuration-to-register reg -This function stores the current frame configuration in register -@var{reg}. -@end deffn -@end ignore - -@node Transposition -@section Transposition of Text - - This subroutine is used by the transposition commands. - -@defun transpose-regions start1 end1 start2 end2 &optional leave-markers -This function exchanges two nonoverlapping portions of the buffer. -Arguments @var{start1} and @var{end1} specify the bounds of one portion -and arguments @var{start2} and @var{end2} specify the bounds of the -other portion. - -Normally, @code{transpose-regions} relocates markers with the transposed -text; a marker previously positioned within one of the two transposed -portions moves along with that portion, thus remaining between the same -two characters in their new position. However, if @var{leave-markers} -is non-@code{nil}, @code{transpose-regions} does not do this---it leaves -all markers unrelocated. -@end defun - -@node Base 64 -@section Base 64 Encoding -@cindex base 64 encoding - - Base 64 code is used in email to encode a sequence of 8-bit bytes as -a longer sequence of @acronym{ASCII} graphic characters. It is defined in -Internet RFC@footnote{ -An RFC, an acronym for @dfn{Request for Comments}, is a numbered -Internet informational document describing a standard. RFCs are -usually written by technical experts acting on their own initiative, -and are traditionally written in a pragmatic, experience-driven -manner. -}2045. This section describes the functions for -converting to and from this code. - -@defun base64-encode-region beg end &optional no-line-break -This function converts the region from @var{beg} to @var{end} into base -64 code. It returns the length of the encoded text. An error is -signaled if a character in the region is multibyte, i.e.@: in a -multibyte buffer the region must contain only characters from the -charsets @code{ascii}, @code{eight-bit-control} and -@code{eight-bit-graphic}. - -Normally, this function inserts newline characters into the encoded -text, to avoid overlong lines. However, if the optional argument -@var{no-line-break} is non-@code{nil}, these newlines are not added, so -the output is just one long line. -@end defun - -@defun base64-encode-string string &optional no-line-break -This function converts the string @var{string} into base 64 code. It -returns a string containing the encoded text. As for -@code{base64-encode-region}, an error is signaled if a character in the -string is multibyte. - -Normally, this function inserts newline characters into the encoded -text, to avoid overlong lines. However, if the optional argument -@var{no-line-break} is non-@code{nil}, these newlines are not added, so -the result string is just one long line. -@end defun - -@defun base64-decode-region beg end -This function converts the region from @var{beg} to @var{end} from base -64 code into the corresponding decoded text. It returns the length of -the decoded text. - -The decoding functions ignore newline characters in the encoded text. -@end defun - -@defun base64-decode-string string -This function converts the string @var{string} from base 64 code into -the corresponding decoded text. It returns a unibyte string containing the -decoded text. - -The decoding functions ignore newline characters in the encoded text. -@end defun - -@node MD5 Checksum -@section MD5 Checksum -@cindex MD5 checksum -@cindex message digest computation - - MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit -``fingerprints'' of a document or program. They are used to verify -that you have an exact and unaltered copy of the data. The algorithm -to calculate the MD5 message digest is defined in Internet -RFC@footnote{ -For an explanation of what is an RFC, see the footnote in @ref{Base -64}. -}1321. This section describes the Emacs facilities for computing -message digests. - -@defun md5 object &optional start end coding-system noerror -This function returns the MD5 message digest of @var{object}, which -should be a buffer or a string. - -The two optional arguments @var{start} and @var{end} are character -positions specifying the portion of @var{object} to compute the -message digest for. If they are @code{nil} or omitted, the digest is -computed for the whole of @var{object}. - -The function @code{md5} does not compute the message digest directly -from the internal Emacs representation of the text (@pxref{Text -Representations}). Instead, it encodes the text using a coding -system, and computes the message digest from the encoded text. The -optional fourth argument @var{coding-system} specifies which coding -system to use for encoding the text. It should be the same coding -system that you used to read the text, or that you used or will use -when saving or sending the text. @xref{Coding Systems}, for more -information about coding systems. - -If @var{coding-system} is @code{nil} or omitted, the default depends -on @var{object}. If @var{object} is a buffer, the default for -@var{coding-system} is whatever coding system would be chosen by -default for writing this text into a file. If @var{object} is a -string, the user's most preferred coding system (@pxref{Recognize -Coding, prefer-coding-system, the description of -@code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used. - -Normally, @code{md5} signals an error if the text can't be encoded -using the specified or chosen coding system. However, if -@var{noerror} is non-@code{nil}, it silently uses @code{raw-text} -coding instead. -@end defun - -@node Atomic Changes -@section Atomic Change Groups -@cindex atomic changes - - In data base terminology, an @dfn{atomic} change is an indivisible -change---it can succeed entirely or it can fail entirely, but it -cannot partly succeed. A Lisp program can make a series of changes to -one or several buffers as an @dfn{atomic change group}, meaning that -either the entire series of changes will be installed in their buffers -or, in case of an error, none of them will be. - - To do this for one buffer, the one already current, simply write a -call to @code{atomic-change-group} around the code that makes the -changes, like this: - -@example -(atomic-change-group - (insert foo) - (delete-region x y)) -@end example - -@noindent -If an error (or other nonlocal exit) occurs inside the body of -@code{atomic-change-group}, it unmakes all the changes in that buffer -that were during the execution of the body. This kind of change group -has no effect on any other buffers---any such changes remain. - - If you need something more sophisticated, such as to make changes in -various buffers constitute one atomic group, you must directly call -lower-level functions that @code{atomic-change-group} uses. - -@defun prepare-change-group &optional buffer -This function sets up a change group for buffer @var{buffer}, which -defaults to the current buffer. It returns a ``handle'' that -represents the change group. You must use this handle to activate the -change group and subsequently to finish it. -@end defun - - To use the change group, you must @dfn{activate} it. You must do -this before making any changes in the text of @var{buffer}. - -@defun activate-change-group handle -This function activates the change group that @var{handle} designates. -@end defun - - After you activate the change group, any changes you make in that -buffer become part of it. Once you have made all the desired changes -in the buffer, you must @dfn{finish} the change group. There are two -ways to do this: you can either accept (and finalize) all the changes, -or cancel them all. - -@defun accept-change-group handle -This function accepts all the changes in the change group specified by -@var{handle}, making them final. -@end defun - -@defun cancel-change-group handle -This function cancels and undoes all the changes in the change group -specified by @var{handle}. -@end defun - - Your code should use @code{unwind-protect} to make sure the group is -always finished. The call to @code{activate-change-group} should be -inside the @code{unwind-protect}, in case the user types @kbd{C-g} -just after it runs. (This is one reason why -@code{prepare-change-group} and @code{activate-change-group} are -separate functions, because normally you would call -@code{prepare-change-group} before the start of that -@code{unwind-protect}.) Once you finish the group, don't use the -handle again---in particular, don't try to finish the same group -twice. - - To make a multibuffer change group, call @code{prepare-change-group} -once for each buffer you want to cover, then use @code{nconc} to -combine the returned values, like this: - -@example -(nconc (prepare-change-group buffer-1) - (prepare-change-group buffer-2)) -@end example - -You can then activate the multibuffer change group with a single call -to @code{activate-change-group}, and finish it with a single call to -@code{accept-change-group} or @code{cancel-change-group}. - - Nested use of several change groups for the same buffer works as you -would expect. Non-nested use of change groups for the same buffer -will get Emacs confused, so don't let it happen; the first change -group you start for any given buffer should be the last one finished. - -@node Change Hooks -@section Change Hooks -@cindex change hooks -@cindex hooks for text changes - - These hook variables let you arrange to take notice of all changes in -all buffers (or in a particular buffer, if you make them buffer-local). -See also @ref{Special Properties}, for how to detect changes to specific -parts of the text. - - The functions you use in these hooks should save and restore the match -data if they do anything that uses regular expressions; otherwise, they -will interfere in bizarre ways with the editing operations that call -them. - -@defvar before-change-functions -This variable holds a list of functions to call before any buffer -modification. Each function gets two arguments, the beginning and end -of the region that is about to change, represented as integers. The -buffer that is about to change is always the current buffer. -@end defvar - -@defvar after-change-functions -This variable holds a list of functions to call after any buffer -modification. Each function receives three arguments: the beginning and -end of the region just changed, and the length of the text that existed -before the change. All three arguments are integers. The buffer that's -about to change is always the current buffer. - -The length of the old text is the difference between the buffer positions -before and after that text as it was before the change. As for the -changed text, its length is simply the difference between the first two -arguments. -@end defvar - - Output of messages into the @samp{*Messages*} buffer does not -call these functions. - -@defmac combine-after-change-calls body@dots{} -The macro executes @var{body} normally, but arranges to call the -after-change functions just once for a series of several changes---if -that seems safe. - -If a program makes several text changes in the same area of the buffer, -using the macro @code{combine-after-change-calls} around that part of -the program can make it run considerably faster when after-change hooks -are in use. When the after-change hooks are ultimately called, the -arguments specify a portion of the buffer including all of the changes -made within the @code{combine-after-change-calls} body. - -@strong{Warning:} You must not alter the values of -@code{after-change-functions} within -the body of a @code{combine-after-change-calls} form. - -@strong{Warning:} if the changes you combine occur in widely scattered -parts of the buffer, this will still work, but it is not advisable, -because it may lead to inefficient behavior for some change hook -functions. -@end defmac - -@defvar first-change-hook -This variable is a normal hook that is run whenever a buffer is changed -that was previously in the unmodified state. -@end defvar - -@defvar inhibit-modification-hooks -If this variable is non-@code{nil}, all of the change hooks are -disabled; none of them run. This affects all the hook variables -described above in this section, as well as the hooks attached to -certain special text properties (@pxref{Special Properties}) and overlay -properties (@pxref{Overlay Properties}). - -Also, this variable is bound to non-@code{nil} while running those -same hook variables, so that by default modifying the buffer from -a modification hook does not cause other modification hooks to be run. -If you do want modification hooks to be run in a particular piece of -code that is itself run from a modification hook, then rebind locally -@code{inhibit-modification-hooks} to @code{nil}. -@end defvar - -@ignore - arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b -@end ignore diff --git a/lispref/tindex.pl b/lispref/tindex.pl deleted file mode 100755 index 89bbe5f5f6f..00000000000 --- a/lispref/tindex.pl +++ /dev/null @@ -1,127 +0,0 @@ -#! /usr/bin/perl - -# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, -# 2006, 2007 Free Software Foundation, Inc. -# -# This file is part of GNU Emacs. -# -# GNU Emacs is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 3, or (at your option) -# any later version. -# -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with GNU Emacs; see the file COPYING. If not, write to the -# Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -# Boston, MA 02110-1301, USA. - -require 5; -use Getopt::Long; - -my $USAGE = <<ENDUSAGE; -Remove \@tindex lines from files that were already present in previous -versions. - -Usage: $0 [--old=EXT] FILE... - $0 --help - $0 --version - - --help display this help and exit - --version print version and exit - --old=DIR find old files in DIR - -The script performs two passes. In the first pass, Texinfo files from -DIR are scanned for \@tindex lines, and identifiers in them are -recorded. In a second pass, Texinfo files in the current directory -are scanned, and \@tindex lines for identifiers that were recorded in -the first pass are removed. Old file contents are saved in files -with extension ".orig". A list of modified files and removed \@tindex -identifiers is printed to stdout at the end. -ENDUSAGE - -sub fatal { - print STDERR "$0: ", @_, ".\n"; - exit 1; -} - -my $help = 0; -my $version = 0; -my $old; - -my $rc = GetOptions ('help' => \$help, 'version' => \$version, - 'old=s' => \$old); -if ($version) { - print "0.1\n"; - exit 0; -} elsif (!$rc || !$old || @ARGV) { - print $USAGE; - exit 1; -} elsif ($help) { - print $USAGE; - exit 0; -} - -# Fill the hash %tindex with associations VAR -> COUNT where -# the keys VAR are identifiers mentioned in @tindex lines in the older -# files to process and COUNT is the number of times they are seen in -# the files. - -my %tindex; -my %removed; -my @old_files = glob "$old/*.texi"; -my @new_files = glob "*.texi"; -fatal ("No Texinfo files found in `$old'") unless @old_files; -fatal ("No Texinfo files found in current directory") unless @new_files; - -print "Scanning old files for \@tindex lines\n"; -foreach $file (@old_files) { - open (IN, "<$file") or fatal "Cannot open $file: $!"; - while (<IN>) { - ++$tindex{$1} if /^\s*\@tindex\s+(\S+)/; - } - close IN; -} - -# Process current files and remove those @tindex lines which we -# know were already present in the files scanned above. - -print "Removing old \@tindex lines\n"; -foreach $file (@new_files) { - my $modified = 0; - my $contents = ""; - - open (IN, "< $file") or fatal "Cannot open $file.orig for reading: $!"; - while (<IN>) { - if (/^\s*\@tindex\s+(\S+)/ && $tindex{$1}) { - ++$removed{$1}; - $modified = 1; - } else { - $contents = $contents . $_; - } - } - - close IN; - - if ($modified) { - print " $file\n"; - system ("cp $file $file.orig") == 0 or fatal "Cannot backup $file: $!"; - open (OUT, ">$file") or fatal "Cannot open $file for writing: $!"; - print OUT $contents; - close OUT; - } -} - -# Print a list of identifiers removed. - -print "Removed \@tindex commands for:\n"; -my $key; -foreach $key (keys %removed) { - print " $key\n"; -} - -# arch-tag: f8460df6-6bef-4c98-8555-e2c63a88b0fa diff --git a/lispref/tips.texi b/lispref/tips.texi deleted file mode 100644 index f3070f4659b..00000000000 --- a/lispref/tips.texi +++ /dev/null @@ -1,1130 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/tips -@node Tips, GNU Emacs Internals, GPL, Top -@appendix Tips and Conventions -@cindex tips for writing Lisp -@cindex standards of coding style -@cindex coding standards - - This chapter describes no additional features of Emacs Lisp. Instead -it gives advice on making effective use of the features described in the -previous chapters, and describes conventions Emacs Lisp programmers -should follow. - - You can automatically check some of the conventions described below by -running the command @kbd{M-x checkdoc RET} when visiting a Lisp file. -It cannot check all of the conventions, and not all the warnings it -gives necessarily correspond to problems, but it is worth examining them -all. - -@menu -* 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. -@end menu - -@node Coding Conventions -@section Emacs Lisp Coding Conventions - -@cindex coding conventions in Emacs Lisp - Here are conventions that you should follow when writing Emacs Lisp -code intended for widespread use: - -@itemize @bullet -@item -Simply loading the package should not change Emacs's editing behavior. -Include a command or commands to enable and disable the feature, -or to invoke it. - -This convention is mandatory for any file that includes custom -definitions. If fixing such a file to follow this convention requires -an incompatible change, go ahead and make the incompatible change; -don't postpone it. - -@item -Since all global variables share the same name space, and all -functions share another name space, you should choose a short word to -distinguish your program from other Lisp programs@footnote{The -benefits of a Common Lisp-style package system are considered not to -outweigh the costs.}. Then take care to begin the names of all global -variables, constants, and functions in your program with the chosen -prefix. This helps avoid name conflicts. - -Occasionally, for a command name intended for users to use, it is more -convenient if some words come before the package's name prefix. And -constructs that define functions, variables, etc., work better if they -start with @samp{defun} or @samp{defvar}, so put the name prefix later -on in the name. - -This recommendation applies even to names for traditional Lisp -primitives that are not primitives in Emacs Lisp---such as -@code{copy-list}. Believe it or not, there is more than one plausible -way to define @code{copy-list}. Play it safe; append your name prefix -to produce a name like @code{foo-copy-list} or @code{mylib-copy-list} -instead. - -If you write a function that you think ought to be added to Emacs under -a certain name, such as @code{twiddle-files}, don't call it by that name -in your program. Call it @code{mylib-twiddle-files} in your program, -and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add -it to Emacs. If and when we do, we can change the name easily enough. - -If one prefix is insufficient, your package can use two or three -alternative common prefixes, so long as they make sense. - -Separate the prefix from the rest of the symbol name with a hyphen, -@samp{-}. This will be consistent with Emacs itself and with most Emacs -Lisp programs. - -@item -Put a call to @code{provide} at the end of each separate Lisp file. - -@item -If a file requires certain other Lisp programs to be loaded -beforehand, then the comments at the beginning of the file should say -so. Also, use @code{require} to make sure they are loaded. - -@item -If one file @var{foo} uses a macro defined in another file @var{bar}, -@var{foo} should contain this expression before the first use of the -macro: - -@example -(eval-when-compile (require '@var{bar})) -@end example - -@noindent -(And the library @var{bar} should contain @code{(provide '@var{bar})}, -to make the @code{require} work.) This will cause @var{bar} to be -loaded when you byte-compile @var{foo}. Otherwise, you risk compiling -@var{foo} without the necessary macro loaded, and that would produce -compiled code that won't work right. @xref{Compiling Macros}. - -Using @code{eval-when-compile} avoids loading @var{bar} when -the compiled version of @var{foo} is @emph{used}. - -@item -Please don't require the @code{cl} package of Common Lisp extensions at -run time. Use of this package is optional, and it is not part of the -standard Emacs namespace. If your package loads @code{cl} at run time, -that could cause name clashes for users who don't use that package. - -However, there is no problem with using the @code{cl} package at -compile time, with @code{(eval-when-compile (require 'cl))}. That's -sufficient for using the macros in the @code{cl} package, because the -compiler expands them before generating the byte-code. - -@item -When defining a major mode, please follow the major mode -conventions. @xref{Major Mode Conventions}. - -@item -When defining a minor mode, please follow the minor mode -conventions. @xref{Minor Mode Conventions}. - -@item -If the purpose of a function is to tell you whether a certain condition -is true or false, give the function a name that ends in @samp{p}. If -the name is one word, add just @samp{p}; if the name is multiple words, -add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}. - -@item -If a user option variable records a true-or-false condition, give it a -name that ends in @samp{-flag}. - -@item -If the purpose of a variable is to store a single function, give it a -name that ends in @samp{-function}. If the purpose of a variable is -to store a list of functions (i.e., the variable is a hook), please -follow the naming conventions for hooks. @xref{Hooks}. - -@item -@cindex unloading packages, preparing for -If loading the file adds functions to hooks, define a function -@code{@var{feature}-unload-hook}, where @var{feature} is the name of -the feature the package provides, and make it undo any such changes. -Using @code{unload-feature} to unload the file will run this function. -@xref{Unloading}. - -@item -It is a bad idea to define aliases for the Emacs primitives. Normally -you should use the standard names instead. The case where an alias -may be useful is where it facilitates backwards compatibility or -portability. - -@item -If a package needs to define an alias or a new function for -compatibility with some other version of Emacs, name it with the package -prefix, not with the raw name with which it occurs in the other version. -Here is an example from Gnus, which provides many examples of such -compatibility issues. - -@example -(defalias 'gnus-point-at-bol - (if (fboundp 'point-at-bol) - 'point-at-bol - 'line-beginning-position)) -@end example - -@item -Redefining (or advising) an Emacs primitive is a bad idea. It may do -the right thing for a particular program, but there is no telling what -other programs might break as a result. In any case, it is a problem -for debugging, because the advised function doesn't do what its source -code says it does. If the programmer investigating the problem is -unaware that there is advice on the function, the experience can be -very frustrating. - -We hope to remove all the places in Emacs that advise primitives. -In the mean time, please don't add any more. - -@item -It is likewise a bad idea for one Lisp package to advise a function -in another Lisp package. - -@item -Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for -Loading}) in libraries and packages. This feature is meant for -personal customizations; using it in a Lisp program is unclean, -because it modifies the behavior of another Lisp file in a way that's -not visible in that file. This is an obstacle for debugging, much -like advising a function in the other package. - -@item -If a file does replace any of the functions or library programs of -standard Emacs, prominent comments at the beginning of the file should -say which functions are replaced, and how the behavior of the -replacements differs from that of the originals. - -@item -Constructs that define a function or variable should be macros, -not functions, and their names should start with @samp{def}. - -@item -A macro that defines a function or variable should have a name that -starts with @samp{define-}. The macro should receive the name to be -defined as the first argument. That will help various tools find the -definition automatically. Avoid constructing the names in the macro -itself, since that would confuse these tools. - -@item -Please keep the names of your Emacs Lisp source files to 13 characters -or less. This way, if the files are compiled, the compiled files' names -will be 14 characters or less, which is short enough to fit on all kinds -of Unix systems. - -@item -In some other systems there is a convention of choosing variable names -that begin and end with @samp{*}. We don't use that convention in Emacs -Lisp, so please don't use it in your programs. (Emacs uses such names -only for special-purpose buffers.) The users will find Emacs more -coherent if all libraries use the same conventions. - -@item -If your program contains non-ASCII characters in string or character -constants, you should make sure Emacs always decodes these characters -the same way, regardless of the user's settings. There are two ways -to do that: - -@itemize - -@item -Use coding system @code{emacs-mule}, and specify that for -@code{coding} in the @samp{-*-} line or the local variables list. - -@example -;; XXX.el -*- coding: emacs-mule; -*- -@end example - -@item -Use one of the coding systems based on ISO 2022 (such as -iso-8859-@var{n} and iso-2022-7bit), and specify it with @samp{!} at -the end for @code{coding}. (The @samp{!} turns off any possible -character translation.) - -@example -;; XXX.el -*- coding: iso-latin-2!; -*- -@end example -@end itemize - -@item -Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the -default indentation parameters. - -@item -Don't make a habit of putting close-parentheses on lines by themselves; -Lisp programmers find this disconcerting. Once in a while, when there -is a sequence of many consecutive close-parentheses, it may make sense -to split the sequence in one or two significant places. - -@item -Please put a copyright notice and copying permission notice on the -file if you distribute copies. Use a notice like this one: - -@smallexample -;; Copyright (C) @var{year} @var{name} - -;; This program is free software; you can redistribute it and/or -;; modify it under the terms of the GNU General Public License as -;; published by the Free Software Foundation; either version 3 of -;; the License, or (at your option) any later version. - -;; This program is distributed in the hope that it will be -;; useful, but WITHOUT ANY WARRANTY; without even the implied -;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR -;; PURPOSE. See the GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public -;; License along with this program; if not, write to the Free -;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301 USA -@end smallexample - -If you have signed papers to assign the copyright to the Foundation, -then use @samp{Free Software Foundation, Inc.} as @var{name}. -Otherwise, use your name. See also @xref{Library Headers}. -@end itemize - -@node Key Binding Conventions -@section Key Binding Conventions -@cindex key binding, conventions for - -@itemize @bullet -@item -@cindex mouse-2 -@cindex references, following -Special major modes used for read-only text should usually redefine -@kbd{mouse-2} and @key{RET} to trace some sort of reference in the text. -Modes such as Dired, Info, Compilation, and Occur redefine it in this -way. - -In addition, they should mark the text as a kind of ``link'' so that -@kbd{mouse-1} will follow it also. @xref{Links and Mouse-1}. - -@item -@cindex reserved keys -@cindex keys, reserved -Please do not define @kbd{C-c @var{letter}} as a key in Lisp programs. -Sequences consisting of @kbd{C-c} and a letter (either upper or lower -case) are reserved for users; they are the @strong{only} sequences -reserved for users, so do not block them. - -Changing all the Emacs major modes to respect this convention was a -lot of work; abandoning this convention would make that work go to -waste, and inconvenience users. Please comply with it. - -@item -Function keys @key{F5} through @key{F9} without modifier keys are -also reserved for users to define. - -@item -Applications should not bind mouse events based on button 1 with the -shift key held down. These events include @kbd{S-mouse-1}, -@kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for -users. - -@item -Sequences consisting of @kbd{C-c} followed by a control character or a -digit are reserved for major modes. - -@item -Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}}, -@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes. - -@item -Sequences consisting of @kbd{C-c} followed by any other punctuation -character are allocated for minor modes. Using them in a major mode is -not absolutely prohibited, but if you do that, the major mode binding -may be shadowed from time to time by minor modes. - -@item -Do not bind @kbd{C-h} following any prefix character (including -@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available -as a help character for listing the subcommands of the prefix character. - -@item -Do not bind a key sequence ending in @key{ESC} except following -another @key{ESC}. (That is, it is OK to bind a sequence ending in -@kbd{@key{ESC} @key{ESC}}.) - -The reason for this rule is that a non-prefix binding for @key{ESC} in -any context prevents recognition of escape sequences as function keys in -that context. - -@item -Anything which acts like a temporary mode or state which the user can -enter and leave should define @kbd{@key{ESC} @key{ESC}} or -@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape. - -For a state which accepts ordinary Emacs commands, or more generally any -kind of state in which @key{ESC} followed by a function key or arrow key -is potentially meaningful, then you must not define @kbd{@key{ESC} -@key{ESC}}, since that would preclude recognizing an escape sequence -after @key{ESC}. In these states, you should define @kbd{@key{ESC} -@key{ESC} @key{ESC}} as the way to escape. Otherwise, define -@kbd{@key{ESC} @key{ESC}} instead. -@end itemize - -@node Programming Tips -@section Emacs Programming Tips -@cindex programming conventions - - Following these conventions will make your program fit better -into Emacs when it runs. - -@itemize @bullet -@item -Don't use @code{next-line} or @code{previous-line} in programs; nearly -always, @code{forward-line} is more convenient as well as more -predictable and robust. @xref{Text Lines}. - -@item -Don't call functions that set the mark, unless setting the mark is one -of the intended features of your program. The mark is a user-level -feature, so it is incorrect to change the mark except to supply a value -for the user's benefit. @xref{The Mark}. - -In particular, don't use any of these functions: - -@itemize @bullet -@item -@code{beginning-of-buffer}, @code{end-of-buffer} -@item -@code{replace-string}, @code{replace-regexp} -@item -@code{insert-file}, @code{insert-buffer} -@end itemize - -If you just want to move point, or replace a certain string, or insert -a file or buffer's contents, without any of the other features -intended for interactive users, you can replace these functions with -one or two lines of simple Lisp code. - -@item -Use lists rather than vectors, except when there is a particular reason -to use a vector. Lisp has more facilities for manipulating lists than -for vectors, and working with lists is usually more convenient. - -Vectors are advantageous for tables that are substantial in size and are -accessed in random order (not searched front to back), provided there is -no need to insert or delete elements (only lists allow that). - -@item -The recommended way to show a message in the echo area is with -the @code{message} function, not @code{princ}. @xref{The Echo Area}. - -@item -When you encounter an error condition, call the function @code{error} -(or @code{signal}). The function @code{error} does not return. -@xref{Signaling Errors}. - -Do not use @code{message}, @code{throw}, @code{sleep-for}, -or @code{beep} to report errors. - -@item -An error message should start with a capital letter but should not end -with a period. - -@item -A question asked in the minibuffer with @code{y-or-n-p} or -@code{yes-or-no-p} should start with a capital letter and end with -@samp{? }. - -@item -When you mention a default value in a minibuffer prompt, -put it and the word @samp{default} inside parentheses. -It should look like this: - -@example -Enter the answer (default 42): -@end example - -@item -In @code{interactive}, if you use a Lisp expression to produce a list -of arguments, don't try to provide the ``correct'' default values for -region or position arguments. Instead, provide @code{nil} for those -arguments if they were not specified, and have the function body -compute the default value when the argument is @code{nil}. For -instance, write this: - -@example -(defun foo (pos) - (interactive - (list (if @var{specified} @var{specified-pos}))) - (unless pos (setq pos @var{default-pos})) - ...) -@end example - -@noindent -rather than this: - -@example -(defun foo (pos) - (interactive - (list (if @var{specified} @var{specified-pos} - @var{default-pos}))) - ...) -@end example - -@noindent -This is so that repetition of the command will recompute -these defaults based on the current circumstances. - -You do not need to take such precautions when you use interactive -specs @samp{d}, @samp{m} and @samp{r}, because they make special -arrangements to recompute the argument values on repetition of the -command. - -@item -Many commands that take a long time to execute display a message that -says something like @samp{Operating...} when they start, and change it to -@samp{Operating...done} when they finish. Please keep the style of -these messages uniform: @emph{no} space around the ellipsis, and -@emph{no} period after @samp{done}. - -@item -Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} -command does: use a new local keymap that contains one command defined -to switch back to the old local keymap. Or do what the -@code{edit-options} command does: switch to another buffer and let the -user switch back at will. @xref{Recursive Editing}. -@end itemize - -@node Compilation Tips -@section Tips for Making Compiled Code Fast -@cindex execution speed -@cindex speedups - - Here are ways of improving the execution speed of byte-compiled -Lisp programs. - -@itemize @bullet -@item -@cindex profiling -@cindex timing programs -@cindex @file{elp.el} -Profile your program with the @file{elp} library. See the file -@file{elp.el} for instructions. - -@item -@cindex @file{benchmark.el} -@cindex benchmarking -Check the speed of individual Emacs Lisp forms using the -@file{benchmark} library. See the functions @code{benchmark-run} and -@code{benchmark-run-compiled} in @file{benchmark.el}. - -@item -Use iteration rather than recursion whenever possible. -Function calls are slow in Emacs Lisp even when a compiled function -is calling another compiled function. - -@item -Using the primitive list-searching functions @code{memq}, @code{member}, -@code{assq}, or @code{assoc} is even faster than explicit iteration. It -can be worth rearranging a data structure so that one of these primitive -search functions can be used. - -@item -Certain built-in functions are handled specially in byte-compiled code, -avoiding the need for an ordinary function call. It is a good idea to -use these functions rather than alternatives. To see whether a function -is handled specially by the compiler, examine its @code{byte-compile} -property. If the property is non-@code{nil}, then the function is -handled specially. - -For example, the following input will show you that @code{aref} is -compiled specially (@pxref{Array Functions}): - -@example -@group -(get 'aref 'byte-compile) - @result{} byte-compile-two-args -@end group -@end example - -@item -If calling a small function accounts for a substantial part of your -program's running time, make the function inline. This eliminates -the function call overhead. Since making a function inline reduces -the flexibility of changing the program, don't do it unless it gives -a noticeable speedup in something slow enough that users care about -the speed. @xref{Inline Functions}. -@end itemize - -@node Warning Tips -@section Tips for Avoiding Compiler Warnings -@cindex byte compiler warnings, how to avoid - -@itemize @bullet -@item -Try to avoid compiler warnings about undefined free variables, by adding -dummy @code{defvar} definitions for these variables, like this: - -@example -(defvar foo) -@end example - -Such a definition has no effect except to tell the compiler -not to warn about uses of the variable @code{foo} in this file. - -@item -If you use many functions and variables from a certain file, you can -add a @code{require} for that package to avoid compilation warnings -for them. For instance, - -@example -(eval-when-compile - (require 'foo)) -@end example - -@item -If you bind a variable in one function, and use it or set it in -another function, the compiler warns about the latter function unless -the variable has a definition. But adding a definition would be -unclean if the variable has a short name, since Lisp packages should -not define short variable names. The right thing to do is to rename -this variable to start with the name prefix used for the other -functions and variables in your package. - -@item -The last resort for avoiding a warning, when you want to do something -that usually is a mistake but it's not a mistake in this one case, -is to put a call to @code{with-no-warnings} around it. -@end itemize - -@node Documentation Tips -@section Tips for Documentation Strings -@cindex documentation strings, conventions and tips - -@findex checkdoc-minor-mode - Here are some tips and conventions for the writing of documentation -strings. You can check many of these conventions by running the command -@kbd{M-x checkdoc-minor-mode}. - -@itemize @bullet -@item -Every command, function, or variable intended for users to know about -should have a documentation string. - -@item -An internal variable or subroutine of a Lisp program might as well have -a documentation string. In earlier Emacs versions, you could save space -by using a comment instead of a documentation string, but that is no -longer the case---documentation strings now take up very little space in -a running Emacs. - -@item -Format the documentation string so that it fits in an Emacs window on an -80-column screen. It is a good idea for most lines to be no wider than -60 characters. The first line should not be wider than 67 characters -or it will look bad in the output of @code{apropos}. - -You can fill the text if that looks good. However, rather than blindly -filling the entire documentation string, you can often make it much more -readable by choosing certain line breaks with care. Use blank lines -between topics if the documentation string is long. - -@item -The first line of the documentation string should consist of one or two -complete sentences that stand on their own as a summary. @kbd{M-x -apropos} displays just the first line, and if that line's contents don't -stand on their own, the result looks bad. In particular, start the -first line with a capital letter and end with a period. - -For a function, the first line should briefly answer the question, -``What does this function do?'' For a variable, the first line should -briefly answer the question, ``What does this value mean?'' - -Don't limit the documentation string to one line; use as many lines as -you need to explain the details of how to use the function or -variable. Please use complete sentences for the rest of the text too. - -@item -When the user tries to use a disabled command, Emacs displays just the -first paragraph of its documentation string---everything through the -first blank line. If you wish, you can choose which information to -include before the first blank line so as to make this display useful. - -@item -The first line should mention all the important arguments of the -function, and should mention them in the order that they are written -in a function call. If the function has many arguments, then it is -not feasible to mention them all in the first line; in that case, the -first line should mention the first few arguments, including the most -important arguments. - -@item -When a function's documentation string mentions the value of an argument -of the function, use the argument name in capital letters as if it were -a name for that value. Thus, the documentation string of the function -@code{eval} refers to its second argument as @samp{FORM}, because the -actual argument name is @code{form}: - -@example -Evaluate FORM and return its value. -@end example - -Also write metasyntactic variables in capital letters, such as when you -show the decomposition of a list or vector into subunits, some of which -may vary. @samp{KEY} and @samp{VALUE} in the following example -illustrate this practice: - -@example -The argument TABLE should be an alist whose elements -have the form (KEY . VALUE). Here, KEY is ... -@end example - -@item -Never change the case of a Lisp symbol when you mention it in a doc -string. If the symbol's name is @code{foo}, write ``foo,'' not -``Foo'' (which is a different symbol). - -This might appear to contradict the policy of writing function -argument values, but there is no real contradiction; the argument -@emph{value} is not the same thing as the @emph{symbol} which the -function uses to hold the value. - -If this puts a lower-case letter at the beginning of a sentence -and that annoys you, rewrite the sentence so that the symbol -is not at the start of it. - -@item -Do not start or end a documentation string with whitespace. - -@item -@strong{Do not} indent subsequent lines of a documentation string so -that the text is lined up in the source code with the text of the first -line. This looks nice in the source code, but looks bizarre when users -view the documentation. Remember that the indentation before the -starting double-quote is not part of the string! - -@anchor{Docstring hyperlinks} -@item -@iftex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{`lambda'}. There are two exceptions: -write @code{t} and @code{nil} without single-quotes. -@end iftex -@ifnottex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{lambda}. There are two exceptions: write -t and nil without single-quotes. (In this manual, we use a different -convention, with single-quotes for all symbols.) -@end ifnottex - -@cindex hyperlinks in documentation strings -Help mode automatically creates a hyperlink when a documentation string -uses a symbol name inside single quotes, if the symbol has either a -function or a variable definition. You do not need to do anything -special to make use of this feature. However, when a symbol has both a -function definition and a variable definition, and you want to refer to -just one of them, you can specify which one by writing one of the words -@samp{variable}, @samp{option}, @samp{function}, or @samp{command}, -immediately before the symbol name. (Case makes no difference in -recognizing these indicator words.) For example, if you write - -@example -This function sets the variable `buffer-file-name'. -@end example - -@noindent -then the hyperlink will refer only to the variable documentation of -@code{buffer-file-name}, and not to its function documentation. - -If a symbol has a function definition and/or a variable definition, but -those are irrelevant to the use of the symbol that you are documenting, -you can write the words @samp{symbol} or @samp{program} before the -symbol name to prevent making any hyperlink. For example, - -@example -If the argument KIND-OF-RESULT is the symbol `list', -this function returns a list of all the objects -that satisfy the criterion. -@end example - -@noindent -does not make a hyperlink to the documentation, irrelevant here, of the -function @code{list}. - -Normally, no hyperlink is made for a variable without variable -documentation. You can force a hyperlink for such variables by -preceding them with one of the words @samp{variable} or -@samp{option}. - -Hyperlinks for faces are only made if the face name is preceded or -followed by the word @samp{face}. In that case, only the face -documentation will be shown, even if the symbol is also defined as a -variable or as a function. - -To make a hyperlink to Info documentation, write the name of the Info -node (or anchor) in single quotes, preceded by @samp{info node}, -@samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info -file name defaults to @samp{emacs}. For example, - -@smallexample -See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. -@end smallexample - -Finally, to create a hyperlink to URLs, write the URL in single -quotes, preceded by @samp{URL}. For example, - -@smallexample -The home page for the GNU project has more information (see URL -`http://www.gnu.org/'). -@end smallexample - -@item -Don't write key sequences directly in documentation strings. Instead, -use the @samp{\\[@dots{}]} construct to stand for them. For example, -instead of writing @samp{C-f}, write the construct -@samp{\\[forward-char]}. When Emacs displays the documentation string, -it substitutes whatever key is currently bound to @code{forward-char}. -(This is normally @samp{C-f}, but it may be some other character if the -user has moved key bindings.) @xref{Keys in Documentation}. - -@item -In documentation strings for a major mode, you will want to refer to the -key bindings of that mode's local map, rather than global ones. -Therefore, use the construct @samp{\\<@dots{}>} once in the -documentation string to specify which key map to use. Do this before -the first use of @samp{\\[@dots{}]}. The text inside the -@samp{\\<@dots{}>} should be the name of the variable containing the -local keymap for the major mode. - -It is not practical to use @samp{\\[@dots{}]} very many times, because -display of the documentation string will become slow. So use this to -describe the most important commands in your major mode, and then use -@samp{\\@{@dots{}@}} to display the rest of the mode's keymap. - -@item -For consistency, phrase the verb in the first sentence of a function's -documentation string as an imperative---for instance, use ``Return the -cons of A and B.'' in preference to ``Returns the cons of A and B@.'' -Usually it looks good to do likewise for the rest of the first -paragraph. Subsequent paragraphs usually look better if each sentence -is indicative and has a proper subject. - -@item -The documentation string for a function that is a yes-or-no predicate -should start with words such as ``Return t if,'' to indicate -explicitly what constitutes ``truth.'' The word ``return'' avoids -starting the sentence with lower-case ``t,'' which could be somewhat -distracting. - -@item -If a line in a documentation string begins with an open-parenthesis, -write a backslash before the open-parenthesis, like this: - -@example -The argument FOO can be either a number -\(a buffer position) or a string (a file name). -@end example - -This prevents the open-parenthesis from being treated as the start of a -defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). - -@item -Write documentation strings in the active voice, not the passive, and in -the present tense, not the future. For instance, use ``Return a list -containing A and B.'' instead of ``A list containing A and B will be -returned.'' - -@item -Avoid using the word ``cause'' (or its equivalents) unnecessarily. -Instead of, ``Cause Emacs to display text in boldface,'' write just -``Display text in boldface.'' - -@item -Avoid using ``iff'' (a mathematics term meaning ``if and only if''), -since many people are unfamiliar with it and mistake it for a typo. In -most cases, the meaning is clear with just ``if''. Otherwise, try to -find an alternate phrasing that conveys the meaning. - -@item -When a command is meaningful only in a certain mode or situation, -do mention that in the documentation string. For example, -the documentation of @code{dired-find-file} is: - -@example -In Dired, visit the file or directory named on this line. -@end example - -@item -When you define a variable that users ought to set interactively, you -normally should use @code{defcustom}. However, if for some reason you -use @code{defvar} instead, start the doc string with a @samp{*}. -@xref{Defining Variables}. - -@item -The documentation string for a variable that is a yes-or-no flag should -start with words such as ``Non-nil means,'' to make it clear that -all non-@code{nil} values are equivalent and indicate explicitly what -@code{nil} and non-@code{nil} mean. -@end itemize - -@node Comment Tips -@section Tips on Writing Comments -@cindex comments, Lisp convention for - - We recommend these conventions for where to put comments and how to -indent them: - -@table @samp -@item ; -Comments that start with a single semicolon, @samp{;}, should all be -aligned to the same column on the right of the source code. Such -comments usually explain how the code on the same line does its job. In -Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment}) -command automatically inserts such a @samp{;} in the right place, or -aligns such a comment if it is already present. - -This and following examples are taken from the Emacs sources. - -@smallexample -@group -(setq base-version-list ; there was a base - (assoc (substring fn 0 start-vn) ; version to which - file-version-assoc-list)) ; this looks like - ; a subversion -@end group -@end smallexample - -@item ;; -Comments that start with two semicolons, @samp{;;}, should be aligned to -the same level of indentation as the code. Such comments usually -describe the purpose of the following lines or the state of the program -at that point. For example: - -@smallexample -@group -(prog1 (setq auto-fill-function - @dots{} - @dots{} - ;; update mode line - (force-mode-line-update))) -@end group -@end smallexample - -We also normally use two semicolons for comments outside functions. - -@smallexample -@group -;; This Lisp code is run in Emacs -;; when it is to operate as a server -;; for other processes. -@end group -@end smallexample - -Every function that has no documentation string (presumably one that is -used only internally within the package it belongs to), should instead -have a two-semicolon comment right before the function, explaining what -the function does and how to call it properly. Explain precisely what -each argument means and how the function interprets its possible values. - -@item ;;; -Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. These are used, occasionally, for comments within -functions that should start at the margin. We also use them sometimes -for comments that are between functions---whether to use two or three -semicolons depends on whether the comment should be considered a -``heading'' by Outline minor mode. By default, comments starting with -at least three semicolons (followed by a single space and a -non-whitespace character) are considered headings, comments starting -with two or less are not. - -Another use for triple-semicolon comments is for commenting out lines -within a function. We use three semicolons for this precisely so that -they remain at the left margin. By default, Outline minor mode does -not consider a comment to be a heading (even if it starts with at -least three semicolons) if the semicolons are followed by at least two -spaces. Thus, if you add an introductory comment to the commented out -code, make sure to indent it by at least two spaces after the three -semicolons. - -@smallexample -(defun foo (a) -;;; This is no longer necessary. -;;; (force-mode-line-update) - (message "Finished with %s" a)) -@end smallexample - -When commenting out entire functions, use two semicolons. - -@item ;;;; -Comments that start with four semicolons, @samp{;;;;}, should be aligned -to the left margin and are used for headings of major sections of a -program. For example: - -@smallexample -;;;; The kill ring -@end smallexample -@end table - -@noindent -The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;} -(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}), -automatically indent comments according to these conventions, -depending on the number of semicolons. @xref{Comments,, -Manipulating Comments, emacs, The GNU Emacs Manual}. - -@node Library Headers -@section Conventional Headers for Emacs Libraries -@cindex header comments -@cindex library header comments - - Emacs has conventions for using special comments in Lisp libraries -to divide them into sections and give information such as who wrote -them. This section explains these conventions. - - We'll start with an example, a package that is included in the Emacs -distribution. - - Parts of this example reflect its status as part of Emacs; for -example, the copyright notice lists the Free Software Foundation as the -copyright holder, and the copying permission says the file is part of -Emacs. When you write a package and post it, the copyright holder would -be you (unless your employer claims to own it instead), and you should -get the suggested copying permission from the end of the GNU General -Public License itself. Don't say your file is part of Emacs -if we haven't installed it in Emacs yet! - - With that warning out of the way, on to the example: - -@smallexample -@group -;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers - -;; Copyright (C) 1992 Free Software Foundation, Inc. -@end group - -;; Author: Eric S. Raymond <esr@@snark.thyrsus.com> -;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com> -;; Created: 14 Jul 1992 -;; Version: 1.2 -@group -;; Keywords: docs - -;; This file is part of GNU Emacs. -@dots{} -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. -@end group -@end smallexample - - The very first line should have this format: - -@example -;;; @var{filename} --- @var{description} -@end example - -@noindent -The description should be complete in one line. If the file -needs a @samp{-*-} specification, put it after @var{description}. - - After the copyright notice come several @dfn{header comment} lines, -each beginning with @samp{;; @var{header-name}:}. Here is a table of -the conventional possibilities for @var{header-name}: - -@table @samp -@item Author -This line states the name and net address of at least the principal -author of the library. - -If there are multiple authors, you can list them on continuation lines -led by @code{;;} and a tab character, like this: - -@smallexample -@group -;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu> -;; Dave Sill <de5@@ornl.gov> -;; Dave Brennan <brennan@@hal.com> -;; Eric Raymond <esr@@snark.thyrsus.com> -@end group -@end smallexample - -@item Maintainer -This line should contain a single name/address as in the Author line, or -an address only, or the string @samp{FSF}. If there is no maintainer -line, the person(s) in the Author field are presumed to be the -maintainers. The example above is mildly bogus because the maintainer -line is redundant. - -The idea behind the @samp{Author} and @samp{Maintainer} lines is to make -possible a Lisp function to ``send mail to the maintainer'' without -having to mine the name out by hand. - -Be sure to surround the network address with @samp{<@dots{}>} if -you include the person's full name as well as the network address. - -@item Created -This optional line gives the original creation date of the -file. For historical interest only. - -@item Version -If you wish to record version numbers for the individual Lisp program, put -them in this line. - -@item Adapted-By -In this header line, place the name of the person who adapted the -library for installation (to make it fit the style conventions, for -example). - -@item Keywords -This line lists keywords for the @code{finder-by-keyword} help command. -Please use that command to see a list of the meaningful keywords. - -This field is important; it's how people will find your package when -they're looking for things by topic area. To separate the keywords, you -can use spaces, commas, or both. -@end table - - Just about every Lisp library ought to have the @samp{Author} and -@samp{Keywords} header comment lines. Use the others if they are -appropriate. You can also put in header lines with other header -names---they have no standard meanings, so they can't do any harm. - - We use additional stylized comments to subdivide the contents of the -library file. These should be separated by blank lines from anything -else. Here is a table of them: - -@table @samp -@item ;;; Commentary: -This begins introductory comments that explain how the library works. -It should come right after the copying permissions, terminated by a -@samp{Change Log}, @samp{History} or @samp{Code} comment line. This -text is used by the Finder package, so it should make sense in that -context. - -@item ;;; Documentation: -This was used in some files in place of @samp{;;; Commentary:}, -but it is deprecated. - -@item ;;; Change Log: -This begins change log information stored in the library file (if you -store the change history there). For Lisp files distributed with Emacs, -the change history is kept in the file @file{ChangeLog} and not in the -source file at all; these files generally do not have a @samp{;;; Change -Log:} line. @samp{History} is an alternative to @samp{Change Log}. - -@item ;;; Code: -This begins the actual code of the program. - -@item ;;; @var{filename} ends here -This is the @dfn{footer line}; it appears at the very end of the file. -Its purpose is to enable people to detect truncated versions of the file -from the lack of a footer line. -@end table - -@ignore - arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e -@end ignore diff --git a/lispref/two-volume-cross-refs.txt b/lispref/two-volume-cross-refs.txt deleted file mode 100644 index 6e40920cf66..00000000000 --- a/lispref/two-volume-cross-refs.txt +++ /dev/null @@ -1,322 +0,0 @@ -Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007 - Free Software Foundation, Inc. - See end for copying conditions. - -Two Volume Cross References -=========================== - -12 June 2007 (karl) - -For lispref 2.9 (for Emacs 22, June 2007), I created a very ugly -Makefile, in the file two-volume.make, to encapsulate all the steps -below, without manual intervention. In theory, simply running "make -f -two-volume.make" should create a vol1.pdf and vol2.pdf with all the -niceties worked out. - -One issue not explicitly discussed below is getting page numbers right. -It's not enough to go through the whole process. You have to go through -the whole process twice -- otherwise, some index entries and/or toc -entries will be off by one. See two-volume.make for a few more comments. - -For future editions, it should suffice to update the usual things in -vol[12].texi (as well as elisp.texi). That was my hope, anyway. - - -18 March 1992 (bob) - -This enables you to create manuals in *two* volumes, with tables of -contents, cross references, and indices in each volume referring to -*both* volumes. - -The procedure is tedious. However, the resulting two volumes are -conveniently organized. Each has an index of the whole two volumes. -Each volume starts with page 1. (I don't like multi-volume works -where each volume starts with a higher page number since I find it -harder to go to the right place in the volume.) - -References to the same volume are just the page number; references to -the other volume are a volumne number (in Roman numerals) preceding -the page number. - -For example, in Volume I: - - list length ......... 90 - list motion ......II:117 - -and in Volume II: - - list length ....... I:90 - list motion .........117 - -All other references and the table of contents work the same way. I -find this *very* helpful. - - -In brief: you run tex on a .texi file with - - a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file - b. redone .aux file - c. redone .fns file - - -Here are the steps in detail: - -% tex vol1.texi -% texindex vol1.?? -% tex vol1.texi - -% tex vol2.texi -% texindex vol2.?? -% tex vol2.texi - -### Create .aux files with volume numbers for other volume. - -% cp vol1.aux elisp1-aux -% cp vol2.aux elisp2-aux - -% cp vol1.aux elisp1-aux-vol-added -% cp vol2.aux elisp2-aux-vol-added - -on elisp1-aux-vol-number-added -(volume-aux-markup 1) see defun for volume-aux-markup below. -to create elisp1-aux-vol-added - -on elisp2-aux-vol-number-added -(volume-aux-markup 2) -to create elisp2-aux-vol-added - -insert elisp2-aux-vol-added into vol1.aux (append) -insert elisp1-aux-vol-added into vol2.aux (prepend) - -(so you dont have to do it again) -% cp vol1.aux elisp1-aux-ready -% cp vol2.aux elisp2-aux-ready - - -### Create .fn files with volume numbers for other volume. - -% cp vol1.fn elisp1-fn -% cp vol2.fn elisp2-fn - -% cp vol1.fn elisp1-fn-vol-number-added -% cp vol2.fn elisp2-fn-vol-number-added - -on elisp1-fn-vol-number-added -(volume-index-markup "I") -to create elisp1-fn-vol-number-added - -on elisp2-fn-vol-number-added -(volume-index-markup "II") -to create elisp2-fn-vol-number-added - -insert elisp2-fn-vol-number-added into vol1.fn: do following `cat' -insert elisp1-fn-vol-number-added into vol2.fn: do following `cat' - -% cat elisp2-fn-vol-number-added >> vol1.fn -% cat elisp1-fn-vol-number-added >> vol2.fn - -Be sure to handle special case entries by hand. -Be sure that .fn file has no blank lines. - -% texindex vol1.fn -% texindex vol2.fn - -(so you dont have to do it again) -% cp vol1.fns elisp1-fns-2vol-ready -% cp vol2.fns elisp2-fns-2vol-ready - -### Create merged .toc file with volume number headings. - -append vol2.toc to vol1.toc with following `cat' - -% cat vol1.toc vol2.toc > elisp-toc-2vol.toc - -and edit in Volume titles - -\unnumbchapentry {Volume 1}{} -\unnumbchapentry {}{} - -\unnumbchapentry {Index}{295} -\unnumbchapentry {}{} -\unnumbchapentry {Volume 2}{} -\unnumbchapentry {}{} - -If you want to put in volume numbers for TOC, then do this: -Create volume specific .toc files with volume numbers in them. - -% cp elisp-toc-2vol.toc elisp1-toc.toc -% cp elisp-toc-2vol.toc elisp2-toc.toc - -Use keyboard macro to put I: in first half of elisp1-toc.toc and -II: in first half of elisp2-toc.toc - -Copy the tocs to something you can remember more easily - -% cp elisp2-toc.toc elisp1-toc-ready.toc -% cp elisp1-toc.toc elisp2-toc-ready.toc - -Then, edit vol1.texi to input elisp1-toc-ready.toc -and vol2.texi to input elisp2-toc-ready.toc - - -### Now format the two volumes: - -% cp elisp1-aux-2vol-ready vol1.aux -% cp elisp2-aux-2vol-ready vol2.aux - -% tex vol1.texi -% tex vol2.texi - - - -For every additional run: - -### recopy aux files so the correct ones are read: -% cp elisp1-aux-2vol-ready vol1.aux -% cp elisp2-aux-2vol-ready vol2.aux - -Do not run texindex. Then proper sorted index will stay. - else do: % cp elisp2-fns-2vol-ready vol2.fns - -Do not change the .texi files; they will call the elisp-toc-2vol.toc file. - -% tex vol1.texi -% tex vol2.texi - -================================================================ - - -(defun volume-aux-markup (arg) - "Append `vol. NUMBER' to page number. -Apply to aux file that you save. -Then insert marked file into other volume's .aux file." - (interactive "sType volume number, 1 or 2: " ) - (goto-char (point-min)) - (while (search-forward "-pg" nil t) - (end-of-line 1) - (delete-backward-char 1 nil) - (insert ", vol.'tie" arg "}"))) - -(defun volume-index-markup (arg) - "Prepend `NUMBER:' to page number. Use Roman Numeral. -Apply only to unsorted index file, -Then insert marked file into other volume's unsorted index file. -Then run texindex on that file and save." - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "\\entry" nil t) - (search-forward "}{" (save-excursion (end-of-line) (point)) nil) - (insert arg ":"))) - - -================================================================ - - -The steps: - -1. Run TeX, texindex and TeX on file1. -2. Run TeX, texindex and TeX on file2. - -3. Copy both .aux files into specially named files - -4. In the case of the elisp ref manual, - - copy the *unsorted* function index files into specially named files - (no other index used in elisp ref manual) - - -5. For aux files: - - Run a function on the specially named .aux files to label each - entry according to volume. Save these files. - - i.e., convert - 'xrdef {Special-pg}{7} to 'xrdef {Special-pg}{7, vol.'tie1} - -5a.Insert each specially named .aux file into the regular .aux file of - the other volume. - -6. For index files: - - Run a function on the specially named unsorted index files to label - each entry according to volume. Save these files. - -6b.Insert each specially named marked unsorted index file into the - regular unsorted file of the other volume. Run texindex on this - -7. Insert the other volumes .toc file into the .toc, edit, and rename to - elisp-toc-2vol.toc - -7a. insert special @contents and @summarycontents defs into .texi files. - -8. Run TeX on each .texi file. - -================ - - - -Here is the discursive commentary: - -I've been running some small test files, called test1.texi and -test2.texi. As far as I can see, if we run tex on the two test files, -tex creates a .aux for each that includes the names of all the nodes -in that file. The node names are used for cross references. - -If you insert the .aux file for the second test file, test2.aux, into -the .aux file for the first test file, test1.aux, then when you next -run TeX on the first test file, test1.texi, the second volume cross -references are inserted. - -You can edit the text of the cross reference in test2.aux to include -the volume number. - -For example, you can take the following two lines from test1.texi and -insert them into test2.texi: - - 'xrdef {Special-pg}{7} - 'xrdef {Special-snt}{Section'tie1.6} - -You can re-edit this to show that the page is in volume 1: - - 'xrdef {Special-pg}{7, vol.'tie1} - 'xrdef {Special-snt}{Section'tie1.6} - -(The 'tie is a TeX special command to keep the number tied on one -line to the previous word. I don't know if it works after a period in -the "vol." but figure it is worth trying. {The ' is the @ of .aux files.} -Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the -definition for 'tie is the following: - - \def\tie{\penalty 10000\ } % Save plain tex definition of ~. - -) - -After running tex on the test2.texi file with the augmented test2.aux -file, you can see the following in the resulting DVI file: - - See Section 1.6 [Special], page 7, vol. 1 - -Note that TeX rewrites the .aux file each time TeX is run, so after -running Tex using an .aux file augmented with the .aux file from the -other volume, the new .aux file will *lack* the other volumes cross -references. Save your augmented .aux file in some other name for -another run! - - -COPYING CONDITIONS - -This file is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 3, or (at your option) -any later version. - -This file is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this file; see the file COPYING. If not, write to -the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -Boston, MA 02110-1301, USA. diff --git a/lispref/two-volume.make b/lispref/two-volume.make deleted file mode 100644 index b2550576825..00000000000 --- a/lispref/two-volume.make +++ /dev/null @@ -1,227 +0,0 @@ -# Copyright 2007 Free Software Foundation, Inc. -# See end for copying conditions. - -# although it would be nice to use tex rather than pdftex to avoid -# colors, spurious warnings about names being referenced but not -# existing, etc., dvips | ps2pdf doesn't preserve the page size. -# Instead of creating a special dvips config file, put up with the warnings. -tex = pdftex -interaction=nonstopmode - -all: vol1.pdf vol2.pdf - -# vol1.texi and vol2.texi specially define \tocreadfilename so we can -# use our premade .toc's. -# -vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready - @echo -e "\f Final TeX run for volume 1..." - cp elisp1med-toc-ready elisp1-toc-ready.toc - cp elisp1med-fns-ready vol1.fns - cp elisp1med-aux-ready vol1.aux - $(tex) vol1.texi -# -vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready - @echo "Final TeX run for volume 2..." - cp elisp2med-toc-ready elisp2-toc-ready.toc - cp elisp2med-fns-ready vol2.fns - cp elisp2med-aux-ready vol2.aux - $(tex) vol2.texi - -# intermediate toc files. -# -# vol1 toc: volume 1, page break, volume 2 (with II: prepended). -elisp1med-toc-ready: elisp1med-init elisp2med-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - cat elisp1med-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@ -# -# vol2 toc: volume 1 (with I: prepended), page break, volume 2. -elisp2med-toc-ready: elisp1med-init elisp2med-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - cat elisp2med-toc >>$@ - - -# intermediate aux files. -# -# append vol2's fixed aux to normal vol1. -elisp1med-aux-ready: elisp2med-aux-vol-added - cat elisp1med-aux $< >$@ -# -# prepend vol1's fixed aux to vol2. -elisp2med-aux-ready: elisp1med-aux-vol-added - cat $< elisp2med-aux >$@ - -# on -pg entries, append volume number after page number. -elisp1med-aux-vol-added: elisp1med-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1med-aux >$@ -# -elisp2med-aux-vol-added: elisp2med-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@ - - - -# intermediate index (fns) file. -# -elisp1med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added - cat elisp2med-fn-vol-added >>vol1.fn - texindex vol1.fn - cp vol1.fns $@ -# -elisp2med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added - cat elisp1med-fn-vol-added >>vol2.fn - texindex vol2.fn - cp vol2.fns $@ - -# Insert volume number (I: or II:) into index file. -elisp1med-fn-vol-added: elisp1med-init - cp vol1.fn elisp1med-fn - sed 's/}{/}{I:/' elisp1med-fn >$@ -# -elisp2med-fn-vol-added: elisp2med-init - cp vol2.fn elisp2med-fn - sed 's/}{/}{II:/' elisp2med-fn >$@ - -# ----------------------------------------------------------------------------- -# everything above is essentially a duplicate of everything below. sorry. -# ----------------------------------------------------------------------------- - -# intermediate TeX runs. -# -# this generates what would be the final versions -- except the page -# numbers aren't right. The process of adding the I: and II: changes -# the page breaks, so a few index entries, at least are wrong. (In -# 2007, x-meta-keysym in vol.II ended up on page 374 when the index had -# it on page 375 from the initial run.) -# -# So, we start all over again, from these fns/aux/toc files. -# -elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready texinfo.tex - @echo -e "\f Intermediate TeX run for volume 1..." - cp elisp1init-toc-ready elisp1-toc-ready.toc - cp elisp1-fns-ready vol1.fns - cp elisp1-aux-ready vol1.aux - $(tex) vol1.texi - texindex vol1.?? - mv vol1.aux elisp1med-aux - mv vol1.toc elisp1med-toc -# -elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready texinfo.tex - @echo "Final TeX run for volume 2..." - cp elisp2init-toc-ready elisp2-toc-ready.toc - cp elisp2-fns-ready vol2.fns - cp elisp2-aux-ready vol2.aux - $(tex) vol2.texi - texindex vol2.?? - mv vol2.aux elisp2med-aux - mv vol2.toc elisp2med-toc - - -# initial toc files. -# -# vol1 toc: volume 1, page break, volume 2 (with II: prepended). -elisp1init-toc-ready: elisp1-init elisp2-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - cat elisp1-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@ -# -# vol2 toc: volume 1 (with I: prepended), page break, volume 2. -elisp2init-toc-ready: elisp1-init elisp2-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - cat elisp2-toc >>$@ - - -# initial aux files. -# -# append vol2's fixed aux to normal vol1. The initial runs saved -# elisp1-aux and elisp2-aux. -elisp1-aux-ready: elisp2-aux-vol-added - cat elisp1-aux $< >$@ -# -# prepend vol1's fixed aux to vol2. -elisp2-aux-ready: elisp1-aux-vol-added - cat $< elisp2-aux >$@ - -# on -pg entries, append volume number after page number. -elisp1-aux-vol-added: elisp1-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1-aux >$@ -# -elisp2-aux-vol-added: elisp2-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@ - - -# initial index (fns) file. -# -# Append other volume's index entries to this one's. -# Index entries in this volume will then take precedence. -elisp1-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added - cat elisp2-fn-vol-added >>vol1.fn - texindex vol1.fn - cp vol1.fns $@ -# -elisp2-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added - cat elisp1-fn-vol-added >>vol2.fn - texindex vol2.fn - cp vol2.fns $@ - -# Insert volume number (I: or II:) into index file. -elisp1-fn-vol-added: elisp1-init - cp vol1.fn elisp1-fn - sed 's/}{/}{I:/' elisp1-fn >$@ -# -elisp2-fn-vol-added: elisp2-init - cp vol2.fn elisp2-fn - sed 's/}{/}{II:/' elisp2-fn >$@ - - -# initial TeX runs. -# -# We use the .fn, .aux, and .toc files created here in subsequent -# processing. The page numbers generated here will not be correct yet, -# but we run texindex and TeX a second time just to get them closer. -# Otherwise it might take even longer for them to converge. -# -elisp1-init: vol1.texi - @echo -e "\f Initial TeX run for volume 1..." - rm -f vol1.aux vol1.toc - $(tex) $< - texindex vol1.?? - mv vol1.aux elisp1-aux - mv vol1.toc elisp1-toc - touch $@ -# -elisp2-init: vol2.texi - @echo "Initial TeX run for volume 2..." - rm -f vol2.aux vol2.toc - $(tex) $< - texindex vol2.?? - mv vol2.aux elisp2-aux - mv vol2.toc elisp2-toc - touch $@ - -# COPYING CONDITIONS -# -# This file is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 3, or (at your option) -# any later version. -# -# This file is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this file; see the file COPYING. If not, write to -# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -# Boston, MA 02110-1301, USA. - -# arch-tag: 5c258a2e-d4a9-4d0e-b279-fb3a6faa27eb diff --git a/lispref/two.el b/lispref/two.el deleted file mode 100644 index baade844463..00000000000 --- a/lispref/two.el +++ /dev/null @@ -1,80 +0,0 @@ -;; Auxiliary functions for preparing a two volume manual. - -;; Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007 -;; Free Software Foundation, Inc. - -;; --rjc 30mar92 - -;; This file is free software; you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. - -;; This file is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with this file; see the file COPYING. If not, write to -;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. - -(defun volume-aux-markup (arg) - "Append `vol. NUMBER' to page number. -Apply to aux file that you save. -Then insert marked file into other volume's .aux file." - (interactive "sType volume number, 1 or 2: " ) - (goto-char (point-min)) - (while (search-forward "-pg" nil t) - (end-of-line 1) - (delete-backward-char 1 nil) - (insert ", vol.'tie" arg "}"))) - -(defun volume-index-markup (arg) - "Prepend `NUMBER:' to page number. Use Roman Numeral. -Apply only to unsorted index file, -Then insert marked file into other volume's unsorted index file. -Then run texindex on that file and save." - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "\\entry" nil t) - (search-forward "}{" (save-excursion (end-of-line) (point)) nil) - (insert arg ":"))) - -(defun volume-numbers-toc-markup (arg) - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "chapentry" nil t) - (end-of-line) - (search-backward "{" nil t) - (forward-char 1) - (insert arg ":"))) - -(defun volume-header-toc-markup () - "Insert Volume I and Volume II text into .toc file. -NOTE: this auxilary function is file specific. -This is for the *Elisp Ref Manual*" - (interactive) - (goto-char (point-min)) - (insert "\\unnumbchapentry {Volume 1}{}\n\\unnumbchapentry {}{}\n") - (search-forward "\\unnumbchapentry {Index}") - (forward-line 1) - (insert - "\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {Volume 2}{}\n\\unnumbchapentry {}{}\n")) - - -;;; In batch mode, you cannot call functions with args; hence this kludge: - -(defun volume-aux-markup-1 () (volume-aux-markup "1")) -(defun volume-aux-markup-2 () (volume-aux-markup "2")) - -(defun volume-index-markup-I () (volume-index-markup "I")) -(defun volume-index-markup-II () (volume-index-markup "II")) - -(defun volume-numbers-toc-markup-I () (volume-numbers-toc-markup "I")) -(defun volume-numbers-toc-markup-II () (volume-numbers-toc-markup "II")) - -;;; arch-tag: 848955fe-e9cf-45e7-a2f1-570ef156d6a5 diff --git a/lispref/variables.texi b/lispref/variables.texi deleted file mode 100644 index 9d9dc8260bb..00000000000 --- a/lispref/variables.texi +++ /dev/null @@ -1,1908 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/variables -@node Variables, Functions, Control Structures, Top -@chapter Variables -@cindex variable - - A @dfn{variable} is a name used in a program to stand for a value. -Nearly all programming languages have variables of some sort. In the -text of a Lisp program, variables are written using the syntax for -symbols. - - In Lisp, unlike most programming languages, programs are represented -primarily as Lisp objects and only secondarily as text. The Lisp -objects used for variables are symbols: the symbol name is the variable -name, and the variable's value is stored in the value cell of the -symbol. The use of a symbol as a variable is independent of its use as -a function name. @xref{Symbol Components}. - - The Lisp objects that constitute a Lisp program determine the textual -form of the program---it is simply the read syntax for those Lisp -objects. This is why, for example, a variable in a textual Lisp program -is written using the read syntax for the symbol that represents the -variable. - -@menu -* 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. -@end menu - -@node Global Variables -@section Global Variables -@cindex global variable - - The simplest way to use a variable is @dfn{globally}. This means that -the variable has just one value at a time, and this value is in effect -(at least for the moment) throughout the Lisp system. The value remains -in effect until you specify a new one. When a new value replaces the -old one, no trace of the old value remains in the variable. - - You specify a value for a symbol with @code{setq}. For example, - -@example -(setq x '(a b)) -@end example - -@noindent -gives the variable @code{x} the value @code{(a b)}. Note that -@code{setq} does not evaluate its first argument, the name of the -variable, but it does evaluate the second argument, the new value. - - Once the variable has a value, you can refer to it by using the symbol -by itself as an expression. Thus, - -@example -@group -x @result{} (a b) -@end group -@end example - -@noindent -assuming the @code{setq} form shown above has already been executed. - - If you do set the same variable again, the new value replaces the old -one: - -@example -@group -x - @result{} (a b) -@end group -@group -(setq x 4) - @result{} 4 -@end group -@group -x - @result{} 4 -@end group -@end example - -@node Constant Variables -@section Variables that Never Change -@kindex setting-constant -@cindex keyword symbol -@cindex variable with constant value -@cindex constant variables -@cindex symbol that evaluates to itself -@cindex symbol with constant value - - In Emacs Lisp, certain symbols normally evaluate to themselves. These -include @code{nil} and @code{t}, as well as any symbol whose name starts -with @samp{:} (these are called @dfn{keywords}). These symbols cannot -be rebound, nor can their values be changed. Any attempt to set or bind -@code{nil} or @code{t} signals a @code{setting-constant} error. The -same is true for a keyword (a symbol whose name starts with @samp{:}), -if it is interned in the standard obarray, except that setting such a -symbol to itself is not an error. - -@example -@group -nil @equiv{} 'nil - @result{} nil -@end group -@group -(setq nil 500) -@error{} Attempt to set constant symbol: nil -@end group -@end example - -@defun keywordp object -function returns @code{t} if @var{object} is a symbol whose name -starts with @samp{:}, interned in the standard obarray, and returns -@code{nil} otherwise. -@end defun - -@node Local Variables -@section Local Variables -@cindex binding local variables -@cindex local variables -@cindex local binding -@cindex global binding - - Global variables have values that last until explicitly superseded -with new values. Sometimes it is useful to create variable values that -exist temporarily---only until a certain part of the program finishes. -These values are called @dfn{local}, and the variables so used are -called @dfn{local variables}. - - For example, when a function is called, its argument variables receive -new local values that last until the function exits. The @code{let} -special form explicitly establishes new local values for specified -variables; these last until exit from the @code{let} form. - -@cindex shadowing of variables - Establishing a local value saves away the previous value (or lack of -one) of the variable. When the life span of the local value is over, -the previous value is restored. In the mean time, we say that the -previous value is @dfn{shadowed} and @dfn{not visible}. Both global and -local values may be shadowed (@pxref{Scope}). - - If you set a variable (such as with @code{setq}) while it is local, -this replaces the local value; it does not alter the global value, or -previous local values, that are shadowed. To model this behavior, we -speak of a @dfn{local binding} of the variable as well as a local value. - - The local binding is a conceptual place that holds a local value. -Entry to a function, or a special form such as @code{let}, creates the -local binding; exit from the function or from the @code{let} removes the -local binding. As long as the local binding lasts, the variable's value -is stored within it. Use of @code{setq} or @code{set} while there is a -local binding stores a different value into the local binding; it does -not create a new binding. - - We also speak of the @dfn{global binding}, which is where -(conceptually) the global value is kept. - -@cindex current binding - A variable can have more than one local binding at a time (for -example, if there are nested @code{let} forms that bind it). In such a -case, the most recently created local binding that still exists is the -@dfn{current binding} of the variable. (This rule is called -@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no -local bindings, the variable's global binding is its current binding. -We sometimes call the current binding the @dfn{most-local existing -binding}, for emphasis. Ordinary evaluation of a symbol always returns -the value of its current binding. - - The special forms @code{let} and @code{let*} exist to create -local bindings. - -@defspec let (bindings@dots{}) forms@dots{} -This special form binds variables according to @var{bindings} and then -evaluates all of the @var{forms} in textual order. The @code{let}-form -returns the value of the last form in @var{forms}. - -Each of the @var{bindings} is either @w{(i) a} symbol, in which case -that symbol is bound to @code{nil}; or @w{(ii) a} list of the form -@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is -bound to the result of evaluating @var{value-form}. If @var{value-form} -is omitted, @code{nil} is used. - -All of the @var{value-form}s in @var{bindings} are evaluated in the -order they appear and @emph{before} binding any of the symbols to them. -Here is an example of this: @code{z} is bound to the old value of -@code{y}, which is 2, not the new value of @code{y}, which is 1. - -@example -@group -(setq y 2) - @result{} 2 -@end group -@group -(let ((y 1) - (z y)) - (list y z)) - @result{} (1 2) -@end group -@end example -@end defspec - -@defspec let* (bindings@dots{}) forms@dots{} -This special form is like @code{let}, but it binds each variable right -after computing its local value, before computing the local value for -the next variable. Therefore, an expression in @var{bindings} can -reasonably refer to the preceding symbols bound in this @code{let*} -form. Compare the following example with the example above for -@code{let}. - -@example -@group -(setq y 2) - @result{} 2 -@end group -@group -(let* ((y 1) - (z y)) ; @r{Use the just-established value of @code{y}.} - (list y z)) - @result{} (1 1) -@end group -@end example -@end defspec - - Here is a complete list of the other facilities that create local -bindings: - -@itemize @bullet -@item -Function calls (@pxref{Functions}). - -@item -Macro calls (@pxref{Macros}). - -@item -@code{condition-case} (@pxref{Errors}). -@end itemize - - Variables can also have buffer-local bindings (@pxref{Buffer-Local -Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a -few variables have terminal-local bindings (@pxref{Multiple Displays}). -These kinds of bindings work somewhat like ordinary local bindings, but -they are localized depending on ``where'' you are in Emacs, rather than -localized in time. - -@defvar max-specpdl-size -@anchor{Definition of max-specpdl-size} -@cindex variable limit error -@cindex evaluation error -@cindex infinite recursion -This variable defines the limit on the total number of local variable -bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,, -Cleaning Up from Nonlocal Exits}) that are allowed before signaling an -error (with data @code{"Variable binding depth exceeds -max-specpdl-size"}). - -This limit, with the associated error when it is exceeded, is one way -that Lisp avoids infinite recursion on an ill-defined function. -@code{max-lisp-eval-depth} provides another limit on depth of nesting. -@xref{Definition of max-lisp-eval-depth,, Eval}. - -The default value is 1000. Entry to the Lisp debugger increases the -value, if there is little room left, to make sure the debugger itself -has room to execute. -@end defvar - -@node Void Variables -@section When a Variable is ``Void'' -@kindex void-variable -@cindex void variable - - If you have never given a symbol any value as a global variable, we -say that that symbol's global value is @dfn{void}. In other words, the -symbol's value cell does not have any Lisp object in it. If you try to -evaluate the symbol, you get a @code{void-variable} error rather than -a value. - - Note that a value of @code{nil} is not the same as void. The symbol -@code{nil} is a Lisp object and can be the value of a variable just as any -other object can be; but it is @emph{a value}. A void variable does not -have any value. - - After you have given a variable a value, you can make it void once more -using @code{makunbound}. - -@defun makunbound symbol -This function makes the current variable binding of @var{symbol} void. -Subsequent attempts to use this symbol's value as a variable will signal -the error @code{void-variable}, unless and until you set it again. - -@code{makunbound} returns @var{symbol}. - -@example -@group -(makunbound 'x) ; @r{Make the global value of @code{x} void.} - @result{} x -@end group -@group -x -@error{} Symbol's value as variable is void: x -@end group -@end example - -If @var{symbol} is locally bound, @code{makunbound} affects the most -local existing binding. This is the only way a symbol can have a void -local binding, since all the constructs that create local bindings -create them with values. In this case, the voidness lasts at most as -long as the binding does; when the binding is removed due to exit from -the construct that made it, the previous local or global binding is -reexposed as usual, and the variable is no longer void unless the newly -reexposed binding was void all along. - -@smallexample -@group -(setq x 1) ; @r{Put a value in the global binding.} - @result{} 1 -(let ((x 2)) ; @r{Locally bind it.} - (makunbound 'x) ; @r{Void the local binding.} - x) -@error{} Symbol's value as variable is void: x -@end group -@group -x ; @r{The global binding is unchanged.} - @result{} 1 - -(let ((x 2)) ; @r{Locally bind it.} - (let ((x 3)) ; @r{And again.} - (makunbound 'x) ; @r{Void the innermost-local binding.} - x)) ; @r{And refer: it's void.} -@error{} Symbol's value as variable is void: x -@end group - -@group -(let ((x 2)) - (let ((x 3)) - (makunbound 'x)) ; @r{Void inner binding, then remove it.} - x) ; @r{Now outer @code{let} binding is visible.} - @result{} 2 -@end group -@end smallexample -@end defun - - A variable that has been made void with @code{makunbound} is -indistinguishable from one that has never received a value and has -always been void. - - You can use the function @code{boundp} to test whether a variable is -currently void. - -@defun boundp variable -@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void; -more precisely, if its current binding is not void. It returns -@code{nil} otherwise. - -@smallexample -@group -(boundp 'abracadabra) ; @r{Starts out void.} - @result{} nil -@end group -@group -(let ((abracadabra 5)) ; @r{Locally bind it.} - (boundp 'abracadabra)) - @result{} t -@end group -@group -(boundp 'abracadabra) ; @r{Still globally void.} - @result{} nil -@end group -@group -(setq abracadabra 5) ; @r{Make it globally nonvoid.} - @result{} 5 -@end group -@group -(boundp 'abracadabra) - @result{} t -@end group -@end smallexample -@end defun - -@node Defining Variables -@section Defining Global Variables -@cindex variable definition - - You may announce your intention to use a symbol as a global variable -with a @dfn{variable definition}: a special form, either @code{defconst} -or @code{defvar}. - - In Emacs Lisp, definitions serve three purposes. First, they inform -people who read the code that certain symbols are @emph{intended} to be -used a certain way (as variables). Second, they inform the Lisp system -of these things, supplying a value and documentation. Third, they -provide information to utilities such as @code{etags} and -@code{make-docfile}, which create data bases of the functions and -variables in a program. - - The difference between @code{defconst} and @code{defvar} is primarily -a matter of intent, serving to inform human readers of whether the value -should ever change. Emacs Lisp does not restrict the ways in which a -variable can be used based on @code{defconst} or @code{defvar} -declarations. However, it does make a difference for initialization: -@code{defconst} unconditionally initializes the variable, while -@code{defvar} initializes it only if it is void. - -@ignore - One would expect user option variables to be defined with -@code{defconst}, since programs do not change them. Unfortunately, this -has bad results if the definition is in a library that is not preloaded: -@code{defconst} would override any prior value when the library is -loaded. Users would like to be able to set user options in their init -files, and override the default values given in the definitions. For -this reason, user options must be defined with @code{defvar}. -@end ignore - -@defspec defvar symbol [value [doc-string]] -This special form defines @var{symbol} as a variable and can also -initialize and document it. The definition informs a person reading -your code that @var{symbol} is used as a variable that might be set or -changed. Note that @var{symbol} is not evaluated; the symbol to be -defined must appear explicitly in the @code{defvar}. - -If @var{symbol} is void and @var{value} is specified, @code{defvar} -evaluates it and sets @var{symbol} to the result. But if @var{symbol} -already has a value (i.e., it is not void), @var{value} is not even -evaluated, and @var{symbol}'s value remains unchanged. If @var{value} -is omitted, the value of @var{symbol} is not changed in any case. - -If @var{symbol} has a buffer-local binding in the current buffer, -@code{defvar} operates on the default value, which is buffer-independent, -not the current (buffer-local) binding. It sets the default value if -the default value is void. @xref{Buffer-Local Variables}. - -When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in -Emacs Lisp mode (@code{eval-defun}), a special feature of -@code{eval-defun} arranges to set the variable unconditionally, without -testing whether its value is void. - -If the @var{doc-string} argument appears, it specifies the documentation -for the variable. (This opportunity to specify documentation is one of -the main benefits of defining the variable.) The documentation is -stored in the symbol's @code{variable-documentation} property. The -Emacs help functions (@pxref{Documentation}) look for this property. - -If the variable is a user option that users would want to set -interactively, you should use @samp{*} as the first character of -@var{doc-string}. This lets users set the variable conveniently using -the @code{set-variable} command. Note that you should nearly always -use @code{defcustom} instead of @code{defvar} to define these -variables, so that users can use @kbd{M-x customize} and related -commands to set them. @xref{Customization}. - -Here are some examples. This form defines @code{foo} but does not -initialize it: - -@example -@group -(defvar foo) - @result{} foo -@end group -@end example - -This example initializes the value of @code{bar} to @code{23}, and gives -it a documentation string: - -@example -@group -(defvar bar 23 - "The normal weight of a bar.") - @result{} bar -@end group -@end example - -The following form changes the documentation string for @code{bar}, -making it a user option, but does not change the value, since @code{bar} -already has a value. (The addition @code{(1+ nil)} would get an error -if it were evaluated, but since it is not evaluated, there is no error.) - -@example -@group -(defvar bar (1+ nil) - "*The normal weight of a bar.") - @result{} bar -@end group -@group -bar - @result{} 23 -@end group -@end example - -Here is an equivalent expression for the @code{defvar} special form: - -@example -@group -(defvar @var{symbol} @var{value} @var{doc-string}) -@equiv{} -(progn - (if (not (boundp '@var{symbol})) - (setq @var{symbol} @var{value})) - (if '@var{doc-string} - (put '@var{symbol} 'variable-documentation '@var{doc-string})) - '@var{symbol}) -@end group -@end example - -The @code{defvar} form returns @var{symbol}, but it is normally used -at top level in a file where its value does not matter. -@end defspec - -@defspec defconst symbol value [doc-string] -This special form defines @var{symbol} as a value and initializes it. -It informs a person reading your code that @var{symbol} has a standard -global value, established here, that should not be changed by the user -or by other programs. Note that @var{symbol} is not evaluated; the -symbol to be defined must appear explicitly in the @code{defconst}. - -@code{defconst} always evaluates @var{value}, and sets the value of -@var{symbol} to the result. If @var{symbol} does have a buffer-local -binding in the current buffer, @code{defconst} sets the default value, -not the buffer-local value. (But you should not be making -buffer-local bindings for a symbol that is defined with -@code{defconst}.) - -Here, @code{pi} is a constant that presumably ought not to be changed -by anyone (attempts by the Indiana State Legislature notwithstanding). -As the second form illustrates, however, this is only advisory. - -@example -@group -(defconst pi 3.1415 "Pi to five places.") - @result{} pi -@end group -@group -(setq pi 3) - @result{} pi -@end group -@group -pi - @result{} 3 -@end group -@end example -@end defspec - -@defun user-variable-p variable -@cindex user option -This function returns @code{t} if @var{variable} is a user option---a -variable intended to be set by the user for customization---and -@code{nil} otherwise. (Variables other than user options exist for the -internal purposes of Lisp programs, and users need not know about them.) - -User option variables are distinguished from other variables either -though being declared using @code{defcustom}@footnote{They may also be -declared equivalently in @file{cus-start.el}.} or by the first character -of their @code{variable-documentation} property. If the property exists -and is a string, and its first character is @samp{*}, then the variable -is a user option. Aliases of user options are also user options. -@end defun - -@kindex variable-interactive - If a user option variable has a @code{variable-interactive} property, -the @code{set-variable} command uses that value to control reading the -new value for the variable. The property's value is used as if it were -specified in @code{interactive} (@pxref{Using Interactive}). However, -this feature is largely obsoleted by @code{defcustom} -(@pxref{Customization}). - - @strong{Warning:} If the @code{defconst} and @code{defvar} special -forms are used while the variable has a local binding (made with -@code{let}, or a function argument), they set the local-binding's -value; the top-level binding is not changed. This is not what you -usually want. To prevent it, use these special forms at top level in -a file, where normally no local binding is in effect, and make sure to -load the file before making a local binding for the variable. - -@node Tips for Defining -@section Tips for Defining Variables Robustly - - When you define a variable whose value is a function, or a list of -functions, use a name that ends in @samp{-function} or -@samp{-functions}, respectively. - - There are several other variable name conventions; -here is a complete list: - -@table @samp -@item @dots{}-hook -The variable is a normal hook (@pxref{Hooks}). - -@item @dots{}-function -The value is a function. - -@item @dots{}-functions -The value is a list of functions. - -@item @dots{}-form -The value is a form (an expression). - -@item @dots{}-forms -The value is a list of forms (expressions). - -@item @dots{}-predicate -The value is a predicate---a function of one argument that returns -non-@code{nil} for ``good'' arguments and @code{nil} for ``bad'' -arguments. - -@item @dots{}-flag -The value is significant only as to whether it is @code{nil} or not. - -@item @dots{}-program -The value is a program name. - -@item @dots{}-command -The value is a whole shell command. - -@item @dots{}-switches -The value specifies options for a command. -@end table - - When you define a variable, always consider whether you should mark -it as ``risky''; see @ref{File Local Variables}. - - When defining and initializing a variable that holds a complicated -value (such as a keymap with bindings in it), it's best to put the -entire computation of the value into the @code{defvar}, like this: - -@example -(defvar my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - map) - @var{docstring}) -@end example - -@noindent -This method has several benefits. First, if the user quits while -loading the file, the variable is either still uninitialized or -initialized properly, never in-between. If it is still uninitialized, -reloading the file will initialize it properly. Second, reloading the -file once the variable is initialized will not alter it; that is -important if the user has run hooks to alter part of the contents (such -as, to rebind keys). Third, evaluating the @code{defvar} form with -@kbd{C-M-x} @emph{will} reinitialize the map completely. - - Putting so much code in the @code{defvar} form has one disadvantage: -it puts the documentation string far away from the line which names the -variable. Here's a safe way to avoid that: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - (setq my-mode-map map))) -@end example - -@noindent -This has all the same advantages as putting the initialization inside -the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on -each form, if you do want to reinitialize the variable. - - But be careful not to write the code like this: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (setq my-mode-map (make-sparse-keymap)) - (define-key my-mode-map "\C-c\C-a" 'my-command) - @dots{}) -@end example - -@noindent -This code sets the variable, then alters it, but it does so in more than -one step. If the user quits just after the @code{setq}, that leaves the -variable neither correctly initialized nor void nor @code{nil}. Once -that happens, reloading the file will not initialize the variable; it -will remain incomplete. - -@node Accessing Variables -@section Accessing Variable Values - - The usual way to reference a variable is to write the symbol which -names it (@pxref{Symbol Forms}). This requires you to specify the -variable name when you write the program. Usually that is exactly what -you want to do. Occasionally you need to choose at run time which -variable to reference; then you can use @code{symbol-value}. - -@defun symbol-value symbol -This function returns the value of @var{symbol}. This is the value in -the innermost local binding of the symbol, or its global value if it -has no local bindings. - -@example -@group -(setq abracadabra 5) - @result{} 5 -@end group -@group -(setq foo 9) - @result{} 9 -@end group - -@group -;; @r{Here the symbol @code{abracadabra}} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value 'abracadabra)) - @result{} foo -@end group - -@group -;; @r{Here, the value of @code{abracadabra},} -;; @r{which is @code{foo},} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value abracadabra)) - @result{} 9 -@end group - -@group -(symbol-value 'abracadabra) - @result{} 5 -@end group -@end example - -A @code{void-variable} error is signaled if the current binding of -@var{symbol} is void. -@end defun - -@node Setting Variables -@section How to Alter a Variable Value - - The usual way to change the value of a variable is with the special -form @code{setq}. When you need to compute the choice of variable at -run time, use the function @code{set}. - -@defspec setq [symbol form]@dots{} -This special form is the most common method of changing a variable's -value. Each @var{symbol} is given a new value, which is the result of -evaluating the corresponding @var{form}. The most-local existing -binding of the symbol is changed. - -@code{setq} does not evaluate @var{symbol}; it sets the symbol that you -write. We say that this argument is @dfn{automatically quoted}. The -@samp{q} in @code{setq} stands for ``quoted.'' - -The value of the @code{setq} form is the value of the last @var{form}. - -@example -@group -(setq x (1+ 2)) - @result{} 3 -@end group -x ; @r{@code{x} now has a global value.} - @result{} 3 -@group -(let ((x 5)) - (setq x 6) ; @r{The local binding of @code{x} is set.} - x) - @result{} 6 -@end group -x ; @r{The global value is unchanged.} - @result{} 3 -@end example - -Note that the first @var{form} is evaluated, then the first -@var{symbol} is set, then the second @var{form} is evaluated, then the -second @var{symbol} is set, and so on: - -@example -@group -(setq x 10 ; @r{Notice that @code{x} is set before} - y (1+ x)) ; @r{the value of @code{y} is computed.} - @result{} 11 -@end group -@end example -@end defspec - -@defun set symbol value -This function sets @var{symbol}'s value to @var{value}, then returns -@var{value}. Since @code{set} is a function, the expression written for -@var{symbol} is evaluated to obtain the symbol to set. - -The most-local existing binding of the variable is the binding that is -set; shadowed bindings are not affected. - -@example -@group -(set one 1) -@error{} Symbol's value as variable is void: one -@end group -@group -(set 'one 1) - @result{} 1 -@end group -@group -(set 'two 'one) - @result{} one -@end group -@group -(set two 2) ; @r{@code{two} evaluates to symbol @code{one}.} - @result{} 2 -@end group -@group -one ; @r{So it is @code{one} that was set.} - @result{} 2 -(let ((one 1)) ; @r{This binding of @code{one} is set,} - (set 'one 3) ; @r{not the global value.} - one) - @result{} 3 -@end group -@group -one - @result{} 2 -@end group -@end example - -If @var{symbol} is not actually a symbol, a @code{wrong-type-argument} -error is signaled. - -@example -(set '(x y) 'z) -@error{} Wrong type argument: symbolp, (x y) -@end example - -Logically speaking, @code{set} is a more fundamental primitive than -@code{setq}. Any use of @code{setq} can be trivially rewritten to use -@code{set}; @code{setq} could even be defined as a macro, given the -availability of @code{set}. However, @code{set} itself is rarely used; -beginners hardly need to know about it. It is useful only for choosing -at run time which variable to set. For example, the command -@code{set-variable}, which reads a variable name from the user and then -sets the variable, needs to use @code{set}. - -@cindex CL note---@code{set} local -@quotation -@b{Common Lisp note:} In Common Lisp, @code{set} always changes the -symbol's ``special'' or dynamic value, ignoring any lexical bindings. -In Emacs Lisp, all variables and all bindings are dynamic, so @code{set} -always affects the most local existing binding. -@end quotation -@end defun - -@node Variable Scoping -@section Scoping Rules for Variable Bindings - - A given symbol @code{foo} can have several local variable bindings, -established at different places in the Lisp program, as well as a global -binding. The most recently established binding takes precedence over -the others. - -@cindex scope -@cindex extent -@cindex dynamic scoping -@cindex lexical scoping - Local bindings in Emacs Lisp have @dfn{indefinite scope} and -@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in -the source code the binding can be accessed. ``Indefinite scope'' means -that any part of the program can potentially access the variable -binding. @dfn{Extent} refers to @emph{when}, as the program is -executing, the binding exists. ``Dynamic extent'' means that the binding -lasts as long as the activation of the construct that established it. - - The combination of dynamic extent and indefinite scope is called -@dfn{dynamic scoping}. By contrast, most programming languages use -@dfn{lexical scoping}, in which references to a local variable must be -located textually within the function or block that binds the variable. - -@cindex CL note---special variables -@quotation -@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are -dynamically scoped, like all variables in Emacs Lisp. -@end quotation - -@menu -* 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. -@end menu - -@node Scope -@subsection Scope - - Emacs Lisp uses @dfn{indefinite scope} for local variable bindings. -This means that any function anywhere in the program text might access a -given binding of a variable. Consider the following function -definitions: - -@example -@group -(defun binder (x) ; @r{@code{x} is bound in @code{binder}.} - (foo 5)) ; @r{@code{foo} is some other function.} -@end group - -@group -(defun user () ; @r{@code{x} is used ``free'' in @code{user}.} - (list x)) -@end group -@end example - - In a lexically scoped language, the binding of @code{x} in -@code{binder} would never be accessible in @code{user}, because -@code{user} is not textually contained within the function -@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user} -may or may not refer to the binding of @code{x} established in -@code{binder}, depending on the circumstances: - -@itemize @bullet -@item -If we call @code{user} directly without calling @code{binder} at all, -then whatever binding of @code{x} is found, it cannot come from -@code{binder}. - -@item -If we define @code{foo} as follows and then call @code{binder}, then the -binding made in @code{binder} will be seen in @code{user}: - -@example -@group -(defun foo (lose) - (user)) -@end group -@end example - -@item -However, if we define @code{foo} as follows and then call @code{binder}, -then the binding made in @code{binder} @emph{will not} be seen in -@code{user}: - -@example -(defun foo (x) - (user)) -@end example - -@noindent -Here, when @code{foo} is called by @code{binder}, it binds @code{x}. -(The binding in @code{foo} is said to @dfn{shadow} the one made in -@code{binder}.) Therefore, @code{user} will access the @code{x} bound -by @code{foo} instead of the one bound by @code{binder}. -@end itemize - -Emacs Lisp uses dynamic scoping because simple implementations of -lexical scoping are slow. In addition, every Lisp system needs to offer -dynamic scoping at least as an option; if lexical scoping is the norm, -there must be a way to specify dynamic scoping instead for a particular -variable. It might not be a bad thing for Emacs to offer both, but -implementing it with dynamic scoping only was much easier. - -@node Extent -@subsection Extent - - @dfn{Extent} refers to the time during program execution that a -variable name is valid. In Emacs Lisp, a variable is valid only while -the form that bound it is executing. This is called @dfn{dynamic -extent}. ``Local'' or ``automatic'' variables in most languages, -including C and Pascal, have dynamic extent. - - One alternative to dynamic extent is @dfn{indefinite extent}. This -means that a variable binding can live on past the exit from the form -that made the binding. Common Lisp and Scheme, for example, support -this, but Emacs Lisp does not. - - To illustrate this, the function below, @code{make-add}, returns a -function that purports to add @var{n} to its own argument @var{m}. This -would work in Common Lisp, but it does not do the job in Emacs Lisp, -because after the call to @code{make-add} exits, the variable @code{n} -is no longer bound to the actual argument 2. - -@example -(defun make-add (n) - (function (lambda (m) (+ n m)))) ; @r{Return a function.} - @result{} make-add -(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}} - ; @r{with @code{(make-add 2)}.} - @result{} (lambda (m) (+ n m)) -(add2 4) ; @r{Try to add 2 to 4.} -@error{} Symbol's value as variable is void: n -@end example - -@cindex closures not available - Some Lisp dialects have ``closures,'' objects that are like functions -but record additional variable bindings. Emacs Lisp does not have -closures. - -@node Impl of Scope -@subsection Implementation of Dynamic Scoping -@cindex deep binding - - A simple sample implementation (which is not how Emacs Lisp actually -works) may help you understand dynamic binding. This technique is -called @dfn{deep binding} and was used in early Lisp systems. - - Suppose there is a stack of bindings, which are variable-value pairs. -At entry to a function or to a @code{let} form, we can push bindings -onto the stack for the arguments or local variables created there. We -can pop those bindings from the stack at exit from the binding -construct. - - We can find the value of a variable by searching the stack from top to -bottom for a binding for that variable; the value from that binding is -the value of the variable. To set the variable, we search for the -current binding, then store the new value into that binding. - - As you can see, a function's bindings remain in effect as long as it -continues execution, even during its calls to other functions. That is -why we say the extent of the binding is dynamic. And any other function -can refer to the bindings, if it uses the same variables while the -bindings are in effect. That is why we say the scope is indefinite. - -@cindex shallow binding - The actual implementation of variable scoping in GNU Emacs Lisp uses a -technique called @dfn{shallow binding}. Each variable has a standard -place in which its current value is always found---the value cell of the -symbol. - - In shallow binding, setting the variable works by storing a value in -the value cell. Creating a new binding works by pushing the old value -(belonging to a previous binding) onto a stack, and storing the new -local value in the value cell. Eliminating a binding works by popping -the old value off the stack, into the value cell. - - We use shallow binding because it has the same results as deep -binding, but runs faster, since there is never a need to search for a -binding. - -@node Using Scoping -@subsection Proper Use of Dynamic Scoping - - Binding a variable in one function and using it in another is a -powerful technique, but if used without restraint, it can make programs -hard to understand. There are two clean ways to use this technique: - -@itemize @bullet -@item -Use or bind the variable only in a few related functions, written close -together in one file. Such a variable is used for communication within -one program. - -You should write comments to inform other programmers that they can see -all uses of the variable before them, and to advise them not to add uses -elsewhere. - -@item -Give the variable a well-defined, documented meaning, and make all -appropriate functions refer to it (but not bind it or set it) wherever -that meaning is relevant. For example, the variable -@code{case-fold-search} is defined as ``non-@code{nil} means ignore case -when searching''; various search and replace functions refer to it -directly or through their subroutines, but do not bind or set it. - -Then you can bind the variable in other programs, knowing reliably what -the effect will be. -@end itemize - - In either case, you should define the variable with @code{defvar}. -This helps other people understand your program by telling them to look -for inter-function usage. It also avoids a warning from the byte -compiler. Choose the variable's name to avoid name conflicts---don't -use short names like @code{x}. - -@node Buffer-Local Variables -@section Buffer-Local Variables -@cindex variable, buffer-local -@cindex buffer-local variables - - Global and local variable bindings are found in most programming -languages in one form or another. Emacs, however, also supports additional, -unusual kinds of variable binding: @dfn{buffer-local} bindings, which -apply only in one buffer, and @dfn{frame-local} bindings, which apply only in -one frame. Having different values for a variable in different buffers -and/or frames is an important customization method. - - This section describes buffer-local bindings; for frame-local -bindings, see the following section, @ref{Frame-Local Variables}. (A few -variables have bindings that are local to each terminal; see -@ref{Multiple Displays}.) - -@menu -* 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. -@end menu - -@node Intro to Buffer-Local -@subsection Introduction to Buffer-Local Variables - - A buffer-local variable has a buffer-local binding associated with a -particular buffer. The binding is in effect when that buffer is -current; otherwise, it is not in effect. If you set the variable while -a buffer-local binding is in effect, the new value goes in that binding, -so its other bindings are unchanged. This means that the change is -visible only in the buffer where you made it. - - The variable's ordinary binding, which is not associated with any -specific buffer, is called the @dfn{default binding}. In most cases, -this is the global binding. - - A variable can have buffer-local bindings in some buffers but not in -other buffers. The default binding is shared by all the buffers that -don't have their own bindings for the variable. (This includes all -newly-created buffers.) If you set the variable in a buffer that does -not have a buffer-local binding for it, this sets the default binding -(assuming there are no frame-local bindings to complicate the matter), -so the new value is visible in all the buffers that see the default -binding. - - The most common use of buffer-local bindings is for major modes to change -variables that control the behavior of commands. For example, C mode and -Lisp mode both set the variable @code{paragraph-start} to specify that only -blank lines separate paragraphs. They do this by making the variable -buffer-local in the buffer that is being put into C mode or Lisp mode, and -then setting it to the new value for that mode. @xref{Major Modes}. - - The usual way to make a buffer-local binding is with -@code{make-local-variable}, which is what major mode commands typically -use. This affects just the current buffer; all other buffers (including -those yet to be created) will continue to share the default value unless -they are explicitly given their own buffer-local bindings. - -@cindex automatically buffer-local - A more powerful operation is to mark the variable as -@dfn{automatically buffer-local} by calling -@code{make-variable-buffer-local}. You can think of this as making the -variable local in all buffers, even those yet to be created. More -precisely, the effect is that setting the variable automatically makes -the variable local to the current buffer if it is not already so. All -buffers start out by sharing the default value of the variable as usual, -but setting the variable creates a buffer-local binding for the current -buffer. The new value is stored in the buffer-local binding, leaving -the default binding untouched. This means that the default value cannot -be changed with @code{setq} in any buffer; the only way to change it is -with @code{setq-default}. - - @strong{Warning:} When a variable has buffer-local or frame-local -bindings in one or more buffers, @code{let} rebinds the binding that's -currently in effect. For instance, if the current buffer has a -buffer-local value, @code{let} temporarily rebinds that. If no -buffer-local or frame-local bindings are in effect, @code{let} rebinds -the default value. If inside the @code{let} you then change to a -different current buffer in which a different binding is in effect, -you won't see the @code{let} binding any more. And if you exit the -@code{let} while still in the other buffer, you won't see the -unbinding occur (though it will occur properly). Here is an example -to illustrate: - -@example -@group -(setq foo 'g) -(set-buffer "a") -(make-local-variable 'foo) -@end group -(setq foo 'a) -(let ((foo 'temp)) - ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}} - (set-buffer "b") - ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}} - @var{body}@dots{}) -@group -foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},} - ; @r{but we don't see that in buffer @samp{b}} -@end group -@group -(set-buffer "a") ; @r{verify the local value was restored} -foo @result{} 'a -@end group -@end example - - Note that references to @code{foo} in @var{body} access the -buffer-local binding of buffer @samp{b}. - - When a file specifies local variable values, these become buffer-local -values when you visit the file. @xref{File Variables,,, emacs, The -GNU Emacs Manual}. - -@node Creating Buffer-Local -@subsection Creating and Deleting Buffer-Local Bindings - -@deffn Command make-local-variable variable -This function creates a buffer-local binding in the current buffer for -@var{variable} (a symbol). Other buffers are not affected. The value -returned is @var{variable}. - -@c Emacs 19 feature -The buffer-local value of @var{variable} starts out as the same value -@var{variable} previously had. If @var{variable} was void, it remains -void. - -@example -@group -;; @r{In buffer @samp{b1}:} -(setq foo 5) ; @r{Affects all buffers.} - @result{} 5 -@end group -@group -(make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.} - @result{} foo -@end group -@group -foo ; @r{That did not change} - @result{} 5 ; @r{the value.} -@end group -@group -(setq foo 6) ; @r{Change the value} - @result{} 6 ; @r{in @samp{b1}.} -@end group -@group -foo - @result{} 6 -@end group - -@group -;; @r{In buffer @samp{b2}, the value hasn't changed.} -(save-excursion - (set-buffer "b2") - foo) - @result{} 5 -@end group -@end example - -Making a variable buffer-local within a @code{let}-binding for that -variable does not work reliably, unless the buffer in which you do this -is not current either on entry to or exit from the @code{let}. This is -because @code{let} does not distinguish between different kinds of -bindings; it knows only which variable the binding was made for. - -If the variable is terminal-local, this function signals an error. Such -variables cannot have buffer-local bindings as well. @xref{Multiple -Displays}. - -@strong{Warning:} do not use @code{make-local-variable} for a hook -variable. The hook variables are automatically made buffer-local as -needed if you use the @var{local} argument to @code{add-hook} or -@code{remove-hook}. -@end deffn - -@deffn Command make-variable-buffer-local variable -This function marks @var{variable} (a symbol) automatically -buffer-local, so that any subsequent attempt to set it will make it -local to the current buffer at the time. - -A peculiar wrinkle of this feature is that binding the variable (with -@code{let} or other binding constructs) does not create a buffer-local -binding for it. Only setting the variable (with @code{set} or -@code{setq}), while the variable does not have a @code{let}-style -binding that was made in the current buffer, does so. - -If @var{variable} does not have a default value, then calling this -command will give it a default value of @code{nil}. If @var{variable} -already has a default value, that value remains unchanged. -Subsequently calling @code{makunbound} on @var{variable} will result -in a void buffer-local value and leave the default value unaffected. - -The value returned is @var{variable}. - -@strong{Warning:} Don't assume that you should use -@code{make-variable-buffer-local} for user-option variables, simply -because users @emph{might} want to customize them differently in -different buffers. Users can make any variable local, when they wish -to. It is better to leave the choice to them. - -The time to use @code{make-variable-buffer-local} is when it is crucial -that no two buffers ever share the same binding. For example, when a -variable is used for internal purposes in a Lisp program which depends -on having separate values in separate buffers, then using -@code{make-variable-buffer-local} can be the best solution. -@end deffn - -@defun local-variable-p variable &optional buffer -This returns @code{t} if @var{variable} is buffer-local in buffer -@var{buffer} (which defaults to the current buffer); otherwise, -@code{nil}. -@end defun - -@defun local-variable-if-set-p variable &optional buffer -This returns @code{t} if @var{variable} will become buffer-local in -buffer @var{buffer} (which defaults to the current buffer) if it is -set there. -@end defun - -@defun buffer-local-value variable buffer -This function returns the buffer-local binding of @var{variable} (a -symbol) in buffer @var{buffer}. If @var{variable} does not have a -buffer-local binding in buffer @var{buffer}, it returns the default -value (@pxref{Default Value}) of @var{variable} instead. -@end defun - -@defun buffer-local-variables &optional buffer -This function returns a list describing the buffer-local variables in -buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is -used.) It returns an association list (@pxref{Association Lists}) in -which each element contains one buffer-local variable and its value. -However, when a variable's buffer-local binding in @var{buffer} is void, -then the variable appears directly in the resulting list. - -@example -@group -(make-local-variable 'foobar) -(makunbound 'foobar) -(make-local-variable 'bind-me) -(setq bind-me 69) -@end group -(setq lcl (buffer-local-variables)) - ;; @r{First, built-in variables local in all buffers:} -@result{} ((mark-active . nil) - (buffer-undo-list . nil) - (mode-name . "Fundamental") - @dots{} -@group - ;; @r{Next, non-built-in buffer-local variables.} - ;; @r{This one is buffer-local and void:} - foobar - ;; @r{This one is buffer-local and nonvoid:} - (bind-me . 69)) -@end group -@end example - -Note that storing new values into the @sc{cdr}s of cons cells in this -list does @emph{not} change the buffer-local values of the variables. -@end defun - -@deffn Command kill-local-variable variable -This function deletes the buffer-local binding (if any) for -@var{variable} (a symbol) in the current buffer. As a result, the -default binding of @var{variable} becomes visible in this buffer. This -typically results in a change in the value of @var{variable}, since the -default value is usually different from the buffer-local value just -eliminated. - -If you kill the buffer-local binding of a variable that automatically -becomes buffer-local when set, this makes the default value visible in -the current buffer. However, if you set the variable again, that will -once again create a buffer-local binding for it. - -@code{kill-local-variable} returns @var{variable}. - -This function is a command because it is sometimes useful to kill one -buffer-local variable interactively, just as it is useful to create -buffer-local variables interactively. -@end deffn - -@defun kill-all-local-variables -This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent.'' As a -result, the buffer will see the default values of most variables. - -This function also resets certain other information pertaining to the -buffer: it sets the local keymap to @code{nil}, the syntax table to the -value of @code{(standard-syntax-table)}, the case table to -@code{(standard-case-table)}, and the abbrev table to the value of -@code{fundamental-mode-abbrev-table}. - -The very first thing this function does is run the normal hook -@code{change-major-mode-hook} (see below). - -Every major mode command begins by calling this function, which has the -effect of switching to Fundamental mode and erasing most of the effects -of the previous major mode. To ensure that this does its job, the -variables that major modes set should not be marked permanent. - -@code{kill-all-local-variables} returns @code{nil}. -@end defun - -@defvar change-major-mode-hook -The function @code{kill-all-local-variables} runs this normal hook -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. It is also useful for buffer-specific minor modes -that should be forgotten if the user changes the 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. @xref{Hooks}. -@end defvar - -@c Emacs 19 feature -@cindex permanent local variable -A buffer-local variable is @dfn{permanent} if the variable name (a -symbol) has a @code{permanent-local} property that is non-@code{nil}. -Permanent locals are appropriate for data pertaining to where the file -came from or how to save it, rather than with how to edit the contents. - -@node Default Value -@subsection The Default Value of a Buffer-Local Variable -@cindex default value - - The global value of a variable with buffer-local bindings is also -called the @dfn{default} value, because it is the value that is in -effect whenever neither the current buffer nor the selected frame has -its own binding for the variable. - - The functions @code{default-value} and @code{setq-default} access and -change a variable's default value regardless of whether the current -buffer has a buffer-local binding. For example, you could use -@code{setq-default} to change the default setting of -@code{paragraph-start} for most buffers; and this would work even when -you are in a C or Lisp mode buffer that has a buffer-local value for -this variable. - -@c Emacs 19 feature - The special forms @code{defvar} and @code{defconst} also set the -default value (if they set the variable at all), rather than any -buffer-local or frame-local value. - -@defun default-value symbol -This function returns @var{symbol}'s default value. This is the value -that is seen in buffers and frames that do not have their own values for -this variable. If @var{symbol} is not buffer-local, this is equivalent -to @code{symbol-value} (@pxref{Accessing Variables}). -@end defun - -@c Emacs 19 feature -@defun default-boundp symbol -The function @code{default-boundp} tells you whether @var{symbol}'s -default value is nonvoid. If @code{(default-boundp 'foo)} returns -@code{nil}, then @code{(default-value 'foo)} would get an error. - -@code{default-boundp} is to @code{default-value} as @code{boundp} is to -@code{symbol-value}. -@end defun - -@defspec setq-default [symbol form]@dots{} -This special form gives each @var{symbol} a new default value, which is -the result of evaluating the corresponding @var{form}. It does not -evaluate @var{symbol}, but does evaluate @var{form}. The value of the -@code{setq-default} form is the value of the last @var{form}. - -If a @var{symbol} is not buffer-local for the current buffer, and is not -marked automatically buffer-local, @code{setq-default} has the same -effect as @code{setq}. If @var{symbol} is buffer-local for the current -buffer, then this changes the value that other buffers will see (as long -as they don't have a buffer-local value), but not the value that the -current buffer sees. - -@example -@group -;; @r{In buffer @samp{foo}:} -(make-local-variable 'buffer-local) - @result{} buffer-local -@end group -@group -(setq buffer-local 'value-in-foo) - @result{} value-in-foo -@end group -@group -(setq-default buffer-local 'new-default) - @result{} new-default -@end group -@group -buffer-local - @result{} value-in-foo -@end group -@group -(default-value 'buffer-local) - @result{} new-default -@end group - -@group -;; @r{In (the new) buffer @samp{bar}:} -buffer-local - @result{} new-default -@end group -@group -(default-value 'buffer-local) - @result{} new-default -@end group -@group -(setq buffer-local 'another-default) - @result{} another-default -@end group -@group -(default-value 'buffer-local) - @result{} another-default -@end group - -@group -;; @r{Back in buffer @samp{foo}:} -buffer-local - @result{} value-in-foo -(default-value 'buffer-local) - @result{} another-default -@end group -@end example -@end defspec - -@defun set-default symbol value -This function is like @code{setq-default}, except that @var{symbol} is -an ordinary evaluated argument. - -@example -@group -(set-default (car '(a b c)) 23) - @result{} 23 -@end group -@group -(default-value 'a) - @result{} 23 -@end group -@end example -@end defun - -@node Frame-Local Variables -@section Frame-Local Variables -@cindex frame-local variables - - Just as variables can have buffer-local bindings, they can also have -frame-local bindings. These bindings belong to one frame, and are in -effect when that frame is selected. Frame-local bindings are actually -frame parameters: you create a frame-local binding in a specific frame -by calling @code{modify-frame-parameters} and specifying the variable -name as the parameter name. - - To enable frame-local bindings for a certain variable, call the function -@code{make-variable-frame-local}. - -@deffn Command make-variable-frame-local variable -Enable the use of frame-local bindings for @var{variable}. This does -not in itself create any frame-local bindings for the variable; however, -if some frame already has a value for @var{variable} as a frame -parameter, that value automatically becomes a frame-local binding. - -If @var{variable} does not have a default value, then calling this -command will give it a default value of @code{nil}. If @var{variable} -already has a default value, that value remains unchanged. - -If the variable is terminal-local, this function signals an error, -because such variables cannot have frame-local bindings as well. -@xref{Multiple Displays}. A few variables that are implemented -specially in Emacs can be buffer-local, but can never be frame-local. - -This command returns @var{variable}. -@end deffn - - Buffer-local bindings take precedence over frame-local bindings. Thus, -consider a variable @code{foo}: if the current buffer has a buffer-local -binding for @code{foo}, that binding is active; otherwise, if the -selected frame has a frame-local binding for @code{foo}, that binding is -active; otherwise, the default binding of @code{foo} is active. - - Here is an example. First we prepare a few bindings for @code{foo}: - -@example -(setq f1 (selected-frame)) -(make-variable-frame-local 'foo) - -;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.} -(set-buffer (get-buffer-create "b1")) -(make-local-variable 'foo) -(setq foo '(b 1)) - -;; @r{Make a frame-local binding for @code{foo} in a new frame.} -;; @r{Store that frame in @code{f2}.} -(setq f2 (make-frame)) -(modify-frame-parameters f2 '((foo . (f 2)))) -@end example - - Now we examine @code{foo} in various contexts. Whenever the -buffer @samp{b1} is current, its buffer-local binding is in effect, -regardless of the selected frame: - -@example -(select-frame f1) -(set-buffer (get-buffer-create "b1")) -foo - @result{} (b 1) - -(select-frame f2) -(set-buffer (get-buffer-create "b1")) -foo - @result{} (b 1) -@end example - -@noindent -Otherwise, the frame gets a chance to provide the binding; when frame -@code{f2} is selected, its frame-local binding is in effect: - -@example -(select-frame f2) -(set-buffer (get-buffer "*scratch*")) -foo - @result{} (f 2) -@end example - -@noindent -When neither the current buffer nor the selected frame provides -a binding, the default binding is used: - -@example -(select-frame f1) -(set-buffer (get-buffer "*scratch*")) -foo - @result{} nil -@end example - -@noindent -When the active binding of a variable is a frame-local binding, setting -the variable changes that binding. You can observe the result with -@code{frame-parameters}: - -@example -(select-frame f2) -(set-buffer (get-buffer "*scratch*")) -(setq foo 'nobody) -(assq 'foo (frame-parameters f2)) - @result{} (foo . nobody) -@end example - -@node Future Local Variables -@section Possible Future Local Variables - - We have considered the idea of bindings that are local to a category -of frames---for example, all color frames, or all frames with dark -backgrounds. We have not implemented them because it is not clear that -this feature is really useful. You can get more or less the same -results by adding a function to @code{after-make-frame-functions}, set up to -define a particular frame parameter according to the appropriate -conditions for each frame. - - It would also be possible to implement window-local bindings. We -don't know of many situations where they would be useful, and it seems -that indirect buffers (@pxref{Indirect Buffers}) with buffer-local -bindings offer a way to handle these situations more robustly. - - If sufficient application is found for either of these two kinds of -local bindings, we will provide it in a subsequent Emacs version. - -@node File Local Variables -@section File Local Variables -@cindex file local variables - - A file can specify local variable values; Emacs uses these to create -buffer-local bindings for those variables in the buffer visiting that -file. @xref{File variables, , Local Variables in Files, emacs, The -GNU Emacs Manual}, for basic information about file local variables. -This section describes the functions and variables that affect -processing of file local variables. - -@defopt enable-local-variables -This variable controls whether to process file local variables. -The possible values are: - -@table @asis -@item @code{t} (the default) -Set the safe variables, and query (once) about any unsafe variables. -@item @code{:safe} -Set only the safe variables and do not query. -@item @code{:all} -Set all the variables and do not query. -@item @code{nil} -Don't set any variables. -@item anything else -Query (once) about all the variables. -@end table -@end defopt - -@defun hack-local-variables &optional mode-only -This function parses, and binds or evaluates as appropriate, any local -variables specified by the contents of the current buffer. The variable -@code{enable-local-variables} has its effect here. However, this -function does not look for the @samp{mode:} local variable in the -@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking -@code{enable-local-variables} into account (@pxref{Auto Major Mode}). - -If the optional argument @var{mode-only} is non-@code{nil}, then all -this function does is return @code{t} if the @w{@samp{-*-}} line or -the local variables list specifies a mode and @code{nil} otherwise. -It does not set the mode nor any other file local variable. -@end defun - - If a file local variable could specify a function that would -be called later, or an expression that would be executed later, simply -visiting a file could take over your Emacs. Emacs takes several -measures to prevent this. - -@cindex safe local variable - You can specify safe values for a variable with a -@code{safe-local-variable} property. The property has to be -a function of one argument; any value is safe if the function -returns non-@code{nil} given that value. Many commonly encountered -file variables standardly have @code{safe-local-variable} properties, -including @code{fill-column}, @code{fill-prefix}, and -@code{indent-tabs-mode}. For boolean-valued variables that are safe, -use @code{booleanp} as the property value. Lambda expressions should -be quoted so that @code{describe-variable} can display the predicate. - -@defopt safe-local-variable-values -This variable provides another way to mark some variable values as -safe. It is a list of cons cells @code{(@var{var} . @var{val})}, -where @var{var} is a variable name and @var{val} is a value which is -safe for that variable. - -When Emacs asks the user whether or not to obey a set of file local -variable specifications, the user can choose to mark them as safe. -Doing so adds those variable/value pairs to -@code{safe-local-variable-values}, and saves it to the user's custom -file. -@end defopt - -@defun safe-local-variable-p sym val -This function returns non-@code{nil} if it is safe to give @var{sym} -the value @var{val}, based on the above criteria. -@end defun - -@c @cindex risky local variable Duplicates risky-local-variable - Some variables are considered @dfn{risky}. A variable whose name -ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function}, -@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form}, -@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist}, -@samp{-program}, or @samp{-predicate} is considered risky. The -variables @samp{font-lock-keywords}, @samp{font-lock-keywords} -followed by a digit, and @samp{font-lock-syntactic-keywords} are also -considered risky. Finally, any variable whose name has a -non-@code{nil} @code{risky-local-variable} property is considered -risky. - -@defun risky-local-variable-p sym -This function returns non-@code{nil} if @var{sym} is a risky variable, -based on the above criteria. -@end defun - - If a variable is risky, it will not be entered automatically into -@code{safe-local-variable-values} as described above. Therefore, -Emacs will always query before setting a risky variable, unless the -user explicitly allows the setting by customizing -@code{safe-local-variable-values} directly. - -@defvar ignored-local-variables -This variable holds a list of variables that should not be given local -values by files. Any value specified for one of these variables is -completely ignored. -@end defvar - - The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs -normally asks for confirmation before handling it. - -@defopt enable-local-eval -This variable controls processing of @samp{Eval:} in @samp{-*-} lines -or 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 - -@defopt safe-local-eval-forms -This variable holds a list of expressions that are safe to -evaluate when found in the @samp{Eval:} ``variable'' in a file -local variables list. -@end defopt - - If the expression is a function call and the function has a -@code{safe-local-eval-function} property, the property value -determines whether the expression is safe to evaluate. The property -value can be a predicate to call to test the expression, a list of -such predicates (it's safe if any predicate succeeds), or @code{t} -(always safe provided the arguments are constant). - - Text properties are also potential loopholes, since their values -could include functions to call. So Emacs discards all text -properties from string values specified for file local variables. - -@node Variable Aliases -@section Variable Aliases -@cindex variable aliases - - It is sometimes useful to make two variables synonyms, so that both -variables always have the same value, and changing either one also -changes the other. Whenever you change the name of a -variable---either because you realize its old name was not well -chosen, or because its meaning has partly changed---it can be useful -to keep the old name as an @emph{alias} of the new one for -compatibility. You can do this with @code{defvaralias}. - -@defun defvaralias new-alias base-variable &optional docstring -This function defines the symbol @var{new-alias} as a variable alias -for symbol @var{base-variable}. This means that retrieving the value -of @var{new-alias} returns the value of @var{base-variable}, and -changing the value of @var{new-alias} changes the value of -@var{base-variable}. The two aliased variable names always share the -same value and the same bindings. - -If the @var{docstring} argument is non-@code{nil}, it specifies the -documentation for @var{new-alias}; otherwise, the alias gets the same -documentation as @var{base-variable} has, if any, unless -@var{base-variable} is itself an alias, in which case @var{new-alias} gets -the documentation of the variable at the end of the chain of aliases. - -This function returns @var{base-variable}. -@end defun - - Variable aliases are convenient for replacing an old name for a -variable with a new name. @code{make-obsolete-variable} declares that -the old name is obsolete and therefore that it may be removed at some -stage in the future. - -@defun make-obsolete-variable obsolete-name current-name &optional when -This function makes the byte-compiler warn that the variable -@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, it is -the variable's new name; then the warning message says to use -@var{current-name} instead of @var{obsolete-name}. If @var{current-name} -is a string, this is the message and there is no replacement variable. - -If provided, @var{when} should be a string indicating when the -variable was first made obsolete---for example, a date or a release -number. -@end defun - - You can make two variables synonyms and declare one obsolete at the -same time using the macro @code{define-obsolete-variable-alias}. - -@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring -This macro marks the variable @var{obsolete-name} as obsolete and also -makes it an alias for the variable @var{current-name}. It is -equivalent to the following: - -@example -(defvaralias @var{obsolete-name} @var{current-name} @var{docstring}) -(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when}) -@end example -@end defmac - -@defun indirect-variable variable -This function returns the variable at the end of the chain of aliases -of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is -not defined as an alias, the function returns @var{variable}. - -This function signals a @code{cyclic-variable-indirection} error if -there is a loop in the chain of symbols. -@end defun - -@example -(defvaralias 'foo 'bar) -(indirect-variable 'foo) - @result{} bar -(indirect-variable 'bar) - @result{} bar -(setq bar 2) -bar - @result{} 2 -@group -foo - @result{} 2 -@end group -(setq foo 0) -bar - @result{} 0 -foo - @result{} 0 -@end example - -@node Variables with Restricted Values -@section Variables with Restricted Values - - Ordinary Lisp variables can be assigned any value that is a valid -Lisp object. However, certain Lisp variables are not defined in Lisp, -but in C. Most of these variables are defined in the C code using -@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on -any value. However, some variables are defined using -@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp -variables in C,, Writing Emacs Primitives}, in particular the -description of functions of the type @code{syms_of_@var{filename}}, -for a brief discussion of the C implementation. - - Variables of type @code{DEFVAR_BOOL} can only take on the values -@code{nil} or @code{t}. Attempting to assign them any other value -will set them to @code{t}: - -@example -(let ((display-hourglass 5)) - display-hourglass) - @result{} t -@end example - -@defvar byte-boolean-vars -This variable holds a list of all variables of type @code{DEFVAR_BOOL}. -@end defvar - - Variables of type @code{DEFVAR_INT} can only take on integer values. -Attempting to assign them any other value will result in an error: - -@example -(setq window-min-height 5.0) -@error{} Wrong type argument: integerp, 5.0 -@end example - -@ignore - arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e -@end ignore diff --git a/lispref/vol1.texi b/lispref/vol1.texi deleted file mode 100644 index d41b2f076df..00000000000 --- a/lispref/vol1.texi +++ /dev/null @@ -1,1507 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This file is used for printing the GNU Emacs Lisp Reference Manual -@c in two volumes. It is a modified version of elisp.texi. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual: Volume 1 -@c %**end of header - -@c See two-volume-cross-refs.txt. -@tex -\message{Formatting for two volume edition...Volume 1...} -% -% Read special toc file, set up in two-volume.make. -\gdef\tocreadfilename{elisp1-toc-ready.toc} -% -% Don't make outlines, they're not needed and \readdatafile can't pay -% attention to the special definition above. -\global\let\pdfmakeoutlines=\relax -% -% Start volume 1 chapter numbering at 1; this must be listed as chapno0. -\global\chapno=0 -@end tex - -@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 - -@dircategory Emacs -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. the manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % 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, 2001, 2002, 2003, 2004, 2005, 2006, 2007 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 are free to copy and modify -this GNU Manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle Volume 1 -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, June 2007 - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman -@author and the GNU Manual Group -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 - -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -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 - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- 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. -* 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 description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -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. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -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. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -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:: Recording the way a frame is subdivided. -* 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 to 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. -* List Variables:: Modifying lists stored in variables. -* 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:: Special characteristics of Emacs Lisp 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. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. - -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. -* Standard Errors:: List of all error symbols. - -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. -* Standard Buffer-Local Variables:: - List of variables buffer-local in all buffers. - -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. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -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. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, number, - string, file, directory, alist. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -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. - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. -* Accessing Events:: Functions to extract info from events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -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:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A 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:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* 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. -* Standard Keymaps:: List of standard keymaps. - -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. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. - -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. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Setting Syntax Properties:: Defining character syntax based on context - using the Font Lock mechanism. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property -* Region to Fontify:: Controlling which region gets refontified - after a buffer change. - -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. -* Locating Files:: How to find a file in standard places. - -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-level 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 Tree:: The layout and sizes of all windows in a frame. -* 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 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 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. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* 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. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Color Parameters:: Colors of various parts of the frame. - -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 character 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. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. - -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 of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -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. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -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. - -Low-Level Network Access - -* Proc: Network Processes. Using @code{make-network-process}. -* Options: Network Options. Further control over network connections. -* Features: Network Feature Testing. - Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -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. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize their warnings. -* Warning Options:: Variables users set to control display of warnings. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Defining Faces:: How to define a face with @code{defface}. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Font Selection:: Finding the best available font for a face. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; magnifying text; moving it - up or down on the page; adjusting the width - of spaces within text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* PostScript Images:: Special features for PostScript format. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Display Tables - -* Display Table Format:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. - -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. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording 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. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -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 the dumped Emacs is made. -* 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 detailmenu -@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 - -@c ================ Beginning of Volume 2 ================ -@c include buffers.texi -@c include windows.texi -@c include frames.texi - -@c include positions.texi -@c include markers.texi -@c include text.texi -@c include nonascii.texi - -@c include searching.texi -@c include syntax.texi -@c include abbrevs.texi -@c include processes.texi - -@c include display.texi -@c include os.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@c include anti.texi -@c include doclicense.texi -@c include gpl.texi -@c include tips.texi -@c include internals.texi -@c include errors.texi -@c include locals.texi -@c include maps.texi -@c 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: 9594760d-8801-4d1b-aeb9-f3b3166b5be2 -@end ignore diff --git a/lispref/vol2.texi b/lispref/vol2.texi deleted file mode 100644 index 515973c6281..00000000000 --- a/lispref/vol2.texi +++ /dev/null @@ -1,1506 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This file is used for printing the GNU Emacs Lisp Reference Manual -@c in two volumes. It is a modified version of elisp.texi. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual: Volume 2 -@c %**end of header - -@c See two-volume-cross-refs.txt. -@tex -\message{Formatting for two volume edition...Volume 2...} -% -% Read special toc file, set up in two-volume.make. -\gdef\tocreadfilename{elisp2-toc-ready.toc} -% -% Don't make outlines, they're not needed and \readdatafile can't pay -% attention to the special definition above. -\global\let\pdfmakeoutlines=\relax -% -% Start volume 2 chapter numbering at 27; this must be listed as chapno26 -\global\chapno=26 -@end tex - -@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 - -@dircategory Emacs -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. the manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % 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, 2001, 2002, 2003, 2004, 2005, 2006, 2007 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 are free to copy and modify -this GNU Manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle Volume 2 -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, June 2007 - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman -@author and the GNU Manual Group -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -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 - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- 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. -* 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 description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -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. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -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. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -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:: Recording the way a frame is subdivided. -* 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 to 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. -* List Variables:: Modifying lists stored in variables. -* 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:: Special characteristics of Emacs Lisp 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. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. - -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. -* Standard Errors:: List of all error symbols. - -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. -* Standard Buffer-Local Variables:: - List of variables buffer-local in all buffers. - -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. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -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. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, number, - string, file, directory, alist. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -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. - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. -* Accessing Events:: Functions to extract info from events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -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:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A 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:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* 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. -* Standard Keymaps:: List of standard keymaps. - -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. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. - -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. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Setting Syntax Properties:: Defining character syntax based on context - using the Font Lock mechanism. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property -* Region to Fontify:: Controlling which region gets refontified - after a buffer change. - -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. -* Locating Files:: How to find a file in standard places. - -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-level 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 Tree:: The layout and sizes of all windows in a frame. -* 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 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 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. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* 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. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Color Parameters:: Colors of various parts of the frame. - -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 character 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. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. - -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 of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -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. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -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. - -Low-Level Network Access - -* Proc: Network Processes. Using @code{make-network-process}. -* Options: Network Options. Further control over network connections. -* Features: Network Feature Testing. - Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -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. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize their warnings. -* Warning Options:: Variables users set to control display of warnings. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Defining Faces:: How to define a face with @code{defface}. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Font Selection:: Finding the best available font for a face. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; magnifying text; moving it - up or down on the page; adjusting the width - of spaces within text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* PostScript Images:: Special features for PostScript format. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Display Tables - -* Display Table Format:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. - -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. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording 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. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -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 the dumped Emacs is made. -* 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 detailmenu -@end menu - -@c include intro.texi -@c include objects.texi -@c include numbers.texi -@c include strings.texi - -@c include lists.texi -@c include sequences.texi -@c include hash.texi -@c include symbols.texi -@c include eval.texi - -@c include control.texi -@c include variables.texi -@c include functions.texi -@c include macros.texi - -@c include customize.texi -@c include loading.texi -@c include compile.texi -@c include advice.texi - -@c include debugging.texi -@c include streams.texi -@c include minibuf.texi -@c include commands.texi - -@c include keymaps.texi -@c include modes.texi -@c include help.texi -@c include files.texi - -@c include backups.texi - -@c ================ Beginning of Volume 2 ================ -@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: dfdbecf8-fec2-49c1-8427-3e8ac8b0b849 -@end ignore diff --git a/lispref/windows.texi b/lispref/windows.texi deleted file mode 100644 index bd8f7bc2d36..00000000000 --- a/lispref/windows.texi +++ /dev/null @@ -1,2446 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/windows -@node Windows, Frames, Buffers, Top -@chapter Windows - - This chapter describes most of the functions and variables related to -Emacs windows. See @ref{Display}, for information on how text is -displayed in windows. - -@menu -* 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-level 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 Tree:: The layout and sizes of all windows in a frame. -* 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. -@end menu - -@node Basic Windows -@section Basic Concepts of Emacs Windows -@cindex window -@cindex selected window - - A @dfn{window} in Emacs is the physical area of the screen in which a -buffer is displayed. The term is also used to refer to a Lisp object that -represents that screen area in Emacs Lisp. It should be -clear from the context which is meant. - - Emacs groups windows into frames. A frame represents an area of -screen available for Emacs to use. Each frame always contains at least -one window, but you can subdivide it vertically or horizontally into -multiple nonoverlapping Emacs windows. - - In each frame, at any time, one and only one window is designated as -@dfn{selected within the frame}. The frame's cursor appears in that -window, but the other windows have ``non-selected'' cursors, normally -less visible. At any time, one frame is the selected frame; and the -window selected within that frame is @dfn{the selected window}. The -selected window's buffer is usually the current buffer (except when -@code{set-buffer} has been used). @xref{Current Buffer}. - -@defvar cursor-in-non-selected-windows -If this variable is @code{nil}, Emacs displays only one cursor, -in the selected window. Other windows have no cursor at all. -@end defvar - - For practical purposes, a window exists only while it is displayed in -a frame. Once removed from the frame, the window is effectively deleted -and should not be used, @emph{even though there may still be references -to it} from other Lisp objects. Restoring a saved window configuration -is the only way for a window no longer on the screen to come back to -life. (@xref{Deleting Windows}.) - - Each window has the following attributes: - -@itemize @bullet -@item -containing frame - -@item -window height - -@item -window width - -@item -window edges with respect to the screen or frame - -@item -the buffer it displays - -@item -position within the buffer at the upper left of the window - -@item -amount of horizontal scrolling, in columns - -@item -point - -@item -the mark - -@item -how recently the window was selected - -@item -fringe settings - -@item -display margins - -@item -scroll-bar settings -@end itemize - -@cindex multiple windows - Users create multiple windows so they can look at several buffers at -once. Lisp libraries use multiple windows for a variety of reasons, but -most often to display related information. In Rmail, for example, you -can move through a summary buffer in one window while the other window -shows messages one at a time as they are reached. - - The meaning of ``window'' in Emacs is similar to what it means in the -context of general-purpose window systems such as X, but not identical. -The X Window System places X windows on the screen; Emacs uses one or -more X windows as frames, and subdivides them into -Emacs windows. When you use Emacs on a character-only terminal, Emacs -treats the whole terminal screen as one frame. - -@cindex terminal screen -@cindex screen of terminal -@cindex tiled windows - Most window systems support arbitrarily located overlapping windows. -In contrast, Emacs windows are @dfn{tiled}; they never overlap, and -together they fill the whole screen or frame. Because of the way in -which Emacs creates new windows and resizes them, not all conceivable -tilings of windows on an Emacs frame are actually possible. -@xref{Splitting Windows}, and @ref{Size of Window}. - - @xref{Display}, for information on how the contents of the -window's buffer are displayed in the window. - -@defun windowp object -This function returns @code{t} if @var{object} is a window. -@end defun - -@node Splitting Windows -@section Splitting Windows -@cindex splitting windows -@cindex window splitting - - The functions described here are the primitives used to split a window -into two windows. Two higher level functions sometimes split a window, -but not always: @code{pop-to-buffer} and @code{display-buffer} -(@pxref{Displaying Buffers}). - - The functions described here do not accept a buffer as an argument. -The two ``halves'' of the split window initially display the same buffer -previously visible in the window that was split. - -@deffn Command split-window &optional window size horizontal -This function splits a new window out of @var{window}'s screen area. -It returns the new window. - -If @var{horizontal} is non-@code{nil}, then @var{window} splits into -two side by side windows. The original window @var{window} keeps the -leftmost @var{size} columns, and gives the rest of the columns to the -new window. Otherwise, it splits into windows one above the other, and -@var{window} keeps the upper @var{size} lines and gives the rest of the -lines to the new window. The original window is therefore the -left-hand or upper of the two, and the new window is the right-hand or -lower. - -If @var{window} is omitted or @code{nil}, that stands for the selected -window. When you split the selected window, it remains selected. - -If @var{size} is omitted or @code{nil}, then @var{window} is divided -evenly into two parts. (If there is an odd line, it is allocated to -the new window.) When @code{split-window} is called interactively, -all its arguments are @code{nil}. - -If splitting would result in making a window that is smaller than -@code{window-min-height} or @code{window-min-width}, the function -signals an error and does not split the window at all. - -The following example starts with one window on a screen that is 50 -lines high by 80 columns wide; then it splits the window. - -@smallexample -@group -(setq w (selected-window)) - @result{} #<window 8 on windows.texi> -(window-edges) ; @r{Edges in order:} - @result{} (0 0 80 50) ; @r{left--top--right--bottom} -@end group - -@group -;; @r{Returns window created} -(setq w2 (split-window w 15)) - @result{} #<window 28 on windows.texi> -@end group -@group -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window;} - ; @r{top is line 15} -@end group -@group -(window-edges w) - @result{} (0 0 80 15) ; @r{Top window} -@end group -@end smallexample - -The screen looks like this: - -@smallexample -@group - __________ - | | line 0 - | w | - |__________| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 -@end group -@end smallexample - -Next, split the top window horizontally: - -@smallexample -@group -(setq w3 (split-window w 35 t)) - @result{} #<window 32 on windows.texi> -@end group -@group -(window-edges w3) - @result{} (35 0 80 15) ; @r{Left edge at column 35} -@end group -@group -(window-edges w) - @result{} (0 0 35 15) ; @r{Right edge at column 35} -@end group -@group -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window unchanged} -@end group -@end smallexample - -@need 3000 -Now the screen looks like this: - -@smallexample -@group - column 35 - __________ - | | | line 0 - | w | w3 | - |___|______| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 -@end group -@end smallexample - -Normally, Emacs indicates the border between two side-by-side windows -with a scroll bar (@pxref{Layout Parameters,Scroll Bars}) or @samp{|} -characters. The display table can specify alternative border -characters; see @ref{Display Tables}. -@end deffn - -@deffn Command split-window-vertically &optional size -This function splits the selected window into two windows, one above the -other, leaving the upper of the two windows selected, with @var{size} -lines. (If @var{size} is negative, then the lower of the two windows -gets @minus{} @var{size} lines and the upper window gets the rest, but -the upper window is still the one selected.) However, if -@code{split-window-keep-point} (see below) is @code{nil}, then either -window can be selected. - -In other respects, this function is similar to @code{split-window}. -In particular, the upper window is the original one and the return -value is the new, lower window. -@end deffn - -@defopt split-window-keep-point -If this variable is non-@code{nil} (the default), then -@code{split-window-vertically} behaves as described above. - -If it is @code{nil}, then @code{split-window-vertically} adjusts point -in each of the two windows to avoid scrolling. (This is useful on -slow terminals.) It selects whichever window contains the screen line -that point was previously on. - -This variable only affects the behavior of @code{split-window-vertically}. -It has no effect on the other functions described here. -@end defopt - -@deffn Command split-window-horizontally &optional size -This function splits the selected window into two windows -side-by-side, leaving the selected window on the left with @var{size} -columns. If @var{size} is negative, the rightmost window gets -@minus{} @var{size} columns, but the leftmost window still remains -selected. - -This function is basically an interface to @code{split-window}. -You could define a simplified version of the function like this: - -@smallexample -@group -(defun split-window-horizontally (&optional arg) - "Split selected window into two windows, side by side..." - (interactive "P") -@end group -@group - (let ((size (and arg (prefix-numeric-value arg)))) - (and size (< size 0) - (setq size (+ (window-width) size))) - (split-window nil size t))) -@end group -@end smallexample -@end deffn - -@defun one-window-p &optional no-mini all-frames -This function returns non-@code{nil} if there is only one window. The -argument @var{no-mini}, if non-@code{nil}, means don't count the -minibuffer even if it is active; otherwise, the minibuffer window is -counted when it is active. - -The argument @var{all-frames} specifies which frames to consider. Here -are the possible values and their meanings: - -@table @asis -@item @code{nil} -Count the windows in the selected frame, plus the minibuffer used -by that frame even if it lies in some other frame. - -@item @code{t} -Count all windows in all existing frames. - -@item @code{visible} -Count all windows in all visible frames. - -@item 0 -Count all windows in all visible or iconified frames. - -@item anything else -Count precisely the windows in the selected frame, and no others. -@end table -@end defun - -@node Deleting Windows -@section Deleting Windows -@cindex deleting windows - -A window remains visible on its frame unless you @dfn{delete} it by -calling certain functions that delete windows. A deleted window cannot -appear on the screen, but continues to exist as a Lisp object until -there are no references to it. There is no way to cancel the deletion -of a window aside from restoring a saved window configuration -(@pxref{Window Configurations}). Restoring a window configuration also -deletes any windows that aren't part of that configuration. - - When you delete a window, the space it took up is given to one -adjacent sibling. - -@c Emacs 19 feature -@defun window-live-p window -This function returns @code{nil} if @var{window} is deleted, and -@code{t} otherwise. - -@strong{Warning:} Erroneous information or fatal errors may result from -using a deleted window as if it were live. -@end defun - -@deffn Command delete-window &optional window -This function removes @var{window} from display, and returns @code{nil}. -If @var{window} is omitted, then the selected window is deleted. An -error is signaled if there is only one window when @code{delete-window} -is called. -@end deffn - -@deffn Command delete-other-windows &optional window -This function makes @var{window} the only window on its frame, by -deleting the other windows in that frame. If @var{window} is omitted or -@code{nil}, then the selected window is used by default. - -The return value is @code{nil}. -@end deffn - -@deffn Command delete-windows-on buffer-or-name &optional frame -This function deletes all windows showing @var{buffer-or-name}. If -there are no windows showing @var{buffer-or-name}, it does nothing. -@var{buffer-or-name} must be a buffer or the name of an existing -buffer. - -@code{delete-windows-on} operates frame by frame. If a frame has -several windows showing different buffers, then those showing -@var{buffer-or-name} are removed, and the others expand to fill the -space. If all windows in some frame are showing @var{buffer-or-name} -(including the case where there is only one window), then the frame -winds up with a single window showing another buffer chosen with -@code{other-buffer}. @xref{The Buffer List}. - -The argument @var{frame} controls which frames to operate on. This -function does not use it in quite the same way as the other functions -which scan all windows; specifically, the values @code{t} and @code{nil} -have the opposite of their meanings in other functions. Here are the -full details: - -@itemize @bullet -@item -If it is @code{nil}, operate on all frames. -@item -If it is @code{t}, operate on the selected frame. -@item -If it is @code{visible}, operate on all visible frames. -@item -If it is 0, operate on all visible or iconified frames. -@item -If it is a frame, operate on that frame. -@end itemize - -This function always returns @code{nil}. -@end deffn - -@node Selecting Windows -@section Selecting Windows -@cindex selecting a window - - When a window is selected, the buffer in the window becomes the current -buffer, and the cursor will appear in it. - -@defun selected-window -This function returns the selected window. This is the window in -which the cursor appears and to which many commands apply. -@end defun - -@defun select-window window &optional norecord -This function makes @var{window} the selected window. The cursor then -appears in @var{window} (on redisplay). Unless @var{window} was -already selected, @code{select-window} makes @var{window}'s buffer the -current buffer. - -Normally @var{window}'s selected buffer is moved to the front of the -buffer list, but if @var{norecord} is non-@code{nil}, the buffer list -order is unchanged. - -The return value is @var{window}. - -@example -@group -(setq w (next-window)) -(select-window w) - @result{} #<window 65 on windows.texi> -@end group -@end example -@end defun - -@defmac save-selected-window forms@dots{} -This macro records the selected frame, as well as the selected window -of each frame, executes @var{forms} in sequence, then restores the -earlier selected frame and windows. It also saves and restores the -current buffer. It returns the value of the last form in @var{forms}. - -This macro does not save or restore anything about the sizes, -arrangement or contents of windows; therefore, if the @var{forms} -change them, the change persists. If the previously selected window -of some frame is no longer live at the time of exit from @var{forms}, -that frame's selected window is left alone. If the previously -selected window is no longer live, then whatever window is selected at -the end of @var{forms} remains selected. -@end defmac - -@defmac with-selected-window window forms@dots{} -This macro selects @var{window} (without changing the buffer list), -executes @var{forms} in sequence, then restores the previously -selected window and current buffer. It is just like -@code{save-selected-window}, except that it explicitly selects -@var{window}, also without altering the buffer list sequence. -@end defmac - -@cindex finding windows - The following functions choose one of the windows on the screen, -offering various criteria for the choice. - -@defun get-lru-window &optional frame dedicated -This function returns the window least recently ``used'' (that is, -selected). If any full-width windows are present, it only considers -these. The selected window is always the most recently used window. - -The selected window can be the least recently used window if it is the -only window. A newly created window becomes the least recently used -window until it is selected. A minibuffer window is never a -candidate. Dedicated windows are never candidates unless the -@var{dedicated} argument is non-@code{nil}, so if all -existing windows are dedicated, the value is @code{nil}. - -The argument @var{frame} controls which windows are considered. - -@itemize @bullet -@item -If it is @code{nil}, consider windows on the selected frame. -@item -If it is @code{t}, consider windows on all frames. -@item -If it is @code{visible}, consider windows on all visible frames. -@item -If it is 0, consider windows on all visible or iconified frames. -@item -If it is a frame, consider windows on that frame. -@end itemize -@end defun - -@defun get-largest-window &optional frame dedicated -This function returns the window with the largest area (height times -width). If there are no side-by-side windows, then this is the window -with the most lines. A minibuffer window is never a candidate. -Dedicated windows are never candidates unless the -@var{dedicated} argument is non-@code{nil}, so if all existing windows -are dedicated, the value is @code{nil}. - -If there are two candidate windows of the same size, this function -prefers the one that comes first in the cyclic ordering of windows -(see following section), starting from the selected window. - -The argument @var{frame} controls which set of windows to -consider. See @code{get-lru-window}, above. -@end defun - -@cindex window that satisfies a predicate -@cindex conditional selection of windows -@defun get-window-with-predicate predicate &optional minibuf all-frames default -This function returns a window satisfying @var{predicate}. It cycles -through all visible windows using @code{walk-windows} (@pxref{Cyclic -Window Ordering}), calling @var{predicate} on each one of them -with that window as its argument. The function returns the first -window for which @var{predicate} returns a non-@code{nil} value; if -that never happens, it returns @var{default}. - -The optional arguments @var{minibuf} and @var{all-frames} specify the -set of windows to include in the scan. See the description of -@code{next-window} in @ref{Cyclic Window Ordering}, for details. -@end defun - -@node Cyclic Window Ordering -@comment node-name, next, previous, up -@section Cyclic Ordering of Windows -@cindex cyclic ordering of windows -@cindex ordering of windows, cyclic -@cindex window ordering, cyclic - - When you use the command @kbd{C-x o} (@code{other-window}) to select -the next window, it moves through all the windows on the screen in a -specific cyclic order. For any given configuration of windows, this -order never varies. It is called the @dfn{cyclic ordering of windows}. - - This ordering generally goes from top to bottom, and from left to -right. But it may go down first or go right first, depending on the -order in which the windows were split. - - If the first split was vertical (into windows one above each other), -and then the subwindows were split horizontally, then the ordering is -left to right in the top of the frame, and then left to right in the -next lower part of the frame, and so on. If the first split was -horizontal, the ordering is top to bottom in the left part, and so on. -In general, within each set of siblings at any level in the window tree, -the order is left to right, or top to bottom. - -@defun next-window &optional window minibuf all-frames -@cindex minibuffer window, and @code{next-window} -This function returns the window following @var{window} in the cyclic -ordering of windows. This is the window that @kbd{C-x o} would select -if typed when @var{window} is selected. If @var{window} is the only -window visible, then this function returns @var{window}. If omitted, -@var{window} defaults to the selected window. - -The value of the argument @var{minibuf} determines whether the -minibuffer is included in the window order. Normally, when -@var{minibuf} is @code{nil}, the minibuffer is included if it is -currently active; this is the behavior of @kbd{C-x o}. (The minibuffer -window is active while the minibuffer is in use. @xref{Minibuffers}.) - -If @var{minibuf} is @code{t}, then the cyclic ordering includes the -minibuffer window even if it is not active. - -If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer -window is not included even if it is active. - -The argument @var{all-frames} specifies which frames to consider. Here -are the possible values and their meanings: - -@table @asis -@item @code{nil} -Consider all the windows in @var{window}'s frame, plus the minibuffer -used by that frame even if it lies in some other frame. If the -minibuffer counts (as determined by @var{minibuf}), then all windows on -all frames that share that minibuffer count too. - -@item @code{t} -Consider all windows in all existing frames. - -@item @code{visible} -Consider all windows in all visible frames. (To get useful results, you -must ensure @var{window} is in a visible frame.) - -@item 0 -Consider all windows in all visible or iconified frames. - -@item a frame -Consider all windows on that frame. - -@item anything else -Consider precisely the windows in @var{window}'s frame, and no others. -@end table - -This example assumes there are two windows, both displaying the -buffer @samp{windows.texi}: - -@example -@group -(selected-window) - @result{} #<window 56 on windows.texi> -@end group -@group -(next-window (selected-window)) - @result{} #<window 52 on windows.texi> -@end group -@group -(next-window (next-window (selected-window))) - @result{} #<window 56 on windows.texi> -@end group -@end example -@end defun - -@defun previous-window &optional window minibuf all-frames -This function returns the window preceding @var{window} in the cyclic -ordering of windows. The other arguments specify which windows to -include in the cycle, as in @code{next-window}. -@end defun - -@deffn Command other-window count &optional all-frames -This function selects the @var{count}th following window in the cyclic -order. If count is negative, then it moves back @minus{}@var{count} -windows in the cycle, rather than forward. It returns @code{nil}. - -The argument @var{all-frames} has the same meaning as in -@code{next-window}, but the @var{minibuf} argument of @code{next-window} -is always effectively @code{nil}. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@c Emacs 19 feature -@defun walk-windows proc &optional minibuf all-frames -This function cycles through all windows. It calls the function -@code{proc} once for each window, with the window as its sole -argument. - -The optional arguments @var{minibuf} and @var{all-frames} specify the -set of windows to include in the scan. See @code{next-window}, above, -for details. -@end defun - -@defun window-list &optional frame minibuf window -This function returns a list of the windows on @var{frame}, starting -with @var{window}. If @var{frame} is @code{nil} or omitted, -@code{window-list} uses the selected frame instead; if @var{window} is -@code{nil} or omitted, it uses the selected window. - -The value of @var{minibuf} determines if the minibuffer window is -included in the result list. If @var{minibuf} is @code{t}, the result -always includes the minibuffer window. If @var{minibuf} is @code{nil} -or omitted, that includes the minibuffer window if it is active. If -@var{minibuf} is neither @code{nil} nor @code{t}, the result never -includes the minibuffer window. -@end defun - -@node Buffers and Windows -@section Buffers and Windows -@cindex examining windows -@cindex windows, controlling precisely -@cindex buffers, controlled in windows - - This section describes low-level functions to examine windows or to -display buffers in windows in a precisely controlled fashion. -@iftex -See the following section for -@end iftex -@ifnottex -@xref{Displaying Buffers}, for -@end ifnottex -related functions that find a window to use and specify a buffer for it. -The functions described there are easier to use than these, but they -employ heuristics in choosing or creating a window; use these functions -when you need complete control. - -@defun set-window-buffer window buffer-or-name &optional keep-margins -This function makes @var{window} display @var{buffer-or-name} as its -contents. It returns @code{nil}. @var{buffer-or-name} must be a -buffer, or the name of an existing buffer. This is the fundamental -primitive for changing which buffer is displayed in a window, and all -ways of doing that call this function. - -@example -@group -(set-window-buffer (selected-window) "foo") - @result{} nil -@end group -@end example - -Normally, displaying @var{buffer} in @var{window} resets the window's -display margins, fringe widths, scroll bar settings, and position -based on the local variables of @var{buffer}. However, if -@var{keep-margins} is non-@code{nil}, the display margins and fringe -widths of @var{window} remain unchanged. @xref{Fringes}. -@end defun - -@defvar buffer-display-count -This buffer-local variable records the number of times a buffer is -displayed in a window. It is incremented each time -@code{set-window-buffer} is called for the buffer. -@end defvar - -@defun window-buffer &optional window -This function returns the buffer that @var{window} is displaying. If -@var{window} is omitted, this function returns the buffer for the -selected window. - -@example -@group -(window-buffer) - @result{} #<buffer windows.texi> -@end group -@end example -@end defun - -@defun get-buffer-window buffer-or-name &optional all-frames -This function returns a window currently displaying -@var{buffer-or-name}, or @code{nil} if there is none. If there are -several such windows, then the function returns the first one in the -cyclic ordering of windows, starting from the selected window. -@xref{Cyclic Window Ordering}. - -The argument @var{all-frames} controls which windows to consider. - -@itemize @bullet -@item -If it is @code{nil}, consider windows on the selected frame. -@item -If it is @code{t}, consider windows on all frames. -@item -If it is @code{visible}, consider windows on all visible frames. -@item -If it is 0, consider windows on all visible or iconified frames. -@item -If it is a frame, consider windows on that frame. -@end itemize -@end defun - -@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames -This function returns a list of all the windows currently displaying -@var{buffer-or-name}. - -The two optional arguments work like the optional arguments of -@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not} -like the single optional argument of @code{get-buffer-window}. Perhaps -we should change @code{get-buffer-window} in the future to make it -compatible with the other functions. -@end defun - -@defvar buffer-display-time -This variable records the time at which a buffer was last made visible -in a window. It is always local in each buffer; each time -@code{set-window-buffer} is called, it sets this variable to -@code{(current-time)} in the specified buffer (@pxref{Time of Day}). -When a buffer is first created, @code{buffer-display-time} starts out -with the value @code{nil}. -@end defvar - -@node Displaying Buffers -@section Displaying Buffers in Windows -@cindex switching to a buffer -@cindex displaying a buffer - - In this section we describe convenient functions that choose a window -automatically and use it to display a specified buffer. These functions -can also split an existing window in certain circumstances. We also -describe variables that parameterize the heuristics used for choosing a -window. -@iftex -See the preceding section for -@end iftex -@ifnottex -@xref{Buffers and Windows}, for -@end ifnottex -low-level functions that give you more precise control. All of these -functions work by calling @code{set-window-buffer}. - - Do not use the functions in this section in order to make a buffer -current so that a Lisp program can access or modify it; they are too -drastic for that purpose, since they change the display of buffers in -windows, which would be gratuitous and surprise the user. Instead, use -@code{set-buffer} and @code{save-current-buffer} (@pxref{Current -Buffer}), which designate buffers as current for programmed access -without affecting the display of buffers in windows. - -@deffn Command switch-to-buffer buffer-or-name &optional norecord -This function makes @var{buffer-or-name} the current buffer, and also -displays the buffer in the selected window. This means that a human can -see the buffer and subsequent keyboard commands will apply to it. -Contrast this with @code{set-buffer}, which makes @var{buffer-or-name} -the current buffer but does not display it in the selected window. -@xref{Current Buffer}. - -If @var{buffer-or-name} does not identify an existing buffer, then a new -buffer by that name is created. The major mode for the new buffer is -set according to the variable @code{default-major-mode}. @xref{Auto -Major Mode}. If @var{buffer-or-name} is @code{nil}, -@code{switch-to-buffer} chooses a buffer using @code{other-buffer}. - -Normally the specified buffer is put at the front of the buffer list -(both the selected frame's buffer list and the frame-independent buffer -list). This affects the operation of @code{other-buffer}. However, if -@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer -List}. - -The @code{switch-to-buffer} function is often used interactively, as -the binding of @kbd{C-x b}. It is also used frequently in programs. It -returns the buffer that it switched to. -@end deffn - -The next two functions are similar to @code{switch-to-buffer}, except -for the described features. - -@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord -This function makes @var{buffer-or-name} the current buffer and -displays it in a window not currently selected. It then selects that -window. The handling of the buffer is the same as in -@code{switch-to-buffer}. - -The currently selected window is absolutely never used to do the job. -If it is the only window, then it is split to make a distinct window for -this purpose. If the selected window is already displaying the buffer, -then it continues to do so, but another window is nonetheless found to -display it in as well. - -This function updates the buffer list just like @code{switch-to-buffer} -unless @var{norecord} is non-@code{nil}. -@end deffn - -@defun pop-to-buffer buffer-or-name &optional other-window norecord -This function makes @var{buffer-or-name} the current buffer and -switches to it in some window, preferably not the window previously -selected. The ``popped-to'' window becomes the selected window within -its frame. The return value is the buffer that was switched to. -If @var{buffer-or-name} is @code{nil}, that means to choose some -other buffer, but you don't specify which. - -If the variable @code{pop-up-frames} is non-@code{nil}, -@code{pop-to-buffer} looks for a window in any visible frame already -displaying the buffer; if there is one, it returns that window and makes -it be selected within its frame. If there is none, it creates a new -frame and displays the buffer in it. - -If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer} -operates entirely within the selected frame. (If the selected frame has -just a minibuffer, @code{pop-to-buffer} operates within the most -recently selected frame that was not just a minibuffer.) - -If the variable @code{pop-up-windows} is non-@code{nil}, windows may -be split to create a new window that is different from the original -window. For details, see @ref{Choosing Window}. - -If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or -creates another window even if @var{buffer-or-name} is already visible -in the selected window. Thus @var{buffer-or-name} could end up -displayed in two windows. On the other hand, if @var{buffer-or-name} is -already displayed in the selected window and @var{other-window} is -@code{nil}, then the selected window is considered sufficient display -for @var{buffer-or-name}, so that nothing needs to be done. - -All the variables that affect @code{display-buffer} affect -@code{pop-to-buffer} as well. @xref{Choosing Window}. - -If @var{buffer-or-name} is a string that does not name an existing -buffer, a buffer by that name is created. The major mode for the new -buffer is set according to the variable @code{default-major-mode}. -@xref{Auto Major Mode}. - -This function updates the buffer list just like @code{switch-to-buffer} -unless @var{norecord} is non-@code{nil}. -@end defun - -@deffn Command replace-buffer-in-windows buffer-or-name -This function replaces @var{buffer-or-name} with some other buffer in all -windows displaying it. It chooses the other buffer with -@code{other-buffer}. In the usual applications of this function, you -don't care which other buffer is used; you just want to make sure that -@var{buffer-or-name} is no longer displayed. - -This function returns @code{nil}. -@end deffn - -@node Choosing Window -@section Choosing a Window for Display - - This section describes the basic facility that chooses a window to -display a buffer in---@code{display-buffer}. All the higher-level -functions and commands use this subroutine. Here we describe how to use -@code{display-buffer} and how to customize it. - -@deffn Command display-buffer buffer-or-name &optional not-this-window frame -This command makes @var{buffer-or-name} appear in some window, like -@code{pop-to-buffer}, but it does not select that window and does not -make the buffer current. The identity of the selected window is -unaltered by this function. @var{buffer-or-name} must be a buffer, or -the name of an existing buffer. - -If @var{not-this-window} is non-@code{nil}, it means to display the -specified buffer in a window other than the selected one, even if it is -already on display in the selected window. This can cause the buffer to -appear in two windows at once. Otherwise, if @var{buffer-or-name} is -already being displayed in any window, that is good enough, so this -function does nothing. - -@code{display-buffer} returns the window chosen to display -@var{buffer-or-name}. - -If the argument @var{frame} is non-@code{nil}, it specifies which frames -to check when deciding whether the buffer is already displayed. If the -buffer is already displayed in some window on one of these frames, -@code{display-buffer} simply returns that window. Here are the possible -values of @var{frame}: - -@itemize @bullet -@item -If it is @code{nil}, consider windows on the selected frame. -(Actually, the last non-minibuffer frame.) -@item -If it is @code{t}, consider windows on all frames. -@item -If it is @code{visible}, consider windows on all visible frames. -@item -If it is 0, consider windows on all visible or iconified frames. -@item -If it is a frame, consider windows on that frame. -@end itemize - -Precisely how @code{display-buffer} finds or creates a window depends on -the variables described below. -@end deffn - -@defopt display-buffer-reuse-frames -If this variable is non-@code{nil}, @code{display-buffer} searches -existing frames for a window displaying the buffer. If the buffer is -already displayed in a window in some frame, @code{display-buffer} makes -the frame visible and raises it, to use that window. If the buffer is -not already displayed, or if @code{display-buffer-reuse-frames} is -@code{nil}, @code{display-buffer}'s behavior is determined by other -variables, described below. -@end defopt - -@defopt pop-up-windows -This variable controls whether @code{display-buffer} makes new windows. -If it is non-@code{nil} and there is only one window, then that window -is split. If it is @code{nil}, then @code{display-buffer} does not -split the single window, but uses it whole. -@end defopt - -@defopt split-height-threshold -This variable determines when @code{display-buffer} may split a window, -if there are multiple windows. @code{display-buffer} always splits the -largest window if it has at least this many lines. If the largest -window is not this tall, it is split only if it is the sole window and -@code{pop-up-windows} is non-@code{nil}. -@end defopt - -@defopt even-window-heights -This variable determines if @code{display-buffer} should even out window -heights if the buffer gets displayed in an existing window, above or -beneath another existing window. If @code{even-window-heights} is -@code{t}, the default, window heights will be evened out. If -@code{even-window-heights} is @code{nil}, the original window heights -will be left alone. -@end defopt - -@c Emacs 19 feature -@defopt pop-up-frames -This variable controls whether @code{display-buffer} makes new frames. -If it is non-@code{nil}, @code{display-buffer} looks for an existing -window already displaying the desired buffer, on any visible frame. If -it finds one, it returns that window. Otherwise it makes a new frame. -The variables @code{pop-up-windows} and @code{split-height-threshold} do -not matter if @code{pop-up-frames} is non-@code{nil}. - -If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either -splits a window or reuses one. - -@xref{Frames}, for more information. -@end defopt - -@c Emacs 19 feature -@defopt pop-up-frame-function -This variable specifies how to make a new frame if @code{pop-up-frames} -is non-@code{nil}. - -Its value should be a function of no arguments. When -@code{display-buffer} makes a new frame, it does so by calling that -function, which should return a frame. The default value of the -variable is a function that creates a frame using parameters from -@code{pop-up-frame-alist}. -@end defopt - -@defopt pop-up-frame-alist -This variable holds an alist specifying frame parameters used when -@code{display-buffer} makes a new frame. @xref{Frame Parameters}, for -more information about frame parameters. -@end defopt - -@defopt special-display-buffer-names -A list of buffer names for buffers that should be displayed specially. -If the buffer's name is in this list, @code{display-buffer} handles the -buffer specially. - -By default, special display means to give the buffer a dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of the -list is the buffer name, and the rest of the list says how to create -the frame. There are two possibilities for the rest of the list (its -@sc{cdr}). It can be an alist, specifying frame parameters, or it can -contain a function and arguments to give to it. (The function's first -argument is always the buffer to be displayed; the arguments from the -list come after that.) - -For example: - -@example -(("myfile" (minibuffer) (menu-bar-lines . 0))) -@end example - -@noindent -specifies to display a buffer named @samp{myfile} in a dedicated frame -with specified @code{minibuffer} and @code{menu-bar-lines} parameters. - -The list of frame parameters can also use the phony frame parameters -@code{same-frame} and @code{same-window}. If the specified frame -parameters include @code{(same-window . @var{value})} and @var{value} -is non-@code{nil}, that means to display the buffer in the current -selected window. Otherwise, if they include @code{(same-frame . -@var{value})} and @var{value} is non-@code{nil}, that means to display -the buffer in a new window in the currently selected frame. -@end defopt - -@defopt special-display-regexps -A list of regular expressions that specify buffers that should be -displayed specially. If the buffer's name matches any of the regular -expressions in this list, @code{display-buffer} handles the buffer -specially. - -By default, special display means to give the buffer a dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of the -list is the regular expression, and the rest of the list says how to -create the frame. See above, under @code{special-display-buffer-names}. -@end defopt - -@defun special-display-p buffer-name -This function returns non-@code{nil} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -create a special frame. The value is @code{t} if it would -use the default frame parameters, or else the specified list -of frame parameters. -@end defun - -@defvar special-display-function -This variable holds the function to call to display a buffer specially. -It receives the buffer as an argument, and should return the window in -which it is displayed. - -The default value of this variable is -@code{special-display-popup-frame}. -@end defvar - -@defun special-display-popup-frame buffer &optional args -This function makes @var{buffer} visible in a frame of its own. If -@var{buffer} is already displayed in a window in some frame, it makes -the frame visible and raises it, to use that window. Otherwise, it -creates a frame that will be dedicated to @var{buffer}. This -function returns the window it used. - -If @var{args} is an alist, it specifies frame parameters for the new -frame. - -If @var{args} is a list whose @sc{car} is a symbol, then @code{(car -@var{args})} is called as a function to actually create and set up the -frame; it is called with @var{buffer} as first argument, and @code{(cdr -@var{args})} as additional arguments. - -This function always uses an existing window displaying @var{buffer}, -whether or not it is in a frame of its own; but if you set up the above -variables in your init file, before @var{buffer} was created, then -presumably the window was previously made by this function. -@end defun - -@defopt special-display-frame-alist -@anchor{Definition of special-display-frame-alist} -This variable holds frame parameters for -@code{special-display-popup-frame} to use when it creates a frame. -@end defopt - -@defopt same-window-buffer-names -A list of buffer names for buffers that should be displayed in the -selected window. If the buffer's name is in this list, -@code{display-buffer} handles the buffer by switching to it in the -selected window. -@end defopt - -@defopt same-window-regexps -A list of regular expressions that specify buffers that should be -displayed in the selected window. If the buffer's name matches any of -the regular expressions in this list, @code{display-buffer} handles the -buffer by switching to it in the selected window. -@end defopt - -@defun same-window-p buffer-name -This function returns @code{t} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -put it in the selected window. -@end defun - -@c Emacs 19 feature -@defvar display-buffer-function -This variable is the most flexible way to customize the behavior of -@code{display-buffer}. If it is non-@code{nil}, it should be a function -that @code{display-buffer} calls to do the work. The function should -accept two arguments, the first two arguments that @code{display-buffer} -received. It should choose or create a window, display the specified -buffer in it, and then return the window. - -This hook takes precedence over all the other options and hooks -described above. -@end defvar - -@c Emacs 19 feature -@cindex dedicated window -A window can be marked as ``dedicated'' to its buffer. Then -@code{display-buffer} will not try to use that window to display any -other buffer. - -@defun window-dedicated-p window -This function returns non-@code{nil} if @var{window} is marked as -dedicated; otherwise @code{nil}. -@end defun - -@defun set-window-dedicated-p window flag -This function marks @var{window} as dedicated if @var{flag} is -non-@code{nil}, and nondedicated otherwise. -@end defun - -@node Window Point -@section Windows and Point -@cindex window position -@cindex window point -@cindex position in window -@cindex point in window - - Each window has its own value of point, independent of the value of -point in other windows displaying the same buffer. This makes it useful -to have multiple windows showing one buffer. - -@itemize @bullet -@item -The window point is established when a window is first created; it is -initialized from the buffer's point, or from the window point of another -window opened on the buffer if such a window exists. - -@item -Selecting a window sets the value of point in its buffer from the -window's value of point. Conversely, deselecting a window sets the -window's value of point from that of the buffer. Thus, when you switch -between windows that display a given buffer, the point value for the -selected window is in effect in the buffer, while the point values for -the other windows are stored in those windows. - -@item -As long as the selected window displays the current buffer, the window's -point and the buffer's point always move together; they remain equal. -@end itemize - -@noindent -@xref{Positions}, for more details on buffer positions. - -@cindex cursor - As far as the user is concerned, point is where the cursor is, and -when the user switches to another buffer, the cursor jumps to the -position of point in that buffer. - -@defun window-point &optional window -This function returns the current position of point in @var{window}. -For a nonselected window, this is the value point would have (in that -window's buffer) if that window were selected. If @var{window} is -@code{nil}, the selected window is used. - -When @var{window} is the selected window and its buffer is also the -current buffer, the value returned is the same as point in that buffer. - -Strictly speaking, it would be more correct to return the -``top-level'' value of point, outside of any @code{save-excursion} -forms. But that value is hard to find. -@end defun - -@defun set-window-point window position -This function positions point in @var{window} at position -@var{position} in @var{window}'s buffer. It returns @var{position}. - -If @var{window} is selected, and its buffer is current, -this simply does @code{goto-char}. -@end defun - -@node Window Start -@section The Window Start Position -@cindex window start position - - Each window contains a marker used to keep track of a buffer position -that specifies where in the buffer display should start. This position -is called the @dfn{display-start} position of the window (or just the -@dfn{start}). The character after this position is the one that appears -at the upper left corner of the window. It is usually, but not -inevitably, at the beginning of a text line. - -@defun window-start &optional window -@cindex window top line -This function returns the display-start position of window -@var{window}. If @var{window} is @code{nil}, the selected window is -used. For example, - -@example -@group -(window-start) - @result{} 7058 -@end group -@end example - -When you create a window, or display a different buffer in it, the -display-start position is set to a display-start position recently used -for the same buffer, or 1 if the buffer doesn't have any. - -Redisplay updates the window-start position (if you have not specified -it explicitly since the previous redisplay)---for example, to make sure -point appears on the screen. Nothing except redisplay automatically -changes the window-start position; if you move point, do not expect the -window-start position to change in response until after the next -redisplay. - -For a realistic example of using @code{window-start}, see the -description of @code{count-lines}. @xref{Definition of count-lines}. -@end defun - -@defun window-end &optional window update -This function returns the position of the end of the display in window -@var{window}. If @var{window} is @code{nil}, the selected window is -used. - -Simply changing the buffer text or moving point does not update the -value that @code{window-end} returns. The value is updated only when -Emacs redisplays and redisplay completes without being preempted. - -If the last redisplay of @var{window} was preempted, and did not finish, -Emacs does not know the position of the end of display in that window. -In that case, this function returns @code{nil}. - -If @var{update} is non-@code{nil}, @code{window-end} always returns an -up-to-date value for where the window ends, based on the current -@code{window-start} value. If the saved value is valid, -@code{window-end} returns that; otherwise it computes the correct -value by scanning the buffer text. - -Even if @var{update} is non-@code{nil}, @code{window-end} does not -attempt to scroll the display if point has moved off the screen, the -way real redisplay would do. It does not alter the -@code{window-start} value. In effect, it reports where the displayed -text will end if scrolling is not required. -@end defun - -@defun set-window-start window position &optional noforce -This function sets the display-start position of @var{window} to -@var{position} in @var{window}'s buffer. It returns @var{position}. - -The display routines insist that the position of point be visible when a -buffer is displayed. Normally, they change the display-start position -(that is, scroll the window) whenever necessary to make point visible. -However, if you specify the start position with this function using -@code{nil} for @var{noforce}, it means you want display to start at -@var{position} even if that would put the location of point off the -screen. If this does place point off screen, the display routines move -point to the left margin on the middle line in the window. - -For example, if point @w{is 1} and you set the start of the window @w{to -2}, then point would be ``above'' the top of the window. The display -routines will automatically move point if it is still 1 when redisplay -occurs. Here is an example: - -@example -@group -;; @r{Here is what @samp{foo} looks like before executing} -;; @r{the @code{set-window-start} expression.} -@end group - -@group ----------- Buffer: foo ---------- -@point{}This is the contents of buffer foo. -2 -3 -4 -5 -6 ----------- Buffer: foo ---------- -@end group - -@group -(set-window-start - (selected-window) - (1+ (window-start))) -@result{} 2 -@end group - -@group -;; @r{Here is what @samp{foo} looks like after executing} -;; @r{the @code{set-window-start} expression.} ----------- Buffer: foo ---------- -his is the contents of buffer foo. -2 -3 -@point{}4 -5 -6 ----------- Buffer: foo ---------- -@end group -@end example - -If @var{noforce} is non-@code{nil}, and @var{position} would place point -off screen at the next redisplay, then redisplay computes a new window-start -position that works well with point, and thus @var{position} is not used. -@end defun - -@defun pos-visible-in-window-p &optional position window partially -This function returns non-@code{nil} if @var{position} is within the -range of text currently visible on the screen in @var{window}. It -returns @code{nil} if @var{position} is scrolled vertically out of -view. Locations that are partially obscured are not considered -visible unless @var{partially} is non-@code{nil}. The argument -@var{position} defaults to the current position of point in -@var{window}; @var{window}, to the selected window. - -If @var{position} is @code{t}, that means to check the last visible -position in @var{window}. - -The @code{pos-visible-in-window-p} function considers only vertical -scrolling. If @var{position} is out of view only because @var{window} -has been scrolled horizontally, @code{pos-visible-in-window-p} returns -non-@code{nil} anyway. @xref{Horizontal Scrolling}. - -If @var{position} is visible, @code{pos-visible-in-window-p} returns -@code{t} if @var{partially} is @code{nil}; if @var{partially} is -non-@code{nil}, and the character after @var{position} is fully -visible, it returns a list of the form @code{(@var{x} @var{y})}, where -@var{x} and @var{y} are the pixel coordinates relative to the top left -corner of the window; otherwise it returns an extended list of the -form @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} -@var{vpos})}, where the @var{rtop} and @var{rbot} specify the number -of off-window pixels at the top and bottom of the row at -@var{position}, @var{rowh} specifies the visible height of that row, -and @var{vpos} specifies the vertical position (zero-based row number) -of that row. - -Here is an example: - -@example -@group -;; @r{If point is off the screen now, recenter it now.} -(or (pos-visible-in-window-p - (point) (selected-window)) - (recenter 0)) -@end group -@end example -@end defun - -@defun window-line-height &optional line window -This function returns information about text line @var{line} in @var{window}. -If @var{line} is one of @code{header-line} or @code{mode-line}, -@code{window-line-height} returns information about the corresponding -line of the window. Otherwise, @var{line} is a text line number -starting from 0. A negative number counts from the end of the window. -The argument @var{line} defaults to the current line in @var{window}; -@var{window}, to the selected window. - -If the display is not up to date, @code{window-line-height} returns -@code{nil}. In that case, @code{pos-visible-in-window-p} may be used -to obtain related information. - -If there is no line corresponding to the specified @var{line}, -@code{window-line-height} returns @code{nil}. Otherwise, it returns -a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, -where @var{height} is the height in pixels of the visible part of the -line, @var{vpos} and @var{ypos} are the vertical position in lines and -pixels of the line relative to the top of the first text line, and -@var{offbot} is the number of off-window pixels at the bottom of the -text line. If there are off-window pixels at the top of the (first) -text line, @var{ypos} is negative. -@end defun - -@node Textual Scrolling -@section Textual Scrolling -@cindex textual scrolling -@cindex scrolling textually - - @dfn{Textual scrolling} means moving the text up or down through a -window. It works by changing the value of the window's display-start -location. It may also change the value of @code{window-point} to keep -point on the screen. - - Textual scrolling was formerly called ``vertical scrolling,'' but we -changed its name to distinguish it from the new vertical fractional -scrolling feature (@pxref{Vertical Scrolling}). - - In the commands @code{scroll-up} and @code{scroll-down}, the directions -``up'' and ``down'' refer to the motion of the text in the buffer at which -you are looking through the window. Imagine that the text is -written on a long roll of paper and that the scrolling commands move the -paper up and down. Thus, if you are looking at text in the middle of a -buffer and repeatedly call @code{scroll-down}, you will eventually see -the beginning of the buffer. - - Some people have urged that the opposite convention be used: they -imagine that the window moves over text that remains in place. Then -``down'' commands would take you to the end of the buffer. This view is -more consistent with the actual relationship between windows and the -text in the buffer, but it is less like what the user sees. The -position of a window on the terminal does not move, and short scrolling -commands clearly move the text up or down on the screen. We have chosen -names that fit the user's point of view. - - The textual scrolling functions (aside from -@code{scroll-other-window}) have unpredictable results if the current -buffer is different from the buffer that is displayed in the selected -window. @xref{Current Buffer}. - - If the window contains a row which is taller than the height of the -window (for example in the presence of a large image), the scroll -functions will adjust the window vscroll to scroll the partially -visible row. To disable this feature, Lisp code may bind the variable -`auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}). - -@deffn Command scroll-up &optional count -This function scrolls the text in the selected window upward -@var{count} lines. If @var{count} is negative, scrolling is actually -downward. - -If @var{count} is @code{nil} (or omitted), then the length of scroll -is @code{next-screen-context-lines} lines less than the usable height of -the window (not counting its mode line). - -@code{scroll-up} returns @code{nil}, unless it gets an error -because it can't scroll any further. -@end deffn - -@deffn Command scroll-down &optional count -This function scrolls the text in the selected window downward -@var{count} lines. If @var{count} is negative, scrolling is actually -upward. - -If @var{count} is omitted or @code{nil}, then the length of the scroll -is @code{next-screen-context-lines} lines less than the usable height of -the window (not counting its mode line). - -@code{scroll-down} returns @code{nil}, unless it gets an error because -it can't scroll any further. -@end deffn - -@deffn Command scroll-other-window &optional count -This function scrolls the text in another window upward @var{count} -lines. Negative values of @var{count}, or @code{nil}, are handled -as in @code{scroll-up}. - -You can specify which buffer to scroll by setting the variable -@code{other-window-scroll-buffer} to a buffer. If that buffer isn't -already displayed, @code{scroll-other-window} displays it in some -window. - -When the selected window is the minibuffer, the next window is normally -the one at the top left corner. You can specify a different window to -scroll, when the minibuffer is selected, by setting the variable -@code{minibuffer-scroll-window}. This variable has no effect when any -other window is selected. When it is non-@code{nil} and the -minibuffer is selected, it takes precedence over -@code{other-window-scroll-buffer}. @xref{Definition of -minibuffer-scroll-window}. - -When the minibuffer is active, it is the next window if the selected -window is the one at the bottom right corner. In this case, -@code{scroll-other-window} attempts to scroll the minibuffer. If the -minibuffer contains just one line, it has nowhere to scroll to, so the -line reappears after the echo area momentarily displays the message -@samp{Beginning of buffer}. -@end deffn - -@c Emacs 19 feature -@defvar other-window-scroll-buffer -If this variable is non-@code{nil}, it tells @code{scroll-other-window} -which buffer to scroll. -@end defvar - -@defopt scroll-margin -This option specifies the size of the scroll margin---a minimum number -of lines between point and the top or bottom of a window. Whenever -point gets within this many lines of the top or bottom of the window, -redisplay scrolls the text automatically (if possible) to move point -out of the margin, closer to the center of the window. -@end defopt - -@defopt scroll-conservatively -This variable controls how scrolling is done automatically when point -moves off the screen (or into the scroll margin). If the value is a -positive integer @var{n}, then redisplay scrolls the text up to -@var{n} lines in either direction, if that will bring point back into -proper view. This action is called @dfn{conservative scrolling}. -Otherwise, scrolling happens in the usual way, under the control of -other variables such as @code{scroll-up-aggressively} and -@code{scroll-down-aggressively}. - -The default value is zero, which means that conservative scrolling -never happens. -@end defopt - -@defopt scroll-down-aggressively -The value of this variable should be either @code{nil} or a fraction -@var{f} between 0 and 1. If it is a fraction, that specifies where on -the screen to put point when scrolling down. More precisely, when a -window scrolls down because point is above the window start, the new -start position is chosen to put point @var{f} part of the window -height from the top. The larger @var{f}, the more aggressive the -scrolling. - -A value of @code{nil} is equivalent to .5, since its effect is to center -point. This variable automatically becomes buffer-local when set in any -fashion. -@end defopt - -@defopt scroll-up-aggressively -Likewise, for scrolling up. The value, @var{f}, specifies how far -point should be placed from the bottom of the window; thus, as with -@code{scroll-up-aggressively}, a larger value scrolls more aggressively. -@end defopt - -@defopt scroll-step -This variable is an older variant of @code{scroll-conservatively}. The -difference is that it if its value is @var{n}, that permits scrolling -only by precisely @var{n} lines, not a smaller number. This feature -does not work with @code{scroll-margin}. The default value is zero. -@end defopt - -@defopt scroll-preserve-screen-position -If this option is @code{t}, scrolling which would move the current -point position out of the window chooses the new position of point -so that the vertical position of the cursor is unchanged, if possible. - -If it is non-@code{nil} and not @code{t}, then the scrolling functions -always preserve the vertical position of point, if possible. -@end defopt - -@defopt next-screen-context-lines -The value of this variable is the number of lines of continuity to -retain when scrolling by full screens. For example, @code{scroll-up} -with an argument of @code{nil} scrolls so that this many lines at the -bottom of the window appear instead at the top. The default value is -@code{2}. -@end defopt - -@deffn Command recenter &optional count -@cindex centering point -This function scrolls the text in the selected window so that point is -displayed at a specified vertical position within the window. It does -not ``move point'' with respect to the text. - -If @var{count} is a nonnegative number, that puts the line containing -point @var{count} lines down from the top of the window. If -@var{count} is a negative number, then it counts upward from the -bottom of the window, so that @minus{}1 stands for the last usable -line in the window. If @var{count} is a non-@code{nil} list, then it -stands for the line in the middle of the window. - -If @var{count} is @code{nil}, @code{recenter} puts the line containing -point in the middle of the window, then clears and redisplays the entire -selected frame. - -When @code{recenter} is called interactively, @var{count} is the raw -prefix argument. Thus, typing @kbd{C-u} as the prefix sets the -@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets -@var{count} to 4, which positions the current line four lines from the -top. - -With an argument of zero, @code{recenter} positions the current line at -the top of the window. This action is so handy that some people make a -separate key binding to do this. For example, - -@example -@group -(defun line-to-top-of-window () - "Scroll current line to top of window. -Replaces three keystroke sequence C-u 0 C-l." - (interactive) - (recenter 0)) - -(global-set-key [kp-multiply] 'line-to-top-of-window) -@end group -@end example -@end deffn - -@node Vertical Scrolling -@section Vertical Fractional Scrolling -@cindex vertical fractional scrolling - - @dfn{Vertical fractional scrolling} means shifting the image in the -window up or down by a specified multiple or fraction of a line. -Each window has a @dfn{vertical scroll position}, -which is a number, never less than zero. It specifies how far to raise -the contents of the window. Raising the window contents generally makes -all or part of some lines disappear off the top, and all or part of some -other lines appear at the bottom. The usual value is zero. - - The vertical scroll position is measured in units of the normal line -height, which is the height of the default font. Thus, if the value is -.5, that means the window contents are scrolled up half the normal line -height. If it is 3.3, that means the window contents are scrolled up -somewhat over three times the normal line height. - - What fraction of a line the vertical scrolling covers, or how many -lines, depends on what the lines contain. A value of .5 could scroll a -line whose height is very short off the screen, while a value of 3.3 -could scroll just part of the way through a tall line or an image. - -@defun window-vscroll &optional window pixels-p -This function returns the current vertical scroll position of -@var{window}. If @var{window} is @code{nil}, the selected window is -used. If @var{pixels-p} is non-@code{nil}, the return value is -measured in pixels, rather than in units of the normal line height. - -@example -@group -(window-vscroll) - @result{} 0 -@end group -@end example -@end defun - -@defun set-window-vscroll window lines &optional pixels-p -This function sets @var{window}'s vertical scroll position to -@var{lines}. The argument @var{lines} should be zero or positive; if -not, it is taken as zero. - -If @var{window} is @code{nil}, the selected window is used. - -The actual vertical scroll position must always correspond -to an integral number of pixels, so the value you specify -is rounded accordingly. - -The return value is the result of this rounding. - -@example -@group -(set-window-vscroll (selected-window) 1.2) - @result{} 1.13 -@end group -@end example - -If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of -pixels. In this case, the return value is @var{lines}. -@end defun - -@defvar auto-window-vscroll -If this variable is non-@code{nil}, the line-move, scroll-up, and -scroll-down functions will automatically modify the window vscroll to -scroll through display rows that are taller that the height of the -window, for example in the presence of large images. -@end defvar - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - - @dfn{Horizontal scrolling} means shifting the image in the window left -or right by a specified multiple of the normal character width. Each -window has a @dfn{horizontal scroll position}, which is a number, never -less than zero. It specifies how far to shift the contents left. -Shifting the window contents left generally makes all or part of some -characters disappear off the left, and all or part of some other -characters appear at the right. The usual value is zero. - - The horizontal scroll position is measured in units of the normal -character width, which is the width of space in the default font. Thus, -if the value is 5, that means the window contents are scrolled left by 5 -times the normal character width. How many characters actually -disappear off to the left depends on their width, and could vary from -line to line. - - Because we read from side to side in the ``inner loop,'' and from top -to bottom in the ``outer loop,'' the effect of horizontal scrolling is -not like that of textual or vertical scrolling. Textual scrolling -involves selection of a portion of text to display, and vertical -scrolling moves the window contents contiguously; but horizontal -scrolling causes part of @emph{each line} to go off screen. - - Usually, no horizontal scrolling is in effect; then the leftmost -column is at the left edge of the window. In this state, scrolling to -the right is meaningless, since there is no data to the left of the edge -to be revealed by it; so this is not allowed. Scrolling to the left is -allowed; it scrolls the first columns of text off the edge of the window -and can reveal additional columns on the right that were truncated -before. Once a window has a nonzero amount of leftward horizontal -scrolling, you can scroll it back to the right, but only so far as to -reduce the net horizontal scroll to zero. There is no limit to how far -left you can scroll, but eventually all the text will disappear off the -left edge. - -@vindex auto-hscroll-mode - If @code{auto-hscroll-mode} is set, redisplay automatically alters -the horizontal scrolling of a window as necessary to ensure that point -is always visible. However, you can still set the horizontal -scrolling value explicitly. The value you specify serves as a lower -bound for automatic scrolling, i.e. automatic scrolling will not -scroll a window to a column less than the specified one. - -@deffn Command scroll-left &optional count set-minimum -This function scrolls the selected window @var{count} columns to the -left (or to the right if @var{count} is negative). The default -for @var{count} is the window width, minus 2. - -The return value is the total amount of leftward horizontal scrolling in -effect after the change---just like the value returned by -@code{window-hscroll} (below). - -Once you scroll a window as far right as it can go, back to its normal -position where the total leftward scrolling is zero, attempts to scroll -any farther right have no effect. - -If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes -the lower bound for automatic scrolling; that is, automatic scrolling -will not scroll a window to a column less than the value returned by -this function. Interactive calls pass non-@code{nil} for -@var{set-minimum}. -@end deffn - -@deffn Command scroll-right &optional count set-minimum -This function scrolls the selected window @var{count} columns to the -right (or to the left if @var{count} is negative). The default -for @var{count} is the window width, minus 2. Aside from the direction -of scrolling, this works just like @code{scroll-left}. -@end deffn - -@defun window-hscroll &optional window -This function returns the total leftward horizontal scrolling of -@var{window}---the number of columns by which the text in @var{window} -is scrolled left past the left margin. - -The value is never negative. It is zero when no horizontal scrolling -has been done in @var{window} (which is usually the case). - -If @var{window} is @code{nil}, the selected window is used. - -@example -@group -(window-hscroll) - @result{} 0 -@end group -@group -(scroll-left 5) - @result{} 5 -@end group -@group -(window-hscroll) - @result{} 5 -@end group -@end example -@end defun - -@defun set-window-hscroll window columns -This function sets horizontal scrolling of @var{window}. The value of -@var{columns} specifies the amount of scrolling, in terms of columns -from the left margin. The argument @var{columns} should be zero or -positive; if not, it is taken as zero. Fractional values of -@var{columns} are not supported at present. - -Note that @code{set-window-hscroll} may appear not to work if you test -it by evaluating a call with @kbd{M-:} in a simple way. What happens -is that the function sets the horizontal scroll value and returns, but -then redisplay adjusts the horizontal scrolling to make point visible, -and this overrides what the function did. You can observe the -function's effect if you call it while point is sufficiently far from -the left margin that it will remain visible. - -The value returned is @var{columns}. - -@example -@group -(set-window-hscroll (selected-window) 10) - @result{} 10 -@end group -@end example -@end defun - - Here is how you can determine whether a given position @var{position} -is off the screen due to horizontal scrolling: - -@example -@group -(defun hscroll-on-screen (window position) - (save-excursion - (goto-char position) - (and - (>= (- (current-column) (window-hscroll window)) 0) - (< (- (current-column) (window-hscroll window)) - (window-width window))))) -@end group -@end example - -@node Size of Window -@section The Size of a Window -@cindex window size -@cindex size of window - - An Emacs window is rectangular, and its size information consists of -the height (the number of lines) and the width (the number of character -positions in each line). The mode line is included in the height. But -the width does not count the scroll bar or the column of @samp{|} -characters that separates side-by-side windows. - - The following three functions return size information about a window: - -@defun window-height &optional window -This function returns the number of lines in @var{window}, including -its mode line and header line, if any. If @var{window} fills its -entire frame except for the echo area, this is typically one less than -the value of @code{frame-height} on that frame. - -If @var{window} is @code{nil}, the function uses the selected window. - -@example -@group -(window-height) - @result{} 23 -@end group -@group -(split-window-vertically) - @result{} #<window 4 on windows.texi> -@end group -@group -(window-height) - @result{} 11 -@end group -@end example -@end defun - -@defun window-body-height &optional window -Like @code{window-height} but the value does not include the -mode line (if any) or the header line (if any). -@end defun - -@defun window-width &optional window -This function returns the number of columns in @var{window}. If -@var{window} fills its entire frame, this is the same as the value of -@code{frame-width} on that frame. The width does not include the -window's scroll bar or the column of @samp{|} characters that separates -side-by-side windows. - -If @var{window} is @code{nil}, the function uses the selected window. - -@example -@group -(window-width) - @result{} 80 -@end group -@end example -@end defun - -@defun window-full-width-p &optional window -This function returns non-@code{nil} if @var{window} is as wide as -the frame that contains it; otherwise @code{nil}. -If @var{window} is @code{nil}, the function uses the selected window. -@end defun - -@defun window-edges &optional window -This function returns a list of the edge coordinates of @var{window}. -If @var{window} is @code{nil}, the selected window is used. - -The order of the list is @code{(@var{left} @var{top} @var{right} -@var{bottom})}, all elements relative to 0, 0 at the top left corner of -the frame. The element @var{right} of the value is one more than the -rightmost column used by @var{window}, and @var{bottom} is one more than -the bottommost row used by @var{window} and its mode-line. - -The edges include the space used by the window's scroll bar, display -margins, fringes, header line, and mode line, if it has them. Also, -if the window has a neighbor on the right, its right edge value -includes the width of the separator line between the window and that -neighbor. Since the width of the window does not include this -separator, the width does not usually equal the difference between the -right and left edges. -@end defun - -@defun window-inside-edges &optional window -This is similar to @code{window-edges}, but the edge values -it returns include only the text area of the window. They -do not include the header line, mode line, scroll bar or -vertical separator, fringes, or display margins. -@end defun - -Here are the results obtained on a typical 24-line terminal with just -one window, with menu bar enabled: - -@example -@group -(window-edges (selected-window)) - @result{} (0 1 80 23) -@end group -@group -(window-inside-edges (selected-window)) - @result{} (0 1 80 22) -@end group -@end example - -@noindent -The bottom edge is at line 23 because the last line is the echo area. -The bottom inside edge is at line 22, which is the window's mode line. - -If @var{window} is at the upper left corner of its frame, and there is -no menu bar, then @var{bottom} returned by @code{window-edges} is the -same as the value of @code{(window-height)}, @var{right} is almost the -same as the value of @code{(window-width)}, and @var{top} and -@var{left} are zero. For example, the edges of the following window -are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8 -columns, the last column of the window (column 7) holds a border -rather than text. The last row (row 4) holds the mode line, shown -here with @samp{xxxxxxxxx}. - -@example -@group - 0 - _______ - 0 | | - | | - | | - | | - xxxxxxxxx 4 - - 7 -@end group -@end example - -In the following example, let's suppose that the frame is 7 -columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} -and the edges of the right window are @w{@samp{4 0 7 3}}. -The inside edges of the left window are @w{@samp{0 0 3 2}}, -and the inside edges of the right window are @w{@samp{4 0 7 2}}, - -@example -@group - ___ ___ - | | | - | | | - xxxxxxxxx - - 0 34 7 -@end group -@end example - -@defun window-pixel-edges &optional window -This function is like @code{window-edges} except that, on a graphical -display, the edge values are measured in pixels instead of in -character lines and columns. -@end defun - -@defun window-inside-pixel-edges &optional window -This function is like @code{window-inside-edges} except that, on a -graphical display, the edge values are measured in pixels instead of -in character lines and columns. -@end defun - -@node Resizing Windows -@section Changing the Size of a Window -@cindex window resizing -@cindex resize window -@cindex changing window size -@cindex window size, changing - - The window size functions fall into two classes: high-level commands -that change the size of windows and low-level functions that access -window size. Emacs does not permit overlapping windows or gaps between -windows, so resizing one window affects other windows. - -@deffn Command enlarge-window size &optional horizontal -This function makes the selected window @var{size} lines taller, -stealing lines from neighboring windows. It takes the lines from one -window at a time until that window is used up, then takes from another. -If a window from which lines are stolen shrinks below -@code{window-min-height} lines, that window disappears. - -If @var{horizontal} is non-@code{nil}, this function makes -@var{window} wider by @var{size} columns, stealing columns instead of -lines. If a window from which columns are stolen shrinks below -@code{window-min-width} columns, that window disappears. - -If the requested size would exceed that of the window's frame, then the -function makes the window occupy the entire height (or width) of the -frame. - -If there are various other windows from which lines or columns can be -stolen, and some of them specify fixed size (using -@code{window-size-fixed}, see below), they are left untouched while -other windows are ``robbed.'' If it would be necessary to alter the -size of a fixed-size window, @code{enlarge-window} gets an error -instead. - -If @var{size} is negative, this function shrinks the window by -@minus{}@var{size} lines or columns. If that makes the window smaller -than the minimum size (@code{window-min-height} and -@code{window-min-width}), @code{enlarge-window} deletes the window. - -@code{enlarge-window} returns @code{nil}. -@end deffn - -@deffn Command enlarge-window-horizontally columns -This function makes the selected window @var{columns} wider. -It could be defined as follows: - -@example -@group -(defun enlarge-window-horizontally (columns) - (interactive "p") - (enlarge-window columns t)) -@end group -@end example -@end deffn - -@deffn Command shrink-window size &optional horizontal -This function is like @code{enlarge-window} but negates the argument -@var{size}, making the selected window smaller by giving lines (or -columns) to the other windows. If the window shrinks below -@code{window-min-height} or @code{window-min-width}, then it disappears. - -If @var{size} is negative, the window is enlarged by @minus{}@var{size} -lines or columns. -@end deffn - -@deffn Command shrink-window-horizontally columns -This function makes the selected window @var{columns} narrower. -It could be defined as follows: - -@example -@group -(defun shrink-window-horizontally (columns) - (interactive "p") - (shrink-window columns t)) -@end group -@end example -@end deffn - -@defun adjust-window-trailing-edge window delta horizontal -This function makes the selected window @var{delta} lines taller or -@var{delta} columns wider, by moving the bottom or right edge. This -function does not delete other windows; if it cannot make the -requested size adjustment, it signals an error. On success, this -function returns @code{nil}. -@end defun - -@defun fit-window-to-buffer &optional window max-height min-height -This function makes @var{window} the right height to display its -contents exactly. If @var{window} is omitted or @code{nil}, it uses -the selected window. - -The argument @var{max-height} specifies the maximum height the window -is allowed to be; @code{nil} means use the frame height. The argument -@var{min-height} specifies the minimum height for the window; -@code{nil} means use @code{window-min-height}. All these height -values include the mode-line and/or header-line. -@end defun - -@deffn Command shrink-window-if-larger-than-buffer &optional window -This command shrinks @var{window} vertically to be as small as -possible while still showing the full contents of its buffer---but not -less than @code{window-min-height} lines. If @var{window} is not -given, it defaults to the selected window. - -However, the command does nothing if the window is already too small to -display the whole text of the buffer, or if part of the contents are -currently scrolled off screen, or if the window is not the full width of -its frame, or if the window is the only window in its frame. - -This command returns non-@code{nil} if it actually shrank the window -and @code{nil} otherwise. -@end deffn - -@defvar window-size-fixed -If this variable is non-@code{nil}, in any given buffer, -then the size of any window displaying the buffer remains fixed -unless you explicitly change it or Emacs has no other choice. - -If the value is @code{height}, then only the window's height is fixed; -if the value is @code{width}, then only the window's width is fixed. -Any other non-@code{nil} value fixes both the width and the height. - -This variable automatically becomes buffer-local when set. - -Explicit size-change functions such as @code{enlarge-window} -get an error if they would have to change a window size which is fixed. -Therefore, when you want to change the size of such a window, -you should bind @code{window-size-fixed} to @code{nil}, like this: - -@example -(let ((window-size-fixed nil)) - (enlarge-window 10)) -@end example - -Note that changing the frame size will change the size of a -fixed-size window, if there is no other alternative. -@end defvar - -@cindex minimum window size - The following two variables constrain the window-structure-changing -functions to a minimum height and width. - -@defopt window-min-height -The value of this variable determines how short a window may become -before it is automatically deleted. Making a window smaller than -@code{window-min-height} automatically deletes it, and no window may -be created shorter than this. The default value is 4. - -The absolute minimum window height is one; actions that change window -sizes reset this variable to one if it is less than one. -@end defopt - -@defopt window-min-width -The value of this variable determines how narrow a window may become -before it is automatically deleted. Making a window smaller than -@code{window-min-width} automatically deletes it, and no window may be -created narrower than this. The default value is 10. - -The absolute minimum window width is two; actions that change window -sizes reset this variable to two if it is less than two. -@end defopt - -@node Coordinates and Windows -@section Coordinates and Windows - -This section describes how to relate screen coordinates to windows. - -@defun window-at x y &optional frame -This function returns the window containing the specified cursor -position in the frame @var{frame}. The coordinates @var{x} and @var{y} -are measured in characters and count from the top left corner of the -frame. If they are out of range, @code{window-at} returns @code{nil}. - -If you omit @var{frame}, the selected frame is used. -@end defun - -@defun coordinates-in-window-p coordinates window -This function checks whether a particular frame position falls within -the window @var{window}. - -The argument @var{coordinates} is a cons cell of the form @code{(@var{x} -. @var{y})}. The coordinates @var{x} and @var{y} are measured in -characters, and count from the top left corner of the screen or frame. - -The value returned by @code{coordinates-in-window-p} is non-@code{nil} -if the coordinates are inside @var{window}. The value also indicates -what part of the window the position is in, as follows: - -@table @code -@item (@var{relx} . @var{rely}) -The coordinates are inside @var{window}. The numbers @var{relx} and -@var{rely} are the equivalent window-relative coordinates for the -specified position, counting from 0 at the top left corner of the -window. - -@item mode-line -The coordinates are in the mode line of @var{window}. - -@item header-line -The coordinates are in the header line of @var{window}. - -@item vertical-line -The coordinates are in the vertical line between @var{window} and its -neighbor to the right. This value occurs only if the window doesn't -have a scroll bar; positions in a scroll bar are considered outside the -window for these purposes. - -@item left-fringe -@itemx right-fringe -The coordinates are in the left or right fringe of the window. - -@item left-margin -@itemx right-margin -The coordinates are in the left or right margin of the window. - -@item nil -The coordinates are not in any part of @var{window}. -@end table - -The function @code{coordinates-in-window-p} does not require a frame as -argument because it always uses the frame that @var{window} is on. -@end defun - -@node Window Tree -@section The Window Tree -@cindex window tree - - A @dfn{window tree} specifies the layout, size, and relationship -between all windows in one frame. - -@defun window-tree &optional frame -This function returns the window tree for frame @var{frame}. -If @var{frame} is omitted, the selected frame is used. - -The return value is a list of the form @code{(@var{root} @var{mini})}, -where @var{root} represents the window tree of the frame's -root window, and @var{mini} is the frame's minibuffer window. - -If the root window is not split, @var{root} is the root window itself. -Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} -@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split, -and @code{t} for a vertical split, @var{edges} gives the combined size and -position of the subwindows in the split, and the rest of the elements -are the subwindows in the split. Each of the subwindows may again be -a window or a list representing a window split, and so on. The -@var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})} -similar to the value returned by @code{window-edges}. -@end defun - -@node Window Configurations -@section Window Configurations -@cindex window configurations -@cindex saving window information - - A @dfn{window configuration} records the entire layout of one -frame---all windows, their sizes, which buffers they contain, what -part of each buffer is displayed, and the values of point and the -mark; also their fringes, margins, and scroll bar settings. It also -includes the values of @code{window-min-height}, -@code{window-min-width} and @code{minibuffer-scroll-window}. An -exception is made for point in the selected window for the current -buffer; its value is not saved in the window configuration. - - You can bring back an entire previous layout by restoring a window -configuration previously saved. If you want to record all frames -instead of just one, use a frame configuration instead of a window -configuration. @xref{Frame Configurations}. - -@defun current-window-configuration &optional frame -This function returns a new object representing @var{frame}'s current -window configuration. If @var{frame} is omitted, the selected frame -is used. -@end defun - -@defun set-window-configuration configuration -This function restores the configuration of windows and buffers as -specified by @var{configuration}, for the frame that @var{configuration} -was created for. - -The argument @var{configuration} must be a value that was previously -returned by @code{current-window-configuration}. This configuration is -restored in the frame from which @var{configuration} was made, whether -that frame is selected or not. This always counts as a window size -change and triggers execution of the @code{window-size-change-functions} -(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't -know how to tell whether the new configuration actually differs from the -old one. - -If the frame which @var{configuration} was saved from is dead, all this -function does is restore the three variables @code{window-min-height}, -@code{window-min-width} and @code{minibuffer-scroll-window}. In this -case, the function returns @code{nil}. Otherwise, it returns @code{t}. - -Here is a way of using this function to get the same effect -as @code{save-window-excursion}: - -@example -@group -(let ((config (current-window-configuration))) - (unwind-protect - (progn (split-window-vertically nil) - @dots{}) - (set-window-configuration config))) -@end group -@end example -@end defun - -@defspec save-window-excursion forms@dots{} -This special form records the window configuration, executes @var{forms} -in sequence, then restores the earlier window configuration. The window -configuration includes, for each window, the value of point and the -portion of the buffer that is visible. It also includes the choice of -selected window. However, it does not include the value of point in -the current buffer; use @code{save-excursion} also, if you wish to -preserve that. - -Don't use this construct when @code{save-selected-window} is sufficient. - -Exit from @code{save-window-excursion} always triggers execution of the -@code{window-size-change-functions}. (It doesn't know how to tell -whether the restored configuration actually differs from the one in -effect at the end of the @var{forms}.) - -The return value is the value of the final form in @var{forms}. -For example: - -@example -@group -(split-window) - @result{} #<window 25 on control.texi> -@end group -@group -(setq w (selected-window)) - @result{} #<window 19 on control.texi> -@end group -@group -(save-window-excursion - (delete-other-windows w) - (switch-to-buffer "foo") - 'do-something) - @result{} do-something - ;; @r{The screen is now split again.} -@end group -@end example -@end defspec - -@defun window-configuration-p object -This function returns @code{t} if @var{object} is a window configuration. -@end defun - -@defun compare-window-configurations config1 config2 -This function compares two window configurations as regards the -structure of windows, but ignores the values of point and mark and the -saved scrolling positions---it can return @code{t} even if those -aspects differ. - -The function @code{equal} can also compare two window configurations; it -regards configurations as unequal if they differ in any respect, even a -saved point or mark. -@end defun - -@defun window-configuration-frame config -This function returns the frame for which the window configuration -@var{config} was made. -@end defun - - Other primitives to look inside of window configurations would make -sense, but are not implemented because we did not need them. See the -file @file{winner.el} for some more operations on windows -configurations. - -@node Window Hooks -@section Hooks for Window Scrolling and Changes -@cindex hooks for window operations - -This section describes how a Lisp program can take action whenever a -window displays a different part of its buffer or a different buffer. -There are three actions that can change this: scrolling the window, -switching buffers in the window, and changing the size of the window. -The first two actions run @code{window-scroll-functions}; the last runs -@code{window-size-change-functions}. - -@defvar window-scroll-functions -This variable holds a list of functions that Emacs should call before -redisplaying a window with scrolling. It is not a normal hook, because -each function is called with two arguments: the window, and its new -display-start position. - -Displaying a different buffer in the window also runs these functions. - -These functions must be careful in using @code{window-end} -(@pxref{Window Start}); if you need an up-to-date value, you must use -the @var{update} argument to ensure you get it. - -@strong{Warning:} don't use this feature to alter the way the window -is scrolled. It's not designed for that, and such use probably won't -work. -@end defvar - -@defvar window-size-change-functions -This variable holds a list of functions to be called if the size of any -window changes for any reason. The functions are called just once per -redisplay, and just once for each frame on which size changes have -occurred. - -Each function receives the frame as its sole argument. There is no -direct way to find out which windows on that frame have changed size, or -precisely how. However, if a size-change function records, at each -call, the existing windows and their sizes, it can also compare the -present sizes and the previous sizes. - -Creating or deleting windows counts as a size change, and therefore -causes these functions to be called. Changing the frame size also -counts, because it changes the sizes of the existing windows. - -It is not a good idea to use @code{save-window-excursion} (@pxref{Window -Configurations}) in these functions, because that always counts as a -size change, and it would cause these functions to be called over and -over. In most cases, @code{save-selected-window} (@pxref{Selecting -Windows}) is what you need here. -@end defvar - -@defvar redisplay-end-trigger-functions -This abnormal hook is run whenever redisplay in a window uses text that -extends past a specified end trigger position. You set the end trigger -position with the function @code{set-window-redisplay-end-trigger}. The -functions are called with two arguments: the window, and the end trigger -position. Storing @code{nil} for the end trigger position turns off the -feature, and the trigger value is automatically reset to @code{nil} just -after the hook is run. -@end defvar - -@defun set-window-redisplay-end-trigger window position -This function sets @var{window}'s end trigger position at -@var{position}. -@end defun - -@defun window-redisplay-end-trigger &optional window -This function returns @var{window}'s current end trigger position. -If @var{window} is @code{nil} or omitted, it uses the selected window. -@end defun - -@defvar window-configuration-change-hook -A normal hook that is run every time you change the window configuration -of an existing frame. This includes splitting or deleting windows, -changing the sizes of windows, or displaying a different buffer in a -window. The frame whose window configuration has changed is the -selected frame when this hook runs. -@end defvar - -@ignore - arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3 -@end ignore |