| Store | Cart

ActiveState Docs

PDK 8.0 Documentation

Loading...

Filter Builder - User Guide

About the Filter Builder

The Filter Builder is a tool for constructing filters and, optionally, altering the contents of text-based files, such as log and XML files. Search and replacement criteria can be specified, and then applied on a line-by-line basis to the input.

The Filter Builder is useful for tasks such as searching log files, tweaking regular expressions and renaming variables throughout source files for a Perl program.

The Filter Builder can filter text documents using either strings or Perl5 regular expressions. Filters created with the Filter Builder can be saved as Perl scripts and run from the command line.

Input can be entered or pasted into the Input pane or loaded from files. The Output pane displays the filtered results. Both input and output can be saved to a file. The filters created with the Filter Builder can be saved as Perl scripts.

The Select Lines from Input, Input and Output panes are displayed by default when the Filter Builder launches. Use the View menu to display additional panes and to toggle the display of all panes. Resize panes by clicking on the bars that separate the various panes. Hide unwanted panes by clicking the 'X' in the top right corner of each pane.

To launch the Filter Builder:

  • Select Start|Programs|ActiveState Perl Dev Kit 7.x|Filter Builder

Selecting Input

The Filter Builder searches and matches based on the text displayed in the Input pane. Text can be typed directly into the Input pane, copied and pasted from another application ('Ctrl'+'C', 'Ctrl'+'V') or copied from the Filter Builder's own Output pane (Edit|Copy Output to Input). Input can also be loaded as a file (.txt, .log, .pl, etc). To make text with long lines easier to read, on the View menu, click Wrap Lines.

To load input from a file:

  1. On the File menu, select Open|Input File..., or click the 'load input' icon at the top of the Input pane.

  2. Select a file using the Load Input dialog box, and click Open. The contents of the file are displayed in the Input pane.

    Note: If you have edited the contents of the input file but want to reload the original file, on the File menu, select Reload|Input. This command is only available if the input was loaded from a file.

To load remote input from a URL:

  1. On the File menu, select Open|Input Location....

  2. Enter the URL (HTTP, HTTPS, or FTP). For example:
      ftp://example.org/pub/remotefile.log

Saving Input

To save changes to the input, use the Save|Input and Save|Input As commands on the File menu.

Clearing Input

To delete the contents of the Input pane, click the 'clear input' icon at the top of the Input pane. To clear the contents of all panes, and return to the Filter Builder's default view, select File|New.

Selecting Lines from Input

The Select Lines from Input pane is displayed by default when the Filter Builder launches. The Select Lines from Input pane contains a drop-down list for narrowing filter criteria as well as a check box to make matches case-sensitive or case-insensitive and a button to set the highlighting color for filtered text.

The Select Lines from Input pane accepts both strings and Perl5 regular expressions. Select an option from the drop-down list to define the nature of the filter. The first four options (containing, not containing, starting with, not starting with apply to string-based filters, and the last two (matching, not matching) are for use with regular expressions.

To create a 'select' filter:

  1. On the drop-down list, click the item that defines the filter.

  2. Enter the string or regular expression in the field provided. The check box to the left of the drop-down list is automatically selected. The results are automatically displayed in the Output pane. Any text that matches the filter criteria is highlighted.

By default, this pane contains only one 'selector' (set of options consisting of an input field and buttons), but others can be added by clicking the 'plus' button in the top right corner of the pane. By adding selectors, you can create a filter with multiple conditions.

The Or and And radio buttons determine the boolean relationship between multiple conditions (i.e. 'this' AND 'that' vs. 'this' OR 'that').

Replacing Text

The Replace Regular Expression pane accepts Perl5 regular expressions. Select View|Replace to display this pane.

To create a 'replace' filter:

  1. In the first field, enter the regular expression to be replaced. The check box to the left of this field is automatically selected. The initial results are automatically displayed in the Output pane.

  2. In the second field, specify the replacement for the regular expression. The results are automatically displayed in the Output pane. Any text that matches the filter criteria is highlighted.

    Use the options to the right of the fields in the Replace Regular Expression pane to further refine the replacement criteria. Clear the Global check box to replace the first instance in a given line (the default is to replace all occurrences in each line). Clear the Ignore case check box to make the match case-sensitive. Click the 'select color' button set the highlighting color for the filtered text that appears in the Input and Output panes.

By default, the Replace Regular Expression pane contains only one 'selector' (a set of replacement fields and buttons for additional options). Click the 'plus' button in the top right corner of the pane to create additional selectors. Adding selectors makes it possible to create a filter with multiple conditions. Select different check boxes to experiment with various filter combinations.

Specifying Variables

Use the Variables pane to specify elements of regular expressions that will be provided to the filter script as arguments. Replace the parts of regular expressions in the Select Lines from Input and Replace Regular Expression panes with the variable name. Once these variables have been created and tested with the Filter Builder, they can be initialized from the command line.

Select View|Variables to display the Variables pane.

To create a variable filter:

  1. In the Variables pane, click the 'add' button. The New Variable dialog box is displayed.

  2. Enter a name for the variable, and click OK. The variable name must conform to Perl syntax. That is, the first two characters must be a dollar sign and some letter (e.g. $a). Add other letter and numbers as desired to complete the variable name (e.g. $arg1). An entry is added to the Variables pane.

  3. Enter the value for the variable, and select Save|Filter As. Once the file has been saved, the location of the filter is displayed in the Filter Builder's status bar.

Saving Filters as Perl Files

You can save filters so that they may be re-opened in the Filter Builder. To save changes to a newly created filter as a Perl file, select File|Save Filter As. To save changes to a previously saved filter, select File|Save Filter.

Adding Descriptions to Filters

When saving a filter, you may want to add an explanation of its purpose. Select View|Description Pane to display the Description pane. Click in the Description pane, and then type or paste the description into the pane. The text is saved along with the contents of a filter.

Opening Filters

Filters created in the Select Lines from Input, Replace Regular Expression, and Variables panes can be saved as Perl files and then re-opened whenever necessary. To open a previously saved filter, on the File menu, select Open|Filter. Use the Open Filter dialog box to navigate to the filter location.

Closing Filters

To close a saved filter, on the File menu, click New. The existing filter closes, and a new set of the current panes is displayed.

Saving Input and Output

The contents of the Input and Output panes can be saved to disk. When saving input, select File|Save|Input As. To save changes to existing input, select File|Save|Input. Output can be saved in a variety of file formats but cannot be edited. To save output, click the 'save' button at the top right of the Output pane. Alternatively, use File|Save|Input As or File|Save|Input.