|
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: 54223 (0xd3cf)
Types: TextFile
Names: »lispref-16«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-16«
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: Complex Regexp Example, Prev: Regular Expressions, Up: Regular Expressions
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 `sentence-end'.
First, the regexp is given in Lisp syntax to enable you to distinguish
the spaces from the tab characters. In Lisp syntax, the string constant
begins and ends with a double-quote. `\"' stands for a double-quote as
part of the regexp, `\\' for a backslash as part of the regexp, `\t' for
a tab and `\n' for a newline.
"[.?!][]\"')}]*\\($\\|\t\\| \\)[\n]*"
In contrast, if you evaluate the variable `sentence-end', you will see
the following:
sentence-end
=>
"[.?!][]\"')}]*\\($\\| \\| \\)[
]*"
In this case, the tab and carriage return are the actual characters.
This regular expression contains four parts in succession and can be
decyphered as follows:
`[.?!]'
The first part of the pattern consists of three characters, a
period, a question mark and an exclamation mark, within square
brackets. The match must begin with one or other of these
characters.
`[]\"')}]*'
The second part of the pattern is the group of closing braces and
quotation marks, which can appear zero or more times. These may
follow the period, question mark or exclamation mark. The `\"' is
Lisp syntax for a double quote in a string. The asterisk, `*',
indicates that the items in the previous group (the group
surrounded by square brackets, `[]') may be repeated zero or more
times.
`\\($\\|\t\\| \\)'
The third part of the pattern is one or other of: either the end of
a line, or a tab, or two blank spaces. The double back-slashes are
used to prevent Emacs from reading the parentheses and vertical
bars as part of the search pattern; the parentheses are used to
mark the group and the vertical bars are used to indicated that the
patterns to either side of them are alternatives. The dollar sign
is used to indicate the end of a line. The TAB character is
inserted using `\t' and the two spaces are inserted as is.
`[\n]*"'
Finally, the last part of the pattern indicates that the end of the
line or the whitespace following the period, question mark or
exclamation mark may, but need not, be followed by one or more
carriage returns.
* Function: regexp-quote STRING
This function returns a regular expression string which matches
exactly STRING and nothing else. This allows you to request an
exact string match when calling a function that wants a regular
expression.
(regexp-quote "^The cat$")
=> "\\^The cat\\$"
One use of `regexp-quote' is to combine an exact string match with
context described as a regular expression. For example, this
searches for the string which is the value of `string', surrounded
by whitespace:
(re-search-forward (concat "\\s " (regexp-quote string) "\\s "))
▶1f◀
File: lispref Node: Regular Expression Searching, Prev: Regular Expressions, Up: Searching and Matching, Next: Replacement
Regular Expression Searching
============================
A cluster of functions provide various features involved with regular
expression searches. The primary function is `re-search-forward'.
* Command: re-search-forward REGEXP &optional LIMIT NOERROR REPEAT
This function searches forward in the current buffer for a string
of text that is matched by the regular expression REGEXP. The
function skips over any amount of text that is not matched by
REGEXP, and leaves the point at the end of the first string of text
that does match.
If the search is successful (i.e., if there is text that is
matched by REGEXP), then point is left at the end of that text, and
the function returns `t'.
If there is no text matched by REGEXP, then a `search-failed'
error is signaled. However, if NOERROR is `t', then if the search
fails, `re-search-forward' returns `nil' without signaling an
error.
If LIMIT is supplied (it must be a number or a marker), it will
be the maximum position in the buffer that the point can be skipped
to. Point will be left at or before LIMIT. Also, the match found
must not extend after that position. This means that nothing can
be found beyond the LIMIT.
Also, if the search fails and NOERROR is neither `nil' nor `t',
then point is moved to and left at the LIMIT position; and the
function returns `nil'.
If REPEAT is supplied (it must be a positive number), then the
search is repeated that many times; and point left at the end of
the last match found.
When called interactively, Emacs prompts you for REGEXP in the
minibuffer.
In the example, point is located directly before the `T'. After
evaluating the form, it is located at the end of that line (between
the `t' of `hat' and before the newline).
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------
(re-search-forward "[a-z]+" nil t 5)
=> t
---------- Buffer: foo ----------
I read "The cat in the hat-!-
comes back" twice.
---------- Buffer: foo ----------
* Command: re-search-backward REGEXP &optional LIMIT NOERROR REPEAT
This function searches backward in the current buffer for a
string of text that is matched by the regular expression REGEXP,
leaving point at the beginning of the first text found. This
function is the exact analog of `re-search-forward'.
* Function: string-match REGEXP STRING &optional START
This function returns the index of the start of the first match
for the regular expression REGEXP in STRING, or `nil' if there is
no match. If START is non-`nil', the search is started at that
index in STRING.
For example,
(string-match "quick" "The quick brown fox jumped quickly.")
=> 4
(string-match "quick" "The quick brown fox jumped quickly." 8)
=> 27
The index of the first character of the string is 0, the index of
the second character is 1, and so on.
After this function returns, the index of the first character
beyond the match is available as `(match-end 0)'.
(string-match "quick" "The quick brown fox jumped quickly." 8)
=> 27
(match-end 0)
=> 32
The `match-end' function is described along with
`match-beginning'; *Note Match Data::.
* Function: looking-at REGEXP
This function determines whether the text in the current buffer
directly following the point matches the regular expression REGEXP.
``Directly following'' means precisely that: the search is
``anchored'' and it must succeed starting with the first character
following the point. The result is `t' if so, `nil' otherwise.
Point is not moved, but the match data is updated and can be used
with `match-beginning' or `match-end'.
In the example, the point is located directly before the `T'. If
it were anywhere else, the result would have been `nil'.
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------
(looking-at "The cat in the hat$")
=> t
▶1f◀
File: lispref Node: Replacement, Prev: Regular Expression Searching, Up: Searching and Matching, Next: Match Data
Replacement
===========
Emacs has several replacement commands for interactive use. For a
description of these, *Note Replacement Commands: (emacs)Replace..
The commands include:
`replace-regexp'
This function replaces every match of REGEXP occurring between
point and the maximum point by REPLACEMENT, which must be a string.
`replace-string'
This function replaces occurrences of STRING with REPLACEMENT.
The following function replaces characters, not strings, but is included
here since it involves replacement.
* Function: subst-char-in-region START END OLD-CHAR NEW-CHAR &optional NOUNDO
This function replaces all occurrences of the character OLD-CHAR
with the character NEW-CHAR in the region of the current buffer
defined by START and END.
If NOUNDO is non-`nil', then `subst-char-in-region' does not
record the change for undo and does not mark the buffer as
modified. This optional argument is used for obscure purposes, for
example, in Outline mode to change visible lines to invisible lines
and vice versa.
`subst-char-in-region' does not move point and returns `nil'.
---------- Buffer: foo ----------
This is the contents of the buffer before.
---------- Buffer: foo ----------
(subst-char-in-region 1 20 ?i ?X)
=> nil
---------- Buffer: foo ----------
ThXs Xs the contents of the buffer before.
---------- Buffer: foo ----------
▶1f◀
File: lispref Node: Match Data, Prev: Replacement, Up: Searching and Matching, Next: Standard Regexps
Match Data
==========
Emacs keeps track of the positions of the start and end of 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 extract different parts of it.
* Function: match-beginning COUNT
This function returns the position of the start of text matched
by the last regular expression searched for. COUNT, a number,
specifies which subexpression to return the start position of. If
COUNT is zero, then it returns the position of the text matched by
the whole regexp. If COUNT is greater than zero, then the position
of the beginning of the text matched by the COUNT'th subexpression
is returned, regardless of whether it was used in the final match.
Subexpressions are those expressions grouped inside of parentheses,
`\(...\)'. The COUNT'th subexpression is found by counting
occurances of `\(' from the beginning of the whole regular
expression. The first subexpression is 1, the second is 2, and so
on.
The `match-end' function is similar to the `match-beginning'
function except that it returns the position of the end of the
matched text.
(In the example, the positions in the text are numbered to make
the results more apparent.)
(string-match "\\(qu\\)\\(ick\\)" "The quick brown fox jumped quickly.")
=> 4 ;^^^^^^^^^^
;0123456789
(match-beginning 1) ; The beginning of the match
=> 4 ; with `qu' is at index 4.
(match-beginning 2) ; The beginning of the match
=> 6 ; with `ick' is at index 6.
(match-end 1) ; The end of the match
=> 6 ; with `qu' is at index 6.
(match-end 2) ; The end of the match
=> 9 ; with `ick' is at index 9.
The `match-end' function is used in functions such as
`rmail-make-basic-summary-line'.
Here is another example. Before the form is evaluated, the point
is located at the beginning of the line. After evaluating the
search form, it is located on the line between the space and the
word `in'. The beginning of the entire match is at the 9th
character of the buffer (`T'), and the beginning of the match for
the first subexpression is at the 13th character (`c').
(list
(re-search-forward "The \\(cat \\)")
(match-beginning 0)
(match-beginning 1))
=> (t 9 13)
---------- Buffer: foo ----------
I read "The cat -!-in the hat comes back" twice.
^ ^
9 13
---------- Buffer: foo ----------
(Note that in this case, the index returned is a buffer position;
the first character of the buffer counts as 1.)
It is essential that `match-beginning' be called after the search
desired and before any other searches are performed.
`match-beginning' may not give the desired results if called in a
separate command from the search. The example below is the wrong
way to call `match-beginning'.
(re-search-forward "The \\(cat \\)")
=> t
(foo) ; Perhaps `foo' does more regexp searching.
(match-beginning 0)
=> 61 ; Unexpected result!
See the discussion of `store-match-data' for an example of how to
save match data and restore the information after an intervening
search.
* Function: match-end COUNT
This function returns the position of the end of text matched by
the last regular expression searched for. This function is the
exact analog of `match-beginning'.
* Function: replace-match REPLACEMENT &optional FIXEDCASE LITERAL
This function replaces the text matched by the last search with
REPLACEMENT.
If FIXEDCASE is non-`nil', then the case of the replacement text
is not changed. Otherwise the replacement text is converted to a
different case depending upon the capitalization of the text to be
replaced. If the original text is all upper case, then the
replacement text is converted to upper case, except when all of the
words in the original text are only one character long. In that
event, the replacement text is capitalized. If *all* of the words
in the original text are capitalized, then all of the words in the
replacement text will be capitalized.
If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
it is, the only alterations being a possible change in case. If it
is NIL (the default), then the character `\' is treated specially.
If a `\' appears in REPLACEMENT, then it must be followed by one of
the following characters:
`\&'
`\&' is replaced by the entire original text.
`\N'
N is a digit. `\N' is replaced by the N'th subexpression in
the original regexp. Subexpressions are those expressions
grouped inside of `\(...\)'.
`\\'
`\\' is replaced by `\'.
`replace-match' leaves the point at the end of the replacement
text, and returns `t'.
* Function: match-data
This function returns a new list containing all the information
on what the last search matched. The zero'th element is the
beginning of the match for the whole expression; the first element
is the end of the match for the expression. The next two elements
are the beginning and end of the match for the first subexpression.
In general, the 2N'th element corresponds to `(match-beginning N)';
and element 2N + 1 corresponds to `(match-end N)'.
All the elements are markers, or `nil' if there was no match for
that subexpression. As with other search commands, there must be
no possibility of intervening searches between the call to a search
and the call to `match-data' that is intended to save the
match-data for that search.
(match-data)
=> (#<marker at 9 in foo> #<marker at 17 in foo>
#<marker at 13 in foo> #<marker at 17 in foo>)
* Function: store-match-data MATCH-LIST
This function sets the internal data structure for the ``last
search match'' to the elements of MATCH-LIST. MATCH-LIST should
have been created by calling `match-data' previously.
Together with `match-data', `store-match-data' may be used to avoid
changing the `match-data' if you do a regexp search. This is
useful when such searches occur in subroutines whose callers may
not expect searches to go on.
The following example illustrates the canonical use of these two
functions.
(let ((data (match-data)))
(unwind-protect
... ; May change the original match data.
(store-match-data data)))
All asynchronous process functions (filters and sentinels) and
some modes that use `recursive-edit' should save and restore the
match data if they do a search or if they let a user make a search.
Here is a function which will restore the match data if the buffer
associated with it still exists.
(defun restore-match-data (data)
"Restore the match data DATA unless the buffer is missing."
(catch 'foo
(let ((d data))
(while d
(and (car d)
(null (marker-buffer (car d)))
;; match-data buffer is deleted.
(throw 'foo nil))
(setq d (cdr d)))
(store-match-data data)
)))
▶1f◀
File: lispref Node: Standard Regexps, Prev: Match Data, Up: Searching and Matching, Next: Searching and Case
Standard Regular Expressions Used in Editing
============================================
* Variable: page-delimiter
This is the regexp describing line-beginnings that separate pages.
The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"').
* Variable: paragraph-separate
This is the regular expression for the beginning of a line that
separates paragraphs. (If you change this, you may have to change
`paragraph-start' also.) The default value is `"^[ \t\f]*$"',
which is a line that consists entirely of spaces, tabs, and form
feeds.
* Variable: paragraph-start
This is the regular expression for the beginning of a line that
starts *or* separates paragraphs. The default value is `"^[
\t\n\f]"', which means any number of spaces, tabs, newlines, and
form feeds.
* Variable: sentence-end
This is the regular expression describing the end of a sentence.
All paragraph boundaries also end sentences, regardless. Default
value is `"[.?!][]\"')}]*\\($\\|\t\\| \\)[ \t\n]*"'. This means a
period, question mark or exclamation mark, followed by a closing
brace, followed by tabs, spaces or new lines.
For a full description of this regular expression, *Note Complex
Regexp Example::.
▶1f◀
File: lispref Node: Searching and Case, Prev: Standard Regexps, Up: Searching and Matching
Searching and Case
==================
By default, searches in Emacs ignore the case of the text they are
searching through; if you specify searching for `FOO', then `Foo' and
`foo' are also considered a match. Regexps, and in particular character
sets, are included: `[aB]' would match `a' or `A' or `b' or `B'.
If you do not want this feature, set the variable `case-fold-search'
to `nil'. Then all letters must match exactly, including case. This is
a per-buffer-local variable; altering the variable affects only the
current buffer. (*Note Buffer Local Variables::.) Alternatively, you
may change the value of `default-case-fold-search', which is the default
value of `case-fold-search' for buffers that do not override it.
* User Option: case-replace
This variable determines whether `query-replace' should preserve
case in replacements. If the variable is `nil', then case need not
be preserved.
* User Option: case-fold-search
This buffer-local variable determines whether searches should
ignore case. If the variable is `nil' they will not, if it is `t',
then they will ignore case.
* Variable: default-case-fold-search
The value of this variable is the default value for
`case-fold-search' in buffers that do not override it. This is the
same as `(default-value 'case-fold-search)'.
▶1f◀
File: lispref Node: Syntax Tables, Prev: Searching and Matching, Up: Top, Next: Lisp Expressions
Syntax Tables
*************
A "syntax table" provides Emacs with the information that Emacs needs
to determine the syntatic use of each character in a buffer. This
information is used by the parsing commands, the complex movement
commands, and others, to determine where words, symbols, and other
syntactic constructs begin and end.
A syntax table is a vector of 256 elements; it contains one entry for
each of the 256 ASCII characters of an 8-bit byte. Each element is an
integer which encodes the syntax of the character in question.
Syntax tables are used only for moving across text, not for the GNU
Emacs Lisp reader. GNU Emacs Lisp uses built-in C code to read Lisp
expressions and does not use syntax tables.
Each different buffer may be in a different major mode, and each
different major mode may have a different definition of the syntactic
class of a given character. For example, in Lisp mode, the character
`;' begins a comment, but in C mode, it terminates a statement. Syntax
tables are local to each buffer, but a major mode will usually provide
the same syntax table to all buffers that use the mode. *Note Major
Modes::, for an example of how to set up a syntax table.
* Function: syntax-table-p OBJECT
This function returns `t' if OBJECT is a vector of length 256
elements. This means that the vector may be a syntax table.
However, according to this test, any vector of length 256 is
considered to be a syntax table, no matter what its contents.
* Menu:
* Syntax Classes::
* Syntax Table Functions::
* Some Standard Syntax Tables::
* Syntax Table Internals::
▶1f◀
File: lispref Node: Syntax Classes, Prev: Syntax Tables, Up: Syntax Tables, Next: Syntax Table Functions
Syntax Classes
==============
A character belongs to one of twelve "syntax classes". Often,
different tables put characters into different classes; there does not
need be any relation between the class of a character in one table and
its class in any other.
Most of the functions that operate on syntax tables use characters to
represent the classes; the character that represents each class is
chosen as a mnemonic.
Here is a summary of the classes, and the characters that stand for
the classes:
`SPC'
Whitespace syntax
`w'
Word constituent
`_'
Symbol constituent
`.'
Punctuation
`('
Open-parenthesis
`)'
Close-parenthesis
`"'
String quote
`\'
Character quote
`$'
Paired delimiter
``'
Expression prefix operator
`<'
Comment starter
`>'
Comment ender
* Syntax-class: whitespace CHARACTERS
"Whitespace characters" divide symbols and words from each other.
Typically, whitespace characters have no other syntactic use and
multiple whitespace characters are considered as one. Space, tab,
newline, formfeed are almost always considered whitespace.
* Syntax-class: word CONSTITUENTS
"Word constituents" are parts of normal English words and are
typically used in variable and command names in programs. All
upper and lower case letters and the digits are typically word
constituents.
* Syntax-class: symbol CONSTITUENTS
"Symbol constituents" are the extra characters, that along with
word constituents, are used in variable and command names. The
symbol constituents class may be used, for example, to allow Lisp
symbols to include extra characters without changing the notion
that a word is an element of the English language. In Lisp, symbol
constituents are `$&*+-_<>'. In standard C, the only
non-word-constituent character that is valid in symbols is
underscore (`_').
* Syntax-class: punctuation CHARACTERS
"Punctuation characters" are those characters that are used as
punctuation in English, or are used in some way in a programming
languages to separate symbols from one another. Most programming
language modes, including Emacs Lisp mode, do not have any
characters in this class since the few characters that are not
symbol or word constituents all have other uses.
* Syntax-class: parenthesis CHARACTERS
Open and close "parenthesis characters" come in pairs of matching
characters that allow one to surround sentences or expressions. In
English text, and in C code, these are `()', `[]', and `{}'. In
Lisp, the list and vector delimiting characters (`()' and `[]') are
parenthesis characters.
Normally, Emacs shows a matching open parenthesis when you type a
closing parenthesis. *Note Blinking::.
* Syntax-class: string QUOTE
In many programming languages including Lisp, a pair of "string
quote characters" delimit a string of characters. English text has
no string quote characters because it is not a programming
language. Emacs Lisp has two string quote characters: double quote
(`"') and vertical bar (`|'), although there is no use in Emacs
Lisp of the ``|'' character. C also has two string quote
characters: double quote for strings, and single quote (`'') for
character constants.
* Syntax-class: character QUOTE
A "character quote character" quotes the following character such
that it loses its normal syntax meaning. In regular expressions,
the backslash (`\') does this.
* Syntax-class: delimiter CHARACTERS
Paired "delimiter characters" serve a similar purpose to string
quote characters, but differ in that the same character is used at
the beginning and end. Only TeX mode uses paired delimiters
presently---the `$' that begins and ends math mode.
* Syntax-class: expression PREFIX
An "expression prefix operator" is used in Lisp for things that go
next to an expression but aren't part of a symbol if they are next
to it, such as the apostrophe, `'', used for quoting and the comma,
`,' used in macros.
* Syntax-class: comment STARTER
The "comment starter" and "comment ender" characters are used in
different languages to delimit comments. English text has no
comment characters. In Lisp, the semi-colon (`;') starts a comment
and a newline or formfeed ends one.
In addition to these classes, entries for characters in a syntax table
can include flags. At present, there are four possible flags, all of
which are intended to deal with multi-character comment delimiters. The
four flags (represented by the characters `1', `2', `3', and `4')
indicate that the character for which the entry is being made can *also*
be part of a comment sequence. Thus an asterisk (used for
multiplication in C) is a punctuation character, *and* the second
character of a start-of-comment sequence (`/*'), *and* the first
character of an end-of-comment sequence (`*/').
The flags for a character C are:
`1'
means C is the start of a two-character comment start sequence.
`2'
means C is the second character of such a sequence.
`3'
means C is the start of a two-character comment end sequence.
`4'
means C is the second character of such a sequence.
Thus, the entry for the character ``*'' in the C syntax table is:
`.23' (i.e., punctuation, second character of a comment-starter, first
character of an comment--ender), and the entry for `/' is `.14' (i.e.,
punctuation, first character of a comment-starter, second character of a
comment-ender).
▶1f◀
File: lispref Node: Syntax Table Functions, Prev: Syntax Classes, Up: Syntax Tables, Next: Some Standard Syntax Tables
Syntax Table Functions
======================
The syntax table functions all work with strings of characters that
represent a syntax class. The representative characters are chosen to
be mnemonic.
* Function: make-syntax-table &optional TABLE
This function constructs a copy of TABLE and returns it. If
TABLE is not supplied, it returns a copy of the current syntax
table.
It is an error if TABLE is not a syntax table.
* Function: copy-syntax-table &optional TABLE
This function is identical to `make-syntax-table'.
* Command: modify-syntax-entry CHAR SYNTAX-STRING &optional TABLE
This function sets the syntax entry for CHAR according to
SYNTAX-STRING. The syntax is changed only for TABLE, which
defaults to the current buffer's syntax table. The syntax string
defines the new syntax for the character according to the
definitions for the representation characters (*Note Syntax
Classes::).
The old syntax information in the table for this character is
completely forgotten.
This function always returns `nil'. It is an error if the first
character of the syntax string is not one of the twelve syntax
class characters. It is an error if CHAR is not a character.
The first example makes the SPC character an element of the class
of whitespace. The second example, makes ``$'' an open parenthesis
character, with ``^'' as its matching close parenthesis character.
The third example example makes ``^'' a close parenthesis
character, with ``$'' its matching open parenthesis character. The
fourth example makes ``/'' a punctuation character, the first
character of a start-comment sequence, and the second character of
an end-comment sequence.
(modify-syntax-entry ?\ " ") ; space
=> nil
(modify-syntax-entry ?$ "(^")
=> nil
(modify-syntax-entry ?^ ")$")
=> nil
(modify-syntax-entry ?/ ".13")
=> nil
* Function: char-syntax CHARACTER
This function returns the syntax class of CHARACTER, represented
by its mnemonic character. This *only* returns the class, not any
matching parentheses, or flags.
It is an error if CHAR is not a character.
The first example shows that the syntax class of space is
whitespace (represented by a space). The second example shows that
the syntax of ``/'' is punctuation in C-mode. This does not show
the fact that it is also a comment sequence character. The third
example shows that open parenthesis is in the class of open
parentheses. This does not show the fact that it has a matching
character, ``)''.
(char-to-string (char-syntax ? ))
=> " "
(char-to-string (char-syntax ?/))
=> "."
(char-to-string (char-syntax ?( ))
=> "("
* Function: set-syntax-table TABLE
This function makes TABLE the syntax table for the current
buffer. It returns TABLE.
* Function: syntax-table
This function returns the current syntax table. This is the
table for the current buffer.
* Function: backward-prefix-chars
This function moves the point backward over any number of chars
with syntax PREFIX. *Note Syntax Tables::, to find out about
prefix characters.
* command: describe-syntax
This function describes the syntax specifications of the current
syntax table. It makes a listing in the `*Help*' buffer, and then
pops up a window to view this in.
It returns `nil'.
A portion of a description is shown below.
(describe-syntax)
=> nil
---------- Buffer: *Help* ----------
C-q \ which means: escape
C-r .. C-_ which means: whitespace
! . which means: punctuation
( () which means: open, matches )
) )( which means: close, matches (
* .. + _ which means: symbol
, . which means: punctuation
- _ which means: symbol
. . which means: punctuation
/ . 13 which means: punctuation,
is the first character of a comment-start sequence,
is the first character of a comment-end sequence
0 .. 9 w which means: word
---------- Buffer: *Help* ----------
▶1f◀
File: lispref Node: Some Standard Syntax Tables, Prev: Syntax Table Functions, Up: Syntax Tables, Next: Syntax Table Internals
Some Standard Syntax Tables
===========================
Each of the major modes in Emacs has its own syntax table. Here are
several of them:
* Function: standard-syntax-table
This function returns the standard syntax table. This is the
syntax table used in Fundamental mode.
* Variable: text-mode-syntax-table
The value of this variable is the syntax table used in text mode.
* Variable: c-mode-syntax-table
The value of this variable is the syntax table in use in C-mode
buffers.
* Variable: emacs-lisp-mode-syntax-table
The value of this variable is the syntax table used in Emacs Lisp
mode by editing commands. (It has no effect on the Lisp `read'
function.)
▶1f◀
File: lispref Node: Syntax Table Internals, Prev: Some Standard Syntax Tables, Up: Syntax Tables
Syntax Table Internals
======================
Each element of a syntax table is an integer which translates into the
full meaning of the entry: class, possible matching character, and
flags. However, it is not common for a programmer to work with the
entries directly in this form since the syntax table functions all
expect a string of representative characters. In such a string, the
first character of the string will always be the class of the character;
the second character will be the matching parenthesis (if it is a
parenthesis character); and the subsequent characters will be the flags,
if any.
The low 8 bits of each element of a syntax table indicates the
syntax class.
`Integer'
Class
`0'
whitespace
`1'
punctuation
`2'
word
`3'
symbol
`4'
open paren
`5'
close paren
`6'
expression prefix
`7'
string quote
`8'
`9'
character quote
`10'
`11'
comment-start
`12'
comment-end
The next 8 bits are the matching opposite parenthesis (if the
character has parenthesis syntax); otherwise, they are not meaningful.
The next 4 bits are the flags.
▶1f◀
File: lispref Node: Lisp Expressions, Prev: Syntax Tables, Up: Top, Next: Abbreviations
Lisp Expressions
****************
Here are several functions for parsing and scanning Lisp expressions.
* Function: parse-partial-sexp START LIMIT &optional TARGET-DEPTH STOP-BEFORE STATE
This function parses Lisp syntax in the current buffer starting
at START and not reading past LIMIT. It returns the status of the
parse at LIMIT. Parsing stops at LIMIT or when certain criteria
are met described below; point is set to where parsing stops.
Normally, START is assumed to be the top level of a form to be
parsed, such as the beginning of a function definition. If you
wish to continue a previous parse, you must provide a STATE
argument, which describes the initial status of parsing. If STATE
is omitted (or `nil'), parsing assumes that START is the beginning
of a new parse at level 0.
If the third argument TARGET-DEPTH is non-`nil', parsing stops if
the depth in parentheses becomes equal to TARGET-DEPTH. The depth
starts at 0, or at whatever is given in STATE.
If the fourth argument STOP-BEFORE is non-`nil', parsing stops
when it comes to any character that starts a sexp.
The fifth argument STATE is a seven-element list in the same form
as this function returns, described below. the return value of one
call may be used to initialize the state of the parse on another
call to `parse-partial-sexp'.
The result is a list of seven elements describing the final state
of the parse:
1. Depth in parens, starting at 0.
2. Character position of the start of the innermost containing
list; `nil' if none.
3. Character position of the start of the last complete sexp
terminated; `nil' if none.
4. Non-`nil' if inside a string. (It is the character that will
terminate the string.)
5. `t' if inside a comment.
6. `t' if point is just after a quote character.
7. The minimum paren-depth encountered during this scan.
Elements 1, 4, 5, and 6 are significant in the argument STATE.
This function is used to determine how to indent lines of programs
that have nested lists.
* Function: scan-lists FROM COUNT DEPTH
This function scals from character number FROM by COUNT lists.
It returns the character number of the position thus found.
If DEPTH is nonzero, parenthesis depth counting begins from that
value. Only places where the depth in parentheses becomes zero are
candidates for stopping; COUNT such places are counted. Thus, a
positive value for DEPTH means go out levels of parenthesis.
Comments are ignored if `parse-sexp-ignore-comments' is
non-`nil'.
If the beginning or end of (the accessiblepart of) the buffer is
reached and the depth is not zero, an `end-of-file' error is
signaled. If the depth is zerobut the count is not used up, `nil'
is returned.
* Function: scan-sexps FROM COUNT
Scan from character number FROM by COUNT balanced expressions.
Returns the character number of the position thus found.
Comments are ignored if `parse-sexp-ignore-comments' is
non-`nil'.
If the beginning or end of (the accessible part of) the buffer is
reached in the middle of a parenthetical grouping, an `end-of-file'
error is signaled. If the beginning or end is reached between
groupings but before count is used up, `nil' is returned.
* Variable: parse-sexp-ignore-comments
Non-`nil' means `forward-sexp', etc., should treat comments as
whitespace. Non-`nil' works only when the comment terminator is
something like `*/', and appears only when it ends a comment. If
comments are terminated by newlines, you must make this variable
`nil', since not every newline is the end of a comment. (In
version 19, this limitation is removed.)
▶1f◀
File: lispref Node: Abbreviations, Prev: Lisp Expressions, Up: Top, Next: Processes
Abbreviations
*************
An abbreviation or "abbrev" is a string of characters that may be
expanded to a longer string. If you type a part of an abbreviation,
Emacs replaces the abbreviation with the full string. This saves typing
and makes life easier.
The set of abbrevs currently in effect is recorded in an "abbrev
table". Each buffer can have its own abbrev table, but normally all
buffers in the same major mode share one abbrev table.
An abbrev table is represented as an obarray containing non-canonical
symbols, one for each abbreviation. The symbol's name is the
abbreviation. Its value is the expression; its function definition is
the hook; its property-list slot contains the number of times the
abbreviation has been expanded.
Use of all the abbreviation-related commands is described in the GNU
Emacs User Manual *Note Abbrev Mode: (emacs)Abbrev Mode.
* Menu:
* Abbrev Mode:: Setting up Emacs for abbreviation.
* Tables: Abbrev Tables. Creating and working with abbrev tables.
* Defining Abbrevs:: Specifying what to use as abbreviations.
* Files: Abbrev Files. Saving abbrevs in files.
* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
* Standard Abbrev Tables:: Several standard tables.
▶1f◀
File: lispref Node: Abbrev Mode, Prev: Abbreviations, Up: Abbreviations, Next: Abbrev Tables
Setting Up Abbrev Mode
==========================
Abbrev mode is a minor mode controlled by the value of the variable
`abbrev-mode'.
* Variable: abbrev-mode
A non-`nil' value of this variable turns on the automatic expansion
of abbrevs when their abbreviations are inserted into a buffer. If
the value is `nil', abbrevs may be defined, but they are not
expanded automatically.
Automatically becomes local when set in any fashion.
* Variable: default-abbrev-mode
This is the value `abbrev-mode' for buffers that do not override
it. This is the same as `(default-value 'abbrev-mode)'.
▶1f◀
File: lispref Node: Abbrev Tables, Prev: Abbrev Mode, Up: Abbreviations, Next: Defining Abbrevs
Abbrev Tables
=============
* Function: make-abbrev-table
This function creates a new, empty abbrev table---an obarray with
no symbols. It is a vector filled with `nil's.
* Function: clear-abbrev-table TABLE
This function undefines all the abbrevs in abbrev table TABLE,
leaving it empty.
* Function: define-abbrev-table TABNAME DEFINITIONS
This function defines TABNAME (a symbol) as an abbrev table name,
i.e., as a variable whose value is an abbrev table. Define abbrevs
in the table according to DEFINITIONS, a list of elements of the
form `(ABBREVNAME EXPANSION HOOK USECOUNT)'.
* Variable: abbrev-table-name-list
This is a list of symbols whose values are abbrev tables.
`define-abbrev-table' adds the new abbrev table name to this list.
* Function: insert-abbrev-table-description NAME HUMAN
This function inserts before point a description of the abbrev
table named NAME. NAME is a symbol whose value is an abbrev table.
If HUMAN is non-`nil', a human-oriented description is inserted.
Otherwise the description is a Lisp expression---a call to
`define-abbrev-table' which would define NAME exactly as it is
currently defined.
▶1f◀
File: lispref Node: Defining Abbrevs, Prev: Abbrev Tables, Up: Abbreviations, Next: Abbrev Files
Defining Abbrevs
================
* Function: add-abbrev TABLE TYPE ARG
This function adds an abbreviation to abbrev table TABLE. TYPE is
a string saying what kind of abbrev this is (global or
mode-specific, or whatever). ARG is the number of words in the
expansion.
* Function: define-abbrev TABLE NAME EXPANSION HOOK
This function defines an abbrev in TABLE named NAME, to expand to
EXPANSION, and call HOOK. NAME and EXPANSION are strings.
HOOK is a function or `nil'. If HOOK is non-`nil', then it is
called with no arguments after the abbrev is replaced with
EXPANSION; point is located at the end of EXPANSION.
The use-count of the abbrev is initialized to zero.
To undefine an abbrev, define it with EXPANSION = `nil'
* User Option: only-global-abbrevs
If the the value of this variable is `t', it means that the user
plans to use global abbrevs only. This makes the commands that
define mode-specific abbrevs define global ones instead.
* Variable: edit-abbrevs-map
This is the keymap used in `edit-abbrevs'.
▶1f◀
File: lispref Node: Abbrev Files, Prev: Defining Abbrevs, Up: Abbreviations, Next: Abbrev Expansion
Saving Abbrevs in Files
=======================
* User Option: abbrev-file-name
This is the default name of the file to read abbrevs from and to
save them in.
* Function: quietly-read-abbrev-file FILE
This function reads abbrev definitions from a file named FILE,
previously written with `write-abbrev-file'. If FILE is `nil', the
file specified in `abbrev-file-name' is used. `save-abbrevs' is
set to `t' so that changes will be saved.
This function does not print anything.
* User Option: save-abbrevs
A non-`nil' value for `save-abbrev' means that Emacs should save
word abbrevs when files are saved. `abbrev-file-name' specifies
the file to save in.
* Variable: abbrevs-changed
This variable is set non-`nil' by defining or altering any word
abbrevs. This serves as a flag for various Emacs commands to offer
to save your abbrevs.
* Command: write-abbrev-file FILE
Save all abbrev definitions, in all abbrev tables, in file FILE as
a Lisp program which will redefine the abbrevs when it is run.
▶1f◀
File: lispref Node: Abbrev Expansion, Prev: Abbrev Files, Up: Abbreviations, Next: Standard Abbrev Tables
Looking Up and Expanding Abbreviations
======================================
Abbrevs are usually expanded by commands for interactive use, or
automatically by `self-insert'. This section describes the subroutines
used in writing such functions, and the variables they use for
communication.
* Function: abbrev-symbol ABBREV TABLE
This function returns the symbol representing the abbrev named
ABBREV. The value returned is `nil' if that abbrev is not defined.
The optional second argument TABLE is the abbrev table to look it
up in. By default, this function tries the buffer's mode-specific
abbrev table, and then the global table.
* User Option: abbrev-all-caps
When this is set non-`nil', Emacs expands multi-word abbrevs using
all upper case letters if the abbrev was all in upper case.
* Function: abbrev-expansion ABBREV &optional TABLE
This function returns the string that ABBREV expands into in the
current buffer. Optionally specify an abbrev TABLE; then ABBREV is
looked up in that table only.
* Variable: abbrev-start-location
This is the buffer position for `expand-abbrev' to use as the start
of the abbrev to expand. `nil' means use the word before point as
the abbrev. `abbrev-start-location' is set to `nil' each time
`expand-abbrev' is called. This variable is set by
`abbrev-prefix-mark'.
* Variable: abbrev-start-location-buffer
The value of this variable is the buffer that
`abbrev-start-location' has been set for. Trying to expand an
abbrev in any other buffer clears `abbrev-start-location'. This
variable is set by `abbrev-prefix-mark'.
* Variable: last-abbrev
This is the `abbrev-symbol' of the last abbrev expanded. This
contains information left by `expand-abbrev' for the sake of the
`unexpand-abbrev' command.
* Variable: last-abbrev-location
This is the location of the last abbrev expanded. This contains
information left by `expand-abbrev' for the sake of the
`unexpand-abbrev' command.
* Variable: last-abbrev-text
This is the exact expansion text of the last abbrev expanded, as
results from case conversion. Its value is `nil' if the abbrev has
already been unexpanded. This contains information left by
`expand-abbrev' for the sake of the `unexpand-abbrev' command.
▶1f◀
File: lispref Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbreviations
Standard Abbrev Tables
======================
* Variable: global-abbrev-table
This is the abbrev table whose abbrevs affect all buffers. Each
buffer may also have a local abbrev table. If it does, the local
table overrides the global one for any particular abbrev defined in
both.
* Variable: local-abbrev-table
The value of this buffer-local variable is the (mode-specific)
abbreviation table of the current buffer.
* Variable: fundamental-mode-abbrev-table
This is the fundamental abbrev table of mode-specific abbrevs for
Fundamental mode.
* Variable: text-mode-abbrev-table
This s the local abbrev table used in Text mode.
* Variable: c-mode-abbrev-table
This is the local abbrev table used in C mode.
* Variable: lisp-mode-abbrev-table
This is the local abbrev table used in Lisp mode and Emacs Lisp
mode.
▶1f◀
File: lispref Node: Processes, Prev: Abbreviations, Up: Top, Next: Operating System Interface
Processes
*********
A subprocess of Emacs is represented within Emacs by an object called
a "process". Creating a new (asynchronous) subprocess of Emacs results
in the creation of a process object to represent it for use by Emacs
Lisp.
Emacs provides functions for manipulating processes in most of the
ways you might desire: you may send signals, obtain information from
processes, and so on.
I/O for a process can be handled in several different ways by the
operating system. The standard I/O may be directed though a pipe, or
through a "pseudo terminal" (or ``pty'').
* Menu:
* Functions that Create Subprocesses::
* Creating a Synchronous Process::
* Creating an Asynchronous Process::
* Deleting Processes::
* Process Information::
* Sending Input to Processes::
* Sending Signals to Processes::
* Receiving Information from Processes::
* Subprocess Functions for VMS::
* TCP::
* Function: processp OBJECT
This function returns `t' if OBJECT is a process, `nil' otherwise.
▶1f◀
File: lispref Node: Functions that Create Subprocesses, Prev: Processes, Up: Processes, Next: Creating a Synchronous Process
Functions that Create Subprocesses
==================================
There are three functions that create a new Unix subprocess in which
to run a program. The first, `start-process', creates an asynchronous
process and returns a process object. The other two, `call-process' and
`call-process-region', create a synchronous process and do not return a
process object. Synchronous and asychonous processes are explained in
following sections. (*Note Creating an Asynchronous Process::, and
*Note Creating a Synchronous Process::.) Since the three functions are
all called in a similar fashion, their common arguments are described
here.
In all cases, the program to be run, named by the function's PROGRAM
argument, is found by following the normal rules for Unix: if an
absolute file name is given for the program, then the program must be
found in the specified place. If a relative file name is given, then
the program is searched for in each of the directories in `exec-path',
which is set to the user's `PATH' variable on entering Emacs. The
standard symbols, `~', `.', and `..', are interpreted the same as by
Unix shells. Environment variables (`HOME', etc.) are not substituted
for. See `expand-file-name' in *Note Relative File Names::. It is an
error if the program is not found.
Each of the subprocess creating functions has a BUFFER-OR-NAME
argument. This argument specifies where the standard output from the
program will go. BUFFER-OR-NAME may be either a buffer or the name of
one; the buffer will be created if it does not already exist. If
BUFFER-OR-NAME is `nil', then the output will be discarded by directing
it to `/dev/null' unless a filter function is specified to handle it.
(*Note Process Filters::, and *Note Streams::.) Normally, you do not
want more than one process to send output to the same buffer because the
outputs will be intermixed randomly.
All three of the subprocess creating functions have a `&rest'
argument, ARGS. The ARGS must all be strings, and they are supplied to
PROGRAM as separate command line arguments. *Note* that the argument
PROGRAM is only the name of the program; it may not contain any
arguments for the PROGRAM.
Subprocesses also inherit an environment from Emacs; but you can
specify overrides for it with `process-environment'.
* Variable: process-environment
This global variable is a list of strings to append to the
environment of processes that are started. Each string assigns a
value to a shell environment variable. (This applies both to
asynchronous and synchronous processes.)
process-environment
=> ("l=/usr/stanford/lib/gnuemacs/lisp"
"PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
"USER=lewis"
"TERM=ibmapa16"
"SHELL=/bin/csh"
"HOME=/user/lewis")
* Variable: exec-directory
The value of this variable is the name of a directory (a string)
that contains programs that come with GNU Emacs, which are intended
for Emacs to invoke. The program `loadst' is an example of such a
program; it is used by the `display time' command and prints a
string of the current time one per minute minute. We sometimes
refer to the default value of the `exec-directory' as `emacs/etc'.
* User Option: exec-path
The value of this variable is a list of directories to search for
programs to run in subprocesses. Each element is either the name
of a directory (i.e., a string), or `nil', which stands for the
default directory (which is the value of `default-directory').
` exec-path' is used by `call-process' or `start-process' when
its PROGRAM argument does not contain an absolute file name.
▶1f◀