Symbolic expressions
Symbolic expressions can be used for many purposes:
- Folder paths: for example, <ProgramFilesFolder> returns the folder path of the "Program Files" folder on the target system, localized as appropriate; <$comp_name> returns the folder path that is associated with component comp_name.
- File paths: for example, <#file_alias> returns the installation path of the file with alias file_alias.
- General text: for example, <ProductName> returns the name of the product that is being installed.
- General and system variables: for example, <TsuQuiet> returns the user interface level of the installer; <VersionNT> returns the Windows version if the installer runs on a Windows NT-based system.
- Auxiliary variables: for example, <UIRegistrationPage> is used to control support for the customer registration functionality.
- Runtime information: for example, <%ComSpec> returns the path to the command processor on the target system; <@<HKCU>\Software\<Publisher>\<ProductName>\User> returns the value of the (hypothetical) User registry value under the product's registry key.
- Runtime functions: for example, <$sfn(<#file_alias>)> returns the short file name (8.3) version of the path to the file with alias file_alias; <$fverp(<#file_alias>)> returns the product version of the same file.
Furthermore, symbolic expressions and variables are used in conditional expressions.
Syntax
The symbolic expression syntax is defined as follows.
- Items in italics are non-terminals.
- Items in bold are keywords or literal symbols.
- The pipe character '|' indicates a choice.
- ...something... items are informal definitions of terms.
- Names are case-insensitive. We recommend that you do not create names that differ only in case.
- Recursive symbolic expressions are allowed up to a depth of 32 in InstallMate.
symexpr ::= < expr >
expr ::= varname | ?varname | #filealias | $compname | %envvar | @regpath |
$func(params) | #filepath?section?key | !expr | expr=expr
varname ::= ...name of a symbolic variable (may use symbolic expressions)...
filealias ::= ...alias of installation file (may use symbolic expressions)...
compname ::= ...component name (may use symbolic expressions)...
envvar ::= ...environment variable name (may use symbolic expressions)...
regpath ::= ...path to registry value (may use symbolic expressions)...
func ::= ...name of runtime function...
filepath ::= ...file path (may use symbolic expressions)...
section ::= ...INI file section name (may use symbolic expressions)...
key ::= ...INI file key name (may use symbolic expressions)...
Non-symbolic expressions
To prevent InstallMate from interpreting some text as a symbolic expression, enclose the text in backticks: `...some text...`. You can do this for the entire text, or only for the portions that must not be interpreted. For example:
- `<ProgramFilesFolder>`
- Resolves to the literal text <ProgramFilesFolder>
- `<ProgramFilesFolder>`=<ProgramFilesFolder>
- Resolves to <ProgramFilesFolder>=...value of ProgramFilesFolder variable...
Expression prefixes
The following prefixes can be used in expr expressions. Examples of their use follow after the table.
| Prefix | Operands | Result |
|---|---|---|
| (no prefix) | Variable name | Value of the symbolic variable with all symbolic references recursively resolved, for example <MyVar>. See Alphabetical reference for a full list of predefined symbolic variables; you can add your own variables on the Variables project page. |
| ? | Variable name | Value of the symbolic variable without any further recursion, for example <?MyVar>. Use this prefix to retrieve the value of the symbolic variable as-is, without trying to interpret that value as perhaps another symbolic expression. This is useful if the value contains characters such as '<' that you do not want to be interpreted as a symbolic expression. |
| ! | Symbolic expression | The literal value of the symbolic expression, without further symbolic resolution, for example <!MyVar>. This allows, for example, expressions like <@<ShellFoldersCU>\My Pictures=!<PersonalFolder>\My Pictures> to behave as expected, instead of treating <...<PersonalFolder>...> as a lookup of the PersonalFolder variable, followed by an attempt to look up the non-existing variable whose name was retrieved from PersonalFolder. |
| # | File alias | Installation path of the corresponding file, for example <#file_alias>. |
| #...?...?... | INI file path, section, key |
Value from the corresponding INI file, section, and key, retrieved from the target system at installation time. Specify the lookup as <#inipath?section_name?keyname>. |
| $... | Component name | Installation path of the folder linked to the component, or an empty string if the component does not have a linked folder. Note 1: You must specify the component's (internal) name with this prefix, not the component's display title. For example, use <$compname> and not <$Some Product Feature>. Note 2: The installation folder path, if any, is returned regardless of the installation status of the component itself. Note 3: The <$compname> syntax documented here differs from the $compname syntax (without '<' and '>' brackets) used in conditional expressions, where it retrieves the component's installation action. |
| $...(...) | Function name, parameters |
Result from the corresponding runtime function. The required parameters depend on the function. See Runtime functions for a full list. |
| % | Environment variable | Value of the corresponding environment variable, retrieved from the target system at installation time, for example <%COMSPEC>. |
| @ @32: @64: |
Registry value path | Value of the corresponding registry value, retrieved from the target system at installation time. Specify the path as <@HKEY_hive\path\to\regkey\value_name>. By default, the lookup will try both the 64-bit and the 32-bit registry views on a 64-bit Windows system. To force the lookup to consider only the 32-bit or only the 64-bit view, use a 32: or 64: prefix as shown on the left. On 32-bit Windows systems, the 32: prefix acts as per usual, but the 64: prefix causes the lookup to fail. Note 1: To retrieve the unnamed (default) value of a registry key, terminate the registry value path with a backslash ('\'). Note 2: To retrieve a value whose name contains a backslash ('\'), start the value name with '?|' (question mark followed by pipe character) to separate the value name from the preceding key path, like this: <@HKEY_hive\path\to\regkey\?|value_name\with\backslash>. See the examples below. |
| = | Alternate expressions | If the left operand is not empty, the left operand; else the right operand. You may use a sequence of alternate expressions to try them all in succession: <expr1=expr2=expr3=...> |
Examples
For the examples assume the following variables and values:
- Variable MyVar with value <AnotherVar>
- Variable AnotherVar with value ANestedValue
- Plain variable lookup, no prefix
- <MyVar> resolves to ANestedValue after a recursive lookup: the first lookup returns <AnotherVar>, which is immediately further expanded to ANestedValue.
- Non-recursive lookup
- <?MyVar> resolves to <AnotherVar>, its immediate value; no recursion is applied after the ? prefix.
- Alternate values
- <NoneSuch=MyVar> resolves to ANestedValue because the first try, <NoneSuch>, results in an empty string, after which the second part is evaluated as <MyVar>, which succeeds after some recursion.
- Literal value within < and > context
<NoneSuch=!MyVar> resolves to the literal text MyVar, as follows: first the interpreter tries to resolve <NoneSuch>; if that fails because there is no variable called NoneSuch, it then tries to resolve the alternate part (after the '=') as <!MyVar>, which results in the literal text MyVar instead of a lookup of the MyVar variable.
The ! prefix prevents interpretation of MyVar as a variable name inside the < and > context, which is necessary if you want to provide a literal alternate value after an '=' character inside a symbolic expression.
- File installation path lookup
- <#File1_B626B86FC5B040E7> resolves to the installation path of the file with Alias File1_B626B86FC5B040E7 in your project.
- INI file value lookup
- <#<WindowsFolder>\win.ini?Mail?MAPI> performs a lookup in the C:\Windows\win.ini file, finds the section [Mail] in that file, then returns the value associated with the key MAPI in that section, if any.
- Runtime functions
- See Runtime functions for a full list with examples.
- Environment variable lookup
Example 1: <%COMSPEC> resolves to the path to the command processor, typically something like C:\Windows\System32\cmd.exe
Example 2: <%NUMBER_OF_PROCESSORS> returns the number of processor cores on the system.
- Registry value lookup
Example 1: <@<HKLM>\Software\Microsoft\DirectX\Version> resolves to the registry lookup of the value Version under the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\DirectX. The result is typically something like 4.09.00.0904
Example 2: <@32:<HKLM>\Software\Microsoft\DirectX\Version> resolves to the registry lookup of the 32-bit DirectX installation, if any. It will not consider the 64-bit registry view on a 64-bit Windows system.
Example 3: <@64:<HKLM>\Software\Microsoft\DirectX\Version> resolves to the registry lookup of the 64-bit DirectX installation, if any. It will not consider the 32-bit registry view on a 64-bit Windows system. On a 32-bit Windows system, the lookup will always fail (i.e., return an empty string).
Example 4: <@<HKLM>\<WinCurVer>\SharedDlls\?|C:\Windows\system32\VSJitDebugger.exe> resolves to the C:\Windows\system32\VSJitDebugger.exe value under the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\SharedDlls registry key.
The '?|' characters immediately before the value name separate the value name from the preceding key path; without this special separator, the '\' characters in the value name would be considered part of the (non-existing) key path.