procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update unicode branch

Browse source
This commit is contained in:
Miles Bader 2004-04-19 07:01:43 +00:00
parent 6b61353c0a
commit 770ecbeecb
64 changed files with 6360 additions and 1935 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

938
lispref/ChangeLog
View file

@ -1,3 +1,935 @@
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.
@ -88,7 +1020,7 @@
(Hooks): Add run-mode-hooks and delay-mode-hooks.
* variables.texi (Creating Buffer-Local): Add buffer-local-value.
(Variable Aliases): Clarify defvralias.
(Variable Aliases): Clarify defvaralias.
* loading.texi (Library Search): Add load-suffixes.
@ -738,9 +1670,11 @@ Tue Apr 11 12:23:28 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu)
for the Project GNU development environment.
;; Local Variables:
;; coding: iso-2022-7bit-unix
;; coding: iso-2022-7bit
;; End:
Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification,
are permitted provided the copyright notice and this notice are preserved.
;;; arch-tag: 985ae0ce-df29-475b-b3f8-4bbcbf6f7fda

51
lispref/Makefile.in
View file

@ -1,6 +1,6 @@
# Makefile for the GNU Emacs Lisp Reference Manual.
# Copyright (C) 1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
# Copyright (C) 1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001,2003
# Free Software Foundation, Inc.
# This file is part of GNU Emacs.
@ -28,24 +28,15 @@ VPATH=@srcdir@
infodir = $(srcdir)/../info
# Redefine `TEX' if `tex' does not invoke plain TeX. For example:
# TEX=platex
TEX=tex
SHELL=/bin/sh
TEXI2DVI = texi2dvi
SHELL = /bin/sh
INSTALL_INFO = install-info
MAKEINFO=makeinfo
# The environment variable and its value to add $(srcdir) to the path
# searched for TeX input files.
texinputdir = TEXINPUTS=$(srcdir):"$(TEXINPUTS)"
MAKEINFO = makeinfo
# The name of the manual:
VERSION=2.9
manual = elisp-manual-21-$(VERSION)
# Uncomment this line for permuted index.
# permuted_index = 1
# List of all the texinfo files in the manual:
srcs = \
@ -99,8 +90,7 @@ srcs = \
$(srcdir)/tips.texi \
$(srcdir)/variables.texi \
$(srcdir)/windows.texi \
$(srcdir)/index.unperm \
$(srcdir)/index.perm \
$(srcdir)/index.texi \
$(srcdir)/gpl.texi \
$(srcdir)/doclicense.texi
@ -110,31 +100,11 @@ srcs = \
# The info file is named `elisp'.
info: $(infodir)/elisp
$(infodir)/elisp: $(srcs) index.texi
$(infodir)/elisp: $(srcs)
$(MAKEINFO) -I. -I$(srcdir) $(srcdir)/elisp.texi -o $(infodir)/elisp
elisp.dvi: $(srcs) index.texi
# Avoid losing old contents of aux file entirely.
-mv elisp.aux elisp.oaux
# First shot to define xrefs.
$(texinputdir) $(TEX) $(srcdir)/elisp.texi
if [ a${permuted_index} != a ]; \
then \
$(srcdir)/permute-index; \
mv permuted.fns elisp.fns; \
texindex elisp.tp; \
else \
texindex elisp.??; \
fi
$(texinputdir) $(TEX) $(srcdir)/elisp.texi
index.texi:
if [ a${permuted_index} != a ]; \
then \
ln -s $(srcdir)/index.perm index.texi || ln $(srcdir)/index.perm index.texi || cp $(srcdir)/index.perm index.texi; \
else \
ln -s $(srcdir)/index.unperm index.texi || ln $(srcdir)/index.unperm index.texi || cp $(srcdir)/index.unperm index.texi; \
fi
elisp.dvi: $(srcs)
$(TEXI2DVI) -I $(srcdir) $(srcdir)/elisp.texi
install: elisp
$(srcdir)/mkinstalldirs $(infodir)
@ -145,7 +115,6 @@ clean:
rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \
*.vr *.vrs *.pg *.pgs *.ky *.kys
rm -f make.out core
rm -f index.texi
distclean: clean
@ -157,7 +126,7 @@ dist: elisp elisp.dvi
-mkdir temp
-mkdir temp/$(manual)
-ln $(srcdir)/README $(srcdir)/configure.in $(srcdir)/configure \
$(srcdir)/Makefile.in $(srcdir)/permute-index $(srcs) \
$(srcdir)/Makefile.in $(srcs) \
$(srcdir)/../man/texinfo.tex \
elisp.dvi elisp.aux elisp.??s elisp elisp-[0-9] elisp-[0-9][0-9] \
temp/$(manual)
@ -166,3 +135,5 @@ dist: elisp elisp.dvi
(cd temp/$(manual); rm -f *~)
(cd temp; tar chf - $(manual)) | gzip > $(manual).tar.gz
-rm -rf temp
# arch-tag: f5a1a94d-62e1-4460-a2d1-f02e538ab554

116
lispref/abbrevs.texi
View file

@ -24,12 +24,17 @@ 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
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.) Because these symbols 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
@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
@ -80,13 +85,28 @@ 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} @r{[}@var{system-flag}@r{]})}. The return
value is always @code{nil}.
@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
@ -100,38 +120,24 @@ 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.
Otherwise the description is a Lisp expression---a call to
@code{define-abbrev-table} that would define @var{name} exactly as it
is currently defined.
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
These functions define an abbrev in a specified abbrev table.
@code{define-abbrev} is the low-level basic function, while
@code{add-abbrev} is used by commands that ask for information from
the user. When major modes predefine standard abbrevs, they should
call @code{define-abbrev} and specify @code{t} for @var{system-flag}.
@defun add-abbrev table type arg
This function adds an abbreviation to abbrev table @var{table} based on
information from the user. The argument @var{type} is a string
describing in English the kind of abbrev this will be (typically,
@code{"global"} or @code{"mode-specific"}); this is used in prompting
the user. The argument @var{arg} is the number of words in the
expansion.
The return value is the symbol that internally represents the new
abbrev, or @code{nil} if the user declines to confirm redefining an
existing abbrev.
@end defun
@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}.
@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 a
symbol that represents the abbrev inside Emacs; its name is
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
@ -149,6 +155,7 @@ 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
@ -204,9 +211,10 @@ This function does not display any messages. It returns @code{nil}.
@end defun
@defopt save-abbrevs
A non-@code{nil} value for @code{save-abbrev} means that Emacs should
save abbrevs when files are saved. @code{abbrev-file-name} specifies
the file to save the abbrevs in.
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
@ -216,11 +224,11 @@ 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), in all abbrev
tables, 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}.
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
@ -243,9 +251,10 @@ abbrev table.
@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). The optional
argument @var{table} specifies the abbrev table to use, as in
@code{abbrev-symbol}.
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
@ -260,10 +269,15 @@ returns @code{nil} even though expansion did occur.
@end deffn
@deffn Command abbrev-prefix-mark &optional arg
Mark current 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.
This command marks current 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
@ -274,9 +288,10 @@ expansion.
@end defopt
@defvar abbrev-start-location
This is the buffer position for @code{expand-abbrev} to use as the start
of the next abbrev to be expanded. (@code{nil} means use the word
before point instead.) @code{abbrev-start-location} is set to
The value of this variable is a marker pointing to the buffer position
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
@ -377,3 +392,6 @@ This is the local abbrev table used in Text mode.
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

4
lispref/advice.texi
View file

@ -751,3 +751,7 @@ pieces of advice is the same. The only difference is that
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

7
lispref/anti.texi
View file

@ -100,7 +100,7 @@ and background colors, so you cannot specify different colors for
the scroll bars.
@item
For simplicity, all @sc{ascii} characters now have the same height and width.
For simplicity, all @acronym{ASCII} characters now have the same height and width.
(Certain characters, such as Chinese characters, always have twice
the standard width.) All characters are created equal.
@ -292,4 +292,9 @@ and allied functions.
@item
@code{file-attributes} returns the file size and the file inode number
only as a simple integer.
Also @acronym{UID} and @acronym{GID} are always returned as integers.
@end itemize
@ignore
arch-tag: 1d0ef137-2bad-430e-ae8e-d820d569b5a6
@end ignore

4
lispref/back.texi
View file

@ -31,3 +31,7 @@ are peculiar to Emacs Lisp or relate specifically to editing.
@hfil
@bye
@ignore
arch-tag: ac7694c8-1f02-4b42-9531-33ba13b179e1
@end ignore

77
lispref/backups.texi
View file

@ -55,6 +55,14 @@ don't want them any more, or Emacs can delete them automatically.
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
@ -90,7 +98,7 @@ save disk space. (You would put this code in your init file.)
@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, a file name to consider. If the function returns
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.
@ -146,6 +154,7 @@ ignored.
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} behaviour.
@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
@ -184,25 +193,25 @@ 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}.
@defvar backup-by-copying
@defopt backup-by-copying
If this variable is non-@code{nil}, Emacs always makes backup files by
copying.
@end defvar
@end defopt
The following two 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.
@defvar backup-by-copying-when-linked
@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 defvar
@end defopt
@defvar backup-by-copying-when-mismatch
@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.
@ -214,9 +223,9 @@ 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 defvar
@end defopt
@defvar backup-by-copying-when-privileged-mismatch
@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
@ -227,7 +236,7 @@ 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 defvar
@end defopt
@node Numbered Backups
@subsection Making and Deleting Numbered Backup Files
@ -379,7 +388,8 @@ 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.
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
@ -518,7 +528,7 @@ customize the naming convention for auto-save files. Be sure to
change @code{auto-save-file-name-p} in a corresponding way.
@end defun
@defvar auto-save-visited-file-name
@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
@ -530,7 +540,7 @@ 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 defvar
@end defopt
@defun recent-auto-save-p
This function returns @code{t} if the current buffer has been
@ -547,7 +557,8 @@ function returns @code{nil}.
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.
enabled. Setting this to zero disables autosaving based on the
number of characters typed.
@end defopt
@defopt auto-save-timeout
@ -586,24 +597,28 @@ If @var{current-only} is non-@code{nil}, only the current buffer
is auto-saved.
@end deffn
@defun delete-auto-save-file-if-necessary
@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
@defvar delete-auto-save-files
@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 defvar
@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 the visited file name has not changed, this function does
nothing.
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
@ -633,7 +648,7 @@ 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 @sc{id} and the
with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the
host name.
@end defvar
@ -654,7 +669,7 @@ 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
@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.
@ -670,6 +685,10 @@ 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 file'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
@ -682,22 +701,24 @@ the buffer. Preserving any additional markers would be problematical.
You can customize how @code{revert-buffer} does its work by setting
the variables described in the rest of this section.
@defvar revert-without-query
@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 defvar
@end defopt
Some major modes customize @code{revert-buffer} by making
buffer-local bindings for these variables:
@defvar revert-buffer-function
The value of this variable is the function to use to revert this buffer.
If non-@code{nil}, it is called as a function with no arguments to do
the work of reverting. If the value is @code{nil}, reverting works the
usual way.
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
@ -729,3 +750,7 @@ 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

4
lispref/book-spine.texinfo
View file

@ -23,3 +23,7 @@
@sp 5
@center Free Software Foundation
@bye
@ignore
arch-tag: 4466c7ca-e549-4119-948c-6eed34e1ff87
@end ignore

240
lispref/buffers.texi
View file

@ -106,7 +106,7 @@ Emacs reads a command is the buffer that the command will apply 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{Note:} Lisp functions that change to a different current buffer
@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
@ -215,14 +215,19 @@ of course. Instead, whichever buffer was current just before exit
remains current.
@end defspec
@defmac with-current-buffer buffer body...
@defmac with-current-buffer buffer-or-name body...
The @code{with-current-buffer} macro saves the identity of the current
buffer, makes @var{buffer} 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}).
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
@anchor{Definition of with-temp-buffer}
@defmac with-temp-buffer body...
The @code{with-temp-buffer} macro evaluates the @var{body} forms
with a temporary buffer as the current buffer. It saves the identity of
@ -236,9 +241,10 @@ return the contents of the temporary buffer by using
The current buffer is restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
@end defmac
See also @code{with-temp-file} in @ref{Writing to Files}.
See also @code{with-temp-file} in @ref{Definition of with-temp-file,,
Writing to Files}.
@end defmac
@node Buffer Names
@section Buffer Names
@ -292,8 +298,7 @@ foo
@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, or if there is already a
buffer with that name. The function returns @var{newname}.
is signaled if @var{newname} is not a string.
@c Emacs 19 feature
Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
@ -301,6 +306,8 @@ 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
@ -329,11 +336,12 @@ 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 &rest ignore
@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{}>}.
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; it makes a difference if it is a name in the
@ -403,9 +411,11 @@ Emacs.
@end defvar
@defvar buffer-file-truename
This buffer-local variable holds the 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}.
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
@ -419,6 +429,9 @@ The value is normally a list of the form @code{(@var{filenum}
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
@ -426,7 +439,9 @@ 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.
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
@ -440,25 +455,50 @@ 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.
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.
the buffer as having no visited file, without changing the buffer's
modified flag.
Normally, this function asks the user for confirmation if the specified
file already exists. If @var{no-query} is non-@code{nil}, that prevents
asking this question.
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}.
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
@ -514,10 +554,16 @@ function @code{force-mode-line-update} works by doing this:
@end example
@end defun
@deffn Command not-modified
This command marks the current buffer as unmodified, and not needing to
be saved. With prefix arg, it marks the buffer as modified, so that it
will be saved at the next suitable occasion.
@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.
@ -528,6 +574,7 @@ echo area; use @code{set-buffer-modified-p} (above) instead.
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
@node Modification Time
@ -552,6 +599,16 @@ 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
@ -567,10 +624,30 @@ file should not be done.
@c Emacs 19 feature
@defun visited-file-modtime
This function returns the 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}.)
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}.)
The function returns zero if the buffer has no recorded last
modification time, which can happen, for instance, if the record has
been explicitly cleared by @code{clear-visited-file-modtime} or if the
buffer is not visiting a file. Note, however, that
@code{visited-file-modtime} can return a non-zero value for some
buffers that are not visiting files, but are nevertheless closely
associated with a file. This happens, for instance, with dired
buffers listing a directory. For such buffers,
@code{visited-file-modtime} 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
@ -580,7 +657,7 @@ 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 not @code{nil}, it should have the form
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.
@ -646,12 +723,13 @@ 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 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 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
@ -659,17 +737,22 @@ properties have no effect. If @code{inhibit-read-only} is a list, then
of the list (comparison is done with @code{eq}).
@end defvar
@deffn Command toggle-read-only
This command changes whether the current buffer is read-only. It is
@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{Interactive Call}, for another way to
buffer is read-only. @xref{Using Interactive}, for another way to
signal an error if the current buffer is read-only.
@end defun
@ -807,12 +890,14 @@ buffer and gives it a unique name.
subprocess can also create a buffer (@pxref{Processes}).
@defun get-buffer-create name
This function returns a buffer named @var{name}. It returns an existing
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.
An error is signaled if @var{name} is not a string.
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
@ -821,8 +906,8 @@ An error is signaled if @var{name} is not a string.
@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.
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.
@xref{Auto Major Mode}.
@end defun
@ -896,8 +981,8 @@ this feature to test whether a buffer has been killed:
@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. It
returns @code{nil}.
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.
@ -912,16 +997,20 @@ for confirmation, clear the modified flag before calling
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{} nil
@result{} t
(kill-buffer "foo.changed")
---------- Buffer: Minibuffer ----------
Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
---------- Buffer: Minibuffer ----------
@result{} nil
@result{} t
@end smallexample
@end deffn
@ -944,12 +1033,19 @@ is not cleared by changing major modes.
@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} to offer to
save that buffer, just as they offer to save file-visiting buffers. The
variable @code{buffer-offer-save} automatically becomes buffer-local
when set for any reason. @xref{Buffer-Local Variables}.
@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
@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
@ -980,19 +1076,29 @@ buffer.
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
This creates an indirect buffer named @var{name} whose base buffer
is @var{base-buffer}. The argument @var{base-buffer} may be a buffer
or a string.
@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.
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 buffer-base-buffer buffer
This function returns the base buffer of @var{buffer}. If @var{buffer}
is not indirect, the value is @code{nil}. Otherwise, the value is
another buffer, which is never an indirect buffer.
@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
@ -1018,3 +1124,7 @@ This function returns the current gap position in the current buffer.
@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

14
lispref/calendar.texi
View file

@ -255,12 +255,12 @@ occur on the first Tuesday after the first Monday in November of years
divisible by 4:
@smallexample
(holiday-sexp (if (= 0 (% year 4))
(holiday-sexp '(if (= 0 (% year 4))
(calendar-gregorian-from-absolute
(1+ (calendar-dayname-on-or-before
1 (+ 6 (calendar-absolute-from-gregorian
(list 11 1 year))))))
"US Presidential Election"))
(list 11 1 year)))))))
"US Presidential Election")
@end smallexample
@noindent
@ -967,7 +967,7 @@ how far in advance it begins doing so, by setting these variables:
@table @code
@item appt-message-warning-time
The time in minutes before an appointment that the reminder begins. The
default is 10 minutes.
default is 12 minutes.
@item appt-audible
If this is non-@code{nil}, Emacs rings the
terminal bell for appointment reminders. The default is @code{t}.
@ -988,5 +988,9 @@ This variable holds a function to use to get rid of the appointment
message window, when its time is up.
@item appt-display-duration
The number of seconds to display an appointment message. The default
is 5 seconds.
is 10 seconds.
@end table
@ignore
arch-tag: 8e50c766-4703-4888-a421-af15244cca7e
@end ignore

263
lispref/commands.texi
View file

@ -239,9 +239,8 @@ This function returns the @code{interactive} form of @var{function}. If
@var{function} is a command (@pxref{Interactive Call}), the value is a
list of the form @code{(interactive @var{spec})}, where @var{spec} is
the descriptor specification used by the command's @code{interactive}
form to compute the function's arguments (@pxref{Using Interactive}).
If @var{function} is not a command, @code{interactive-form} returns
@code{nil}.
form to compute the function's arguments. If @var{function} is not a
command, @code{interactive-form} returns @code{nil}.
@end defun
@node Interactive Codes
@ -328,7 +327,7 @@ 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{System Environment}).
current buffer, @code{default-directory} (@pxref{File Name Expansion}).
Existing, Completion, Default, Prompt.
@item e
@ -340,7 +339,7 @@ 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 @sc{ascii} characters, do not count where @samp{e} is concerned.
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
@ -503,7 +502,7 @@ 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
@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}.
@ -514,11 +513,13 @@ 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}.
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}).
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}.
@ -661,6 +662,10 @@ non-@code{nil}. Here's how:
(message "foo")))
@end example
@noindent
Defined in this way, the function does display the message when
called from a keyboard macro.
The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
@node Command Loop Info
@ -727,6 +732,14 @@ 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
@ -783,7 +796,7 @@ last-command-event
@end example
@noindent
The value is 5 because that is the @sc{ascii} code for @kbd{C-e}.
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.
@ -902,14 +915,14 @@ The
@ifnottex
2**26
@end ifnottex
bit in the character code indicates a non-@sc{ascii}
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 @sc{ascii}, such as
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
@ -918,7 +931,7 @@ for @kbd{%} plus
@ifnottex
2**26
@end ifnottex
(assuming the terminal supports non-@sc{ascii}
(assuming the terminal supports non-@acronym{ASCII}
control characters).
@item shift
@ -929,13 +942,13 @@ The
@ifnottex
2**25
@end ifnottex
bit in the character code indicates an @sc{ascii} control
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
@sc{ascii} character set whenever possible, Emacs avoids using the
@acronym{ASCII} character set whenever possible, Emacs avoids using the
@tex
@math{2^{25}}
@end tex
@ -944,7 +957,7 @@ character with a different basic code. In order to keep within the
@end ifnottex
bit for those characters.
However, @sc{ascii} provides no way to distinguish @kbd{C-A} from
However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
@tex
@math{2^{25}}
@ -1018,10 +1031,10 @@ function keys:
@table @asis
@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
These keys correspond to common @sc{ascii} control characters that have
These keys correspond to common @acronym{ASCII} control characters that have
special keys on most keyboards.
In @sc{ascii}, @kbd{C-i} and @key{TAB} are the same character. If the
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}.
@ -1033,7 +1046,7 @@ 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 @sc{ascii}, @key{BS} is really @kbd{C-h}. But @code{backspace}
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.
@ -1105,27 +1118,13 @@ binding of the key sequence.
@cindex mouse click event
When the user presses a mouse button and releases it at the same
location, that generates a @dfn{click} event. Mouse click events have
this form:
location, that generates a @dfn{click} event. All mouse click event
share the same format:
@example
(@var{event-type}
(@var{window} @var{buffer-pos} (@var{x} . @var{y})
@var{timestamp})
@var{click-count})
(@var{event-type} @var{position} @var{click-count})
@end example
or, for clicks on strings in the mode line, header line or marginal
areas:
@example
(@var{event-type}
(@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp} (@var{string} . @var{string-pos})
@var{click-count})
@end example
Here is what the elements normally mean:
@table @asis
@item @var{event-type}
This is a symbol that indicates which mouse button was used. It is
@ -1141,21 +1140,50 @@ 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. The various formats are described below.
@item @var{click-count}
This is the number of rapid repeated presses so far of the same mouse
button. @xref{Repeat Events}.
@end table
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}.
@item @var{x}, @var{y}
These are the pixel-denominated coordinates of the click, relative to
the top left corner of @var{window}, which is @code{(0 . 0)}.
@item @var{buffer-pos}
This is the buffer position of the character clicked on.
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. (Since
this value wraps around the entire range of Emacs Lisp integers in about
five hours, it is useful only for relating the times of nearby
events.)
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.
@item @var{string}
This is the string on which the click occurred, including any
@ -1165,29 +1193,58 @@ properties.
This is the position in the string on which the click occurred,
relevant if properties at the click need to be looked up.
@item @var{click-count}
This is the number of rapid repeated presses so far of the same mouse
button. @xref{Repeat Events}.
@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-denominated 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.
@end table
The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat
different when the event location is in a special part of the screen,
such as the mode line or a scroll bar.
For mouse clicks on a scroll-bar, @var{position} has this form:
If the location is in a scroll bar, then @var{buffer-pos} is the symbol
@code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair
@code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion}
. @var{whole})}, where @var{portion} is the distance of the click from
the top or left end of the scroll bar, and @var{whole} is the length of
the entire scroll bar.
@example
(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
@end example
If the position is on a mode line, the vertical line separating
@var{window} from its neighbor to the right, or in a marginal area,
then @var{buffer-pos} is the symbol @code{mode-line},
@code{header-line}, @code{vertical-line}, @code{left-margin}, or
@code{right-margin}. For the mode line, @var{y} does not have
meaningful data. For the vertical line, @var{x} does not have
meaningful data.
@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
In one special case, @var{buffer-pos} is a list containing a symbol (one
of the symbols listed above) instead of just the symbol. This happens
@ -1615,7 +1672,9 @@ a mouse button or motion event.
mouse-button event, as a list of this form:
@example
(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
(@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
@ -1636,15 +1695,24 @@ position such events have.
@end defun
@cindex mouse position list, accessing
These five functions take a position list as described above, and
These seven 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 the event occurred.
@end defun
@defun posn-point position
Return the buffer position in @var{position}. This is an integer.
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
@ -1653,15 +1721,54 @@ cell @code{(@var{x} . @var{y})}.
@end defun
@defun posn-col-row position
Return the row and column (in units of characters) 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}.
Return the row and column (in units of frame default characters) 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. Return
@code{nil} if @var{position} does not include the actual positions; in that
case, @code{posn-col-row} can be used 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 mouse event, timestamp
@cindex timestamp of a mouse event
@defun posn-timestamp position
Return the timestamp in @var{position}.
@defun posn-timestamp
Return the timestamp in @var{position}. This is the time at which the
event occurred, in milliseconds.
@end defun
These functions are useful for decoding scroll bar events.
@ -1796,7 +1903,7 @@ bit, resulting in a value between 128 and 255. Only a unibyte string
can include these codes.
@item
Non-@sc{ascii} characters above 256 can be included in a multibyte string.
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
@ -1965,7 +2072,7 @@ 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-@sc{ascii} character. Otherwise, input method handling is disabled
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}
@ -1995,7 +2102,7 @@ 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} (@sc{ascii}
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
@ -2041,7 +2148,7 @@ calls that function, passing the character as an argument.
If this is non-@code{nil}, its value specifies the current input method
function.
@strong{Note:} Don't bind this variable with @code{let}. It is often
@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
@ -2175,7 +2282,7 @@ 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},
@sc{ascii} code 49. It becomes the value of @code{last-input-event},
@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}.
@ -2819,3 +2926,7 @@ 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

