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