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.

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

  1. 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.

  2. 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.

  3. 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).
  4. 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)
1for a search with regular expressions. In this case "searchString"
and "replacementString" can be any regular expression.
ifor a case insensitive search. If there is no i, the search will
be case sensitive.
mto 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 :

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 :

    Version History

    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 :

    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.