Expression Functions¶
Content Chimera provides a comprehensive set of functions that can be used in expressions for data transformation and analysis. These functions are grouped into several categories for different types of operations:
Syntax Guidelines¶
When writing expressions, please follow these formatting conventions:
Strings should be wrapped in double quotes (like “drop”)
Fields should be surrounded in backticks (like folder1)
Map names should be in double quotes (like “folder1_to_content_type”)
Choosing the right function¶
Different functions serve different purposes. Here’s a quick guide for common scenarios:
For text manipulation, use the Text Processing Functions like
text_transform,regex, orxpath.For numerical calculations, use the Mathematical Functions like
avg,sum, or basic arithmetic operations.For conditional logic, use the Logical Functions like
if,case, or boolean operations.For value lookups, use the Mapping Functions like
map.
Comparison of function types¶
This is a brief comparison of the function categories available:
Primary Use |
Examples |
Common Use Cases |
|
|---|---|---|---|
Simple Comparison |
Simple comparisons |
=, <, > |
Matching field values, for instance in if statements |
Text Processing |
Manipulating and extracting text |
text_transform, regex, xpath |
Cleaning HTML, extracting patterns |
Mathematical |
Numerical calculations |
avg, sum, min, max, +, -, / |
Aggregating values, calculating metrics |
Logical |
Conditional operations |
if, case, and, or, not |
Decision making, branching logic |
Mapping |
Value lookups |
map |
Normalizing values, categorization |
Simple Comparison Functions¶
The following can be used for comparisons as simple functions: =, <, >. Note that == is NOT used for comparison.
Text Processing Functions¶
text_transform¶
Transforms HTML text by cleaning it up, removing unnecessary attributes and tags.
Parameters:
text (required): The HTML text to transform
transformer_id (optional): Specific transformer ID to use
Returns: Transformed text with HTML cleaned up
Example:
text_transform("<p style='color: red'>Hello</p>")
// Returns: <p>Hello</p>
Special considerations: When no specific transformer is provided, a generic transformer is used. This function is useful for cleaning up HTML content before display or analysis.
xpath¶
Extracts values from HTML using XPath queries.
Parameters:
html (required): The HTML to parse
xpath_query (required): XPath query to execute
Returns: Comma-separated list of matching node values
Example:
xpath("<div><p>Hello</p><p>World</p></div>", "//p")
// Returns: Hello,World
Special considerations: Uses PHP’s DOMDocument and DOMXPath for parsing. Internal errors during HTML parsing are suppressed.
regex / regexall¶
Pattern matching with optional capture groups.
Parameters:
string (required): Text to search in
pattern (required): Regular expression pattern
Returns:
For regex: First capture group match or true/false if no capture group
For regexall: All capture group matches concatenated or true/false if no capture group
Example:
regex("hello123world", "/\\d+/")
// Returns: true, since there is a match but no capture group (in parentheses)
regex("hello123world", "/hello(\\d+)world/")
// Returns: 123
Special considerations: Make sure to properly escape regular expression patterns (including with a leading and trailing slahs). The regex function returns only the first match, while regexall returns all matches.
substring¶
Extracts a portion of a string.
Parameters:
string (required): Source string
start (required): Starting position
length (required): Number of characters to extract
Returns: Extracted substring
Example:
substring("hello world", 0, 5)
// Returns: hello
char_count¶
Counts characters in a string.
Parameters:
string (required): Text to count
Returns: Number of characters
Example:
char_count("hello")
// Returns: 5
Special considerations: Uses PHP’s mb_strlen function to properly handle multi-byte characters.
word_count¶
Counts words in a string.
Parameters:
string (required): Text to count
Returns: Number of words
Example:
word_count("hello world")
// Returns: 2
Special considerations: Uses a custom implementation (Utilities::mb_str_word_count) to handle multi-byte characters.
trim¶
Removes whitespace from string edges.
Parameters:
string (required): Text to trim
Returns: Trimmed string
Example:
trim(" hello ")
// Returns: hello
starts_with / starts_with_any¶
Checks if string starts with pattern(s).
Parameters:
string (required): Text to check
pattern(s) (required): Single pattern or comma-separated patterns for _any variant
Returns: Boolean true/false
Example:
starts_with("hello world", "hello")
// Returns: true
starts_with_any("hello world", "hi,hello,hey")
// Returns: true
contains / contains_any¶
Checks if string contains pattern(s).
Parameters:
string (required): Text to check
pattern(s) (required): Single pattern or comma-separated patterns for _any variant
Returns: Boolean true/false
Example:
contains("hello world", "world")
// Returns: true
contains_any("hello world", "earth,world,mars")
// Returns: true
concat¶
Concatenates multiple strings.
Parameters:
strings (required): Two or more strings to concatenate
Returns: Concatenated string
Example:
concat("hello", " ", "world")
// Returns: hello world
parse_url¶
Parses URL components.
Parameters:
url (required): URL to parse
component (required): Component to extract (host, scheme, path, query, or fragment)
Returns: Requested URL component or error message
Example:
parse_url("https://example.com/path?q=1", "host")
// Returns: example.com
Special considerations: Returns error messages if URL parsing fails or if the requested component doesn’t exist in the URL.
Mathematical Functions¶
avg / avg_zn¶
Calculates average of values.
Parameters:
values (required): Numbers to average
Returns:
avg: Average excluding null/empty values
avg_zn: Average including null/empty values as zero
Example:
avg(1, 2, null, 3)
// Returns: 2
avg_zn(1, 2, null, 3)
// Returns: 1.5
Special considerations: avg ignores null and empty values completely, while avg_zn counts them as zero in the calculation.
sum¶
Sums numeric values.
Parameters:
values (required): Numbers to sum
Returns: Sum of values
Example:
sum(1, 2, 3)
// Returns: 6
Special considerations: Null and empty values are ignored in the calculation.
min¶
Returns minimum value.
Parameters:
values (required): Numbers to compare
Returns: Minimum value
Example:
min(1, 2, 3)
// Returns: 1
max¶
Returns maximum value.
Parameters:
values (required): Numbers to compare
Returns: Maximum value
Example:
max(1, 2, 3)
// Returns: 3
round¶
Rounds a number.
Parameters:
number (required): Number to round
Returns: Rounded integer
Example:
round(1.6)
// Returns: 2
Special considerations: Returns null if the input is null or empty.
Arithmetic Operations¶
Basic arithmetic operations: divide (/), add (+), subtract (-), multiply (*).
Parameters:
number1 (required): First number
number2 (required): Second number
Returns: Result of arithmetic operation
Special considerations: Division by zero will raise an error.
Example:
10 / 2
// Returns: 5
3 + 4
// Returns: 7
5 - 2
// Returns: 3
6 * 2
// Returns: 12
counta¶
Counts non-empty values.
Parameters:
values (required): Values to count
Returns: Count of non-empty values
Example:
counta(1, null, "", 3)
// Returns: 2
Logical Functions¶
if¶
Conditional execution.
Parameters:
condition (required): Boolean condition
true_value (required): Value if condition is true
false_value (optional): Value if condition is false (null if omitted)
Returns: Selected value based on condition
Example:
if(5 > 3, "yes", "no")
// Returns: yes
ifnull / isnull¶
Null value handling.
Parameters:
For ifnull:
test_value (required): Value to test
if_null_value (required): Value to return if test_value is null
if_not_null_value (optional): Value to return if test_value is not null
For isnull:
value (required): Value to test
Returns:
ifnull: Selected value based on null test
isnull: Boolean indicating if value is null
Example:
ifnull(null, "was null", "not null")
// Returns: was null
isnull(null)
// Returns: true
case¶
Multiple condition handling.
Parameters:
condition1, value1, condition2, value2, …, default_value
Returns: First value whose condition is true, or default_value if no conditions are true
Example:
case(x > 10, "high", x > 5, "medium", "low")
and¶
Logical AND operation.
Parameters:
conditions (required): Two or more conditions
Returns: true if all conditions are true, false otherwise
Example:
and(5 > 3, 2 < 4)
// Returns: true
or¶
Logical OR operation.
Parameters:
conditions (required): Two or more conditions
Returns: true if any condition is true, false otherwise
Example:
or(5 < 3, 2 < 4)
// Returns: true
not¶
Logical NOT operation.
Parameters:
condition (required): Condition to negate
Returns: Opposite of the condition’s boolean value
Example:
not(5 < 3)
// Returns: true
Special Constants¶
Special constant values for logical operations:
true: Boolean true value
false: Boolean false value
null: Null value
now: Current date and time
Example:
if(true, "always", "never")
// Returns: always
Mapping Functions¶
map¶
Looks up values in defined mappings.
Parameters:
map_name (required): Name of the mapping to use
lookup_value (required): Value to look up in the mapping
Returns: Mapped value or null if not found
Special considerations:
Map must be defined and valid for the current extent
Returns null if the map is not valid for the current extent
Example:
map("content_type_map", "article")
// Returns: mapped value for "article" in content_type_map
