PPWIZARD is a free preprocessor for HTML, REXX, Visual Basic or any text files.

CompareReplaceFixed()

This is a rexx function provided by PPWIZARD. This routine (like all PPWIZARD extensions) can be used with any operating system supported by PPWIZARD.

This function has 2 main operations as follows:

1. Compare a string against a compare specification. The return specification parameter is not passed by the caller. Returns 0 if not matched and 1 if match.

2. Compare a string against a compare specification. Either return the original string on no match or a new string as specified by the return specification.

This is quite a complicated routine and hopefully the examples will clarify things.

This routine can be very useful in #AsIs and #AutoTag processing.

The function takes 3 parameters as follows:

1. The string to be compared with.

2. The COMPARE specification. This is made up of one or more of the following command sequences (in any order):

   • @Operator,Posn=^CmpText^
     The "operator" is a rexx compare operator such as "=" or "<>".

     The "posn" is the integer position of the substring within the "COMPARE" parameter to compare with "CmpText". If the value is positive then the value refers to a position from the left else it refers to a position from the right. For example "2" indicates the second character from the left while "-2" indicates the second last character. The length of the substring is the same as the length of "CmpText".

     Any character can be used for a quote character around the "CmpText".

   • ?Operator/CmpText/
     The operator should be either "=" or "!". If "=" then we expect to find "CmpText" in the first parameter, otherwise we don't.

     Any character can be used for a quote character around the "CmpText".

   • !SubCommand
     The subcommand is one of:

     • S
       The following compares are to be case sensitive (each time this routine is called it begins in case sensitive mode).

     • i
       The following compares are to be case insensitive (you should supply upper case "CmpText" text).

     • I
       Ignore leading and trailing whitespace. Convert multiple spaces into a single space.

     • B
       Ignore leading and trailing whitespace.

     • L
       Ignore leading whitespace.

     • T
       Ignore trailing whitespace.

3. The RETURN specification. If not supplied then we are doing a simple compare operation and returning 1 on match and 0 if not.

   This parameter determines what string this routine will return. You can extract parts of the first parameter and intermix text of your own. A return command is imbedded in text and begins with the '@' character, the following byte determines the type of command, valid commands are:

   • @
     A '@@' indicates that the user wishes a single '@'. This is an escape sequence which allows the '@' character to be specified.

   • $Posn,Len;
     You wish to extract a string out of the first parameter. You need to specify its position and length. You may supply '*' for the length to indicate that the rest of the string is desired.

     If the value is positive then the value refers to a position from the left else it refers to a position from the right. For example "2" indicates the second character from the left while "-2" indicates the second last character.

   • =/RexxExpression/
     A rexx expression is executed to determine the text to be used, you have access to the first parameter of this routine in the variable "CompareString". This method should be avoided where ever possible as it is significantly slower.

     Any character can be used for a quote character around the "RexxExpression" parameter.

While some validation of the parameters is performed you should be careful with the parameters passed. If invalid parameters are passed you probably will not get the "change" you desire and I'm not ruling out a PPWIZARD trap. Validations are only performed when they will not (greatly) affect performance.

Example - Compare Specifications

1. @=,1=^HTML^
   To see if a string starts with the characters "HTML" (in that case).

2. @=,1=^HTML^!i@=,-2=^YZ^
   To see if a string starts with the characters "HTML" (in that case) and ends with the characters "YZ" (in any case).

3. !B@=,1=^HTML^!i@=,-2=^YZ^
   Same as above but leading and trailing whitespace is ignored.

4. @=,1=/HTML/!i@<>,-2=\YZ\
   To see if a string starts with the characters "HTML" (in that case) and does not end with the characters "YZ" (in any case).

5. !i?=/HTML/
   We expect the compare string to contain "HTML" (in any case).

Example - Return Specifications

1. ABCD
   Return the string "ABCD".

2. AB@@C@@D
   Return the string "AB@C@D".

3. REM @$1,*;
   Return the compare string (first parameter) preceeded by "REM ".

4. REM @$1,1;@$3,1;@$-1,1;
   Return the 1st and 3rd and last characters of the compare string preceeded by "REM ".

5. REM (@=/strip(CompareString)/)
   Return the line stripped of leading and trailing whitespace surrounded by round brackets and preceeded by "REM ".

Stupid Examples

    ;--- The following compare operation will return "1" as the compare "matches" ---
    #evaluate ^^ ^say 'Expect to see 1    ==> ' || CompareReplaceFixed('HTML', '@=,1=~HTML~')^
    
    ;--- The following compare matches and the return specification is processed ---
    #evaluate ^^ ^say 'Expect to see ASDF ==> ' || CompareReplaceFixed('HTML', '@=,1=~HTML~', 'ASDF')^
    

PPWIZARD Manual

Thursday January 17 2002 at 6:27pm