StyleBook configuration

View PDF

Built-in functions

August 29, 2024

Contributed by:

C C

Expressions in StyleBooks can use built-in functions.

For example, you can use the built-in function, str() to transform a number to a string.

str($parameters.order)

Or, you can use the built-in function, int() to transform a string into an integer.

int($parameters.priority)

The following is the list of built-in functions supported in StyleBook expressions with examples of how they can be used:

str()

The str() function transforms the input argument to a string value.

Allowed argument types:

string
number
tcp-port
boolean
ipaddress

Examples:

The "set-" + str(10) function returns "set-10".
The str(10) function returns 10.
The str(1.1.1.1) function returns 1.1.1.1.
The str(True) function returns "True".
The str(NetScaler Console) function returns "NetScaler Console".

int()

The int() function takes a string, number, IP address, or tcpport as an argument and returns an integer.

Examples:

The int("10") function returns 10.
The int(10) function returns 10.
The int(ip('0.0.4.1')) function returns 1025.

bool()

The bool() function takes any type as an argument. If the argument value is false, empty, or absent, this function returns false.

Otherwise, it returns true.

Examples:

The bool(true) function returns true.
The bool(false) function returns false.
The bool($parameters.a) function returns false if the $parameters.a is false, empty, or absent.

len()

The len() function takes a string or a list as an argument, and returns the number of characters in a string or the number of items in a list.

Example 1:

If you define a substitution as follows:

items: ["123", "abc", "xyz"]

The len($substitutions.items) function returns 3

Example 2:

The len("NetScaler Console") function returns 10.

Example 3:

If $parameters.vips has values ['1.1.1.1', '1.1.1.2', '1.1.1.3'], the len($parameters.vips) function returns 3.

min()

The min() function takes either a list or a series of numbers or TCP ports as arguments, and returns the smallest item.

Examples with a series of numbers/TCP ports:

The min(80, 100, 1000) function returns 80.
The min(-20, 100, 400) function returns -20.
The min(-80, -20, -10) function returns -80.
The min(0, 100, -400) function returns -400.

Examples with a list of numbers/TCP ports:

Support $parameters.ports is a list of TCP ports and has values: [80, 81, 8080].

The min($parameters.ports) function returns 80.

max()

The max() function takes either a list or a series of numbers or TCP ports as arguments, and returns the largest item.

Examples with a series of numbers/TCP ports:

The max(80, 100, 1000) function returns 1000.
The max(-20, 100, 400) function returns 400.
The max(-80, -20, -10) function returns -10.
The max(0, 100, -400) function returns 100.

Examples with a list of numbers/TCP ports:

Support $parameters.ports is list of TCP ports and has values: [80, 81, 8080].

The max($parameters.ports) function returns 8080.

bin()

The bin() function takes a number as an argument, and returns a string that represents the number in binary format.

Examples of expressions:

The bin(100) function returns 0b1100100.

oct()

The oct() function takes a number as an argument, and returns a string that represents the number in octal format.

Examples of expressions:

The oct(100) function returns 0144.

hex()

The hex() function takes a number as an argument, and returns a lowercase string that represents the number in hexadecimal format.

Examples of expressions:

The hex(100) function returns 0x64.

lower()

The lower() function takes a string as an argument and returns the same string in the lowercase.

Example:

The lower("NetScaler Console") function returns NetScaler Console.

upper()

The upper() function takes a string as an argument and returns the same string in uppercase.

Example:

The upper("NetScaler Console") function returns NetScaler Console.

sum()

The sum() function takes a list of numbers or tcpports as arguments and returns the sum of the numbers in the list.

Example 1:

If you define a substitution as follows: substitutions:

list-of-numbers = [11, 22, 55]

The sum($substitutions.list-of-numbers) function returns 88.

Example 2:

If $parameters.ports is [80, 81, 82], the sum($parameters.ports) function returns 243.

pow()

The pow() function takes two numbers as arguments and returns a number that represents the first argument raised to the power of the second one.

Example:

The pow(3,2) function returns 9.

ip()

The ip() function takes an integer, string, or an IP address as an argument and returns the IP address based on the input value.

Examples:

Specify an IP address in the ip function:

The ip(3.1.1.1) function returns 3.1.1.1.
Specify a string in the ip function:

The ip('2.1.1.1') function returns 2.1.1.1
Specify an integer in the ip function:
- The ip(12) function returns 0.0.0.12.
- When you specify an integer as string in the ip function, it returns an equivalent IP address of the input.
  
  The ip('1025') function returns 0.0.4.1.
