Searching Subroutines

int do_searching(int flags, char *str)  /* search.e */

int do_color_searching(int flags, char *str)  /* search.e */

The do_searching( ) subroutine defined in search.e is handy when you want to use a variable to determine the type of search. A flags value of 0 means perform a plain forward search. The flags REVERSE, REGEX, and WORD specify a reverse search, a regular expression search, or a word search, respectively. The subroutine normally performs case-folding if the buffer's case_fold variable is non-zero; pass MODFOLD to force Epsilon to search without case-folding, or pass MODFOLD and FOLD to force Epsilon to case-fold. The above flags may be combined in any combination.

The do_searching( ) subroutine returns 1 on a successful search, or 0 if the search text was not found. It can also return DSABORT if the user aborted the search (see the abort_searching variable) or DSBAD if the (regular expression) search pattern was invalid. If the search was successful, Epsilon moves to just after the found text (or just before, for reverse searches); in all other cases point doesn't change.

The do_color_searching( ) subroutine defined in search.e takes parameters and returns values just like do_searching( ), but it handles regular expressions that use assertions like <c:perl-comment> to match based on the colors applied via syntax highlighting. If you use such syntax in a primitive like re_search( ), Epsilon will search based on the syntax highlighting currently applied to the buffer. Because Epsilon computes syntax highlighting only as needed during screen display, as well as in the background, the buffer's syntax highlighting may not be up to date. This subroutine ensures that the buffer's syntax highlighting is up to date as it finds matches, by reparsing and recoloring the buffer whenever it has to.

int word_search(int dir, char *str) int narrowed_search(int flags, char *str, int limit)
If do_searching( ) needs to search in word mode, it calls the word_search( ) subroutine. This function searches for str, rejecting matches unless they are preceded and followed by non-word characters. More precisely, it converts the text into a regular expression pattern, constructed so that each space in the original pattern matches any sequence of whitespace characters, and each word in the pattern only matches whole words.

The narrowed_search( ) subroutine is like do_searching( ), but takes a parameter limit to limit the search. Epsilon will only search a region of the buffer within limit characters of its starting point. For example, if point is at 30000 and you call narrowed_search( ) and specify a reverse search with a limit of 1000, the match must occur between positions 29000 and 30000. If no such match is found, point will be set to 29000 and the function will return 0.

string_replace(char *str, char *with, int flags) show_replace(char *str, char *with, int flags)
The string_replace( ) subroutine allows you to do string replacements from within a function. It accepts flags from the same list as do_searching( ). Provide the INCR flag if you want the subroutine to display the number of matches it found, and the number that were replaced. Provide the QUERY flag to ask the user to confirm each replacement. This subroutine sets the variables replace-num-found and replace-num-changed to indicate the total number of replacements it found, and the number the user elected to change.

If you want to display what will be replaced without replacing anything, call the show_replace( ) subroutine. It takes the same parameters as string_replace( ), and displays a message in the echo area. All Epsilon's replacing commands call this subroutine to display their messages.

int simple_re_replace(int flags, char *str, char *repl)
The simple_re_replace( ) subroutine performs a regular expression replacement on the current buffer. It searches through the buffer, starting from the top (the bottom, for reverse searches), and passing flags and str directly to the re_search( ) primitive. It deletes each match and inserts the string repl instead, returning the number of replacements it did. The replacement text is inserted literally, with no interpolation. If you want to use #1 in your replacement text or other more involved things, call string_replace( ) instead. The subroutine preserves point using a spot; if the text containing point is replaced, point will go after the replacement.

int search_read(char *str, char *prmpt, int flags) int default_fold(int flags) int get_search_string(char *pr, int flags) char *default_search_string(int flags) char **default_replace_string(int flags)
To ask the user for a search string, use the search_read( ) subroutine. Its parameter str provides an initial search string, and it returns a set of flags which you can pass to do_searching( ). It takes an initial set of flags, which you can use to start the user in one of the searching modes. Call default_fold( ) with any flags before calling search_read( ). It will turn on any needed flags relating to case-folding, based on the value of the case_fold variable, and return a modified set of flags.

The function leaves the string in either the _default_search or the _default_regex_search variable, depending upon the searching flags it returns. You can call the default_search_string( ) subroutine with that set of searching flags and it will return a pointer to the appropriate one of these. Depending on what the user types, the search_read( ) subroutine may perform searching itself, in addition to returning the search string.

