macros.conf

macros.conf

The following are the spec and example files for macros.conf.

macros.conf.spec

# Copyright (C) 2005-2010 Splunk Inc.  All Rights Reserved.  Version 4.1.5 
#
# This file contains possible attribute/value pairs for search language macros

# To learn more about configuration files (including precedence) please see the documentation 
# located at http://www.splunk.com/base/Documentation/latest/Admin/Aboutconfigurationfiles

[$STANZA_NAME]
	* Each stanza represents a search macro that can be referenced in any search
	* The stanza name is the name of the macro if the macro takes no arguments.  Otherwise,
	  the stanza name is the macro name append with "(<numargs>)", where <numargs> is the number of arguments that this macro takes.
	* macros may be overloaded so there can be [foobar] and [foobar(1)] and [foobar(2)] etc
	* macros can be used in the search language by enclosing the macro name and any argument list within tick marks, e.g. `foobar(arg1,arg2)` or `foobar`
	* no macro expansion are attempted inside of quoted values, e.g. "foo`bar`baz"

args = <string>
        * A comma delimited string of argument names.
	* Argument names may only contain the characters alphanumerics and underscore '_' and dash '-'
	* If the stanza name indicates this macro takes no arguments, this key will be ignored
	* It is an error if this list contains any repeated elements

definition = <string>
	* The string that the macro will expand to, with the arguments filled in. (exception if iseval = true, see below)
	* Arguments to be filled in must be wrapped by dollar signs $ e.g. "the last part of this string will be replaced by the value of argument foo $foo$"   
	* If a $ is not followed by the name of an argument (specified in the args list) followed by another $, it will be ignored and interpreted as a literal $
	* the $...$ pattern will be replace globally in the string, even inside of quotes
	
validation = <string>
	* A validation string that is an 'eval' expression.  This expression must statically either evaluate to a boolean or a string.
	* This validation is for verifying that the argument value used to invoke this macro are acceptable
	* If the validation expression is a boolean expression, validation succeeds when it returns true.  If it returns false or is null, validation fails, and the error message defined by 'errormsg' is returned.
	* If the validation expression is not a boolean expression, it is expected to return a string or null.  For this case, if it returns null, validation is considered a success.  Otherwise, the string returned is rendered as the error string.

errormsg = <string>
	* The error message to be displayed if validation is a boolean expression and it does not evaluate to true.

iseval = <true/false>
        * If true, 'definition' is expected to be an eval expression that returns a string that represents the expansion of this macro.
        * Defaults to false

macros.conf.example

# Copyright (C) 2005-2010 Splunk Inc.  All Rights Reserved.  Version 4.1.5
#
# Example macros.conf
#

# macro foobar that takes no arguments can be invoked via `foobar`
[foobar]
# the defintion of a macro can invoke another macro.  nesting can be indefinite and cycles will be detected and result in an error
definition = `foobar(foo=defaultfoo)`


# macro foobar that takes one argument, invoked via `foobar(someval)`
[foobar(1)]
args = foo
# note this is definition will include the leading and trailing quotes, i.e.
# something `foobar(someval)`
# would expand to
# something "foo = someval"
definition = "foo = $foo$"

# macro that takes two arguments
# note that macro arguments can be named so this particular macro could be invoked equivalently as
# `foobar(1,2)` `foobar(foo=1,bar=2)` or `foobar(bar=2,foo=1)`
[foobar(2)]
args = foo, bar
definition = "foo = $foo$, bar = $bar$"

# macro that takes one argument that does validation
[foovalid(1)]
args = foo
definition = "foovalid = $foo$"
# the validation eval function takes any even number of arguments (>=2) where the first argument is
# a boolean expression, the 2nd a string, the third boolean, 4th a string, etc etc etc
validation = validate(foo>15,"foo must be greater than 15",foo<=100,"foo must be <= 100")

# macro showing simple boolean validation, where if foo > bar is not true, errormsg is displayed
[foovalid(2)]
args = foo, bar
definition = "foo = $foo$ and bar = $bar$"
validation = foo > bar
errormsg = foo must be greater than bar

# example of an eval-based definition.  For example in this case `fooeval(10,20)` would get replaced by 10 + 20
[fooeval(2)]
args = foo, bar
definition = if (bar > 0, "$foo$ + $bar$", "$foo$ - $bar$")
iseval = true

• Was this topic useful?
• Post a comment