TextSpresso Manual Menu

Utility Filters

Overview

Break Text Filter

Character Table Filter

Insert Text Filter

Overview

This chapter explains how to create new filters using some of the simpler filter types available in TextSpresso. The filter types covered in this chapter aren't designed to perform advanced search and replace functions. (For filters of that type, see the Replace Text Filter, Replace Pattern Filter, and Word Table Filter chapters.) The filters in this chapter provide utility functions which may be useful by themselves or when integrated into a MultiFilter.

This chapter covers the Break Text Filter, the Character Table Filter, and the Insert Text filter. This chapter will grow as more utility filter types are added.

This chapter assumes that you already know how to create new filters and open filter editors, and that you know how to use the elements common to all filter editors. If not, please read Chapter 5: Managing Filters before proceeding.

Break Text Filter

The Break Text filter type can be used to insert any string into a body of text every X number of characters. Its name comes from the fact that it's useful for breaking, or hard wrapping, text to a particular line width by inserting a carriage return every so many characters. In fact, the Hard Wrap... menu command under the Text menu creates and invokes a temporary Break Text filter to get the job done.

The Break Text filter editor has two fields named Break Length and Break String. You enter the break length (i.e. line width) in the first field, and the string to insert in the second. The first field will, of course, only accept a number greater than 0.

Keep in mind when entering your break length that the final line width will be the break length you enter plus the string that's inserted. For instance, if you enter 100 and CR (carriage return), a CR character will be inserted after every 100 characters to produce a line width that is 101 characters. If the line width needed to be 1 including the CR, you would enter 99 as the break length.

In the Break Text filter editor there is also a check box titled Try to break between words? When this box is checked the filter attempts to insert the break string in between whole words rather than in the middle of a word. If it must, it will break in the middle of a word to avoid producing a line that is longer than the break length. But if it can it will avoid doing so by breaking in between words. This will generally produce lines which are shorter than break length, but as close as possible while preserving whole words.

Character Table Filter

The Character Table filter is a single character search and replace function which is capable of mapping any where from 1 to 2 characters within a single pass. Because it is optimized to search and replace single characters it is very, very fast. Further, there is no speed penalty for mapping more than one character. Mapping the entire ASCII character set is just as fast as mapping one character.

For instance, say you wanted to create a filter which converted all characters to lowercase. You could create a MultiFilter with a large number of Replace Text filters, one to convert each uppercase letter to a lowercase letter. Or you could use a single Character Table filter to do the job and do it at higher speeds.

The Character Table filter uses a case mask to map characters. A case mask is a table which maps normal ASCII characters to replacement, or mask, characters.

To edit and save a new case mask for an Character Table filter, click the Edit Case Mask button in the Character Table filter editor. A new dialog will appear which lists all of the 2 characters in the 8-bit Mac ASCII character set. On the left side of the list is the normal character and its ASCII code. On the right side is the replacement character and its ASCII code.

Now select the character you wish to map and type the replacement character. For the example above, you would scroll to find 'A' (ASCII 65), select the list item by clicking on it, and type 'a'. The right side of the list item will change to reflect the replacement character. Now every 'A' found by the filter will be replaced by an 'a'. You would repeat this for every uppercase character in the alphabet, and then click Save to save the new mask, or Cancel to discard the new mask and retain the old one.

You can also type the ASCII code for the replacement character while holding down the control key. Or you can select a character from the Character popup menu.

Finally, there are a number of predefined case masks under the Tables popup menu. Simply select one from the menu and click Save to use it. Lowercase is one of the masks which is already provided.

Insert Text Filter

The Insert Text filter is used to insert text at or over one or more user specified locations relative to the beginning, middle, or end of the text. It can also be used to delete text from user specified locations.

Locations are specified using a Point. A Point consists of two 0-based integers, a Start and a Finish. Points are Anchored to the beginning, middle, or end of the text. Start is where the insert operation begins, and Finish is where it ends. It's important to note that integer locations are in between characters. For example:

Point Example

The location 0 falls before the letter A. The location 1 falls after A. A occupies the Point ( 0 1 ).

To specify an Insert Text filter to replace "sentence" in the above example, you would enter a point of ( 2 10 Beginning ). This would replace the characters which fall between location 2 and location 10.

It's important to note the following behavior when creating Insert Text filters:

  • If the Point is anchored to Beginning negative integers are confined to 0. So the Point ( -5 -2 Beginning ) would be seen by the filter as ( 0 0 Beginning ). 0 is at the beginning of the text, and positive integers "fall ahead" into the text. For example, to insert over the first 10 characters of the text your Point would be ( 0 10 Beginning).
  • If the Point is anchored to Middle both negative and positive integers are accepted. Negative integers "fall behind" the middle point, while positive integers "fall ahead". Note that the middle is calculated as the length of the text divided by two and rounded down to the nearest integer. So if you have 10 characters, the middle point is ( 5 5 ). 5 would be added to both the Start and the Finish of your point for the insert operation. What if you have 9 characters of text? Then the middle would be ( 4 4 ). All values are confined so that they do not exceed the length of the text in either direction. For example, to insert over the middle 10 characters of the text your Point would be ( -5 5 Middle ).
  • If the Point is anchored to the End, then only negative integers and 0 are accepted. 0 is, of course, the end of the text, with negative integers falling back into the text. Negative integers are confined so that they don't accidentally exceed the length of the text (backwards). For example, to delete the last 10 characters of the text your Point would be ( -10 0 End ).
  • In all cases Start must be equal to or less than Finish, or the Point will be skipped!
  • In all cases the Points are calculated in the context of the text being filtered. If you've selected a subset of the document text, then this is the context, not the whole document. Beginning and End would be the Beginning and End of your selection, respectively, and middle would be the middle of your selection.

Editing Insert Text Filters

The Insert Text filter editor has three fields, three radio buttons, and a scrolling list. The Insert field is where you enter the text to insert. Leave it blank for deletions.

The Start and Finish fields are where you enter your Start and Finish integers. Next to these fields are three radio buttons: Beginning, Middle, and End. Click the anchor you want to use for the Point you are entering.

Adding a Point -

  1. Enter the Start integer in the Start field.
  2. Enter the Finish integer in the Finish field.
  3. Click the anchor you want.
  4. Click the Add button.

Editing a Point -

  1. Select the Point to edit in the list. Double-click to enter its values in the above fields.
  2. Edit the Start, Finish, and Anchor values as desired.
  3. Click the Store button next to the list.

Deleting a Point -

  1. Select the Point or Points you wish to delete in the list.
  2. Click the Delete button.