The similar default_replace_string( ) subroutine returns a pointer to the address of the current replacement string. Dereference it to access the replacement string.

The get_search_string( ) subroutine asks the user for a string to search for by calling search_read( ).

buffer int (*search_continuation)(); int sample_search_continuation(int code, int flags, char *str)
In some modes a buffer may contain a single "record" out of many. Records may be swapped by changing the narrowing on the buffer (as in Info mode), while in other modes the contents of the buffer may be completely replaced with text from a different record.

A mode may wish to let users search from one record to the next, when no more matches can be found in the current record. (This capability relates to searching by the user, with the search_read( ) subroutine, not the primitive searching functions.)

A mode may set the buffer-specific search_continuation function pointer to a search-continuation function if it wants this behavior. If it's nonzero, the searching functions will call this function to advance to a different record, or to remember or return to a particular record.

Epsilon assumes that the set of possible records have an implicit order to them, forming a list. And it assumes that a record id, referring to a specific record, may be stored in a character array of length FNAMELEN.

The code parameter indicates the desired operation. If SCON_RECORD, the search-continuation function must write a record id for the current record into the array str. If SCON_RESTORE, it must return to the record identified by the previously-saved id str. These operations should return zero. If SCON_COMPARE, it must compare the current record with the id saved in str (according to the record order), returning -1, 0, or 1 depending on whether the current record is before, equal to, or after the saved record, respectively.

Any other code means to move to the next or previous record, according to whether the flags parameter contains the REVERSE bit, and position to its start (or, for reverse searching, end). In this case, code becomes a count, starting from 1, that indicates the number of record positionings done since the last user keypress (for use in displaying progress messages). It should return 1 on success, or 0 if there were no more records (and should remain at the original record in that case).

A search-continuation function may wish to pre-screen records, and skip over those that do not contain the search string (but is not required to do so). If it chooses to do this, it can use flags and str to call the do_searching( ) subroutine; these specify the search being performed.

int col_search(char *str, int col) /* search.e */ int column_color_searching(int flags, char *pat, int startcol, int endcol)
The col_search( ) subroutine defined in search.e attempts to go to the beginning of the next line containing a certain string starting in a certain column. It returns 1 if the search is successful, 0 otherwise.

The column_color_searching( ) subroutine defined in search.e ignores matches unless they start and end in the specified columns. Either startcol or endcol may be -1, and that column restriction won't apply. It takes flags and pat parameters like do_color_searching( ), so it can search for regular expressions, including those that use syntax highlighting colors, restrict matches to whole words, search in reverse, and so forth. See do_searching( ) at the start of this section for details on its flag parameter.

int line_search(int dir, char *s) /* grep.e */ int prox_line_search(char *s) /* tags.e */ int count_matches_in_buffer(int buf, char *text)
The line_search( ) subroutine searches in direction dir for a line containing only the text s. It returns 1 if found, otherwise 0.

The prox_line_search( ) subroutine searches in the buffer for lines containing exactly the text s. It goes to the start of the closest such line to point, and returns 1. If there is no matching line, it returns 0.

The count_matches_in_buffer( ) subroutine returns the number of instances of the given text in the specified buffer.

do_drop_matching_lines(int flags, char *pat, int drop)
The do_drop_matching_lines( ) subroutine deletes all lines after point in the current buffer but those that contain the specified search pattern. The search flags say how to interpret the pattern. If drop is nonzero, the subroutine deletes lines that contain the pattern; if drop is zero it deletes all lines except those that contain the pattern. Temporarily set the show-status variable to zero to keep it from displaying a line count summary.

replace_in_readonly_hook(int old_readonly) replace_in_existing_hook(int old_readonly)
The file-query-replace command calls some hook functions as it goes through its list of buffers or files. Just before it makes its first change in each buffer (or asks the user whether to make the change, if it's still in query mode), it calls either the replace_in_existing_hook( ) subroutine (if the buffer or file was already loaded before running the command) or the replace_in_readonly_hook( ) (if file-query-replace had to read the file itself). The file-query-replace command temporarily zeroes the readonly-warning variable; it passes the original value of this variable as a parameter to each hook.

The default version of replace_in_existing_hook( ) does nothing. The default version of replace_in_readonly_hook( ) warns about the file being read-only by calling do_readonly_warning( ).

Previous Up Next
Regular Expression Searching Primitives and EEL Subroutines Moving by Lines