granicus.if.org Git - icinga2/blob - doc/20-library-reference.md

   1 # <a id="library-reference"></a> Library Reference
   2
   3 ## <a id="global-functions"></a> Global functions
   4
   5 Function                        | Description
   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 exit(integer)                   | Terminates the application.
  23
  24 ## <a id="object-accessor-functions"></a> Object Accessor Functions
  25
  26 These functions can be used to retrieve a reference to another object by name.
  27
  28 ### <a id="objref-get_check_command"></a> get_check_command
  29
  30 Signature:
  31
  32     function get_check_command(name);
  33
  34 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
  35
  36 ### <a id="objref-get_event_command"></a> get_event_command
  37
  38 Signature:
  39
  40     function get_event_command(name);
  41
  42 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
  43
  44 ### <a id="objref-get_notification_command"></a> get_notification_command
  45
  46 Signature:
  47
  48     function get_notification_command(name);
  49
  50 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
  51
  52 ### <a id="objref-get_host"></a> get_host
  53
  54 Signature:
  55
  56     function get_notification_command(name);
  57
  58 Returns the Host object with the specified name, or `null` if no such Host object exists.
  59
  60
  61 ### <a id="objref-get_service"></a> get_service
  62
  63 Signature:
  64
  65     function get_service(host_name, service_name);
  66
  67 Returns the Service object with the specified name, or `null` if no such Service object exists.
  68
  69
  70 ### <a id="objref-get_user"></a> get_user
  71
  72 Signature:
  73
  74     function get_user(name);
  75
  76 Returns the User object with the specified name, or `null` if no such User object exists.
  77
  78 ### <a id="objref-get_host_group"></a> get_host_group
  79
  80 Signature:
  81
  82     function get_host_group(name);
  83
  84 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
  85
  86
  87 ### <a id="objref-get_service_group"></a> get_service_group
  88
  89 Signature:
  90
  91     function get_service_group(name);
  92
  93 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
  94
  95 ### <a id="objref-get_user_group"></a> get_user_group
  96
  97 Signature:
  98
  99     function get_user_group(name);
 100
 101 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
 102
 103
 104 ### <a id="objref-get_time_period"></a> get_time_period
 105
 106 Signature:
 107
 108     function get_time_period(name);
 109
 110 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
 111
 112
 113 ### <a id="objref-get_object"></a> get_object
 114
 115 Signature:
 116
 117     function get_object(type, name);
 118
 119 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
 120 to a type object.
 121
 122
 123 ### <a id="objref-get_objects"></a> get_objects
 124
 125 Signature:
 126
 127     function get_objects(type);
 128
 129 Returns an array of objects whose type matches the specified type. `type` must refer
 130 to a type object.
 131
 132
 133 ## <a id="math-object"></a> Math object
 134
 135 The global `Math` object can be used to access a number of mathematical constants
 136 and functions.
 137
 138 ### <a id="math-e"></a> Math.E
 139
 140 Euler's constant.
 141
 142 ### <a id="math-ln2"></a> Math.LN2
 143
 144 Natural logarithm of 2.
 145
 146 ### <a id="math-ln10"></a> Math.LN10
 147
 148 Natural logarithm of 10.
 149
 150 ### <a id="math-log2e"></a> Math.LOG2E
 151
 152 Base 2 logarithm of E.
 153
 154 ### <a id="math-pi"></a> Math.PI
 155
 156 The mathematical constant Pi.
 157
 158 ### <a id="math-sqrt1_2"></a> Math.SQRT1_2
 159
 160 Square root of 1/2.
 161
 162 ### <a id="math-sqrt2"></a> Math.SQRT2
 163
 164 Square root of 2.
 165
 166 ### <a id="math-abs"></a> Math.abs
 167
 168 Signature:
 169
 170     function abs(x);
 171
 172 Returns the absolute value of `x`.
 173
 174 ### <a id="math-acos"></a> Math.acos
 175
 176 Signature:
 177
 178     function acos(x);
 179
 180 Returns the arccosine of `x`.
 181
 182 ### <a id="math-asin"></a> Math.asin
 183
 184 Signature:
 185
 186     function asin(x);
 187
 188 Returns the arcsine of `x`.
 189
 190 ### <a id="math-atan"></a> Math.atan
 191
 192 Signature:
 193
 194     function atan(x);
 195
 196 Returns the arctangent of `x`.
 197
 198 ### <a id="math-atan2"></a> Math.atan2
 199
 200 Signature:
 201
 202     function atan2(y, x);
 203
 204 Returns the arctangent of the quotient of `y` and `x`.
 205
 206 ### <a id="math-ceil"></a> Math.ceil
 207
 208 Signature:
 209
 210     function ceil(x);
 211
 212 Returns the smallest integer value not less than `x`.
 213
 214 ### <a id="math-cos"></a> Math.cos
 215
 216 Signature:
 217
 218     function cos(x);
 219
 220 Returns the cosine of `x`.
 221
 222 ### <a id="math-exp"></a> Math.exp
 223
 224 Signature:
 225
 226     function exp(x);
 227
 228 Returns E raised to the `x`th power.
 229
 230 ### <a id="math-floor"></a> Math.floor
 231
 232 Signature:
 233
 234     function floor(x);
 235
 236 Returns the largest integer value not greater than `x`.
 237
 238 ### <a id="math-isinf"></a> Math.isinf
 239
 240 Signature:
 241
 242     function isinf(x);
 243
 244 Returns whether `x` is infinite.
 245
 246 ### <a id="math-isnan"></a> Math.isnan
 247
 248 Signature:
 249
 250     function isnan(x);
 251
 252 Returns whether `x` is NaN (not-a-number).
 253
 254 ### <a id="math-log"></a> Math.log
 255
 256 Signature:
 257
 258     function log(x);
 259
 260 Returns the natural logarithm of `x`.
 261
 262 ### <a id="math-max"></a> Math.max
 263
 264 Signature:
 265
 266     function max(...);
 267
 268 Returns the largest argument. A variable number of arguments can be specified.
 269 If no arguments are given -Infinity is returned.
 270
 271 ### <a id="math-min"></a> Math.min
 272
 273 Signature:
 274
 275     function min(...);
 276
 277 Returns the smallest argument. A variable number of arguments can be specified.
 278 If no arguments are given +Infinity is returned.
 279
 280 ### <a id="math-pow"></a> Math.pow
 281
 282 Signature:
 283
 284     function pow(x, y);
 285
 286 Returns `x` raised to the `y`th power.
 287
 288 ### <a id="math-random"></a> Math.random
 289
 290 Signature:
 291
 292     function random();
 293
 294 Returns a pseudo-random number between 0 and 1.
 295
 296 ### <a id="math-round"></a> Math.round
 297
 298 Signature:
 299
 300     function round(x);
 301
 302 Returns `x` rounded to the nearest integer value.
 303
 304 ### <a id="math-sign"></a> Math.sign
 305
 306 Signature:
 307
 308     function sign(x);
 309
 310 Returns -1 if `x` is negative, 1 if `x` is positive
 311 and 0 if `x` is 0.
 312
 313 ### <a id="math-sin"></a> Math.sin
 314
 315 Signature:
 316
 317     function sin(x);
 318
 319 Returns the sine of `x`.
 320
 321 ### <a id="math-sqrt"></a> Math.sqrt
 322
 323 Signature:
 324
 325     function sqrt(x);
 326
 327 Returns the square root of `x`.
 328
 329 ### <a id="math-tan"></a> Math.tan
 330
 331 Signature:
 332
 333     function tan(x);
 334
 335 Returns the tangent of `x`.
 336
 337 ## <a id="json-object"></a> Json object
 338
 339 The global `Json` object can be used to encode and decode JSON.
 340
 341 ### <a id="json-encode"></a> Json.encode
 342
 343 Signature:
 344
 345     function encode(x);
 346
 347 Encodes an arbitrary value into JSON.
 348
 349 ### <a id="json-decode"></a> Json.decode
 350
 351 Signature:
 352
 353     function decode(x);
 354
 355 Decodes a JSON string.
 356
 357 ## <a id="number-type"></a> Number type
 358
 359 ### <a id="number-to_string"></a> Number#to_string
 360
 361 Signature:
 362
 363     function to_string();
 364
 365 The `to_string` method returns a string representation of the number.
 366
 367 Example:
 368
 369     var example = 7
 370         example.to_string() /* Returns "7" */
 371
 372 ## <a id="boolean-type"></a> Boolean type
 373
 374 ### <a id="boolean-to_string"></a> Boolean#to_string
 375
 376 Signature:
 377
 378     function to_string();
 379
 380 The `to_string` method returns a string representation of the boolean value.
 381
 382 Example:
 383
 384     var example = true
 385         example.to_string() /* Returns "true" */
 386
 387 ## <a id="string-type"></a> String type
 388
 389 ### <a id="string-find"></a> String#find
 390
 391 Signature:
 392
 393     function find(str, start);
 394
 395 Returns the zero-based index at which the string `str` was found in the string. If the string
 396 was not found -1 is returned. `start` specifies the zero-based index at which `find` should
 397 start looking for the string (defaults to 0 when not specified).
 398
 399 Example:
 400
 401     "Hello World".find("World") /* Returns 6 */
 402
 403 ### <a id="string-contains"></a> String#contains
 404
 405 Signature:
 406
 407     function contains(str);
 408
 409 Returns `true` if the string `str` was found in the string. If the string
 410 was not found `false` is returned. Use [find](20-library-reference.md#string-find)
 411 for getting the index instead.
 412
 413 Example:
 414
 415     "Hello World".contains("World") /* Returns true */
 416
 417 ### <a id="string-len"></a> String#len
 418
 419 Signature
 420
 421     function len();
 422
 423 Returns the length of the string in bytes. Note that depending on the encoding type of the string
 424 this is not necessarily the number of characters.
 425
 426 Example:
 427
 428     "Hello World".len() /* Returns 11 */
 429
 430 ### <a id="string-lower"></a> String#lower
 431
 432 Signature:
 433
 434     function lower();
 435
 436 Returns a copy of the string with all of its characters converted to lower-case.
 437
 438 Example:
 439
 440     "Hello World".lower() /* Returns "hello world" */
 441
 442 ### <a id="string-upper"></a> String#upper
 443
 444 Signature:
 445
 446     function upper();
 447
 448 Returns a copy of the string with all of its characters converted to upper-case.
 449
 450 Example:
 451
 452     "Hello World".upper() /* Returns "HELLO WORLD" */
 453
 454 ### <a id="string-replace"></a> String#replace
 455
 456 Signature:
 457
 458     function replace(search, replacement);
 459
 460 Returns a copy of the string with all occurences of the string specified in `search` replaced
 461 with the string specified in `replacement`.
 462
 463 ### <a id="string-split"></a> String#split
 464
 465 Signature:
 466
 467     function split(delimiters);
 468
 469 Splits a string into individual parts and returns them as an array. The `delimiters` argument
 470 specifies the characters which should be used as delimiters between parts.
 471
 472 Example:
 473
 474     "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
 475
 476 ### <a id="string-substr"></a> String#substr
 477
 478 Signature:
 479
 480     function substr(start, len);
 481
 482 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
 483 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
 484
 485 Example:
 486
 487     "Hello World".substr(6) /* Returns "World" */
 488
 489 ### <a id="string-to_string"></a> String#to_string
 490
 491 Signature:
 492
 493     function to_string();
 494
 495 Returns a copy of the string.
 496
 497 ## <a id="array-type"></a> Array type
 498
 499 ### <a id="array-add"></a> Array#add
 500
 501 Signature:
 502
 503     function add(value);
 504
 505 Adds a new value after the last element in the array.
 506
 507 ### <a id="array-clear"></a> Array#clear
 508
 509 Signature:
 510
 511     function clear();
 512
 513 Removes all elements from the array.
 514
 515 ### <a id="array-clone"></a> Array#clone
 516
 517     function clone();
 518
 519 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
 520 as arrays and dictionaries) only the references are copied.
 521
 522 ### <a id="array-contains"></a> Array#contains
 523
 524 Signature:
 525
 526     function contains(value);
 527
 528 Returns true if the array contains the specified value, false otherwise.
 529
 530 ### <a id="array-len"></a> Array#len
 531
 532 Signature:
 533
 534     function len();
 535
 536 Returns the number of elements contained in the array.
 537
 538 ### <a id="array-remove"></a> Array#remove
 539
 540 Signature:
 541
 542     function remove(index);
 543
 544 Removes the element at the specified zero-based index.
 545
 546 ### <a id="array-set"></a> Array#set
 547
 548 Signature:
 549
 550     function set(index, value);
 551
 552 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
 553 which already exists in the array.
 554
 555 ### <a id="array-sort"></a> Array#sort
 556
 557 Signature:
 558
 559     function sort(less_cmp);
 560
 561 Returns a copy of the array where all items are sorted. The items are
 562 compared using the `<` (less-than) operator. A custom comparator function
 563 can be specified with the `less_cmp` argument.
 564
 565 ### <a id="array-join"></a> Array#join
 566
 567 Signature:
 568
 569     function join(separator);
 570
 571 Joins all elements of the array using the specified separator.
 572
 573 ## <a id="dictionary-type"></a> Dictionary type
 574
 575 ### <a id="dictionary-clone"></a> Dictionary#clone
 576
 577 Signature:
 578
 579     function clone();
 580
 581 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
 582 as arrays and dictionaries) only the references are copied.
 583
 584 ### <a id="dictionary-contains"></a> Dictionary#contains
 585
 586 Signature:
 587
 588     function contains(key);
 589
 590 Returns true if a dictionary item with the specified `key` exists, false otherwise.
 591
 592 ### <a id="dictionary-len"></a> Dictionary#len
 593
 594 Signature:
 595
 596     function len();
 597
 598 Returns the number of items contained in the dictionary.
 599
 600 ### <a id="dictionary-remove"></a> Dictionary#remove
 601
 602 Signature:
 603
 604     function remove(key);
 605
 606 Removes the item with the specified `key`. Trying to remove an item which does not exist
 607 is a no-op.
 608
 609 ### <a id="dictionary-set"></a> Dictionary#set
 610
 611 Signature:
 612
 613     function set(key, value);
 614
 615 Creates or updates an item with the specified `key` and `value`.
 616
 617 ## <a id="scriptfunction-type"></a> Function type
 618
 619 ### <a id="scriptfunction-call"></a> Function#call
 620
 621 Signature:
 622
 623     function call(thisArg, ...);
 624
 625 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
 626 scope for the function. All other arguments are passed directly to the function.
 627
 628 Example:
 629
 630     function set_x(val) {
 631           this.x = val
 632         }
 633
 634         dict = {}
 635
 636         set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
 637
 638 ### <a id="scriptfunction-callv"></a> Function#callv
 639
 640 Signature:
 641
 642     function callv(thisArg, args);
 643
 644 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
 645 scope for the function. The items in the `args` array are passed to the function as individual arguments.
 646
 647 Example:
 648
 649     function set_x(val) {
 650           this.x = val
 651         }
 652
 653         var dict = {}
 654
 655         var args = [ 7 ]
 656
 657         set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
 658