This function also supports the integer addition and subtraction operations and returns a resultant IP address.
- Addition: The ip(1025) + ip(12) function returns 0.0.4.13.
- Subtraction: The ip('1025') - ip(12) function returns 0.0.3.245.
- Combine addition and subtraction: The ip('1.1.1.1') + ip('1.1.1.1') – ip(2) returns 2.2.2.0.

ip_network()

The ip_network function takes IP address and netmask length as arguments and returns an IP network notation.

Example-1:

The ip_network(1.1.1.1, 28) function returns 1.1.1.1/28.

Example-2:

Consider the value 1.1.1.1 for $parameters.ipaddr. The ip_network($parameters.ipaddr, 30) function returns 1.1.1.1/30.

Example-3:

Consider the value 24 for $parameters.netmask-len. The ip_network(23.1.12.76, $parameters.netmask-len) function returns 23.1.12.76/24.

network_ip()

The network_ip() function returns the first IP address of the specified IP network.

Example:

The network_ip(1.1.1.1/28) function returns 1.1.1.0. In this example, 1.1.1.0 is the first IP address in the given network.

subnets()

The subnets() function returns the list of subnets from the specified IP network and netmask length.

Example:

The subnets(1.1.1.1/28, 30) function returns the subnets list from the given IP network and netmask length. The output can be as follows:

