This is a help file for the Filters Menu in Alpha. This file should be
located in the Help subfolder of Alpha's folder to show up automatically in
the Help menu when Alpha is loaded.
Introduction
The Filters Menu allows you to do successive "Search And Replace"
operations. All the operations are gathered in files called "filters"
which you can apply to any text file opened in Alpha.
- You can mix various kinds of "Search And Replace" in the same filter:
textual or regular (i-e with grep patterns), case sensitive or not,
matching exact words or not.
- You can write your own filters and collect them in the "Filters"
folder. They are immediatly available. The syntax of the filters is very
simple (see below).
- You can also combine filters and build a Multi Filter : all the
filters in the Multi Filter will be applied sequentially to your current
window.
- For temporary operations which you do not want to store in a filter,
you can use the Temporary Filter.
- All the "Search And Replace" operations can be applied to a whole file
or to a selected region only.
- Filters and Multi Filters can be applied to all the text files in a
same folder.
This is a find-and-replace gizmo that works on its own, using just the
items in the Filters menu. One doesn't have to use the Find window or
command line but uses filters instead. Installation
Automatic installation
Open the "OPEN TO INSTALL" file. Opening this file indicates to Alpha that
a new package has to be installed : the procedure is automatic. Alpha knows
where to store the different elements of your Filters Menu package.
Manual installation
- put the "Filters Menu" folder in the "Menus" subfolder of the "Tcl"
folder which is located at the same level as your Alpha application : this
folder contains the file "filterMenu.tcl" and a folder called "Filters"
where all the filters are stored. If there is no "Filters" folder there, it
will be created automatically by the Filters Menu.
In versions of Filters Menu prior to 1.5, the Filters folder was located in
the UserModifications folder : if you have personal filters stored there
you will have to move them to the new location.
- put the "Filters Help" file in the "Help" folder located at the same
level as your Alpha application. Next time you launch Alpha, you will have
a "Filters Help" item in the Help menu.
- launch Alpha. You have to rebuild the package indices and the Tcl
indices. "Rebuild Package Indices" is in the Config/Packages menu, and
"Rebuild Tcl Indices" is in the Tcl menu (press cmd-Y to open a tcl shell).
- quit Alpha and relaunch it : that's all there is to it.
After installing
Have a look at the Filters Menu preferences in the "Packages" submenu of
the "Config" menu. You can set various flags. More explanations below.
Tutorial
For any conversion you want to do, you have to select an appropriate filter
with the "Pick a filter" menu item. This filter contains the conversion
instructions : it is a simple list of strings to find and of replacements
for these strings. Then if you want to convert an entire file, this file
must be open in the current window : just select the "Apply to file" menu
item and the conversion will be accomplished. If you want to convert only a
part of your current file, hilite the corresponding region and choose the
"Apply to selection" menu item.
Note that the selected filter which you apply to your file or to a region
does not have to be open. Once you picked it, it is the active filter.
First example
Suppose your file is full of accented letters and you want to strip all the
accents (to send an e-mail for instance). You can select the filter called
"Strip The Accents". Once it is selected, you will see its name at the
bottom of the Filters menu. Bring your current file's window to the front
and choose the "Apply to file" menu item.
Alternatively you can use the following key binding : hit 'control-f',
release, then hit the 'f' key. If you convert only a selected region, hit
'control-f', release, then hit the 's' key. To pick a filter you can also
use 'control-f p'. Second example
Suppose no filter suits your needs. You'll have to write your own. This is
very easy. Choose the "New Filter" menu item in the "Filters Utilities"
submenu. You'll be prompted for a name to give to the new filter. Let's
call it "MyNewFilter" : this new filter is now the active filter. Suppose
you want to change in a text all the occurences of J.S. Bach in L. van
Beethoven, then to delete all the occurences of the ¤ character and finally
to replace multiple tabulations by a single one. You have to type the three
following lines (more about the filters syntax later) where the arguments
are tab-separated :
J.S. Bach L. van Beethoven
¤
\t+ \t 1
Save your filter and apply it as in the preceding example. You can check
the syntax of your new filter thanks to the "Check Syntax" menu item in the
Filters Utilities submenu (or hit control-f c). Third example: multi filters
Suppose you want to apply several filters successively : for instance "Html
To Accents" then "Accents To Rtf". This can be done in one run thanks to
the
MultiFilter. The MultiFilter will be the list of filters you want to apply
(in the order you want them to be applied). To build such a list, hold the
option key down then open the Filters menu : instead of "Pick a filter" its
first item will now be "Build a multifilter" which brings a list of all the
filters available. This list will be brought to you repeatedly until you
have chosen all the filters you want and have finished with the "cancel"
button. To apply the Multifilter to a selection, a file or a folder, hold
down the option key and select the corresponding item in the Filters menu.
Fourth example: temporary filter
If you want to do temporary conversions on the fly and do not want to keep
them in a filter, you have the Temporary Filter. You use it exactly like
any other filter. The only difference is that the instructions you write in
it will not be saved. They will remain only as long as you do not quit
Alpha and do not close it. More examples
See the filter called Example (file example.flt). Most of the filters
provided with the Filters Menu deal with accents conversions but you can
imagine many kinds of conversions. A more advanced example is given in the
"Convert Html To Latex" filter which converts an Html document to a latex
source file ready to process with LaTeX. Filters syntax
Every "Search And Replace" operation is described by a line whose syntax is
as follows :
searchString replacementString [option]
where the three arguments are separated by one or more tabulations.
The option is a (possibly empty) string containing 0 or 1 and/or one of the
letters i and m with the following signification :
0 | (or nothing) for an ordinary textual search (this is the default) |
1 | for a search with regular expressions. In this case "searchString" |
| and "replacementString" can be any regular expression. |
i | for a case insensitive search. If there is no i, the search will |
| be case sensitive. |
m | to match words exactly (not only a substring of a word). |
| If there is no m, the search will match any substring. |
The options can be combined (in any order) :
0m, im1, i, 0m etc. (01 means 1).
A line starting with two exclamation signs (!!) is considered a comment and
not a filter instruction.
All the filters are located in the Filters subfolder of the "Filters Menu"
folder included in the "Tcl:Menus" folder of Alpha's distribution. They
have an extension ".flt" to identify them.
Included filters
There is the possibility (since version 1.6 of Filters Menu) of calling a
filter from within a filter. The syntax for this is :
!!includefilter "name-of-filter"
or
!!inputfilter "name-of-filter"
The keywords 'includefilter' and 'inputfilter' are synonymous. The double
exclamation point must be at the beginning of a line and no space follows
it. The includefilter command is followed by one or several spacing
characters (spaces or tabulations) and the name of the filter (with or
without the ".flt" extension). The double quotes are optional: use should
use them if the name of the filter contains spaces for the sake of
legibility (but even in that case, they are not required).When an includefilter or inputfilter statement is encountered, the entire
included filter is executed before continuing with the next line. An
included filter can also have includefilter or inputfilter statements
itself: to avoid the risk of recursive calls resulting in an infinite loop,
the depth of included filters is limited. The default value for the maximal
depth is 2. This can be changed in the Filters Menu Preferences with the
variable "Max Include Depth".
With a maximal depth of 2 you can have a structure of included filters like
this
Main filter
/ \
/ \
/ \
/ \
fltA fltB
/ \ / \
/ \ / \
fltC fltD fltE fltF
If filters fltC, fltD, fltE or fltF contain include statements, these
statements will be ignored since they wil be at level 3 (unless of course
you set the "Max Include Depth" to 3 or more). You can put as many includes
as you want in a filter.
This technique can replace the use of multi filters. A multi filter could
be replaced by a main filter contain an includefilter command for each of
its components. The advantage is that they can be stored for later reuse.
The Temporary Filter can also be included as any other filter, like this:
!!includefilter Temporary Filter
Caveat
It is very important that the arguments be separated by tabulations. The
spaces, if any, will be considered as part of the strings. You can separate
the arguments with several tabulations : this will not confuse the Filters
Menu and can be useful for a nice visual presentation of the filters.
The replacement string can, of course, be empty. In this case, the
corresponding line in the filter will look like this
searchString [option]
(note that there are two tabs here between searchString and [option]).
If there is no option, the line will just be :
searchString
Beware of misinterpretations : if you write
arg1 [tab] [tab] arg2
i-e two arguments separated by a double tabulation, this will be
interpreted as :
- search String = arg1
- replacement string is empty
- options = arg2
If this is NOT what you want you will have to precise the options and write
arg1 [tab] [tab] arg2 [tab] options
which is equivalent to
arg1 [tab] arg2 [tab] options
Note that most of the built-in filters supplied with the Filters menu
convert character entities; for example, the HtmlToLaTeX filter will
convert HTML entities such as
ë
to their LaTeX equivalent
\"{e}
These filters do not convert structural markup such as headers, paragraphs,
or blockquotes. But a filter like ConvertHtmlToLatex DOES this kind of
things. Here is now an example of filtering instructions
(see also the Example.flt filter) :
LaTeX Plain TeX im
(oz|cmac)TeX \\TeX 1
!! The following suppresses empty lines :
^$\r 1
!! Replace tea by coffee (the 0 option can be omitted) :
tea coffee 0m
Contributions
I hope that in the future there will be contributions and that new general
purpose filters will be added to the present collection.
Send me an e-mail if you want me to add your filters to the
distribution and/or to host them on my home page on the web :
bdesgraupes@easyconnect.fr.
Description of the menu items
Here are the explanations for all the menu items of the Filters Menu.
Certain items are obtained if you hold the Option Key down while opening
the menu.
- Pick A Filter
-
Will show you the list of the filters : select the
one you want to apply. The file does not have
necessarily to be open. The name of the selected
filter will be indicated at the bottom of the
Filters Menu
When holding the option key down :Build A Multi Filter-
A dialog window allows you to build a Multi Filter.
Select any filter you want to include in the Multi
Filter with the pop-up menu. The dialog will show
up repeatedly until you click on the "cancel"
button. This item is equivalent to the "New Multi
Filter" item (see below).
Apply Filter To Selection-
Apply the selected filter to a selected region in
the front window.
When holding the option key down :Apply Multi To Selection-
Apply the Multi Filter to a selected region in the
front window.
Apply Filter To Window-
Apply the selected filter to the current window.
This is not undoable.
When holding the option key down :Apply Multi To Window-
Apply the Multi Filter to the current window. This
is undoable.
Apply Filter To Fileset...-
Prompts you for a fileset to which apply the
selected filter. The Filesets packages must be activated.
This is not undoable.
When holding the option key down :Apply Multi To Fileset...-
Prompts you for a fileset to which apply the Multi
Filter. This is not undoable.
Apply Filter To Folder...-
Prompts you for a folder to which apply the
selected filter. This is not undoable.
When holding the option key down :Apply Multi To Folder...-
Prompts you for a folder to which apply the Multi
Filter. This is not undoable.
Temporary Filter-
Open a Temporary Filter window in which you can
type and apply filtering instructions that you do
not intend to save later. See the syntax above.
Apply Temp To Selection-
Apply the Temporary Filter to a selected region in
the front window.
Apply Temp To Window-
Apply the Temporary Filter to the current window.
This is not undoable.
Apply Temp To Fileset...-
Prompts you for a fileset to which apply the
Temporary Filter. This is not undoable.
Apply Temp To Folder...-
Prompts you for a folder to which apply the
Temporary Filter. This is not undoable.
Current Filter / No Filter Selected-
Display a dialog window indicating the name of
the current filter and the contents of the Multi
Filter.
The "Filters Utilities" submenu has the following items :

