1 # <a id="library-reference"></a> Library Reference
3 ## <a id="global-functions"></a> Global functions
6 --------------------------------|-----------------------
7 regex(pattern, text) | Returns true if the regex pattern matches the text, false otherwise.
8 match(pattern, text) | Returns true if the wildcard pattern matches the text, false otherwise.
9 cidr_match(pattern, ip) | Returns true if the CIDR pattern matches the IP address, false otherwise. IPv4 addresses are converted to IPv4-mapped IPv6 addresses before being matched against the pattern.
10 len(value) | Returns the length of the value, i.e. the number of elements for an array or dictionary, or the length of the string in bytes.
11 union(array, array, ...) | Returns an array containing all unique elements from the specified arrays.
12 intersection(array, array, ...) | Returns an array containing all unique elements which are common to all specified arrays.
13 keys(dict) | Returns an array containing the dictionary's keys.
14 string(value) | Converts the value to a string.
15 number(value) | Converts the value to a number.
16 bool(value) | Converts the value to a bool.
17 random() | Returns a random value between 0 and RAND_MAX (as defined in stdlib.h).
18 log(value) | Writes a message to the log. Non-string values are converted to a JSON string.
19 log(severity, facility, value) | Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`, `LogInformation`, `LogWarning`, and `LogCritical`. Non-string values are converted to a JSON string.
20 typeof(value) | Returns the type object for a value.
21 get_time() | Returns the current UNIX timestamp.
22 parse_performance_data(pd) | Parses a performance data string and returns an array describing the values.
23 dirname(path) | Returns the directory portion of the specified path.
24 basename(path) | Returns the filename portion of the specified path.
25 escape\_shell\_arg(text) | Escapes a string for use as a single shell argument.
26 escape\_shell\_cmd(text) | Escapes shell meta characters in a string.
27 escape\_create\_process\_arg(text)| (Windows only) Escapes a string for use as an argument for CreateProcess().
28 exit(integer) | Terminates the application.
30 ## <a id="object-accessor-functions"></a> Object Accessor Functions
32 These functions can be used to retrieve a reference to another object by name.
34 ### <a id="objref-get_check_command"></a> get_check_command
38 function get_check_command(name);
40 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
42 ### <a id="objref-get_event_command"></a> get_event_command
46 function get_event_command(name);
48 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
50 ### <a id="objref-get_notification_command"></a> get_notification_command
54 function get_notification_command(name);
56 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
58 ### <a id="objref-get_host"></a> get_host
62 function get_host(host_name);
64 Returns the Host object with the specified name, or `null` if no such Host object exists.
67 ### <a id="objref-get_service"></a> get_service
71 function get_service(host_name, service_name);
73 Returns the Service object with the specified name, or `null` if no such Service object exists.
76 ### <a id="objref-get_user"></a> get_user
80 function get_user(name);
82 Returns the User object with the specified name, or `null` if no such User object exists.
84 ### <a id="objref-get_host_group"></a> get_host_group
88 function get_host_group(name);
90 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
93 ### <a id="objref-get_service_group"></a> get_service_group
97 function get_service_group(name);
99 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
101 ### <a id="objref-get_user_group"></a> get_user_group
105 function get_user_group(name);
107 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
110 ### <a id="objref-get_time_period"></a> get_time_period
114 function get_time_period(name);
116 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
119 ### <a id="objref-get_object"></a> get_object
123 function get_object(type, name);
125 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
129 ### <a id="objref-get_objects"></a> get_objects
133 function get_objects(type);
135 Returns an array of objects whose type matches the specified type. `type` must refer
139 ## <a id="math-object"></a> Math object
141 The global `Math` object can be used to access a number of mathematical constants
144 ### <a id="math-e"></a> Math.E
148 ### <a id="math-ln2"></a> Math.LN2
150 Natural logarithm of 2.
152 ### <a id="math-ln10"></a> Math.LN10
154 Natural logarithm of 10.
156 ### <a id="math-log2e"></a> Math.LOG2E
158 Base 2 logarithm of E.
160 ### <a id="math-pi"></a> Math.PI
162 The mathematical constant Pi.
164 ### <a id="math-sqrt1_2"></a> Math.SQRT1_2
168 ### <a id="math-sqrt2"></a> Math.SQRT2
172 ### <a id="math-abs"></a> Math.abs
178 Returns the absolute value of `x`.
180 ### <a id="math-acos"></a> Math.acos
186 Returns the arccosine of `x`.
188 ### <a id="math-asin"></a> Math.asin
194 Returns the arcsine of `x`.
196 ### <a id="math-atan"></a> Math.atan
202 Returns the arctangent of `x`.
204 ### <a id="math-atan2"></a> Math.atan2
208 function atan2(y, x);
210 Returns the arctangent of the quotient of `y` and `x`.
212 ### <a id="math-ceil"></a> Math.ceil
218 Returns the smallest integer value not less than `x`.
220 ### <a id="math-cos"></a> Math.cos
226 Returns the cosine of `x`.
228 ### <a id="math-exp"></a> Math.exp
234 Returns E raised to the `x`th power.
236 ### <a id="math-floor"></a> Math.floor
242 Returns the largest integer value not greater than `x`.
244 ### <a id="math-isinf"></a> Math.isinf
250 Returns whether `x` is infinite.
252 ### <a id="math-isnan"></a> Math.isnan
258 Returns whether `x` is NaN (not-a-number).
260 ### <a id="math-log"></a> Math.log
266 Returns the natural logarithm of `x`.
268 ### <a id="math-max"></a> Math.max
274 Returns the largest argument. A variable number of arguments can be specified.
275 If no arguments are given -Infinity is returned.
277 ### <a id="math-min"></a> Math.min
283 Returns the smallest argument. A variable number of arguments can be specified.
284 If no arguments are given +Infinity is returned.
286 ### <a id="math-pow"></a> Math.pow
292 Returns `x` raised to the `y`th power.
294 ### <a id="math-random"></a> Math.random
300 Returns a pseudo-random number between 0 and 1.
302 ### <a id="math-round"></a> Math.round
308 Returns `x` rounded to the nearest integer value.
310 ### <a id="math-sign"></a> Math.sign
316 Returns -1 if `x` is negative, 1 if `x` is positive
319 ### <a id="math-sin"></a> Math.sin
325 Returns the sine of `x`.
327 ### <a id="math-sqrt"></a> Math.sqrt
333 Returns the square root of `x`.
335 ### <a id="math-tan"></a> Math.tan
341 Returns the tangent of `x`.
343 ## <a id="json-object"></a> Json object
345 The global `Json` object can be used to encode and decode JSON.
347 ### <a id="json-encode"></a> Json.encode
353 Encodes an arbitrary value into JSON.
355 ### <a id="json-decode"></a> Json.decode
361 Decodes a JSON string.
363 ## <a id="number-type"></a> Number type
365 ### <a id="number-to_string"></a> Number#to_string
369 function to_string();
371 The `to_string` method returns a string representation of the number.
376 example.to_string() /* Returns "7" */
378 ## <a id="boolean-type"></a> Boolean type
380 ### <a id="boolean-to_string"></a> Boolean#to_string
384 function to_string();
386 The `to_string` method returns a string representation of the boolean value.
391 example.to_string() /* Returns "true" */
393 ## <a id="string-type"></a> String type
395 ### <a id="string-find"></a> String#find
399 function find(str, start);
401 Returns the zero-based index at which the string `str` was found in the string. If the string
402 was not found -1 is returned. `start` specifies the zero-based index at which `find` should
403 start looking for the string (defaults to 0 when not specified).
407 "Hello World".find("World") /* Returns 6 */
409 ### <a id="string-contains"></a> String#contains
413 function contains(str);
415 Returns `true` if the string `str` was found in the string. If the string
416 was not found `false` is returned. Use [find](21-library-reference.md#string-find)
417 for getting the index instead.
421 "Hello World".contains("World") /* Returns true */
423 ### <a id="string-len"></a> String#len
429 Returns the length of the string in bytes. Note that depending on the encoding type of the string
430 this is not necessarily the number of characters.
434 "Hello World".len() /* Returns 11 */
436 ### <a id="string-lower"></a> String#lower
442 Returns a copy of the string with all of its characters converted to lower-case.
446 "Hello World".lower() /* Returns "hello world" */
448 ### <a id="string-upper"></a> String#upper
454 Returns a copy of the string with all of its characters converted to upper-case.
458 "Hello World".upper() /* Returns "HELLO WORLD" */
460 ### <a id="string-replace"></a> String#replace
464 function replace(search, replacement);
466 Returns a copy of the string with all occurences of the string specified in `search` replaced
467 with the string specified in `replacement`.
469 ### <a id="string-split"></a> String#split
473 function split(delimiters);
475 Splits a string into individual parts and returns them as an array. The `delimiters` argument
476 specifies the characters which should be used as delimiters between parts.
480 "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
482 ### <a id="string-substr"></a> String#substr
486 function substr(start, len);
488 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
489 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
493 "Hello World".substr(6) /* Returns "World" */
495 ### <a id="string-to_string"></a> String#to_string
499 function to_string();
501 Returns a copy of the string.
503 ### <a id="string-reverse"></a> String#reverse
509 Returns a copy of the string in reverse order.
511 ## <a id="object-type"></a> Object type
513 ### <a id="object-clone"></a> Object#clone
519 Returns a copy of the object. Note that for object elements which are
520 reference values (e.g. objects such as arrays or dictionaries) the entire
521 object is recursively copied.
523 ## <a id="array-type"></a> Array type
525 Inherits methods from the [object type](21-library-reference.md#object-type).
527 ### <a id="array-add"></a> Array#add
533 Adds a new value after the last element in the array.
535 ### <a id="array-clear"></a> Array#clear
541 Removes all elements from the array.
543 ### <a id="array-shallow-clone"></a> Array#shallow_clone
545 function shallow_clone();
547 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
548 as arrays and dictionaries) only the references are copied.
550 ### <a id="array-contains"></a> Array#contains
554 function contains(value);
556 Returns true if the array contains the specified value, false otherwise.
558 ### <a id="array-len"></a> Array#len
564 Returns the number of elements contained in the array.
566 ### <a id="array-remove"></a> Array#remove
570 function remove(index);
572 Removes the element at the specified zero-based index.
574 ### <a id="array-set"></a> Array#set
578 function set(index, value);
580 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
581 which already exists in the array.
583 ### <a id="array-get"></a> Array#get
589 Retrieves the element at the specified zero-based index.
591 ### <a id="array-sort"></a> Array#sort
595 function sort(less_cmp);
597 Returns a copy of the array where all items are sorted. The items are
598 compared using the `<` (less-than) operator. A custom comparator function
599 can be specified with the `less_cmp` argument.
601 ### <a id="array-join"></a> Array#join
605 function join(separator);
607 Joins all elements of the array using the specified separator.
609 ### <a id="array-reverse"></a> Array#reverse
615 Returns a new array with all elements of the current array in reverse order.
617 ## <a id="dictionary-type"></a> Dictionary type
619 Inherits methods from the [object type](21-library-reference.md#object-type).
621 ### <a id="dictionary-shallow-clone"></a> Dictionary#shallow_clone
625 function shallow_clone();
627 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
628 as arrays and dictionaries) only the references are copied.
630 ### <a id="dictionary-contains"></a> Dictionary#contains
634 function contains(key);
636 Returns true if a dictionary item with the specified `key` exists, false otherwise.
638 ### <a id="dictionary-len"></a> Dictionary#len
644 Returns the number of items contained in the dictionary.
646 ### <a id="dictionary-remove"></a> Dictionary#remove
650 function remove(key);
652 Removes the item with the specified `key`. Trying to remove an item which does not exist
655 ### <a id="dictionary-set"></a> Dictionary#set
659 function set(key, value);
661 Creates or updates an item with the specified `key` and `value`.
663 ### <a id="dictionary-get"></a> Dictionary#get
669 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
672 ### <a id="dictionary-keys"></a> Dictionary#keys
678 Returns a list of keys for all items that are currently in the dictionary.
680 ## <a id="scriptfunction-type"></a> Function type
682 ### <a id="scriptfunction-call"></a> Function#call
686 function call(thisArg, ...);
688 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
689 scope for the function. All other arguments are passed directly to the function.
693 function set_x(val) {
699 set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
701 ### <a id="scriptfunction-callv"></a> Function#callv
705 function callv(thisArg, args);
707 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
708 scope for the function. The items in the `args` array are passed to the function as individual arguments.
712 function set_x(val) {
720 set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */