search-buffer - Search the current buffer for a string
n search-buffer "flags" "string"
search-buffer searches for a string from the current cursor position, in a forwards or backwards direction, to the end or start of the buffer, respectively. The search direction and mode is specified by the by flags argument.
The search-buffer command is designed to be used from the macro language rather than the command line as the search may be defined independently of the buffer setting of magic(2m) mode, which allows regular expression pattern matching, or exact(2m) mode, which makes the search case sensitive. The flags argument is used to explicitly set the magic(2m) and exact(2m) search modes.
The flags argument is defined as a character string which defines the search behavior:
b - backward search
e - enable exact search
E - disable exact search
m - enable magic
M - disable magic
When the flags are not specified then the default behavior is to search in a forwards direction inheriting the exact(2m) and magic(2m) modes of the buffer. Within macros it is suggested that the search modes are explicitly specified unless the buffer modes are to be inherited.
The numeric argument n is interpreted in the same way as a search-forward(2) command:-
n > 0
n < 0
The command returns a status of FALSE if the string could not be located (or nth string where n occurrences are requested). If the string is found within the given search criteria the return status is TRUE.
The following examples show the use of the search-buffer command. The search-buffer is usually used with the !force(4) directive which traps any FALSE return status and may be subsequently tested using the !if(4) directive on the status $status(5) variable. If the !force directive is omitted then the macro will abort with a failure status if the search fails (sometimes this behavior may be required).
Case sensitive search forward for the word "foo", this is not a magic regular expression.
!force search-buffer "eM" "foo" !if $status ; found string !else ; not found !endif
Case sensitive search bacward for the word "foo", this is not a magic regular expression.
search-buffer "beM" "foo"
Regular expression search forward for `<' or `>'.
search-buffer "m" "[<>]"
Regular expression search catching the regular expression. A[a-z]*. The macro variable @s1 returns the regular expression string that has been found.
!force search-buffer "em" "\\(A[a-z]*\\)" !if $status ; found string 1000 ml-write &spr "Found string '%s'" @s1 !else ; not found !endif
Search-buffer was added in November 2004 to simplify macro writing and to speed up macro execution. It replaces the macro commands regex-forward(3) and regex-backward(3). The command simplifies macro development by allowing the exact(2m) and magic(2m) modes to be specified on the command line, this ensures that the buffer mode does not need to be saved, set and then restored in order to modify the behaviour of a search operation.
Copyright (c) 1998-2006 JASSPA
Last Modified: 2005/01/15
Generated On: 2006/10/07