WinPTE.com

• Overview.
• Screenshot of code fragment selection dialog.
• Sample result and code fragment file.
• Detailed Analysis of the sample code fragment file
• Macro Variables Reference describes available macro variables that are expanded to text during template insertion into a file.
• Code Fragment File Format describes the general format of code fragment template files.
• Code Fragment Reference describes the available code fragment directives and their options.
• New Vector Parameters and Iterative Code Fragment Expansion describes how to create code fragments that expand for each value of parameter vector.

Overview

WinPTE code templates got a major overhaul. Previously code templates had a few substitution "macro names" like time, date, file name, author (creator) and copyright holder. They were an all or nothing proposition. Either all the text of the template would get inserted into the file or none, option selected by not inserting the template.

Now they have code fragments that can be independently selected and inserted into a file. Each fragment defines its list of dependencies, its placement preference (top, bottom, cursor, search string from top, search string from bottom, place before/after another fragment), substitution parameters, a list of satellite fragments that are also to be included (not dependent on them, but they travel together like opening statements at top and closing statements at the bottom) and also exclusion condition - default exclusion is finding the first line of the code fragment already in the file (i.e. was already included).

Robust placement conditions allow the template to be invoked multiple times and only adding some or one fragment at a time. This allows the user of the template to pick and choose what they want to include and also to change their mind and add from the menu at a later date.

The inserted code still has the option of expanding the old WinPTE template macro variables (turned on by default) this allows the inclusion of configured author, copyright holder, file name, date, etc. Additionally each fragment can define any number of substitution parameters that the user of the template can fill in using the same dialog where they choose the code fragments to insert.

New Text substitution parameters are saved on a per code template and destination file basis. Launching the same code template on a file will recall the last entered parameters for this code template in this file. Additionally, it is possible to make several code templates share their saved parameter values so that you can create a group of code templates that will re-use each others saved parameters so all templates in the group will pickup the last used values for the parameters for the file. This is more practical for sharing global parameters since local parameters are saved on a per code fragment basis. Sharing the local parameters is only possible if for code fragments that have identical ID's.

Details

