Filters Menu Help

Name:	Filters Menu
Version:	4.0
Last update:	2019-11-27 15:09:08

Introduction
Activation
Basics
Filters syntax
- Caveats
Description of the menu items
- Main Filters Menu
- Filters Utilities Submenu
Using filters from a script
Key Bindings
Preferences
Known problems
License and Disclaimer

Introduction

The Filters Menu allows you to perform successive Search And Replace operations. All the operations are gathered in files called filters which you can apply to any document opened in Alpha, or to all the files contained in a folder or a fileset.
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 selects filters instead.

You can mix various kinds of Search And Replace operations 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 keep them in one of the Filters folders known by the menu. They are immediately available. The syntax of the filters is very simple (see the Filters syntax section below).
For temporary operations which you do not want to store in a permanent filter, you can use the Temporary Filter.
All the Search And Replace operations may be applied to an entire window or be limited to a selected region.
The filters may also be applied to all the files in a given directory or in a fileset.

Activation

To activate the Filters Menu, go to Alpha ↣ Global Setup ↣ Menus and select the Filters Menu checkbox.
Once it is activated, you have a new menu in the menu bar with the filter commands.

Basics

For any conversion you want to perform, you have to select an appropriate filter with the Pick A Filter menu item. This filter contains the conversion instructions which are lines of text describing the strings to find and the replacements for these strings.
In order to convert the current window, select the Apply Filter To Window menu item. If you want to convert only a part of your current window, hilite the corresponding region and choose the Apply Filter To Selection menu item.
Note that the selected filter which you apply to a window or to a selection does not have to be open. Once you picked it, it is the active filter (its name is displayed at the bottom of the Filters Menu).
Alpha comes with some predefined filters providing basic operations but most of the time you will create your own filters as explained through the following examples.

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 window to the front and choose the Apply Filter To Window menu item.
Alternatively you can use the following keyboard shortcut: ⌃F W. If you convert only a selected region, press ⌃F S. To pick a filter you can also use ⌃F P.

Second example

If no predefined 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 (or press ⌃F N). 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 to L. van Beethoven, then delete all the occurences of the § symbol and finally 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 press ⌃F Y).

Third example: temporary filter

If you want to do temporary conversions on the fly and do not want to keep them permanently in a filter, you can use 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 between sessions. They will remain available only as long as you do not quit Alpha and do not close the Temporary Filter window.

Filters syntax

Every Search And Replace operation is described by a line whose syntax is as follows:

 searchString    replacementString    [options]

where the three arguments are separated by one or more tabulations. The options, when specified, are any combination of the following symbols:

0	ordinary textual search (this is the default)
1	regular expression syntax
i	case insensitive
m	match words
d	let '.' match any character, including line separators
e	let '^' and '$' match only the extremities of the region

Option 0 can be omitted. Option 1 means that the search and replace strings are interpreted according to the syntax of regular expressions.
If option i is not specified, the search is case sensitive by default. If option m is not specified, the search can match any substring.
By default, a dot matches all characters except line endings: with option d, a dot will also match the line separators.
By default, the anchors ^ and $ match respectively the start and end of all the lines: with option e, they will instead match only the extremities of the region to which the filter is applied.
The options can be combined (in any order). For instance: m, im1, mi, 1de etc.
A line starting with two exclamation marks (!!) is considered a comment and is ignored.
Options d and e have been introduced in version 4.0 of this package (in Alpha 9.1.1).

Caveats

Remark 1

It is very important that the arguments of each filtering instruction in a filter 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 engine and can be useful for a nice visual presentation of the filters.

Remark 2

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 like this (with no tabulation at all after the search string):

 searchString

Remark 3

Beware of misinterpretations: if you write

 arg1  [tab]  [tab]  arg2

i-e two arguments separated by two tabulations, 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 be more specific with the options and write

    arg1  [tab]  [tab]  arg2  [tab]  options

which is equivalent to

 arg1  [tab]  arg2  [tab]  options

Description of the menu items

Here is the description of all the menu items of the Filters Menu. Some items are displayed if you press the Shift (⇧) key or the Option key (⌥) while opening the menu.

Main Filters Menu

