Hyper Search Help

Name:	Hyper Search
Version:	3.1
Last update:	2019-11-27 14:12:50

Introduction

HyperSearch is a feature for the text editor Alpha: it inserts a new item called Hyper Search in the Search menu to perform multi-file searches and display the results in a separate window with hyperlinks that allow you to jump directly to the corresponding match.
Search is executed in a selected folder. The results window can be saved to a file and reused later. This package can be considered as a tool to extract and collect information from a set of files with navigation capacities.
There is already a batch search option in Alpha's usual Find dialog but, with HyperSearch, you can do much more:

you can customize the output (with or without line numbers, with or without hyperlinks, with or without file names).
you can restrict the files you want to search: for instance, only the files with a .tex or .tcl extension, or only files whose name matches a given pattern, etc.
you can search in an entire folder and in all its subfolders.
you can search only the current window. In that case, HyperSearch extracts from this window the information you need.

And of course the usual flags can be set: search can be textual or regular, case sensitive or not, matching on word boundaries or not etc.
By default, some elements in the results window (such as the path names and line numbers) are displayed as hyperlinks: they appear underlined and colored in blue. Just click on them to open the corresponding file at the correct position.
Note that the search is done by scanning the files on disk, no matter whether some of them are edited or not. So possible matches in possibly opened and unsaved windows may not be found.

Activation

This package is always active and can be accessed through the Search ↣ Hyper Search… menu item.

Description of the dialog window

When you choose Hyper Search in the Search menu, Alpha displays a dialog window containing items which are described in the next sections.

Editable field

In the String to search field, set the text to search. If you use regular expressions, don't forget to check the regexp check box.

Buttons

Add Folder…: Click on this button if you want to select a new folder to search. Its name will be added to the Search In popup menu. If a folder with the same name already exists in the list, it will simply be replaced by the new one.
Reset list: Click on this button to clear all the elements of the pop up folders list.
Search: Click to launch the searching procedure.
Cancel: Click here to cancel the search. Nothing will be changed.

Check boxes

Ignore case: Set this flag to do no distinction between lower and upper case letters while searching.
Regexp: Set this flag for a regular search (as opposed to textual search). See the 'Regular Expressions' file in the Help menu.
Match words: Set this flag if you want to find only entire words (as opposed to a substring of a longer word).
Recursive: If this flag is set, the procedure will search in the selected folder and ALL its subfolders.
Line Anchors: If this flag is set, ^ and $ in regexp patterns match the start and end of lines. This checkbox is enabled only if the Regexp checkbox is selected.
Dot Matches All: If this flag is set, dots in regexp patterns match any character, including line separators. This checkbox is enabled only if the Regexp checkbox is selected.
No header: If this flag is not set, the results window will indicate the name of the files in which certain lines contained the searched string, as well as the number of these lines in the file and a hyperlink to edit this file. If this flag is not set, only the matching lines will be sent to the results window (with or without line numbers depending on the following flog).
No line numbers: Set this flag if you do not want the number of the matching lines to be written in the results window.
No hyperlinks: Set this flag if you do not want hyperlinks in the results window.

Pop up menus

Search In

Select from this list the folder or set of files you want to search. If you want a folder which is not in the list, use the Add Folder… button. The list of folders will be recorded between sessions: you will find it again next time you launch Alpha.
The popup menu also proposes some meta locations:

Top Window's Folder: If the current window corresponds to a file on disk, it performs the search in the directory containing this file.
Open Windows: To perform the search among the currently opened windows. Note that only windows corresponding to a file on disk are searched.
Current Window: To perform the search in the current window. In that case, the Pattern menu is irrelevant.

Pattern

In this popup menu, you can specify which kind of files should be searched: you can specify particular extensions to search only the files whose name ends with this extension or do more advanced choices.
The Any File item indicates that all the files must be searched.
The Extension… item allows you to specify a file extension. It displays a new editable field in the dialog window where one can specify the extension (with or without the dot).
The Filter… item allows you to specify a pattern for the file names. It displays a new editable field in the dialog window where one can specify a regular expression pattern to restrict the files to search (see the Regular Expressions help file for more about the syntax).
The rest of the list lets you select a particular extension.
Note: this part of the list is customizable via the Preferences. For instance, if you want to add permanently a new extension to the list, go to the Hyper Search Preferences panel and modify the list of extensions there. The preferences can be accessed with the Alpha ↣ Preferences ↣ Package Preferences ↣ HyperSearch menu item.

Hyper Search preferences

Click here to display the Hyper Search Preferences panel (or select Alpha ↣ Preferences ↣ Package Preferences).
All the preferences should be self-explanatory:

Hyper Search Shortcut allows you to customize the keyboard shortcut associated with the Hyper Search command.
Files Extensions lets you customize the list of file extensions displayed in the Pattern popup menu.
Folders Count allows you to set the maximum number of folders displayed in the Search In popup menu.

Using Hyper Search from a script

This section is intended for developers or users who want to use the Hyper Search facility from a script.
The HyperSearch package provides a Tcl proc called hypersearch::execute which by-passes the dialog and lets you specify directly the relevant options to perform the search.
The arguments passed to this proc should be formatted as a list suitable for the [array set] Tcl command. The keys of the array correspond to the various settings.
The available parameters are:

Flags	Default
matchWords	0
ignoreCase	0
noLineNumbers	0
noLinks	0
noHeader	0
recursive	1
regexp	0
dotAll	0
lineAnchor	1
Strings	Default
directory	[pwd]
searchString	current search string
filePattern	'.*'

Here is an example of use:

    hypersearch::execute searchString $str ignoreCase 1 directory $path

where str and path are variables containing respectively the string to search and the directory.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2001-2019, Bernard Desgraupes.
All rights reserved.
The Hyper Search package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Bernard Desgraupes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BERNARD DESGRAUPES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.