The file_search module offers easy to use support for performing searches in files. It ships with built-in support for three file search backends (simply referred to “searchers”) but offers the ability to easily register additional ones if so desired.

Apart from performing the actual searches the module also provides support for intelligent sorting of the results. The added intelligence compared to the basic search tools comes from exploiting the knowledge of the current context which is available in a editing context but not for generic tools.


Searches are registered using the register_searcher function, and can be unregistered using its companion unregister_searcher. The searches itself is a simple table which must provide three fields:

Search handlers

Search handlers have the following signature:

handler(directory, search, opts)

I.e. they are invoked with three arguments; directory is a File instance specifying the directory in which to perform the search. search is a string containing the actual string to search for. Finally, opts is table with the following possible options:

The handler can return three different types of return values: First, it can return a string, in which case it’s interpreted as an external search command to run. The command will be run and its output will be parsed for search results. Second, it can return a Process instance. Here as well the process will be run and its output will be parsed for search results. Third, the handler can perform the search in some way of its own design and return the search results directly in a table.

For handlers performing their own searches it’s well to note that care has to be taken not block the application while performing the search. If needed, the activities module can be used to allow the user feedback and optionally a way of cancelling the search.

The results should be returned as a table, containing one or more search hit tables. Each search hit table must contain the following members:

While not required, if at all possible the search hit should also include the numeric column of the matching text via the column member. This should be reported using byte offsets.



A table of available searchers, keyed by name.


register_searcher (searcher)

Registers the searcher searcher. The following fields must be specified for a searcher:

See the section Searchers for more information about search handlers.

Performs a search in directory for the search string in term. opts, if specified, can contain the following fields:

The function returns two values, a table of search results and the actual searched used for the search. Each search hit contains at least the following fields:

Search hits can also optionally contain the following fields:

sort (matches, directory, term [, context])

Sorts the search hits provided in matches. directory should be a File pointing to the directory where the search was performed and term the search string. The optional context argument is a BufferContext instance indicating the context from which the search was performed. If provided, search hits will be ranked according to their relevance to the given position.


Unregisters the searcher with name name.