- New Filter
-
Create a new filter.
When holding the option key down :New Multi Filter-
Build a new Multi Filter. The previous contents of
the Multi Filter will be replaced by the new
definition. This is equivalent to the
"Build A Multi Filter" item seen above.
Edit A Filter-
Will show you the list of the filters : select the
one you want to edit.
When holding the option key down :Edit Current Filter-
Edit the file defining the currently selected filter.
When holding the shift key down :Show Multi Filter-
Show the contents of the Multi Filter.
When holding the control key down :Edit Multi Filter-
Edit all the filters contained in the Multi Filter.
Delete A Filter-
Will show you the list of the filters : select the
one you want to delete
When holding the option key down :
Clear Multi Filter-
Empty the contents of the Multi Filter.
Check Syntax-
Check the syntax of a filter : this filter must be
edited and be the current window. This will look
for syntax errors concerning the structure of each
line, the options, the validity of the grep
patterns. There is a maximum number of errors
tolerated (see the preferences) : if more are to be
found, the syntax checking will stop. If other
filters are included using the !!inputfilter or
!!includefilter keywords, Filters Menu will propose
to open these files for checking too: it does not
automatically checks the syntax of the included
filters.
Display Syntax-
Display, as a reminder, a short description of the
filters syntax.
Filters Bindings-
Display in a window the key bindings available to
access the various features. See section "Key
Bindings" below.
When holding the option key down :Reveal Filters Folder-
Switch to the Finder and open the folder containing
the '.flt' files defining the filters.
Filters Tutorial-
Open the tutorial.
Exporting procs
Since version 1.4 of Filters menu, two procs have been defined to
export the filtering capacity in other scripts. Just say
alpha::package require filtersMenu 1.4
at the beginning of your script and then use one of the following
commands
flt::filterThisFile $filtername $filename
flt::filterThisSelection $filtername $selection
"filtername" is the name of the filter you want to apply (without the
flt extension). If "filename" is not specified then it applies to the
current window. "selection" is the name of a variable : the proc
flt::filterThisSelection returns the result of filtering applied to
the contents of this variable. Key Bindings
There are a few easy to remember keybindings "ˆ la emacs". For all of
them you have to hit 'ctrl-f', release, then hit one of the following
letters :
'b' | to show the key bindings |
'c' | to check the syntax |
'd' | to filter a folder (or directory) |
'e' | to edit a filter |
'f' | to filter a fileset |
'm' | to build a multifilter |
'n' | to create a new filter |
'p' | to pick a filter |
's' | to filter the selection |
't' | to call up the temporary filter |
'w' | to filter the current window |
If you add the shift key with letters s, w, d, f, c or e you get the
equivalent actions but with a Multifilter instead of a Filter. For instance
'ctrl-f shift-f' is equivalent to "apply multifilter to the current file"
and 'ctrl-f shift-c' will clear the multifilter.'ctrl-f opt-e' edits the current filter.
There are three more key bindings to use the Temporary Filter. First hit
'ctrl-t', release, then hit one of the letters s, w, d, f in order to apply
the temporary filter to a selection, to the current window, to a directory
or to a fileset respectively.
Preferences
The "Filters Prefs..." item in the "Packages" submenu of the "Config" menu
allows you to make a few choices :
- the "Warn Not Undoable" flag can be set to warn you, each time
you apply a filter to a whole file, that it is an action which can't
be undone. Uncheck this box if you do not want to be warned.
- if the "Show Filter Syntax" flag is set, there will be a short
description of the filters syntax at the beginning of any new filter and of
the Temporary Filter window. Uncheck this box if you do not want it.
- the "Max Numb Err" variable designates the maximum number of errors
tolerated when checking the syntax of a filter. If there are more, syntax
checking will be aborted after MaxNumbErr errors. Default value is 15.
- the "Max Before Scrap" variable designates the maximum length of a
selection above which filtering will be done not in the current window
directly but in a scrap window. Using a scrap window is much faster, so you
should give this variable a small value. Default value is 70.
- the "ToggleSupSearch" flag allows filtering to run much faster by
deactivating superSearch (if present) during filtering operations and
then immediatly reactivating. If unchecked, filtering will be slowed
down. This flag has no effect with Alpha8: it only applies to Alpha7.
Version History
- 0.1a -- 00/04/05 -- Created the Filters Menu.
- 0.1b -- 00/04/18 -- First beta release.
- 0.2b -- 00/04/19 -- Modified the procs to filter a selection: now
uses a scrap window which accelerates considerably the substitutions.
Added avariable in the menu preferences to decide which method to use
depending on the length of the selection. Corrected lots of minorbugs.
- 0.3b -- 00/04/27 -- Added new filters. Changed the uninstall
procedure.
- 0.4b -- 00/04/29 -- Added a warning to deactivate superSearch when
loading the Filters Menus. Corrected minor bugs in the syntax checking
proc.
- 0.5b -- 00/05/03 -- Added key bindings.
- 0.6b -- 00/05/04 -- Modified the code to reflect Vince's guidelines
concerning future versions of AlphaTcl or AlphaTk. Suppressed the warning
concerning superSearch since this latter has been modified. Made the scrap
window "invisible" (off screen). Made the flt::substitute proc compatible
with superSearch by toggling it forth and back (can't account for the
incompatibility). Added a flag to toggle supersearch
- 1.0 -- 00/05/08 -- Cosmetic changes and first release.
- 1.1 -- 00/08/15 -- Added an internal Fltr mode to improve filters
edition (coloring of comments, correct commenting/uncommenting procs,
option-click on title bar, file marking).
- 1.2 -- 00/09/20 -- Added a "Filters Tutorial" menu item.
- 1.2.1 -- 00/10/20 -- Made minor corrections. Corrected a bug in
flt::applyToFolderProc.
- 1.2.2 -- 00/11/16 -- Added an info window with the key bindings
available with the filter menu ('ctrl-f b' to bring it up).
- 1.2.3 -- 00/12/22 -- Introduced the menu icon (coming with AlphaTcl
version 7.4).
- 1.3 -- 01/02/21 -- Modified the code internally to put all the
filters global vars in specific arrays. Done some cleaning. Nothing is
changed from the user's side except for the dialog window to build a
multifilter which has been much improved. Changed license to BSD.
- 1.3.1 -- 01/04/08 -- Minor syntactic changes (procs renamed).
- 1.3.2/3.. -- 01/04/20.. -- Minor corrections concerning the filtering
of a selection.
- 1.3.5 -- 01/04/28 -- Changed date to ISOTime in new filters. Changed
to new color syntax.
- 1.4 -- 01/05/27 -- Added two exporting procs. Factored some pieces
with flt::filterCore.
- 1.5 -- 01/07/31 -- Changed the location of the Filters folder to
facilitate the installing procedure.
- 1.6 -- 02/10/12 -- Added the possibility of include'ing filters in a
filter. Split the distribution into several smaller files.
- 1.7 -- 02/11/22 -- Changed the code for compatibility with Alpha8
which now uses supersearch as its default (and unique) search engine.
Streamlined the code. Added capacity of filtering a fileset. Filtering is
now processed off-screen.
Known problems
Note for Alpha7:
Filters menu is MUCH faster (6 times!) when superSearch is NOT active
due to the way each of them deals with its respective tasks. So you
should better temporarily deactivate superSearch : this is done by
default with the "ToggleSupSearch" flag in the preferences. Unless you
have a very good reason, leave this flag set. If you leave superSearch
active, you should then unset, in its preferences, the
"beepOnFailedSearch" flag (introduced 05/03/2000) unless you want to
hear a beep symphony when applying a long filter to a file containing
many unmatched strings. These remarks do not apply to Alpha8.Please e-mail any problem or bug you encounter :
bdesgraupes@easyconnect.fr
Visit my Web page for updates and other Alpha utilities :
http://webperso.easyconnect.fr/bdesgraupes/alpha.html
License and Disclaimer
(c) Copyright : Bernard Desgraupes, 2000, 2001, 2002
All rights reserved.
This software 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 the regents or contributors 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.