Pick A Filter…: Will show you the list of all filters: select the one you want to apply. The name of the selected filter will be displayed at the bottom of the Filters Menu.
Apply Filter To Selection: Apply the filter to a selected region in the front window.
Apply Filter To Window: Apply the filter to the current window.
Apply Filter To Fileset…: Prompts you for a fileset to apply the selected filter to. The Filesets packages must be activated. This is not undoable.
Apply Filter To Folder…: Prompts you for a folder to apply the selected filter to. This is not undoable. Note that recursion in subfolders is controlled by the Filtering Depth preference which is 0 by default.
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 apply the Temporary Filter to. This is not undoable.
Apply Temp To Folder…: Prompts you for a folder to apply the Temporary Filter to. This is not undoable.
Current Filter: Display a message window indicating the name of the current filter.

Filters Utilities Submenu

The Filters Utilities submenu has the following items:

New Filter: Create a new filter.
Edit A Filter…: Displays the list of all filters: select the one you want to edit.
Edit Current Filter: Edit the file defining the currently selected filter.
Delete A Filter…: Displays the list of all filters: select the one you want to delete.
Filtering Depth…: Set the value of the filtering depth: this controls the level of recursion in subfolders when applying a filter to a folder.
Reveal Filters Folder: Switch to the Finder and open the folder containing the '.flt' files corresponding to the user defined filters.
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, etc. There is a maximum number of errors tolerated (see the preferences): if more are to be found, the syntax checking will stop.
Display Bindings: Display in a separate window the keyboard shortcuts available to access the various features. See the Key Bindings section below.
Display Syntax: Display, as a reminder, a short description of the filters syntax.
Filters Sandbox: Open a tutorial.
Filters Example: Open a sample filter.
Filters Preferences…: Display the preferences dialog.
Menu Shortcuts…: Lets you set custom keyboard shortcuts for all the menu items.

Using filters from a script

You may perform filtering from a script with one of the following commands.

flt::filterString filter str

Apply a filter to a string. Return the processed string.

flt::applyToSelection ?-w win? filter

Process the current selection of a document window with a filter. If the -w argument is not specified, the proc applies to the current window.

flt::applyToWindow ?-w win? filter

Process the entire contents of a document window with a filter. If the -w argument is not specified, the proc applies to the current window.

flt::applyToFolder filter ?dir? ?level? ?warn (0|1)?

Process all the files contained in a folder (and possibly in subfolders depending on the current filtering depth). This is not undoable. If the dir argument is not specified, ask the user to select a folder. If the level argument is not specified, use the current filtering depth. If the warn argument is set to 0, skip the warning dialogs.

flt::applyToFileset filter ?fset? ?warn (0|1)?

Process all the files contained in a fileset. This is not undoable. If the fset argument is not specified, ask the user to select a fileset. If the warn argument is set to 0, skip the warning dialogs.

flt::applyToFileset filter file

Apply a filter to a file. Return 1 if the file was modified, 0 otherwise.

Key Bindings

There are a few easy to remember key bindings à la emacs. They are composite bindings starting with ⌃F or ⌃T. Click here to display all the available bindings.

Preferences

The Filters Preferences item in the Filters Utilities submenu displays a dialog which allows you to set some preferences explained below. Click here to display the Filters Menu Preferences panel.

the Warn Not Undoable flag can be set to warn you, each time you apply a filter to an entire directory or to a fileset, that it is an action which cannot be undone. Uncheck this box if you do not want to be warned. Note that filtering applied to a selection or to a window can be undone.
if the Show Filter Syntax flag is set, there will be a short reminder of the filters syntax at the beginning of any newly created filter and of the Temporary Filter window. Uncheck this box if you do not want this.
the Max Number Errors variable specifies the maximum number of errors tolerated when checking the syntax of a filter. If there are more, syntax checking will be aborted after this number of errors. Default value is 15.
the Filtering Depth variable sets the depth of nested subfolders to visit when applying a filter to a folder. 0 means don't recurse in subfolders, -1 means unlimited depth.

Known problems

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

License and Disclaimer

Copyright (c) 2000-2019, Bernard Desgraupes.
All rights reserved.
The Filters Menu 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.