KLayout Documentation (Qt 5): Main Index » Various Topics » About Expressions

About Expressions

Beside a ruby and Python programming API, KLayout provides support for simple expressions in some places. In particular this feature is employed to generate dynamic strings, for example when deriving the label text for a ruler.

String interpolation

The feature of inserting dynamic content into a string is called interpolation. The Syntax KLayout uses for string interpolation is a dollar character followed by the expression which is evaluated. Simple expressions can be put directly after the dollar character. Others must be put into brackets.

Every dollar expression is evaluated and the expression is substituted by the result string. For example:

String interpolation plays a role where expressions are used to generate dynamic strings. When expressions are used as standalone features (i.e. as parts of a custom layout query - see About Custom Layout Queries), string interpolation is not supported inside string constants, but strings can be built dynamically using the "+" operator.

Basic data types

Expressions use different data types to represent strings or numeric values. The following data types are supported currently:

Apart from that, all RBA objects are supported with their methods (see Class Index). For example, that is a valid expression which gives a value of 100:

Box.new(-10, 0, 90, 60).width

In a boolean context (i.e. the conditional evaluation "condition ? expr1 : expr2"), "nil" and the boolean "false" will render false, while all other values render true. This follows the Ruby convention and in effect, unlike some other languages, a numeric value if 0 is not treated as "false" but as "true"!

Constants

The following constants are defined currently:

Operators and precedence

KLayout's expressions support the following operators with the given precedence:

The match operators work on strings. They use the glob pattern notation (as used in the shell for example) and support substring matching with the usual bracket notation. Substrings can be referred to by "$n" later, where n is the nth bracket. For example:

Method calls

Expressions support all the objects provided by KLayout for the Ruby API. Objects are values inside expressions like integers or strings are. Sometimes, objects can be manipulated with the operators as well (like "box1 + box2"). The most important way to work with objects however are methods.

The dot calls a method on an object. Before the dot an expression must be given which results in an object, or a class name must be given. In the latter case, static methods will be called. After the dot, a valid method name is expected.

Important note: the method names used inside expressions usually is equivalent to the names mentioned in the class documentation. Setter methods like "box_with=" can be used as targets in assignments, i.e.

shape.box_width = 20

Boolean predicates (like "is_box?") are used without the question mark because that is reserved for the decision operator (".. ? .. : .."):

shape.is_box

Concatenation of expressions

The semicolon separates two expressions. The value of that compound expression is the value of the last one.

Keyword arguments

Most methods support keyword arguments similar to Python. For example you can write:

CplxTrans.new(rot = 45.0)

This is more explicit than writing the individual arguments and allows giving one argument without having to insert the default values for the previous ones.

Keyword arguments are not supported for the built-in functions such as "sqrt" and a few built-in methods.

Variables

Depending on the context, some variables may be already defined. For example, when used for generating ruler dimension labels, "D" is a predefined variable that is the length of the ruler. See the specific documentation on these variables.

Inside expressions, variables can be defined to store intermediate results for example. To define a variable use the "var" keyword followed by the variable name and an optional initialisation. Assignment of values can be done with the "=" operator. For example, the following expression gives the result 4:

var x = 3; x = x + 1; x

Special variables

Special variables start with a dollar character. Currently the only special variables available are "$1..9" which is the 1 to 9nth substring match of the last match expression.

Special constants

In the context of a layout, various additional constant expressions are supported:

Distance and area units

A value with a unit is automatically converted to database units. For example, "0.15 um" will give 150 if the database unit of the layout is 1 nm. See below for a list of units available. Supported units are:

Layer index constants

A layer given in the common notation and enclosed in angle brackets is converted to a layer index. For example: "<16/0>" will be converted to the layer index of the layer with layer number 16 and datatype 0.

Cell index constants

A cell name enclosed in double angle brackets will be converted to the index of that cell, for example "<<TOP>>".

Functions

KLayout's expressions support the following functions: