[comment]: # translation:outdated

[comment]: # ({0458cee0-0458cee0})
# 1 Macro functions

[comment]: # ({/0458cee0-0458cee0})

[comment]: # ({4aba217d-4aba217d})
#### Overview

Macro functions offer the ability to customize
[macro](/manual/config/macros) values.

Sometimes a macro may resolve to a value that is not necessarily easy to
work with. It may be long or contain a specific substring of interest
that you would like to extract. This is where macro functions can be
useful.

The syntax of a macro function is:

    {<macro>.<func>(<params>)}

where:

-   <macro> - the macro to customize (for example {ITEM.VALUE} or
    {\#LLDMACRO})
-   <func> - the function to apply
-   <params> - a comma-delimited list of function parameters.
    Parameters must be quoted if they start with '' '' (space), `"` or
    contain `)`, `,`.

For example:

    {{ITEM.VALUE}.regsub(pattern, output)}
    {{#LLDMACRO}.regsub(pattern, output)}

[comment]: # ({/4aba217d-4aba217d})

[comment]: # ({077c9a88-077c9a88})
#### Supported macro functions

|FUNCTION|<|<|<|<|
|--------|-|-|-|-|
|<|**Description**|**Parameters**|**Supported for**|<|
|**regsub** (<pattern>,<output>)|<|<|<|<|
|<|Substring extraction by a regular expression match (case sensitive).|**pattern** - the regular expression to match<br>**output** - the output options. **\\1 - \\9** placeholders are supported to capture groups. **\\0** returns the matched text.|{ITEM.VALUE}<br>{ITEM.LASTVALUE}<br>[Low-level discovery macros](/manual/config/macros/lld_macros) (except in low-level discovery rule filter)|<|
|**iregsub** (<pattern>,<output>)|<|<|<|<|
|<|Substring extraction by a regular expression match (case insensitive).|**pattern** - the regular expression to match<br>**output** - the output options. **\\1 - \\9** placeholders are supported to capture groups. **\\0** returns the matched text.|{ITEM.VALUE}<br>{ITEM.LASTVALUE}<br>[Low-level discovery macros](/manual/config/macros/lld_macros) (except in low-level discovery rule filter)|<|

If a function is used in a [supported
location](/manual/appendix/macros/supported_by_location), but applied to
a macro not supporting macro functions, then the macro evaluates to
'UNKNOWN'.

If pattern is not a correct regular expression then the macro evaluates
to 'UNKNOWN' (excluding low-level discovery macros where the function
will be ignored in that case and macro will remain unexpanded)

If a macro function is applied to the macro in locations not supporting
macro functions then the function is ignored.

[comment]: # ({/077c9a88-077c9a88})

[comment]: # ({d674d268-d674d268})
#### Examples

The ways in which macro functions can be used to customize macro values
is illustrated in the following examples containing log lines as
received value:

|Received value|Macro|Output|
|--------------|-----|------|
|`123Log line`|`{{ITEM.VALUE}.regsub(^[0-9]+, Problem)}`|`Problem`|
|`123 Log line`|`{{ITEM.VALUE}.regsub("^([0-9]+)", "Problem")}`|`Problem`|
|`123 Log line`|`{{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)}`|`Problem ID: 123`|
|`Log line`|`{{ITEM.VALUE}.regsub(".*", "Problem ID: \1")}`|''Problem ID: ''|
|`MySQL crashed errno 123`|`{{ITEM.VALUE}.regsub("^(\w+).*?([0-9]+)", " Problem ID: \1_\2 ")}`|'' Problem ID: MySQL\_123 ''|
|`123 Log line`|`{{ITEM.VALUE}.regsub("([1-9]+", "Problem ID: \1")}`|`*UNKNOWN*` (invalid regular expression)|
|`customername_1`|`{{#IFALIAS}.regsub("(.*)_([0-9]+)", \1)}`|`customername`|
|`customername_1`|`{{#IFALIAS}.regsub("(.*)_([0-9]+)", \2)}`|`1`|
|`customername_1`|`{{#IFALIAS}.regsub("(.*)_([0-9]+", \1)}`|`{{#IFALIAS}.regsub("(.*)_([0-9]+", \1)}` (invalid regular expression)|
|`customername_1`|`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \1)}"}`|`{$MACRO:"customername"}`|
|`customername_1`|`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \2)}"}`|`{$MACRO:"1"}`|
|`customername_1`|`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+\", \1)}"}`|`{$MACRO:"{{#M}.regsub(\"(.*)_([0-9]+\", \1)}"}` (invalid regular expression)|
|`customername_1`|`"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+)\\", \1)}\"}"`|`"{$MACRO:\"customername\"}"`|
|`customername_1`|`"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+)\\", \2)}\"}"`|`"{$MACRO:\"1\"}")`|
|`customername_1`|`"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}"`|`"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}")` (invalid regular expression)|

[comment]: # ({/d674d268-d674d268})