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

   1 # Library Reference <a id="library-reference"></a>
   2
   3 ## Global functions <a id="global-functions"></a>
   4
   5 These functions are globally available in [assign/ignore where expressions](03-monitoring-basics.md#using-apply-expressions),
   6 [functions](17-language-reference.md#functions), [API filters](12-icinga2-api.md#icinga2-api-filters)
   7 and the [Icinga 2 debug console](11-cli-commands.md#cli-command-console).
   8
   9 You can use the [Icinga 2 debug console](11-cli-commands.md#cli-command-console)
  10 as a sandbox to test these functions before implementing
  11 them in your scenarios.
  12
  13 ### regex <a id="global-functions-regex"></a>
  14
  15 Signature:
  16
  17     function regex(pattern, value, mode)
  18
  19 Returns true if the regular expression `pattern` matches the `value`, false otherwise.
  20 The `value` can be of the type [String](18-library-reference.md#string-type) or [Array](18-library-reference.md#array-type) (which
  21 contains string elements).
  22
  23 The `mode` argument is optional and can be either `MatchAll` (in which case all elements
  24 for an array have to match) or `MatchAny` (in which case at least one element has to match).
  25 The default mode is `MatchAll`.
  26
  27 **Tip**: In case you are looking for regular expression tests try [regex101](https://regex101.com).
  28
  29 Example for string values:
  30
  31     $ icinga2 console
  32     Icinga 2 (version: v2.7.0)
  33     <1> => host.vars.os_type = "Linux/Unix"
  34     null
  35     <2> => regex("^Linux", host.vars.os_type)
  36     true
  37     <3> => regex("^Linux$", host.vars.os_type)
  38     false
  39
  40 Example for an array of string values:
  41
  42     $ icinga2 console
  43     Icinga 2 (version: v2.7.0)
  44     <1> => host.vars.databases = [ "db-prod1", "db-prod2", "db-dev" ]
  45     null
  46     <2> => regex("^db-prod\\d+", host.vars.databases, MatchAny)
  47     true
  48     <3> => regex("^db-prod\\d+", host.vars.databases, MatchAll)
  49     false
  50
  51
  52 ### match <a id="global-functions-match"></a>
  53
  54 Signature:
  55
  56     function match(pattern, text, mode)
  57
  58 Returns true if the wildcard (`?*`) `pattern` matches the `value`, false otherwise.
  59 The `value` can be of the type [String](18-library-reference.md#string-type) or [Array](18-library-reference.md#array-type) (which
  60 contains string elements).
  61
  62 The `mode` argument is optional and can be either `MatchAll` (in which case all elements
  63 for an array have to match) or `MatchAny` (in which case at least one element has to match).
  64 The default mode is `MatchAll`.
  65
  66 Example for string values:
  67
  68     $ icinga2 console
  69     Icinga 2 (version: v2.7.0)
  70     <1> => var name = "db-prod-sfo-657"
  71     null
  72     <2> => match("*prod-sfo*", name)
  73     true
  74     <3> => match("*-dev-*", name)
  75     false
  76
  77 Example for an array of string values:
  78
  79     $ icinga2 console
  80     Icinga 2 (version: v2.7.0-28)
  81     <1> => host.vars.application_types = [ "web-wp", "web-rt", "db-local" ]
  82     null
  83     <2> => match("web-*", host.vars.application_types, MatchAll)
  84     false
  85     <3> => match("web-*", host.vars.application_types, MatchAny)
  86     true
  87
  88
  89 ### cidr_match <a id="global-functions-cidr_match"></a>
  90
  91 Signature:
  92
  93     function cidr_match(pattern, ip, mode)
  94
  95 Returns true if the CIDR pattern matches the IP address, false otherwise.
  96
  97 IPv4 addresses are converted to IPv4-mapped IPv6 addresses before being
  98 matched against the pattern. The `mode` argument is optional and can be
  99 either `MatchAll` (in which case all elements for an array have to match) or `MatchAny`
 100 (in which case at least one element has to match). The default mode is `MatchAll`.
 101
 102
 103 Example for a single IP address:
 104
 105     $ icinga2 console
 106     Icinga 2 (version: v2.7.0)
 107     <1> => host.address = "192.168.56.101"
 108     null
 109     <2> => cidr_match("192.168.56.0/24", host.address)
 110     true
 111     <3> => cidr_match("192.168.56.0/26", host.address)
 112     false
 113
 114 Example for an array of IP addresses:
 115
 116     $ icinga2 console
 117     Icinga 2 (version: v2.7.0)
 118     <1> => host.vars.vhost_ips = [ "192.168.56.101", "192.168.56.102", "10.0.10.99" ]
 119     null
 120     <2> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAll)
 121     false
 122     <3> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAny)
 123     true
 124
 125 ### range <a id="global-functions-range"></a>
 126
 127 Signature:
 128
 129     function range(end)
 130     function range(start, end)
 131     function range(start, end, increment)
 132
 133 Returns an array of numbers in the specified range.
 134 If you specify one parameter, the first element starts at `0`.
 135 The following array numbers are incremented by `1` and stop before
 136 the specified end.
 137 If you specify the start and end numbers, the returned array
 138 number are incremented by `1`. They start at the specified start
 139 number and stop before the end number.
 140 Optionally you can specify the incremented step between numbers
 141 as third parameter.
 142
 143 Example:
 144
 145     $ icinga2 console
 146     Icinga 2 (version: v2.7.0)
 147     <1> => range(5)
 148     [ 0.000000, 1.000000, 2.000000, 3.000000, 4.000000 ]
 149     <2> => range(2,4)
 150     [ 2.000000, 3.000000 ]
 151     <3> => range(2,10,2)
 152     [ 2.000000, 4.000000, 6.000000, 8.000000 ]
 153
 154 ### len <a id="global-functions-len"></a>
 155
 156 Signature:
 157
 158     function len(value)
 159
 160 Returns the length of the value, i.e. the number of elements for an array
 161 or dictionary, or the length of the string in bytes.
 162
 163 **Note**: Instead of using this global function you are advised to use the type's
 164 prototype method: [Array#len](18-library-reference.md#array-len), [Dictionary#len](18-library-reference.md#dictionary-len) and
 165 [String#len](18-library-reference.md#string-len).
 166
 167 Example:
 168
 169     $ icinga2 console
 170     Icinga 2 (version: v2.7.0)
 171     <1> => host.groups = [ "linux-servers", "db-servers" ]
 172     null
 173     <2> => host.groups.len()
 174     2.000000
 175     <3> => host.vars.disks["/"] = {}
 176     null
 177     <4> => host.vars.disks["/var"] = {}
 178     null
 179     <5> => host.vars.disks.len()
 180     2.000000
 181     <6> => host.vars.os_type = "Linux/Unix"
 182     null
 183     <7> => host.vars.os_type.len()
 184     10.000000
 185
 186
 187 ### union <a id="global-functions-union"></a>
 188
 189 Signature:
 190
 191     function union(array, array, ...)
 192
 193 Returns an array containing all unique elements from the specified arrays.
 194
 195 Example:
 196
 197     $ icinga2 console
 198     Icinga 2 (version: v2.7.0)
 199     <1> => var dev_notification_groups = [ "devs", "slack" ]
 200     null
 201     <2> => var host_notification_groups = [ "slack", "noc" ]
 202     null
 203     <3> => union(dev_notification_groups, host_notification_groups)
 204     [ "devs", "noc", "slack" ]
 205
 206 ### intersection <a id="global-functions-intersection"></a>
 207
 208 Signature:
 209
 210     function intersection(array, array, ...)
 211
 212 Returns an array containing all unique elements which are common to all
 213 specified arrays.
 214
 215 Example:
 216
 217     $ icinga2 console
 218     Icinga 2 (version: v2.7.0)
 219     <1> => var dev_notification_groups = [ "devs", "slack" ]
 220     null
 221     <2> => var host_notification_groups = [ "slack", "noc" ]
 222     null
 223     <3> => intersection(dev_notification_groups, host_notification_groups)
 224     [ "slack" ]
 225
 226 ### keys <a id="global-functions-keys"></a>
 227
 228 Signature:
 229
 230     function keys(dict)
 231
 232 Returns an array containing the dictionary's keys.
 233
 234 **Note**: Instead of using this global function you are advised to use the type's
 235 prototype method: [Dictionary#keys](18-library-reference.md#dictionary-keys).
 236
 237 Example:
 238
 239     $ icinga2 console
 240     Icinga 2 (version: v2.7.0)
 241     <1> => host.vars.disks["/"] = {}
 242     null
 243     <2> => host.vars.disks["/var"] = {}
 244     null
 245     <3> => host.vars.disks.keys()
 246     [ "/", "/var" ]
 247
 248 ### string <a id="global-functions-string"></a>
 249
 250 Signature:
 251
 252     function string(value)
 253
 254 Converts the value to a string.
 255
 256 **Note**: Instead of using this global function you are advised to use the type's
 257 prototype method:
 258
 259 * [Number#to_string](18-library-reference.md#number-to_string)
 260 * [Boolean#to_string](18-library-reference.md#boolean-to_string)
 261 * [String#to_string](18-library-reference.md#string-to_string)
 262 * [Object#to_string](18-library-reference.md#object-to-string) for Array and Dictionary types
 263 * [DateTime#to_string](18-library-reference.md#datetime-tostring)
 264
 265 Example:
 266
 267     $ icinga2 console
 268     Icinga 2 (version: v2.7.0)
 269     <1> => 5.to_string()
 270     "5"
 271     <2> => false.to_string()
 272     "false"
 273     <3> => "abc".to_string()
 274     "abc"
 275     <4> => [ "dev", "slack" ].to_string()
 276     "[ \"dev\", \"slack\" ]"
 277     <5> => { "/" = {}, "/var" = {} }.to_string()
 278     "{\n\t\"/\" = {\n\t}\n\t\"/var\" = {\n\t}\n}"
 279     <6> => DateTime(2016, 11, 25).to_string()
 280     "2016-11-25 00:00:00 +0100"
 281
 282 ### number <a id="global-functions-number"></a>
 283
 284 Signature:
 285
 286     function number(value)
 287
 288 Converts the value to a number.
 289
 290 Example:
 291
 292     $ icinga2 console
 293     Icinga 2 (version: v2.7.0)
 294     <1> => number(false)
 295     0.000000
 296     <2> => number("78")
 297     78.000000
 298
 299 ### bool <a id="global-functions-bool"></a>
 300
 301 Signature:
 302
 303     function bool(value)
 304
 305 Converts the value to a bool.
 306
 307 Example:
 308
 309     $ icinga2 console
 310     Icinga 2 (version: v2.7.0)
 311     <1> => bool(1)
 312     true
 313     <2> => bool(0)
 314     false
 315
 316 ### random <a id="global-functions-random"></a>
 317
 318 Signature:
 319
 320     function random()
 321
 322 Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h).
 323
 324     $ icinga2 console
 325     Icinga 2 (version: v2.7.0)
 326     <1> => random()
 327     1263171996.000000
 328     <2> => random()
 329     108402530.000000
 330
 331 ### log <a id="global-functions-log"></a>
 332
 333 Signature:
 334
 335     function log(value)
 336
 337 Writes a message to the log. Non-string values are converted to a JSON string.
 338
 339 Signature:
 340
 341     function log(severity, facility, value)
 342
 343 Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`,
 344 `LogInformation`, `LogWarning`, and `LogCritical`.
 345
 346 Non-string values are converted to a JSON string.
 347
 348 Example:
 349
 350     $ icinga2 console
 351     Icinga 2 (version: v2.7.0)
 352     <1> => log(LogCritical, "Console", "First line")
 353     critical/Console: First line
 354     null
 355     <2> => var groups = [ "devs", "slack" ]
 356     null
 357     <3> => log(LogCritical, "Console", groups)
 358     critical/Console: ["devs","slack"]
 359     null
 360
 361 ### typeof <a id="global-functions-typeof"></a>
 362
 363 Signature:
 364
 365     function typeof(value)
 366
 367 Returns the [Type](18-library-reference.md#type-type) object for a value.
 368
 369 Example:
 370
 371     $ icinga2 console
 372     Icinga 2 (version: v2.7.0)
 373     <1> => typeof(3) == Number
 374     true
 375     <2> => typeof("str") == String
 376     true
 377     <3> => typeof(true) == Boolean
 378     true
 379     <4> => typeof([ 1, 2, 3]) == Array
 380     true
 381     <5> => typeof({ a = 2, b = 3 }) == Dictionary
 382     true
 383
 384 ### get_time <a id="global-functions-get_time"></a>
 385
 386 Signature:
 387
 388     function get_time()
 389
 390 Returns the current UNIX timestamp as floating point number.
 391
 392 Example:
 393
 394     $ icinga2 console
 395     Icinga 2 (version: v2.7.0)
 396     <1> => get_time()
 397     1480072135.633008
 398     <2> => get_time()
 399     1480072140.401207
 400
 401 ### parse_performance_data <a id="global-functions-parse_performance_data"></a>
 402
 403 Signature:
 404
 405     function parse_performance_data(pd)
 406
 407 Parses a performance data string and returns an array describing the values.
 408
 409 Example:
 410
 411     $ icinga2 console
 412     Icinga 2 (version: v2.7.0)
 413     <1> => var pd = "'time'=1480074205.197363;;;"
 414     null
 415     <2> => parse_performance_data(pd)
 416     {
 417         counter = false
 418         crit = null
 419         label = "time"
 420         max = null
 421         min = null
 422         type = "PerfdataValue"
 423         unit = ""
 424         value = 1480074205.197363
 425         warn = null
 426     }
 427
 428 ### dirname <a id="global-functions-dirname"></a>
 429
 430 Signature:
 431
 432     function dirname(path)
 433
 434 Returns the directory portion of the specified path.
 435
 436 Example:
 437
 438     $ icinga2 console
 439     Icinga 2 (version: v2.7.0)
 440     <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
 441     null
 442     <2> => dirname(path)
 443     "/etc/icinga2/scripts"
 444
 445 ### basename <a id="global-functions-basename"></a>
 446
 447 Signature:
 448
 449     function basename(path)
 450
 451 Returns the filename portion of the specified path.
 452
 453 Example:
 454
 455     $ icinga2 console
 456     Icinga 2 (version: v2.7.0)
 457     <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
 458     null
 459     <2> => basename(path)
 460     "xmpp-notification.pl"
 461
 462 ### escape_shell_arg <a id="global-functions-escape_shell_arg"></a>
 463
 464 Signature:
 465
 466     function escape_shell_arg(text)
 467
 468 Escapes a string for use as a single shell argument.
 469
 470 Example:
 471
 472     $ icinga2 console
 473     Icinga 2 (version: v2.7.0)
 474     <1> => escape_shell_arg("'$host.name$' '$service.name$'")
 475     "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
 476
 477 ### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a>
 478
 479 Signature:
 480
 481     function escape_shell_cmd(text)
 482
 483 Escapes shell meta characters in a string.
 484
 485 Example:
 486
 487     $ icinga2 console
 488     Icinga 2 (version: v2.7.0)
 489     <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
 490     "/bin/echo 'shell test' \\$ENV"
 491
 492 ### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a>
 493
 494 Signature:
 495
 496     function escape_create_process_arg(text)
 497
 498 Escapes a string for use as an argument for CreateProcess(). Windows only.
 499
 500 ### sleep <a id="global-functions-sleep"></a>
 501
 502 Signature:
 503
 504     function sleep(interval)
 505
 506 Sleeps for the specified amount of time (in seconds).
 507
 508 ## Object Accessor Functions <a id="object-accessor-functions"></a>
 509
 510 These functions can be used to retrieve a reference to another object by name.
 511
 512 ### get_check_command <a id="objref-get_check_command"></a>
 513
 514 Signature:
 515
 516     function get_check_command(name);
 517
 518 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
 519
 520 ### get_event_command <a id="objref-get_event_command"></a>
 521
 522 Signature:
 523
 524     function get_event_command(name);
 525
 526 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
 527
 528 ### get_notification_command <a id="objref-get_notification_command"></a>
 529
 530 Signature:
 531
 532     function get_notification_command(name);
 533
 534 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
 535
 536 ### get_host <a id="objref-get_host"></a>
 537
 538 Signature:
 539
 540     function get_host(host_name);
 541
 542 Returns the Host object with the specified name, or `null` if no such Host object exists.
 543
 544
 545 ### get_service <a id="objref-get_service"></a>
 546
 547 Signature:
 548
 549     function get_service(host_name, service_name);
 550     function get_service(host, service_name);
 551
 552 Returns the Service object with the specified host name or object and service name pair,
 553 or `null` if no such Service object exists.
 554
 555 Example in the [debug console](11-cli-commands.md#cli-command-console)
 556 which fetches the `disk` service object from the current Icinga 2 node:
 557
 558 ```
 559 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
 560 Icinga 2 (version: v2.7.0)
 561
 562 <1> => get_service(NodeName, "disk")
 563 <2> => get_service(NodeName, "disk").__name
 564 "icinga2-master1.localdomain!disk"
 565
 566 <3> => get_service(get_host(NodeName), "disk").__name
 567 "icinga2-master1.localdomain!disk"
 568 ```
 569
 570 ### get_services <a id="objref-get_services"></a>
 571
 572 Signature:
 573
 574     function get_services(host_name);
 575     function get_services(host);
 576
 577 Returns an [array](17-language-reference.md#array) of service objects for the specified host name or object,
 578 or `null` if no such host object exists.
 579
 580 Example in the [debug console](11-cli-commands.md#cli-command-console)
 581 which fetches all service objects from the current Icinga 2 node:
 582
 583 ```
 584 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
 585 Icinga 2 (version: v2.7.0)
 586
 587 <1> => get_services(NodeName).map(s => s.name)
 588 [ "disk", "disk /", "http", "icinga", "load", "ping4", "ping6", "procs", "ssh", "users" ]
 589 ```
 590
 591 Note: [map](18-library-reference.md#array-map) takes a [lambda function](17-language-reference.md#lambdas) as argument. In this example
 592 we only want to collect and print the `name` attribute with `s => s.name`.
 593
 594 This works in a similar fashion for a host object where you can extract all service states
 595 in using the [map](18-library-reference.md#array-map) functionality:
 596
 597 ```
 598 <2> => get_services(get_host(NodeName)).map(s => s.state)
 599 [ 2.000000, 2.000000, 2.000000, 0.000000, 0.000000, 0.000000, 2.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000 ]
 600 ```
 601
 602 ### get_user <a id="objref-get_user"></a>
 603
 604 Signature:
 605
 606     function get_user(name);
 607
 608 Returns the User object with the specified name, or `null` if no such User object exists.
 609
 610 ### get_host_group <a id="objref-get_host_group"></a>
 611
 612 Signature:
 613
 614     function get_host_group(name);
 615
 616 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
 617
 618
 619 ### get_service_group <a id="objref-get_service_group"></a>
 620
 621 Signature:
 622
 623     function get_service_group(name);
 624
 625 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
 626
 627 ### get_user_group <a id="objref-get_user_group"></a>
 628
 629 Signature:
 630
 631     function get_user_group(name);
 632
 633 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
 634
 635
 636 ### get_time_period <a id="objref-get_time_period"></a>
 637
 638 Signature:
 639
 640     function get_time_period(name);
 641
 642 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
 643
 644
 645 ### get_object <a id="objref-get_object"></a>
 646
 647 Signature:
 648
 649     function get_object(type, name);
 650
 651 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
 652 to a type object.
 653
 654
 655 ### get_objects <a id="objref-get_objects"></a>
 656
 657 Signature:
 658
 659     function get_objects(type);
 660
 661 Returns an array of objects whose type matches the specified type. `type` must refer
 662 to a type object.
 663
 664
 665 ## Math object <a id="math-object"></a>
 666
 667 The global `Math` object can be used to access a number of mathematical constants
 668 and functions.
 669
 670 ### Math.E <a id="math-e"></a>
 671
 672 Euler's constant.
 673
 674 ### Math.LN2 <a id="math-ln2"></a>
 675
 676 Natural logarithm of 2.
 677
 678 ### Math.LN10 <a id="math-ln10"></a>
 679
 680 Natural logarithm of 10.
 681
 682 ### Math.LOG2E <a id="math-log2e"></a>
 683
 684 Base 2 logarithm of E.
 685
 686 ### Math.PI <a id="math-pi"></a>
 687
 688 The mathematical constant Pi.
 689
 690 ### Math.SQRT1_2 <a id="math-sqrt1_2"></a>
 691
 692 Square root of 1/2.
 693
 694 ### Math.SQRT2 <a id="math-sqrt2"></a>
 695
 696 Square root of 2.
 697
 698 ### Math.abs <a id="math-abs"></a>
 699
 700 Signature:
 701
 702     function abs(x);
 703
 704 Returns the absolute value of `x`.
 705
 706 ### Math.acos <a id="math-acos"></a>
 707
 708 Signature:
 709
 710     function acos(x);
 711
 712 Returns the arccosine of `x`.
 713
 714 ### Math.asin <a id="math-asin"></a>
 715
 716 Signature:
 717
 718     function asin(x);
 719
 720 Returns the arcsine of `x`.
 721
 722 ### Math.atan <a id="math-atan"></a>
 723
 724 Signature:
 725
 726     function atan(x);
 727
 728 Returns the arctangent of `x`.
 729
 730 ### Math.atan2 <a id="math-atan2"></a>
 731
 732 Signature:
 733
 734     function atan2(y, x);
 735
 736 Returns the arctangent of the quotient of `y` and `x`.
 737
 738 ### Math.ceil <a id="math-ceil"></a>
 739
 740 Signature:
 741
 742     function ceil(x);
 743
 744 Returns the smallest integer value not less than `x`.
 745
 746 ### Math.cos <a id="math-cos"></a>
 747
 748 Signature:
 749
 750     function cos(x);
 751
 752 Returns the cosine of `x`.
 753
 754 ### Math.exp <a id="math-exp"></a>
 755
 756 Signature:
 757
 758     function exp(x);
 759
 760 Returns E raised to the `x`th power.
 761
 762 ### Math.floor <a id="math-floor"></a>
 763
 764 Signature:
 765
 766     function floor(x);
 767
 768 Returns the largest integer value not greater than `x`.
 769
 770 ### Math.isinf <a id="math-isinf"></a>
 771
 772 Signature:
 773
 774     function isinf(x);
 775
 776 Returns whether `x` is infinite.
 777
 778 ### Math.isnan <a id="math-isnan"></a>
 779
 780 Signature:
 781
 782     function isnan(x);
 783
 784 Returns whether `x` is NaN (not-a-number).
 785
 786 ### Math.log <a id="math-log"></a>
 787
 788 Signature:
 789
 790     function log(x);
 791
 792 Returns the natural logarithm of `x`.
 793
 794 ### Math.max <a id="math-max"></a>
 795
 796 Signature:
 797
 798     function max(...);
 799
 800 Returns the largest argument. A variable number of arguments can be specified.
 801 If no arguments are given, -Infinity is returned.
 802
 803 ### Math.min <a id="math-min"></a>
 804
 805 Signature:
 806
 807     function min(...);
 808
 809 Returns the smallest argument. A variable number of arguments can be specified.
 810 If no arguments are given, +Infinity is returned.
 811
 812 ### Math.pow <a id="math-pow"></a>
 813
 814 Signature:
 815
 816     function pow(x, y);
 817
 818 Returns `x` raised to the `y`th power.
 819
 820 ### Math.random <a id="math-random"></a>
 821
 822 Signature:
 823
 824     function random();
 825
 826 Returns a pseudo-random number between 0 and 1.
 827
 828 ### Math.round <a id="math-round"></a>
 829
 830 Signature:
 831
 832     function round(x);
 833
 834 Returns `x` rounded to the nearest integer value.
 835
 836 ### Math.sign <a id="math-sign"></a>
 837
 838 Signature:
 839
 840     function sign(x);
 841
 842 Returns -1 if `x` is negative, 1 if `x` is positive
 843 and 0 if `x` is 0.
 844
 845 ### Math.sin <a id="math-sin"></a>
 846
 847 Signature:
 848
 849     function sin(x);
 850
 851 Returns the sine of `x`.
 852
 853 ### Math.sqrt <a id="math-sqrt"></a>
 854
 855 Signature:
 856
 857     function sqrt(x);
 858
 859 Returns the square root of `x`.
 860
 861 ### Math.tan <a id="math-tan"></a>
 862
 863 Signature:
 864
 865     function tan(x);
 866
 867 Returns the tangent of `x`.
 868
 869 ## Json object <a id="json-object"></a>
 870
 871 The global `Json` object can be used to encode and decode JSON.
 872
 873 ### Json.encode <a id="json-encode"></a>
 874
 875 Signature:
 876
 877     function encode(x);
 878
 879 Encodes an arbitrary value into JSON.
 880
 881 ### Json.decode <a id="json-decode"></a>
 882
 883 Signature:
 884
 885     function decode(x);
 886
 887 Decodes a JSON string.
 888
 889 ## Number type <a id="number-type"></a>
 890
 891 ### Number#to_string <a id="number-to_string"></a>
 892
 893 Signature:
 894
 895     function to_string();
 896
 897 The `to_string` method returns a string representation of the number.
 898
 899 Example:
 900
 901     var example = 7
 902         example.to_string() /* Returns "7" */
 903
 904 ## Boolean type <a id="boolean-type"></a>
 905
 906 ### Boolean#to_string <a id="boolean-to_string"></a>
 907
 908 Signature:
 909
 910     function to_string();
 911
 912 The `to_string` method returns a string representation of the boolean value.
 913
 914 Example:
 915
 916     var example = true
 917         example.to_string() /* Returns "true" */
 918
 919 ## String type <a id="string-type"></a>
 920
 921 ### String#find <a id="string-find"></a>
 922
 923 Signature:
 924
 925     function find(str, start);
 926
 927 Returns the zero-based index at which the string `str` was found in the string. If the string
 928 was not found, -1 is returned. `start` specifies the zero-based index at which `find` should
 929 start looking for the string (defaults to 0 when not specified).
 930
 931 Example:
 932
 933     "Hello World".find("World") /* Returns 6 */
 934
 935 ### String#contains <a id="string-contains"></a>
 936
 937 Signature:
 938
 939     function contains(str);
 940
 941 Returns `true` if the string `str` was found in the string. If the string
 942 was not found, `false` is returned. Use [find](18-library-reference.md#string-find)
 943 for getting the index instead.
 944
 945 Example:
 946
 947     "Hello World".contains("World") /* Returns true */
 948
 949 ### String#len <a id="string-len"></a>
 950
 951 Signature
 952
 953     function len();
 954
 955 Returns the length of the string in bytes. Note that depending on the encoding type of the string
 956 this is not necessarily the number of characters.
 957
 958 Example:
 959
 960     "Hello World".len() /* Returns 11 */
 961
 962 ### String#lower <a id="string-lower"></a>
 963
 964 Signature:
 965
 966     function lower();
 967
 968 Returns a copy of the string with all of its characters converted to lower-case.
 969
 970 Example:
 971
 972     "Hello World".lower() /* Returns "hello world" */
 973
 974 ### String#upper <a id="string-upper"></a>
 975
 976 Signature:
 977
 978     function upper();
 979
 980 Returns a copy of the string with all of its characters converted to upper-case.
 981
 982 Example:
 983
 984     "Hello World".upper() /* Returns "HELLO WORLD" */
 985
 986 ### String#replace <a id="string-replace"></a>
 987
 988 Signature:
 989
 990     function replace(search, replacement);
 991
 992 Returns a copy of the string with all occurences of the string specified in `search` replaced
 993 with the string specified in `replacement`.
 994
 995 ### String#split <a id="string-split"></a>
 996
 997 Signature:
 998
 999     function split(delimiters);
1000
1001 Splits a string into individual parts and returns them as an array. The `delimiters` argument
1002 specifies the characters which should be used as delimiters between parts.
1003
1004 Example:
1005
1006     "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
1007
1008 ### String#substr <a id="string-substr"></a>
1009
1010 Signature:
1011
1012     function substr(start, len);
1013
1014 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
1015 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
1016
1017 Example:
1018
1019     "Hello World".substr(6) /* Returns "World" */
1020
1021 ### String#to_string <a id="string-to_string"></a>
1022
1023 Signature:
1024
1025     function to_string();
1026
1027 Returns a copy of the string.
1028
1029 ### String#reverse <a id="string-reverse"></a>
1030
1031 Signature:
1032
1033     function reverse();
1034
1035 Returns a copy of the string in reverse order.
1036
1037 ### String#trim <a id="string-trim"></a>
1038
1039 Signature:
1040
1041     function trim();
1042
1043 Removes trailing whitespaces and returns the string.
1044
1045 ## Object type <a id="object-type"></a>
1046
1047 This is the base type for all types in the Icinga application.
1048
1049 ### Object#clone <a id="object-clone"></a>
1050
1051 Signature:
1052
1053      function clone();
1054
1055 Returns a copy of the object. Note that for object elements which are
1056 reference values (e.g. objects such as arrays or dictionaries) the entire
1057 object is recursively copied.
1058
1059 ### Object#to_string <a id="object-to-string"></a>
1060
1061 Signature:
1062
1063     function to_string();
1064
1065 Returns a string representation for the object. Unless overridden this returns a string
1066 of the format "Object of type '<typename>'" where <typename> is the name of the
1067 object's type.
1068
1069 Example:
1070
1071     [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
1072
1073 ### Object#type <a id="object-type-field"></a>
1074
1075 Signature:
1076
1077     String type;
1078
1079 Returns the object's type name. This attribute is read-only.
1080
1081 Example:
1082
1083     get_host("localhost").type /* Returns "Host" */
1084
1085 ## Type type <a id="type-type"></a>
1086
1087 Inherits methods from the [Object type](18-library-reference.md#object-type).
1088
1089 The `Type` type provides information about the underlying type of an object or scalar value.
1090
1091 All types are registered as global variables. For example, in order to obtain a reference to the `String` type the global variable `String` can be used.
1092
1093 ### Type#base <a id="type-base"></a>
1094
1095 Signature:
1096
1097     Type base;
1098
1099 Returns a reference to the type's base type. This attribute is read-only.
1100
1101 Example:
1102
1103     Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
1104
1105 ### Type#name <a id="type-name"></a>
1106
1107 Signature:
1108
1109     String name;
1110
1111 Returns the name of the type.
1112
1113 ### Type#prototype <a id="type-prototype"></a>
1114
1115 Signature:
1116
1117     Object prototype;
1118
1119 Returns the prototype object for the type. When an attribute is accessed on an object that doesn't exist the prototype object is checked to see if an attribute with the requested name exists. If it does, the attribute's value is returned.
1120
1121 The prototype functionality is used to implement methods.
1122
1123 Example:
1124
1125     3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
1126
1127 ## Array type <a id="array-type"></a>
1128
1129 Inherits methods from the [Object type](18-library-reference.md#object-type).
1130
1131 ### Array#add <a id="array-add"></a>
1132
1133 Signature:
1134
1135     function add(value);
1136
1137 Adds a new value after the last element in the array.
1138
1139 ### Array#clear <a id="array-clear"></a>
1140
1141 Signature:
1142
1143     function clear();
1144
1145 Removes all elements from the array.
1146
1147 ### Array#shallow_clone <a id="array-shallow-clone"></a>
1148
1149     function shallow_clone();
1150
1151 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
1152 as arrays and dictionaries) only the references are copied.
1153
1154 ### Array#contains <a id="array-contains"></a>
1155
1156 Signature:
1157
1158     function contains(value);
1159
1160 Returns true if the array contains the specified value, false otherwise.
1161
1162 ### Array#len <a id="array-len"></a>
1163
1164 Signature:
1165
1166     function len();
1167
1168 Returns the number of elements contained in the array.
1169
1170 ### Array#remove <a id="array-remove"></a>
1171
1172 Signature:
1173
1174     function remove(index);
1175
1176 Removes the element at the specified zero-based index.
1177
1178 ### Array#set <a id="array-set"></a>
1179
1180 Signature:
1181
1182     function set(index, value);
1183
1184 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
1185 which already exists in the array.
1186
1187 ### Array#get <a id="array-get"></a>
1188
1189 Signature:
1190
1191     function get(index);
1192
1193 Retrieves the element at the specified zero-based index.
1194
1195 ### Array#sort <a id="array-sort"></a>
1196
1197 Signature:
1198
1199     function sort(less_cmp);
1200
1201 Returns a copy of the array where all items are sorted. The items are
1202 compared using the `<` (less-than) operator. A custom comparator function
1203 can be specified with the `less_cmp` argument.
1204
1205 ### Array#join <a id="array-join"></a>
1206
1207 Signature:
1208
1209     function join(separator);
1210
1211 Joins all elements of the array using the specified separator.
1212
1213 ### Array#reverse <a id="array-reverse"></a>
1214
1215 Signature:
1216
1217     function reverse();
1218
1219 Returns a new array with all elements of the current array in reverse order.
1220
1221 ### Array#map <a id="array-map"></a>
1222
1223 Signature:
1224
1225     function map(func);
1226
1227 Calls `func(element)` for each of the elements in the array and returns
1228 a new array containing the return values of these function calls.
1229
1230 ### Array#reduce <a id="array-reduce"></a>
1231
1232 Signature:
1233
1234     function reduce(func);
1235
1236 Reduces the elements of the array into a single value by calling the provided
1237 function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
1238 or results from previous function calls.
1239
1240 ### Array#filter <a id="array-filter"></a>
1241
1242 Signature:
1243
1244     function filter(func);
1245
1246 Returns a copy of the array containing only the elements for which `func(element)`
1247 is true.
1248
1249 ### Array#any <a id="array-any"></a>
1250
1251 Signature:
1252
1253     function any(func);
1254
1255 Returns true if the array contains at least one element for which `func(element)`
1256 is true, false otherwise.
1257
1258 ### Array#all <a id="array-all"></a>
1259
1260 Signature:
1261
1262     function all(func);
1263
1264 Returns true if the array contains only elements for which `func(element)`
1265 is true, false otherwise.
1266
1267 ### Array#unique <a id="array-unique"></a>
1268
1269 Signature:
1270
1271     function unique();
1272
1273 Returns a copy of the array with all duplicate elements removed. The original order
1274 of the array is not preserved.
1275
1276 ## Dictionary type <a id="dictionary-type"></a>
1277
1278 Inherits methods from the [Object type](18-library-reference.md#object-type).
1279
1280 ### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
1281
1282 Signature:
1283
1284     function shallow_clone();
1285
1286 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
1287 as arrays and dictionaries) only the references are copied.
1288
1289 ### Dictionary#contains <a id="dictionary-contains"></a>
1290
1291 Signature:
1292
1293     function contains(key);
1294
1295 Returns true if a dictionary item with the specified `key` exists, false otherwise.
1296
1297 ### Dictionary#len <a id="dictionary-len"></a>
1298
1299 Signature:
1300
1301     function len();
1302
1303 Returns the number of items contained in the dictionary.
1304
1305 ### Dictionary#remove <a id="dictionary-remove"></a>
1306
1307 Signature:
1308
1309     function remove(key);
1310
1311 Removes the item with the specified `key`. Trying to remove an item which does not exist
1312 is a no-op.
1313
1314 ### Dictionary#set <a id="dictionary-set"></a>
1315
1316 Signature:
1317
1318     function set(key, value);
1319
1320 Creates or updates an item with the specified `key` and `value`.
1321
1322 ### Dictionary#get <a id="dictionary-get"></a>
1323
1324 Signature:
1325
1326     function get(key);
1327
1328 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
1329 in the dictionary.
1330
1331 ### Dictionary#keys <a id="dictionary-keys"></a>
1332
1333 Signature:
1334
1335     function keys();
1336
1337 Returns a list of keys for all items that are currently in the dictionary.
1338
1339 ### Dictionary#values <a id="dictionary-values"></a>
1340
1341 Signature:
1342
1343     function values();
1344
1345 Returns a list of values for all items that are currently in the dictionary.
1346
1347 ## Function type <a id="scriptfunction-type"></a>
1348
1349 Inherits methods from the [Object type](18-library-reference.md#object-type).
1350
1351 ### Function#call <a id="scriptfunction-call"></a>
1352
1353 Signature:
1354
1355     function call(thisArg, ...);
1356
1357 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1358 scope for the function. All other arguments are passed directly to the function.
1359
1360 Example:
1361
1362     function set_x(val) {
1363           this.x = val
1364         }
1365
1366         dict = {}
1367
1368         set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
1369
1370 ### Function#callv <a id="scriptfunction-callv"></a>
1371
1372 Signature:
1373
1374     function callv(thisArg, args);
1375
1376 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1377 scope for the function. The items in the `args` array are passed to the function as individual arguments.
1378
1379 Example:
1380
1381     function set_x(val) {
1382           this.x = val
1383         }
1384
1385         var dict = {}
1386
1387         var args = [ 7 ]
1388
1389         set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
1390
1391 ## DateTime type <a id="datetime-type"></a>
1392
1393 Inherits methods from the [Object type](18-library-reference.md#object-type).
1394
1395 ### DateTime constructor <a id="datetime-ctor"></a>
1396
1397 Signature:
1398
1399     function DateTime()
1400     function DateTime(unixTimestamp)
1401     function DateTime(year, month, day)
1402     function DateTime(year, month, day, hours, minutes, seconds)
1403
1404 Constructs a new DateTime object. When no arguments are specified for the constructor a new
1405 DateTime object representing the current time is created.
1406
1407 Example:
1408
1409     var d1 = DateTime() /* current time */
1410     var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
1411
1412 ### DateTime arithmetic <a id="datetime-arithmetic"></a>
1413
1414 Subtracting two DateTime objects yields the interval between them, in seconds.
1415
1416 Example:
1417
1418     var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */
1419
1420 Subtracting a number from a DateTime object yields a new DateTime object that is further in the past:
1421
1422 Example:
1423
1424     var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */
1425
1426 Adding a number to a DateTime object yields a new DateTime object that is in the future:
1427
1428 Example:
1429
1430     var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */
1431
1432 ### DateTime#format <a id="datetime-format"></a>
1433
1434 Signature:
1435
1436     function format(fmt)
1437
1438 Returns a string representation for the DateTime object using the specified format string.
1439 The format string may contain format conversion placeholders as specified in strftime(3).
1440
1441 Example:
1442
1443     var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
1444
1445 ### DateTime#to_string <a id="datetime-tostring"></a>
1446
1447 Signature:
1448
1449     function to_string()
1450
1451 Returns a string representation for the DateTime object. Uses a suitable default format.
1452
1453 Example:
1454
1455     var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */