A buffer is an object that holds text and is the place where almost all editing code works. Every Lisp program that edits text acts on the current buffer, at point, inside the accessible part of the buffer (the part that narrowing leaves visible). Positions are integers that count characters from 1; a position lies between two characters. This page lists the functions by area and the properties that decorate text.
Buffers
| Name | Meaning |
|---|---|
current-buffer, set-buffer | the current buffer; make another one current (not displayed) |
get-buffer, get-buffer-create, generate-new-buffer, generate-new-buffer-name | find a buffer by name; create it if needed; always make a new one with a unique name |
with-current-buffer | runs the body with another buffer current, then restores the old one |
with-temp-buffer | runs the body in a new, empty, hidden buffer and kills it afterwards; with-work-buffer is a reusing variant (Emacs 31) |
kill-buffer, buffer-live-p, buffer-name, rename-buffer, buffer-list, bury-buffer | lifetime and names; a name that starts with a space is hidden from the lists and has no undo by default |
buffer-modified-p, set-buffer-modified-p, restore-buffer-modified-p, buffer-modified-tick | the modified flag and a counter of changes |
buffer-read-only, barf-if-buffer-read-only, inhibit-read-only | read-only state; the variable lets code change a read-only buffer |
buffer-local-set-state, with-buffer-unmodified-if-unchanged | set variables and restore them later (Emacs 29); keep the buffer unmodified when the body leaves the text as it was (Emacs 29) |
make-indirect-buffer, buffer-base-buffer | an indirect buffer shares the text of its base buffer but has its own point, narrowing, markers and local variables |
insert-into-buffer, buffer-line-statistics | copy a buffer into another (Emacs 28); line count and line lengths (Emacs 28) |
(with-temp-buffer
(insert "one\ntwo\n")
(goto-char (point-min))
(forward-line 1)
(buffer-substring (point) (line-end-position))) ; => "two"Buffer-local variables are covered on Variables and scope. Showing a buffer in a window and the window, frame and display chapters are named in Not described.
Point and motion
| Name | Meaning |
|---|---|
point, point-min, point-max, buffer-size | current position and the limits of the accessible part |
goto-char | moves point to a position or marker |
forward-char, backward-char | move by characters; signal beginning-of-buffer or end-of-buffer at the limit |
forward-line | moves by lines to the start of a line and returns how many it could not move |
beginning-of-line, end-of-line, line-beginning-position, line-end-position | line limits; they respect fields and invisible text |
pos-bol, pos-eol | like the line-position functions but ignore fields and are faster (Emacs 29) |
bobp, eobp, bolp, eolp | tests for the limits of the buffer and of a line |
skip-chars-forward, skip-chars-backward, skip-syntax-forward | move over characters in a set such as "a-zA-Z_" or a syntax class |
forward-word, forward-sexp, forward-list, up-list, scan-lists, scan-sexps | move over words and balanced expressions according to the syntax table (Regexps and syntax tables) |
line-number-at-pos, count-lines, current-column | measure |
Reading, inserting and deleting text
| Name | Meaning |
|---|---|
buffer-substring, buffer-substring-no-properties, buffer-string | copy text, with or without properties; buffer-string is the whole accessible part |
char-after, char-before, following-char, preceding-char | the character at a position; nil outside the buffer for the first two |
insert, insert-char, insert-buffer-substring, insert-before-markers | insert at point; the last form also advances markers that sit at point |
delete-region, delete-char, delete-and-extract-region, erase-buffer | remove text |
subst-char-in-region, translate-region | replace one character, or map characters through a table, in a region |
replace-buffer-contents, replace-region-contents | replace text by a minimal edit, so that markers and properties in unchanged text survive; Emacs 31 lets replace-region-contents take more kinds of source |
replace-regexp-in-region, replace-string-in-region | search and replace in a region from Lisp (Emacs 28) |
Narrowing and saving state
| Form | Meaning |
|---|---|
narrow-to-region, widen, buffer-narrowed-p | restrict the accessible part of the buffer; remove the restriction |
save-restriction | restores the narrowing afterwards |
with-restriction, without-restriction | narrow (optionally with a :label that only the same label can lift), or temporarily widen (Emacs 29) |
save-excursion | restores the current buffer and the point (as a marker) |
save-mark-and-excursion | the same, plus the mark and its activation |
save-match-data | restores the regexp match data (Regexps and syntax tables) |
Markers, mark and region
A marker is an object that points to a position in a buffer and moves with edits. make-marker creates one that points nowhere; point-marker, copy-marker and point-min-marker create set ones; set-marker and move-marker change one; marker-position, marker-buffer and (Emacs 30) marker-last-position read one. Set a marker to nil or release it with (set-marker M nil) when finished, as live markers slow down edits.
The insertion type decides what happens to a marker at the exact place where text is inserted: by default it stays before the new text; (set-marker-insertion-type M t) makes it advance. insert-before-markers advances every marker at that place.
The mark is a marker per buffer (mark, set-mark, push-mark, mark-marker), and the region is the text between point and mark (region-beginning, region-end, use-region-p, region-active-p). The variable mark-active says whether the region is active.
Undo
| Name | Meaning |
|---|---|
buffer-undo-list | the list of undo records of the buffer: (BEG . END) for an insertion, (TEXT . POS) for a deletion, (t . TIME) for the unmodified state, nil as a boundary between commands, t when undo is off |
undo-boundary | puts a boundary record in the list |
buffer-disable-undo, buffer-enable-undo | turn recording off and on |
prepare-change-group, activate-change-group, accept-change-group, cancel-change-group | group changes so that they can be undone as one |
atomic-change-group | runs the body and undoes all its changes when it exits non-locally |
undo-amalgamate-change-group | removes the boundaries inside a change group |
Text properties
Every character in a buffer or string can have a property list. put-text-property, add-text-properties, set-text-properties, remove-text-properties and propertize change them; get-text-property and text-properties-at read them; get-char-property also looks at overlays and returns the overlay’s value first. text-property-search-forward and text-property-search-backward return a prop-match for the next region where a property matches. next-property-change and next-single-char-property-change step between changes. Emacs 29 added add-display-text-property and Emacs 31 added remove-display-text-property.
| Property | Effect |
|---|---|
face, font-lock-face | the display face (a name, a plist or a list of them); font-lock-face is used only when Font Lock is on |
display | replaces the text on screen by a string, image, space or other spec |
invisible | hides the text when its value is non-nil (or listed in buffer-invisibility-spec) |
read-only | forbids changes; signals text-read-only |
keymap, local-map | a keymap for key presses on the text (the first overrides the minor-mode maps) |
help-echo, mouse-face | tooltip or echo-area text; face when the mouse is over the text |
field | divides the buffer into fields that limit line motion and delete-field |
intangible | makes point skip over the text (obsolete, with cursor-intangible as the replacement) |
cursor | where the cursor is drawn for a display string |
category | a symbol whose plist supplies default values for other properties |
front-sticky, rear-nonsticky | stickiness: whether text inserted next to the text inherits its properties; by default a property is rear-sticky, and text-property-default-nonsticky changes the default (it is buffer-local from Emacs 31) |
Overlays
An overlay is an object that covers a range of a buffer and carries properties, without becoming part of the text. It moves with edits as markers do and is not copied by buffer-substring. (make-overlay BEG END &optional BUFFER FRONT-ADVANCE REAR-ADVANCE) creates it; overlay-put and overlay-get set and read properties; move-overlay and delete-overlay change or remove it; overlays-at, overlays-in, next-overlay-change and remove-overlays find them. Properties include face, display, invisible, priority, before-string, after-string, evaporate (delete the overlay when it becomes empty), modification-hooks, insert-in-front-hooks, insert-behind-hooks, help-echo, mouse-face, keymap, window and category; Emacs 31 allows min-width as an overlay property.
The implementation of overlays changed in Emacs 29. In Emacs 31 overlays-in and overlays-at again return overlays outside the current narrowing, as they did before Emacs 28.
Change hooks
| Variable | Called |
|---|---|
before-change-functions | before a change, with the start and end of the text to be changed |
after-change-functions | after a change, with the start, the end and the old length |
first-change-hook | before the first change of an unmodified buffer |
inhibit-modification-hooks | when non-nil, no change hooks run; Emacs binds it to t while a hook runs |
Columns and indentation
current-column gives the display column of point (tabs and wide characters count by width). move-to-column moves to a column, indent-to inserts tabs and spaces up to a column, current-indentation measures the indentation of a line, and indent-rigidly, indent-region and indent-line-function change it; indent-tabs-mode chooses tabs or spaces. Filling uses fill-column, fill-region and fill-paragraph; they are named here only.
Not described
Known, not yet covered
- Reference: displaying buffers: windows, frames,
display-bufferand the display chapters (fonts, faces in detail, images, fringes, the mode line, bidirectional text). - Reference: the rules of text-property inheritance and stickiness when text is inserted,
insert-and-inherit, and the full list of special properties such ascompositionandcursor-sensor-functions(Emacs 31 makes its boundaries obey stickiness). - Reference: filling, case conversion of regions, sorting text, and the full interface of the abbrev, transposing and column functions.
- Reference: the exact record formats of
buffer-undo-listfor text properties and marker adjustments.
See also
- Regexps and syntax tables – searching text and the syntax table
- Strings and characters – the same properties on strings
- Variables and scope – buffer-local variables
- Commands and modes – major and minor modes and keymaps
- Buffers – the manual’s chapter on buffers
- Text – the manual’s chapter on editing text
- Markers – the manual’s chapter on markers