103
lispref/compile.texi
View file

@ -173,14 +173,18 @@ variable names and function names used by the function, except for
certain primitives that are coded as special instructions.
@end defun
@deffn Command compile-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
@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
@ -193,8 +197,11 @@ 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}. When called interactively, it prompts
for the file name.
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
@ -215,20 +222,28 @@ for the file name.
@end example
@end deffn
@deffn Command byte-recompile-directory directory flag
@deffn Command byte-recompile-directory directory &optional flag force
@cindex library compilation
This function recompiles every @samp{.el} file in @var{directory} that
needs recompilation. A file needs recompilation if a @samp{.elc} file
exists but is older than the @samp{.el} file.
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}, these files are ignored. If it
is non-@code{nil}, the user is asked whether to compile each such 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.
The returned value of this command is unpredictable.
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
@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
@ -236,6 +251,9 @@ 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
@ -420,7 +438,45 @@ these messages.
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 a
@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}:
@defmac with-no-warnings body...
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 defmac
@node Byte-Code Objects
@section Byte-Code Function Objects
@cindex compiled function
@ -513,14 +569,16 @@ returns it as the value of the function.
ordinary Lisp variables, by transferring values between variables and
the stack.
@deffn Command disassemble object &optional stream
This function prints the disassembled code for @var{object}. If
@var{stream} is supplied, then output goes there. Otherwise, the
disassembled code is printed to the stream @code{standard-output}. The
argument @var{object} can be a function name or a lambda expression.
@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.
As a special exception, if this function is used interactively,
it outputs to a buffer named @samp{*Disassemble*}.
The argument @var{object} can be a function name, a lambda expression
or a byte-code object.
@end deffn
Here are two examples of using the @code{disassemble} function. We
@ -766,3 +824,6 @@ The @code{silly-loop} function is somewhat more complex:
@end example
@ignore
arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289
@end ignore

4
lispref/configure.in
View file

@ -1,3 +1,7 @@
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

92
lispref/control.texi
View file

@ -496,7 +496,7 @@ This construct executes @var{body} once for each integer from 0
(inclusive) to @var{count} (exclusive), using the variable @var{var} to
hold 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} do something 100 times:
Here is an example of using @code{dotimes} to do something 100 times:
@example
(dotimes (i 100)
@ -757,7 +757,7 @@ 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{String Conversion}) to
applying @code{format} (@pxref{Formatting Strings}) to
@var{format-string} and @var{args}.
These examples show typical uses of @code{error}:
@ -784,6 +784,7 @@ contains @samp{%}, it will be interpreted as a format specifier, with
undesirable results. Instead, use @code{(error "%s" @var{string})}.
@end defun
@anchor{Definition of signal}
@defun signal error-symbol data
This function signals an error named by @var{error-symbol}. The
argument @var{data} is a list of additional Lisp objects relevant to the
@ -792,19 +793,26 @@ 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.
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.
@xref{Error Symbols}, for a description of error symbols.
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}). If the error is not handled,
these two values are used in printing the error message.
@var{data})} (@pxref{Handling Errors}).
The function @code{signal} never returns (though in older Emacs versions
it could sometimes return).
@ -989,7 +997,7 @@ error symbol and associated data are not available to the handler.
@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.
usual error message for that error. @xref{Definition of signal}.
@end defun
@cindex @code{arith-error} example
@ -1071,10 +1079,10 @@ 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. 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.
@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.
@ -1082,13 +1090,16 @@ 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.
@cindex peculiar error
message @samp{peculiar error} is used. @xref{Definition of signal}.
Here is how we define a new error symbol, @code{new-error}:
@ -1114,8 +1125,8 @@ classification; and @code{error}, which is the widest of all.
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{Signaling Errors}) in your
code can do this:
an explicit call to @code{signal} (@pxref{Definition of signal}) in
your code can do this:
@example
@group
@ -1158,32 +1169,34 @@ and their conditions.
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.
@defspec unwind-protect body cleanup-forms@dots{}
@defspec unwind-protect body-form cleanup-forms@dots{}
@cindex cleanup forms
@cindex protected forms
@cindex error cleanup
@cindex unwinding
@code{unwind-protect} executes the @var{body} with a guarantee that the
@var{cleanup-forms} will be evaluated if control leaves @var{body}, no
matter how that happens. The @var{body} 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.
@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 the @var{body} forms finish normally, @code{unwind-protect} returns
the value of the last @var{body} form, after it evaluates the
@var{cleanup-forms}. If the @var{body} forms do not finish,
@code{unwind-protect} does not return any value in the normal sense.
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 the @var{body} is protected by the @code{unwind-protect}. If any
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.
@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{Local Variables}).
@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
@ -1195,7 +1208,7 @@ make sure to kill it before finishing:
(let ((buffer (get-buffer-create " *temp*")))
(set-buffer buffer)
(unwind-protect
@var{body}
@var{body-form}
(kill-buffer buffer))))
@end group
@end smallexample
@ -1203,15 +1216,16 @@ make sure to kill it before finishing:
@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} happens to get an
error after switching to a different buffer! (Alternatively, you could
write another @code{save-excursion} around the body, to ensure that the
temporary buffer becomes current again in time to kill it.)
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{Current Buffer}).
Several of the macros defined in this manual use @code{unwind-protect}
in this way.
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
@ -1240,3 +1254,7 @@ 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

84
lispref/customize.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
@ -62,7 +62,7 @@ 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 @sc{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}.
@item (emacs-commentary-link @var{library})
@ -373,6 +373,7 @@ equivalent to @code{(string)}.
* Composite Types::
* Splicing into Lists::
* Type Keywords::
* Defining New Types::
@end menu
All customization types are implemented as widgets; see @ref{Top, ,
@ -584,7 +585,7 @@ The value must be a coding-system name, and you can do completion with
@item color
The value must be a valid color name, and you can do completion with
@kbd{M-@key{TAB}}. A sample is provided,
@kbd{M-@key{TAB}}. A sample is provided.
@end table
@node Composite Types
@ -975,7 +976,8 @@ 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 as for @code{help-echo} text properties.
to yield a help string. If it is a function, it is called with one
argument, the widget.
@c @xref{Text help-echo}.
@item :match @var{function}
@ -1054,3 +1056,77 @@ 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 once, and use that name each @code{defcustom}. The other case is
when a user option accept a recursive datastructure. 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 name @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 accept 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 follows the keyword arguments. The most
important is @code{:type}, which describes the datatype 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 are there to ensure that child nodes are
indented four spaces relatively 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.
If you wonder about the name @code{lazy}, know 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
datastructure is itself recursive, this conversion will go on forever,
or at least until Emacs run out of stack space. The @code{lazy} widget
stop this recursion, it will only convert its @code{:type} argument when
needed.
@ignore
arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
@end ignore

51
lispref/debugging.texi
View file

@ -30,6 +30,7 @@ compiler, you need to know how to examine the compiler's input buffer.
* 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
@ -215,10 +216,10 @@ When @code{debug-on-entry} is called interactively, it prompts for
up to invoke the debugger on entry, @code{debug-on-entry} does nothing.
@code{debug-on-entry} always returns @var{function-name}.
@strong{Note:} 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.
@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.
@example
@group
@ -550,7 +551,7 @@ forms are elided.
(1+ var)
(list 'testing (backtrace))))))))
@result{} nil
@result{} (testing nil)
@end group
@group
@ -738,6 +739,42 @@ 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 first using
the command @kbd{M-x testcover-start @key{RET} @var{file} @key{RET}}
to instrument it. Then test your code by calling it one or more
times. Then use the command @kbd{M-x testcover-mark-all} to display
``splotches'' on the code to show where coverage is insufficient. The
command @kbd{M-x testcover-next-mark} will move point forward to the
next spot that has a splotch.
Normally, a red splotch indicates the form was never completely
evaluated; a brown splotch means it always evaluated to the same value
(meaning there has been little testing of what is done with the
result). However, the red splotch is skipped for forms that can't
possibly complete their evaluation, such as @code{error}. The brown
splotch 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
@node Compilation Errors
@section Debugging Problems in Compilation
@ -762,3 +799,7 @@ the error.
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

860
lispref/display.texi
View file

File diff suppressed because it is too large Load diff

4
lispref/doclicense.texi
View file

@ -366,3 +366,7 @@ 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

48
lispref/edebug.texi
View file

@ -124,7 +124,7 @@ Here we use periods to show the stop points in the function
@example
(defun fac (n)
.(if .(< 0 n.).
.(* n. .(fac (1- n.).).).
.(* n. .(fac .(1- n.).).).
1).)
@end example
@ -257,7 +257,8 @@ Next: stop at the next stop point encountered after an expression
@ref{Edebug Misc}.
@item t
Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}).
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
@ -307,6 +308,10 @@ 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
@ -871,8 +876,12 @@ performed for all execution of an instrumented function, even if the
execution mode is Go-nonstop, and regardless of whether coverage testing
is enabled.
Use @kbd{M-x edebug-display-freq-count} to display both the
coverage information and the frequency counts for a definition.
@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
@ -1077,15 +1086,14 @@ For example, (for i from 1 to 10 do (print i))."
...)
@end example
@defspec declare (edebug @var{specification})
Specify which expressions of a call to the macro in which the
declaration appears 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.
@end defspec
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
You can also define an edebug specification for a macro separately
from the macro definition with @code{def-edebug-spec}. Adding
@code{edebug} declarations is preferred, and more convenient, for
macro definitions in Lisp, but @code{def-edebug-spec} makes it
@ -1185,7 +1193,7 @@ either way.
A lambda expression with no quoting.
@item &optional
@kindex &optional @r{(Edebug)}
@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.
@ -1195,7 +1203,7 @@ elements must all match or none, use @code{&optional
[@var{specs}@dots{}]}. See the @code{defun} example below.
@item &rest
@kindex &rest @r{(Edebug)}
@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
@ -1206,7 +1214,7 @@ To specify several elements that must all match on every repetition, use
@code{&rest [@var{specs}@dots{}]}.
@item &or
@kindex &or @r{(Edebug)}
@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.
@ -1216,14 +1224,14 @@ group two or more list elements as a single alternative, enclose them in
@code{[@dots{}]}.
@item &not
@kindex &not @r{(Edebug)}
@c @kindex &not @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{&not} specification
succeeds.
@item &define
@kindex &define @r{(Edebug)}
@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
@ -1373,7 +1381,7 @@ 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 bactracking is
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
@ -1554,3 +1562,7 @@ 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

4
lispref/elisp-covers.texi
View file

@ -246,3 +246,7 @@
@end titlepage
@bye
@ignore
arch-tag: 02d65d63-3b64-49bc-a5c0-bfd5eabb6c98
@end ignore

24
lispref/elisp.texi
View file

@ -415,6 +415,7 @@ Macros
* 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.
Loading
@ -534,6 +535,7 @@ Keymaps
* Key Lookup:: How extracting elements from keymaps works.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
* Remapping Commands:: Bindings that translate one command to another.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
@ -738,12 +740,16 @@ Text
* Transposition:: Swapping two portions of a buffer.
* Registers:: How registers are implemented. Accessing
the text or position stored in a register.
* Atomic Changes:: Installing several buffer changes ``atomically''.
* Base 64:: Conversion to or from base 64 encoding.
* MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''.
* 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.
@ -852,6 +858,7 @@ 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.
Operating System Interface
@ -882,12 +889,21 @@ Emacs Display
* Refresh Screen:: Clearing the screen and redrawing everything on it.
* Truncation:: Folding or wrapping long text lines.
* The Echo Area:: Where messages are displayed.
* Warnings:: Displaying warning messages for the user.
* Selective Display:: Hiding part of the buffer text.
* Overlay Arrow:: Display of an arrow to indicate position.
* Temporary Displays:: Displays that go away automatically.
* Waiting:: Forcing display update and waiting for user.
* Overlays:: Use overlays to highlight parts of the buffer.
* Width:: How wide a character or string is on the screen.
* Faces:: A face defines a graphics style
for text characters: font, colors, etc.
* Fringes:: Controlling window fringes.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Blinking:: How Emacs shows the matching open parenthesis.
* Usual Display:: How control characters are displayed.
* Inverse Video:: Specifying how the screen looks.
* 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.
@ -988,3 +1004,7 @@ Object Internals
These words prevent "local variables" above from confusing Emacs.
@ignore
arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34
@end ignore

28
lispref/errors.texi
View file

@ -62,6 +62,10 @@ See @code{/} and @code{%} in @ref{Numbers}.
@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{Motion}.
@ -69,7 +73,7 @@ See @code{/} and @code{%} in @ref{Numbers}.
@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.
because it pertains to the Lisp reader, not to file I/O.@*
@xref{Input Functions}.
@item file-already-exists
@ -79,12 +83,16 @@ This is a subcategory of @code{file-error}.@*
@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}.
the output file.@*
@xref{Changing Files}.
@item file-error
This error and its subcategories do not have error-strings, because the
error message is constructed from the data items alone when the error
condition @code{file-error} is present.@*
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
@ -113,7 +121,7 @@ in accessing a remote file using ftp.@*
@xref{Regular Expressions}.
@item mark-inactive
@code{"Mark inactive"}@*
@code{"The mark is not active now"}@*
@xref{The Mark}.
@item no-catch
@ -139,6 +147,7 @@ may not be changed.@*
@item text-read-only
@code{"Text is read-only"}@*
This is a subcategory of @code{buffer-read-only}.@*
@xref{Special Properties}.
@item undefined-color
@ -173,6 +182,7 @@ mathematical functions.
@item overflow-error
@code{"Arithmetic overflow error"}@*
This is a subcategory of @code{domain-error}.@*
@xref{Math Functions}.
@item range-error
@ -181,9 +191,15 @@ mathematical 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

71
lispref/eval.texi
View file

@ -313,12 +313,17 @@ symbol function indirection when calling @code{erste}.
perform symbol function indirection explicitly.
@c Emacs 19 feature
@anchor{Definition of indirect-function}
@defun indirect-function 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 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
@ -588,11 +593,11 @@ property list. On these occasions, use the @code{eval} function.
specify limits to the evaluation process, or record recently returned
values. Loading a file also does evaluation (@pxref{Loading}).
@strong{Note:} 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.
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
@ -625,32 +630,51 @@ The number of currently active calls to @code{eval} is limited to
@code{max-lisp-eval-depth} (see below).
@end defun
@anchor{Definition of eval-region}
@deffn Command eval-region start end &optional stream read-function
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.
If @var{stream} is non-@code{nil}, the values that result from
evaluating the expressions in the region are printed using @var{stream}.
@xref{Output Streams}.
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{How Programs
Do Loading}) to specify this function, but it is more robust to use the
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} always returns @code{nil}.
@code{eval-region} does not move point. It always returns @code{nil}.
@end deffn
@cindex evaluation of buffer contents
@deffn Command eval-current-buffer &optional stream
This is like @code{eval-region} except that it operates on the whole
buffer.
@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
@anchor{Definition of max-lisp-eval-depth}
@defvar 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
@ -670,14 +694,17 @@ 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{Local Variables}.
@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.
The elements are ordered most recent first.
(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
@ -719,3 +746,7 @@ particular elements, like this:
@end group
@end example
@end defvar
@ignore
arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
@end ignore

436
lispref/files.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/files
@ -95,11 +95,11 @@ 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.
The body of the @code{find-file} function is very simple and looks
like this:
Aside from some technical details, the body of the @code{find-file}
function is basically equivalent to:
@example
(switch-to-buffer (find-file-noselect filename))
(switch-to-buffer (find-file-noselect filename nil nil wildcards))
@end example
@noindent
@ -193,12 +193,14 @@ When @code{view-file} is called interactively, it prompts for
@end deffn
@tindex find-file-wildcards
@defvar find-file-wildcards
@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. If this is @code{nil}, then wildcard characters are
not treated specially.
@end defvar
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
@ -206,8 +208,7 @@ 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 works just like a normal hook, but we think that renaming
it would not be advisable. @xref{Hooks}.
This variable is a normal hook. @xref{Hooks}.
@end defvar
@defvar find-file-not-found-functions
@ -322,16 +323,21 @@ backed up when the buffer is next saved.
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
@anchor{Definition of save-some-buffers}
@deffn Command save-some-buffers &optional save-silently-p pred
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.
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
@ -346,6 +352,7 @@ 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
@anchor{Definition of write-file}
@deffn Command write-file filename &optional confirm
This function writes the current buffer into file @var{filename}, makes
the buffer visit that file, and marks it not modified. Then it renames
@ -355,7 +362,13 @@ 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.
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
@ -378,8 +391,9 @@ To do so, execute the following code:
@end example
You might wish to save the file modes value returned by
@code{backup-buffer} and use that to set the mode bits of the file that
you write. This is what @code{save-buffer} normally does.
@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
@ -404,20 +418,31 @@ Even though this is not a normal hook, you can use @code{add-hook} and
This works just like @code{write-file-functions}, but it is intended for
hooks that pertain to the contents of the file, as opposed to hooks that
pertain to where the file came from. Such hooks are usually set up by
major modes, as buffer-local bindings for this variable.
major modes, as buffer-local bindings for this variable. If any of the
functions in this hook returns non-@code{nil}, @code{write-file-functions}
is not run.
This variable automatically becomes buffer-local whenever it is set;
switching to a new major mode always resets this variable.
switching to a new major mode always resets this variable, but
calling @code{set-visited-file-name} does not.
@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
@defvar after-save-hook
@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 defvar
@end defopt
@defvar file-precious-flag
@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
@ -431,7 +456,7 @@ 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 defvar
@end defopt
@defopt require-final-newline
This variable determines whether files may be written out that do
@ -530,12 +555,22 @@ 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
@ -590,6 +625,7 @@ feature is useful for programs that use files for internal purposes,
files that the user does not need to know about.
@end deffn
@anchor{Definition of with-temp-file}
@defmac with-temp-file file body...
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
@ -601,7 +637,8 @@ 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{Current Buffer}.
See also @code{with-temp-buffer} in @ref{Definition of
with-temp-buffer,, The Current Buffer}.
@end defmac
@node File Locks
@ -714,7 +751,10 @@ or directories unless otherwise noted.
@cindex accessibility of a file
@cindex file accessibility
These functions test for permission to access a file in specific ways.
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
@ -818,7 +858,13 @@ using @var{string} as the error message text.
@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.
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
@ -826,8 +872,8 @@ then creating it anew would keep the file's owner unchanged.
@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{filename2} does not exist,
it returns @code{t}.
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
@ -866,9 +912,10 @@ 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 link target as a string.
(Determining the file name that the link points to from the target is
nontrivial.)
@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}.
@ -895,6 +942,9 @@ If the file @var{filename} is not a symbolic link (or there is no such file),
@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.
@ -946,14 +996,31 @@ 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. If you specify a number for
@var{limit}, then after chasing through that many links, the function
just returns what it as even if that is still 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
@ -993,9 +1060,13 @@ 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 @sc{suid} bit
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")
@ -1023,6 +1094,11 @@ is set for both others and group, and that the sticky bit is set.
@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
@ -1048,9 +1124,16 @@ link to.
@end example
@end defun
@defun file-attributes filename
@anchor{Definition of file-attributes}
@defun file-attributes filename &optional id-format
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:
@ -1066,10 +1149,11 @@ links, can be created by using the @code{add-name-to-file} function
(@pxref{Changing Files}).
@item
The file's @sc{uid}.
The file's @acronym{UID} as a string or an integer. If a string
value cannot be looked up, the integer value is returned.
@item
The file's @sc{gid}.
The file's @acronym{GID} likewise.
@item
The time of last access, as a list of two integers.
@ -1092,7 +1176,7 @@ The file's modes, as a string of ten letters or dashes,
as in @samp{ls -l}.
@item
@code{t} if the file's @sc{gid} would change if file were
@code{t} if the file's @acronym{GID} would change if file were
deleted and recreated; @code{nil} otherwise.
@item
@ -1114,8 +1198,8 @@ For example, here are the file attributes for @file{files.texi}:
@example
@group
(file-attributes "files.texi")
@result{} (nil 1 2235 75
(file-attributes "files.texi" 'string)
@result{} (nil 1 "lh" "users"
(8489 20284)
(8489 20284)
(8489 20285)
@ -1135,11 +1219,11 @@ is neither a directory nor a symbolic link.
has only one name (the name @file{files.texi} in the current default
directory).
@item 2235
is owned by the user with @sc{uid} 2235.
@item "lh"
is owned by the user with name "lh".
@item 75
is in the group with @sc{gid} 75.
@item "users"
is in the group with name "users".
@item (8489 20284)
was last accessed on Aug 19 00:09.
@ -1158,7 +1242,7 @@ if some of the bytes belong to multibyte sequences.)
has a mode of read and write access for the owner, group, and world.
@item nil
would retain the same @sc{gid} if it were recreated.
would retain the same @acronym{GID} if it were recreated.
@item 129500
has an inode number of 129500.
@ -1195,7 +1279,12 @@ Replace the old file without confirmation if @var{ok-if-already-exists}
is any other value.
@end itemize
@defun add-name-to-file oldname newname &optional ok-if-already-exists
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
@ -1261,7 +1350,7 @@ 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 defun
@end deffn
@deffn Command rename-file filename newname &optional ok-if-already-exists
This command renames the file @var{filename} as @var{newname}.
@ -1270,10 +1359,6 @@ 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.
In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@var{newname} already exists.
@end deffn
@deffn Command copy-file oldname newname &optional ok-if-exists time
@ -1289,9 +1374,19 @@ some operating systems.) If setting the time gets an error,
This function copies the file modes, too.
In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@var{newname} already exists.
In an interactive call, a prefix argument specifies a non-@code{nil}
value for @var{time}.
@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
@ -1304,32 +1399,23 @@ 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
@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}}.
In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@var{newname} already exists.
This function is not available on systems that don't support symbolic
links.
@end deffn
@defun define-logical-name varname string
This function defines the logical name @var{name} to have the value
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 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
@ -1482,18 +1568,6 @@ This function returns the nondirectory part of @var{filename}.
@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. It returns @code{nil} for extensionless file
names such as @file{foo}. 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{""}. If the last
component of a file name begins with a @samp{.}, that @samp{.} doesn't
count as the beginning of an extension, so, for example,
@file{.emacs}'s ``extension'' is @code{nil}, not @samp{.emacs}.
@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.
@ -1523,11 +1597,29 @@ return value, but backup version numbers are kept.
@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 extension, in a file name, is the part that starts with the last
@samp{.} in the last name component, except if that @samp{.} is the
first character of the file name's last component. For example,
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")
@ -1538,7 +1630,14 @@ first character of the file name's last component. For example,
@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
@ -1605,9 +1704,9 @@ 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 (or
backslash), whereas the directory's name as a file lacks that slash.
On MSDOS and VMS, the relationship is more complicated.
Unix systems, this is simple: a directory name ends in a slash,
whereas the directory's name as a file lacks that slash. On MSDOS 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
@ -1617,7 +1716,7 @@ 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{~}, and @samp{..}.
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
@ -1695,7 +1794,9 @@ 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 function @code{abbreviate-file-name} performs these substitutions.
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.
@ -1714,6 +1815,7 @@ and so on.
To convert a directory name to its abbreviation, use this
function:
@anchor{Definition of abbreviate-file-name}
@defun abbreviate-file-name filename
This function applies abbreviations from @code{directory-abbrev-alist}
to its argument, and substitutes @samp{~} for the user's home
@ -1731,6 +1833,9 @@ 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}/../}.
In the next two functions, the @var{directory} argument can be either
a directory name or a directory file name. @xref{Directory Names}.
@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
@ -1758,6 +1863,12 @@ used. For example:
@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:
@ -1770,6 +1881,27 @@ canonical form:
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
@c Emacs 19 feature
@ -1811,8 +1943,9 @@ default-directory
@end example
@end defvar
@anchor{Definition of substitute-in-file-name}
@defun substitute-in-file-name filename
This function replaces environment variables references in
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
@ -1844,8 +1977,9 @@ the user's home directory name, has value @samp{/xcssun/users/rms}.
@end group
@end example
After substitution, if a @samp{~} or a @samp{/} appears following a
@samp{/}, everything before the following @samp{/} is discarded:
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
@ -1877,7 +2011,7 @@ construct a name for such a file, starting in Emacs 21:
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
@defun make-temp-file prefix &optional dir-flag suffix
@tindex make-temp-file
This function creates a temporary file and returns its name.
The name starts with @var{prefix}; it also contains a number that is
@ -1895,8 +2029,12 @@ 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.
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
@ -1926,9 +2064,10 @@ you should use @code{make-temp-name} instead:
This function generates a string that can be used as a unique file name.
The name starts with @var{string}, and contains a number that is
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. On MS-DOS,
the @var{string} prefix can be truncated to fit into the 8+3 file-name
limits.
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
@ -1946,11 +2085,11 @@ 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-name} to choose the temporary
file's name, 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}.
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
@tindex small-temporary-file-directory
@ -2048,8 +2187,8 @@ has five files whose names begin with @samp{f}: @file{foo},
@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 or when a buffer showing all
possible completions is displayed.@refill
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:
@ -2158,9 +2297,20 @@ 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}.
@var{file} in directory @var{dirname}. It is only available on VMS.
@end defun
@tindex file-expand-wildcards
@ -2181,6 +2331,8 @@ normally also relative to the current default directory. However, if
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
@ -2202,6 +2354,12 @@ If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
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
@ -2221,8 +2379,9 @@ delete directories.
@defun make-directory dirname &optional parents
This function creates a directory named @var{dirname}.
If @var{parents} is non-@code{nil}, that means to create
the parent directories first, if they don't already exist.
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
@ -2230,6 +2389,9 @@ 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
@ -2261,10 +2423,10 @@ 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;
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:
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})
@ -2434,7 +2596,7 @@ 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 specal for actual access to the
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
@ -2461,15 +2623,22 @@ for comparison with @code{inhibit-file-name-operation}.
@end defun
@defun file-local-copy filename
This function copies file @var{filename} to an ordinary non-magic file,
if it isn't one already.
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} specifies a magic file name, which programs
outside Emacs cannot directly read or write, this copies the contents to
an ordinary file and returns that file's name.
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
If @var{filename} is an ordinary file name, not magic, then this function
does nothing and returns @code{nil}.
@defun file-remote-p filename
This function returns @code{t} if @var{filename} is a remote file---that is,
a magic file name that handles @code{file-local-copy}.
@end defun
@defun unhandled-file-name-directory filename
@ -2598,11 +2767,14 @@ 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
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.
@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
@ -2634,6 +2806,12 @@ The argument @var{format} is a list of format names. If @var{format} is
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. This variable is
always buffer-local in all buffers.
@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
@ignore
arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
@end ignore

