Token expansion is performed, generally speaking, when a template opens, or when text is inserted into a document. It occurs during the following operations:
Insertions from the Tokens window are the principal means for using token expansions. For token expansion on replacing text, the "Use Token Expansion" setting in the "Editing"/"Find and Replace" setting group must be checked. Likewise, for token expansion on command execution, the alike named setting in the "Command Model" setting group must be set.
As mentioned, tokens may be expanded when a command is executed. The tokens:insert command inserts text into the current selection:
tokens:insert?Hello, $Token%!
This enables advanced text insertion techniques, as well as storing such expandable tokens - as tokens:insert commands with the proper query string - on the toolbar, in the project, or in the Favorites.
Token expansion includes one or more of the following possible actions:
Expansions are performed in the following order:
As noted, not every kind of expansion is performed in each of the situations listed above. For example, Drag-and-drop operations from the Tokens window bar wildcard substitutions and everything that may involve a dialog (such as parameter substitutions). Here is an overview:
| Expansion | Opening/Inserting Templates | Token Insertions | AutoText Completions | Finding/Replacing Text | Command Execution |
|---|---|---|---|---|---|
| Wildcards | - | Yes1 | - | - | - |
| Aliases | - | - | Yes | - | - |
| Parameters | Yes | Yes1 | Yes | Yes | Yes |
| Escapes | - | Yes | Yes | - | - |
1) Except drag-and-drop operations.
Note that alias expansion, which is performed on auto-text completions only, is language specific (see below).
Note that unlike any other command, the tokens:insert command will always perform wildcard expansion as well as unescaping (it works very much the same as token insertions from the token list window).
Also note that if a parameter is substituted in a tokens:insert command in such a way that any further expandable characters or character sequences result (such as the wildcard char), these characters are themselves subject to token expansion. (this is a rather tricky interaction, because parameters in commands are expanded before token expansion as part of the tokens:insert command itself is performed).
Expandable tokens are either a sequence of characters interpreted as literals, escapes, wildcards, or paramenters. Tokens must not contain any line breaks (but line breaks can be achieved with escape characters). Here is a short syntax of elements that can be combined into expandable tokens:
literal
escape-sequence ::= \n
\t
\\
wildcard ::= *
parameter :: = $<parameter-name>%
$<code-expression>%
Examples:
<a href="*">*</a>
<a href="$URL%" title="$Tooltip%">$Text%</a>
\n<p>\n*\n</p>\n
\tTry\n\n\tCatch ex As Exception\n\n\tFinally\n\n\tEnd Try
class $Class%{\n\n\tpublic $Class%(){\n\t}\n\n} // $Class%\n
<p>Created: $System.DateTime.Now%</p>
$SampleScript.MTranslate.G2E("*")%
Wildcards are the asterisk (*), which stands for the current selection. The asterisk may appear multiple times in a token, thereby multiplying the current selection. For example, here's how to convert a URL into a hyperlink:
<a href="*">*</a>
Alias substitution, which is performed on auto-completion only, is language-specific (one or more alias files must be configured for the current language). It is performed before unescaping and expanding parameters, which allows using short identifiers in the token list for more complex auto-completions, included running custom code during parameter substitution (akin to code snippets). To enable aliases, just add catchy identifier tokens to the token list (like "link"; avoid conflicts with other tokens that are to be inserted as-is), configure an alias file in the language configuration file (WebEditLanguages.xml), and define the alias in XML format:
<!-- WebEditLanguages.xml -->
<language type="Gregor.Core.CLanguageInfo" name="HTML">
<extension name=".html" default="1" />
<extension name=".htm" />
<autocompletefile relpath="Tokens\HtmlAutoComplete.txt" />
<aliasfile relpath="Tokens\HtmlAliases.xml" />
</language>
<!-- HtmlAliases.xml -->
<aliases>
<alias key="link" icon="Hyperlink.ico">
<!-- the alias element can define the alias value in a
CDATA child, a text child, or the value attribute -->
<![CDATA[<a href="$Url%" title="$Title%">$Text%</a>]]>
</alias>
</aliases>
<!-- HtmlAutoComplete.txt -->
link
You can also configure aliases in the settings dialog ("Tools"/"Settings" menu item). In the "Editing/Languages" settings group, select a language, then "Aliases". Add an alias - enter a name, a value, and an alias file name (relative path), or editing an existing alias. To add an identifier to a token list, use the Tokens tool window.
If a parameter is an expression that the code interpreter can evaluate, the value or result (respectively) of a variable, property, or method will be converted to a string, and used in place of the parameter.
For example, to insert the current timestamp, or a date info, use:
$System.DateTime.Now%
$System.DateTime.Now.ToString("dddd, MMMM d, yyyy", System.Globalization.CultureInfo.CreateSpecificCulture("en-US"))%
To insert the full path of the current document, use:
<p>\n$Vars.DocPath%\n</p>
With regard to method invocations, it is possible to use a wildcard for a single formal string parameter (the current selection will be used as the actual string parameter). A translation routine could be called like this:
$Translator.Translate("*")%
Note that the call to the Translate method with the "*" argument is evaluated by the code interpreter, which cannot interprete multi-line strings. Therefore, if the current selection spans multiple lines, you can't use this shortcut. Instead, use the following:
$Translator.Translate(Vars.TextSelection)%
The user can accept or overwrite the values calculated by the code interpreter, or fill in missing values for code expressions that the code interpreter can not evaluate, in a special dialog that pops up when a parameter substitution occurs.
Note that, using the Code Interpreter, you can set code variables to use as parameters. For example, set the following variable (in the Console) ...
code:ExcType = "Exception"
... which can be used in the following token ...
Try\n\nCatch ex As $ExcType%\n\nEnd Try
That done, select the AutoText list to the same list that you've added the token to, enable automatic text suggestions, type "Try", and hit Enter.
Program settings control whether or not to perform parameter substitution at all, and whether or not to show the parameter dialog if all values have been successfully calculated by the code interpreter.
Note that the code interpereter can evaluate several statements separated by semicolons. The value of the last statement will be used in this case. Here's how to include the results of a web request into a token:
$reader = new System.IO.StreamReader(System.Net.WebRequest.Create("http://localhost/").GetResponse().GetResponseStream()) ; s = reader.ReadToEnd() ; reader.Close() ; s%
Escapes can be line breaks (\n), tabs (\t), or the backslash (\\). When you drag a token to the Token List, tabs and line breaks are substituted for these escape sequences (this means you can edit an expandable token in the editor without worriying about the escape syntax).
For example, the following token ...
class Test \n{\t// ...\n}
... will expand to this ...
class Test {
// ...
}
If the "Convert Tabs To Spaces" setting (in the "Editing" setting group) is set, all tabs will be replaced by spaces.
Note that escape sequences within parameters may be evaluated by the code interpreter. This is important if they occur in method arguments; then they might not show up in the final result.
See Also: Templates | Token Lists | AutoText | Code Interpreter