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