186
lispref/frames.texi
View file

@ -56,7 +56,7 @@ The frame is displayed on an MS-DOS terminal.
* 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 them.
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.
@ -212,9 +212,10 @@ of @var{frame}. If @var{frame} is @code{nil}, it returns the
selected frame's parameter.
@end defun
@defun frame-parameters frame
@defun frame-parameters &optional frame
The function @code{frame-parameters} returns an alist listing all the
parameters of @var{frame} and their values.
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
@ -222,7 +223,15 @@ 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.
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}
to apply the same parameter values to frames that will be created
henceforth.
@end defun
@node Initial Parameters
@ -423,13 +432,6 @@ considers that buffer.
A list of buffers that have been selected in this frame,
ordered most-recently-selected first.
@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}). Changing this frame parameter on a frame
also changes the font-related attributes of the default face on that
frame.
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
@ -447,7 +449,8 @@ Whether the frame has scroll bars for horizontal scrolling
implemented.)
@item scroll-bar-width
The width of the vertical scroll bar, in pixels.
The width of the vertical scroll bar, in pixels,
or @code{nil} meaning to use the default width.
@item icon-type
The type of icon to use for this frame when it is iconified. If the
@ -459,33 +462,10 @@ picture of a gnu); @code{nil} specifies a text icon.
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 foreground-color
The color to use for the image of a character. This is a string; the
window system defines the meaningful color names. Changing this
parameter is equivalent to changing the foreground color of the face
@code{default} on the frame in question.
@item background-color
The color to use for the background of characters. Changing this
parameter is equivalent to changing the foreground color of the face
@code{default} on the frame in question.
@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 mouse-color
The color for the mouse pointer. Changing this parameter is equivalent
to changing the background color of face @code{mouse}.
@item cursor-color
The color for the cursor that shows point. Changing this parameter is
equivalent to changing the background color of face @code{cursor}.
@item border-color
The color for the border of the frame. Changing this parameter is
equivalent to changing the background color of face @code{border}.
@item tty-color-mode
@cindex standard colors for character terminals
This parameter overrides the terminal's color support as given by the
@ -500,16 +480,6 @@ value is a symbol, that symbol is looked up in the alist
@code{tty-color-mode-alist}, and if found, the associated number is
used as the color support mode.
@item scroll-bar-foreground
If non-@code{nil}, the color for the foreground of scroll bars.
Changing this parameter is equivalent to setting the foreground color of
face @code{scroll-bar}.
@item scroll-bar-background
If non-@code{nil}, the color for the background of scroll bars.
Changing this parameter is equivalent to setting the background color of
face @code{scroll-bar}.
@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
@ -537,9 +507,8 @@ Display a horizontal bar @var{width} pixels high.
@vindex cursor-type
The buffer-local variable @code{cursor-type} overrides the value of
the @code{cursor-type} frame parameter, and can in addition have
values @code{t} (use the cursor specified for the frame) and
@code{nil} (don't display a cursor).
the @code{cursor-type} frame parameter, but if it is @code{t}, that
means to use the cursor specified for the frame.
@item border-width
The width in pixels of the window border.
@ -547,6 +516,22 @@ The width in pixels of the window border.
@item internal-border-width
The distance in pixels between text and border.
@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 frame or the other to a precise
width by specifying that width a negative integer. If both widths are
negative, only the left fringe gets the specified width.
@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.
@ -558,7 +543,7 @@ iconified. @xref{Visibility of Frames}.
@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar.
The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
toolkit, there is only one menu bar line; all that matters about the
toolkit or GTK, there is only one menu bar line; all that matters about the
number you specify is whether it is greater than zero.)
@item screen-gamma
@ -582,7 +567,9 @@ results for LCD color displays.
@item tool-bar-lines
The number of lines to use for the toolbar. A value of @code{nil} means
don't display a tool bar.
don't display a tool bar. (In Emacs versions that use GTK, there is
only one tool bar line; all that matters about the number you specify
is whether it is greater than zero.)
@item line-spacing
Additional space put below text lines in pixels (a positive integer).
@ -611,6 +598,53 @@ in this variable do not take effect immediately, because the variable
is examined only when you specify a cursor type for a frame.
@end defvar
These frame parameters are semi-obsolete in that they are automatically
equivalent to particular face attributes of particular faces.
@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.
@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.
@end table
@node Size and Position
@subsection Frame Size And Position
@cindex size of frame
@ -798,10 +832,10 @@ configuration (@pxref{Frame Configurations}); this is similar to the
way windows behave.
@deffn Command delete-frame &optional frame force
@vindex delete-frame-hook
@vindex delete-frame-functions
This function deletes the frame @var{frame} after running the hook
@code{delete-frame-hook}. By default, @var{frame} is the selected
frame.
@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,
@ -884,8 +918,9 @@ 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 frame
@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
@ -893,9 +928,16 @@ 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 frame
@defun frame-selected-window &optional frame
This function returns the window on @var{frame} that is selected within
@var{frame}.
@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.
@end defun
Conversely, selecting a window for Emacs with @code{select-window} also
@ -994,14 +1036,14 @@ 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 focus-frame
@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 @code{nil}, that cancels any existing
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.
@ -1426,9 +1468,10 @@ 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} and
@code{SECONDARY}; these are symbols with upper-case names, in accord
with X Window System conventions. The default is @code{PRIMARY}.
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. The default is
@code{PRIMARY}.
@end defun
@defun x-get-selection &optional type data-type
@ -1440,6 +1483,7 @@ clients. It takes two optional arguments, @var{type} and
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{LINE_NUMBER}, @code{COLUMN_NUMBER},
@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
@ -1449,15 +1493,17 @@ upper-case names in accord with X conventions.) The default for
@end defun
@cindex cut buffer
The X server also has a set of numbered @dfn{cut buffers} which can
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.
clients that still use them. Cut buffers are numbered from 0 to 7.
@defun x-get-cut-buffer n
@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
@anchor{Definition of x-set-cut-buffer}
@defun x-set-cut-buffer string &optional push
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.
@ -1661,7 +1707,7 @@ instead of an actual name. The format
@defun x-get-resource attribute class &optional component subclass
The function @code{x-get-resource} retrieves a resource value from the X
Windows defaults database.
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
@ -1681,6 +1727,12 @@ 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
@xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
@ -1872,3 +1924,7 @@ This variable's value is @code{t} if no X window manager is in use.
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

4
lispref/front-cover-1.texi
View file

@ -50,3 +50,7 @@
@end titlepage
@bye
@ignore
arch-tag: 5182b306-c403-4e4f-ba24-e1911bc6da9d
@end ignore

84
lispref/functions.texi
View file

@ -113,10 +113,15 @@ 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 macro.
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).
@ -428,13 +433,14 @@ conventions different from the actual function arguments. Write
text like this:
@example
(fn @var{arglist})
\(fn @var{arglist})
@end example
@noindent
following a blank line, with no newline following it inside the
documentation string. This feature is particularly useful for
macro definitions.
following a blank line, at the beginning of the line, with no newline
following it inside the documentation string. This feature is
particularly useful for macro definitions. The @samp{\} is used to
avoid confusing the Emacs motion commands.
@node Function Names
@section Naming a Function
@ -571,9 +577,15 @@ defined is often done deliberately, and there is no way to distinguish
deliberate redefinition from unintentional redefinition.
@end defspec
@defun defalias name definition
@anchor{Definition of defalias}
@defun defalias name definition &optional docstring
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
@ -587,7 +599,7 @@ records.
@end defun
You cannot create a new primitive function with @code{defun} or
@code{defalias}, but you use them to change the function definition of
@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
@ -700,8 +712,8 @@ primitive function; special forms and macros do not make sense in
@end group
@end example
For an interesting example of using @code{apply}, see the description of
@code{mapcar}, in @ref{Mapping Functions}.
For an interesting example of using @code{apply}, see @ref{Definition
of mapcar}.
@end defun
@cindex functionals
@ -726,19 +738,21 @@ This function ignores any arguments and returns @code{nil}.
@section Mapping Functions
@cindex mapping functions
A @dfn{mapping function} applies a given function 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{Creating Symbols}, for the function @code{mapatoms} which
maps over the symbols in an obarray. @xref{Hash Access}, for the
function @code{maphash} which maps over key/value associations in a
hash table.
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}).
@anchor{Definition of mapcar}
@defun mapcar function sequence
@code{mapcar} applies @var{function} to each element of @var{sequence}
in turn, and returns a list of the results.
@ -770,7 +784,7 @@ length of @var{sequence}.
"Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
;; @r{If no list is exhausted,}
(if (not (memq 'nil args))
(if (not (memq nil args))
;; @r{apply function to @sc{car}s.}
(cons (apply function (mapcar 'car args))
(apply 'mapcar* function
@ -961,8 +975,8 @@ to be used only as a function, and therefore can safely be compiled.
Contrast this with @code{quote}, in @ref{Quoting}.
@end defspec
See @code{documentation} in @ref{Accessing Documentation}, for a
realistic example using @code{function} and an anonymous function.
@xref{describe-symbols example}, for a realistic example using
@code{function} and an anonymous function.
@node Function Cells
@section Accessing Function Cell Contents
@ -971,8 +985,8 @@ realistic example using @code{function} and an anonymous function.
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} in @ref{Function
Indirection}.
See also the function @code{indirect-function}. @xref{Definition of
indirect-function}.
@defun symbol-function symbol
@kindex void-function
@ -1027,8 +1041,9 @@ is a legitimate function.
@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. (See also @code{makunbound}, in @ref{Void Variables}.)
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
@ -1064,7 +1079,7 @@ There are three normal uses of this function:
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{Defining Functions}.)
@code{fset}; see @ref{Definition of defalias}.)
@item
Giving a symbol a function definition that is not a list and therefore
@ -1187,15 +1202,15 @@ following the definition, just like macros.
@cindex function safety
@cindex safety of functions
Some major modes such as SES (@pxref{Top,,,ses}) call functions that
are stored in user files. 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.
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 @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
@ -1326,6 +1341,9 @@ See @ref{Char-Tables}.
See @ref{Mapping Functions}.
@item undefined
See @ref{Key Lookup}.
See @ref{Functions for Key Lookup}.
@end table
@ignore
arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2
@end ignore

3
lispref/gpl.texi
View file

@ -398,3 +398,6 @@ 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.
@ignore
arch-tag: d00ac830-e120-41fb-bbc5-7ca3eeaa227f
@end ignore

47
lispref/hash.texi
View file

@ -76,8 +76,10 @@ alternatives:
@table @code
@item eql
Keys which are numbers are ``the same'' if they are equal in value;
otherwise, two distinct objects are never ``the same''.
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.
@ -96,7 +98,7 @@ 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-or-value}. If @var{weak} is @code{key}
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
@ -107,19 +109,19 @@ 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-or-value} or @code{t}, the hash table does
not protect either keys or values from garbage collection; if either
one is collected as garbage, the association is removed.
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-and-value}, associations are removed from
the hash table when both their key and value would be collected as
garbage, again not considering references to the key and value from
weak hash tables.
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. If
@var{weak} is @code{t}, neither keys nor values are protected (that is,
both are weak).
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
@ -158,8 +160,7 @@ 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.
If you want to specify other parameters, you should use
@code{make-hash-table}.
This function is obsolete. Use @code{make-hash-table} instead.
@end defun
@node Hash Access
@ -187,6 +188,10 @@ value @var{value}. If @var{key} already has an association in
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
@tindex clrhash
@ -194,9 +199,13 @@ nothing.
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
@tindex maphash
@anchor{Definition of maphash}
@defun maphash function table
This function calls @var{function} once for each of the associations in
@var{table}. The function @var{function} should accept two
@ -255,8 +264,8 @@ 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; but once in a rare while, by
luck, you will encounter two distinct-looking objects that give the same
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
@ -334,3 +343,7 @@ This returns the rehash threshold of @var{table}.
@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

13
lispref/help.texi
View file

@ -156,6 +156,7 @@ 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)
@ -259,6 +260,7 @@ 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}.
@anchor{Definition of Snarf-documentation}
@defun Snarf-documentation filename
This function is used only during Emacs initialization, just before
the runnable Emacs is dumped. It finds the file offsets of the
@ -430,7 +432,8 @@ 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).
Emacs buffers are usually displayed) and character codes 128
and above are not treated as Meta characters.
@smallexample
@group
@ -439,11 +442,11 @@ Emacs buffers are usually displayed).
@end group
@group
(text-char-description ?\M-m)
@result{} "M-m"
@result{} "\xed"
@end group
@group
(text-char-description ?\C-\M-m)
@result{} "M-^M"
@result{} "\x8d"
@end group
@end smallexample
@end defun
@ -635,3 +638,7 @@ If this variable is non-@code{nil}, commands defined with
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

7
lispref/hooks.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1998 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2004 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/hooks
@node Standard Hooks, Index, Standard Keymaps, Top
@ -47,6 +47,7 @@ however, we have renamed all of those.)
@item before-init-hook
@item before-make-frame-hook
@item before-revert-hook
@item before-save-hook
@item blink-paren-function
@item buffer-access-fontify-functions
@item c-mode-hook
@ -136,3 +137,7 @@ however, we have renamed all of those.)
@item write-file-functions
@item write-region-annotate-functions
@end table
@ignore
arch-tag: 55fd0296-d906-4551-b300-979d3846aa88
@end ignore

58
lispref/internals.texi
View file

@ -13,7 +13,7 @@ the preloaded Lisp libraries in it, how storage is allocated, and some
internal aspects of GNU Emacs that may be of interest to C programmers.
@menu
* Building Emacs:: How to the dumped Emacs is made.
* 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.
@ -81,8 +81,9 @@ 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{Accessing Documentation}).
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}
You can specify other Lisp expressions to execute just before dumping
@ -151,10 +152,10 @@ preload additional libraries or add features to the standard ones.
@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 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.
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
@ -367,7 +368,7 @@ until the subsequent garbage collection, at which time
@code{garbage-collect} will set the threshold back to 10,000.
@end defopt
The value return by @code{garbage-collect} describes the amount of
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.
@ -382,6 +383,12 @@ You can use this to get a general idea of how your actions affect the
memory usage.
@end defun
@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.
@ -563,6 +570,8 @@ 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
@ -593,9 +602,9 @@ protected in the current function. It is necessary to do this explicitly.
GC-protected; as long as the object is not recycled, all pointers to
it remain valid. So if you are sure that a local variable points to
an object that will be preserved by some other pointer, that local
variable does not need a GCPRO. (Formerly, strings were an exception
to this rule; in older Emacs versions, every pointer to a string
needed to be marked by GC.)
variable does not need a @code{GCPRO}. (Formerly, strings were an
exception to this rule; in older Emacs versions, every pointer to a
string needed to be marked by GC.)
The macro @code{GCPRO1} protects just one local variable. If you
want to protect two, use @code{GCPRO2} instead; repeating
@ -610,7 +619,7 @@ Alas, we can't explain all the tricky details here.
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 GCPRO to protecting the Lisp
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.
@ -649,6 +658,7 @@ file, add to it a @code{syms_of_@var{filename}} (e.g.,
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
The function @code{syms_of_@var{filename}} is also the place to define
any C variables that are to be visible as Lisp variables.
@ -746,10 +756,10 @@ number of arguments. They work by calling @code{Ffuncall}.
@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} to include it. This will help the
optimizer.
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
@ -759,9 +769,9 @@ optimizer.
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-eight bits are used to address the
object, and the remaining four bits are used for a GC mark bit and the
tag that identifies the object's type.
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
@ -1287,7 +1297,7 @@ onto the screen.
@item redisplay_end_trigger
If redisplay in this window goes beyond this buffer position, it runs
run the @code{redisplay-end-trigger-hook}.
the @code{redisplay-end-trigger-hook}.
@ignore
@item orig_height
@ -1386,7 +1396,7 @@ A function called whenever the process receives a signal, or @code{nil}.
The associated buffer of the process.
@item pid
An integer, the Unix process @sc{id}.
An integer, the operating system's process @acronym{ID}.
@item childp
A flag, non-@code{nil} if this is really a child process.
@ -1416,7 +1426,7 @@ 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 @sc{pty};
Non-@code{nil} if communication with the subprocess uses a @acronym{PTY};
@code{nil} if it uses a pipe.
@item infd
@ -1456,3 +1466,7 @@ Size of carryover in encoding.
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

15
lispref/intro.texi
View file

@ -132,8 +132,7 @@ worry about it; this manual is self-contained.
@pindex cl
A certain amount of Common Lisp emulation is available via the
@file{cl} library. @xref{Top,, Common Lisp Extension, cl, Common Lisp
Extensions}.
@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
@ -476,7 +475,7 @@ replaced by `User Option'.
These facilities provide information about which version of Emacs is
in use.
@deffn Command emacs-version
@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.
@ -488,8 +487,10 @@ running. It is useful to include this string in bug reports.
@end group
@end smallexample
Called interactively, the function prints the same information in the
echo area.
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
@ -548,3 +549,7 @@ 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

205
lispref/keymaps.texi
View file

@ -28,6 +28,7 @@ found. The whole process is called @dfn{key lookup}.
* Key Lookup:: How extracting elements from keymaps works.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
* Remapping Commands:: Bindings that translate one command to another.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
* Menu Keymaps:: Defining a menu as a keymap.
@ -124,27 +125,24 @@ 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.
@item @var{vector}
If an element of a keymap is a vector, the vector counts as bindings for
all the @sc{ascii} characters, codes 0 through 127; vector 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 vector is
called a @dfn{full keymap}. Other keymaps are called @dfn{sparse
keymaps}.
@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}.
A @code{nil} binding is used to mean that a key is explicitly not bound.
Just like any other binding, it takes precedence over a default binding
or a binding in the parent keymap, but on the other hand, it does not
take precedence over keymaps of lower priority.
When a keymap contains a vector, it always defines a binding for each
@sc{ascii} character, even if the vector contains @code{nil} for that
character. Such a binding of @code{nil} overrides any default key
binding in the keymap, for @sc{ascii} characters. However, default
bindings are still meaningful for events other than @sc{ascii}
characters. 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.
When a keymap contains a char-table vector, it always defines a
binding for each character without modifiers. However, if the binding
is @code{nil}, it doesn't constitute a definition. @code{nil} takes
precedence over a default binding or a binding in the parent keymap.
So in a full keymap, default bindings are not meaningful for
characters without modifiers. They can still apply to characters with
modifier bits and to non-character events. 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.
@item @var{string}
@cindex keymap prompt string
@ -233,9 +231,9 @@ satisfies @code{keymapp}.
@defun make-keymap &optional prompt
This function creates and returns a new full keymap. That keymap
contains a char-table (@pxref{Char-Tables}) with 384 slots: the first
128 slots are for defining all the @sc{ascii} characters, the next 128
128 slots are for defining all the @acronym{ASCII} characters, the next 128
slots are for 8-bit European characters, and each one of the final 128
slots is for one character set of non-@sc{ascii} characters supported by
slots is for one character set of non-@acronym{ASCII} characters supported by
Emacs. The new keymap initially binds all these characters to
@code{nil}, and does not bind any other kind of event.
@ -530,7 +528,8 @@ when the minor mode is enabled.
The variable @code{overriding-local-map}, if non-@code{nil}, specifies
another local keymap that overrides the buffer's local map and all the
minor mode keymaps.
minor mode keymaps. Modes for emulation can specify additional
active keymaps through the variable @code{emulation-mode-map-alists}.
All the active keymaps are used together to determine what command to
execute when a key is entered. Emacs searches these maps one by one, in
@ -594,7 +593,7 @@ other.
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}, @sc{ascii} code 27, is another sparse
in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
keymap.
@example
@ -714,6 +713,16 @@ 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
@ -918,7 +927,7 @@ Used in keymaps to undefine keys. It calls @code{ding}, but does
not cause an error.
@end deffn
@defun key-binding key &optional accept-defaults
@defun key-binding key &optional accept-defaults no-remap
This function returns the binding for @var{key} in the current
keymaps, trying all the active keymaps. The result is @code{nil} if
@var{key} is undefined in the keymaps.
@ -927,6 +936,12 @@ keymaps, trying all the active keymaps. The result is @code{nil} if
The argument @var{accept-defaults} controls checking for default
bindings, as in @code{lookup-key} (above).
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}.
An error is signaled if @var{key} is not a string or a vector.
@example
@ -984,7 +999,7 @@ This variable is the meta-prefix character code. It is used when
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
@sc{ascii} code for @key{ESC}.
@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
@ -1150,6 +1165,12 @@ 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 rebind them with a different
binding. Another feature you can use for similar effects, but which
is often cleaner, is to add a binding that remaps a command
(@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
@ -1184,13 +1205,6 @@ bindings in another. For example,
puts the special deletion command in @code{my-map} for whichever keys
are globally bound to the standard deletion command.
@ignore
@c Emacs 18 only
Prefix keymaps that appear within @var{keymap} are not checked
recursively for keys bound to @var{olddef}; they are not changed at all.
Perhaps it would be better to check nested keymaps recursively.
@end ignore
Here is an example showing a keymap before and after substitution:
@smallexample
@ -1259,6 +1273,56 @@ Dired mode is set up:
@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:
@example
(define-key my-mode-map [remap kill-line] 'my-kill-line)
(define-key my-mode-map [remap kill-word] 'my-kill-word)
@end example
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-mode-map},
so instead of running @code{kill-line}, Emacs runs
@code{my-kill-line}.
Remapping only works through a single level. In other words,
@example
(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 example
@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
This function returns the remapping for @var{command}, given the
current active keymaps. If @var{command} is not remapped (which is
the usual situation), the function returns @code{nil}.
@end defun
@node Key Binding Commands
@section Commands for Binding Keys
@ -1297,8 +1361,8 @@ redefines @kbd{C-x C-\} to move down a line.
redefines the first (leftmost) mouse button, typed with the Meta key, to
set point where you click.
@cindex non-@sc{ascii} text in keybindings
Be careful when using non-@sc{ascii} text characters in Lisp
@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:
@ -1488,7 +1552,7 @@ 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
@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 key sequences (of any length) that are bound to @var{command} in a
@ -1512,13 +1576,20 @@ If @var{firstonly} is @code{non-ascii}, then the value is a single
string 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 @sc{ascii} characters (or meta variants of @sc{ascii}
entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
characters) are preferred to all other key sequences.
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)
@ -1538,13 +1609,13 @@ 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 @sc{ascii} codes have the
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 @sc{ascii} codes to understand which characters this means.
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 @sc{ascii} 32,
@kbd{~} is @sc{ascii} 126, and the characters between them include all
..@: ~} 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}.
@end deffn
@ -1623,7 +1694,12 @@ looks like this:
@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.
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 Gtk+ support.@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:
@ -2248,7 +2324,7 @@ follows.
@tindex tool-bar-add-item
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 located by
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
@ -2257,7 +2333,7 @@ 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
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
@ -2270,15 +2346,26 @@ To define items in some local map, bind @code{`tool-bar-map} with
@defun tool-bar-add-item-from-menu command icon &optional map &rest props
@tindex tool-bar-add-item-from-menu
This command is a convenience for defining tool bar items which are
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 looked for in the same way as by
@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}. @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.
@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} si like the @var{map} argument of
@code{tool-bar-add-item-from-menu}.
@end defun
@tindex auto-resize-tool-bar
@ -2288,22 +2375,22 @@ show all defined tool bar items---but not larger than a quarter of the
frame's height.
@end defvar
@tindex auto-raise-tool-bar-items
@defvar auto-raise-tool-bar-items
@tindex auto-raise-tool-bar-buttons
@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
@tindex tool-bar-item-margin
@defvar tool-bar-item-margin
@tindex tool-bar-button-margin
@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 1.
The value is an integer, a number of pixels. The default is 4.
@end defvar
@tindex tool-bar-item-relief
@defvar tool-bar-item-relief
@tindex tool-bar-button-relief
@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 3.
The value is an integer, a number of pixels. The default is 1.
@end defvar
You can define a special meaning for clicking on a tool bar item with
@ -2371,3 +2458,7 @@ menu of Shell mode, after the item @code{break}:
[work] '("Work" . work-command) 'break)
@end example
@end defun
@ignore
arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
@end ignore

