A character-replacement item is used to substitute one list of characters for another list of characters, wherever they may be found, on an individual basis. For example, to replace all instances of parentheses with brackets, you would replace the list of characters ( and ) with [ and ], respectively.
When a character-replacement item is encountered in the mapping string, it is applied to the result string as it exists at that point in time. Thus, to do character replacement on the ‘final’ result string in a certain way, you would place the character-replacement item last (right-most) in the mapping string.
Because the action of a character-replacement item is applied to the result string and not to the source string, the mapping string can contain additional column-reference operands to the right of a character-replacement item, since the data characters in the source string remain undisturbed in their original locations.
Syntax of a character-replacement item:
RC character-replacement-list [ column-reference ]
Introduces the character-replacement item
Defines a pair of character lists. The list is a quoted string set or string-pair, in the format of:
'before=after' -- in string-set notation
'before'='after' -- in string-pair notation
where before and after are strings of equal length. Each character in the result string that are found in the before string is replaced, individually, by the corresponding character in the after string. The characters are associated by position, so the first character in before is converted to the first character in after, the second character in before is converted to the second character in after, and so on.
In this way, the character-replacement-list essentially defines a character translation table.
The character-replacement-list is a quoted value after the RC code, and inside the quotes of a string set, the value is always an odd length, since the before and after strings must be the same length, and the = equal sign takes up one position. When you use a string pair, each of the two separate strings must be the same length.
By default, the casing of character-replacement-list string uses the current PROFILE CASE setting in effect. This can be overridden by a CC or CT command code, or by using a type code suffix of C, T or X on the character-replacement-list string. When CASE T mode is in effect, by any means, the before string is effectively mapped twice, once for a lower-case version of itself, and once for an upper case version. For example, the command RC'abc=123'T maps both upper and lower case versions of its before string. This operates as if the command RC'ABCabc=123123'C were used. Thus, both “A” and “a” get mapped to “1”, both “B” and “b” become “2”, and both “C” and “c” become “3”.
Special considerations when using hex strings: (1) the hex value is always treated as case-sensitive, as if in CASE C mode; (2) the = equal sign that separates the before and after parts in a string set is written as an actual = equal sign character, the same as in non-hex values. Example: RC'77=99'X.
Specifies columns in the result string to be modified. If column reference is omitted, the entire result string can potentially be modified.
It is an error if the character-replacement-list in a string set is shorter than 3 characters, is not of odd length, or does not contain = equal sign as the center character (if written as a string-set). For a string pair, the values must be the same length and cannot be null strings.
It is illegal for an = equal sign to appear in the before or after part of a string-set character-replacement-list. For example, a command like RC'<=>=[#]' is invalid.
If your before or after values need to contain = equal signs as data, the two values can be specified as a string pair, using the syntax RC'before'='after'. In this example, you could use RC'<=>'='[#]' instead of RC'<=>=[#]'. When you use this string pair format, both the left and right strings of the pair must be the same length. This form is convenient when your strings contain equal signs as data, but can be used for any string values. When you are not dealing with embedded equal signs, the shorter form will be easier to use.
Note. If you use a string pair, the syntax RC'before'='after' allows an alternate format, as RC'before':'after' using a : colon instead of an = equal sign. When you do this, the comparison of the before value, and the substitution of the after value, is done in a case-conformant manner, as if a trailing type code of T appeared on the string operand.
The character-replacement-list represents potential character substitutions that may take place. It is not necessary for any of the characters in the before string to actually exist in the result string. If none are present, it is not an error, no character replacement takes place, and the result string will remain unmodified.
The characters in the before string should be unique, but this is not checked for. In case of any duplication, the before/after relationship of the rightmost instance is used. For example, if RC'AAC=123' is specified, first a relationship of A → 1 is established, then that is discarded and A → 2 is retained; any instances of 'A' will be replaced with '2'. The RC string should perform some useful work, but this is not checked for. For example, if RC'123=123' is specified, it is valid and will be processed, but no useful change will take place; strings will be “changed” to what they already were.
If you have many characters to replace, the character-replacement-list could become quite lengthy if you were doing things that involved all the letters and numbers, for instance. Keep in mind that SPFLite allows even very long primary commands to be entered, since the command line can scroll. One way to create such commands is to use SPFLite itself to build up the command on a data line, take that data line and copy it to the clipboard, then paste it into the primary command line area. You can also define commands as SET values, and then substitute their values on the command line using the =set-name notation.
For instance, if we wanted to implement the character replacement described above (changing parentheses into brackets), you would use a character-replacement item like
Note that the quoted string after RC is of odd length (5) as there are two characters ( ) before the = sign and two characters [ ] after the = sign, with the sign exactly in the middle.
A complete mapping string that used this item would look like:
or with the 1+ implied by auto-copy we can shorten this to:
There is no provision for a character-replacement item in an RC command to make individual characters shorter or longer, by deleting characters or replacing them with multi-character units. However, you could achieve the effect of that by doing it in two steps, where the first step would be to use a mapping string with a character replacement that substituted the desired characters with some special codes, and the second step would be to go back and replace the special codes with other values or with zero-length strings to delete them. You can also use the Delete Character Values command DC to remove specific kinds of characters from the result string, and you can use the String Replacement commands RA, RL and RR to accomplish string deletion when the second string operand of RA, RL or RR is omitted.
Suppose you wanted to find all 5-letter words, and then change all occurrences of A, B and C with lower case versions, but any instance of X you wanted removed. You could do the following, where the second step utilizes the Command Chaining technique. Here, instances of X are changed to the special character ^ which is then removed in the second step, which only applies that change to the lines that were altered in the first step by using the :ZF notation for command chaining.
CHANGE P'@@@@@' ALL WORD M"RC`ABCX=abc^`"
CHANGE '^' '' ALL :ZF
Likewise, if you wanted all instances of X to be expanded, you could use the same technique, only replacing the ^ code with some longer value.
Using the DC command code, you could remove the X in one step, as follows. Assuming that X is a unique value, so that you don’t have to change it to some intermediate form first (like ^ above), the command would be:
CHANGE P'@@@@@' ALL WORD M"RC`ABC=abc` DC`X`"
Created with the Personal Edition of HelpNDoc: Generate EPub eBooks with ease