|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T l
Length: 60971 (0xee2b)
Types: TextFile
Names: »lispref-15«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-15«
Info file: lispref, -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo
This file documents GNU Emacs Lisp.
This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.
Please read this document for review purposes.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1989 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
▶1f◀
File: lispref Node: The Kill Ring, Prev: Deletion, Up: Text, Next: Undo
The Kill Ring
=============
Emacs keeps a number of the last sections of text that were deleted by
the user. These sections of text are kept on a list called the
`kill-ring'. Several functions manipulate this list; they treat it as a
ring rather than as a list.
The kill ring and its associated functions help the user move text
around, make it easy to change his or her mind, and help him or her
recover from accidents.
Some people think use of the word `kill' in Emacs is unfortunate,
since it refers to processes which specifically *do not* destroy the
entities `killed'. This is in sharp contrast to ordinary life, in which
death is permanent, and `killed' entities seldom come back to life. A
different metaphor might have been more intuitive. For example, the
term `cut ring' makes sense to people who, in pre-computer days, used
scissors and paste to cut up and rearrange manuscripts. Others most
readily understand a metaphor incorporating concepts of `attic' or
`closet'; and yet others, who think of text as being `clipped' from the
buffer, prefer a term such as `clip ring'.
* Menu:
* Kill Ring Data Structures::
* Kill Functions::
* Yank Commands::
* Kill Ring Internals::
▶1f◀
File: lispref Node: Kill Ring Data Structures, Prev: The Kill Ring, Up: The Kill Ring, Next: Kill Functions
Kill Ring Data Structures
-------------------------
Killed text is kept as strings in a list. A short kill ring, for
example, might look like this:
("some text" "a different piece of text" "yet more text")
Functions which push more text into the list first make a string of
the text in question (using `buffer-substring'), and then look at the
length of the list. If the length is longer than the value of
`kill-ring-max', the last entry in the list is dropped off when the new
entry is put on.
The `kill-ring-yank-pointer' global variable points to the kill ring
entry that a "yank" function will copy. Several functions move this
pointer from one entry to another, and a user can thereby specify which
entry to copy.
Here is a diagram that shows the variable `kill-ring-yank-pointer'
pointing to the second entry in the kill ring `("some text" "a different
piece of text" "yet more text")'.
kill-ring kill-ring-yank-pointer
| |
| ___ ___ | ___ ___ ___ ___
--> | | | ---> | | | | | |
|___|___|------> |___|___|--> |___|___|--> nil
| | |
| | |
| | -->"yet more text"
| |
| --> "a different piece of text"
|
--> "some text"
(This circumstance occurs when `C-y' (`yank') is immediately followed by
`M-y' (`yank-pop').)
Both `kill-ring' and `kill-ring-yank-pointer' are variables like other
Lisp variables. Both are bound to lists. The word `pointer' is used in
the name of the `kill-ring-yank-pointer' variable to tell human readers
that the purpose of the variable is to point to the element of the list
that will be copied to the buffer when the user gives a yank command.
The functions that change the entry to which the
`kill-ring-yank-pointer' points treat the kill ring (which is a list) as
if it were a ring; that is to say, a change that would otherwise cause
the pointer to point to an entry beyond the end of the list (which would
be useless) instead causes the pointer to point to the first entry on
the list. Hence, movement of the `kill-ring-yank-pointer' is called
"rotation".
The `kill-ring-yank-pointer' variable can be moved in the `reverse'
direction from the end of the list to the beginning; but only one step
at a time; and it cannot be moved from the first entry to the last entry
in the `reverse' direction. The ring is a one way rotary.
Kill commands always place their new text in the beginning of
`kill-ring', and they always reset `kill-ring-yank-pointer' to point to
the first entry of `kill-ring'. The first entry will be the new entry;
consequently, the next `yank' command will copy the new entry into a
buffer, as the user expects.
After `kill-ring-yank-pointer' is reset to point to the first entry of
`kill-ring', `kill-ring' and `kill-ring-yank-pointer' are `eq' to each
other.
`kill-region' is the primary function for programs to use that kill
text. Any command that calls this function is a ``kill command'' (and
should contain the word ``kill'' in its name).
When kill commands are interwoven with other commands, the killed
portions of text are put into separate entries in the kill ring. But
when two or more kill commands are executed in sequence, the text killed
by the second (or third, etc.) kill command is appended to the text
killed by the first command so as to make one entry in the kill ring.
The `kill-region' function uses the `last-command' variable to keep
track of whether the previous was a kill command, in which case, it
appends the killed text to the current entry.
▶1f◀
File: lispref Node: Kill Functions, Prev: Kill Ring Data Structures, Up: The Kill Ring, Next: Yank Commands
Entry Points for Killing
------------------------
* Command: kill-region START END
This function kills the text in the region defined by START and
END. The text is deleted but saved in the kill ring.
When called interactively, START and END are point and mark.
* Command: kill-line &optional COUNT
This function kills the rest of the line following point, not
including the newline. If point is directly before a newline, or
if there is only whitespace between point and the newline, then it
kills the whitespace and newline.
If COUNT is supplied, then it kills that many lines (*including*
the newline). (This makes executing `(kill-line 2)' different from
executing `(kill-line)' two times.) If COUNT is negative, then
`kill-line' kills lines backwards.
When called interactively, COUNT is the unprocessed prefix
argument (which then gets processed if non-`nil').
* Command: zap-to-char COUNT CHARACTER
The Emacs Version 19 implementation of this function kills all
text in the region from point up to and including COUNT the next
occurrence of CHARACTER. Thus, if the cursor were at the beginning
of this sentence and the character were `s', `Thus' would be
removed. If the argument were two, `Thus, if the curs' would be
removed, up to and including the `s' in `cursor'.
The Emacs Version 18 implementation of the function removes the
text from point up to *but not including* the specified character.
Thus, in the example shown in the previous paragraph, the `s' would
*not* be removed.
In addition, the Version 18 implementation will kill text to the
end of the buffer if the specified character is not found; but the
Version 19 implementation will simply generate an error (and not
remove any text).
The function zaps backward if COUNT is negative. The killed text
is put in the kill ring.
* Command: copy-region-as-kill START END
This function saves the region defined by START and END on the
kill ring, but does not delete the text from the buffer.
When called interactively, START and END are point and mark.
▶1f◀
File: lispref Node: Yank Commands, Prev: Kill Functions, Up: The Kill Ring, Next: Kill Ring Internals
Entry Points for Yanking
------------------------
* Command: yank &optional ARG
This function inserts the text in the first entry in the kill
ring directly before point. After the yank, the mark is positioned
at the beginning and point is positioned after the end of the
inserted text.
If ARG is a list (which as passed an an interactive argument when
a user types must `C-u'), then `yank' inserts the text as described
above, but puts point in front of the yanked text and the mark at
the end of the yanked text. If ARG is a number, then `yank'
inserts the ARG'th most recently killed text.
* Command: yank-pop ARG
This function replaces the just-yanked text with a different
piece of killed text. This command is allowed only immediately
after a `yank' or a `yank-pop'. At such a time, the region
contains text that was just inserted by the previous `yank'.
`yank-pop' deletes that text and inserts in its place a different
stretch of killed text.
If ARG is `nil', then the previously inserted text in the region
is deleted (and not reinserted into the kill ring since it is
already on the kill ring), and the previous element of the kill
ring is inserted. If ARG is numeric, then the ARG'TH previous kill
is inserted. If ARG is negative, then this is a more recent kill.
The sequence of kills wraps around, so that after the oldest one
comes the newest one. (However, the reverse wrap is not possible;
you can step backward through the list, but not beyond the
beginning.)
▶1f◀
File: lispref Node: Kill Ring Internals, Prev: Yank Commands, Up: The Kill Ring
Internals of the Kill Ring
--------------------------
* Variable: kill-ring
List of killed text sequences.
* Variable: kill-ring-yank-pointer
This global variable is the CDR of the kill ring whose CAR is the
last thing yanked. The `yank-pop' and `rotate-yank-pointer'
commands move this pointer around in the kill ring. A kill always
resets this variable to point the beginning of the kill ring (that
is, to bind the value of the variable to the whole kill ring).
* Command: rotate-yank-pointer COUNT
This function rotates `kill-ring-yank-pointer' COUNT positions in
the kill ring. In other words, it rebinds `kill-ring-yank-pointer'
to a different CDR of the kill ring, or to the whole kill ring.
* User Option: kill-ring-max
The value of this global variable is the maximum length to which
the kill ring can grow, before elements are thrown away on a
first-in, first-out basis. The default value for `kill-ring-max'
is 30.
▶1f◀
File: lispref Node: Undo, Prev: The Kill Ring, Up: Text, Next: Auto Filling
Undo
====
Each buffer has its own private undo stack. Stack size is limited, so
large changes or a large number of changes cannot be undone.
* Command: undo &optional ARG
This function undoes some previous changes. By repeating this
command you can undo more changes. A numeric argument serves as a
repeat count.
* Function: undo-boundary
This function places a boundary between units of undo. Each undo
command stops at such a boundary; and the next undo command will
undo to the previous boundary.
There is an implicit undo boundary between each key-stroke
command, such as `kill-word'. Thus, each undo undoes the effects
of one command.
This function is used inside of `query-replace', between each
replacement, so that individual replacements can be undone one by
one.
* Function: undo-more COUNT
This function is used to undo changes back COUNT boundaries
beyond what was already undone recently.
* Function: undo-start
This function moves the undo-pointer to the beginning of the undo
stack. This means that the next call to `undo-more' will undo the
most recently made change. This function breaks a sequence of
undo's, so a subsequent call to `undo-more' will undo a previous
change that is itself the result of an undo. This is what you use
to undo your undoing (i.e., redo).
To prepare Emacs to undo a recent sequence of changes, call
`undo-start'; then call `undo-more' one or more times to undo them.
* Command: buffer-enable-undo &optional BUFFER-OR-NAME
This function starts keeping undo information for buffer
BUFFER-OR-NAME. If no argument is supplied, then the current
buffer is used. If the buffer is already keeping undo information,
then nothing is changed.
This function returns `nil'.
When called interactively, BUFFER-OR-NAME is the current buffer.
* Function: buffer-flush-undo BUFFER-OR-NAME
This function makes the buffer BUFFER-OR-NAME stop keeping undo
information, and flushes the information it has kept thus far. If
the buffer is not keeping undo information, then nothing is
changed.
This function returns `nil'.
▶1f◀
File: lispref Node: Auto Filling, Prev: Undo, Up: Text, Next: Filling
Auto Filling
============
"Filling" breaks text into lines that are no more than a specified
number of columns wide. Lines end between words, and thus may be
shorter than the maximum length, unless the line is "justified" in which
case, spaces are inserted between words so that the last letter of the
last word on the line is on the last column.
In Auto Fill mode, Emacs fills lines automatically. This section
describes the hook and the two variables used by Auto Fill mode.
For a description of functions that you can call manually to fill and
justify text, *Note Filling::.
As a practical matter, if you are writing text that you hope other
people will read, you should set the value of `fill-column' to no more
than 70. Otherwise the line will be too long for people to read
comfortably; and they will think your writing is clumsy even if it
isn't!
* Variable: auto-fill-hook
The value of this variable should be a function (of no arguments)
to be called after self-inserting a space at a column beyond
`fill-column'. It may be `nil', in which case, nothing special is
done.
The default value for `auto-fill-function' is `do-auto-fill'.
In version 18, `auto-fill-function' is called `auto-fill-hook';
but since `auto-fill-hook' is not called by the `run-hooks'
function, it is being re-named `auto-fill-function' in Version 19.
* User Option: fill-column
This buffer-local variable controls how wide lines are filled.
It should be an integer which is interpreted as a column. If
automatic line-wrapping is turned on, then any text typed beyond
this column is wrapped onto the next line. The command
`fill-paragraph' adjusts the lines the paragraph which point is in
so that it ends at this column.
* Variable: default-fill-column
The value of this variable is the default value for `fill-column'
in buffers that do not override it. This is the same as
`(default-value 'fill-column)'.
The default value for `default-fill-column' is 70.
▶1f◀
File: lispref Node: Filling, Prev: Auto Filling, Up: Text, Next: Sorting
Filling
=======
"Filling" means adjusting the lengths of lines so that line-breaks
occur between rather than within words; and lines have a specified
maximum length. If a line is justified as will as filled, then spaces
are inserted between the words so that the last letter of the last word
on the line is on the specified column. For ease of reading, lines
should be no longer than 70 or so columns.
Emacs has facilities for automatically filling text as you write it,
but changes to existing text may leave it improperly filled. Then you
must fill the text explicitly.
* Command: fill-paragraph JUSTIFY-FLAG
This function fills the paragraph at or after point. If
JUSTIFY-FLAG is non-`nil', each line is justified as well.
* Command: fill-region START END &optional JUSTIFY-FLAG
This function fills each of the paragraphs in the region from
start to end. The function justifies the paragraph if it is called
interactively with a prefix argument, or if it is called from a
program with a non-`nil' JUSTIFY-FLAG.
The function uses the value of `paragraph-separate' to distinguish
paragraphs.
* Command: fill-individual-paragraphs START END &optional JUSTIFYP MAILP
This function fills each paragraph in the region according to its
individual fill prefix. Thus, if the lines of a paragraph are
indented with spaces, the filled paragraph will continue to be
indented in the same fashion.
The first two arguments, START and END, are the beginning and end
of the region that will be filled. The third and fourth arguments,
JUSTIFYP and MAILP, are optional. If JUSTIFYP is non-`nil', the
paragraphs are justified as well as filled. If MAILP is non-`nil',
the function is told that it is operating on a mail message and
that it should not fill the header lines.
* Command: fill-region-as-paragraph START END &optional JUSTIFY-FLAG
This function considers a region of text as paragraph and fills
it. If the region was made up of many paragraphs, the blank lines
between paragraphs are removed. This function justifies the region
when called interactively with a non-`nil' prefix argument, or when
called from a program with a non-`nil' third argument.
* Command: justify-current-line
This function inserts spaces between the words of the line point
is in so that the line ends at `fill-column'.
▶1f◀
File: lispref Node: Sorting, Prev: Filling, Up: Text, Next: Indentation
Sorting
=======
The sorting commands described in this section all rearrange text in a
buffer. In contrast, the function `sort' rearranges the order of the
elements of a list. (*Note Rearrangement::.)
* Command: sort-regexp-fields REVERSE RECORD-REGEXP KEY START END
This command sorts the region between START and END
lexicographically as specified by RECORD-REGEXP and KEY.
`Lexicographic' means that the function compares the first
characters of each field, the second characters, and so on. One
field is less than a second field in the ordering when compared
characters do not match; the firld whose character is less than the
other is the lessor field. One character is considered to be less
than another if its numerical value as a character is less than the
other. Since Emacs uses the ASCII character set, the ordering in
that set determines lexicographic order.
The value of the RECORD-REGEXP argument specifies the textual
units or "records" that should be sorted. For example, to sort
lines, the value of RECORD-REGEXP would be `^.*$', which matches
lines with at least one character besides a newline.
(*Note Regular Expressions::, for a description of the syntax and
meaning of regular expressions.)
The value of the KEY argument specifies what of each record is to
be used for sorting. The KEY could match the whole record, but it
may be just a part of the record. In the latter case, the part of
each record that is not used for sorting has no effect on the sort.
The KEY argument can refer to match-fields within the regular
expression for the record; or it can be a regular expression on its
own.
If KEY is:
`\DIGIT'
The DIGIT'th `\(...\)' match field from RECORD-REGEXP is used
for sorting.
`\&'
The whole record is used for sorting.
a regular-expression
The function searches for a matchfor the regular-expression
within the record. If such a match is found, it is used for
sorting. If a match for KEY is not found within a record then
that record is ignored, which means its position in the buffer
is not changed.
The `sort-regexp-fields' function sorts in reverse order when the
first argument, REVERSE, is negative. Called interactively, it
sorts in reverse order when passed by a negative prefix argument.
For example, if you plan to sort all the lines in the region by
the first word on each line starting with the letter `f', you
should set RECORD-REGEXP to `^.*$' and set KEY to `\<f\w*\>'.
The resulting expression looks like this:
(sort-regexp-fields nil
"^.*$"
"\\<f\\w*\\>"
(region-beginning)
(region-end))
If you call `sort-regexp-fields' interactively, you are prompted
for RECORD-REGEXP and KEY and you can type them in without
enclosing them in quotation marks and without inserting a second
`\' to quote each `\'.
* Command: sort-subr REVERSE NEXTRECFUN ENDRECFUN &optional STARTKEYFUN ENDKEYFUN
This command is the general text sorting routine that divides a
buffer into records and sorts them.
The functions `sort-lines', `sort-paragraphs', `sort-pages',
`sort-fields', and `sort-numeric-fields' all use `sort-subr'.
To understand how `sort-subr' works, consider the whole
accessible portion of the buffer as being divided into disjoint
pieces called "sort records". A portion of each sort record
(perhaps all of it) is designated as the sort key. The records are
rearranged in the buffer in order by their sort keys. The records
may or may not be contiguous.
Usually, the records are rearranged in order of ascending sort
key. If the first argument to the `sort-subr' function, REVERSE,
is non-`nil', the sort records are rearranged in order of
descending sort key.
The next four arguments to `sort-subr' are functions that are
called to move point across a sort record. They are called many
times from within `sort-subr'.
1. NEXTRECFUN is called with point at the end of the previous
record. This function moves point to the start of the next
record. The first record is assumed to start at the position
of point when `sort-subr' is called.
2. ENDRECFUN is called with point within the record. It moves
point to the end of the record.
3. STARTKEYFUN may move point from the start of the record to the
start of the key. This argument is optional. It will either
return a non-nil value that will be used as the key, or it
will return `nil' and the key will be the substring between
the values of point before and after ENDKEYFUN is called.
4. ENDKEYFUN moves point from the start of the sort key to the
end of the sort key. This argument is optional. ENDKEYFUN
may be `nil' if STARTKEYFUN returns a value that will be used
as the key or if the key continues to the end of the record.
For an example of `sort-subr', here is the complete function
definition for `sort-lines':
(defun sort-lines (reverse beg end)
"Sort lines in region alphabetically; argument means descending order.
Called from a program, there are three arguments: REVERSE (non-nil means
reverse order), BEG and END (region to sort)."
(interactive "P\nr")
(save-restriction
(narrow-to-region beg end)
(goto-char (point-min))
(sort-subr reverse 'forward-line 'end-of-line)))
In the `sort-lines' function, `forward-line' moves point to the
start of the next record, and `end-of-line' moves point to the end
of record.
The `sort-paragraphs' function is very much the same, except that
its `sort-subr' call looks like this:
(sort-subr reverse
(function (lambda () (skip-chars-forward "\n \t\f")))
'forward-paragraph)))
* Command: sort-lines REVERSE START END
This command sorts lines in the region between START and END
alphabetically. If REVERSE is non-`nil', the sort is in reverse
order.
* Command: sort-paragraphs REVERSE START END
This command sorts paragraphs in the region between START and END
alphabetically. If REVERSE is non-`nil', the sort is in reverse
order.
* Command: sort-pages REVERSE START END
This command sorts pages in the region between START and END
alphabetically. If REVERSE is non-`nil', the sort is in reverse
order.
* Command: sort-fields FIELD START END
This command sorts lines in the region between START and END
lexicographically by the FIELD'th field of each line. Fields are
separated by whitespace and numbered from `1' up. If `field' is
negative, sorting is by the -FIELD'th field, in reverse order.
This command is useful for sorting tables.
* Command: sort-numeric-fields FIELD START END
This command sorts lines in the region between START and END
numerically by the FIELD'th field of each line. Fields are
separated by whitespace and numbered from `1' up. Specified field
must contain a number in each line of the region. If `field' is
negative, sort by the -FIELD'th field, in reverse order. This
command is useful for sorting tables.
* Command: sort-columns REVERSE &optional BEG END
This command sorts lines in the region between START and END
alphabetically by a certain range of columns. For the purpose of
this command, the region includes the entire line that point is in
and the entire line containing END. The column positions of BEG
and END bound the range of columns to sort on.
If REVERSE is non-`nil', the sort is in reverse order.
Note that `sort-columns' uses the `sort' utility program and
therefore cannot work properly on text containing TAB characters.
(Use `M-x `untabify'' to convert tabs to spaces before sorting.)
The `sort-columns' function cannot work in VMS.
▶1f◀
File: lispref Node: Indentation, Prev: Sorting, Up: Text, Next: Indent Tabs
Indentation
===========
The indentation functions are used to examine, move to, and change
whitespace that is at the beginning of a line. Some of the functions
can also change whitespace elsewhere on a line. Indentation always
counts from zero at the beginning of a line.
* Command: back-to-indentation
This command moves point to the first non-whitespace character in
the the current line (which is the line in which point is located).
* Command: backward-to-indentation ARG
This command moves point backward ARG lines and positions point
at the first nonblank character.
* Function: current-indentation
This function returns the indentation of the current line. This
is the horizontal position of the character following any initial
whitespace.
* Command: forward-to-indentation ARG
This command moves point forward ARG lines and positions it at
the first nonblank character.
* Command: indent-according-to-mode
This command indents the current line in the proper way for the
current major mode. Thus, Lisp mode uses `lisp-indent-line' to
indent the current line, C mode uses `c-indent-line', and Fortran
mode uses `fortran-indent-line'.
* Command: indent-for-tab-command
This command indents the current line in the proper way for the
current major mode, except that if the function for indenting lines
is `indent-to-left-margin', this function calls `insert-tab'.
However, Lisp mode uses `lisp-indent-line' to indent the current
line, and C mode uses `c-indent-line'.
* Variable: indent-line-function
This variable has a value which is the function that will be
called to indent current line. The default value is
`indent-to-left-margin', and in Lisp mode it would be set to
`lisp-indent-line' and in C mode it would be set to
`c-indent-line'.
A command such as `indent-according-to-mode' is no more than a
`funcall' to this function.
* Variable: left-margin
This variable is the column to which the default default
`indent-line-function' will indent. (That function is
`indent-to-left-margin'.) In Fundamental mode, LFD indents to this
column. This variable automatically becomes local when set in any
fashion.
* Function: indent-to-left-margin
This is the default `indent-line-function'. It is used in
Fundamental mode, Text mode, etc.
Its effect is to make the indentation at the beginning of the
current line exactly the amount specified by the variable
`left-margin'. This may involve inserting additional indentation
or deleting extra indentation.
* Command: indent-region START END TO-COLUMN
This command indents each nonblank line starting between START
(inclusive) and END (exclusive). If TO-COLUMN is `nil',
`indent-region' indents each nonblank line according to the
indentation function that is bound to TAB in that mode, such as
`indent-to-left-margin' in Fundamental mode, `lisp-indent-line' in
Lisp Interaction mode, and `c-indent-line' in C mode. If TO-COLUMN
is an integer, this function indents each line to that column.
* Variable: indent-region-function
The value of this variable is a function that can be used by
`indent-region' as a short cut. It ought to produce the same
results as indenting the lines of the region one by one, which is
the definition of `indent-region' with argument `nil'.
If the value is `nil', there is no short cut, and `indent-region'
actually works line by line.
A short cut is useful in modes such as C mode and Lisp mode,
where the `indent-line-function' must scan from the beginning of
the function: applying it to each line would be quadratic in time.
The short cut can update the scan information as it moves through
the lines indenting them; this takes linear time. If indenting a
line individually is fast, there is no need for a short cut.
`indent-region' with a non-`nil' argument has a different
definition and does not use this variable.
* Command: indent-relative &optional UNINDENTED-OK
This function inserts whitespace at point, extending to the same
column as the next "indent point" of the previous nonblank line.
An indent point is a non-whitespace character following whitespace.
If the previous nonblank line has no indent points beyond (that
is, to the right of) the column from which point starts, this
function calls `tab-to-tab-stop'; except that if the optional
argument, UNINDENTED-OK, is non-`nil', then, if the previous
nonblank line has no indent points beyond the column at which point
starts, this function does nothing.
Thus, if point is underneath, but to the right of the last column
of a short line of text, this function moves point to the next tab
stop by inserting whitespace. If point is underneath and to the
left of the first non-blank character of a line of text, point is
moved to that column by inserting whitespace.
In the first example, point is at the beginning of the third
line.
This line is indented twelve spaces.
-!-The quick brown fox jumped over the lazy dog.
Evaluation of the expression `(indent-relative nil)' produces the
following:
This line is indented twelve spaces.
-!-The quick brown fox jumped over the lazy dog.
In the next example, point is between the `m' and `p' of
`jumped':
This line is indented twelve spaces.
The quick brown fox jum-!-ped over the lazy dog.
Evaluation of the expression `(indent-relative nil)' produces the
following:
This line is indented twelve spaces.
The quick brown fox jum -!-ped over the lazy dog.
* Command: indent-relative-maybe
This command indents the line on which point is located like the
previous nonblank line. The function consists of a call to
`indent-relative' with a non-`nil' value passed to the
UNINDENTED-OK optional argument.
If the previous line is not indented, then the line on which
point is located is given no indentation; and if the previous
nonblank line has no indent points beyond the column at which point
starts, this function does not do any indentation.
* Command: indent-rigidly START END COUNT
This command indents all lines starting between START (inclusive)
and END (exclusive) sideways by `count' columns.
Thus, if you wish to indent all lines in a region by 3 spaces,
you execute this command with a COUNT of 3.
In Mail mode, `C-c C-y' (`mail-yank-original') uses
`indent-rigidly' to indent the text copied from the message being
replied to.
This command adds indentation to lines that are already indented;
it `preserves the shape' of the indented region, moving it sideways
as a single unit. Consequently, this command is useful not only
for indenting regions of unindented text, but also for indenting
regions of formatted code.
* User Option: indent-tabs-mode
If this user option is non-`nil', indentation functions can
insert tabs rather than spaces. Setting this variable
automatically makes it local to the current buffer.
* Command: indent-to COL &optional MINIMUM
This function indents from point with tabs and spaces until
COLUMN is reached. It always indents by at least MIN spaces even
if that goes past COLUMN; by default, MIN is zero.
* Command: newline-and-indent
This function inserts a newline, and then indents the new line
according to the major mode.
Indentation is done using the current `indent-line-function'. In
programming language modes, this is the same as TAB. In some text
modes, where TAB inserts a tab, `newline-and-indent' indents to the
specified left-margin column.
* Command: reindent-then-newline-and-indent
This command reindents current line, inserts a newline at point,
and then indents the new line.
Indentation of both lines is done according to the current major
mode; this means that the current value of `indent-line-function'
is called. In programming language modes, this is the same as TAB.
In some text modes, where TAB inserts a tab,
`reindent-then-newline-and-indent' indents to the specified
left-margin column.
▶1f◀
File: lispref Node: Indent Tabs, Prev: Indentation, Up: Text, Next: Columns
Tabs for Indentation
====================
The following tab functions insert indentation in user specified
amounts. They do not simply insert tab characters.
* Function: tab-to-tab-stop
This function inserts spaces or tabs to the next defined
"tab-stop" column. The variable `tab-stop-list' is a list of
columns at which there are tab stops. The distance between tab
stops need not be constant. This feature is convenient if you are
making tables with columns of differing width.
Use `M-x edit-tab-stops' to edit the location of tab stops
interactively.
* User Option: tab-stop-list
This variable is the list of tab stop positions used by
`tab-to-tab-stops'. The tab stop positions need not be equally
spaced.
Note that `tab-stop-list' has nothing to do with the tab
character and is not related to the `tab-width' variable.
▶1f◀
File: lispref Node: Columns, Prev: Indent Tabs, Up: Text, Next: Case Changes
Columns
=======
The column functions do not take into account the width of windows, or
the amount of horizontal scrolling. As a consequence, the value of
COLUMN can be arbitrarily high.
The first (or leftmost) column is numbered `0'.
* Function: current-column
This function returns the horizontal position of point. The
beginning of a line is column 0. The column is calculated by
adding together the widths of all the displayed representations of
the characters between the start of the current line and point.
This means control characters will be counted as occupying 2 or 4
columns, depending upon the value of `ctl-arrow', and tabs will be
counted as occupying a number of columns that depends on the value
of `tab-width'.
The `current-column' function ignores the finite width of the
screen, which means that this function may return values greater
than `(screen-width)'.
* Function: move-to-column COLUMN
This function moves point to COLUMN in the current line. The
calculation of COLUMN takes into account the widths of all the
displayed representations of the characters between the start of
the line and point. Thus control characters are calculated to
occupy 2 or 4 columns, depending upon the setting of `ctl-arrow',
and tabs to occupy a number of columns that depends on the value of
`tab-width'.
The `move-to-column' function may be passed values greater than
the value returned by `(screen-width)'. If the current line is not
that wide, then point is moved to the end of the line. If COLUMN
is negative, point is moved to the beginning of the line. COLUMN
must be an integer.
The result is the column number actually moved to.
▶1f◀
File: lispref Node: Case Changes, Prev: Indent Tabs, Up: Text, Next: Underlining
Case Changes
============
These case change commands work on text in the current buffer. *Note
Character Case::, for case conversion commands that work on strings and
characters.
* Command: capitalize-region START END
This function capitalizes all words in the region defined by
START and END. To `capitalize' means to convert each word's first
character is upper case and convert the rest of each word to lower
case. The function returns `nil'.
When `capitalize-region' is called interactively, START and END
are point and mark, smallest first.
---------- Buffer: foo ----------
This is the contents of the 5th foo.
---------- Buffer: foo ----------
(capitalize-region 1 44)
=> nil
---------- Buffer: foo ----------
This Is The Contents Of The 5th Foo.
---------- Buffer: foo ----------
* Command: downcase-region START END
This function converts all of the words in the region defined by
START and END to lower case. The function returns `nil'.
When `downcase-region' is called interactively, START and END are
point and mark, smallest first.
* Command: upcase-region START END
This function converts all of the words in the region defined by
START and END to upper case. The function returns `nil'.
When `downcase-region' is called interactively, START and END are
point and mark, smallest first.
* Command: capitalize-word COUNT
This function capitalizes COUNT words after point, moving point
over as it does. To `capitalize' means to convert each word's
first character is upper case and convert the rest of each word to
lower case. If COUNT is negative, the function capitalizes the
-COUNT previous words but does not move point.
When `capitalize-word' is called interactively, COUNT is set to
the numeric prefix argument.
* Command: downcase-word COUNT
This function converts the COUNT words after point to all lower
case, moving point over as it does. If COUNT is negative, it
converts the -COUNT previous words but does not move point.
When `downcase-word' is called interactively, COUNT is set to the
numeric prefix argument.
* Command: upcase-word COUNT
This function converts the COUNT words after point to all upper
case, moving point over as it does. If COUNT is negative, it
converts the -COUNT previous words but does not move point.
When `upcase-word' is called interactively, COUNT is set to the
numeric prefix argument.
▶1f◀
File: lispref Node: Underlining, Prev: Case Changes, Up: Text, Next: Registers
Underlining
===========
The underlining commands are somewhat obsolete. The
`underline-region' function actually inserts `_^H' before each
appropriate character in the region. This command provides a minimal
text formatting feature that might work on your printer; but you are
encouraged to use more powerful text formatting facilities instead, such
as Texinfo.
* Command: underline-region START END
This function underlines all nonblank characters in the region
defined by START and END. That is, an underscore character and a
backspace character are inserted just before each non-whitespace
character in the region. However, the backspace characters are
displayed by Emacs as either `\010' or `^H', depending on the
setting of `ctl-arrow'.
* Command: ununderline-region START END
This function removes all underlining (overstruck underscores) in
the region defined by START and END.
▶1f◀
File: lispref Node: Registers, Prev: Underlining, Up: Text
Registers
=========
A register is a user-level variable in emacs that can hold a marker, a
string, or a rectangle. Emacs has 255 accessible registers (`C-g'
cannot be used as the name of one). The registers include the CTL and
META keys; each register is named by a character.
* Variable: register-alist
This variable is an alist of elements in the form `(NAME .
CONTENTS)'. Normally, there is one element for each Emacs register
that has been used. NAME is a character (a number), identifying
the register. CONTENTS is a string, marker, or list. A list
represents a rectangle; its elements are strings.
* Command: view-register REG
This command displays what is contained in the register named
REG. REG is a character.
* Function: get-register REG
This function returns the contents of the register named REG, or
`nil' if it has no contents. The name of the register is a
character.
* Function: set-register REG VALUE
This function sets the contents of the register named REG to
VALUE. A register can be set to any value; however, the various
other register functions know only about strings, markers, and
lists.
* Command: point-to-register REG
This command stores both the current location of point and the
current buffer in a register as a marker. The argument REG must be
a character, which names the register.
* Command: register-to-point REG
This command moves point to the location in the buffer that was
stored in the register named by the argument. The argument must be
a character. Since both the buffer and the location within the
buffer are stored by the `point-to-register' function, this command
can switch you to another buffer.
* Command: insert-register REG &optional BEFOREP
This command inserts contents of register REG into the current
buffer. REG is a character that names the register.
Normally, this command puts point before and mark after the
inserted text. If the optional second argument, BEFOREP is
non-`nil', the command puts mark before and point after. You can
pass a non-`nil' second argument `beforep' to this function
interactively by supplying it with a prefix argument.
* Command: copy-to-register REG START END &optional DELETE-FLAG
This command copies the region from START to END into register
REG. If DELETE-FLAG is non-`nil', this command deletes the region
from the buffer after copying it into the register.
* Command: prepend-to-register REG START END &optional DELETE-FLAG
This command prepends the region from START to END into register
REG. If DELETE-FLAG is non-`nil', this command deletes the region
from the buffer after copying it to the register.
* Command: append-to-register REG START END &optional DELETE-FLAG
This command appends the region from START to END to the text
already in register REG. If DELETE-FLAG is non-`nil', this command
deletes the region from the buffer after copying it to the
register.
* Command: copy-rectangle-to-register REG START END &optional DELETE-FLAG
This command copies a rectangular region from START to END into
register REG. If DELETE-FLAG is non-`nil', this command deletes
the region from the buffer after copying it to the register.
▶1f◀
File: lispref Node: Searching and Matching, Prev: Text, Up: Top, Next: Syntax Tables
Searching and Matching
**********************
GNU Emacs provides two ways to search through a buffer for specified
text: exact string searches and regular expression searches. "Matching"
may be used following a regular expression search to specify the
positions of sub-expressions found by a regular expression search. This
chapter also describes replacement functions.
* Menu:
* Searching for Strings::
* Regular Expressions::
* Regular Expression Searching::
* Replacement::
* Match Data::
* Standard Regexps::
* Searching and Case::
▶1f◀
File: lispref Node: Searching for Strings, Prev: Searching and Matching, Up: Searching and Matching, Next: Regular Expressions
Searching for Strings
=====================
* Command: search-forward STRING &optional LIMIT NOERROR REPEAT
This function searches forward from point for an exact match for
STRING. It sets point to the end of the occurrence found, and
returns `t'.
In this example, point is positioned at the beginning of the
line. Then `(search-forward "fox")' is evaluated in the minibuffer
and point is left after the last letter of `fox':
---------- Buffer: foo ----------
-!-The quick brown fox jumped over the lazy dog.
---------- Buffer: foo ----------
(search-forward "fox")
=> t
---------- Buffer: foo ----------
The quick brown fox-!- jumped over the lazy dog.
---------- Buffer: foo ----------
If LIMIT is non-`nil' (it must be a position in the current
buffer), then it is the upper bound to the search. No match
extending after that position is accepted.
If NOERROR is `nil', then a `search-failed' error is signaled.
If NOERROR is `t', then if the search fails, it just returns `nil',
and doesn't signal an error. If NOERROR is neither `nil' nor `t',
then `search-forward' moves the point to LIMIT and returns `nil'.
If REPEAT is non-`nil', then the search is repeated that many
times, the point being positioned at the end of the last match.
* Command: search-backward STRING &optional LIMIT NOERROR REPEAT
This function searches backward from point for STRING. It is the
exact analog of `search-forward'. It leaves the point at the
beginning of the string matched.
* Command: word-search-forward STRING &optional LIMIT NOERROR REPEAT
This function searchs forward from the point for a ``word'' match
for STRING. It sets the point to the end of the occurrence found,
and returns `t'.
A word search differs from a simple string search in that a word
search *requires* that the words it searches for are separate words
(searching for the word `ball' will not match the word `balls'),
and punctuation and spacing is ignored (searching for `ball boy'
will match `ball. Boy!').
In the example, the point is first placed at the beginning of the
buffer; the search leaves it between the `y' and the `!'.
---------- Buffer: foo ----------
-!-He said ``Please! Find
the ball boy!''
---------- Buffer: foo ----------
(word-search-forward "Please find the ball, boy.")
=> t
---------- Buffer: foo ----------
He said ``Please! Find
the ball boy-!-!''
---------- Buffer: foo ----------
If LIMIT is non-`nil' (it must be a position in the current
buffer), then it is the upper bound to the search. The match found
must not extend after that position.
If NOERROR is `t', then `word-search-forward' returns `nil' when
a search fails, instead of signalling an error. If NOERROR is
neither `nil' nor `t', then `word-search-forward' moves point to
LIMIT and returns `nil'.
If REPEAT is non-`nil', then the search is repeated that many
times, the point being positioned at the end of the last match.
When `word-search-forward' is called interactively, Emacs prompts
you for the search string; LIMIT and NOERROR, are set to `nil', and
REPEAT is set to 1.
* Command: word-search-backward STRING
This function searches backward from the point for a word match
to STRING. This function is the exact analog to
`word-search-forward'.
▶1f◀
File: lispref Node: Regular Expressions, Prev: Searching for Strings, Up: Searching and Matching, Next: Regular Expression Searching
Regular Expression Syntax
=========================
A "regular expression" ("regexp", for short) is a pattern that denotes
a set of strings, possibly an infinite set. Searching for matches for a
regexp is a very powerful operation. In GNU Emacs, you can search for
the next match for a regexp either incrementally or not. Incremental
search commands are described in the `The GNU Emacs User Manual'. *Note
Regular Expression Search: (emacs)Regexp Search.
Also, *Note Major Modes: Major Modes..
* Menu:
* Complex Regexp Example:: Illustrates regular expression syntax.
Regular expressions have a syntax in which a few characters are
special constructs and the rest are "ordinary". An ordinary character
is a simple regular expression which matches that character and nothing
else. The special characters are `$', `^', `.', `*', `+', `?', `[', `]'
and `\'; no new special characters will be defined in the future. Any
other character appearing in a regular expression is ordinary, unless a
`\' precedes it. If a regular expression is malformed, an
`invalid-regexp' error signaled.
For example, `f' is not a special character, so it is ordinary, and
therefore `f' is a regular expression that matches the string `f' and no
other string. (It does *not* match the string `ff'.) Likewise, `o' is
a regular expression that matches only `o'.
Any two regular expressions A and B can be concatenated. The result is
a regular expression which matches a string if A matches some amount of
the beginning of that string and B matches the rest of the string.
As a simple example, we can concatenate the regular expressions `f' and
`o' to get the regular expression `fo', which matches only the string
`fo'. Still trivial. To do something nontrivial, you need to use one
of the special characters. Here is a list of them:
`. (Period)'
is a special character that matches any single character except a
newline. Using concatenation, we can make regular expressions like
`a.b' which matches any three-character string which begins with
`a' and ends with `b'.
`*'
is not a construct by itself; it is a suffix, which means the
preceding regular expression is to be repeated as many times as
possible. In `fo*', the `*' applies to the `o', so `fo*' matches
one `f' followed by any number of `o's. The case of zero `o's is
allowed: `fo*' does match `f'.
`*' always applies to the *smallest* possible preceding expression.
Thus, `fo*' has a repeating `o', not a repeating `fo'.
The matcher processes a `*' construct by matching, immediately, as
many repetitions as can be found. Then it continues with the rest
of the pattern. If that fails, backtracking occurs, discarding
some of the matches of the `*'-modified construct in case that
makes it possible to match the rest of the pattern. For example,
matching `ca*ar' against the string `caaar', the `a*' first tries
to match all three `a's; but the rest of the pattern is `ar' and
there is only `r' left to match, so this try fails. The next
alternative is for `a*' to match only two `a's. With this choice,
the rest of the regexp matches successfully.
`+'
Is a suffix character similar to `*' except that it requires that
the preceding expression be matched at least once. So, for
example, `ca+r' will match the strings `car' and `caaaar' but not
the string `cr', whereas `ca*r' would match all three strings.
`?'
Is a suffix character similar to `*' except that it can match the
preceding expression either once or not at all. For example,
`ca?r' will match `car' or `cr'; nothing else.
`[ ... ]'
`[' begins a "character set", which is terminated by a `]'. In the
simplest case, the characters between the two form the set. Thus,
`[ad]' matches either one `a' or one `d', and `[ad]*' matches any
string composed of just `a's and `d's (including the empty string),
from which it follows that `c[ad]*r' matches `cr', `car', `cdr',
`caddaar', etc.
Character ranges can also be included in a character set, by
writing two characters with a `-' between them. Thus, `[a-z]'
matches any lower-case letter. Ranges may be intermixed freely
with individual characters, as in `[a-z$%.]', which matches any
lower case letter or `$', `%' or period.
Note that the usual special characters are not special any more
inside a character set. A completely different set of special
characters exists inside character sets: `]', `-' and `^'.
To include a `]' in a character set, you must make it the first
character. For example, `[]a]' matches `]' or `a'. To include a
`-', write `---', which is a range containing only `-'. To include
`^', make it other than the first character in the set.
`[^ ... ]'
`[^' begins a "complement character set", which matches any
character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
all characters *except* letters and digits.
`^' is not special in a character set unless it is the first
character. The character following the `^' is treated as if it
were first (`-' and `]' are not special there).
Note that a complement character set can match a newline, unless
newline is mentioned as one of the characters not to match.
`^'
is a special character that matches the empty string, but only if
at the beginning of a line in the text being matched. Otherwise it
fails to match anything. Thus, `^foo' matches a `foo' which occurs
at the beginning of a line.
When matching a string, `^' matches at the beginning of the string
or after a newline character `\n'.
`$'
is similar to `^' but matches only at the end of a line. Thus,
`xx*$' matches a string of one `x' or more at the end of a line.
When matching a string, `^' matches at the end of the string or
before a newline character `\n'.
`\'
has two functions: it quotes the special characters (including
`\'), and it introduces additional special constructs.
Because `\' quotes special characters, `\$' is a regular expression
which matches only `$', and `\[' is a regular expression which
matches only `[', and so on.
Note that `\' also has special meaning inside the read syntax of
Lisp strings (*Note String Type::). Therefore, to build a regular
expression that matches the `\' character, you must preceed each
`\' in `"\\"' with another `\', i.e., `"\\\\"'.
Note: for historical compatibility, special characters are treated as
ordinary ones if they are in contexts where their special meanings make
no sense. For example, `*foo' treats `*' as ordinary since there is no
preceding expression on which the `*' can act. It is poor practice to
depend on this behavior; better to quote the special character anyway,
regardless of where is appears.
For the most part, `\' followed by any character matches only that
character. However, there are several exceptions: characters which,
when preceded by `\', are special constructs. Such characters are
always ordinary when encountered on their own. Here is a table of `\'
constructs.
`\|'
specifies an alternative. Two regular expressions A and B with
`\|' in between form an expression that matches anything that
either A or B will match.
Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
`\|' applies to the largest possible surrounding expressions. Only
a surrounding `\( ... \)' grouping can limit the grouping power of
`\|'.
Full backtracking capability exists to handle multiple uses of
`\|'.
`\( ... \)'
is a grouping construct that serves three purposes:
1. To enclose a set of `\|' alternatives for other operations.
Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
2. To enclose a complicated expression for the postfix `*' to
operate on. Thus, `ba\(na\)*' matches `bananana', etc., with
any (zero or more) number of `na' strings.
3. To mark a matched substring for future reference.
This last application is not a consequence of the idea of a
parenthetical grouping; it is a separate feature which happens to
be assigned as a second meaning to the same `\( ... \)' construct
because there is no conflict in practice between the two meanings.
Here is an explanation of this feature:
`\DIGIT'
after the end of a `\( ... \)' construct, the matcher remembers the
beginning and end of the text matched by that construct. Then,
later on in the regular expression, you can use `\' followed by
DIGIT to mean ``match the same text matched the DIGIT'th time by
the `\( ... \)' construct.''
The strings matching the first nine `\( ... \)' constructs
appearing in a regular expression are assigned numbers 1 through 9
in order that the open-parentheses appear in the regular
expression. `\1' through `\9' may be used to refer to the text
matched by the corresponding `\( ... \)' construct.
For example, `\(.*\)\1' matches any newline-free string that is
composed of two identical halves. The `\(.*\)' matches the first
half, which may be anything, but the `\1' that follows must match
the same exact text.
`\`'
matches the empty string, provided it is at the beginning of the
buffer.
`\''
matches the empty string, provided it is at the end of the buffer.
`\b'
matches the empty string, provided it is at the beginning or end of
a word. Thus, `\bfoo\b' matches any occurrence of `foo' as a
separate word. `\bballs?\b' matches `ball' or `balls' as a
separate word.
`\B'
matches the empty string, provided it is *not* at the beginning or
end of a word.
`\<'
matches the empty string, provided it is at the beginning of a
word.
`\>'
matches the empty string, provided it is at the end of a word.
`\w'
matches any word-constituent character. The editor syntax table
determines which characters these are.
`\W'
matches any character that is not a word-constituent.
`\sCODE'
matches any character whose syntax is CODE. CODE is a character
which represents a syntax code: thus, `w' for word constituent, `-'
for whitespace, `(' for open-parenthesis, etc. *Note Syntax
Tables::.
`\SCODE'
matches any character whose syntax is not CODE.
▶1f◀