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.
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)...
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:
- Resolves to the literal text <ProgramFilesFolder>
- Resolves to <ProgramFilesFolder>=...value of ProgramFilesFolder variable...
The following prefixes can be used in expr expressions. Examples of their use follow after the table.
|(no prefix)||Variable name||
Value of the symbolic variable with all symbolic references recursively resolved, for example <MyVar>.
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.
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,
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>.
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.
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>.|
|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.
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=...>
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.