Intel® Quartus® Prime Pro Edition User Guide: Scripting

ID 683432
Date 9/26/2022
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

4.1.24.4. escape_brackets (::quartus::misc)

The following table displays information for the escape_brackets Tcl command:

Tcl Package and Version

Belongs to ::quartus::misc

Syntax escape_brackets [-h | -help] [-long_help] <str>
Arguments -h | -help Short help
-long_help Long help with examples and possible return values
<str> String to escape
Description
Escapes square brackets in bus name patterns for use in string
matching. Also escapes the escape character; for example, the string
"\" is escaped into "\\".

Note that natural bus naming is supported by default. This means that
bus names, not bus name patterns, are automatically detected and do
not need to be escaped by using this command.  Bus names have the
following format:

<bus name>[<bus index>] or <bus name>[*]

The <bus name> portion is a string of alphanumeric characters.  The
<bus index> portion is an integer greater than or equal to zero or it
can be the character "*" used for string matching.  Notice that the
<bus index> is enclosed by the square brackets "[" and "]". For
example, "a[0]" and "a[*]" are supported bus names.

All other uses of square brackets must be escaped if you do not intend
to use the brackets as part of a string pattern in a string match. For
example, the bus name pattern "a\[0-2\]" must be escaped using this
"escape_brackets" command since the "0-2" does not satisfy the <bus
index> requirement to be a bus name.

Many Quartus Prime Tcl commands allow string matching in option
arguments. A common error is using bus name patterns in these
arguments, such as:

address\[0-2\]

Square brackets for bus name patterns must already be preceded by an
escape character (\[ or \]) to prevent Tcl from interpreting them as
sub-commands. String matching, however, also uses square brackets to
match any character between the brackets.  The previous example, when
used as a string match pattern, searches for the string patterns
address0, address1, and address2. It does not search for address[0],
address[1], and address[2].

Therefore, for arguments that support string matching, square brackets
must be escaped twice (\\\[ or \\\]) so that the strings are
interpreted as bus name patterns. For example, to search for
address[0], address[0], and address[2], type the following string
match pattern:

address\\\[\[0-2\]\\\]

or, equivalently,

"address[escape_brackets \[]\[0-2\][escape_brackets \]]"

Quartus Prime Tcl commands do not convert bus name patterns
automatically, since they cannot determine if the string is intended
as a bus name pattern or a regular string match pattern. Therefore,
"escape_brackets" is provided for your convenience.

You may choose to disable natural bus naming in order to string match
patterns such as "in\[024\]". In this example, you are string matching
the names "in0", "in2", and "in4".

To disable natural bus naming, type
"disable_natural_bus_naming".

Note that if you disable natural bus naming, then square brackets must
be escaped twice (\\\[ or \\\]) so that the strings are interpreted as
bus names during a string match, such as:

set bus_name "address\[0\]"
string match [escape_brackets $bus_name] $bus_name

The "escape_brackets" command escapes "address\[0\]" into
"address\\\[0\\\]".

To enable natural bus naming again, type
"enable_natural_bus_naming".

For more information about natural bus naming, type
"enable_natural_bus_naming -h".  
Example Usage
# Get all location assignments for bus address[]
set address_names address[*]		
set address_locations [get_all_instance_assignments -to $address_names] -name LOCATION

# Get location assignment for bus address[0]
set address_names address[0]		
set address_locations [get_all_instance_assignments -to $address_names] -name LOCATION

# Get location assignments for bus address[0],
# address[1], and address[2]
set address_names address[0-2]		
set address_locations [get_all_instance_assignments -to [escape_brackets $address_names]] -name LOCATION
Return Value Code Name Code String Return
TCL_OK 0 INFO: Operation successful