CML Reference Guide

Chapter 4.18:  Searching Conference Text


Several very specialized functions provide the capability to search for and display text in the conference items and responses.

$find_in_item (cnum inum r0 r1 any inword text)
Search conference cnum, item inum, responses r0 through r1.  (If r1 is -1, search through the last response).  Look for the word (or words) in text.

The any and inword arguments modify exactly how and when the search succeeds.  If any is 1, the search is successful if any of the words in text are found in a response.  If any is 0, the search succeeds only if all of the words in text are found in the same response. 

If inword is 1, the words in text match no matter where they are found in the response -- including in the middle of a word in the response. (For example, "the" will match "other".)  If inword is 0, matches must occur at the beginning of a word.  (In that case, "the" will not match "other", but it will match "thesis".)

Find_in_item() searches item inum until one of two things has happened:

  • All the responses r0 through r1 have been searched, or
  • It has spent more than pagetime/2 seconds searching (see $pagetime()).

Find_in_item() evaluates to a "pickup" triplet, followed by a triplet list of responses that had successful matches.  The pickup triplet is "0 0 0" if all the responses were searched.  Otherwise it indicates the response after the last response searched, i.e. where to "pick up" with searching again on the next call to $find_in_item().

For example, "0 0 0 17 2 5 17 2 8" means that all the responses were searched, and responses 5 and 8 in item 2 in conference 17 had successful matches.

$find_it (cnum inum r0 r1 any inword text)
Obsolete form of $find_in_item().  Searches responses r0 through r1 without checking time.  Returns just the triplet string of matches, with no "pickup" triplet.

$search_it(cnum inum r0 r1 any text)
This is an obsolete form of $find_it().  It is equivalent to $find_it() with an inword of 0.

$find_filter(size words... inword text)
Find_filter is really a text filter.  It is meant to be used to display just the "hits" in a response that contains a word or words searched for via $search_it().  It boldfaces the searched-for words, and displays 3 lines of text around each hit.

Text is typically the entire text of a response.  Words contains the word or words that were searched for.  Size is the number of distinct words in wordsInword should have the same value it did in $find_it() -- it controls whether matches may be found in the middle of a word (inword = 1), or only at the beginning of a word (inword = 0).

$search_filter(size words... text)
This is an obsolete form of $find_filter().  It is equivalent to $find_filter() with an inword of 0.