PPWIZARD is a free preprocessor for HTML, REXX, Visual Basic or any text files.
[Bottom][Contents][Search][Prev]: ColorSet()[Next]: ConsoleCount()
\ -> Rexx -> Inbuilt PPWIZARD Functions -> CompareReplaceFixed()


This is an inbuilt function function provided 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 (such as ";!i!L@=,1=~HTML~;").

    This is made up of one or more of the following command sequences (in any order):

  3. The RETURN specification (such as "@<<$LinkTo Text=~@$1,2;@$3,2;~>@$5,*;").

    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 character determines the type of command (and where it ends), valid commands are:

    • $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. If you have previosly modified the (leading/trailing) whitespace then the position is relative to the updated string.

    • =/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.

    • <
      When spaces were stripped from the start of the search string, the length was saved, this restores that many spaces (to maintain your indent).

    • >
      When spaces were stripped from the end of the search string, the length was saved, this restores that many spaces. (where trailing spaces may be important).

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

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 ".

Real Life Examples (via #AutoTag)

<p>This is used in documentation for a language where each command starts on
a new line and you are providing examples in the documenattion.

<p>What this command is doing:
    <$li>The 1st #autotag parameter is the search specification and the 2nd is
         the return string.
         The string being compared/updated is supplied
         from the line being auto-tagged.
    <$li>Indicates the compare is case insensitive
    <$li>Indicates that we want to ignore leading spaces
    <$li>Checks if HTML is at the 1st position
    <$li>The return string should begin with the previously removed spaces.
    <$li>Output some specific text to start a macro reference ("<LT>$LinkTo Text=~").
    <$li>Grab the first 2 characters of the line ("ht") in whatever the
         ORIGINAL case was.
    <$li>Output some specific text to break up the HTML string ("<LT>?_<GT>").
    <$li>Grab the next 2 characters of the line ("ml") in whatever the
         ORIGINAL case was.
    <$li>Output some specific text to end a macro reference ("~<GT>").
    <$li>Grab the rest of the line
#option PUSH AtChangeType="FIXED"
    #AutoTag   ^!i!L@=,1=~HTML~^   ^@<<$LinkTo Text=~@$1,2;<?_>@$3,2;~>@$5,*;^   ;;Note don't want any following auto tagging to find "html"
#option  POP

Stupid Examples

;--- Use CompareReplaceFixed() via #AutoTag -----------
#option PUSH AtChangeType="FIXED"
    #AutoTag   '@=,1=^HTML^@=,5=+x+'          'REM CS->@$1,*;'        ;;Case sensitive compare for "HTML" then "x"
    #AutoTag   '!i@=,1=^HTML^!S@=,-1=+x+'     'REM CI->@$1,*;'        ;;Case insensitive comapre for "HTML" + sensitive compare for "x"
    #AutoTag   '!L!i@=,1=^HTML^!S@=,5=+x+'    'REM CI+spaces->@$1,*;' ;;Same as above but ignoring whitespace (leading)
#option  POP

;--- 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')^

email me  any feedback, additional information or corrections.
See this page online (look for updates)

[Top][Contents][Search][Prev]: ColorSet()[Next]: ConsoleCount()

My whole website and this manual itself was developed using PPWIZARD (free preprocessor written by Dennis Bareis)
Sunday November 05 2017 at 10:00am