[1.1.1.0/30', '1.1.1.4/30', '1.1.1.8/30', '1.1.1.12/30']

netmask_ip()

The netmask_ip() function returns the netmask IP address for the specified IP network.

Example:

The netmask_ip(1.1.1.1/28) function returns 255.255.255.240. For the given IP network, 255.255.255.240 is the netmask IP address.

is_netmask_ip()

The is_netmask_ip() function accepts an ipaddress as an input. And, it returns True if the specified value is a valid netmask IP address.

Example 1:

The is_netmask_ip(255.255.255.240) function returns True because the specified value is a valid netmask IP address.

Example 2:

The is_netmask_ip(255.255.255.232) function returns False because the specified value is not a valid netmask IP address.

broadcast_ip()

The broadcast_ip() function returns the broadcast IP address for the specified IP network.

Example:

The broadcast_ip(1.1.1.1/28) function returns 1.1.1.15. For the given IP network, 1.1.1.15 is the broadcast IP address.

cidr()

The cidr() function returns the CIDR notation for the specified IP network.

Example:

The cidr(1.1.1.1/28) function returns the 1.1.1.0/28. For the given IP network, 1.1.1.0/28 is the CIDR notation.

is_cidr()

The is_cidr() function accepts an ipnetwork as an input. And, it returns True if the specified value matches the CIDR notation of the IP network.

Example-1:

The is_cidr(1.1.1.0/24) function returns True because the specified value is the CIDR notation of the given network.

Example-2:

The is_cidr(1.1.1.1/28) function returns False because the CIDR notation of the given network is different than the specified value.

is_in_network()

The is_in_network() function accepts ipnetwork and ipaddress values. And, it returns True if the specified IP address exists in the specified IP network.

Example-1:

The is_in_network(1.1.1.1/24, 1.1.1.121) function returns True because the 1.1.1.121 address is part of the 1.1.1.1/24 network.

Example-2:

The is_in_network(1.1.1.1/28, 2.1.1.1) function returns Fasle because the 2.1.1.1 address is not part of the 1.1.1.1/28 network.

base64.encode()

The base64.encode() function takes a string argument and returns the base64 encoded string.

Example:

The base64.encode("abcd") function returns YWJjZA==.

base64.decode()

The base64.decode function takes a base64 encoded string as an argument and returns the decoded string.

Example:

The base64.decode("YWJjZA==") function returns abcd.

exists()

The exists() function takes an argument of any type and returns a boolean. The return value is True if the input has any value. The return value is False If the input argument does not have a value (that is, no value).

Consider that the $parameters.monitor is an optional parameter. If you provide a value to this parameter when creating a configuration pack, exist the ($parameters.monitor) function returns True.

Otherwise, it returns False.

filter()

The filter() function takes two arguments.

Argument 1: a substitution function that takes one argument and returns a Boolean value.

Argument 2: a list.

The function returns a subset of the original list where each element evaluates to True when passed to the substitution function in the first argument.

Example:

Suppose we have defined a substitution function as follows.

Substitutions:

x(a): $a != 81

This function returns True if the input value is not equal to 81. Otherwise, it returns False.

Suppose,$parameters.ports is [81, 80, 81, 89].

The filter($substitutions.x, $parameters.ports) returns [80, 89] by removing all occurrences of 81 from the list.

if-then-else()

The function if-then-else() takes three arguments.

Argument 1: a Boolean expression

Argument 2: any expression

Argument 3: any expression (optional)

If the expression in argument 1 evaluates to True, the function returns the value of the expression provided as argument 2.

Otherwise, if argument 3 is provided, the function returns the value of the expression in argument 3.

If argument 3 is not provided, the function returns no.

Example 1:

The if-then-else($parameters.servicetype == HTTP, 80, 443) function returns 80 if $parameters.servicetype has value HTTP. Otherwise, the function returns 443.

Example 2:

The if-then-else($parameters.servicetype == HTTP, $parameters.hport, $parameters.sport) function returns the value of $parameters.hport if $parameters.servicetype has value HTTP.

Otherwise, the function returns the value of $parameters.sport.

Example 3:

The if-then-else($parameters.servicetype == HTTP, 80) returns 80 if $parameters.servicetype has value HTTP.

Otherwise, the function does not return any value.

join()

The join() function takes two arguments:

Argument 1: a list of number, tcp-port, string, ipaddress

Argument 2: a delimiter string (optional)

This function joins the elements of the list provided as argument 1 into a string, where each element is separated by the delimiter string provided as argument 2. If argument 2 is not provided, then the elements in the list are joined as one string.

Example:

$parameters.ports is [81, 82, 83].
- With delimiter argument:
  
  The join($parameters.ports, '-') function returns 81-82-83.
- Without delimiter argument:
  
  The join($parameters.ports) function returns 818283.

split()

The split() function splits an input string into multiple lists depending on the specified separators. If no or blank ('') separator is specified, this function considers space as a separator and splits the string into lists.

Examples:

The split('Example_string_split', 's') function returns ['Example_','tring_','plit'].
The split('Example string split') function returns ['Example','string','split'].
The split('Example string split', '') function returns ['Example','string','split'].
The split('Example string') function returns ['Example','string'].

This function considers continuous spaces as one space.

map()

The map() function takes two arguments;

Argument 1: any function

Argument 2: a list of elements

The function returns a list where each element in the list is the result of applying the map() function (argument 1) to the corresponding element in argument 2.

Allowed functions in argument 1:

Built-in functions that take one argument:

base64.encode, base64.decode, bin, bool, exists, hex, int, ip, len, lower, upper, oct, quotewrap, str, trim, upper, url.encode, url.decode
Substitution functions that take at least one argument.

Example:

Suppose $parameters.nums is [81, 82, 83].

Map using a built-in function, str

The map(str, $parameters.nums) function returns ["81", "82", "83"]

The result of the map function is the list of strings where each element is string is computed by applying the str function on the corresponding element in the input list ($parameters.nums).
Map using a substitution function
- Substitutions:
  
  add-10(port): $port + 10
- Expression:
  
  The map($substitutions.add-10, $parameters.nums) function returns a list of numbers: [ 91, 92, 93 ]

The result of this map function is a list of numbers. Each element is computed by applying the substitution function $substitutions.add-10 on the corresponding element in the input list ($parameters.nums).

quotewrap()

The quotewrap() function takes a string as an argument and returns a string after adding a double quote character before and after the input value.

Example:

The quotewrap("NetScaler Console") function returns "NetScaler Console"

replace()

The replace() function takes three arguments:

Argument 1: a string or list of the following built-in types:

string
number
ipaddress
tcp-port
boolean

Argument 2: a single value or a list of values whose type matches the type specified in argument 1

Argument 3: a single value of the same type as specified in argument 1 (optional)

The replace() function replaces all occurrences of argument 2 with argument 3 in argument 1.

If argument 3 is not provided, all occurrences of argument 2 are removed from argument 1.

Example:

replace('abcdef', 'def', 'xyz') function returns abcxyz.

All occurrences of def are replaced with xyz.
replace('abcdefabc', 'def') returns abcabc.

As there is no argument 3, def is removed from the resulting string.
replace('An#example@to%replace!characters', ['@', '#', '!', '%'], '_') function returns An_example_to_replace_characters.

The output string has underscore (_) instead of the characters specified in ['@', '#', '!', '%'].
replace([10.10.10.1, 10.10.10.2, 10.10.10.3, 10.10.10.4], [10.10.10.2, 10.10.10.4]) function returns [10.10.10.1, 10.10.10.3].

As there is no argument 3, 10.10.10.2 and 10.10.10.4 are removed from the resulting list of IP addresses.
replace([8080, 8081, 8082, 8083, 8084], 8083, 80) function returns [8080, 8081, 8082, 80, 8084].

All occurrences of 8083 are replaced with 80.

trim()

The trim() function returns a string where the leading and trailing whitespaces are stripped from the input string.

Example:

The trim(' abc ') function returns abc.

truncate()

The truncate() function takes two arguments:

Argument 1: a string

Argument 2: a number

The function returns a string where the input string in argument 1 is truncated to the length specified by argument 2.

Example:

The truncate('NetScaler Console', 6) returns Citrix.

distinct()

The distinct() function extracts unique items from a list input.

Examples: If $parameters.input_list is ['ADC', 'VPX', 'ADC', 'CPX'], the distinct($parameters.input_list) function returns ['ADC', 'VPX', 'CPX'].

url.encode()

The url.encode() function returns a string where characters are transformed using the ASCII character set according to RFC 3986.

Example:

The url.encode("a/b/c") function returns a%2Fb%2Fc.

url.decode()

The url.decode() function returns a string where the URL encoded argument is decoded in to a regular string according to RFC 3986.

Example:

The url.decode("a%2Fb%2Fc") function returns a/b/c.

is-ipv4()

The is-ipv4() function takes an IP address as an argument and returns the boolean True if the IP address is of the IPv4 format.

The is-ipv4(10.10.10.10) function returns True

is-ipv6()

The is-ipv6() function takes an IP address as an argument and returns the boolean True if the IP address is of the IPv6 format.

The is-ipv6(2001:DB8::) function returns True

startswith()

The startswith() function determines whether a string begins with a given prefix. This function requires two mandatory string arguments.

startswith(str, sub_str)

This function returns True when the string (str) starts with the substring (sub_str).

Examples:

The startswith('Citrix', 'Ci') function returns True.
The startswith('Citrix', 'iC') function returns False
The startswith('Citrix', 'Ab') function returns False

endswith()

The endswith() function determines whether a string ends with a given suffix. This function requires two mandatory string arguments.

endswith(str, sub_str)

This function returns True when the string (str) ends with the substring (sub_str).

Examples:

The endswith('Citrix', 'ix') function returns True.
The endswith('Citrix', 'Ix') function returns False.
The endswith('Citrix', 'ab') function returns False.

contains()

The contains() function determines whether a string contains a given substring. This function requires two mandatory string arguments.

Allowed argument types:

string
number
tcp-port
boolean
ipaddress

contains(str, sub_str)

This function returns True when the substring (sub_str) is contained anywhere inside the string (str).

Examples:

The contains('Citrix', 'tri') function returns True.
The contains('Citrix', 'Ci') function returns True.
The contains('Citrix', 'ti') function returns False

You can also use this function to check whether a given item belongs to the list.

Example:

list_of_strings = [“Citrix”, “Core”, ”Values”, ”Integrity”]

contains($parameters.list_of_strings, “Values”)
<!--NeedCopy-->

In this example, the contains() function returns True because the list has the Values item in it.

substring()

Use the substring() function to extract a substring from a string.

substring(str, start_index, end_index)

This function requires the two mandatory arguments and one optional integer argument.

str (Mandatory)
start_index (Mandatory)
end_index (Optional)

This function returns the substring from the string (str) that is between the specified index positions. If you do not specify the end index position, the function extracts the substring from the start index to the end of the string.

Note

When you specify end_index, the substring excludes the character at the end_index position.

Example:

The substring('Citrix', 2) function returns trix
The substring('Citrix', 10) function returns (")

In this example, the function returns a blank string because it has an invalid start_index position.
The substring('Citrix', 2, 4) function returns tr

In this example, the function extracts the characters between 2 and 4 index positions.
The substring('Citrix', -3) function returns rix

If you want to extract characters that are at the end of the string, specify a negative value for the start_index argument.

In this example, the function extracts the substring that includes the last three characters in the string.

match()

The match() function checks whether an input string matches the defined regular expression pattern. This function accepts regular expression pattern and search strings as arguments. Optional, you can also specify a Boolean type to ignore case sensitive patterns.

Examples:

The match(“^[A-Z0-9]{2}_[A-Z0-9]{2,10}$”, “A2_B2”) returns True.
The match(“^[A-Z0-9]{2}_[A-Z0-9]{2,10}$”, “a2_b2”) returns False.
The match(“^[A-Z0-9]{2}_[A-Z0-9]{2,10}$”, “a2_B2”, $parameters.ignore_case) returns True.

sha256()

Use this function to compute the SHA-256 hash for any string. This function accepts a string input of any length and returns a hash string of fixed length (64 characters).

Example:

components:
    -
        name: lbvserver-comp
        type: ns::lbvserver
        properties:
            name: sha256(lbserver-name)
            servicetype: SSL
            ipv46: 10.10.10.10
<!--NeedCopy-->

In this example, lbserver-name appears as a hash string on the NetScaler object.

This function can also accept expressions as an input.

Example:

components:
    -
        name: lbvserver-comp
        type: ns::lbvserver
        properties:
            name: sha256($parameters.lb-appname)
            servicetype: SSL
            ipv46: 10.10.10.10
<!--NeedCopy-->

relate()

The relate() function forms a list of dictionary objects from a set of lists.

It takes two arguments:

Argument 1: A list of strings which represent key names.

Argument 2: A list of lists, where each list has the values of the corresponding key names in argument 1. Each list in argument 2 must be of the same length. The number of lists in argument 2 should be equal to the number of strings in argument 1.

Example:

name: test_relate_3
description: "Hello World StyleBook."
namespace: com.citrix.adc.stylebooks
schema-version: "1.0"
version: "1.1"

import-stylebooks:
    -
        namespace: netscaler.nitro.config
        prefix: ns
        version: "10.5"
    -
        namespace: com.citrix.adc.stylebooks
        prefix: stlb
        version: "1.0"
        parameters:
    -
        name: namesofservers
        description: "Provide the names of LB VServers"
        type: string[]
    -
        name: listofips
        description: "Provide the list of IP Addresses"
        type: string[]
    -
        name: list_of_keys
        type: string[]
        default:
        - "name"
        - "ip"

    substitutions:
        list_of_values: [$parameters.namesofservers,$parameters.listofips]
    components:
    -
        name: svc-comp
        type: object
        properties:
        svcdetails: relate($parameters.list_of_keys,$substitutions.list_of_values)

    -
        name: lb-comp
        type: ns::lbvserver
        repeat: $components.svc-comp.properties.svcdetails
        repeat-item: svcd
        properties:
            name: $svcd['name']
            servicetype: HTTP
            ipv46: $svcd['ip']
            port: 80
<!--NeedCopy-->

In this example:

The parameters section has a list called list_of_keys which has name and ip.
The substitutions section has a list called list_of_values which has the following two lists:
- A list of virtual server names (string)
- A list of IP addresses (string).

The relate() built-in function accepts the list_of_keys and list_of_values as the arguments. The function then creates a list of dictionary objects where each object has a name from the first list and an IP address from the second list.

If you provide the following list of virtual servers:

["lb1","lb2"]
<!--NeedCopy-->

and a list of virtual server IP addresses as:

["1.1.1.1","2.2.3.3"]
<!--NeedCopy-->

Therelate() function then returns the following lists:

[\{"name": "lb1", "ip": "1.1.1.1"},\{"name": "lb2", "ip": "2.2.3.3"}]
<!--NeedCopy-->

The StyleBook iterates over this list of dictionary objects, in the components section, to create the corresponding virtual servers.

multiple()

The multiple() function takes two arguments:

Argument 1: a number, string, boolean, ipaddress, tcp-port, or password

Argument 2: a number

The multiple(argument1, argument2) function returns a list with many copies of argument 1. The number of copies is equal to the number passed to argument 2.

Examples:

The multiple(10.10.10.10, 3) function returns [10.10.10.10, 10.10.10.10, 10.10.10.10].
The multiple(8080, 4) function returns [8080, 8080, 8080, 8080].

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Built-in functions

August 29, 2024

Contributed by:

C C

August 29, 2024

Contributed by:

C C

Built-in functions

str()

int()

bool()

len()

min()

max()

bin()

oct()

hex()

lower()

upper()

sum()

pow()

ip()

ip_network()

network_ip()

subnets()

netmask_ip()

is_netmask_ip()

broadcast_ip()

cidr()

is_cidr()

is_in_network()

base64.encode()

base64.decode()

exists()

filter()

if-then-else()

join()

split()

map()

quotewrap()

replace()

trim()

truncate()

distinct()

url.encode()

url.decode()

is-ipv4()

is-ipv6()

startswith()

endswith()

contains()

substring()

match()

sha256()

relate()

multiple()

In this article