Mercurial > hg > xemacs-beta

comparison man/lispref/searching.texi @ 4199:3660d327399f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2007-10-01 08:07:39 by stephent] Implement subexpression replacement in replace-match. <87ejgf6yy9.fsf@uwakimon.sk.tsukuba.ac.jp>
author stephent
date Mon, 01 Oct 2007 08:07:57 +0000
parents f45ce138f2ad
children 6772ce4d982b
comparison
equal deleted inserted replaced
4198:fb83e69ce80a 4199:3660d327399f
1280 This function replaces the text in the buffer (or in @var{string}) that 1280 This function replaces the text in the buffer (or in @var{string}) that
1281 was matched by the last search. It replaces that text with 1281 was matched by the last search. It replaces that text with
1282 @var{replacement}. 1282 @var{replacement}.
1283 1283
1284 If you did the last search in a buffer, you should specify @code{nil} 1284 If you did the last search in a buffer, you should specify @code{nil}
1285 for @var{string}. Then @code{replace-match} does the replacement by 1285 for @var{string}. (An error will be signaled if you don't.) Then
1286 editing the buffer; it leaves point at the end of the replacement text, 1286 @code{replace-match} does the replacement by editing the buffer; it
1287 and returns @code{t}. 1287 leaves point at the end of the replacement text, and returns @code{t}.
1288 1288
1289 If you did the search in a string, pass the same string as @var{string}. 1289 If you did the search in a string, pass the same string as @var{string}.
1290 Then @code{replace-match} does the replacement by constructing and 1290 (An error will be signaled if you specify nil.) Then
1291 returning a new string. 1291 @code{replace-match} does the replacement by constructing and returning
1292 1292 a new string.
1293 If the fourth argument @var{string} is a string, fifth argument
1294 @var{strbuffer} specifies the buffer to be used for syntax-table and
1295 case-table lookup and defaults to the current buffer. When @var{string}
1296 is not a string, the buffer that the match occurred in has automatically
1297 been remembered and you do not need to specify it.
1298 1293
1299 If @var{fixedcase} is non-@code{nil}, then the case of the replacement 1294 If @var{fixedcase} is non-@code{nil}, then the case of the replacement
1300 text is not changed; otherwise, the replacement text is converted to a 1295 text is not changed; otherwise, the replacement text is converted to a
1301 different case depending upon the capitalization of the text to be 1296 different case depending upon the capitalization of the text to be
1302 replaced. If the original text is all upper case, the replacement text 1297 replaced. If the original text is all upper case, the replacement text
1315 specially. If a @samp{\} appears in @var{replacement}, then it must be 1310 specially. If a @samp{\} appears in @var{replacement}, then it must be
1316 part of one of the following sequences: 1311 part of one of the following sequences:
1317 1312
1318 @table @asis 1313 @table @asis
1319 @item @samp{\&} 1314 @item @samp{\&}
1320 @cindex @samp{&} in replacement 1315 @cindex @samp{\&} in replacement
1321 @samp{\&} stands for the entire text being replaced. 1316 @samp{\&} stands for the entire text being replaced.
1322 1317
1323 @item @samp{\@var{n}} 1318 @item @samp{\@var{n}}
1324 @cindex @samp{\@var{n}} in replacement 1319 @cindex @samp{\@var{n}} in replacement
1320 @cindex @samp{\@var{digit}} in replacement
1325 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that 1321 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1326 matched the @var{n}th subexpression in the original regexp. 1322 matched the @var{n}th subexpression in the original regexp.
1327 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}. 1323 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1328 1324
1329 @item @samp{\\} 1325 @item @samp{\\}
1330 @cindex @samp{\} in replacement 1326 @cindex @samp{\\} in replacement
1331 @samp{\\} stands for a single @samp{\} in the replacement text. 1327 @samp{\\} stands for a single @samp{\} in the replacement text.
1328
1329 @item @samp{\u}
1330 @cindex @samp{\u} in replacement
1331 @samp{\u} means upcase the next character.
1332
1333 @item @samp{\l}
1334 @cindex @samp{\l} in replacement
1335 @samp{\l} means downcase the next character.
1336
1337 @item @samp{\U}
1338 @cindex @samp{\U} in replacement
1339 @samp{\U} means begin upcasing all following characters.
1340
1341 @item @samp{\L}
1342 @cindex @samp{\L} in replacement
1343 @samp{\L} means begin downcasing all following characters.
1344
1345 @item @samp{\E}
1346 @cindex @samp{\E} in replacement
1347 @samp{\E} means terminate the effect of any @samp{\U} or @samp{\L}.
1332 @end table 1348 @end table
1349
1350 Case changes made with @samp{\u}, @samp{\l}, @samp{\U}, and @samp{\L}
1351 override all other case changes that may be made in the replaced text.
1352
1353 The fifth argument @var{strbuffer} may be a buffer to be used for
1354 syntax-table and case-table lookup. If @var{strbuffer} is not a buffer,
1355 the current buffer is used. When @var{string} is not a string, the
1356 buffer that the match occurred in has automatically been remembered and
1357 you do not need to specify it. @var{string} may also be an integer,
1358 specifying the index of the subexpression to match. When @var{string}
1359 is not an integer, the ``subexpression'' is 0, @emph{i.e.}, the whole
1360 match. An @code{invalid-argument} error will be signaled if you specify
1361 a buffer when @var{string} is nil, or specify a subexpression which was
1362 not matched.
1363
1364 It is not possible to specify both a buffer and a subexpression, but the
1365 idiom
1366 @example
1367 (with-current-buffer @var{buffer} (replace-match ... @var{integer}))
1368 @end example
1369 may be used.
1370
1333 @end defun 1371 @end defun
1372
1334 1373
1335 @node Entire Match Data 1374 @node Entire Match Data
1336 @subsection Accessing the Entire Match Data 1375 @subsection Accessing the Entire Match Data
1337 1376
1338 The functions @code{match-data} and @code{set-match-data} read or 1377 The functions @code{match-data} and @code{set-match-data} read or