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

Macro Tranformations

The subject of macros is reasonably complex (but well worth learning) please ensure you have at least read the macro introduction before reading this section.

PPWIZARD provides a mechanism to hold macro data in one format but transform this data when tranformed, this removes the need to hold the same data in multiple formats.

Transformation commands all start with $$ and apply to:

1. Macro Replacement
   Macros parameter where they were supplied on a reference without a value that and begin with '$$' have special meaning, they are commands to PPWIZARD.

   The command applies to the complete contents of a macro before any replacement of parameters has occurred.

2. Macro Parameter Replacement
   

Restriction

Note that most of the above '$$' commands work directly on the contents of the macro (after parameter substitution). If the contents (or parameters) contained macros then you may not get the desired affect.

The Available $$ Tranformations

In the following list "Bold $$ commands" apply to both macro and parameter replacement, "Dark Green $$ commands" only apply to macro replacement and "Magenta $$ commands" only apply to macro parameter replacement:

• $$ADDCOMMA
  The parameter will be formatted using AddCommasToDecimalNumber().

• $$ASIS
  The value of the macro is substituted EXACTLY as it is, there is no substitution of macro parameters etc. Note that this will not prevent any macros the contents refers to from being expanded.

• $$AQ
  You use this command to surround your parameters data with quotes. The quotes used are double or single quotes, if neither can be used ppwizard will go through a whole list of alternative 'quote' characters, if none of these can be used then ppwizard will terminate.

• $$DSQ
  You use this command to surround your parameters data with quotes. The quotes used are double or single quotes, if neither can be used ppwizard will terminate.

• $$HTMLQ
  The parameter is all or part of a string surrounded by double quotes, any double quotes that exist in the data should be converted to """.

• $$IGNORE
  The parameter will be "dropped" (a empty string will be substituted). The main reason you might want to do this is to prevent a '"{$?}"' type parameter from including this parameter.

• $$LOWER
  The parameter will be converted to lower case.

• $$RX'
  This can be very useful if you wish to use the value in a rexx string which is surrounded by single quotes. It makes sure that the value will not break any rexx rules. Note that there is also a '$$RX"' variant for use in double quoted rexx literals.

• $$RXEXEC
  The value is taken to be rexx code to be executed. The value to be substituted should be returned in the "RXEXEC" variable.

• $$SPCPLUS
  A space is added before the start of the value if it is non-empty.

• $$SQX2
  The value is modified such that all single quote characters are doubled up. This can be very useful if you wish to use the value in a rexx string which is surrounded by single quotes as rexx will in this situation treat the two single quotes as a single single quote that does not terminate the string.

  It should be noted that under regina there is a limitation that a long string could break so I now recommend the use of "$$RX'" instead.

• $$PASSDSQ
  The parameter will be quoted as per the $$DSQ command and the parameter name followed by the equal sign will be added to the start. This is handy when one macro uses another and a parameter needs to be passed to the inner macro (parameter has same name in both macros).

• $$PASSAQ
  The parameter will be quoted as per the $$AQ command and the parameter name followed by the equal sign will be added to the start. This is handy when one macro uses another and a parameter needs to be passed to the inner macro (parameter has same name in both macros).

• $$SDQ
  You use this command to surround your parameters data with quotes. The quotes used are single or double quotes, if neither can be used ppwizard will terminate.

• $$UPPER
  The parameter will be converted to upper case.

• $$?
  If the '$$' command is otherwise unknown you can create your own formatting (ie you can not redefine an existing format).

  To define a format you need to define a macro which contains the rexx formatting code. The macro must have the name of "REXX_$$" followed by the name of your command, for example to use the command "$$TO_C_STRING" you would create "REXX_$$TO_C_STRING". The value to be formatted is in the "TheValue" variable.

  If required you can also determine the source of the value (macro or parameter name) as it is stored in "TheName" (for case insensitive items it is in upper case). For macro parameters only the name of the macro being expanded is in the "TheMacro" variable.

Note that the quoting routines above do more than just make your code "prettier", without using these commands you have to decide on a quote character yourself and then a parameters value must never contain this character. These special commands won't solve all quoting issues (remember parameter processed left to right - imbedded parameters are not processed first) however they will make life much easier.

EXAMPLE - $$ Macro Replacement

If you haven't a clue what this is about, cut and paste the following and try it:

    ;--- Need to have access to mixed, lower and upper case values ---
    #define  MixedCase  Dennis Was Here
    ;#define LowerCase  dennis was here
    ;#define UpperCase  DENNIS WAS HERE
    
    ;--- Output the 3 formats ---
    Mixed case = <$MixedCase>
    Lower case = <$MixedCase $$lower>
    Upper case = <$MixedCase $$upper>
    

A simple example where if the "$$SQX2" command were not used that ppwizard would fail (in this case with variable "A" unknown trap):

    #define TheMacro   The value 'A' is in quotes
    #evaluate "" "call Summary 'VALUE', '<$TheMacro $$SQx2>'"
    

Another example where we wish to add commas to a rexx variable:

    Value = <??ARexxVariable $$ADDCOMMA>
    

Here is another example which may be useful if you were creating 'C' code and maybe other situations:

    ;--- Define directory (non 'C' format as used elsewhere) ---
    #define DIR_NAME     C:\DB\PROJECTS\FRED
    
    ;--- Define a macro to transform a string into 'C' format ---
    #DefineRexx REXX_$$TO_C_STRING
                TheValue = ReplaceString(TheValue, '\',     '\\');
                TheValue = ReplaceString(TheValue, '"',     '\"');
                TheValue = ReplaceString(TheValue, d2c(10), '\n');
                TheValue = ReplaceString(TheValue, d2c(13), '\r');
                TheValue = ReplaceString(TheValue, d2c(7),  '\b');
    #DefineRexx
    
    ;--- Use our defined transformation ---
    StringC = "<$DIR_NAME $$TO_C_STRING>";
    

EXAMPLE - $$ Parameter Replacement

Lets make sure that parameters 2 and 3 in the following macro get translated to upper case:

    ;--- Define macro ---------
    #define  SimpleTest P1={$parm1}, P2={$parm2="parm1_default" $$upper}, P3={$parm3 $$upper $$DSQ}
    
    ;--- Expand macro ---------
    <$SimpleTest Parm1='value1' Parm2='value2' Parm3='value3'>
    

PPWIZARD Manual

Thursday January 17 2002 at 6:27pm