The input dialog is a property grid identical to the Options Pane, with the toolbar and the option group tree hidden. Each code fragment is displayed as a caption and a boolean value (empty for don't include, and Add if it is to be inserted in the file). Double clicking on the items toggles Add flag.

Code templates are located in the Templates subdirectory under WinPTE installation directory. Currently there are three types of templates: banner comment, file header and function header. All templates are searched based on the file name provided by the key used to insert the template and the extension of the file. If an template with a matching extension is not found then a search is made for templates that match every extension listed in the language template for the current file. This allows sharing of the same template for all file extensions of the language or tailoring a template for each extension.

Starting with release 3.00.445 the Custom sub-directory of WinPTE will be searched before the Templates subdirectory. You should place your customized versions of the files in the Custom subdirectory.

Banner comment templates are named Banner.xxx where xxx stands for the various supported source code extensions. These are intended to be inserted when you want to make a location in the file stand out. Ctrl+K, b (two key combination) will insert the banner comment above the current cursor line.

File header templates are named FileHead.xxx and are designed to insert a file comment block at the top and initialize the contents with some skeleton features. It is these templates that are an ideal candidate for code fragment inclusion. Inserted via Ctrl+K, f (two key combination). Currently only the FileHead.h template has code fragments defined the rest have not been updated yet and will simply insert the template contents into the file.

Function header templates are named FuncHead.xxx and are designed to create a block comment for functions and methods of the language. Insert using the Ctrl+K, h (two key combination). Individual templates provide varying degrees of functionality at the top end parsing out the function arguments and creating entries in the comment block for each argument so that you only have to provide the description. On the low end of support they simply insert the function header into the code. C/C++ and VB/Lotus Script language templates provide the top end support. The rest of the language templates can be enhanced with this support if there is a demand for this functionality.

I will be adding a macro that will either list available code fragment templates that are compatible with the current file or let you browse for the file manually. It is also possible to add items in the project tree that will invoke template insertion when double clicked.

Converting Code Templates to Code Fragment Templates

To convert old style templates to the code fragment format add two lines at the top of the file (prefixed with the language specific single line comment prefix). For VB it is ' (single quote), C/C++ //, ProvideX !, etc. Leaving no spaces between the comment char and the directive (I will use a * for the comment character(s) in the example substitute appropriate values in your files):

*%$OPTION

*%FORMAT

You can also add the optional termination line at the bottom of the file:

*%$END

All text between the *%$FORMAT and *%END will be added without questions or confirmations.

Code Fragment Selection Dialog

StructureAlignment and Module are substitution parameters. Parameters can have default values and are displayed as child items of their Code Fragment. The value displayed will be used to replace all occurrences of the parameter reference in the code fragment.

Sample Destination File

The file below is an empty file initialized with the sample code fragment template which allows inclusion of any of the 4 elements in any combination: Header comment, #ifdef include guards, include guard using the MSC #pragma once directive, and structure alignment push/pop pragma. The #ifdef include guards and the alignment pragma consist of two satellite fragments each because they need to have different placements. That way adding the fragment after some code is inserted into the file will still result in the proper placement of each fragment.

After which follows a listing of the sample code fragment file with detailed analysis of every fragment and its directives. The analysis is of the code fragment file directives and their operation and not of the C/C++ language features included in the code fragments. So it is significant event if C/C++ language is not applicable to your work environment.

 Line 
       
    1 
    2 
    3 
    4 
    5 
    6 
    7 
    8 
    9 
   10 
   11 
   12 
   13 
   14 
   15 
   16 
   17 
   18 
   19 
   20 
   21 
   22 
   23 
   24 
   25 
   26 
   27 
   28 

// File: test.h, lines 1 to 28
 
/*$FILE************************************************************************
 
      Module             WinPTE Sample
 
      File               test.h
 
      Contents           
 
      Created            Vladimir Schneider
                         Mar 9, 2005
 
      Copyright (c) 2005 Vladimir Schneider, All Rights Reserved
 
******X******************X************************X************************X$*/
 
#ifndef __test_h_ 
#define __test_h_ 
 
#if _MSC_VER >= 1000 
#pragma once 
#endif // _MSC_VER >= 1000
 
#pragma pack(push, 4)
 
#pragma pack(pop)
 
#endif   // __test_h_
  

Code Fragment File Sample

Sample is a C/C++ Header File template. The features of this template are independed of the language and can by applied to any code fragment template file. Features of this template:

• Optional header comment with automatic author information, copyright, date, module substitution parameter.
• Optional include guards with automatic preprocessor symbol generation based on the file name.
• Optional MSC #pragma once with MSC version test.
• Optional #pragma push()/pop() with alignment substitution parameter with a default value.
• Default setting is to insert all elements.
• None of the elements will be inserted twice.
• Multiple invocations are supported and elements not yet present in the file will be available for insertion.
• No matter what elements are selected and regardless of how many invocations are used to insert them and the order of the insertion, the placement always results in a consistent, predictable and operationally correct code layout.

The file FileHead.h is located in the Templates subdirectory WinPTE installation.

 Line 
       
    1 
    2 
    3 
    4 
    5 
    6 
    7 
    8 
    9 
   10 
   11 
   12 
   13 
   14 
   15 
   16 
   17 
   18 
   19 
   20 
   21 
   22 
   23 
   24 
   25 
   26 
   27 
   28 
   29 
   30 
   31 
   32 
   33 
   34 
   35 
   36 
   37 
   38 
   39 
   40 
   41 
   42 
   43 
   44 
   45 
   46 
   47 
   48 
   49 
   50 
   51 
   52 
   53 
   54 
   55 
   56 
   57 
   58 
   59 
   60 
   61 
   62 
   63 

// File: FileHead.h, lines 1 to 63
 
//%$TITLE=C/C++ Include File Header
//%$SORT=No
//%$EXCLUDE(DUPLICATES)
//%$INCLUDE
 
//%$OPTION(FILE_HEADER)=File Header Comment
//%$PLACEMENT(TOP)
//%$PARAM(Module)
/*$FILE************************************************************************
 
      Module             %$(PARAM:Module)
 
      File               %$FILE
 
      Contents           %$DESC
 
      Created            %$AUTH
                         %$DATE
 
      Copyright (c) %$YEAR %$COPYRIGHT, All Rights Reserved
 
******X******************X************************X************************X$*/
//%$END
 
//%$OPTION(TOP_GUARD)=Ifdef Include Guard
//%$PLACEMENT(TOP DOWN AFTER)=FILE_HEADER
//%$PLACEMENT(TOP DOWN BEFORE)=PRAGMA_ONCE PRAGMA_PUSH
//%$PLACEMENT(TOP)
//%$INCLUDES=BOTTOM_GUARD
#ifndef %$NDEF 
#define %$NDEF 
//%$END
 
//%$OPTION(PRAGMA_ONCE)=MSC_VER based #pragma once guard
//%$PLACEMENT(TOP DOWN AFTER)=TOP_GUARD FILE_HEADER
//%$PLACEMENT(TOP)
#if _MSC_VER >= 1000 
#pragma once 
#endif // _MSC_VER >= 1000
//%$END
 
//%$OPTION(PRAGMA_PUSH)=pack push pragma
//%$PLACEMENT(TOP DOWN AFTER)=PRAGMA_ONCE TOP_GUARD FILE_HEADER
//%$PLACEMENT(TOP)
//%$INCLUDES=PRAGMA_POP
//%$PARAM(StuctureAlignment)=4
//%$PARAMDESC(StuctureAlignment)=Number of Bytes on which to allign structures defined in this file
//%$EXCLUDE=#pragma pack(push
#pragma pack(push, %$(PARAM:StuctureAlignment))
//%$END
 
//%$OPTION(PRAGMA_POP)
//%$PLACEMENT(BOTTOM UP BEFORE)=BOTTOM_GUARD
//%$PLACEMENT(BOTTOM)
#pragma pack(pop)
//%$END
 
//%$OPTION(BOTTOM_GUARD)
//%$PLACEMENT(BOTTOM)
//%$EXCLUDE(BOTTOM UP DUPLICATE)
#endif   // %$NDEF
//%$END
  

Analyzing the Sample

The analysis is of the directives and their effects on how the template will behave when you insert it into a file. The fact that it is a C/C++ header file template is of no consequence to the discussion and not addressed by the following analysis.

Header Directives

Most code fragment directives can be used in the header part of the file and will provide or override defaults for these properties for all code fragments in the file that do not define their own value for the property

 Line 
       
    1 
    2 
    3 
    4 

// File: FileHead.h, lines 1 to 4
 
//%$TITLE=C/C++ Include File Header
//%$SORT=No
//%$EXCLUDE(DUPLICATES)
//%$INCLUDE 

%$TITLE

defines the title of the dialog box that is displayed.

%$SORT=No

specifies that code fragments in the dialog should be shown in order of definition in this file. %$NOSORT could have been used instead with or without =Yes

%$EXCLUDE(DUPLICATES)

provides the default exclusion criteria for code fragments. Any fragment not defining its own will get this definition as a default. DUPLICATES means search for the first line of the code fragment body in the file. Default search start is TOP of file, and search direction is DOWN. The full specification without relying on the defaults provided by the parser would be %$EXCLUDE(TOP DOWN 1) the 1 means first line of the body, 2 would be the second line, etc.

%$INCLUDE

again, provides the default for fragments. By default fragments start out with no "Add" option and you must select them for inclusion in the file. This allows you to change the default. Standard code fragments should be marked for inclusion so that they are selected by default. Could have been specified with %$INCLUDE=Y or =Yes.

Code fragments that have no caption and no fragment ID are assumed to be included by default since there is no other way for them to be included. The lack of caption means they won't be displayed in the dialog box and the lack of ID means they can't be listed in the INCLUDES or REQUIRES dependencies list of other fragments. So they are assumed to always be included, provided their EXCLUDE criteria is not satisfied.

FILE_HEADER Code Fragment

 Line 
       
    6 
    7 
    8 
    9 
   10 
   11 
   12 
   13 
   14 
   15 
   16 
   17 
   18 
   19 
   20 
   21 
   22 
   23 

// File: FileHead.h, lines 6 to 23
 
//%$OPTION(FILE_HEADER)=File Header Comment
//%$PLACEMENT(TOP)
//%$PARAM(Module)
/*$FILE************************************************************************
 
      Module             %$(PARAM:Module)
 
      File               %$FILE
 
      Contents           %$DESC  
 
      Created            %$AUTH
                         %$DATE
 
      Copyright (c) %$YEAR %$COPYRIGHT, All Rights Reserved
 
******X******************X************************X************************X$*/
//%$END  

%$OPTION(FILE_HEADER)=File Header Comment

This marks the start of the code fragment, assigns the FILE_HEADER id to it and the "File Header Comment" caption. The caption will be used for identifying the fragment in the dialog box. Additionally any text after / or - is not shown in the item's caption. The full caption is shown in the description section when the item is selected. So you can add explanations and hints after / or - in the caption.

%$PLACEMENT(TOP)

Specifies that this fragment is to be placed at the TOP of file. Without any other parameters it will always insert it at the TOP. If more than one code fragment in the file specifies TOP placement then the first one will be placed at the TOP, next one will be placed right after it, and so on. To make the code fragment insertion positions to be independent of order of insertions and/or combination of insertions you should always define a placement order for the fragments relative to each other, and as a fallback position use TOP. That way no matter what order the selections are made they will always insert in the same relative order. This is demonstrated by the code fragments that follow.

%$PARAM(Module)

Defines a text substitution parameter with parameter ID of Module with no default value. Default value could be provided by adding = followed by text. The parameter will be displayed as a string item with the caption of "Module" under the code fragment item in the dialog box. Any number of parameters can be added. In the current implementation the display order is arbitrary and does not follow the order of declaration. Additionally, you can add %$PARAMDESC(Module)=Text to provide descriptive text for the item when it is selected in the dialog box.

/*$FILE

Is added as a marker for the file header comment to distinguish it from other multi-line comments that the user can add to the file. Making this comment easily distinguishable allows the exclusion criteria to use a search of the file the first line of the body (DUPLICATES or DUPLICATE is equivalent to 1 for first line). If found the fragment will not be included because it is assumed that it was already present in the file.

%$(PARAM:Module)

Marks the place to substitute the user entered (or default) value for the parameter with ID of Module.

%$FILE

Macro Variable that expands to the file name and extension of the file into which the template is being inserted.

%$DESC

Marks the location of where to place the cursor after inserting the template's code fragments. Lines containing %$DESC will be truncated right before the % character, any text that follows is therefore deleted. The first %$DESC encountered will be used as the cursor position. The rest of the lines will be truncated before the % character and ignored.

%$AUTH

Macro Variable that expands to the string configured for the Author property. To change this configuration go to Tools/Set Author Copyright Holder...

%$DATE

Macro Variable Expands to current system date, format 'MMM D, YYYY' where MMM is the three letter month, D is the day of month and YYYY is the four digit year.

%$COPYRIGHT

Macro Variable that expands to the string configured for the Copyright Holder property. To change this configuration go to Tools/Set Author Copyright Holder...

%$END

Marks the end of the code fragment definition.

TOP_GUARD Code Fragment

This fragment is intended to go at the top of the file, right after the header comment above if it is present. The standard %$OPTION and %$END were already covered in the above discussion and will not be repeated here.

 Line 
       
   25 
   26 
   27 
   28 
   29 
   30 
   31 
   32 

// File: FileHead.h, lines 25 to 32
 
//%$OPTION(TOP_GUARD)=Ifdef Include Guard
//%$PLACEMENT(TOP DOWN AFTER)=FILE_HEADER
//%$PLACEMENT(TOP DOWN BEFORE)=PRAGMA_ONCE PRAGMA_PUSH
//%$PLACEMENT(TOP)
//%$INCLUDES=BOTTOM_GUARD
#ifndef %$NDEF 
#define %$NDEF 
//%$END 

%$OPTION(TOP_GUARD)

Defines the code fragment ID as TOP_GUARD. For the rest see FILE_HEADER fragment.

%$PLACEMENT(TOP DOWN AFTER)=FILE_HEADER

Defines a placement criteria of search from TOP of file, in the DOWN direction, place this code fragment AFTER the code fragment with ID of FILE_HEADER. If more than one ID is listed the fragments will be searched in the order specified and placement will be determined by the first one found. So order is significant.

%$PLACEMENT(TOP)

Defines the placement to use if none of the "Search" based placements have resulted in a match. What is significant in this fragment is that it will go after the FILE_HEADER if it was inserted or at the top of file. Which means that its order is not dependent on how or when the insertion is made.

%$INCLUDES=BOTTOM_GUARD

Defines that adding this code fragment will automatically add a fragment with ID of BOTTOM_GUARD. The text after the = is interpreted as a space delimited list of code fragment ID's that are to be included. More than one %$INCLUDES directive can be used and all IDs are accumulated. Listing the same fragment more than once is silently ignored.

%$NDEF

Macro Variable see Macro Variables table below.

%$END

End of fragment definition

PRAGMA_ONCE Code Fragment

What is significant in this fragment is that we want to preserve it placement in the file to be after the TOP_GUARD fragment and before the PRAGMA_PUSH fragment.

 Line 
       
   34 
   35 
   36 
   37 
   38 
   39 
   40 

// File: FileHead.h, lines 34 to 40
 
//%$OPTION(PRAGMA_ONCE)=MSC_VER based #pragma once guard
//%$PLACEMENT(TOP DOWN AFTER)=TOP_GUARD FILE_HEADER
//%$PLACEMENT(TOP)
#if _MSC_VER >= 1000 
#pragma once 
#endif // _MSC_VER >= 1000
//%$END 

%$OPTION(PRAGMA_ONCE)

Defines the code fragment ID as PRAGMA_ONCE. For the rest see FILE_HEADER fragment.

%$PLACEMENT(TOP DOWN AFTER)=TOP_GUARD FILE_HEADER

Defines a placement criteria of search from TOP of file, in the DOWN direction, place this code fragment AFTER the code fragment with ID of TOP_GUARD and failing that after one with ID of FILE_HEADER.

%$PLACEMENT(TOP)

Defines the placement to use if none of the "Search" based placements have resulted in a match. What is significant in this fragment is that it will go after the TOP_GUARD fragment or the FILE_HEADER if it these were inserted or at the top of file. Which means that its order is not dependent on how or when the insertion(s) are made.

%$END

End of fragment definition

PRAGMA_PUSH Code Fragment

Similar to above fragments with the addition of a substitution parameter.

Line 42 43 44 45 46 47 48 49 50

// File: FileHead.h, lines 42 to 50 //%$OPTION(PRAGMA_PUSH)=pack push pragma //%$PLACEMENT(TOP DOWN AFTER)=PRAGMA_ONCE TOP_GUARD FILE_HEADER //%$PLACEMENT(TOP) //%$INCLUDES=PRAGMA_POP //%$PARAM(StuctureAlignment)=4 //%$PARAMDESC(StuctureAlignment)=Number of Bytes on which to allign structures defined in this file //%$EXCLUDE=#pragma pack(push #pragma pack(push, %$(PARAM:StuctureAlignment)) //%$END

%$OPTION(PRAGMA_PUSH)

Defines the code fragment ID as PRAGMA_PUSH. For the rest see FILE_HEADER fragment.

%$PLACEMENT(TOP DOWN AFTER)=PRAGMA_ONCE TOP_GUARD FILE_HEADER

Defines a placement criteria of search from TOP of file, in the DOWN direction, place this code fragment AFTER the code fragment with ID of PRAGMA_ONCE, or TOP_GUARD and failing that after one with ID of FILE_HEADER.

%$PLACEMENT(TOP)

Defines the placement to use if none of the "Search" based placements have resulted in a match. What is significant in this fragment is that it will go after the TOP_GUARD fragment or the FILE_HEADER if it these were inserted or at the top of file. Which means that its order is not dependent on how or when the insertion(s) are made.

%$PARAM(StructureAlignment)=4

Defines a text substitution parameter with parameter ID of StructureAlignment with default value of 4. The parameter will be displayed as a string item with the caption of "StructureAlignment" under the code fragment item in the dialog box. Any number of parameters can be added. In the current implementation the display order is arbitrary and does not follow the order of declaration.

%$PARAMDESC(StructureAlignment)=...

Defines the text to use for the description section of the dialog box when the parameter item is selected.

%$EXCLUDE=#pragma pack(push

Defines a search only exclusion for a line that starts with the text '#pragma pack(push' the default exclusion of DUPLICATES defined in the header directives would use the first line of the body which includes a text substitution parameter. This would fail the exclusion condition if this fragment was already inserted but with a different parameter value. So the "manual" search string is used here instead so this fragment will be excluded if a line matching the criteria is found in the file.

%$END

End of fragment definition

PRAGMA_POP Code Fragment

Significance of this fragment is that it is used as "closing" text for the PRAGMA_PUSH fragment and must come after it. However, any code in the file should be included between the PRAGMA_PUSH and PRAGMA_POP fragments. Also, this fragment is not user selectable and automatically added if the PRAGMA_PUSH fragment is added.

 Line 
       
   52 
   53 
   54 
   55 
   56 

// File: FileHead.h, lines 52 to 56
 
//%$OPTION(PRAGMA_POP)
//%$PLACEMENT(BOTTOM UP BEFORE)=BOTTOM_GUARD
//%$PLACEMENT(BOTTOM)
#pragma pack(pop)
//%$END 

%$OPTION(PRAGMA_POP)

Defines the code fragment ID as PRAGMA_POP. For the rest see FILE_HEADER fragment.

%$PLACEMENT(BOTTOM UP BEFORE)=BOTTOM_GUARD

Defines a placement criteria of search from BOTTOM of file, in the UP direction, place this code fragment BEFORE the code fragment with ID of BOTTOM_GUARD.

%$PLACEMENT(BOTTOM)

Defines the placement to use if none of the "Search" based placements have resulted in a match. What is significant in this fragment is that it will go before the BOTTOM_GUARD fragment or BOTTOM of file if one is not found. Which means that its order is not dependent on how or when the insertion(s) are made and it will be inserted after any text that already exists in the file.

%$END

End of fragment definition

BOTTOM_GUARD Code Fragment

Significance of this fragment is that it is used as "closing" text for the TOP_GUARD fragment and all code in the file must be enclosed between these two code fragments, so it must be the last element in the file.

 Line 
       
   58 
   59 
   60 
   61 
   62 

// File: FileHead.h, lines 58 to 62
 
//%$OPTION(BOTTOM_GUARD)
//%$PLACEMENT(BOTTOM)
//%$EXCLUDE(BOTTOM UP DUPLICATE)
#endif   // %$NDEF
//%$END 

%$OPTION(BOTTOM_GUARD)

Defines the code fragment ID as BOTTOM_GUARD. For the rest see FILE_HEADER fragment.

%$PLACEMENT(BOTTOM)

Defines the placement to use if none of the "Search" based placements have resulted in a match. What is significant in this fragment is that it will always be inserted at the bottom of the file

%$EXCLUDE(BOTTOM UP DUPLICATE)

Defines the exclusion criteria to be a BOTTOM, UP search for the first line of the fragments body in the file.

%$NDEF

Macro Expansion Variable used to distinguish this #endif statement from others that may be present in the file.

%$END

End of fragment definition

Vector Parameters and Iterative Code Fragment Expansion

The use of vector parameters or indexed parameters allows creating code fragments that will iterate over the individual values of the parameter resulting in multiple copies of the code fragment each with a different value of the parameter being used.

The declaration of a vector parameter includes the maximum upper bound of the index in [ ]. For example $%PARAM(Vect[10]) will declare Vect as a 10 parameter vector. Each of these values is editable as a separate parameter value in the code fragment selection dialog. Lowest index value is 1 and the highest is currently limited to 50.

In the body of the code fragment you can refer to any of the individual values of the vector with the array index notation: %$(PARAM:Vect[2]) which will expand to the value at index 2.

However, you can also reference the vector parameter without an index, for example %$(PARAM:Vect) which will result in "vector" expansion of the code fragment. What this means is that the code fragment will be inserted once for each value of the parameter starting with value at index 1 and progressing to the last value.

This allows you to create any number of parameter "slots" that are to be filled in when the template is inserted into the file. For example, code that creates a property for a class can use a Vector for the properly name and this will allow insertion of multiple properties with a single invocation of the template.

If you have followed the discussion so far then you are ready to tackle code fragments with multiple vector references in their code. These are fragments that refer to two or more, separate vector parameters in their body text without using an index.

Multiple vector references have two modes of iteration: parallel and permuted. Parallel will iterate over all the values incrementing the index for all vectors at the same time. So if we take two parameter vectors A { A1, A2, A3 } and B { B1, B2 } then parallel iteration will result in the following value sets:

• A1, B1
• A2, B2
• A3, -

For now we will ignore the missing value for B in the third set. We will assume that A is declared before B, this determines which vector's index is the inner index, and will be incremented more frequently. The parameter declared last is the innermost and its index is incremented the fastest. This means that global parameters' index will always increment less frequently than any local parameter's index. Permuted iteration will result in the following sets of values:

• A1, B1
• A1, B2
• A2, B1
• A2, B2
• A3, B1
• A3, B2

Now we come back to the missing value issue. If the %$VECTOREMPTY directive is false (as it is by default) then all iterations with an empty value are discarded. This applies equally to parallel and permuted iteration modes. If it is set to true then all iterations will generate code resulting in no text for the missing parameter values.

All non-vector references are expanded for every iteration even if they contain empty values. It is perfectly valid to mix indexed and vector references to the same vector parameter in the same code fragment. Can't think of a good use for it at the moment, but the functionality is there should you find it applicable to your use case.

Vector expansion is Parallel by default, and can be changed with the %$PERMUTE boolean directive. Setting to Yes will result in permuted iteration for the code fragment. The directive has no effect if the fragment's body text does not have any vector references (non-indexed vector parameters.)

Use this sample template that will allow you to see the generated code to get more comfortable with this functionality. You can change the %$PERMUTE and %$VECTOREMPTY properties and see the difference in the results. The template automatically fills in default values for the vector parameters with the index suffix to allow easier experimentation. It has both global and local vector parameters and references 3 vector parameters in it body text.

To use it,

• create a new file with the name FileHead.xxx where .xxx is any extension you want. There is no need to save the file, the template expansion macros will use the file loaded into WinPTE before resorting to a disk search.
• Copy the template text below into the file
• Create another new file with the same extension as the template
• Hit Ctrl+K, f (two key combination) and you will get the code fragment selection dialog. All code fragments are automatically added the only thing you can change in the dialog is the values of the parameters.

Sample Iterative Template Text

 Line 
       
    1 
    2 
    3 
    4 
    5 
    6 
    7 
    8 
    9 
   10 
   11 
   12 
   13 
   14 
   15 
   16 
   17 
   18 
   19 
   20 
   21 
   22 
   23 
   24 

! File: testloop.pvo, lines 1 to 24
 
!%$TITLE=Vector Expansion Sample
!%$SORT=No
!%$EXCLUDE(NONE)
!%$INCLUDE
!%$NOBLANKSPACER
!%$PARAM(Gv[3])=Gv%$(ITER)
!%$PARAMDESC(Gv[3])=Global Vector Param
!%$PARAM(Gnv)=Gnv
!%$PARAMDESC(Gnv)=Global Non Vector Param
 
!%$OPTION=Vector Expansion Fragment
!%$DISABLED
!%$PLACEMENT(TOP)
!%$PARAM(Lv[3])=Lv%$(ITER)
!%$PARAMDESC(Lv)=This is a Vector Param
!%$PARAM(Mv[2])=Mv%$(ITER)
!%$PARAMDESC(Mv)=This is a Vector Param2
!%$PARAM(Lnv)=Lnv
!%$PARAMDESC(Lnv)=This is a Non Vector Param
!%$PERMUTE=No
!%$VECTOREMPTY=No
Testing Lv=%$(PARAM:Lv) Mv=%$(PARAM:Mv) Gv=%$(PARAM:Gv) 
Lnv=%$(PARAM:Lnv) Gnv=%$(PARAM:Gnv) Lv[2]=%$(PARAM:Lv[2])
!%$END 

Macro Variables

These will be expanded wherever they appear in the code fragment body during code fragment insertion. They can also be placed in default values for substitution parameters in which case their expanded values will be editable in the dialog box. Expansion is turned on by default and can be turned on/off at the header level or individual code fragment level. Code fragment expansion setting also controls the expansion of macro variables for the fragment's default parameter values.

The file reference in the table refers to the name of the file being inserted into and not the code fragment template file.

NOTE: All date macro values, %$GUID and %$NOSAVE, when used in the default text for a parameter will prevent the parameter value from being saved since these values are considered to be "ephemeral".

File Format

Code Fragment files are intended to be tailored to a specific programming language or language template. They contain plain text with code fragment directives which direct the parser and provide hints on where the code fragment should be inserted in the file.

Each directive starts with the single line comment prefix and %$ character sequence without any spaces in between. Directives are all uppercase. This is intentional and designed to minimize potential conflicts between text in comments and the code fragment directives.

All directives have the following format, where * is the language specific single line comment prefix:

*%$DIRECTIVE(PARAMLIST)=Text

The directive name consists of the character set [A-Z0-9_].,

Parameter list consists of space separated parameters where each Parameter consists of characters in the set [-A-Za-z0-9_]. The last parameter can also have a numeric value enclosed in square brackets.

Text is anything to the end of line. Not all directives make use of either the parameter or the text part. If PARAMLIST is not specified then the () can be omitted. Similarly if Text is not used the = can be omitted.

A common error is to include a space between the comment and the %$ of the directive. To help visually isolate these errors all default templates have a colorization key word for this combination defined to the error text style.

Header Directives

The header defines the title of the dialog box and default values for some code fragment properties. These default properties can be overridden at the code fragment level and are only used in the event the code fragment does not define the property.

Code Fragment Directives

Each code fragment begins with %$OPTION(FRAGMENT_ID)=Caption - Description and ends with %$END directive.

Limitations on Exclusion and Placement Search

Exclusion criteria are evaluated before the code fragment dialog is displayed at which time parameter values are not avaialble. Hence, the search criteria for for exclusion based on fragment body line, not manually provided line prefix, replaces the parameter references with a wildcard search pattern. This will match any text in place of the parameter which may match more than just the line being searched for. If you want to control the exclusion criteria either include a comment tag to uniquely identify the code fragment or provide a line offset which results in a unique line without any parameter references.

Similarly the Placement directive with BEFORE or AFTER clause will use either the first or last line of the referenced code fragments body text to locate the placement for the referencing code fragment. If these lines contain parameter values then the search will replace the parameter reference with a wild card pattern casuing it to match any possible text replacement. For BEFORE the first line of the referenced code fragment is used. For AFTER the last line of the referenced code fragment is used. If placement is critical and these lines contain parameter references then you may want to add comment marker lines that can be used in the placement search.

Example code fragment body line containing a reference:

prefix text %$(PARAM:ParamName) some suffix of the line

A search for this line either during exclusion or placement will match any line that starts with 'prefix text ' and ends with ' some suffix of the line'. Similarly for the SQUOTE, DQUOTE and BQUOTE versions with the exception that the wildcard pattern will be quoted with the appropriate quotes so it will only match the correspondingly quoted text.

Code Fragment Reference

The A/D/F/H/O column specifies whether the directive is a Header Directive, Fragment Directive or a Default Directive and whether multiple invocations Overwrite previous values or Accumulate them. Header directives are global to all fragments in the file, default directives provide default values for code fragments in the file.

NOTE: Directives that are Boolean use the text to set their state and will accept Y, Yes, 1, or empty as being true. Anything else is false, so specifying just the directive (text is empty) is the same as specifying the directive=Yes.