| Search and Translate Primitives | |
| Macros | |
| quote_regexp | Quote regexp special characters. |
| re_comp | Compile a regular expression. |
| re_delete | Delete a compiled expression. |
| re_result | Retrieve search captures. |
| re_search | Search for a string. |
| re_syntax | Set the regular expression mode. |
| re_translate | Search and replace. |
| search_back | Backwards buffer search. |
| search_case | Set the search pattern case mode. |
| search_fwd | Buffer search. |
| translate | Buffer search and replace. |
string quote_regexp( string text )
Quote regexp special characters.
The quote_regexp() primitive quotes (i.e. prefixes with a backslash) the following set of predefined characters in the specified string text, representing most of the regular expression special characters.
The predefined characters are;
| text | String containing the text to quote, protecting special regular expression characters.. |
The quote_regexp() primitive returns the resulting quoted string.
n/a
list re_comp( [int flags], string pattern, [string &error] )
Compile a regular expression.
The re_comp() primitive is reserved for future development.
The re_comp primitive converts a regular expression string (RE) into an internal form suitable for pattern matching.
| flags | Optional integer flags, one or more of the SF_XXX flags OR’ed together control the options to be applied during the search and replace. |
| pattern | String containing the pattern to translate. |
| error | Optional string reference, on an error shall be populated with a description of the error. |
| parms | Optional string containing configuration parameters. |
The re_comp() primitive returns list containing the compiled expression, otherwise a null list.
DONOT modify the result otherwise you shall encounter undefined results during search operations.
n/a
int re_result( [int capture], [string &value], [int &offset], [int &length] )
Retrieve search captures.
The re_result() primitive retrieves the results of the last regular expression re_search operation. In addition the prior search must have had SF_CAPTURES enabled.
The captured regions reference the original searched object, as such the original buffer, list or string *must not be modified prior to executing re_result.
| capture | Integer capture index, see details below. |
| value | String variable reference, is populated with the value of the referenced capture. |
| offset | Optional integer variable reference, is populated with the starting offset of the capture within the original source. |
| Value |
Description |
|---|---|
| 1 .. 9 |
Xth captured expression. |
| CAPTURE_BEFORE |
Everything prior to matched string |
| CAPTURE_ARENA |
Entire matched string. |
| CAPTURE_AFTER |
Everything after to matched string |
| CAPTURE_LAST |
Last parenthesized pattern match. |
The re_result() primitive returns the length of the capture, otherwise -1 on error.
A GriefEdit extension.
re_search, search_fwd, search_back, search_string, search_list
int re_search( [int flags], [string pattern], [declare object], [int start], [int lensym] )
Search for a string.
The re_search() primitive is a generalised search interface, combining the functionality of the more specialised search primitives but presenting consistent and stateless search capabilities.
In addition both the re and case modes are explicit based upon the flags values.
| flags | Optional integer flags, one or more of the SF_XXX flags OR’ed together control the options to be applied during the search. |
| pattern | A string containing the pattern to be matched. |
| object | Optional object to be searched. The search depends on the type of object. If object is a string, then a string search is performed. If object is a list then a list search is done. Ifn an integer the buffer associated with the stated buffer number is searched, otherwise if omitted a search on the current buffer is performed. |
| start | Optional integer index for list objects, states the element offset at which search operation shall start. If omitted, the search is started from the beginning of the list. |
| lensym | Optional integer reference for string objects is populated with the length of the matched region. |
General control flags.
| Constant |
Description |
|---|---|
| SF_BACKWARDS |
Search in backwards direction. By default searchs are performed in a forward direction; only meaningful for buffer searches or translates. |
| SF_IGNORE_CASE |
Ignore/fold case. |
| SF_BLOCK |
Restrict search to current block. |
| SF_LINE |
Line mode. |
| SF_LENGTH |
Return length of match. |
| SF_MAXIMAL |
BRIEF maximal search mode. |
| SF_CAPTURES |
Capture elements are retained. |
| SF_QUIET |
Do not display progress messages. |
| SF_GLOBAL |
Global translate (*); re_translate only. |
| SF_PROMPT |
Prompt for translate changes; re_translate only. |
| SF_AWK |
awk(1) style capture references. |
| SF_PERLVARS |
perl(1) style capture references. |
(*) PROMPT is given priority over GLOBAL.
Syntax selection, one of the following mutually exclusive options can be stated.
| Constant |
Description |
|---|---|
| SF_NOT_REGEXP |
Treat as plain test, not as a regular expression. |
| SF_BRIEF/SF_CRISP |
BRIEF/CRiSP/GRIEF expressions (default). |
| SF_UNIX |
Unix regular expressions. |
| SF_EXTENDED |
Extended Unix expressions. |
| SF_PERL |
PERL syntax. |
| SF_RUBY |
Ruby syntax. |
The re_search() primitive return is dependent on the type of the object searched; matching the corresponding specialised primitive search_fwd, search_list and search_string. These are summarised below.
| Object Type |
return |
|---|---|
| buffer |
on success the length of the matched text; otherwise 0 if no match or -1 on error. |
| list |
on success index of the matched element, otherwise -1 if on match. |
| string |
on success the index of first character of match, otherwise 0 if no match. |
On error re_search returns -1.
n/a
re_translate, search_fwd, search_back, search_string, search_list, re_syntax
int re_syntax( [int re], [int case], [int capture] )
Set the regular expression mode.
The re_syntax() primitive configures the global regular expression syntax mode to the mode re. By default, the mode is set to the RE_BRIEF regular expression syntax.
re_syntax affects the defaults of the following primitives;
The supported regular expression syntax modes.
| Value |
Constant |
Description |
|---|---|---|
| 0 |
RE_BRIEF |
BRIEF/Crisp Edit mode. |
| 1 |
RE_UNIX |
Basic Unix syntax. |
| 2 |
RE_EXTENDED |
POSIX Extended Unix. |
| 3 |
RE_PERL |
Perl. |
| 4 |
RE_RUBY |
Ruby style syntax. |
| re | Optional integer value, specifying the new regular expression syntax to by applied. If omitted, the current value is unchanged. |
| case | Optional integer value, specifying the new state of the global case mode. If case is specified and is zero, then searches are performed as case insensitive, otherwise when non-zero they shall be case sensitive. If omitted, the current value is unchanged. |
| capture | Optional integer value, specifying the new state of the global replacement pattern reference mode. If RE_PERLVARS then Perl style capture references shall be utilised, when RE_AWKVARS AWK style capture references are utilised, otherwise then 0 the style is dependent on the re mode; see translate. If omitted, the current value is unchanged. |
The re_syntax() primitive returns the current/resulting regular expression syntax mode.
The case and re arguments are GriefEdit extensions.
int|string re_translate( [int flags], string pattern, [string replacement], [declare object] )
Search and replace.
The re_translate() primitive is a generalised search and replace interface, combining the functionality of the more specialised primitives but presenting consistent and stateless search capabilities.
| flags | Optional integer flags, one or more of the SF_XXX flags OR’ed together control the options to be applied during the search and replace. |
| pattern | String containing the pattern to translate. |
| replacement | String containing the replacement expression for each matched pattern. It may contain references to the pattern’s capture groups by special variables using one of three forms GRIEF, AWK or Perl, see below. |
| object | Optional object to be searched. The search depends on the type of object. If object is a string, then a string search is performed; translating a string provides similar functionality to awk’s sub() and gsub() functions. If object is a list then a list search is done. If an integer the buffer associated with the stated buffer number is searched, otherwise if omitted a search on the current buffer is performed. |
This style take the form of of the form “\d”, where d is a numeric group number started at an index of 0; note escapes need to be preceded by an additional backslash.
This style take the form of “\d”, where d is a numeric group number indexed from 1; note escapes need to be preceded by an additional backslash.
This style is super-set of all three forms. Capture references take the form “$x” when x is a numeric group number indexed from 1 or one of the special variables $`, $&, and $’. In addition the AWK “\x” syntax is supported, yet their use should be avoided due to the need to quote the escapes.
| Variable |
Value |
|---|---|
| \1, \2 ... |
Old style, Xth captured expression. |
| $1, $2 ... |
Xth captured expression. |
| ${xx} |
Xth captured expression. |
| $+ |
Last parenthesized pattern match. |
| $` |
Everything prior to the matched string. |
| $& |
Entire matched string. |
| $’ |
Everything after the matched string. |
If object is a string, then the resulting translated string is returned.
Otherwise the re_translate() primitive returns the number of translations which occurred, otherwise -1 on error.
n/a
int search_back( string pattern, [int re], [int case], [int block], [int length] )
Backwards buffer search.
The search_back() primitive searches backwards within the active buffer from the current cursor position to the buffer top (or block) against the expression pattern. The treatment of the matched pattern may either be a regular-expression or constant string dependent on re and case folding based on case.
The search_back primitive is provided primary for BRIEF compatibility. Since re and case can reference the current global search states, inconsistent and/or unexpected results may result between usage; as such it is advised that the state-less re_search primitive is used by new macros.
| pattern | A string containing the pattern to be matched. |
| re | Optional integer value. If re is specified and is zero, then pattern is treated as a literal string not as a regular expression; behaviour being the same as index. Otherwise the string shall be treated as a regular expression using the current global syntax, see re_syntax and search_back for additional information. |
| case | Optional integer value specifying whether case folding should occur. If case is specified and is zero, then the search is done with case insensitive. If omitted the current global setting is referenced. |
| block | Optional integer flag. If block is specified and is non-zero, the search operations are limited to the current marked region. |
| length | Optional inter flag. If length is specified and is non-zero, indicates that the total length of the text should be returned; regardless of any \\c anchors in the pattern. |
The search_back() primitive returns the length of the matched text plus one otherwise zero or less if no match was found.
Alternatively, if length is specified the total length of the matched text is returned. Otherwise if a \\c anchor was encountered within the pattern, it returns the length of the text from the position of the marker to the end of the matched text plus one.
n/a
int search_case( [int case] )
Set the search pattern case mode.
The search_case() primitive sets or toggles the global search case mode, if omitted the current mode is toggled.
On completion the resulting mode is echo on the command prompt, either as
Case sensitivity on
or
Case sensitivity off
By default all searches are case sensitive, that is A and a are not equivalent, by setting the case mode to a zero value, case sensitivity will be ignored when performing matches.
search_case affects the default case sensitivity of the follow primitives.
| case | Optional integer value, specifying the new state of the case mode. If case is omitted, the current value is toggled. |
The search_case() primitive returns the previous value of the case mode.
n/a
int search_fwd( string pattern, [int re], [int case], [int block], [int length] )
Buffer search.
The search_fwd() primitive searches forward within the active buffer from the current cursor position to the buffer end (or block) against the expression pattern. The treatment of the matched pattern may either be a regular-expression or constant string dependent on re and case folding based on case.
The search_fwd primitive is provided primary for BRIEF compatibility. Since re and case can reference the current global search states, inconsistent and/or unexpected results may result between usage; as such it is advised that the state-less re_search primitive is used by new macros.
| pattern | A string containing the pattern to be matched. |
| re | Optional integer value. If re is specified and is zero, then pattern is treated as a literal string not as a regular expression; behaviour being the same as index. Otherwise the string shall be treated as a regular expression using the current global syntax, see re_syntax and search_back for additional information. |
| case | Optional integer value specifying whether case folding should occur. If case is specified and is zero, then the search is done with case insensitive. If omitted the current global setting is referenced. |
| block | Optional integer flag. If block is specified and is non-zero, the search operations are limited to the current marked region. |
| length | Optional inter flag. If length is specified and is non-zero, indicates that the total length of the text should be returned; regardless of any \\c anchors in the pattern. |
The search_fwd() primitive returns the length of the matched text plus one otherwise zero or less if no match was found.
Alternatively, if length is specified the total length of the matched text is returned. Otherwise if a \\c anchor was encountered within the pattern, it returns the length of the text from the position of the marker to the end of the matched text plus one.
n/a
int translate( string pattern, string replacement, [int global], [int re], [int case], [int block], [int forward] )
Buffer search and replace.
The translate() primitive perform string translations within the current buffer. The translate starting at the current cursor position, continuing until the end of the buffer or optionally terminated by the end user.
If either the pattern or replacement is not specified, then the user is prompted for the change.
Unless global is specified, during translate operations the user to informed on the first match and prompted for the desired action.
Change [Yes|No|Global|One|Entire|Abort,Top|Center]?
the actions being
| Yes | Replace current match with the pattern and continue searching. |
| No | Do not replace current match with the pattern and continue searching. |
| Global | Replace all matches from cursor to end of file. |
| Entire | Replace all matches in the file. |
| Abort | Stop the translation. |
| Top | Moves cursor and the associated text for better visibility to top of page and re-prompts. |
| Center | Centers the cursor and the associated text for better visibility and re-prompts. |
The translate primitive is provided primary for BRIEF compatibility. As the values of re and case can reference the current global state resulting in possible inconsistent results between usage, it is advised that the state-less re_translate primitive is used by new macros.
| pattern | String containing the pattern to translate. |
| replacement | String containing the replacement expression for each matched pattern. It may contain references to the pattern’s capture groups by special variables using one of three forms GRIEF, AWK or Perl, see below. |
| global | Optional integer flag controls user prompts. If specified as non-zero every occurence of the pattern is replaced, otherwise only the first occurance is translated. If global is omitted the user is prompted on each match. |
| re | Optional integer value. If re is specified and is zero, then pattern is treated as a literal string not as a regular expression; behaviour being the same as index. Otherwise the string shall be treated as a regular expression using the current global syntax, see re_syntax and search_back for additional information. |
| case | Optional integer value specifying whether case folding should occur. If case is specified and is zero, then the search is done with case insensitive. If omitted the current global setting is referenced. |
| block | Optional integer flag. If block is specified and is non-zero, the search operations are limited to the current marked region. |
| forward | Optional integer flag specifying the search direction. If forward is specified as non-zero or omitted, the translation operation moves forward. Otherwise the translation moves backwards until the top of buffer. |
The translate() primitive returns the number of translations which occurred, otherwise -1 on error.
n/a
search_fwd, search_back, re_search
$Id: $
To send feedback on this topic email: griefedit@gmail.com
Copyright © Adam Young All Rights Reserved.
Quote regexp special characters.
string quote_regexp( string text )
Compile a regular expression.
list re_comp( [int flags], string pattern, [string &error] )
Delete a compiled expression.
int re_delete( list handle )
Retrieve search captures.
int re_result( [int capture], [string &value], [int &offset], [int &length] )
Search for a string.
int re_search( [int flags], [string pattern], [declare object], [int start], [int lensym] )
Set the regular expression mode.
int re_syntax( [int re], [int case], [int capture] )
Search and replace.
int|string re_translate( [int flags], string pattern, [string replacement], [declare object] )
Backwards buffer search.
int search_back( string pattern, [int re], [int case], [int block], [int length] )
Set the search pattern case mode.
int search_case( [int case] )
Buffer search.
int search_fwd( string pattern, [int re], [int case], [int block], [int length] )
Buffer search and replace.
int translate( string pattern, string replacement, [int global], [int re], [int case], [int block], [int forward] )
Searches for a pattern in a string.
int search_string( string pattern, string text, [int &length], [int re], [int case] )
Search list contents.
int search_list( [int start], string pattern, list expr, [int re], [int case] )
Search string for a leftmost sub-string or character.
int index( string str, int ch|string s )