Winpte.com

Language Template Reference

Definition

Language templates encompass the configuration and macro definitions that are associated with files based on the file's extension. Each language template has an extension list which is used to resolve the association of files to their language template.

Creation

A language template comes into existence when its name is first defined via the 'set source ... name' command:

set source templateName { based-on baseName }

templateName is also used to identify the data point name under the /editor/session/templates node to be used for storing this template's configuration and is used to identify all source settings and the key definitions belonging to this template.

NOTE: versions 3.00.445 and prior used extensions from the templates extension list to identify settings and key definitions. This made them dependent on the currently associated extension list, making user configurable extensions a potential way of orphanning the settings and key definitions or overwriting defintions and/or settings of another template. Using extensions for identifying settings and key defintions is no longer recommended because of this potential conflict. Additionally, resolving the key definitions based on extension is depricated and will result in warnings on load with instructions where and what to fix. It will be discontinued after the next few releases.

The template will not be associated with any file extensions until its extension list is defined with the set source .ext1;.ext2.. extensions where .ext1;.ext2..... is a list of file extensions that are to be associated with this language template. A language template with no extensions can be used as a Base language template for a common set of languages and should contain all the common macro definitions.

based-on baseName is an optional directive specifying which language template is to be used as the base template for purposes of resolving key and function definitions. If not specified then the template will inherit from the default template.

Language template settings are not inheritted nor copied and start with their default values the first time a template is created, on subsequent WinPTE startup settings that are persistent will be restored from persistent storage, others will always initialize from the command file that defines the language template.

Default Template

This template is automatically created and contains an empty extension list. Any file whose extension does not match a specific language template is associated with the default template.

Language Template Configuration Commands

Configuration commands are all part of the SET command under the SOURCE group, so all commands start with SET SOURCE templateName..... The templateName can be a previously created language template name. If no such template is found and the template name contains a . then the name is interpreted as a file name and an attempt is made to resolve the template reference using the template's associated extension list. So you can use a filename and the file's extension will be used to resolve the language template reference. If the name is an extension list (; separated) then only the first extension in the list will be used).

An error results if the language template reference cannot be resolved for any of the defined templates.

NOTE: Template resolution based on file name and/or extension list is a convenience feature for command line savy users and not to be used to create language template definition files.

NOTE: Creating a template whose name contains a period is not recommended because a typo in the name may not result in errors if a match to another template based on a file name search is successful.