4
lispref/lay-flat.texi
View file

@ -37,3 +37,7 @@ pushed or held down.
@end tex
@bye
@ignore
arch-tag: 9e03a1c7-6f62-4346-85d9-ed5b79386e07
@end ignore

173
lispref/lists.texi
View file

@ -448,11 +448,11 @@ 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 fundamental function used to build new list
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.
@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
@ -568,14 +568,13 @@ 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.
The @code{append} function also allows integers as arguments. It
converts them to strings of digits, making up the decimal print
representation of the integer, and then uses the strings instead of the
original integers. @strong{Don't use this feature; we plan to eliminate
it. If you already use this feature, change your programs now!} 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}).
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}:
@ -708,40 +707,55 @@ x
@end example
@end defun
@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}.
@defun copy-tree tree &optional vecp
This function returns a copy 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.
@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
@noindent
The function @code{delq} offers a way to perform this operation
destructively. See @ref{Sets And Lists}.
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 to &optional separation
This returns a list of numbers starting with @var{from}
and incrementing by @var{separation} (or by 1 if @var{separation}
is @code{nil} or omitted), and ending at or just before @var{to}.
For example,
@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 one element list @code{(from)} is returned. If @var{separation}
is 0 and @var{to} is neither @code{nil} nor numerically equal to
@var{from}, an error is signaled.
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
@ -1209,7 +1223,8 @@ useful example of @code{sort}.
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). Other useful
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}.
@ -1241,13 +1256,6 @@ compare @var{object} against the elements of the list. For example:
@end example
@end defun
@defun member-ignore-case object list
This function is like @code{member}, except 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 delq object list
@cindex deletion of elements
This function destructively removes all elements @code{eq} to
@ -1314,9 +1322,34 @@ and the @code{(4)} in the @code{sample-list} are not @code{eq}:
@end group
@end example
The following two functions are like @code{memq} and @code{delq} but use
@code{equal} rather than @code{eq} to compare elements. @xref{Equality
Predicates}.
@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
@noindent
The function @code{delq} offers a way to perform this operation
destructively. See @ref{Sets And Lists}.
@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
@ -1393,6 +1426,21 @@ 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{Setting Variables},
for another way to add an element to a list stored in a variable.
@ -1501,9 +1549,9 @@ Here is another example, in which the keys and values are not symbols:
@end smallexample
@end defun
The functions @code{assoc-ignore-representation} and
@code{assoc-ignore-case} are much like @code{assoc} except using
@code{compare-strings} to do the comparison. @xref{Text Comparison}.
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
@ -1658,13 +1706,22 @@ the associations of one copy without affecting the other:
@defun assq-delete-all key alist
@tindex assq-delete-all
This function deletes from @var{alist} all the elements whose @sc{car}
is @code{eq} to @var{key}. It returns @var{alist}, modified
in this way. Note that it modifies the original list structure
of @var{alist}.
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
(assq-delete-all 'foo
'((foo 1) (bar 2) (foo 3) (lose 4)))
(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
@ignore
arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
@end ignore

53
lispref/loading.texi
View file

@ -37,7 +37,7 @@ containing Lisp code.
@menu
* How Programs Do Loading:: The @code{load} function and others.
* Library Search:: Finding a library to load.
* Loading Non-ASCII:: Non-@sc{ascii} characters in Emacs Lisp files.
* 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.
@ -140,6 +140,7 @@ This variable is non-@code{nil} if Emacs is in the process of loading a
file, and it is @code{nil} otherwise.
@end defvar
@anchor{Definition of load-read-function}
@defvar load-read-function
This variable specifies an alternate expression-reading function for
@code{load} and @code{eval-region} to use instead of @code{read}.
@ -148,9 +149,9 @@ 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}.
@strong{Note:} 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{Eval}.
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
@ -172,7 +173,7 @@ directory).
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/paths.h} when Emacs is built.
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.
@ -289,13 +290,13 @@ tells @code{locate-library} to display the file name in the echo area.
@defvar load-suffixes
This variable is a list of suffixes (strings) that @code{load} should
try adding to the specified file name. The default value is
@code{(".el" ".elc")}. There is no need to include the null suffix.
@code{(".elc" ".el")}. There is no need to include the null suffix.
@end defvar
@node Loading Non-ASCII
@section Loading Non-@sc{ascii} Characters
@section Loading Non-@acronym{ASCII} Characters
When Emacs Lisp programs contain string constants with non-@sc{ascii}
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
@ -309,7 +310,7 @@ unibyte text, and its string constants will be unibyte strings.
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-@sc{ascii} characters translate into multibyte
constants with non-@acronym{ASCII} characters translate into multibyte
strings. The only exception is when a particular file specifies no
decoding.
@ -321,7 +322,7 @@ 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-@sc{ascii} strings are
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
@ -329,7 +330,7 @@ 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-@sc{ascii} characters written as @code{?v@var{literal}}.
non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
@node Autoload
@section Autoload
@ -656,6 +657,7 @@ The argument @var{feature} must be a symbol. @code{provide} returns
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}.
@smallexample
features
@ -668,7 +670,7 @@ features
@end smallexample
When a file is loaded to satisfy an autoload, and it stops due to an
error in the evaluating its contents, any function definitions or
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
@ -723,12 +725,14 @@ library with @code{defun}, @code{defalias}, @code{defsubst},
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{loadhist-special-hooks}. This
is to prevent Emacs from ceasing to function because important hooks
refer to functions that are no longer defined.
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
@ -786,18 +790,7 @@ The value of @code{load-history} may have one element whose @sc{car} is
by adding the symbols defined to the element for the file being visited,
rather than replacing that element. @xref{Eval}.
Preloaded libraries don't contribute initially to @code{load-history}.
Instead, preloading writes information about preloaded libraries into a
file, which can be loaded later on to add information to
@code{load-history} describing the preloaded files. This file is
installed in @code{exec-directory} and has a name of the form
@file{fns-@var{emacsversion}.el}.
@findex symbol-file
See the source for the function @code{symbol-file}, for an example of
code that loads this file to find functions in preloaded libraries.
@defvar loadhist-special-hooks
@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
@ -852,3 +845,7 @@ implement @code{eval-after-load}.
@end defvar
@c Emacs 19 feature
@ignore
arch-tag: df731f89-0900-4389-a436-9105241b6f7a
@end ignore

6
lispref/locals.texi
View file

@ -79,7 +79,7 @@ use, but we don't try to list them all here.
@xref{Comments,,, emacs, The GNU Emacs Manual}.
@item default-directory
@xref{System Environment}.
@xref{File Name Expansion}.
@item defun-prompt-regexp
@xref{List Motion}.
@ -174,3 +174,7 @@ Used for communication between mouse commands and scroll-bar commands.
@item vc-mode
@xref{Mode Line Variables}.
@end table
@ignore
arch-tag: 6baae835-b667-4447-91e2-9829ae1cf543
@end ignore

123
lispref/macros.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2004 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/macros
@node Macros, Customization, Functions, Top
@ -30,6 +30,7 @@ instead. @xref{Inline Functions}.
* 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
@ -136,6 +137,28 @@ uses this feature.
@end smallexample
@end defun
@defun macroexpand-all form &optional environment
@cindex macro expansion in entire form
@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.
In emacs-lisp, @code{macroexpand-all} guarantees that if no macros
are expanded, the return value will be @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
@ -205,6 +228,41 @@ 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.
@anchor{Definition of declare}
@defmac declare @var{specs}@dots{}
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 (edebug @var{edebug-form-spec})
Specify how to step through macro calls for Edebug.
@xref{Instrumenting Macro Calls}, for more details.
@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)
@ -331,9 +389,9 @@ trouble, and rules to follow to avoid trouble.
@node Wrong Time
@subsection Wrong Time
The most common problem in writing macros is doing too some of the
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 nmacro
expansion itself. For instance, one real package had this macro
definition:
@example
@ -636,3 +694,62 @@ One way to avoid pathological cases like this is to think of
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 a number, @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

4
lispref/maps.texi
View file

@ -187,3 +187,7 @@ A sparse keymap used by Text mode.
@vindex view-mode-map
A full keymap used by View mode.
@end table
@ignore
arch-tag: b741253c-7e23-4a02-b3fa-cffd9e4d72b9
@end ignore

43
lispref/markers.texi
View file

