PML 2 Plugin Development Guide
Built-in Functions
This document describes the built-in functions and arithmetic operators available in PML 2 plugin conditions and action templates.
1. Overview
The function library is an important part of the PML 2 plugin system. When writing a plugin you can call built-in functions directly from condition expressions and action parameter templates to transform, compute and test context data such as ctx.data and ctx.variables — without writing any code.
The built-in functions are provided by the expression evaluator and cover string and collection handling, arithmetic, trigonometry and date/time operations. Function names are written in lower case; arguments are converted as needed and may be strings, numbers or collections.
In the sections below, the version marker next to a function means the function is available in that PML 2 version and later. Pick the functions that match the PML 2 version you actually use.
Where functions can be used
Built-in functions may appear in two places:
| Location | Syntax | Example |
|---|---|---|
Condition expression (condition) | Write the expression directly, without {{ }} | len(ctx.data.proxyName) > 0 -and upper(ctx.data.proxyName) -eq 'WEB' |
Action parameter template (params) | Wrap it in {{ expression }}; one string may embed several templates | msg: "Tunnel {{ctx.data.proxyName}} started (length {{len(ctx.data.proxyName)}})" |
If a function name is unknown, or the number or type of arguments is invalid, expression evaluation throws. The plugin engine records it as a log entry and the application will not crash, but that execution of the trigger fails. Always double-check function names and argument counts.
2. Function categories
| Category | Functions |
|---|---|
| String and collection | len, lower, upper, coalesce |
| Mathematical | abs, round, floor, ceil, sqrt, pow, min, max, ln, log10, log2, log |
| Trigonometric | sin, cos, tan, cot, sec, csc |
| Date and time | now, datetime.now.strftime |
3. Function reference
1. String and collection functions 26.3.1
| Function | Arguments | Description | Example |
|---|---|---|---|
len(x) | x: any | Returns a length or element count. null returns 0; a string returns its character count; a collection returns its element count; anything else returns the length of its string representation. | len("abcd") returns 4len(ctx.variables.list) returns the element count |
lower(s) | s: any | Converts the argument to a string and lower-cases it. null returns an empty string. | lower("Web") returns "web" |
upper(s) | s: any | Converts the argument to a string and upper-cases it. null returns an empty string. | upper("Web") returns "WEB" |
coalesce(a, b, ...) | one or more | Returns the first argument that is neither null nor an empty string; if all are empty it returns null. Commonly used to supply a default for a missing field. | coalesce(ctx.data.errorCategory, "timeout") returns "timeout" when the field is missing |
len works for both strings and collections, so the same function can measure a tunnel name or count list items.2. Mathematical functions
min and max are available since 26.3.1; the other mathematical functions are available since 26.5. All of them require arguments that can be parsed as numbers, otherwise an exception is thrown.
| Function | Arguments | Description | Example |
|---|---|---|---|
abs(x) | x: number | Returns the absolute value of x. | abs(-5) returns 5 |
round(x) | x: number | Rounds to nearest, ties to even (banker's rounding, i.e. .NET's default MidpointRounding.ToEven). | round(4.5) returns 4round(5.5) returns 6 |
floor(x) | x: number | Returns the largest integer less than or equal to x. | floor(4.9) returns 4 |
ceil(x) | x: number | Returns the smallest integer greater than or equal to x. | ceil(4.2) returns 5 |
sqrt(x) | x: number | Returns the square root of x. | sqrt(9) returns 3 |
pow(x, y) | x, y: number | Returns x raised to the power of y. | pow(2, 10) returns 1024 |
min(a, b, ...) | two or more numbers | Returns the smallest value. | min(3, 5) returns 3 |
max(a, b, ...) | two or more numbers | Returns the largest value. | max(3, 5) returns 5 |
ln(x) | x: number | Returns the natural logarithm (base e). | ln(1) returns 0 |
log10(x) | x: number | Returns the common logarithm (base 10). | log10(100) returns 2 |
log2(x) | x: number | Returns the base-2 logarithm. | log2(8) returns 3 |
log(x, base) | x, base: number | Returns the logarithm with the given base; base must be greater than 0. | log(8, 2) returns 3 |
3. Trigonometric functions 26.5
| Function | Arguments | Description | Example |
|---|---|---|---|
sin(x) | x: number | Returns the sine. | sin(0) returns 0 |
cos(x) | x: number | Returns the cosine. | cos(0) returns 1 |
tan(x) | x: number | Returns the tangent. | tan(0) returns 0 |
cot(x) | x: number | Returns the cotangent, i.e. 1 / tan(x). | cot(1) |
sec(x) | x: number | Returns the secant, i.e. 1 / cos(x). | sec(1) |
csc(x) | x: number | Returns the cosecant, i.e. 1 / sin(x). | csc(1) |
The default parameter for trigonometric functions is in the degree system. If the second parameter is passed as
"true", the calculation will be performed in the radian system. Before evaluation, the \pi in the parameters will be replaced with the numerical value of the mathematical constant π to facilitate the writing of constants containing π.4. Date and time functions
now is available since 26.3.1; datetime.now.strftime is available since 26.5.
| Function | Arguments | Description | Example |
|---|---|---|---|
now | none | Returns the current UTC time as a Unix timestamp (seconds). | now returns 1759456000 |
datetime.now.strftime(format) | format (optional): string | Returns the current local time as a formatted string; when format is omitted the pattern yyyy-MM-dd HH:mm:ss is used. | datetime.now.strftime("yyyy/MM/dd") returns 2026/10/03 |
Although
datetime.now.strftime contains strftime in its name, its format string follows .NET's custom date and time format strings and is not Python / C strftime syntax.4. Arithmetic operators
Besides function calls, PML 2 expressions support arithmetic, and parentheses () can change precedence. The arithmetic operators are available since 26.3.1.
| Operator | Description | Example |
|---|---|---|
+ | Addition: the sum of both sides. | ctx.variables.count + 5 |
- | Subtraction: the difference of both sides. | ctx.variables.count - 5 |
* | Multiplication: the product of both sides. | ctx.variables.count * 5 |
/ | Division: the quotient of both sides (floating point). | 5 / 2 returns 2.5 |
% | Modulo: the remainder of both sides. | 7 % 3 returns 1 |
** or ^ | Exponentiation: the left value raised to the power of the right value. | 2 ** 10 returns 1024 |
// | Integer division: the quotient of both sides rounded down. | 7 // 2 returns 3 |
Arithmetic operators require numeric operands; a string operand is first parsed as a number and throws if parsing fails. Operators and built-in functions can be combined freely, for example
max(len(ctx.data.proxyName), 3) * 2.5. Complete example
The example below is taken from the official sample plugin tech.rycb.plugin.demo-functions.yaml and shows built-in functions and arithmetic in condition expressions and action parameter templates:
triggers:
# Log when the tunnel name is longer than 0 characters and equals "web" ignoring case
- on: proxy.start
condition: "len(ctx.data.proxyName) > 0 -and upper(ctx.data.proxyName) -eq 'WEB'"
actions:
- name: log
params:
msg: "Tunnel {{ctx.data.proxyName}} started (name length {{len(ctx.data.proxyName)}})"
# Treat a missing failure category as timeout, and notify only when retries are at most 3
- on: proxy.failed
condition: "coalesce(ctx.data.errorCategory, 'timeout') -eq 'timeout' -and min(ctx.variables.retryCount, 3) -le 3"
actions:
- name: notify
params:
msg: "Tunnel {{ctx.data.proxyName}} failed: {{ctx.data.errorMessage}}"