Command	Description
set source templateName name based-on baseName	Creates the language template if it does not already exist. The based-on with the baseName is optional and specifies the base template to use for resolving key and function definitions.
set source templateName	With no options will reset the current file's template association based to the template reference given by templateName. If templateName is not provided then the file name of the current file will be used to resolve the reference. This is useful when you have just created a new templates and want to resolve the name of the current file for testing or if you want to manually change the template association for the currnent file.
set source templateName extensions .ext1;.ext2...	Defines the file extensions that are to be associated with the language template.
set source templateName case set source templateName nocase	Case sensitivity of the language, case for case sensitive, nocase for not case sensitive. This is used by some macros to modify default search options to reflect the language case sensitivity.
set source templateName columns 'style1:cols1;style2:cols2;...'	Defines column based colorization for the language. Style1, Style2 ... are text style names and cols1, cols2, .... are the number of columns to be colorized in this style. If the column count can be omitted from the last style name and the remaining columns will be colorized with that style. If style name is omitted then the text in those columns will use the keyword definitions for that language. This allows some columns to have a fixed text style while others to use keyword based colorization. An example of such is the for.pte template which defines Fortran-77 colorization as: 'comment:1;controlflow:5;linecontinuation:6;:72;errorcolor:'
set source templateName comments # 'charSet'	This only applies to languages such as Fortran-77 that have the comment character associated with a specific column position to define comments. # is the column position and charSet is the set of characters that start a comment. All other non-column based languages use keyword colorization to define comments.
set source templateName word 'charSet'	Defines the set of characters that are considered to be part of identifiers and keywords of the language. This is used in search/replace to resolve the 'Whole Word' option and by many macros that need to tailor their function according to the language's word definition.
set source templateName glossaryword 'charSet'	Defines the set of characters to be considered a word by the statement completion list. Statement completion list will match items that consist of characters that are part of this character set. Other items in the statement completion list can be included but will not be automatically selected. Additionally the space character is always treated as excluded from the set and is used to signal that the statement completion list should be closed.
set source templateName trailingblanks set source templateName notrailingblanks	Whether to preserve trailing blanks on save. If notrailingblanks options is specified then trailing blanks will not be saved.
set source templateName autoglossary number	Specifies the minimum number of consecutive characters that must be typed before the statement completion list will display. Any items in the list less than the number specified will cause the list to pop up when they have been completely typed in. So with a minimum of 3, the 'if' item will still cause the list when if keyword is typed in. Specifying the word 'off' for the number will turn off the automatic popup of the statement completion list. It will only be available through manual invocation.
set source templateName margins left right indent commentLead	Defines the left margin, right margin column numbers, indentation in number of columns per single indent and the leading characters to use for the single line comments when reflowing comments, inserting new comment lines or toggling comments. The comment prefix characters can be enclosed in single quotes. If the comment prefix is a single quote then it must be enclosed in single quotes and escaped via \. In other words use '\'' as the string.
set source templateName tabs tab1 tab2 tab3 ....	defines the tab stops for the files associated with this template. This only affects the initial tab settings for the file. Thereafter the file's tabs can be changed via the 'set tabs ' command. tab1 tab2 tab3 specify the tab stops either as individual columns, or if prefixed with + as every N columns, if prefixed with a - then the tab stop given by the number is removed. The latter is useful to clear a few specific stops set with a previous +#. Note that +8 will set tab stops at 1, 9, 17, ... since column numbering starts with 1. Example: 4 +8 -9 will result in tab stops on columns 1, 4, 17, 25, 33, ...
set source templateName nonflexing reg1 reg2 reg3 ...	Defines syntax colorization region numbers which do not stretch/compress spaces in flex insert mode. Default 2 and 3 which are single and double quoted string regions by convention. Region numbers are 1 to 255, 1 - multi-line comments, 2 single quoted string, 3 double quoted strings, 255 single line comments. 1 to 3 is a convention only used by standard templates, region 255 is part of the implementation. (new setting, introduced after 3.00.445)
set source templateName glossary	Clears the statement completion list, it is a good idea to clear the list before starting the definition for the statement completion list even though on initial load the list is already empty. You will most likely reload the single template file multiple times during testing and subsequent reloads will not have the list empty and unless cleared will create multiple entries for every item.
set source templateName glossary 'itemCaption' 'itemTemplate'	Defines an entry for the statement completion list. The itemCaption defines the caption and an optional tooltip while the itemTemplate defines the expansion text or the optional command to be executed when the item is selected. itemCaption any characters following \f will be used to define the tooltip which will be displayed when the item is selected in the list. Use \n to insert a line break for the tooltip. itemTemplate defines the text the item will expand. If the text starts with \f then it will be treated as a command to be executed instead of text to be inserted into the file. You can specify insertion points where you can enter parameters into the template with \v# where # is a digit 0 to 9, if # is omitted then 0 is assumed. The cursor will move from the lowest count insertion point to highest every time ENTER key is pressed, until no more insertion points are defined. At which time the ENTER key will revert to its normal function. The actual position of the insertion points in the template is arbitrary and should be guided by what makes more sense for the language construct that the template represents. Additionally the text entered at any insertion point can be replicated to any number of places in the template. To specify the location for the copy use the \a# where # is 0 to 9 and corresponds to the 0 - 9 insertion points. This is useful when the template needs parameter text to be replicated throughout the language construct. For example to convert the basic loop into a template: FOR I = 1 TO 10 NEXT I In this case I would be the first insertion point, 1 and 10 would be insertion points 1 and 2, the I after NEXT would be a copy of the first insertion point or \a. The full definition for the statement completion template would be: set source .ext1 glossary 'for' 'FOR \v = \v1 TO \v2\n\v3\nNEXT \a' The \v3 insertion point is needed to move the cursor inside the construct after all the parameters entries have been filled in. Otherwise you will have to manually move the cursor down. If the language template defines an auto format function then the expanded template code will be auto formatted after expansion. Otherwise you can/need to include \t for indent and \b for un-indent in the template to create the right indentation in the expanded text. Do not be tempted to use spaces for two reasons: one they take up more space, two they will have hard-coded the indentation level whereas \t \b use the currently defined setting in their language template.
set source templateName keyword keywordOpt 'style' keyword1 keyword2 ....	Defines the keyword and its associated style name. keywordOpt are defined in the table below. keyword1, keyword2 ... are the keywords to be used. Optionally these can be specified inside single quotes. Otherwise space is used as a delimiter between keywords. Quotes must be used if the keywords contains spaces or single quotes. style must be the name of a style data point defined under the /editor/session/textview/userstyles. If the style is not defined then the Normal text style will be used and the keyword(s) will appear as not colorized. (see Options Pane Reference ) and the options.xml file for examples of user styles exposed through the Options Pane.

Keyword Options

For historical reasons the keyword context options are specified using the same single character options as the find and replace commands with a few having a special meaning. This part is a kludge, has limitations and is on a short list of items to be rewritten. However, for now this is how you would define the keywords.

Limit of a maximum of 255 templates defined at a time and "soon to be eliminated" maximum limit of 817 keywords per language template.

Option	Description
c	case sensitive compare. Default is not case sensitive even if case sensitive is defined for the template.
w	whole word match. Words are considered to be any stretch of characters that are part of the word charSet for the language template. The keyword must also start and end with a character that is part of the word set.
b	must be the beginning of a word. Words are considered to be any stretch of characters that are part of the word charSet for the language template. The keyword must also start with a character that is part of the word set.
e	must be the end of a word. Words are considered to be any stretch of characters that are part of the word charSet for the language template. The keyword must also end with a character that is part of the word set.
d	Defines a single line comment prefix
f	must be the first non blank on the line. i.e. at the beginning of the line ignoring leading blanks.
l	must be the last non blank on the line. i.e. at the end of the line ignoring trailing blanks
^	must be in the first column on the line
$	must be at the end of the line
i# o# io#	define the start and end keywords for a multi-line region respectively (think of them as going In and going Out). Used for multi-line comments and strings. # is a numeric value from 1 to 254. If the region starts and ends with the same character then it must be specified as either io# or oi# in the same command. By convention and assumed by most macros region 1 is the multi-line comment region. Regions 2 and 3 are used for single and double quoted strings. The rest do not have any identifiable convention.
d#	defines an escape sequence for the region given by #. Only the first character is significant. However the number of characters colored with the specified style are determined from the length of the keyword-1. So for C/C++/C# etc. string escapes are specified as '\\22' the 2 has no special meaning and serves only to reserve space for characters as being colorized by the color of the given keyword. In this case two characters. (Don't ask why length-1, this is very old code)
n	specifies that the end region style will remain in effect until the end of the line.
s	Shift case to match that of the keyword. Useful for case insensitive languages to force all keywords to a specific case format. So if you specify the keyword as 'For' then every time 'for' appears in the file it will be changed to match the case of the keyword.