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