KLayout Manual: Main Index » Various Topics » About Expressions

About Expressions

Beside a ruby 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	Evaluates to
`An irrational number: $sqrt(2).`	`An irrational number: 1.4142136`
`1+2 is $(1+2).`	`1+2 is 3.`

Basic data types

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

Type	Examples
Numeric	`1.2 -0.5e-6`
String	`"abc" 'x'`
Boolean	`true false`
Array	`[1,5,4]`
Undefined (no value)	`nil`

Constants

The following constants are defined currently:

Constant	Description
`M_PI`	The mathematical constant 'pi'
`M_E`	The mathematical constant 'e'
`false`	'false' boolean value
`true`	'true' boolean value
`nil`	The 'undefined' value

Operators and precedence

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

Prec.	Operator	Data types	Result type	Description
1	`(`...`)`	Any		Grouping of sub-expressions
2	`[`...`,`...`]`	Any	Array	Array formation
3	`!`...	Boolean	Boolean	Logical 'not'
3	`~`...	Numeric	Numeric	Bitwise 'not' (evaluated as 32 bit integers)
3	`-`...	Numeric	Numeric	Negation
4	...`^`...	Numeric	Numeric	Bitwise 'xor' (evaluated as 32 bit integers)
4	...`&`...	Numeric	Numeric	Bitwise 'and' (evaluated as 32 bit integers)
4	...`\|`...	Numeric	Numeric	Bitwise 'or' (evaluated as 32 bit integers)
5	...`%`...	Numeric	Numeric	Modulo
5	...`/`...	Numeric	Numeric	Division
5	...`*`...	Numeric	Numeric	Product
		Numeric*String	String	String multiplication (n times the same string)
6	...`-`...	Numeric	Numeric	Subtraction
6	...`+`...	Numeric	Numeric	Addition
		String	string	Concatenation
7	...`<<`...	Numeric	Numeric	Bit shift to left
7	...`>>`...	Numeric	Numeric	Bit shift to right
8	...`==`...	Any	Boolean	Equality
8	...`!=`...	Any	Boolean	Inequality
8	...`<=`...	Any	Boolean	Less or equal
8	...`<`...	Any	Boolean	Less
8	...`>=`...	Any	Boolean	Greater or equal
8	...`>`...	Any	Boolean	Greater
9	...`&&`...	Boolean	Boolean	Logical 'and'
9	...`\|\|`...	Boolean	Boolean	Logical 'or'
10	...`?`...`:`...	Boolean?Any:Any	Any	Conditional evaluation

Functions

KLayout's expressions support the following functions:

Function	Data types	Result type	Description
`absolute_file_path(`x`)`	String	String	Convert a relative file path to an absolute one
`absolute_path(`x`)`	String	String	Returns the absolute path component of a file specification
`acos(`x`)`	Numeric	Numeric	Inverse cosine function
`asin(`x`)`	Numeric	Numeric	Inverse sine function
`atan2(`x`,`y`)`	Numeric	Numeric	Inverse tangent of x/y
`atan(`x`)`	Numeric	Numeric	Inverse tangent function
`basename(`x`)`	String	String	Returns the basename component of a file specification
`ceil(`x`)`	Numeric	Numeric	Round up
`combine(`x`,`y`)`	String	String	Combines the path components x and y using the system specific separator
`cosh(`x`)`	Numeric	Numeric	Hyperbolic cosine function
`cos(`x`)`	Numeric	Numeric	Cosine function
`env(`x`)`	String	String	Access an environment variable
`error(`x`)`	String		Raise an error
`exp(`x`)`	Numeric	Numeric	Exponential function
`extension(`x`)`	String	String	Returns the extension component of a file specification
`file_exists(`x`)`	String	Boolean	Returns true if the given file exists
`find(`s`,`t`)`	String	Numeric	Finds the first occurrence of a t in s and returns the position (where 0 is the first character)
`floor(`x`)`	Numeric	Numeric	Round down
`gsub(`s`,`x`,y)`	String	String	Substitute all occurrences of a x in s by y
`is_array(`x`)`	Any	Boolean	True if the argument is an array
`is_dir(`x`)`	String	Boolean	Returns true if the given path is a directory
`is_nil(`x`)`	Any	Boolean	True if the argument is undefined
`is_numeric(`x`)`	Any	Boolean	True if the argument is numeric
`is_string(`x`)`	Any	Boolean	True if the argument is a string
`item(`a`,`i`)`	Array	Any	Access a certain item of an array
`join(`a`,`s`)`	Array, String	String	Join all array members in a into a string using the separator s
`len(`x`)`	String	Numeric	Return the length of a string
`log10(`x`)`	Numeric	Numeric	Base 10 logarithm function
`log(`x`)`	Numeric	Numeric	Natural logarithm function
`max(`a`,`b ...`)`	Numeric	Numeric	Maximum of the given arguments
`min(`a`,`b ...`)`	Numeric	Numeric	Minimum of the given arguments
`path(`x`)`	String	String	Returns the path component of a file specification
`pow(`x`,`y`)`	Numeric	Numeric	Power function (x to the power of y)
`rfind(`s`,`t`)`	String	Numeric	Finds the last occurrence of a t in s and returns the position (where 0 is the first character)
`round(`x`)`	Numeric	Numeric	Round up or down
`sinh(`x`)`	Numeric	Numeric	Hyperbolic sine function
`sin(`x`)`	Numeric	Numeric	Sine function
`split(`t`,`s`)`	String	Array	Splits t into elements using the separator s
`sprintf(`f`,`a ...`)`	String, Any	String	Implement of 'C' sprintf. Provides not all features but the most commonly used ones (precision, field width, alignment, zero padding, 'e', 'g', 'f', 'd', 'x', 'u' and 's' formats)
`sqrt(`x`)`	Numeric	Numeric	Square root
`substr(`t`,`f[`,`l]`)`	String	String	Return a substring of t (starting from position f with length l). 'l' is optional. If omitted, the tail of the string is returned.
`sub(`s`,`x`,`y`)`	String	String	Substitute the first occurrence of a x in s by y
`tanh(`x`)`	Numeric	Numeric	Hyperbolic tangent function
`tan(`x`)`	Numeric	Numeric	Tangent function
`to_f(`x`)`	Any	Numeric	Convert argument to numeric if possible
`to_i(`x`)`	Any	Numeric (integer)	Convert argument to numeric (32 bit integer)
`to_s(`x`)`	Any	String	Convert argument to string