@ -28,10 +28,13 @@ deleted, so that it stays with the two characters on either side of it.
@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. @xref{Positions}, for a complete
description of positions.
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 two attributes: the marker position, and the marker
buffer. The marker position is an integer that is equivalent (at a
@ -144,6 +147,9 @@ 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.
@ -201,7 +207,7 @@ chapter.
@end example
@end defun
@defun copy-marker marker-or-integer insertion-type
@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,
@ -331,6 +337,11 @@ text is inserted at its position. If @var{type} is @code{nil},
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
@ -432,10 +443,11 @@ programming. So we do not describe it here.
@cindex current buffer mark
This function returns the current buffer's mark position as an integer.
If the mark is inactive, @code{mark} normally signals an error.
However, if @var{force} is non-@code{nil}, then @code{mark} returns the
mark position anyway---or @code{nil}, if the mark is not yet set for
this buffer.
If Transient Mark mode is enabled, @code{mark-even-if-inactive} is
@code{nil} and and the mark is inactive, @code{mark} normally signals
an error. However, if @var{force} is non-@code{nil}, then @code{mark}
returns the mark position anyway---or @code{nil}, if the mark is not
yet set for this buffer.
@end defun
@defun mark-marker
@ -617,20 +629,21 @@ 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.
If the mark does not point anywhere, an error is signaled.
@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.
If the mark does not point anywhere, an error is signaled.
@end defun
Few programs need to use the @code{region-beginning} and
@ -639,3 +652,7 @@ 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

379
lispref/minibuf.texi
View file

@ -63,6 +63,11 @@ 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
@ -130,13 +135,17 @@ 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
@var{read} is non-@code{nil}, then @var{default} is also used as the
input to @code{read}, if the user enters empty input. However, in the
usual case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
does not return @var{default} when the user enters empty input; it
returns an empty string, @code{""}. In this respect, it is different
from all the other minibuffer input functions in this chapter.
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
@ -166,8 +175,9 @@ its initial contents.
Alternatively, @var{initial-contents} can be a cons cell of the form
@code{(@var{string} . @var{position})}. This means to insert
@var{string} in the minibuffer but put point @var{position} characters
from the beginning, rather than at the end.
@var{string} in the minibuffer but put point at @emph{one-indexed}
@var{position} in the minibuffer, rather than at the end. Any integer
value less or equal to one puts point at the beginning of the string.
@strong{Usage note:} The @var{initial-contents} argument and the
@var{default} argument are two alternative features for more or less the
@ -175,21 +185,21 @@ same job. It does not make sense to use both features in a single call
to @code{read-from-minibuffer}. In general, we recommend using
@var{default}, since this permits the user to insert the default value
when it is wanted, but does not burden the user with deleting it from
the minibuffer on other occasions.
the minibuffer on other occasions. For an exception to this rule,
see @ref{Minibuffer History}.
@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} and @var{initial} are used as in
@code{read-from-minibuffer}. The keymap used is
@code{minibuffer-local-map}.
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{history}, if non-@code{nil}, specifies a
history list and optionally the initial position in the list. The
optional argument @var{default} specifies a default value to return if
the user enters null input; it should be a string. The optional
argument @var{inherit-input-method} specifies whether to inherit the
current buffer's input method.
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:
@ -201,7 +211,7 @@ This function is a simplified interface to the
(let ((value
(read-from-minibuffer @var{prompt} @var{initial} nil nil
@var{history} @var{default} @var{inherit})))
(if (equal value "")
(if (and (equal value "") @var{default})
@var{default}
value))
@end group
@ -211,13 +221,15 @@ This function is a simplified interface to the
@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.
Since all minibuffer input uses @code{read-from-minibuffer}, this
variable applies to all minibuffer input.
Note that the completion functions discard text properties unconditionally,
regardless of the value of this variable.
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
@anchor{Definition of minibuffer-local-map}
@defvar minibuffer-local-map
This is the default local keymap for reading from the minibuffer. By
default, it makes the following bindings:
@ -238,10 +250,10 @@ default, it makes the following bindings:
@item @kbd{M-p}
@code{previous-history-element}
@item @kbd{M-r}
@item @kbd{M-s}
@code{next-matching-history-element}
@item @kbd{M-s}
@item @kbd{M-r}
@code{previous-matching-history-element}
@end table
@end defvar
@ -260,11 +272,15 @@ 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{}
(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)
(let (minibuffer-allow-text-properties)
(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
@end group
@end smallexample
@end defun
@ -307,7 +323,8 @@ This is a simplified interface to the
@group
(read-minibuffer @var{prompt} @var{initial})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} nil t)
(let (minibuffer-allow-text-properties)
(read-from-minibuffer @var{prompt} @var{initial} nil t))
@end group
@end smallexample
@ -416,11 +433,16 @@ 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} (an integer, counting from
zero which specifies the most recent element of the history).
initial history position is @var{startpos} (a nonnegative integer).
If you specify @var{startpos}, then you should also specify that element
of the history as the initial minibuffer contents, for consistency.
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.
@end table
If you don't specify @var{hist}, then the default history list
@ -534,8 +556,9 @@ the higher-level completion features that do use the minibuffer.
@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, an alist, an obarray, or a
function that implements a virtual set of strings (see below).
@var{collection} must be a list of strings, 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
@ -547,7 +570,12 @@ longest initial sequence common to all the permissible completions that
match.
If @var{collection} is an alist (@pxref{Association Lists}), the
@sc{car}s of the alist elements form the set of permissible completions.
permissible completions are the elements of the alist that are either
strings or conses whose @sc{car} is a string. Other elements of the
alist are ignored. (Remember that in Emacs Lisp, the elements of
alists do not @emph{have} to be conses.) As all elements of the alist
can be strings, this case actually includes lists of strings, 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
@ -559,6 +587,9 @@ 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
@ -568,11 +599,20 @@ 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. 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 from the
list, a cons cell from the alist (the @sc{car} of which is a string)
or a symbol (@emph{not} a symbol name) from the obarray.
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
@ -628,10 +668,13 @@ too short). Both of those begin with the string @samp{foobar}.
@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}. If @var{nospace} is
non-@code{nil}, completions that start with a space are ignored unless
@var{string} also starts with a space.
@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}
@ -657,13 +700,24 @@ example for @code{try-completion}:
@end smallexample
@end defun
@anchor{Definition of test-completion}
@defun test-completion string collection &optional predicate
This function returns non-@code{nil} if @var{string} is a valid
completion possibility specified by @var{collection} and
@var{predicate}. The other arguments are the same as in
@code{try-completion}. For instance, if @var{collection} is a list,
this is true if @var{string} appears in the list and @var{predicate}
is satisfied.
@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.
@code{test-completion} 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
@ -675,6 +729,13 @@ 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 &rest args
This macro provides a way to initialize the variable @var{var} as a
collection for completion in a lazy way, not computing its actual
@ -706,8 +767,12 @@ 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.
@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
@ -718,19 +783,13 @@ 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}. The value of @var{default} (if non-@code{nil}) is also
available to the user through the history commands.
@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 user can exit with null input by typing @key{RET} with an empty
minibuffer. Then @code{completing-read} returns @code{""}. This is how
the user requests whatever default the command uses for the value being
read. The user can return using @key{RET} in this way regardless of the
value of @var{require-match}, and regardless of whether the empty string
is included in @var{collection}.
The function @code{completing-read} works by calling
@code{read-minibuffer}. It uses @code{minibuffer-local-completion-map}
as the keymap if @var{require-match} is @code{nil}, and uses
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}.
@ -739,15 +798,21 @@ saving the input and for minibuffer history commands. It defaults to
@code{minibuffer-history}. @xref{Minibuffer History}.
If @var{initial} is non-@code{nil}, @code{completing-read} inserts it
into the minibuffer as part of the input. Then it allows the user to
edit the input, providing several commands to attempt completion.
In most cases, we recommend using @var{default}, and not @var{initial}.
into the minibuffer as part of the input, with point at the end. Then
it allows the user to edit the input, providing several commands to
attempt completion. @var{initial} can also be a cons cell of the form
@code{(@var{string} . @var{position})}. In that case, point is put at
@emph{zero-indexed} position @var{position} in @var{string}. Note
that this is different from @code{read-from-minibuffer} and related
functions, which use a one-indexed position. In most cases, we
recommend using @var{default}, and not @var{initial}.
@strong{We discourage use of a non-@code{nil} value for
@var{initial}}, because it is an intrusive interface. The history
list feature (which did not exist when we introduced @var{initial})
offers a far more convenient and general way for the user to get the
default and edit it, and it is always available.
default and edit it, and it is always available. For an exception to
this rule, see @ref{Minibuffer History}.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method (@pxref{Input
@ -794,8 +859,13 @@ see @ref{Completion Commands}.
@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.
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-local-completion-map
@code{completing-read} uses this value as the local keymap when an
@ -815,7 +885,7 @@ keymap makes the following bindings:
@noindent
with other characters bound as in @code{minibuffer-local-map}
(@pxref{Text from Minibuffer}).
(@pxref{Definition of minibuffer-local-map}).
@end defvar
@defvar minibuffer-local-must-match-map
@ -847,8 +917,8 @@ with other characters bound as in @code{minibuffer-local-map}.
@end defvar
@defvar minibuffer-completion-table
The value of this variable is the alist or obarray used for completion
in the minibuffer. This is the global variable that contains what
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
@ -902,8 +972,10 @@ This function displays @var{completions} to the stream in
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, or a list of two strings, which is printed
as if the strings were concatenated.
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.
This function is called by @code{minibuffer-completion-help}. The
most common way to use it is together with
@ -943,9 +1015,10 @@ is not inserted in the minibuffer as initial input.
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. (However, @var{default} is not checked
for validity; it is returned, whatever it is, if the user exits with the
minibuffer empty.)
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
@ -991,7 +1064,8 @@ 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{nil}.
enters null input, the return value is @code{(intern "")}, that is, a
symbol whose name is an empty string.
@example
(read-command "Command name? ")
@ -1036,7 +1110,7 @@ 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{nil}.
user enters null input, the return value is @code{(intern "")}.
@example
@group
@ -1083,12 +1157,9 @@ predicate @code{user-variable-p} instead of @code{commandp}:
file name. It provides special features including automatic insertion
of the default directory.
@defun read-file-name prompt &optional directory default existing initial
@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{default} is
non-@code{nil}, then the function returns @var{default} if the user just
types @key{RET}. @var{default} is not checked for validity; it is
returned, whatever it is, if the user exits with the minibuffer empty.
@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
@ -1099,18 +1170,58 @@ value of @var{existing} is neither @code{nil} nor @code{t}, then
acceptable.
The argument @var{directory} specifies the directory to use for
completion of relative file names. 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}.
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
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{Note:} we
recommend using @var{default} rather than @var{initial} in most cases.
@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:
@ -1146,15 +1257,38 @@ 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
@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 the
current buffer's default directory as substitute default, ignoring
@var{directory}.
@end defun
@defopt insert-default-directory
This variable is used by @code{read-file-name}. 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.
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:
@ -1611,9 +1745,10 @@ The current value of this variable is used to rebind @code{help-form}
locally inside the minibuffer (@pxref{Help Functions}).
@end defvar
@defun minibufferp &optional buffer
This function returns non-@code{nil} if @var{buffer} is a minibuffer.
If @var{buffer} is omitted, it tests the current buffer.
@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
@defun active-minibuffer-window
@ -1629,9 +1764,19 @@ 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 window
This function returns non-@code{nil} if @var{window} is a minibuffer window.
@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
@ -1650,6 +1795,12 @@ 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
Finally, some functions and variables deal with recursive minibuffers
(@pxref{Recursive Editing}):
@ -1674,12 +1825,18 @@ another window to do it.
@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. The minibuffer
command @code{next-matching-history-element} (normally @kbd{M-s} in the
minibuffer) uses this feature.
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.
@defun minibuffer-message string &optional timeout
@defun minibuffer-message string
This function displays @var{string} temporarily at the end of the
minibuffer text, for @var{timeout} seconds. (The default is 2
seconds.)
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

2
lispref/mkinstalldirs
View file

@ -4,8 +4,6 @@
# Created: 1993-05-16
# Public domain
# $Id: mkinstalldirs,v 1.10 1996/05/03 07:37:52 friedman Exp $
errstatus=0
for file

537
lispref/modes.texi
View file

@ -4,7 +4,7 @@
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
@node Modes, Documentation, Keymaps, Top
@node Modes, Documentation, Keymaps, Top
@chapter Major and Minor Modes
@cindex mode
@ -203,7 +203,7 @@ a newline. The command to insert a newline and then indent is
@kbd{C-j}. Please keep this distinction uniform for all major modes.
@item
Major modes should not alter options that are primary a matter of user
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
@ -236,7 +236,9 @@ setting up a buffer-local value for the variable
@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} or
variable @code{imenu-generic-expression}, for the pair of 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
@ -274,7 +276,7 @@ recommended way to define one is to use @code{define-derived-mode},
but this is not required. Such a mode should use
@code{delay-mode-hooks} around its entire body, including the call to
the parent mode command and the final call to @code{run-mode-hooks}.
(Using @code{define-derived-mode} does this automatically.)
(Using @code{define-derived-mode} does this automatically.)
@item
If something special should be done if the user switches a buffer from
@ -421,7 +423,7 @@ correspondingly more complicated. Here are excerpts from
@group
;; @r{Set syntax of chars up to 0 to class of chars that are}
;; @r{part of symbol names but not words.}
;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
;; @r{(The number 0 is @code{48} in the @acronym{ASCII} character set.)}
(while (< i ?0)
(modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
(setq i (1+ i)))
@ -1101,7 +1103,7 @@ See the command \\[hungry-electric-delete]."
@end smallexample
@node Mode Line Format
@section Mode Line Format
@section Mode-Line Format
@cindex mode line
Each Emacs window (aside from minibuffer windows) typically has a mode
@ -1137,10 +1139,12 @@ update of the mode line so as to display the new information or
display it in the new way.
@c Emacs 19 feature
@defun force-mode-line-update
@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.
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.
@ -1161,41 +1165,44 @@ actually appears.
* %-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 Data
@subsection The Data Structure of the Mode Line
@cindex mode line construct
@cindex mode-line construct
The mode line contents are controlled by a data structure of lists,
The mode-line contents are controlled by a data structure of lists,
strings, symbols, and numbers kept in buffer-local variables. The data
structure is called a @dfn{mode line construct}, and it is built in
recursive fashion out of simpler mode line constructs. The same data
structure is called a @dfn{mode-line construct}, and it is built in
recursive fashion out of simpler mode-line constructs. The same data
structure is used for constructing frame titles (@pxref{Frame Titles})
and header lines (@pxref{Header Lines}).
@defvar mode-line-format
The value of this variable is a mode line construct with overall
responsibility for the mode line format. The value of this variable
controls which other variables are used to form the mode line text, and
The value of this variable is a mode-line construct with overall
responsibility for the mode-line format. The value of this variable
controls which other variables are used to form the mode-line text, and
where they appear.
If you set this variable to @code{nil} in a buffer, that buffer does not
have a mode line. (This feature was added in Emacs 21.)
@end defvar
A mode line construct may be as simple as a fixed string of text, but
A mode-line construct may be as simple as a fixed string of text, but
it usually specifies how to use other variables to construct the text.
Many of these variables are themselves defined to have mode line
Many of these variables are themselves defined to have mode-line
constructs as their values.
The default value of @code{mode-line-format} incorporates the values
of variables such as @code{mode-name} and @code{minor-mode-alist}.
Because of this, very few modes need to alter @code{mode-line-format}
itself. For most purposes, it is sufficient to alter some of the
variables that @code{mode-line-format} refers to.
of 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}). Because of
this, 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.
A mode line construct may be a list, a symbol, or a string. If the
A mode-line construct may be a list, a symbol, or a string. If the
value is a list, each element may be a list, a symbol, or a string.
The mode line can display various faces, if the strings that control
@ -1206,43 +1213,56 @@ mode line (@pxref{Standard Faces}).
@table @code
@cindex percent symbol in mode line
@item @var{string}
A string as a mode line construct is displayed verbatim in the mode line
A string as a mode-line construct is displayed verbatim in the mode line
except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
specify the field width for space filling on the right (i.e., the data
is left justified). @xref{%-Constructs}.
@item @var{symbol}
A symbol as a mode line construct stands for its value. The value of
@var{symbol} is used as a mode line construct, in place of @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 properties in
any strings, as well as all @code{:eval} and @code{:propertize} forms in
the value of that symbol will be ignored.
@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
A list whose first element is a string or list means to process all the
elements recursively and concatenate the results. This is the most
common form of mode line construct.
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.
(This feature is new as of Emacs 21.)
@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 and 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 21.4.)
@c FIXME: This might be Emacs 21.5.
@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 the
value is non-@code{nil}, the second element, @var{then}, is processed
recursively as a mode line element. But if the value of @var{symbol} is
recursively as a mode-line element. But if the value of @var{symbol} is
@code{nil}, the third element, @var{else}, is processed recursively.
You may omit @var{else}; then the mode line element displays nothing if
You may omit @var{else}; then the mode-line element displays nothing if
the value of @var{symbol} is @code{nil}.
@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
@var{rest} are processed recursively as mode-line constructs and
concatenated together. Then the result is space filled (if
@var{width} is positive) or truncated (to @minus{}@var{width} columns,
if @var{width} is negative) on the right.
@ -1274,7 +1294,7 @@ directory.
@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.}
;; @r{It makes a mode-line construct which is just a string.}
(getenv "HOST")
@end group
":"
@ -1291,7 +1311,7 @@ directory.
'(which-func-mode ("" which-func-format "--"))
'(line-number-mode "L%l--")
'(column-number-mode "C%c--")
'(-3 . "%p")
'(-3 "%p")
"-%-"))
@end group
@end example
@ -1331,8 +1351,8 @@ Changing this variable does not force an update of the mode line.
@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
@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
@ -1342,24 +1362,74 @@ default value is @code{("%12b")}, which displays the buffer name, padded
with spaces to at least 12 columns.
@end defvar
@defvar global-mode-string
This variable holds a mode line spec that appears in the mode line by
default, just after the buffer name. The command @code{display-time}
sets @code{global-mode-string} to refer to the variable
@code{display-time-string}, which holds a string containing the time and
load information.
@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.
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}.
@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
This variable holds an association list whose elements specify how the
mode line should indicate that a minor mode is active. Each element of
@ -1369,51 +1439,28 @@ the @code{minor-mode-alist} should be a two-element list:
(@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
More generally, @var{mode-line-string} can be any mode-line spec. It
appears in the mode line when the value of @var{minor-mode-variable}
is non-@code{nil}, and not otherwise. These strings should begin with
spaces so that they don't run together. Conventionally, the
@var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
value when that minor mode is activated.
The default value of @code{minor-mode-alist} is:
@example
@group
minor-mode-alist
@result{} ((vc-mode vc-mode)
(abbrev-mode " Abbrev")
(overwrite-mode overwrite-mode)
(auto-fill-function " Fill")
(defining-kbd-macro " Def")
(isearch-mode isearch-mode))
@end group
@end example
@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 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 global-mode-string
This variable holds a mode-line spec that appears in the mode line by
default, just after the buffer name. The command @code{display-time}
sets @code{global-mode-string} to refer to the variable
@code{display-time-string}, which holds a string containing the time and
load information.
Some variables are used by @code{minor-mode-alist} to display
a string for various minor modes when enabled. This is a typical
example:
@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.
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
@ -1424,7 +1471,9 @@ This variable holds the default @code{mode-line-format} for buffers
that do not override it. This is the same as @code{(default-value
'mode-line-format)}.
The default value of @code{default-mode-line-format} is this list:
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
@ -1435,23 +1484,13 @@ The default value of @code{default-mode-line-format} is this list:
mode-line-buffer-identification
@end group
" "
global-mode-string
@group
" %[("
;; @r{@code{mode-line-mode-name} is a function}
;; @r{that copies the mode name and adds text}
;; @r{properties to make it mouse-sensitive.}
(:eval (mode-line-mode-name))
mode-line-process
minor-mode-alist
"%n"
")%]--"
@end group
mode-line-position
(vc-mode vc-mode)
" "
@group
mode-line-modes
(which-func-mode ("" which-func-format "--"))
(line-number-mode "L%l--")
(column-number-mode "C%c--")
(-3 . "%p")
(global-mode-string ("--" global-mode-string))
"-%-")
@end group
@end example
@ -1480,6 +1519,15 @@ function. @xref{Buffer File Name}.
The title (only on a window system) or the name of the selected frame.
@xref{Window Frame 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.
@ -1554,29 +1602,33 @@ The value of @code{global-mode-string}. Currently, only
@node Properties in Mode
@subsection Properties in the Mode Line
@cindex text properties in the mode line
Starting in Emacs 21, certain text properties are meaningful in the
mode line. The @code{face} property affects the appearance of text; the
@code{help-echo} property associate help strings with the text, and
@code{local-map} can make the text mouse-sensitive.
There are three ways to specify text properties for text in the mode
There are four ways to specify text properties for text in the mode
line:
@enumerate
@item
Put a string with the @code{local-map} property directly into the
mode-line data structure.
Put a string with a text property directly into the mode-line data
structure.
@item
Put a @code{local-map} property on a mode-line %-construct
such as @samp{%12b}; then the expansion of the %-construct
will have that same text property.
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
@code{local-map} property.
structure, and make @var{form} evaluate to a string that has a text
property.
@end enumerate
You use the @code{local-map} property to specify a keymap. Like any
@ -1591,7 +1643,7 @@ keymap can only take real effect for mouse clicks.
Starting in Emacs 21, 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
feature works just like the mode-line feature, except that it's
controlled by different variables.
@tindex header-line-format
@ -1610,6 +1662,31 @@ that do not override it. This is the same as @code{(default-value
It is normally @code{nil}, so that ordinary buffers have no header line.
@end defvar
@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 certain mode-line specification.
@defun format-mode-line &optional format window no-props
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.
If @var{format} is @code{nil}, that means to use
@code{mode-line-format} and return the text that would appear in the
mode line. If @var{format} is @code{t}, that means to use
@code{header-line-format} so as to return the text that would appear
in the header line (@code{""} if the window has no header line).
The argument @var{window} defaults to the selected window.
The value string normally has text properties that correspond to the
faces, keymaps, etc., that the mode line would have. If
@var{no-props} is non-@code{nil}, the value has no text properties.
@end defun
@node Imenu
@section Imenu
@ -1629,12 +1706,12 @@ particular major mode.
@code{imenu-generic-expression}:
@defvar imenu-generic-expression
This variable, if non-@code{nil}, specifies regular expressions for
finding definitions for Imenu. In the simplest case, elements should
look like this:
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{subexp})
(@var{menu-title} @var{regexp} @var{index})
@end example
Here, if @var{menu-title} is non-@code{nil}, it says that the matches
@ -1644,10 +1721,10 @@ for this element should go in a submenu of the buffer index;
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{subexp}, indicates which subexpression in @var{regexp}
matches the definition's name.
(@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:
@ -1655,11 +1732,13 @@ An element can also look like this:
(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
@end example
Each match for this element creates a special index item which, if
selected by the user, calls @var{function} with arguments consisting of
the item name, the buffer position, and @var{arguments}.
Like in the previous case, each match for this element creates an
index item. However, if this 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, @var{pattern} could look like this:
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
@ -1683,9 +1762,10 @@ Setting this variable makes it buffer-local in the current buffer.
@end defvar
@defvar imenu-case-fold-search
This variable controls whether matching against
@var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
means matching should ignore case.
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
@ -1713,11 +1793,11 @@ For example, Fortran mode uses it this way:
(setq imenu-syntax-alist '(("_$" . "w")))
@end example
The @code{imenu-generic-expression} patterns 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.
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
@ -1750,37 +1830,48 @@ Setting this variable makes it buffer-local in the current buffer.
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 for the
current buffer. It is called within @code{save-excursion}, so where it
leaves point makes no difference.
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 default value is a function that uses
@code{imenu-generic-expression} to produce the index alist. If you
specify a different function, then @code{imenu-generic-expression} is
not used.
Setting this variable makes it buffer-local in the current buffer.
@end defvar
@defvar imenu-index-alist
This variable holds the index alist for the current buffer.
Setting it makes it buffer-local in the current buffer.
Simple elements in the alist look like @code{(@var{index-name}
. @var{index-position})}. Selecting a simple element has the effect of
moving to position @var{index-position} in the buffer.
Special elements look like @code{(@var{index-name} @var{position}
@var{function} @var{arguments}@dots{})}. Selecting a special element
performs
The index alist can have three types of elements. Simple elements
look like this:
@example
(funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
(@var{index-name} . @var{index-position})
@end example
A nested sub-alist element looks like @code{(@var{index-name}
@var{sub-alist})}.
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 uses
@code{imenu-prev-index-position-function} and
@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
@ -1933,9 +2024,10 @@ If you use @code{regexp-opt} to produce the regular expression
@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
of Regexps}) to calculate the value for @var{match}.
@item (@var{matcher} . @var{facename})
In this kind of element, @var{facename} is an expression whose value
specifies the face name to use for highlighting.
@item (@var{matcher} . @var{facespec})
In this kind of element, @var{facespec} is an object which specifies
the face variable to use for highlighting. In the simplest case, it
is a Lisp variable (a symbol), whose value should be a face name.
@example
;; @r{Highlight occurrences of @samp{fubar},}
@ -1943,8 +2035,7 @@ specifies the face name to use for highlighting.
("fubar" . fubar-face)
@end example
The value of @var{facename} is usually a face name (a symbol), but it
can also be a list of the form
However, @var{facespec} can also be a list of the form
@example
(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
@ -1962,21 +2053,22 @@ which specifies how to highlight matches found by @var{matcher}.
It has the form
@example
(@var{subexp} @var{facename} @var{override} @var{laxmatch})
(@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{facename}, specifies the face, as described above.
subelement, @var{facespec}, specifies the face, as described above.
The last two values in @var{highlighter}, @var{override} and
@var{laxmatch}, are 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 @var{facename} is added to the
beginning of the @code{face} property. If it is @code{append}, the face
@var{facename} is added to the end of the @code{face} property.
@var{laxmatch}, are 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}.
@ -2069,7 +2161,11 @@ Its value should have one of the forms described in this table.
to match text which spans lines; this does not work reliably. While
@code{font-lock-fontify-buffer} handles multi-line patterns correctly,
updating when you edit the buffer does not, since it considers text one
line at a time.
line at a time. If you have patterns that typically only span one
line but can occasionally span two or three, such as
@samp{<title>...</title>}, you can ask font-lock to be more careful by
setting @code{font-lock-multiline} to @code{t}. But it still will not
work in all cases.
@node Other Font Lock Variables
@subsection Other Font Lock Variables
@ -2132,11 +2228,25 @@ textual modes.
@end defvar
@defvar font-lock-extra-managed-props
Additional properties (other than @code{face}) that are being managed
by Font Lock mode. Font Lock mode normally manages only the @code{face}
property; if you want it to manage others as well, you must specify
them in a @var{facename} in @code{font-lock-keywords} as well as adding
them to this list.
Additional properties (other than @code{font-lock-face}) that are
being managed by Font Lock mode. Font Lock mode normally manages only
the @code{font-lock-face} property; if you want it to manage others as
well, you must specify them in a @var{facespec} in
@code{font-lock-keywords} as well as adding them to this list.
@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 elements that span
multiple lines, but this is too obscure to document in this manual.
@end defvar
@node Levels of Font Lock
@ -2178,7 +2288,7 @@ 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 conveninent for special modes
@code{font-lock-face} is especially convenient for special modes
which construct their text programmatically, such as
@code{list-buffers} and @code{occur}.
@ -2242,8 +2352,8 @@ where they are defined and where they are used.
@vindex font-lock-constant-face
Used (typically) for constant names.
@item font-locl-preprocessor-face
@vindex font-locl-preprocessor-face
@item font-lock-preprocessor-face
@vindex font-lock-preprocessor-face
Used (typically) for preprocessor commands.
@item font-lock-warning-face
@ -2343,9 +2453,10 @@ are used in other contexts too. For example, the hook
The recommended way to add a hook function to a normal hook is by
calling @code{add-hook} (see below). The hook functions may be any of
the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
a Function}). Most normal hook variables are initially void;
@code{add-hook} knows how to deal with this.
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
@ -2376,17 +2487,17 @@ run particular hooks. This function calls the hook functions that have
been added with @code{add-hook}.
@defun run-hooks &rest hookvars
This function takes one or more hook variable names as arguments, and
runs each hook in turn. Each argument should be a symbol that is a hook
variable. These arguments are processed in the order specified.
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 may be a
function or a list of functions. If the value is a function (either a
lambda expression or a symbol with a function definition), it is called.
If it is a list, the elements are called, in order. The hook functions
are called with no arguments. Nowadays, storing a single function in
the hook variable is semi-obsolete; you should always use a list of
functions.
function or a list of functions. (The former option is considered
obsolete.) If the value is a function (either a lambda expression or
a symbol with a function definition), it is called. If it is a list
that isn't a function, its elements are called, consecutively. All
the hook functions are called with no arguments.
For example, here's how @code{emacs-lisp-mode} runs its mode hook:
@ -2408,33 +2519,33 @@ its parent modes' mode hooks until the end.
@end defmac
@defun run-hook-with-args hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions. It calls each of the hook functions, passing
each of them the arguments @var{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 which passes arguments
to the hook functions, and stops as soon as any hook function fails. It
calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns @code{nil}. Then it stops,
and returns @code{nil} if some hook function returned @code{nil}.
Otherwise it returns a non-@code{nil} value.
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 which passes arguments
to the hook functions, and stops as soon as any 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.
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}. The argument @var{function} may be any valid Lisp
function with the proper number of arguments. For example,
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)
@ -2443,24 +2554,34 @@ function with the proper number of arguments. For example,
@noindent
adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
You can use @code{add-hook} for abnormal hooks as well as for normal
hooks.
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,
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.
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 @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}.
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
@ignore
arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e
@end ignore

325
lispref/nonascii.texi
View file

@ -4,11 +4,11 @@
@c See the file elisp.texi for copying conditions.
@setfilename ../info/characters
@node Non-ASCII Characters, Searching and Matching, Text, Top
@chapter Non-@sc{ascii} Characters
@chapter Non-@acronym{ASCII} Characters
@cindex multibyte characters
@cindex non-@sc{ascii} characters
@cindex non-@acronym{ASCII} characters
This chapter covers the special issues relating to non-@sc{ascii}
This chapter covers the special issues relating to non-@acronym{ASCII}
characters and how they are stored in strings and buffers.
@menu
@ -17,7 +17,7 @@ characters and how they are stored in strings and buffers.
* Selecting a Representation:: Treating a byte sequence as unibyte or multi.
* Character Codes:: How unibyte and multibyte relate to
codes of individual characters.
* Character Sets:: The space of possible characters codes
* 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.
@ -44,8 +44,8 @@ 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 @sc{ascii} characters; the codes from 128 through 255
are used for one non-@sc{ascii} character set (you can choose which
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
@ -96,13 +96,15 @@ default value to @code{nil} early in startup.
@defun position-bytes position
@tindex position-bytes
Return the byte-position corresponding to buffer position @var{position}
in the current buffer.
in the current buffer. If @var{position} is out of range, the value
is @code{nil}.
@end defun
@defun byte-to-position byte-position
@tindex byte-to-position
Return the buffer position corresponding to byte-position
@var{byte-position} in the current buffer.
@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
@ -134,14 +136,14 @@ 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 @sc{ascii} characters
Converting unibyte text to multibyte text leaves @acronym{ASCII} characters
unchanged, and likewise character codes 128 through 159. It converts
the non-@sc{ascii} codes 160 through 255 by adding the value
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-@sc{ascii} characters
'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.
@ -153,10 +155,10 @@ 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-@sc{ascii} character
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-@sc{ascii} range, 128 through 255. However, the functions
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{(-
@ -173,6 +175,9 @@ 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
@ -186,15 +191,35 @@ fails, this function takes just the low 8 bits of each character.
@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, it is returned unchanged.
The function @code{unibyte-char-to-multibyte} is used to convert
each unibyte character to a multibyte character.
@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}. If @var{string} is a multibyte
string, the value is the equal to @var{string}.
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
@ -263,7 +288,7 @@ 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 @sc{ascii} codes
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
@ -280,8 +305,8 @@ text representations.
@end example
If the optional argument @var{genericp} is non-@code{nil}, this
function returns @code{t} if @var{charcode} is a generic character
(@pxref{Splitting Characters}).
function also returns @code{t} if @var{charcode} is a generic
character (@pxref{Splitting Characters}).
@end defun
@node Character Sets
@ -301,8 +326,8 @@ 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}.
@sc{ascii} characters are in character set @code{ascii}. The
non-@sc{ascii} characters 128 through 159 are in character set
@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}.
@ -311,13 +336,19 @@ 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 a list of all defined character set names.
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.
belongs to, or the symbol @code{unknown} if @var{character} is not a
valid character.
@end defun
@defun charset-plist charset
@ -325,9 +356,7 @@ belongs to.
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; for example,
@code{preferred-coding-system} helps determine which coding system to
use to encode characters in a charset.
special purposes within Emacs.
@end defun
@node Chars and Bytes
@ -338,8 +367,8 @@ use to encode characters in a charset.
@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 @sc{ascii} character
set and the @sc{eight-bit-graphic} character set have a zero-length
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
@ -380,6 +409,9 @@ Return a list containing the name of the character set of
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)
@ -401,6 +433,11 @@ or both of @var{code1} and @var{code2} according to the dimension of
(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
@ -423,8 +460,8 @@ For example:
@result{} (latin-iso8859-1 0)
@end example
The character sets @sc{ascii}, @sc{eight-bit-control}, and
@sc{eight-bit-graphic} don't have corresponding generic characters. If
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}.
@ -460,11 +497,19 @@ current buffer.
@cindex character translation tables
@cindex translation tables
A @dfn{translation table} 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.
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
@ -480,24 +525,30 @@ character, say @var{to-alt}, @var{from} is also translated to
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, @var{to} should also be a generic character, for another
character set of the same dimension. Then the translation table
translates each character of @var{from}'s character set into the
corresponding character of @var{to}'s character set.
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{character-translation-table-for-decode}, that specifies
the translation table to use. Otherwise, if
@code{standard-translation-table-for-decode} is non-@code{nil}, decoding
uses that table.
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{character-translation-table-for-encode}, that specifies the
translation table to use. Otherwise the variable
@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.
@ -513,7 +564,12 @@ coding systems that don't specify any other translation table.
@defvar translation-table-for-input
Self-inserting characters are translated through this translation
table before they are inserted.
table before they are inserted. This variable automatically becomes
buffer-local when set.
@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.
@end defvar
@node Coding Systems
@ -669,6 +725,26 @@ interested in.
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
@ -683,7 +759,7 @@ systems as well.
@defun coding-system-p object
This function returns @code{t} if @var{object} is a coding system
name.
name or @code{nil}.
@end defun
@defun check-coding-system coding-system
@ -698,6 +774,9 @@ 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
@ -741,56 +820,80 @@ 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 @sc{ascii} characters, the value
is @code{undecided} or @code{(undecided)}.
If the region contains only @acronym{ASCII} characters, 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 highest
@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{Process Information}, for how to examine or set the coding
systems used for I/O to a subprocess.
@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
@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},
defaulting to the whole buffer if they are @code{nil}. If @var{from}
is a string, the string specifies the text to encode, and @var{to} is
ignored.
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 user's most
preferred coding system (@pxref{Recognize Coding,
prefer-coding-system, the description of @code{prefer-coding-system},
emacs, GNU Emacs Manual}), and after that the current buffer's value
of @code{buffer-file-coding-system} (if it is not @code{undecided}).
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 the coding system selected
without user interaction is acceptable. If this function returns
@code{nil}, the silently selected coding system is rejected, and the
user is asked to select a coding system from a list of possible
candidates.
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
@ -851,9 +954,11 @@ that coding system is used for both reading the file and writing it. If
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 must return a coding
system or a cons cell containing two coding systems. This value is used
as described above.
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.
@end defvar
@defvar process-coding-system-alist
@ -920,7 +1025,7 @@ performing @var{operation} with @var{arguments}. The value has this
form:
@example
(@var{decoding-system} @var{encoding-system})
(@var{decoding-system} . @var{encoding-system})
@end example
The first element, @var{decoding-system}, is the coding system to use
@ -945,7 +1050,6 @@ or port number.
This function looks up the target in @code{file-coding-system-alist},
@code{process-coding-system-alist}, or
@code{network-coding-system-alist}, depending on @var{operation}.
@xref{Default Coding Systems}.
@end defun
@node Specifying Coding Systems
@ -972,8 +1076,8 @@ of the right way to use the variable:
@example
;; @r{Read the file with no character code conversion.}
;; @r{Assume @sc{crlf} represents end-of-line.}
(let ((coding-system-for-write 'emacs-mule-dos))
;; @r{Assume @acronym{crlf} represents end-of-line.}
(let ((coding-system-for-read 'emacs-mule-dos))
(insert-file-contents filename))
@end example
@ -1037,33 +1141,41 @@ decoding functions produce sequences of bytes; the encoding functions
are meant to operate on sequences of bytes. All of these functions
discard text properties.
@defun encode-coding-region start end coding-system
This function encodes the text from @var{start} to @var{end} according
@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.
@end defun
@defun encode-coding-string string coding-system
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. The result of encoding is a unibyte string.
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
@defun decode-coding-region start end coding-system
This function decodes the text from @var{start} to @var{end} according
@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.
@end defun
@defun decode-coding-string string coding-system
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. To make explicit decoding useful, the contents of
@var{string} ought to be a sequence of byte values, but a multibyte
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
@ -1092,22 +1204,22 @@ 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
@defun set-keyboard-coding-system coding-system
This function specifies @var{coding-system} as the coding system to
@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 defun
@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
@defun set-terminal-coding-system coding-system
This function specifies @var{coding-system} as the coding system to use
@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 defun
@end deffn
@node MS-DOS File Types
@subsection MS-DOS File Types
@ -1172,9 +1284,9 @@ from the file contents, in the usual Emacs fashion.
@section Input Methods
@cindex input methods
@dfn{Input methods} provide convenient ways of entering non-@sc{ascii}
@dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII}
characters from the keyboard. Unlike coding systems, which translate
non-@sc{ascii} characters to and from encodings meant to be read by
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
@ -1190,18 +1302,18 @@ in any fashion.) It is @code{nil} if no input method is active in the
buffer now.
@end defvar
@defvar default-input-method
@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 defvar
@end defopt
@defun set-input-method input-method
This function activates input method @var{input-method} for the current
@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 function deactivates any input
If @var{input-method} is @code{nil}, this command deactivates any input
method for the current buffer.
@end defun
@end deffn
@defun read-input-method-name prompt &optional default inhibit-null
This function reads an input method name with the minibuffer, prompting
@ -1237,7 +1349,8 @@ it is good for.
@end defvar
The fundamental interface to input methods is through the
variable @code{input-method-function}. @xref{Reading One Event}.
variable @code{input-method-function}. @xref{Reading One Event},
and @ref{Invoking the Input Method}.
@node Locales
@section Locales
@ -1291,13 +1404,17 @@ through @code{MON_12}).
@item paper
Return a list @code{(@var{width} @var{height})} for the default paper
size measured in milimeters (locale items @code{PAPER_WIDTH} and
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, GNU Libc Manual},
@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

212
lispref/numbers.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/numbers
@ -36,22 +36,22 @@ exact; they have a fixed, limited amount of precision.
@section Integer Basics
The range of values for an integer depends on the machine. The
minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
minimum range is @minus{}268435456 to 268435455 (29 bits; i.e.,
@ifnottex
-2**27
-2**28
@end ifnottex
@tex
@math{-2^{27}}
@math{-2^{28}}
@end tex
to
@ifnottex
2**27 - 1),
2**28 - 1),
@end ifnottex
@tex
@math{2^{27}-1}),
@math{2^{28}-1}),
@end tex
but some machines may provide a wider range. Many examples in this
chapter assume an integer has 28 bits.
chapter assume an integer has 29 bits.
@cindex overflow
The Lisp reader reads an integer as a sequence of digits with optional
@ -62,7 +62,7 @@ initial sign and optional final period.
1. ; @r{The integer 1.}
+1 ; @r{Also the integer 1.}
-1 ; @r{The integer @minus{}1.}
268435457 ; @r{Also the integer 1, due to overflow.}
536870913 ; @r{Also the integer 1, due to overflow.}
0 ; @r{The integer 0.}
-0 ; @r{The integer 0.}
@end example
@ -70,6 +70,9 @@ initial sign and optional final period.
@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
In addition, the Lisp reader recognizes a syntax for integers in
bases other than 10: @samp{#B@var{integer}} reads @var{integer} in
binary (radix 2), @samp{#O@var{integer}} reads @var{integer} in octal
@ -83,10 +86,10 @@ inclusively). Case is not significant for the letter after @samp{#}
bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
view the numbers in their binary form.
In 28-bit binary, the decimal integer 5 looks like this:
In 29-bit binary, the decimal integer 5 looks like this:
@example
0000 0000 0000 0000 0000 0000 0101
0 0000 0000 0000 0000 0000 0000 0101
@end example
@noindent
@ -96,12 +99,12 @@ between groups of 8 bits, to make the binary integer easier to read.)
The integer @minus{}1 looks like this:
@example
1111 1111 1111 1111 1111 1111 1111
1 1111 1111 1111 1111 1111 1111 1111
@end example
@noindent
@cindex two's complement
@minus{}1 is represented as 28 ones. (This is called @dfn{two's
@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
@ -109,24 +112,24 @@ complement} notation.)
@minus{}5 looks like this:
@example
1111 1111 1111 1111 1111 1111 1011
1 1111 1111 1111 1111 1111 1111 1011
@end example
In this implementation, the largest 28-bit binary integer value is
134,217,727 in decimal. In binary, it looks like this:
In this implementation, the largest 29-bit binary integer value is
268,435,455 in decimal. In binary, it looks like this:
@example
0111 1111 1111 1111 1111 1111 1111
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 134,217,727, the value is the
negative integer @minus{}134,217,728:
outside their range, when you add 1 to 268,435,455, the value is the
negative integer @minus{}268,435,456:
@example
(+ 1 134217727)
@result{} -134217728
@result{} 1000 0000 0000 0000 0000 0000 0000
(+ 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
@ -160,16 +163,16 @@ example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
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 IEEE floating point
@cindex @acronym{IEEE} floating point
@cindex positive infinity
@cindex negative infinity
@cindex infinity
@cindex NaN
Most modern computers support the IEEE floating point standard, which
provides for positive infinity and negative infinity as floating point
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{(sqrt -1.0)} returns a
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
@ -186,8 +189,8 @@ these special floating point values:
@end table
In addition, the value @code{-0.0} is distinguishable from ordinary
zero in IEEE floating point (although @code{equal} and @code{=} consider
them equal values).
zero in @acronym{IEEE} floating point (although @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):
@ -376,10 +379,16 @@ it unchanged.
@end defun
There are four functions to convert floating point numbers to integers;
they differ in how they round. These functions accept integer arguments
also, and return such arguments unchanged.
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
@defun truncate number &optional divisor
This returns @var{number}, converted to an integer by rounding towards
zero.
@ -399,10 +408,8 @@ zero.
This returns @var{number}, converted to an integer by rounding downward
(towards negative infinity).
If @var{divisor} is specified, @code{floor} divides @var{number} by
@var{divisor} and then converts to an integer; this uses the kind of
division operation that corresponds to @code{mod}, rounding downward.
An @code{arith-error} results if @var{divisor} is 0.
If @var{divisor} is specified, this uses the kind of division
operation that corresponds to @code{mod}, rounding downward.
@example
(floor 1.2)
@ -418,7 +425,7 @@ An @code{arith-error} results if @var{divisor} is 0.
@end example
@end defun
@defun ceiling number
@defun ceiling number &optional divisor
This returns @var{number}, converted to an integer by rounding upward
(towards positive infinity).
@ -434,7 +441,7 @@ This returns @var{number}, converted to an integer by rounding upward
@end example
@end defun
@defun round number
@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,
@ -465,8 +472,8 @@ commonly used.
if any argument is floating.
It is important to note that in Emacs Lisp, arithmetic functions
do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
@minus{}134217728, depending on your hardware.
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.
@ -562,7 +569,7 @@ 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 IEEE floating point;
infinity or a NaN if your machine supports @acronym{IEEE} floating point;
otherwise, it signals an @code{arith-error} error.
@example
@ -785,19 +792,19 @@ 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
134,217,727 produces @minus{}2 on a 28-bit machine:
268,435,455 produces @minus{}2 on a 29-bit machine:
@example
(lsh 134217727 1) ; @r{left shift}
(lsh 268435455 1) ; @r{left shift}
@result{} -2
@end example
In binary, in the 28-bit implementation, the argument looks like this:
In binary, in the 29-bit implementation, the argument looks like this:
@example
@group
;; @r{Decimal 134,217,727}
0111 1111 1111 1111 1111 1111 1111
;; @r{Decimal 268,435,455}
0 1111 1111 1111 1111 1111 1111 1111
@end group
@end example
@ -807,7 +814,7 @@ which becomes the following when left shifted:
@example
@group
;; @r{Decimal @minus{}2}
1111 1111 1111 1111 1111 1111 1110
1 1111 1111 1111 1111 1111 1111 1110
@end group
@end example
@end defun
@ -830,9 +837,9 @@ looks like this:
@group
(ash -6 -1) @result{} -3
;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
1111 1111 1111 1111 1111 1111 1010
1 1111 1111 1111 1111 1111 1111 1010
@result{}
1111 1111 1111 1111 1111 1111 1101
1 1111 1111 1111 1111 1111 1111 1101
@end group
@end example
@ -841,11 +848,11 @@ In contrast, shifting the pattern of bits one place to the right with
@example
@group
(lsh -6 -1) @result{} 134217725
;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
1111 1111 1111 1111 1111 1111 1010
(lsh -6 -1) @result{} 268435453
;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
1 1111 1111 1111 1111 1111 1111 1010
@result{}
0111 1111 1111 1111 1111 1111 1101
0 1111 1111 1111 1111 1111 1111 1101
@end group
@end example
@ -855,34 +862,34 @@ Here are other examples:
@c with smallbook but not with regular book! --rjc 16mar92
@smallexample
@group
; @r{ 28-bit binary values}
; @r{ 29-bit binary values}
(lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
@result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100}
(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{1111 1111 1111 1111 1111 1111 1011}
@result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100}
(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{0000 0000 0000 0000 0000 0000 0101}
@result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001}
(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{1111 1111 1111 1111 1111 1111 1011}
@result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110}
(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{1111 1111 1111 1111 1111 1111 1011}
@result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110}
(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
@ -919,23 +926,23 @@ because its binary representation consists entirely of ones. If
@smallexample
@group
; @r{ 28-bit binary values}
; @r{ 29-bit binary values}
(logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
@result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
(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{0000 0000 0000 0000 0000 0000 1110}
; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
@result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
(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{1111 1111 1111 1111 1111 1111 1111}
@result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111}
@end group
@end smallexample
@end defun
@ -951,18 +958,18 @@ passed just one argument, it returns that argument.
@smallexample
@group
; @r{ 28-bit binary values}
; @r{ 29-bit binary values}
(logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
@result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
(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{0000 0000 0000 0000 0000 0000 1100}
; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
@result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111}
(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
@ -978,18 +985,18 @@ result is 0, which is an identity element for this operation. If
@smallexample
@group
; @r{ 28-bit binary values}
; @r{ 29-bit binary values}
(logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
@result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001}
(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{0000 0000 0000 0000 0000 0000 1100}
; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
@result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
(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
@ -1004,9 +1011,9 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in
@example
(lognot 5)
@result{} -6
;; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
;; @r{becomes}
;; -6 = @r{1111 1111 1111 1111 1111 1111 1010}
;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010}
@end example
@end defun
@ -1040,8 +1047,8 @@ pi/2
@tex
@math{\pi/2}
@end tex
(inclusive) whose sine is @var{arg}; if, however, @var{arg}
is out of range (outside [-1, 1]), then the result is a NaN.
(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
range (outside [-1, 1]), it signals a @code{domain-error} error.
@end defun
@defun acos arg
@ -1052,8 +1059,8 @@ pi
@tex
@math{\pi}
@end tex
(inclusive) whose cosine is @var{arg}; if, however, @var{arg}
is out of range (outside [-1, 1]), then the result is a NaN.
(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
of range (outside [-1, 1]), it signals a @code{domain-error} error.
@end defun
@defun atan y &optional x
@ -1105,8 +1112,8 @@ If you don't specify @var{base}, the base
@ifnottex
@i{e}
@end ifnottex
is used. If @var{arg}
is negative, the result is a NaN.
is used. If @var{arg} is negative, it signals a @code{domain-error}
error.
@end defun
@ignore
@ -1125,8 +1132,9 @@ lose accuracy.
@defun log10 arg
This function returns the logarithm of @var{arg}, with base 10. If
@var{arg} is negative, the result is a NaN. @code{(log10 @var{x})}
@equiv{} @code{(log @var{x} 10)}, at least approximately.
@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
@ -1138,7 +1146,7 @@ integer values.
@defun sqrt arg
This returns the square root of @var{arg}. If @var{arg} is negative,
the value is a NaN.
it signals a @code{domain-error} error.
@end defun
@node Random Numbers
@ -1163,7 +1171,7 @@ 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 @sc{id} number.
day and on Emacs's process @acronym{ID} number.
@defun random &optional limit
This function returns a pseudo-random integer. Repeated calls return a
@ -1173,10 +1181,14 @@ 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 @sc{id} number.
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

134
lispref/objects.texi
View file

@ -42,7 +42,9 @@ it as a number; Lisp knows it is a vector, not a number.
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.
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
@ -161,24 +163,24 @@ latter are unique to Emacs Lisp.
@node Integer Type
@subsection Integer Type
The range of values for integers in Emacs Lisp is @minus{}134217728 to
134217727 (28 bits; i.e.,
The range of values for integers in Emacs Lisp is @minus{}268435456 to
268435455 (29 bits; i.e.,
@ifnottex
-2**27
-2**28
@end ifnottex
@tex
@math{-2^{27}}
@math{-2^{28}}
@end tex
to
@ifnottex
2**27 - 1)
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+ 134217727)} is @minus{}134217728 on most
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
@ -192,7 +194,7 @@ leading @samp{+} or a final @samp{.}.
1 ; @r{The integer 1.}
1. ; @r{Also the integer 1.}
+1 ; @r{Also the integer 1.}
268435457 ; @r{Also the integer 1 on a 28-bit implementation.}
536870913 ; @r{Also the integer 1 on a 29-bit implementation.}
@end group
@end example
@ -216,7 +218,7 @@ number whose value is 1500. They are all equivalent.
@node Character Type
@subsection Character Type
@cindex @sc{ascii} character codes
@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
@ -226,11 +228,12 @@ example, the character @kbd{A} is represented as the @w{integer 65}.
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 @sc{ascii} codes; the
rest are non-@sc{ascii} (@pxref{Non-ASCII Characters}). Characters that represent
keyboard input have a much wider range, to encode modifier keys such as
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.
@cindex read syntax for characters
@ -323,9 +326,9 @@ equivalent to @samp{?\^I} and to @samp{?\^i}:
@end example
In strings and buffers, the only control characters allowed are those
that exist in @sc{ascii}; but for keyboard input purposes, you can turn
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-@sc{ascii} control characters include the
codes for these non-@acronym{ASCII} control characters include the
@tex
@math{2^{26}}
@end tex
@ -333,7 +336,7 @@ codes for these non-@sc{ascii} control characters include the
2**26
@end ifnottex
bit as well as the code for the corresponding non-control
character. Ordinary terminals have no way of generating non-@sc{ascii}
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.
@ -365,9 +368,8 @@ modifier key. The integer that represents such a character has the
@ifnottex
2**27
@end ifnottex
bit set (which on most machines makes it a negative number). We
use high bits for this and other modifiers to make possible a wide range
of basic character codes.
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
@ -376,11 +378,11 @@ of basic character codes.
@ifnottex
2**7
@end ifnottex
bit attached to an @sc{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 @sc{ascii}
characters. (In Emacs versions 18 and older, this convention was used
for characters outside of strings as well.)
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
@ -390,8 +392,8 @@ 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}.
The case of a graphic character is indicated by its character code;
for example, @sc{ascii} distinguishes between the characters @samp{a}
and @samp{A}. But @sc{ascii} has no way to represent whether a control
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}}
@ -409,15 +411,16 @@ represents the shifted-control-o character.
@cindex hyper characters
@cindex super characters
@cindex alt characters
The X Window System defines three other modifier bits that can be set
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.
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
@ -432,9 +435,9 @@ 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 @sc{ascii}
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 @sc{ascii} representation.
important than the @acronym{ASCII} representation.
@example
@group
@ -915,11 +918,11 @@ but the newline is ignored if escaped."
@end example
@node Non-ASCII in Strings
@subsubsection Non-@sc{ascii} Characters in Strings
@subsubsection Non-@acronym{ASCII} Characters in Strings
You can include a non-@sc{ascii} international character in a string
You can include a non-@acronym{ASCII} international character in a string
constant by writing it literally. There are two text representations
for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
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
@ -927,9 +930,9 @@ 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-@sc{ascii} character with its
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-@sc{ascii} character codes are all
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
@ -938,10 +941,13 @@ 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.
Using a multibyte hex escape forces the string to multibyte. You can
represent a unibyte non-@sc{ascii} character with its character code,
which must be in the range from 128 (0200 octal) to 255 (0377 octal).
This forces a unibyte string.
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.
@xref{Text Representations}, for more information about the two
text representations.
@ -958,14 +964,14 @@ 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 @sc{ascii} control characters. Strings do not
distinguish case in @sc{ascii} control characters.
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 @sc{ascii} characters in a
string. If you use the @samp{\M-} syntax to indicate a meta character
in a string constant, this sets the
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
@ -1082,16 +1088,25 @@ 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. If the length is not a
multiple of 8, the printed representation shows extra elements, but
these extras really make no difference.
correspond to the lowest indices in the bool-vector.
@example
(make-bool-vector 3 t)
@result{} #&3"\007"
@result{} #&3"^G"
(make-bool-vector 3 nil)
@result{} #&3"\0"
;; @r{These are equal since only the first 3 bits are used.}
@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
@ -1484,7 +1499,7 @@ positions.
@cindex @samp{#@var{n}=} read syntax
@cindex @samp{#@var{n}#} read syntax
In Emacs 21, to represent shared or circular structure within a
In Emacs 21, 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}#}.
@ -1875,9 +1890,12 @@ always true.
@end example
Comparison of strings is case-sensitive, but does not take account of
text properties---it compares only the characters in the strings.
A unibyte string never equals a multibyte string unless the
contents are entirely @sc{ascii} (@pxref{Text Representations}).
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
@ -1902,3 +1920,7 @@ returns @code{t} if and only if both the expressions below return
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

34
lispref/os.texi
View file

@ -590,7 +590,7 @@ after a suspension.
Emacs provides access to variables in the operating system environment
through various functions. These variables include the name of the
system, the user's @sc{uid}, and so on.
system, the user's @acronym{UID}, and so on.
@defvar system-configuration
This variable holds the GNU configuration name for the hardware/software
@ -796,6 +796,11 @@ 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.
@example
@group
(load-average)
@ -815,7 +820,7 @@ lewis@@rocky[5] % uptime
@end defun
@defun emacs-pid
This function returns the process @sc{id} of the Emacs process.
This function returns the process @acronym{ID} of the Emacs process.
@end defun
@defvar tty-erase-char
@ -865,7 +870,7 @@ 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 @sc{uid}, not the real @sc{uid}.
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).
@ -880,7 +885,7 @@ to @var{uid} (which should be an integer).
@defun user-real-login-name
This function returns the user name corresponding to Emacs's real
@sc{uid}. This ignores the effective @sc{uid} and ignores the
@acronym{UID}. This ignores the effective @acronym{UID} and ignores the
environment variables @code{LOGNAME} and @code{USER}.
@end defun
@ -916,7 +921,7 @@ variables are also useful for constructing frame titles (@pxref{Frame
Titles}).
@defun user-real-uid
This function returns the real @sc{uid} of the user.
This function returns the real @acronym{UID} of the user.
The value may be a floating point number.
@example
@ -928,7 +933,7 @@ The value may be a floating point number.
@end defun
@defun user-uid
This function returns the effective @sc{uid} of the user.
This function returns the effective @acronym{UID} of the user.
The value may be a floating point number.
@end defun
@ -1005,6 +1010,13 @@ integers. Thus, you can use times obtained from @code{current-time}
(see above) and from @code{file-attributes} (@pxref{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.
@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,
@ -1233,6 +1245,8 @@ 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 Calculations
@ -1292,7 +1306,7 @@ execution is very precise if Emacs is idle.
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 calls a function that takes substantial time to run is likely
timer to call a function that takes substantial time to run is likely
to be annoying.
@defun run-at-time time repeat function &rest args
@ -1928,7 +1942,7 @@ entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
@code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
@kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
was natural and uncontroversial. With so many commands needing key
assignments, of course we assigned meanings to nearly all @sc{ascii}
assignments, of course we assigned meanings to nearly all @acronym{ASCII}
control characters.
Later, some terminals were introduced which required these characters
@ -2073,3 +2087,7 @@ Emacs is restarted by the session manager.
nil)
@end group
@end example
@ignore
arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7
@end ignore

55
lispref/positions.texi
View file

@ -18,7 +18,11 @@ 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. @xref{Markers}.
surrounding characters. Functions that expect an argument to be a
position (an integer), but accept a marker as a substitute, normally
ignore the marker buffer. Of course, markers used this way usually
point to a position in the buffer that the function operates on, but
that is entirely the programmer's responsibility. @xref{Markers}.
See also the ``field'' feature (@pxref{Fields}), which provides
functions that are used by many cursor-motion commands.
@ -89,8 +93,9 @@ that you narrowed to. (@xref{Narrowing}.)
@end defun
@defun buffer-end flag
This function returns @code{(point-min)} if @var{flag} is less than 1,
@code{(point-max)} otherwise. The argument @var{flag} must be a number.
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
@ -185,7 +190,7 @@ In an interactive call, @var{count} is the numeric prefix argument.
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 count
@deffn Command forward-word &optional count
This function moves point forward @var{count} words (or backward if
@var{count} is negative). ``Moving one word'' means moving until point
crosses a word-constituent character and then encounters a
@ -203,19 +208,12 @@ 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.
argument. If @var{count} is omitted or @code{nil}, it defaults to 1.
@end deffn
@deffn Command backward-word count
@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.
In an interactive call, @var{count} is set to the numeric prefix
argument.
@c [Now optimized by compiler.]
@c This function is rarely used in programs, as it is more efficient to
@c call @code{forward-word} with a negative argument.
@end deffn
@defvar words-include-escapes
@ -405,12 +403,18 @@ Here is an example of using @code{count-lines}:
(defun current-line ()
"Return the vertical position of point@dots{}"
(+ (count-lines (window-start) (point))
(if (= (current-column) 0) 1 0)
-1))
(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 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
@ -662,8 +666,8 @@ 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
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
@ -695,13 +699,13 @@ other kinds, such as words and string constants
This function moves backward across @var{arg} (default 1) balanced expressions.
@end deffn
@deffn Command beginning-of-defun arg
@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.
@end deffn
@deffn Command end-of-defun arg
@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.
@ -794,7 +798,7 @@ comes back" twice.
Note that char classes are not currently supported in
@var{character-set}; they will be treated as literals. Thus you
cannot use @code{"[:alpha:]"} instead of @code{"a-zA-Z"} to include
non-ASCII letters. A way to skip forward over all letters is:
non-@acronym{ASCII} letters. A way to skip forward over all letters is:
@example
(re-search-forward "\\=[[:alpha:]]*" nil t)
@ -874,8 +878,9 @@ The value returned by @code{save-excursion} is the result of the last of
@strong{Warning:} Ordinary insertion of text adjacent to the saved
point value relocates the saved value, just as it relocates all markers.
Therefore, when the saved point value is restored, it normally comes
before the inserted text.
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
@ -916,7 +921,7 @@ 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 move-count
@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
@ -996,3 +1001,7 @@ This is the contents of foo@point{}
@end group
@end example
@end defspec
@ignore
arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87
@end ignore

604
lispref/processes.texi
View file

@ -48,6 +48,10 @@ This function returns @code{t} if @var{object} is a process,
* 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::
* Low-Level Network:: Lower-level but more general function
to create connections and servers.
@end menu
@node Subprocess Creation
@ -261,7 +265,7 @@ 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-@sc{ascii} characters are encountered. There are fundamental
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
@ -376,6 +380,13 @@ inputinput@point{}
@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 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.
@ -457,17 +468,17 @@ Arguments}.
@defvar process-connection-type
@cindex pipes
@cindex @sc{pty}s
@cindex @acronym{PTY}s
This variable controls the type of device used to communicate with
asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are
asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are
used, when available. Otherwise, pipes are used.
@sc{pty}s are usually preferable for processes visible to the user, as
@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 @sc{pty}s is limited on many systems and
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
@ -483,7 +494,7 @@ with one subprocess by binding the variable around the call to
@end smallexample
To determine whether a given subprocess actually got a pipe or a
@sc{pty}, use the function @code{process-tty-name} (@pxref{Process
@acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
Information}).
@end defvar
@ -539,10 +550,13 @@ will happen sooner or later).
Several functions return information about processes.
@code{list-processes} is provided for interactive use.
@deffn Command list-processes
@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
@ -583,10 +597,10 @@ were given to the program.
@end defun
@defun process-id process
This function returns the @sc{pid} of @var{process}. This is an
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
@sc{pid} of a process is chosen by the operating system kernel when 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
@ -594,12 +608,6 @@ process is started and remains constant as long as the process exists.
This function returns the name of @var{process}.
@end defun
@defun process-contact process
This function returns @code{t} for an ordinary child process, and
@code{(@var{hostname} @var{service})} for a net connection
(@pxref{Network}).
@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
@ -622,6 +630,12 @@ for a network connection that is open.
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
@ -662,6 +676,7 @@ instead of a terminal (see @code{process-connection-type} in
@ref{Asynchronous Processes}).
@end defun
@anchor{Coding systems for a subprocess}
@defun process-coding-system process
This function returns a cons cell describing the coding systems in use
for decoding output from @var{process} and for encoding input to
@ -677,6 +692,27 @@ 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
@ -689,9 +725,9 @@ 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
@sc{pty}. On these systems, Emacs sends an @sc{eof} periodically amidst
@acronym{PTY}. On these systems, Emacs sends an @acronym{EOF} periodically amidst
the other characters, to force them through. For most programs,
these @sc{eof}s do no harm.
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
@ -747,10 +783,10 @@ is unimportant which number is larger.)
@defun process-send-eof &optional process-name
This function makes @var{process-name} see an end-of-file in its
input. The @sc{eof} comes after any text already sent to it.
input. The @acronym{EOF} comes after any text already sent to it.
If @var{process-name} is not supplied, or if it is @code{nil}, then
this function sends the @sc{eof} to the current buffer's process. An
this function sends the @acronym{EOF} to the current buffer's process. An
error is signaled if the current buffer has no process.
The function returns @var{process-name}.
@ -859,10 +895,12 @@ stopped previously.
@end defun
@c Emacs 19 feature
@defun signal-process pid signal
This function sends a signal to process @var{pid}, which need not be
a child of Emacs. The argument @var{signal} specifies which signal
to send; it should be an integer.
@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.
You can specify the target process by its process @acronym{ID}; that allows
you to send signals to processes that are not children of Emacs.
@end defun
@node Output from Processes
@ -1436,25 +1474,59 @@ Transaction queues are implemented by means of a filter function.
@section Network Connections
@cindex network connection
@cindex TCP
@cindex UDP
Emacs Lisp programs can open TCP 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 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 process at the other end; that process must decide
what to do about closure of the connection.
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
one of the @code{open-network-...} functions descibed below;
internally, they just call @code{make-network-process} with suitable
arguments.
You can distinguish process objects representing network connections
from those representing subprocesses with the @code{process-status}
function. It always returns either @code{open} or @code{closed} for a
network connection, and it never returns either of those values for a
real subprocess. @xref{Process Information}.
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
systems.) 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 for a service to a host. It
returns a process object to represent the connection.
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.
@ -1469,3 +1541,461 @@ 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 open-network-stream-nowait name buffer-or-name host service &optional sentinel filter
This function opens a TCP connection, like @code{open-network-stream},
but it returns immediately without waiting for the request to be
accepted or rejected by the remote server. When the request is
subsequently accepted or rejected, the process's sentinel function
will be called with a string that starts with @code{"open"} (on
success) or @code{"failed"} (on error).
Some systems do not support non-blocking connections; on those
systems, @code{open-network-stream-nowait} returns @code{nil}
and does nothing.
The optional arguments @var{sentinel} and @var{filter} specify the
sentinel and filter functions for this network connection. It is
useful to specify them when opening the connection, because they will
be used later asynchronously. The other arguments mean the same as in
@code{open-network-stream}.
@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, this is 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
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
@defun open-network-stream-server name buffer-or-name service &optional sentinel filter
Create a network server process for a TCP service.
It returns @code{nil} if server processes are not supported; otherwise,
it returns a subprocess-object to represent the server.
When a client connects to the specified service, Emacs creates a new
subprocess to handle the new connection, and then calls its sentinel
function (which it has inherited from the server).
The optional arguments @var{sentinel} and @var{filter} specify the
sentinel and filter functions for the server. It is useful to specify
them now, because they will be used later asynchronously when the
server receives a connection request. The three arguments @var{name},
@var{buffer-or-name} and @var{service} mean the same thing as in
@code{open-network-stream}, but @var{service} can be @code{t}
meaning ask the system to allocate an unused port to listen on.
@end defun
@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
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 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} stands for IPv4. @code{local} specifies a
Unix socket, in which case @var{host} is ignored.
@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 vector of integers @code{[@var{a}
@var{b} @var{c} @var{d} @var{p}]} corresponding to numeric IP address
@var{a}.@var{b}.@var{c}.@var{d} 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 following network options can be specified for the network
process. Except for @code{:reuseaddr}, you can 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 they are 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
The original argument list, modified with the actual connection
information, is available via the @code{process-contact} function.
@end defun
@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
@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. For example, a five-element vector @code{[@var{a} @var{b}
@var{c} @var{d} @var{p}]} represents an IP 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}"}.
If @var{omit-port} is non-@code{nil}, the value does not include
the port number.
@end defun
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 (aka ``UNIX domain'') sockets are 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
Here are some of the option @var{keyword}s 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
@ignore
arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
@end ignore

204
lispref/searching.texi
View file

@ -20,8 +20,8 @@ portions of it.
* Regexp Search:: Searching for a match for a regexp.
* POSIX Regexps:: Searching POSIX-style for the longest match.
* Search and Replace:: Internals of @code{query-replace}.
* Match Data:: Finding out which part of the text matched
various parts of a regexp, after regexp search.
* Match Data:: Finding out which part of the text matched,
after a string or regexp search.
* Searching and Case:: Case-independent or case-significant searching.
* Standard Regexps:: Useful regexps for finding sentences, pages,...
@end menu
@ -90,7 +90,8 @@ 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, leaving point where it started.
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
@ -143,7 +144,7 @@ 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 buffer) and returns @code{nil}.
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.
@ -168,8 +169,8 @@ regexps; the following section says how to search for them.
@menu
* Syntax of Regexps:: Rules for writing regular expressions.
* Regexp Functions:: Functions for operating on regular expressions.
* Regexp Example:: Illustrates regular expression syntax.
* Regexp Functions:: Functions for operating on regular expressions.
@end menu
@node Syntax of Regexps
@ -293,10 +294,10 @@ 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 @sc{ascii} letter. Ranges may be
intermixed freely with individual characters, as in @samp{[a-z$%.]},
which matches any lower case @sc{ascii} letter or @samp{$}, @samp{%} or
period.
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
@ -326,14 +327,14 @@ 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-@sc{ascii} characters with the regular
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-@sc{ascii} characters have codes
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-@sc{ascii} characters (see below regarding @samp{^}),
does match all non-@acronym{ASCII} characters (see below regarding @samp{^}),
in both multibyte and unibyte representations, because only the
@sc{ascii} characters are excluded.
@acronym{ASCII} characters are excluded.
Starting in Emacs 21, a character alternative can also specify named
character classes (@pxref{Char Classes}). This is a POSIX feature whose
@ -358,10 +359,11 @@ the handling of regexps in programs such as @code{grep}.
@item @samp{^}
@cindex beginning of line in regexp
is a special character that matches the empty string, but only at the
beginning of a line in the text being matched. Otherwise it fails to
match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
the beginning of a line.
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.
@ -372,8 +374,9 @@ beginning of the regular expression, or after @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. Thus,
@samp{x+$} matches a string of one @samp{x} or more at the end of a line.
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.
@ -415,7 +418,7 @@ in Emacs 21, and what they mean:
@table @samp
@item [:ascii:]
This matches any @sc{ascii} (unibyte) character.
This matches any @acronym{ASCII} (unibyte) character.
@item [:alnum:]
This matches any letter or digit. (At present, for multibyte
characters, it matches anything that has word syntax.)
@ -425,20 +428,20 @@ matches anything that has word syntax.)
@item [:blank:]
This matches space and tab only.
@item [:cntrl:]
This matches any @sc{ascii} control character.
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 @sc{ascii} control
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 [:nonascii:]
This matches any non-@sc{ascii} (multibyte) character.
This matches any non-@acronym{ASCII} (multibyte) character.
@item [:print:]
This matches printing characters---everything except @sc{ascii} control
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
@ -494,7 +497,7 @@ 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 more general postfix operator that specifies repetition with a
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.
@ -542,7 +545,7 @@ 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 particulary useful for mechanically-constructed regular
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.
@ -567,6 +570,10 @@ 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
@ -611,7 +618,9 @@ matches any character whose category is not @var{c}.
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.
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 \`
@ -636,25 +645,25 @@ 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
@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.
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 only if a
@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 only if the contents end with a
word-constituent character.
matches at the end of the buffer (or string) only if the contents end
with a word-constituent character.
@end table
@kindex invalid-regexp
@ -668,9 +677,11 @@ an @code{invalid-regexp} error is signaled.
@comment node-name, next, previous, up
@subsection Complex Regexp Example
Here is a complicated regexp, used by Emacs to recognize the end of a
sentence together with any whitespace that follows. It is the value of
the variable @code{sentence-end}.
Here is a complicated regexp which was formerly used by Emacs to
recognize the end of a sentence together with any whitespace that
follows. It was used as the variable @code{sentence-end}. (Its value
nowadays contains alternatives for @samp{.}, @samp{?} and @samp{!} in
other character sets.)
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
@ -679,17 +690,16 @@ 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]*"
"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
@end example
@noindent
In contrast, if you evaluate the variable @code{sentence-end}, you
will see the following:
In contrast, if you evaluate this string, you will see the following:
@example
@group
sentence-end
@result{} "[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
@result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[
]*"
@end group
@end example
@ -704,7 +714,10 @@ deciphered as follows:
@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.
mark. The match must begin with one of these three characters. (This
is the one point where the new value of @code{sentence-end} differs
from the old. The new value also lists sentence ending
non-@acronym{ASCII} characters.)
@item []\"')@}]*
The second part of the pattern matches any closing braces and quotation
@ -764,13 +777,14 @@ whitespace:
@defun regexp-opt strings &optional paren
This function returns an efficient regular expression that will match
any of the strings @var{strings}. This is useful when you need to make
matching or searching as fast as possible---for example, for Font Lock
mode.
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.
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
@ -788,7 +802,8 @@ regular expression which is equivalent to the actual value
@defun regexp-opt-depth regexp
This function returns the total number of grouping constructs
(parenthesized expressions) in @var{regexp}.
(parenthesized expressions) in @var{regexp}. (This does not include
shy groups.)
@end defun
@node Regexp Search
@ -830,7 +845,7 @@ error is signaled. If @var{noerror} is @code{t},
@code{re-search-forward} does nothing and returns @code{nil}. If
@var{noerror} is neither @code{nil} nor @code{t}, then
@code{re-search-forward} moves point to @var{limit} (or the end of the
buffer) and returns @code{nil}.
accessible portion of the buffer) and returns @code{nil}.
In the following example, point is initially before the @samp{T}.
Evaluating the search call moves point to the end of that line (between
@ -866,9 +881,10 @@ 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. 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.
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
@ -1069,7 +1085,8 @@ 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 buffer's end is used for @var{end}.
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.
@ -1090,7 +1107,7 @@ get the replacement text. This function is called with two arguments:
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 cyclicly to the next one.
@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
@ -1099,6 +1116,22 @@ 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}, is a
keymap to use instead of @code{query-replace-map}.
@strong{Usage note:} Do not use this function in your own programs
unless you want to do something very similar to what
@code{query-replace} does, including setting the mark and possibly
querying the user. For most purposes a simple loop like, for
instance:
@example
(while (re-search-forward "foo[ \t]+bar" nil t)
(replace-match "foobar"))
@end example
@noindent
is preferable. It runs faster and avoids side effects, such as
setting the mark. @xref{Replacing Match,, Replacing the Text that
Matched}, for a description of @code{replace-match}.
@end defun
@defvar query-replace-map
@ -1173,10 +1206,9 @@ Display some help, then ask again.
@cindex match data
Emacs keeps track of the start and end positions of the segments of
text found during a regular expression search. This means, for example,
that you can search for a complex pattern, such as a date in an Rmail
message, and then extract parts of the match under control of the
pattern.
text found during a search. This means, for example, that you can
search for a complex pattern, such as a date in an Rmail 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
@ -1205,9 +1237,11 @@ 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}. 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}.
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
@ -1239,6 +1273,7 @@ part of one of the following sequences:
@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
@ -1396,7 +1431,7 @@ character of the buffer counts as 1.)
The functions @code{match-data} and @code{set-match-data} read or
write the entire match data, all at once.
@defun match-data
@defun match-data &optional integers reuse
This function returns a newly constructed list containing 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
@ -1420,8 +1455,20 @@ number {\mathsurround=0pt $2n+1$}
corresponds to @code{(match-end @var{n})}.
All the elements are markers or @code{nil} if matching was done on a
buffer, and all are integers or @code{nil} if matching was done on a
string with @code{string-match}.
buffer and all are integers or @code{nil} if matching was done on a
string with @code{string-match}. If @var{integers} is
non-@code{nil}, then all elements are integers or @code{nil}, even if
matching was done on a buffer. Also, @code{match-beginning} and
@code{match-end} always return integers or @code{nil}.
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 avoid producing too
much garbage, that would later have to be collected.
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
@ -1474,7 +1521,8 @@ that shows the problem that arises if you fail to save the match data:
@defmac save-match-data body@dots{}
This macro executes @var{body}, saving and restoring the match
data around it.
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
@ -1544,10 +1592,11 @@ 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 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 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}.
@ -1600,23 +1649,28 @@ spaces, tabs, and form feeds (after its left margin).
@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{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,
newline, or form feed (after its left margin).
@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
This is the regular expression describing the end of a sentence. (All
paragraph boundaries also end sentences, regardless.) The default value
is:
paragraph boundaries also end sentences, regardless.) The (slightly
simplified) default value is:
@example
"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
@end example
This means a period, question mark or exclamation mark, followed
optionally by a closing parenthetical character, followed by tabs,
spaces or new lines.
This means a period, question mark or exclamation mark (the actual
default value also lists their alternatives in other character sets),
followed optionally by closing parenthetical characters, followed by
tabs, spaces or new lines.
For a detailed explanation of this regular expression, see @ref{Regexp
Example}.
@end defvar
@ignore
arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f
@end ignore

37
lispref/sequences.texi
View file

@ -69,8 +69,8 @@ elements. This section describes functions that accept any kind of
sequence.
@defun sequencep object
Returns @code{t} if @var{object} is a list, vector, or
string, @code{nil} otherwise.
Returns @code{t} if @var{object} is a list, vector,
string, bool-vector, or char-table, @code{nil} otherwise.
@end defun
@defun length sequence
@ -78,10 +78,12 @@ string, @code{nil} otherwise.
@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 cons cell that is not a list (because the final
@sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
signaled.
signaled. For a char-table, the value returned is always one more
than the maximum Emacs character code.
@xref{List Elements}, for the related function @code{safe-length}.
@ -109,6 +111,13 @@ signaled.
@end example
@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 is greater than
@code{(length @var{string})}.
@end defun
@defun elt sequence index
@cindex elements of sequences
This function returns the element of @var{sequence} indexed by
@ -163,8 +172,8 @@ list. However, the actual values of the properties are shared.
@xref{Text Properties}.
See also @code{append} in @ref{Building Lists}, @code{concat} in
@ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for other
ways to copy sequences.
@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions},
for other ways to copy sequences.
@example
@group
@ -313,7 +322,7 @@ first element is at index zero.
@end group
@group
(aref "abcdefg" 1)
@result{} 98 ; @r{@samp{b} is @sc{ascii} code 98.}
@result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.}
@end group
@end example
@ -489,14 +498,11 @@ 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}.
The @code{vconcat} function also allows integers as arguments. It
converts them to strings of digits, making up the decimal print
representation of the integer, and then uses the strings instead of the
original integers. @strong{Don't use this feature; we plan to eliminate
it. If you already use this feature, change your programs now!} 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}).
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}
@ -722,3 +728,6 @@ bv
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

31
lispref/streams.texi
View file

@ -361,7 +361,9 @@ 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.
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
@ -685,6 +687,13 @@ The value of this variable is the default output stream---the stream
that print functions use when the @var{stream} argument is @code{nil}.
@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
@ -721,24 +730,24 @@ In the second expression, the local binding of
@end defvar
@defvar print-escape-nonascii
If this variable is non-@code{nil}, then unibyte non-@sc{ascii}
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-@sc{ascii}
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-@sc{ascii}
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-@sc{ascii} characters, regardless of the value of this variable,
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
@ -771,6 +780,14 @@ 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---but they are only defined in Emacs 21.
@ -803,3 +820,7 @@ 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
@ignore
arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434
@end ignore

267
lispref/strings.texi
View file

@ -44,7 +44,7 @@ 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 @sc{ascii} code 0.)
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.
@ -52,10 +52,10 @@ operate on them with the general array and sequence functions.
change individual characters in a string using the functions @code{aref}
and @code{aset} (@pxref{Array Functions}).
There are two text representations for non-@sc{ascii} characters in
There are two text representations for non-@acronym{ASCII} characters in
Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
Representations}). An @sc{ascii} character always occupies one byte in a
string; in fact, when a string is all @sc{ascii}, there is no real
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.
@ -66,8 +66,8 @@ 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 @sc{ascii} control characters, but no other
control characters. They do not distinguish case in @sc{ascii} control
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
@ -172,7 +172,7 @@ 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 as an index, it stands for the length of the
When @code{nil} is used for @var{end}, it stands for the length of the
string. Thus,
@example
@ -208,10 +208,11 @@ For example:
@result{} [b (c)]
@end example
A @code{wrong-type-argument} error is signaled if either @var{start} or
@var{end} is not an integer or @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}.
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
@ -219,6 +220,14 @@ 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
@ -255,11 +264,11 @@ printed form is with @code{format} (@pxref{Formatting Strings}) or
For information about other concatenation functions, see the
description of @code{mapconcat} in @ref{Mapping Functions},
@code{vconcat} in @ref{Vectors}, and @code{append} in @ref{Building
@code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building
Lists}.
@end defun
@defun split-string string separators omit-nulls
@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
@ -280,42 +289,71 @@ null strings are always omitted from the result. Thus:
@example
(split-string " two words ")
@result{} ("two" "words")
@result{} ("two" "words")
@end example
The result is not @samp{("" "two" "words" "")}, which would rarely be
useful. If you need such a result, use an explict value for
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" "")
@result{} ("" "two" "words" "")
@end example
More examples:
@example
(split-string "Soup is good food" "o")
@result{} ("S" "up is g" "" "d f" "" "d")
@result{} ("S" "up is g" "" "d f" "" "d")
(split-string "Soup is good food" "o" t)
@result{} ("S" "up is g" "d f" "d")
@result{} ("S" "up is g" "d f" "d")
(split-string "Soup is good food" "o+")
@result{} ("S" "up is g" "d f" "d")
@result{} ("S" "up is g" "d f" "d")
@end example
Empty matches do count, when not adjacent to another match:
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 "Soup is good food" "o*")
@result{}("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
(split-string "Nice doggy!" "")
@result{}("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
(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}, initially
@samp{"[ \f\t\n\r\v]+"}.
@w{@samp{"[ \f\t\n\r\v]+"}}.
@end defvar
@node Modifying Strings
@ -339,6 +377,14 @@ 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 clears the contents of @var{string} to zeros
and may change its length.
@end defun
@need 2000
@ -362,7 +408,8 @@ in case if @code{case-fold-search} is non-@code{nil}.
@defun string= string1 string2
This function returns @code{t} if the characters of the two strings
match exactly.
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
@ -378,8 +425,20 @@ 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=}.
If the strings contain non-@sc{ascii} characters, and one is unibyte
while the other is multibyte, then they cannot be equal. @xref{Text
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
@ -400,11 +459,11 @@ function returns @code{t}. If the lesser character is the one from
Pairs of characters are compared according to their character codes.
Keep in mind that lower case letters have higher numeric values in the
@sc{ascii} character set than their upper case counterparts; digits and
@acronym{ASCII} character set than their upper case counterparts; digits and
many punctuation characters have a lower numeric value than upper case
letters. An @sc{ascii} character is less than any non-@sc{ascii}
character; a unibyte non-@sc{ascii} character is always less than any
multibyte non-@sc{ascii} character (@pxref{Text Representations}).
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
@ -436,6 +495,9 @@ no characters is less than any other 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
@ -451,9 +513,10 @@ 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 can be equal to
a multibyte string. If @var{ignore-case} is non-@code{nil}, then case
is ignored, so that upper case letters can be equal to lower case letters.
(@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
@ -463,16 +526,14 @@ two strings. The sign is negative if @var{string1} (or its specified
portion) is less.
@end defun
@defun assoc-ignore-case key alist
@defun assoc-string key alist &optional case-fold
This function works like @code{assoc}, except that @var{key} must be a
string, and comparison is done using @code{compare-strings}, ignoring
case differences. @xref{Association Lists}.
@end defun
@defun assoc-ignore-representation key alist
This function works like @code{assoc}, except that @var{key} must be a
string, and comparison is done using @code{compare-strings}.
Case differences are significant.
string, and comparison is done using @code{compare-strings}. 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 rather than conses. In particular, @var{alist} can
be a list of strings rather than an actual alist.
@xref{Association Lists}.
@end defun
See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
@ -509,7 +570,7 @@ This function returns a new string containing one character,
@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, @sc{ascii} code
first character of @var{string} is the null character, @acronym{ASCII} code
0.
@example
@ -540,8 +601,10 @@ 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
@ -555,20 +618,22 @@ See also the function @code{format} in @ref{Formatting Strings}.
@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}, integers are converted
in that base. If @var{base} is @code{nil}, then base ten is used.
Floating point conversion always uses 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,
@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. (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, nor a plus or minus sign, nor the leading dot of a
floating point number, this function returns 0.
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")
@ -670,16 +735,12 @@ Starting in Emacs 21, 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.
If there is no corresponding object, the empty string is used.
@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.
If there is no corresponding object, the empty string is used.
@item %o
@cindex integer to octal
Replace the specification with the base-eight representation of an
@ -737,17 +798,20 @@ operation} error.
@end group
@end example
@cindex numeric prefix
@cindex field width
@cindex padding
All the specification characters allow an optional numeric prefix
between the @samp{%} and the character. The optional numeric prefix
defines the minimum width for the object. If the printed representation
of the object contains fewer characters than this, then it is padded.
The padding is on the left if the prefix is positive (or starts with
zero) and on the right if the prefix is negative. The padding character
is normally a space, but if the numeric prefix starts with a zero, zeros
are used for padding. Here are some examples of padding:
All the specification characters allow an optional ``width'', which
is a digit-string between the @samp{%} and the character. If the
printed representation of the object contains fewer characters than
this width, then it is padded. The padding is 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 if
the width starts with a zero, zeros are used for padding. 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)
@ -757,10 +821,9 @@ are used for padding. Here are some examples of padding:
@result{} "123 is padded on the right"
@end example
@code{format} never truncates an object's printed representation, no
matter what width you specify. Thus, you can use a numeric prefix to
specify a minimum spacing between columns with no risk of losing
information.
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
@ -788,6 +851,32 @@ not truncated. In the third case, the padding is on the right.
@end group
@end smallexample
@cindex precision in format specifications
All the specification characters allow an optional ``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 is ignored 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.
A space character inserts a space for positive numbers (otherwise
nothing is inserted for positive numbers). This flag is ignored
except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}.
The flag @samp{#} indicates ``alternate form''. For @samp{%o} it
ensures that the result begins with a 0. For @samp{%x} and @samp{%X}
the result is prefixed with @samp{0x} or @samp{0X}. For @samp{%e},
@samp{%f}, and @samp{%g} a decimal point is always shown even if the
precision is zero.
@node Case Conversion
@comment node-name, next, previous, up
@section Case Conversion in Lisp
@ -799,7 +888,7 @@ not truncated. In the third case, the padding is on the right.
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-@sc{ascii} letters); other
@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}).
@ -807,7 +896,7 @@ conversion mapping by specifying a case table (@pxref{Case Tables}).
arguments.
The examples below use the characters @samp{X} and @samp{x} which have
@sc{ascii} codes 88 and 120 respectively.
@acronym{ASCII} codes 88 and 120 respectively.
@defun downcase string-or-char
This function converts a character or a string to lower case.
@ -867,11 +956,15 @@ 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)
@ -880,16 +973,20 @@ has the same result as @code{upcase}.
@end example
@end defun
@defun upcase-initials string
This function capitalizes the initials of the words in @var{string},
without altering any letters other than the initials. It returns a new
string whose contents are a copy of @var{string}, in which each word has
@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")
@ -944,9 +1041,9 @@ 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 cyclicly permutes
The extra table @var{equivalences} is a map that cyclically permutes
each equivalence class (of characters with the same canonical
equivalent). (For ordinary @sc{ascii}, this would map @samp{a} into
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.)
@ -983,7 +1080,7 @@ This sets the current buffer's case table to @var{table}.
@end defun
The following three functions are convenient subroutines for packages
that define non-@sc{ascii} character sets. They modify the specified
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.
@ -1007,3 +1104,7 @@ This function makes @var{char} case-invariant, with syntax
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

17
lispref/symbols.texi
View file

@ -360,6 +360,7 @@ This variable is the standard obarray for use by @code{intern} and
@code{read}.
@end defvar
@anchor{Definition of mapatoms}
@defun mapatoms function &optional obarray
This function calls @var{function} once with each symbol in the obarray
@var{obarray}. Then it returns @code{nil}. If @var{obarray} is
@ -475,7 +476,7 @@ This function returns the property list of @var{symbol}.
@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.
not enforced. The return value is @var{plist}.
@smallexample
(setplist 'foo '(a 1 b (2 3) c nil))
@ -560,6 +561,16 @@ in the place where you got @var{plist}. For example,
(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
@tindex plist-member
This returns non-@code{nil} if @var{plist} contains the given
@ -568,3 +579,7 @@ 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

90
lispref/syntax.texi
View file

@ -397,10 +397,13 @@ prefix (@samp{'}). @xref{Motion and Syntax}.
In this section we describe functions for creating, accessing and
altering syntax tables.
@defun make-syntax-table
This function creates a new syntax table. It inherits the syntax for
letters and control characters from the standard syntax table. For
other characters, the syntax is copied from the standard syntax table.
@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
@ -408,7 +411,7 @@ Most major mode syntax tables are created in this way.
@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
current syntax table. Otherwise, an error is signaled if @var{table} is
standard syntax table. Otherwise, an error is signaled if @var{table} is
not a syntax table.
@end defun
@ -425,7 +428,7 @@ 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 twelve syntax class designator characters. An error is also
one of the seventeen syntax class designator characters. An error is also
signaled if @var{char} is not a character.
@example
@ -559,10 +562,11 @@ table.
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}. 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.
This function moves point forward across characters having syntax
classes mentioned in @var{syntaxes} (a string of syntax code
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}.
@ -697,9 +701,10 @@ that can be nested.
The minimum parenthesis depth encountered during this scan.
@item
What kind of comment is active: @code{nil} for a comment of style ``a'',
@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.
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
@ -710,6 +715,12 @@ this element is @code{nil}.
Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.
Actually, the return value is currently a list of ten, rather than
nine, elements and @var{state} is allowed to be a list of ten elements
as well. However, the meaning of the tenth element is subject to
change and only the first eight elements of @var{state} need to be
specified.
@cindex indenting with parentheses
This function is most often used to compute indentation for languages
that have nested parentheses.
@ -752,22 +763,20 @@ before count is used up, @code{nil} is returned.
@defvar multibyte-syntax-as-symbol
@tindex multibyte-syntax-as-symbol
If this variable is non-@code{nil}, @code{scan-sexps} treats all
non-@sc{ascii} characters as symbol constituents regardless
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
@defvar parse-sexp-ignore-comments
@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}.
@end defopt
In older Emacs versions, this feature worked only when the comment
terminator is something like @samp{*/}, and appears only to end a
comment. In languages where newlines terminate comments, it was
necessary make this variable @code{nil}, since not every newline is the
end of a comment. This limitation no longer exists.
@end defvar
@vindex parse-sexp-lookup-properties
The behaviour 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.
@ -781,7 +790,9 @@ 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.
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
@ -940,7 +951,7 @@ 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 @sc{ascii} printing character in
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}.
@ -951,12 +962,12 @@ 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}.
The new category is defined for category table @var{table}, which
defaults to the current buffer's category table.
documentation @var{docstring}, for the category table @var{table},
@end defun
@defun category-docstring category &optional table
@ -971,7 +982,7 @@ in category table @var{table}.
@end example
@end defun
@defun get-unused-category table
@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}.
@ -993,7 +1004,7 @@ This function returns the standard category table.
@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
current category table. Otherwise, an error is signaled if @var{table}
standard category table. Otherwise, an error is signaled if @var{table}
is not a category table.
@end defun
@ -1023,11 +1034,11 @@ other categories.
@end defun
@defun char-category-set char
This function returns the category set for character @var{char}. 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.
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)
@ -1056,8 +1067,13 @@ But if @var{reset} is non-@code{nil}, then it deletes @var{category}
instead.
@end defun
@deffn Command describe-categories
@deffn Command describe-categories &optional buffer-or-name
This function describes the category specifications in the current
category table. The descriptions are inserted in a buffer, which is
then displayed.
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

409
lispref/text.texi
View file

@ -58,6 +58,7 @@ the character after point.
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
@ -68,6 +69,9 @@ the character after 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
@ -158,7 +162,7 @@ the end of a line.
@node Buffer Contents
@section Examining Buffer Contents
This section describes two functions that allow a Lisp program to
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
@ -229,9 +233,9 @@ This is the contents of buffer foo
This function returns the symbol (or word) at or near point, as a string.
The return value includes no text properties.
The optional argument @var{really-word} is non-@code{nil}, it finds a
word; otherwise, it finds a symbol (which includes word characters and
both symbol constituent characters).
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
@ -272,10 +276,10 @@ 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 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.
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
@ -350,16 +354,16 @@ unless all @var{args} are either strings or characters. The value is
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 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.
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 a
number (@code{nil} means 1), and @var{character} must be a character.
The value is @code{nil}.
number, 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
@ -373,7 +377,7 @@ insertion point. @xref{Sticky Properties}.
@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 from @var{start} and @var{end}. (These
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}.
@ -396,6 +400,11 @@ 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
@ -411,9 +420,10 @@ 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 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}.
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
@ -494,11 +504,11 @@ 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, and all
return a value of @code{nil}.
All of the deletion functions operate on the current buffer.
@deffn Command erase-buffer
This function deletes the entire text of the current buffer, leaving it
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
@ -584,8 +594,9 @@ The value returned is always @code{nil}.
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 the whitespace characters before point
with one command, and @code{nil}, meaning do nothing special for
@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
@ -596,11 +607,14 @@ whitespace characters.
commands intended primarily for the user but useful also in Lisp
programs.
@deffn Command delete-horizontal-space
@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.
@ -666,9 +680,10 @@ After the lines are joined, the function @code{fixup-whitespace} is
responsible for deciding whether to leave a space at the junction.
@end deffn
@defun fixup-whitespace
This function replaces all the whitespace surrounding point with either
one space or no space, according to the context. It returns @code{nil}.
@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
@ -702,7 +717,7 @@ This has too many spaces at the start of (this list)
---------- Buffer: foo ----------
@end group
@end smallexample
@end defun
@end deffn
@deffn Command just-one-space
@comment !!SourceFile simple.el
@ -715,7 +730,7 @@ 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 following it.
blank lines immediately following it.
A blank line is defined as a line containing only tabs and spaces.
@ -761,9 +776,10 @@ 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.
* Internals of Kill Ring:: Variables that hold kill ring data.
@end menu
@node Kill Ring Concepts
@ -783,7 +799,7 @@ 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
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.
@ -805,7 +821,7 @@ 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
@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}.
@ -818,6 +834,12 @@ 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
@ -829,9 +851,7 @@ updating the kill ring but not changing the buffer.
@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}. It also indicates the extent
of the text copied by moving the cursor momentarily, or by displaying a
message in the echo area.
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.
@ -842,6 +862,67 @@ support Emacs 18. For newer Emacs versions, it is better to use
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
@ -851,23 +932,29 @@ from the kill ring. The text properties are copied too.
@deffn Command yank &optional arg
@cindex inserting killed text
This command inserts before point the text in the first entry in the
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 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 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.
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 or rotate it.
It returns @code{nil}.
@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 arg
@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.
@ -876,6 +963,8 @@ This is allowed only immediately after a @code{yank} or another
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
@ -889,6 +978,18 @@ 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
@ -908,23 +1009,44 @@ 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.
@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
This function puts the text @var{string} into the kill ring as a new
entry at the front of the ring. It discards the oldest entry if
appropriate. It also invokes the value of
@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
@defun kill-append string before-p &optional yank-handler
This function appends the text @var{string} to the first entry in the
kill ring. Normally @var{string} goes at the end of the entry, but if
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).
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
@ -935,7 +1057,7 @@ programs, when you are using a window system. Its value should be
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 first element of @code{kill-ring} is used.
@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
@ -945,13 +1067,17 @@ another application. @xref{Window System Selections}.
@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 argument.
@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 an argument.
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 from the newly killed text. @xref{Window System Selections}.
selection (and first cut buffer) from the newly killed text.
@xref{Window System Selections}.
@end defvar
@node Internals of Kill Ring
@ -1024,7 +1150,7 @@ that @kbd{C-y} should yank.
@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 30.
value for @code{kill-ring-max} is 60.
@end defopt
@node Undo
@ -1061,7 +1187,9 @@ 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})}.
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
@ -1153,13 +1281,13 @@ 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
@deffnx Command buffer-flush-undo &optional buffer
@deffn Command buffer-disable-undo &optional buffer-or-name
@deffnx Command buffer-flush-undo &optional buffer-or-name
@cindex disable undo
This function discards the undo list of @var{buffer}, and disables
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} is already disabled, this function
the undo list of @var{buffer-or-name} is already disabled, this function
has no effect.
This function returns @code{nil}.
@ -1622,7 +1750,7 @@ 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.
the sort order."
@end group
@group
(interactive "P\nr")
@ -1803,7 +1931,8 @@ 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.
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
@ -2145,16 +2274,18 @@ current line (which is the line in which point is located). It returns
@code{nil}.
@end deffn
@deffn Command backward-to-indentation arg
@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 arg
@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
@ -2320,7 +2451,7 @@ has a category that is a symbol, then @code{get-text-property} returns
the @var{prop} property of that symbol.
@end defun
@defun get-char-property pos prop &optional object
@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}.
@ -2333,6 +2464,20 @@ 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
@ -2435,6 +2580,12 @@ To remove all text properties from certain text, use
list.
@end defun
@defun remove-list-of-text-properties start end list-of-properties &optional object
Like @code{remove-list-properties} except that
@var{list-of-properties} is a list property names only, not an
alternating list of property 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}.
@ -2765,11 +2916,13 @@ The @code{keymap} property specifies an additional keymap for
commands. 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. When the value applies, it is used for key lookup
before the buffer's local map. (For mouse clicks, the position of the
click is used instead of the position of point.) If the property
value is a symbol, the symbol's function definition is used as the
keymap. @xref{Active Keymaps}.
front-sticky. (For mouse clicks, the position of the click is used
instead of the position of point.) If the property value is a symbol,
the symbol's function definition is used as the keymap.
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}.
@item local-map
@kindex local-map @r{(text property)}
@ -2876,9 +3029,9 @@ 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 using @code{char-after} to examine characters at various
positions without moving point to those positions. Only an actual
change in the value of point runs these hook 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.
@end table
@defvar inhibit-point-motion-hooks
@ -3425,7 +3578,7 @@ translation table.
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 @sc{ascii} characters and their meta variants
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.
@ -3593,7 +3746,7 @@ all markers unrelocated.
@cindex base 64 encoding
Base 64 code is used in email to encode a sequence of 8-bit bytes as
a longer sequence of @sc{ascii} graphic characters. It is defined in
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
@ -3697,6 +3850,96 @@ using the specified or chosen coding system. However, if
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
@ -3732,7 +3975,7 @@ changed text, its length is simply the difference between the first two
arguments.
@end defvar
Output of messges into the @samp{*Messages*} buffer does not
Output of messages into the @samp{*Messages*} buffer does not
call these functions.
@defmac combine-after-change-calls body...
@ -3751,7 +3994,7 @@ made within the @code{combine-after-change-calls} body.
@code{after-change-functions} within
the body of a @code{combine-after-change-calls} form.
@strong{Note:} If the changes you combine occur in widely scattered
@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.
@ -3801,3 +4044,7 @@ properties (@pxref{Overlay Properties}).
This variable is available starting in Emacs 21.
@end defvar
@ignore
arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
@end ignore

1
lispref/tindex.pl
View file

@ -123,3 +123,4 @@ sub fatal {
print " $key\n";
}
# arch-tag: f8460df6-6bef-4c98-8555-e2c63a88b0fa

71
lispref/tips.texi
View file

@ -125,6 +125,12 @@ add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}.
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 reserved keys
@cindex keys, reserved
@ -204,7 +210,15 @@ off, and make it autoload (@pxref{Autoload}). Design the package so
that simply loading it has no visible effect---that should not enable
the feature.@footnote{Consider that the package may be loaded
arbitrarily by Custom for instance.} Users will request the feature by
invoking the command.
invoking the command. It is a good idea to define this command
as a minor mode.
@cindex unloading packages
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. Use the
@ -235,6 +249,13 @@ 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
Avoid using macros that define functions and variables with names that
are constructed. It is best for maintenance when the name of the
function or variable being defined is given explicitly in the source
code, as the second element of the list---as it is when you use
@code{defun}, @code{defalias}, @code{defvar} and @code{defopt}.
@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
@ -517,7 +538,7 @@ important arguments.
@item
For consistency, phrase the verb in the first sentence of a function's
documentation string as an imperative--for instance, use ``Return the
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
@ -626,6 +647,7 @@ The argument FOO can be either a number
This prevents the open-parenthesis from being treated as the start of a
defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
@anchor{Docstring hyperlinks}
@item
@iftex
When a documentation string refers to a Lisp symbol, write it as it
@ -674,9 +696,20 @@ that satisfy the criterion.
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 in single quotes, preceded by @samp{info node} or @samp{Info
node}. The Info file name defaults to @samp{emacs}. For example,
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'.
@ -769,19 +802,30 @@ 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 there is a matter of style.
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.
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.
;;; 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
@ -850,7 +894,8 @@ if we haven't installed it in Emacs yet!
@end example
@noindent
The description should be complete in one line.
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
@ -926,9 +971,9 @@ It should come right after the copying permissions, terminated by a
text is used by the Finder package, so it should make sense in that
context.
@item ;;; Documentation
This has been used in some files in place of @samp{;;; Commentary:},
but @samp{;;; Commentary:} is preferred.
@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
@ -945,3 +990,7 @@ 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

2
lispref/two.el
View file

@ -57,3 +57,5 @@ This is for the *Elisp Ref Manual*"
(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

183
lispref/variables.texi
View file

@ -43,6 +43,8 @@ variable.
* Future Local Variables:: New kinds of local values we might add some day.
* Variable Aliases:: Variables that are aliases for other variables.
* File Local Variables:: Handling local variable lists in files.
* Variables with Restricted Values:: Non-constant variables whose value can
@emph{not} be an arbitrary Lisp object.
@end menu
@node Global Variables
@ -198,18 +200,18 @@ 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.
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)
(setq y 2)
@result{} 2
@end group
@group
(let ((Y 1)
(Z Y))
(list Y Z))
(let ((y 1)
(z y))
(list y z))
@result{} (1 2)
@end group
@end example
@ -225,13 +227,13 @@ form. Compare the following example with the example above for
@example
@group
(setq Y 2)
(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))
(let* ((y 1)
(z y)) ; @r{Use the just-established value of @code{y}.}
(list y z))
@result{} (1 1)
@end group
@end example
@ -258,19 +260,21 @@ 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.
@anchor{Definition of max-specpdl-size}
@defvar 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{Nonlocal Exits})
that are allowed before signaling an error (with data @code{"Variable
binding depth exceeds max-specpdl-size"}).
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{Eval}.
@xref{Definition of max-lisp-eval-depth,, Eval}.
The default value is 600. Entry to the Lisp debugger increases the
value, if there is little room left, to make sure the debugger itself
@ -518,7 +522,7 @@ 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]]
@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
@ -526,10 +530,10 @@ 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{value} is given. 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
@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
@ -858,11 +862,16 @@ always affects the most local existing binding.
One other function for setting a variable is designed to add
an element to a list if it is not already present in the list.
@defun add-to-list symbol element
@defun add-to-list symbol element &optional append
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.
Membership is tested using @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
@ -904,6 +913,7 @@ 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
@ -1281,9 +1291,9 @@ If the variable is terminal-local, this function signals an error. Such
variables cannot have buffer-local bindings as well. @xref{Multiple
Displays}.
@strong{Note:} 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
@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
@ -1295,7 +1305,14 @@ 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}) does so.
@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}.
@ -1318,10 +1335,17 @@ This returns @code{t} if @var{variable} is buffer-local in buffer
@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 returns the value of @var{variable} that is currently in
effect in @var{buffer}. If it has no buffer-local binding in
@var{buffer}, this function returns the default value.
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
@ -1358,13 +1382,6 @@ 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
@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
@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
@ -1561,11 +1578,17 @@ 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 (and usually are) 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,
@ -1680,13 +1703,20 @@ value of @var{alias-var} changes the value of @var{base-var}.
If the @var{docstring} argument is non-@code{nil}, it specifies the
documentation for @var{alias-var}; otherwise, the alias gets the same
documentation as @var{base-var} has, if any.
documentation as @var{base-var} has, if any, unless @var{base-var} is
itself an alias, in which case @var{alias-var} gets the documentation
of the variable at the end of the chain of aliases.
This function returns @var{base-var}.
@end defun
@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
@ -1698,8 +1728,10 @@ not defined as an alias, the function returns @var{variable}.
(setq bar 2)
bar
@result{} 2
@group
foo
@result{} 2
@end group
(setq foo 0)
bar
@result{} 0
@ -1711,7 +1743,9 @@ foo
@section File Local Variables
This section describes the functions and variables that affect
processing of local variables lists in files.
processing of local variables lists in files. @xref{File variables, ,
Local Variables in Files, emacs, The GNU Emacs Manual}, for basic
information about file local variables.
@defopt enable-local-variables
This variable controls whether to process file local variables lists. A
@ -1720,13 +1754,19 @@ unconditionally; @code{nil} means ignore them; anything else means ask
the user what to do for each file. The default value is @code{t}.
@end defopt
@defun hack-local-variables &optional force
@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.
@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.
The argument @var{force} usually comes from the argument @var{find-file}
given to @code{normal-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
specifies a mode and @code{nil} otherwise. It does not set the mode
nor any other file local variable. It does not check whether a mode
is specified in the local variables list at the end of the file.
@end defun
If a file local variable list could specify a function that will
@ -1743,7 +1783,15 @@ you should use such a name whenever it is appropriate for the
variable's meaning. The variables @samp{font-lock-keywords},
@samp{font-lock-keywords-[0-9]}, and
@samp{font-lock-syntactic-keywords} cannot be set in a local variable
list, either.
list, either. These rules can be overridden by giving the variable's
name a non-@code{nil} @code{safe-local-variable} property. If one
gives it a @code{safe-local-variable} property of @code{t}, then one
can give the variable any file local value. One can also give any
symbol, including the above, a @code{safe-local-variable} property
that is a function taking exactly one argument. In that case, giving
a variable with that name a file local value is only allowed if the
function returns non-@code{nil} when called with that value as
argument.
In addition, any variable whose name has a non-@code{nil}
@code{risky-local-variable} property is also ignored. So are all
@ -1755,9 +1803,12 @@ set by a file's local variables list. Any value specified
for one of these variables is ignored.
@end defvar
@defun risky-local-variable-p sym
Returns non-@code{nil} if @var{sym} is risky for any of the reasons
stated above.
@defun risky-local-variable-p sym &optional val
If @var{val} is non-@code{nil}, returns non-@code{nil} if giving
@var{sym} a file local value of @var{val} would be risky, for any of
the reasons stated above. If @var{val} is @code{nil} or omitted, only
returns @code{nil} if @var{sym} can be safely assigned any file local
value whatsoever.
@end defun
The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
@ -1769,3 +1820,47 @@ 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
Text properties are also potential loopholes, since their values
could include functions to call. So Emacs discards all text
properties from string values specified in a file's local variables
list.
@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

4
lispref/vol1.texi
View file

@ -1017,3 +1017,7 @@ Object Internals
These words prevent "local variables" above from confusing Emacs.
@ignore
arch-tag: 9594760d-8801-4d1b-aeb9-f3b3166b5be2
@end ignore

4
lispref/vol2.texi
View file

@ -1017,3 +1017,7 @@ Object Internals
These words prevent "local variables" above from confusing Emacs.
@ignore
arch-tag: dfdbecf8-fec2-49c1-8427-3e8ac8b0b849
@end ignore

138
lispref/windows.texi
View file

@ -18,7 +18,7 @@ displayed in windows.
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
* Displaying Buffers:: Higher-lever functions for displaying a buffer
* 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.
@ -97,6 +97,15 @@ the mark
@item
how recently the window was selected
@item
fringe settings
@item
display margins
@item
scroll-bar settings
@end itemize
@cindex multiple windows
@ -149,6 +158,7 @@ This function splits @var{window} into two windows. The original
window @var{window} remains the selected window, but occupies only
part of its former screen area. The rest is occupied by a newly created
window which is returned as the value of this function.
This function returns the newly created 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
@ -291,8 +301,7 @@ You could define a simplified version of the function like this:
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
included, if active, in the total number of windows, which is compared
against one.
counted when it is active.
The argument @var{all-frames} specifies which frames to consider. Here
are the possible values and their meanings:
@ -422,7 +431,7 @@ The return value is @var{window}.
@end defun
@defmac save-selected-window forms@dots{}
This macro records the selected window of eac frame, executes
This macro records the selected window of each frame, executes
@var{forms} in sequence, then restores the earlier selected windows.
This macro does not save or restore anything about the sizes,
@ -446,7 +455,8 @@ offering various criteria for the choice.
@defun get-lru-window &optional frame
This function returns the window least recently ``used'' (that is,
selected). The selected window is always the most recently used window.
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
@ -558,6 +568,9 @@ 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
@ -643,7 +656,7 @@ 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
@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}. This is the fundamental primitive
for changing which buffer is displayed in a window, and all ways
@ -655,6 +668,12 @@ of doing that call this function.
@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
@defun window-buffer &optional window
@ -702,21 +721,6 @@ The two optional arguments work like the optional arguments of
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.
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
@defvar buffer-display-time
@ -800,6 +804,8 @@ 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
@ -943,7 +949,7 @@ splits a window or reuses one.
@end defopt
@c Emacs 19 feature
@defvar pop-up-frame-function
@defopt pop-up-frame-function
This variable specifies how to make a new frame if @code{pop-up-frames}
is non-@code{nil}.
@ -952,7 +958,7 @@ Its value should be a function of no arguments. When
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 defvar
@end defopt
@defopt pop-up-frame-alist
This variable holds an alist specifying frame parameters used when
@ -984,6 +990,14 @@ For 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
@ -999,6 +1013,14 @@ 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 paramaters, 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
@ -1047,6 +1069,12 @@ 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
@ -1067,8 +1095,8 @@ A window can be marked as ``dedicated'' to its buffer. Then
other buffer.
@defun window-dedicated-p window
This function returns @code{t} if @var{window} is marked as dedicated;
otherwise @code{nil}.
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
@ -1322,7 +1350,8 @@ 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}.
@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
@ -1334,7 +1363,8 @@ 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}.
@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
@ -1568,12 +1598,12 @@ left you can scroll, but eventually all the text will disappear off the
left edge.
@vindex auto-hscroll-mode
In Emacs 21, redisplay automatically alters the horizontal scrolling
of a window as necessary to ensure that point is always visible, if
@code{auto-hscroll-mode} is set. 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.
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
This function scrolls the selected window @var{count} columns to the
@ -1626,10 +1656,11 @@ If @var{window} is @code{nil}, the selected window is used.
@end defun
@defun set-window-hscroll window columns
This function sets the number of columns from the left margin that
@var{window} is scrolled from the value of @var{columns}. 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.
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
@ -1680,9 +1711,8 @@ characters that separates side-by-side windows.
@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, and there is no tool bar, this
is typically one less than the value of @code{frame-height} on that
frame.
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.
@ -2007,6 +2037,14 @@ 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
@ -2023,7 +2061,8 @@ argument because it always uses the frame that @var{window} is on.
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. It also includes the values of @code{window-min-height},
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.
@ -2124,10 +2163,15 @@ regards configurations as unequal if they differ in any respect, even a
saved point or mark.
@end defun
Primitives to look inside of window configurations would make sense,
but none are implemented. It is not clear they are useful enough to
be worth implementing. See the file @file{winner.el} for some more
operations on windows configurations.
@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
@ -2202,3 +2246,7 @@ 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