REF VEDSEARCH Jonathan Meyer, Sept 1993
COPYRIGHT University of Sussex 1993. All Rights Reserved.
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< VED SEARCH FACILITIES >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This file describes the Ved regular expression search and substitution
facilities.
CONTENTS - (Use <ENTER> g to access required sections)
1 Introduction
2 Search and Replace in Ved
3 Search Pattern Elements
4 Substitution Pattern Elements
5 Search Commands
6 Search and Substitute Commands
7 Creating New Search Commands
8 Information About the Last Search
9 Procedural Interface
10 Search Variables
10 Definition of "embedded"
---------------
1 Introduction
---------------
This document describes the regular expression search and replace
facilities found in Ved.
If you are an experienced Ved user wanting to learn about the new Ved
search mechanism, read the section 'Notes for experienced Ved users' in
TEACH * VEDSEARCH.
If you are an experienced VI or ED user, you should read the section
'Notes for VI, ED, GREP and AWK users' in TEACH * VEDSEARCH.
NOTE TO XVed USERS: Under XVed you can choose to have Ved automatically
select the matching text for a search. Either do:
<ENTER> xved SearchDoesSelect true
or add the following to your .Xdefaults:
XVed*SearchDoesSelect: true
See REF * XVED/SearchDoesSelect.
----------------------------
2 Search and Replace in Ved
----------------------------
In Ved you can search forward or backwards looking for 'regular
expression' search patterns in files, ranges, procedures, lines, or even
words. You can turn on and off case sensitivity, and specify whether the
search should 'wrap-around' the end of the search region. You can also
substitute matching strings with new strings.
See TEACH * VEDSEARCH for examples showing how to search and substitute
text in Ved.
For full details of how to form search patterns using regular
expressions, see REF * REGEXP For a high level overview of regular
expressions, see TEACH * REGEXP.
--------------------------
3 Search Pattern Elements
--------------------------
Search and substitute commands take strings specifying what to look for.
These strings are 'regular expressions', which are special patterns
containing both normal characters and wildcards. The following table
summarises the wildcards that you can use:
Pattern Meaning
------- -------
@. or @? match any single character
@* match zero or more occurrences of the previous character
@^ or @a constrains a match to the start of the line
@$ or @z constrains a match to the end of the line
@< constrains match to the start of a word boundary
@> constrains match to the end of a word boundary
@{N@} matches N occurrences of previous character, where N is
a positive integer.
@{N,@} matches N or more occurrences of the previous character
@{N,M@} match at least N, at most M occurrences of previous
character, where N and M are positive integers
@[...@] match any character between the brackets, where ... is
any characters e.g. abc or range of characters e.g. A-Z
@[^...@] match any character except those between the brackets
@(...@) denotes a sub-expression for use with @N
@N match a repeat of the N'th sub-expression where N is
a number 1-9
@C match C where C is the search delimiter or `@'
@i turns off case sensitivity for subsequent letters
@c turns on case sensitivity for subsequent letters
Also, to match things like control characters, Ved graphics characters,
or Ved special space characters, you can use all `backslash' sequences
that are recognised in Pop-11 strings. These are described in the
section `Backslash in Strings & Character Constants' in REF * ITEMISE
Note that if you specify character attributes (using \[...] or \{...} ),
these will be ignored in the search string. (However, they are not
ignored in substitute strings, see below).
--------------------------------
4 Substitution Pattern Elements
--------------------------------
Substitution commands take two strings - one is a search pattern (see
the previous section), and another is the substitution text. The
substitution text may itself contain special symbols:
Pattern Meaning
------- -------
@& substitute in the string matched by the search
@n substitute in a line break
@N where N is 1-9, substitute in the N'th sub-expression
@p paste in the contents of the clipboard (XVed only)
See TEACH * VEDSEARCH for examples using these substitution patterns.
As with the search string, the substitute string may also contain any
`backslash' sequence recognised in a Pop-11 string.
Unlike the search string, character attributes specified with \[...] or
\{...} are not ignored, i.e. they are substituted in. So if you use:
\[u]@&
then the matching text will become underlined. By default, character
attributes specified in this way are added to character attributes of
text in the buffer. However, you can specify how existing attributes are
merged together by specifying an attribute mode just after the @. The
mode is is one of:
Mode Description Logical Meaning
---- ----------- ---------------
+ Add attributes EXISTING || NEW (the default)
- Remove attributes EXISTING && ~~ NEW
= Set attributes NEW
~ Toggle attributes EXISTING ||/& NEW
(where EXISTING represents attributes of text in the buffer and NEW is
the attributes of the text in the replacement pattern). e.g.
\[u]@=&
means 'change all matching text to be underlined', and
\[u]@-&
means 'remove all underlining from matching text', and
\[u]@~&
means 'toggle the underlining attribute of matching text'.
------------------
5 Search Commands
------------------
Most of the search and substitute commands do not have a corresponding
procedure as mentioned in the introduction to REF * VEDCOMMS, and these
are marked as "pseudo procedures". i.e. there isn't actually a ved_/
procedure. Instead, ved_search is called to interpret ved_/ commands.
ved_/string/ [ region ] [ +|- option ... ] [pseudo procedure]
ved_\string\ [ region ] [ +|- option ... ] [pseudo procedure]
ved_"string" [ region ] [ +|- option ... ] [pseudo procedure]
ved_`string` [ region ] [ +|- option ... ] [pseudo procedure]
Searches for the regular expression string in the current Ved
buffer. If string is empty, Ved will reuse the last search
string. string may contain search wildcards - see the section
'Search Pattern Elements' above.
Note that there is not in fact a procedure called ved_/ or ved_"
(hence the description 'pseudo procedure' above). In reality,
<ENTER> / and <ENTER> " call ved_search whereas <ENTER> \ and
<ENTER> ` call ved_backsearch (see below).
The delimiter character (the character after the ved_ prefix)
determines the search direction and whether or not the search
will match embedded strings, as follows:
Delimiter Direction Embedded matches
--------- --------- ----------------
/ Forward Yes
" Forward No
\ Backward Yes
` Backward No
Thus, using " as a delimiter rather than / restricts matching
occurrences of string to whole words, e.g.
<ENTER> "define
finds "define" but not "enddefine".
Forward searches start one character after the cursor position,
search to the end of the region, and then from the start of the
region to the cursor position.
Backward searches starts one character before the cursor
position, search to the start of the region, and then from the
end of the region to the cursor position.
See also the "here" option and the "wrap" option below.
If a match is found the cursor is positioned at the start of the
match. Additionally, under XVed, the matching text is selected
if *SearchDoesSelect is true (so hitting backspace deletes the
text, typing a character replaces the text with that character,
and moving the cursor clears the selection).
After the second delimiter, you can optionally specify the
region of the buffer to search and one or more options.
region is one of the following:
file - the whole file (the default)
range - the marked range
procedure - the current procedure
line - the current line
paragraph - the current paragraph
selection - the current selection (XVed only)
sentence - the current sentence
word - the current word
window - the visible text
toendfile - from cursor position to end of file
tostartfile - from cursor position to start of file
Region names can be abbreviated to one or more characters, where
precedence is indicated by the ordering of the regions in the
list above (i.e. the region "p" indicates a procedure, not a
paragraph, "t" indicates "toendfile" not "tostartfile", etc.).
As well as a region, you can specify one or more options
prefixed by either "+" (which turns on the option) or "-" (which
turns it off). eg. +case -wrap indicates that the search should
be case sensitive, but should not wrap around the end of the
region. Options can be abbreviated to one or more letters: -c,
-ca, and -case are all the same option. The "+" and "-"
'persist', so you can do: +case back wrap, which is the same as
+case +back +wrap.
The following options are available:
back
+back forces the search to go backwards. -back forces
the search to go forwards. The default is determined by
the delimiter used.
case
+case (the default) makes the search case sensitive. Use
-case to ignore the case of letters.
embed
+embed makes the search match string even if it is
embedded in another string. -embed constrains the search
to non-embedded items. The default is determined by the
delimiter used.
here
+here (the default) searches from the current cursor
location in the buffer. -here searches from the start of
the region (searching forwards) or the end of the region
(searching backwards).
wrap
+wrap (the default) allows the search to wrap around the
end of the region. -wrap stops the search at the end of
the region.
an integer
an integer n finds the n'th occurrence of string. If n
is negative, the direction of the search is reversed.
NOTE: The search and substitute commands will, for the most part, work
without the closing string delimiter. However a closing delimiter must
be given if the string ends with a space. You can include the delimiter
character as part of the the search or substitute string by preceding it
with "@".
ved_search [procedure variable]
Procedure called by <ENTER> / and <ENTER> " to perform search.
See also ved_re_search.
ved_backsearch [procedure variable]
Procedure called by <ENTER> \ and <ENTER> ` to perform search.
See also ved_re_backsearch.
ved_ss string [procedure variable]
Searches forward for string regardless of the case of the
letters. This is an abbreviation for:
<ENTER>/string/ -case
ved_ww string [procedure variable]
Search for string regardless of case but with word boundaries
(analogous to "). This is an abbreviation for:
<ENTER>"string" -case
---------------------------------
6 Search and Substitute Commands
---------------------------------
ved_s/string_1/string_2/ [ region ] [ +|- option ... ] [procedure]
ved_s"string_1"string_2" [ region ] [ +|- option ... ]
ved_s`string_1`string_2` [ region ] [ +|- option ... ]
Substitutes occurrences of string_1 with string_2. See 'Search
Pattern Elements' and 'Substitution Pattern Elements' above for
descriptions of special symbols that you can use in string_1 and
string_2.
region and option as for REF *VED_/ (see above), with the
following additions:
ask
+ask (the default) asks the user interactively before
performing each substitution. -ask performs the
substitutions throughout the region, replacing as many
matches as possible, without confirmation.
every
+every (the default) replaces all occurrences of a
pattern on a line. -every makes the matcher find only
the first (forward searches) or last (backward searches)
match on each line.
verbose (only for non-interactive substitutions)
+verbose (the default) records progress on the status
line. -verbose doesn't record progress on the status
line, and is therefore slightly faster.
an integer
If an integer is n specified, at most n substitutions
are done. If n is negative, the direction of the search
is reversed.
If the substitution is interactive (i.e. +ask, which is the
default) then, when string_1 is found, Ved prompts for an
action: press Y for a single substitution, or <RETURN> to
substitute and continue; press N to terminate the substitution,
or <DEL> to ignore this occurrence but continue searching for
another. Press G to substitute all other occurrences globally.
ved_s examines the delimiter to determine which direction to
search in (see REF * ved_/ above for details). Thus, using " as
a delimiter rather than / restricts matching occurrences of
string_1 to whole words, e.g.
<ENTER> s"cat"cats"
would leave the word "catch" unchanged.
Note that use of \ as a delimiter for substitution operations
can cause problems because \ is also recognised by the itemiser.
Instead use / as the delimiter and specify the +back option.
Any sign character may be used as a delimiter in place of /,
useful if either STRING contains the character `/`, e.g
<ENTER> s#/usr/users/#/usr2/users#
If you use a sign character as a delimiter, then by default the
search will be forward and will match embedded strings.
If string_1 is empty, the last search string is used instead; if
no argument is given at all (i.e just <ENTER> s) then the last
search and substitute strings are used (but not the options).
NB: this is not the same as
<ENTER> s///
which replaces all occurrences of the last search string with
the empty string.
ved_gs/string_1/string_2/ [procedure variable]
ved_gs"string_1"string_2"
Substitutes all occurrences of string_1 by string_2 throughout
the entire file, without asking for confirmation. This is an
abbreviation for:
<ENTER> s/string_1/string_2/ -ask or
<ENTER> s"string_1"string_2" -ask
See REF * ved_s above for details.
Using " as a delimiter rather than / restricts matching
occurrences of string_1 to whole words, e.g.
<ENTER> gs"cat"cats"
would leave the word "catch" unchanged. This is the same as:
<ENTER> s"cat"cats" -ask
ved_gsr/string_1/string_2/ [procedure variable]
ved_gsr"string_1"string_2"
Global non-interactive substitute in marked range. Like ved_gs.
This is an abbreviation for:
<ENTER> s/string_1/string_2/ range -ask or
<ENTER> s"string_1"string_2" range -ask
See REF * ved_s above for details.
ved_gsp/string_1/string_2/ [procedure variable]
ved_gsp"string_1"string_2"
Global non-interactive substitute in current procedure. (Works
only if * ved_mcp has been defined for the language in
question). This is an abbreviation for:
<ENTER> s/string_1/string_2/ procedure -ask or
<ENTER> s"string_1"string_2" procedure -ask
See REF * ved_s above for details.
ved_gsl/string_1/string2/ [procedure variable]
ved_gsl"string_1"string2"
Global non-interactive substitute in current line - like ved_gs
in current line. This is an abbreviation for:
<ENTER> s/string_1/STRING_2/ line -ask or
<ENTER> s"string_1"STRING_2" line -ask
See REF * ved_s above for details.
ved_sgs/string_1/string_2/ [procedure variable]
ved_sgs"string_1"string_2"
Like ved_gs but "silent", i.e. doesn't record progress on status
line, and therefore faster. This is the same as:
<ENTER> s/string_1/string_2/ -ask -verbose or
<ENTER> s"string_1"string_2" -ask -verbose
See REF * ved_s above for details.
ved_sgsr [procedure variable]
Like ved_gsr but "silent", i.e. doesn't record progress on
status line, and therefore faster. This is the same as:
<ENTER> s/STRING_1/STRING_2/ range -ask -verbose or
<ENTER> s"STRING_1"STRING_2" range -ask -verbose
See REF * ved_s above for details.
-------------------------------
7 Creating New Search Commands
-------------------------------
All of the above search commands and procedures are in fact implemented
as closures of a single procedure, ved_search_or_substitute . You can
add your own customised search commands by creating closures of this
procedure:
ved_search_or_substitute(default_options, mode) [procedure]
Implements the command line interface to the Ved search and
substitute facilities.
default_options is either a string or a boolean.
If default_options is a string, then the string will be used as
the region and options for the search command, and any region or
options specified by the user will be ignored. See REF * ved_/
above for a description of regions and options.
If default_options is a boolean, then any region and options
supplied on the command line by the user are used. In addition,
false makes the search go forwards by default, whereas true
makes the search go backwards by default.
Note that if the search direction and embed mode are not
specified explicitly in the default_options string they are
determined from the delimiter specified by the user:
Delimiter Direction Embedded matches
--------- --------- ----------------
/ Forward Yes
" Forward No
\ Backward Yes
` Backward No
mode is either false, true or undef. Use false for search
commands, true for search-and-substitute commands, and undef for
search commands that don't have delimiters (eg. ved_ww or
ved_ss).
------------------------------------
8 Information About the Last Search
------------------------------------
The following variable is used by all the <ENTER> commands that use
ved_search_or_substitute to perform search or substitution:
ved_search_state -> (item_1, ..., item_n) [active variable]
(item_1, ..., item_n) -> ved_search_state
Contains information about the last search or substitution
command performed by Ved. This active variable is set and used
by the procedure ved_search_or_substitute to redo a search when
the user specifies a blank search string. The specific
datastructure that is placed in ved_search_state is unspecified.
Use ved_set_search and ved_query_last_search to query or modify
the search parameters.
If you wish to call ved_search_or_substitute or to perform an
<ENTER> search command without modifying the information about
the last search, use:
dlocal ved_search_state;
to save and restore the state information about the previous
search.
The procedures ved_query_last_search and ved_set_search extract and
modify information held in ved_search_state:
ved_query_last_search() -> (search_string, start_line, [procedure]
start_column, end_line, end_column)
Returns information held in ved_search_state about the last
search done by an <ENTER> command that uses
ved_search_or_substitute.
search_string is the string that was searched for. If no search
has yet been performed, search_string is false.
start_line, start_column, end_line and end_column specify where
in the buffer the match occurred. If no match was found,
first_line, first_column, last_line and last_column will be
false. If the search succeeded, first_line, first_column,
last_line, last_column will be set such that
vedjumpto(first_line, first_column)
places the cursor on the start of the match and
vedjumpto(last_line, last_column + 1)
places the cursor one character after the end of the match.
Note that last_column will be one less than first_column if the
pattern matches zero characters eg. for patterns such as '@$'.
Thus the result:
4, 18, 4, 17
indicates that a zero-length match occurs at the eighteenth
column of line four.
Similarly, last_column will be zero if all of the characters
including the line break on previous line to last_line are part
of the match (i.e. if the pattern ends in @z@a). Thus the
result:
12, 1, 13, 0
indicates that the whole of line 12 including the line break at
the end of line 12 are part of the match.
ved_set_search(string, substitute_string, options) [procedure]
Set the search pattern used in redo operations by the standard
search and substitute commands. Used by e.g. ved_f to tell the
search commands what the last thing that the user looked for
was.
This procedure constructs a new structure representing a search
for item and assigns it to ved_search_state .
string is the regular expression pattern to look for.
options is a list of words specifying additional parameters of
the search. The following words can occur in the options list:
nowrap
the search stops at the end of the search region.
nocase
the search is case insensitive.
noembed
the search is constrained to match non-embedded items.
In addition, the options list may contain a search constraint
region, which is one of the following words:
file - the whole file (the default)
range - the marked range
procedure - the current procedure
line - the current line
paragraph - the current paragraph
selection - the current selection (XVed only)
sentence - the current sentence
word - the current word
window - the visible text
toendfile - from cursor position to end of file
tostartfile - from cursor position to start of file
If options is empty, the redo will perform a case-sensitive
forwards search in the whole file, wrapping over the end of the
file, and the search will match both embedded and non-embedded
occurrences of the string.
If substitute_item is not false, it is used as the substitution
pattern when the user types a substitution command with no
arguments. Otherwise the current substitution string is
retained.
ved_re_backsearch() [procedure variable]
Redo previous search, looking backwards. Assigned by default to
the <ESC> \ key sequence.
ved_re_search() [procedure variable]
Redo the previous search, looking forwards. Assigned by default
to the <ESC> / key sequence.
-----------------------
9 Procedural Interface
-----------------------
The following two utility procedures offer an easy-to-use interface to
the Ved search mechanism. They both set the variable ved_search_state to
reflect the last search that was performed:
ved_try_search(string, options) -> bool [procedure]
ved_check_search(string, options) [procedure]
Searches for string in the current Ved buffer, starting from the
current cursor position. If the string is found then the cursor
is placed over the start of the matching text.
ved_try_search returns true if the search succeeds and false if
the search fails. On the other hand, ved_check_search simply
returns if the search succeeds, but calls vederror if the search
fails.
By default, a case-sensitive forwards search in the whole file
is performed, wrapping over the end of the file, and the search
will match both embedded and non-embedded occurrences of the
string.
The options argument is a list of words that alters the
parameters of the search described above. The following words
can occur in the options list:
back
a backwards search is performed.
nowrap
the search stops at the end of the search region.
nocase
the search is case insensitive.
noembed
the search is constrained to match non-embedded items.
In addition, the options list may contain a search constraint
region, which is one of the following words:
file - the whole file (the default)
range - the marked range
procedure - the current procedure
line - the current line
paragraph - the current paragraph
selection - the current selection (XVed only)
sentence - the current sentence
word - the current word
window - the visible text
toendfile - from cursor position to end of file
tostartfile - from cursor position to start of file
You can use ved_query_last_search to retrieve the full buffer
coordinates for the match.
These two procedures both set ved_search_state so that if the
user hits the RE_SEARCH key another search for string is
performed. You can do:
dlocal ved_search_state;
inside a procedure before calling these procedures to preserve
the search state.
--------------------
10 Search Variables
--------------------
The following variables are used by the search and substitute mechanism:
vedwrapped -> int [variable]
int -> vedwrapped
A system variable used by Ved searching routines to count how
many times the search process has wrapped around the Ved buffer.
vedsafesubstitute -> bool [variable]
bool -> vedsafesubstitute
If this is true (its default value), then ved_copy is called by
the Ved substitution commands before a global (non interactive)
substitution is performed. This saves the lines of a Ved buffer
within the region that may may be changed by the substitution.
You can then do <ENTER> yank to recover the unchanged lines
after the substitution.
vvedfoundstring -> string [variable]
string -> vvedfoundstring
The text (in a string) that was last replaced by the most recent
substitute commands. This remains largely for
backwards-compatibility.
----------------------------
10 Definition of "embedded"
----------------------------
What counts as a non-embedded string is by default approximately the
same as what the Pop-11 itemiser would separate out from the surrounding
text. This is defined by the procedures vedatitemstart and vedatitemend,
which are in turn defined in terms of vedchartype . This default
specification would not suit all programming languages or all
text-editing contexts, so by redefining vedchartype it is possible to
alter what Ved regards as a text item boundary. For further details see
REF * VEDPROCS/vedatitemend, * VEDPROCS/vedchartype.
--- C.all/ref/vedsearch
--- Copyright University of Sussex 1995. All rights reserved.