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 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.
10 union(array, array, ...) | Returns an array containing all unique elements from the specified arrays.
11 intersection(array, array, ...) | Returns an array containing all unique elements which are common to all specified arrays.
12 keys(dict) | Returns an array containing the dictionary's keys.
13 string(value) | Converts the value to a string.
14 number(value) | Converts the value to a number.
15 bool(value) | Converts the value to a bool.
16 random() | Returns a random value between 0 and RAND_MAX (as defined in stdlib.h).
17 log(value) | Writes a message to the log. Non-string values are converted to a JSON string.
18 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.
19 typeof(value) | Returns the type object for a value.
20 get_time() | Returns the current UNIX timestamp.
21 parse_performance_data(pd) | Parses a performance data string and returns an array describing the values.
22 dirname(path) | Returns the directory portion of the specified path.
23 basename(path) | Returns the filename portion of the specified path.
24 exit(integer) | Terminates the application.
26 ## <a id="object-accessor-functions"></a> Object Accessor Functions
28 These functions can be used to retrieve a reference to another object by name.
30 ### <a id="objref-get_check_command"></a> get_check_command
34 function get_check_command(name);
36 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
38 ### <a id="objref-get_event_command"></a> get_event_command
42 function get_event_command(name);
44 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
46 ### <a id="objref-get_notification_command"></a> get_notification_command
50 function get_notification_command(name);
52 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
54 ### <a id="objref-get_host"></a> get_host
58 function get_host(host_name);
60 Returns the Host object with the specified name, or `null` if no such Host object exists.
63 ### <a id="objref-get_service"></a> get_service
67 function get_service(host_name, service_name);
69 Returns the Service object with the specified name, or `null` if no such Service object exists.
72 ### <a id="objref-get_user"></a> get_user
76 function get_user(name);
78 Returns the User object with the specified name, or `null` if no such User object exists.
80 ### <a id="objref-get_host_group"></a> get_host_group
84 function get_host_group(name);
86 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
89 ### <a id="objref-get_service_group"></a> get_service_group
93 function get_service_group(name);
95 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
97 ### <a id="objref-get_user_group"></a> get_user_group
101 function get_user_group(name);
103 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
106 ### <a id="objref-get_time_period"></a> get_time_period
110 function get_time_period(name);
112 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
115 ### <a id="objref-get_object"></a> get_object
119 function get_object(type, name);
121 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
125 ### <a id="objref-get_objects"></a> get_objects
129 function get_objects(type);
131 Returns an array of objects whose type matches the specified type. `type` must refer
135 ## <a id="math-object"></a> Math object
137 The global `Math` object can be used to access a number of mathematical constants
140 ### <a id="math-e"></a> Math.E
144 ### <a id="math-ln2"></a> Math.LN2
146 Natural logarithm of 2.
148 ### <a id="math-ln10"></a> Math.LN10
150 Natural logarithm of 10.
152 ### <a id="math-log2e"></a> Math.LOG2E
154 Base 2 logarithm of E.
156 ### <a id="math-pi"></a> Math.PI
158 The mathematical constant Pi.
160 ### <a id="math-sqrt1_2"></a> Math.SQRT1_2
164 ### <a id="math-sqrt2"></a> Math.SQRT2
168 ### <a id="math-abs"></a> Math.abs
174 Returns the absolute value of `x`.
176 ### <a id="math-acos"></a> Math.acos
182 Returns the arccosine of `x`.
184 ### <a id="math-asin"></a> Math.asin
190 Returns the arcsine of `x`.
192 ### <a id="math-atan"></a> Math.atan
198 Returns the arctangent of `x`.
200 ### <a id="math-atan2"></a> Math.atan2
204 function atan2(y, x);
206 Returns the arctangent of the quotient of `y` and `x`.
208 ### <a id="math-ceil"></a> Math.ceil
214 Returns the smallest integer value not less than `x`.
216 ### <a id="math-cos"></a> Math.cos
222 Returns the cosine of `x`.
224 ### <a id="math-exp"></a> Math.exp
230 Returns E raised to the `x`th power.
232 ### <a id="math-floor"></a> Math.floor
238 Returns the largest integer value not greater than `x`.
240 ### <a id="math-isinf"></a> Math.isinf
246 Returns whether `x` is infinite.
248 ### <a id="math-isnan"></a> Math.isnan
254 Returns whether `x` is NaN (not-a-number).
256 ### <a id="math-log"></a> Math.log
262 Returns the natural logarithm of `x`.
264 ### <a id="math-max"></a> Math.max
270 Returns the largest argument. A variable number of arguments can be specified.
271 If no arguments are given -Infinity is returned.
273 ### <a id="math-min"></a> Math.min
279 Returns the smallest argument. A variable number of arguments can be specified.
280 If no arguments are given +Infinity is returned.
282 ### <a id="math-pow"></a> Math.pow
288 Returns `x` raised to the `y`th power.
290 ### <a id="math-random"></a> Math.random
296 Returns a pseudo-random number between 0 and 1.
298 ### <a id="math-round"></a> Math.round
304 Returns `x` rounded to the nearest integer value.
306 ### <a id="math-sign"></a> Math.sign
312 Returns -1 if `x` is negative, 1 if `x` is positive
315 ### <a id="math-sin"></a> Math.sin
321 Returns the sine of `x`.
323 ### <a id="math-sqrt"></a> Math.sqrt
329 Returns the square root of `x`.
331 ### <a id="math-tan"></a> Math.tan
337 Returns the tangent of `x`.
339 ## <a id="json-object"></a> Json object
341 The global `Json` object can be used to encode and decode JSON.
343 ### <a id="json-encode"></a> Json.encode
349 Encodes an arbitrary value into JSON.
351 ### <a id="json-decode"></a> Json.decode
357 Decodes a JSON string.
359 ## <a id="number-type"></a> Number type
361 ### <a id="number-to_string"></a> Number#to_string
365 function to_string();
367 The `to_string` method returns a string representation of the number.
372 example.to_string() /* Returns "7" */
374 ## <a id="boolean-type"></a> Boolean type
376 ### <a id="boolean-to_string"></a> Boolean#to_string
380 function to_string();
382 The `to_string` method returns a string representation of the boolean value.
387 example.to_string() /* Returns "true" */
389 ## <a id="string-type"></a> String type
391 ### <a id="string-find"></a> String#find
395 function find(str, start);
397 Returns the zero-based index at which the string `str` was found in the string. If the string
398 was not found -1 is returned. `start` specifies the zero-based index at which `find` should
399 start looking for the string (defaults to 0 when not specified).
403 "Hello World".find("World") /* Returns 6 */
405 ### <a id="string-contains"></a> String#contains
409 function contains(str);
411 Returns `true` if the string `str` was found in the string. If the string
412 was not found `false` is returned. Use [find](20-library-reference.md#string-find)
413 for getting the index instead.
417 "Hello World".contains("World") /* Returns true */
419 ### <a id="string-len"></a> String#len
425 Returns the length of the string in bytes. Note that depending on the encoding type of the string
426 this is not necessarily the number of characters.
430 "Hello World".len() /* Returns 11 */
432 ### <a id="string-lower"></a> String#lower
438 Returns a copy of the string with all of its characters converted to lower-case.
442 "Hello World".lower() /* Returns "hello world" */
444 ### <a id="string-upper"></a> String#upper
450 Returns a copy of the string with all of its characters converted to upper-case.
454 "Hello World".upper() /* Returns "HELLO WORLD" */
456 ### <a id="string-replace"></a> String#replace
460 function replace(search, replacement);
462 Returns a copy of the string with all occurences of the string specified in `search` replaced
463 with the string specified in `replacement`.
465 ### <a id="string-split"></a> String#split
469 function split(delimiters);
471 Splits a string into individual parts and returns them as an array. The `delimiters` argument
472 specifies the characters which should be used as delimiters between parts.
476 "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
478 ### <a id="string-substr"></a> String#substr
482 function substr(start, len);
484 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
485 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
489 "Hello World".substr(6) /* Returns "World" */
491 ### <a id="string-to_string"></a> String#to_string
495 function to_string();
497 Returns a copy of the string.
499 ## <a id="array-type"></a> Array type
501 ### <a id="array-add"></a> Array#add
507 Adds a new value after the last element in the array.
509 ### <a id="array-clear"></a> Array#clear
515 Removes all elements from the array.
517 ### <a id="array-clone"></a> Array#clone
521 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
522 as arrays and dictionaries) only the references are copied.
524 ### <a id="array-contains"></a> Array#contains
528 function contains(value);
530 Returns true if the array contains the specified value, false otherwise.
532 ### <a id="array-len"></a> Array#len
538 Returns the number of elements contained in the array.
540 ### <a id="array-remove"></a> Array#remove
544 function remove(index);
546 Removes the element at the specified zero-based index.
548 ### <a id="array-set"></a> Array#set
552 function set(index, value);
554 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
555 which already exists in the array.
557 ### <a id="array-get"></a> Array#get
563 Retrieves the element at the specified zero-based index.
565 ### <a id="array-sort"></a> Array#sort
569 function sort(less_cmp);
571 Returns a copy of the array where all items are sorted. The items are
572 compared using the `<` (less-than) operator. A custom comparator function
573 can be specified with the `less_cmp` argument.
575 ### <a id="array-join"></a> Array#join
579 function join(separator);
581 Joins all elements of the array using the specified separator.
583 ## <a id="dictionary-type"></a> Dictionary type
585 ### <a id="dictionary-clone"></a> Dictionary#clone
591 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
592 as arrays and dictionaries) only the references are copied.
594 ### <a id="dictionary-contains"></a> Dictionary#contains
598 function contains(key);
600 Returns true if a dictionary item with the specified `key` exists, false otherwise.
602 ### <a id="dictionary-len"></a> Dictionary#len
608 Returns the number of items contained in the dictionary.
610 ### <a id="dictionary-remove"></a> Dictionary#remove
614 function remove(key);
616 Removes the item with the specified `key`. Trying to remove an item which does not exist
619 ### <a id="dictionary-set"></a> Dictionary#set
623 function set(key, value);
625 Creates or updates an item with the specified `key` and `value`.
627 ### <a id="dictionary-get"></a> Dictionary#get
633 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
636 ## <a id="scriptfunction-type"></a> Function type
638 ### <a id="scriptfunction-call"></a> Function#call
642 function call(thisArg, ...);
644 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
645 scope for the function. All other arguments are passed directly to the function.
649 function set_x(val) {
655 set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
657 ### <a id="scriptfunction-callv"></a> Function#callv
661 function callv(thisArg, args);
663 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
664 scope for the function. The items in the `args` array are passed to the function as individual arguments.
668 function set_x(val) {
676 set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */