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 ### path\_exists <a id="global-functions-path-exists"></a>
 463
 464 Signature:
 465
 466     function path_exists(path)
 467
 468 Returns true if the specified path exists, false otherwise.
 469
 470 Example:
 471
 472     $ icinga2 console
 473     Icinga 2 (version: v2.7.0)
 474     <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
 475     null
 476     <2> => path_exists(path)
 477     true
 478
 479 ### glob <a id="global-functions-glob"></a>
 480
 481 Signature:
 482
 483     function glob(pathSpec, type)
 484
 485 Returns an array containing all paths which match the
 486 `pathSpec` argument.
 487
 488 The `type` argument is optional and specifies which types
 489 of paths are matched. This can be a combination of the `GlobFile`
 490 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
 491
 492     $ icinga2 console
 493     Icinga 2 (version: v2.7.0)
 494     <1> => var pathSpec = "/etc/icinga2/conf.d/*.conf"
 495     null
 496     <2> => glob(pathSpec)
 497     [ "/etc/icinga2/conf.d/app.conf", "/etc/icinga2/conf.d/commands.conf", ... ]
 498
 499 ### glob\_recursive <a id="global-functions-glob-recursive"></a>
 500
 501 Signature:
 502
 503     function glob_recursive(path, pattern, type)
 504
 505 Recursively descends into the specified directory and returns an array containing
 506 all paths which match the `pattern` argument.
 507
 508 The `type` argument is optional and specifies which types
 509 of paths are matched. This can be a combination of the `GlobFile`
 510 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
 511
 512     $ icinga2 console
 513     Icinga 2 (version: v2.7.0)
 514     <1> => var path = "/etc/icinga2/zones.d/"
 515     null
 516     <2> => var pattern = "*.conf"
 517     null
 518     <3> => glob_recursive(path, pattern)
 519     [ "/etc/icinga2/zones.d/global-templates/templates.conf", "/etc/icinga2/zones.d/master/hosts.conf", ... ]
 520
 521 ### escape_shell_arg <a id="global-functions-escape_shell_arg"></a>
 522
 523 Signature:
 524
 525     function escape_shell_arg(text)
 526
 527 Escapes a string for use as a single shell argument.
 528
 529 Example:
 530
 531     $ icinga2 console
 532     Icinga 2 (version: v2.7.0)
 533     <1> => escape_shell_arg("'$host.name$' '$service.name$'")
 534     "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
 535
 536 ### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a>
 537
 538 Signature:
 539
 540     function escape_shell_cmd(text)
 541
 542 Escapes shell meta characters in a string.
 543
 544 Example:
 545
 546     $ icinga2 console
 547     Icinga 2 (version: v2.7.0)
 548     <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
 549     "/bin/echo 'shell test' \\$ENV"
 550
 551 ### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a>
 552
 553 Signature:
 554
 555     function escape_create_process_arg(text)
 556
 557 Escapes a string for use as an argument for CreateProcess(). Windows only.
 558
 559 ### sleep <a id="global-functions-sleep"></a>
 560
 561 Signature:
 562
 563     function sleep(interval)
 564
 565 Sleeps for the specified amount of time (in seconds).
 566
 567 ## Object Accessor Functions <a id="object-accessor-functions"></a>
 568
 569 These functions can be used to retrieve a reference to another object by name.
 570
 571 ### get_check_command <a id="objref-get_check_command"></a>
 572
 573 Signature:
 574
 575     function get_check_command(name);
 576
 577 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
 578
 579 ### get_event_command <a id="objref-get_event_command"></a>
 580
 581 Signature:
 582
 583     function get_event_command(name);
 584
 585 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
 586
 587 ### get_notification_command <a id="objref-get_notification_command"></a>
 588
 589 Signature:
 590
 591     function get_notification_command(name);
 592
 593 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
 594
 595 ### get_host <a id="objref-get_host"></a>
 596
 597 Signature:
 598
 599     function get_host(host_name);
 600
 601 Returns the Host object with the specified name, or `null` if no such Host object exists.
 602
 603
 604 ### get_service <a id="objref-get_service"></a>
 605
 606 Signature:
 607
 608     function get_service(host_name, service_name);
 609     function get_service(host, service_name);
 610
 611 Returns the Service object with the specified host name or object and service name pair,
 612 or `null` if no such Service object exists.
 613
 614 Example in the [debug console](11-cli-commands.md#cli-command-console)
 615 which fetches the `disk` service object from the current Icinga 2 node:
 616
 617 ```
 618 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
 619 Icinga 2 (version: v2.7.0)
 620
 621 <1> => get_service(NodeName, "disk")
 622 <2> => get_service(NodeName, "disk").__name
 623 "icinga2-master1.localdomain!disk"
 624
 625 <3> => get_service(get_host(NodeName), "disk").__name
 626 "icinga2-master1.localdomain!disk"
 627 ```
 628
 629 ### get_services <a id="objref-get_services"></a>
 630
 631 Signature:
 632
 633     function get_services(host_name);
 634     function get_services(host);
 635
 636 Returns an [array](17-language-reference.md#array) of service objects for the specified host name or object,
 637 or `null` if no such host object exists.
 638
 639 Example in the [debug console](11-cli-commands.md#cli-command-console)
 640 which fetches all service objects from the current Icinga 2 node:
 641
 642 ```
 643 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
 644 Icinga 2 (version: v2.7.0)
 645
 646 <1> => get_services(NodeName).map(s => s.name)
 647 [ "disk", "disk /", "http", "icinga", "load", "ping4", "ping6", "procs", "ssh", "users" ]
 648 ```
 649
 650 Note: [map](18-library-reference.md#array-map) takes a [lambda function](17-language-reference.md#lambdas) as argument. In this example
 651 we only want to collect and print the `name` attribute with `s => s.name`.
 652
 653 This works in a similar fashion for a host object where you can extract all service states
 654 in using the [map](18-library-reference.md#array-map) functionality:
 655
 656 ```
 657 <2> => get_services(get_host(NodeName)).map(s => s.state)
 658 [ 2.000000, 2.000000, 2.000000, 0.000000, 0.000000, 0.000000, 2.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000 ]
 659 ```
 660
 661 ### get_user <a id="objref-get_user"></a>
 662
 663 Signature:
 664
 665     function get_user(name);
 666
 667 Returns the User object with the specified name, or `null` if no such User object exists.
 668
 669 ### get_host_group <a id="objref-get_host_group"></a>
 670
 671 Signature:
 672
 673     function get_host_group(name);
 674
 675 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
 676
 677
 678 ### get_service_group <a id="objref-get_service_group"></a>
 679
 680 Signature:
 681
 682     function get_service_group(name);
 683
 684 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
 685
 686 ### get_user_group <a id="objref-get_user_group"></a>
 687
 688 Signature:
 689
 690     function get_user_group(name);
 691
 692 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
 693
 694
 695 ### get_time_period <a id="objref-get_time_period"></a>
 696
 697 Signature:
 698
 699     function get_time_period(name);
 700
 701 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
 702
 703
 704 ### get_object <a id="objref-get_object"></a>
 705
 706 Signature:
 707
 708     function get_object(type, name);
 709
 710 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
 711 to a type object.
 712
 713
 714 ### get_objects <a id="objref-get_objects"></a>
 715
 716 Signature:
 717
 718     function get_objects(type);
 719
 720 Returns an array of objects whose type matches the specified type. `type` must refer
 721 to a type object.
 722
 723
 724 ## Math object <a id="math-object"></a>
 725
 726 The global `Math` object can be used to access a number of mathematical constants
 727 and functions.
 728
 729 ### Math.E <a id="math-e"></a>
 730
 731 Euler's constant.
 732
 733 ### Math.LN2 <a id="math-ln2"></a>
 734
 735 Natural logarithm of 2.
 736
 737 ### Math.LN10 <a id="math-ln10"></a>
 738
 739 Natural logarithm of 10.
 740
 741 ### Math.LOG2E <a id="math-log2e"></a>
 742
 743 Base 2 logarithm of E.
 744
 745 ### Math.PI <a id="math-pi"></a>
 746
 747 The mathematical constant Pi.
 748
 749 ### Math.SQRT1_2 <a id="math-sqrt1_2"></a>
 750
 751 Square root of 1/2.
 752
 753 ### Math.SQRT2 <a id="math-sqrt2"></a>
 754
 755 Square root of 2.
 756
 757 ### Math.abs <a id="math-abs"></a>
 758
 759 Signature:
 760
 761     function abs(x);
 762
 763 Returns the absolute value of `x`.
 764
 765 ### Math.acos <a id="math-acos"></a>
 766
 767 Signature:
 768
 769     function acos(x);
 770
 771 Returns the arccosine of `x`.
 772
 773 ### Math.asin <a id="math-asin"></a>
 774
 775 Signature:
 776
 777     function asin(x);
 778
 779 Returns the arcsine of `x`.
 780
 781 ### Math.atan <a id="math-atan"></a>
 782
 783 Signature:
 784
 785     function atan(x);
 786
 787 Returns the arctangent of `x`.
 788
 789 ### Math.atan2 <a id="math-atan2"></a>
 790
 791 Signature:
 792
 793     function atan2(y, x);
 794
 795 Returns the arctangent of the quotient of `y` and `x`.
 796
 797 ### Math.ceil <a id="math-ceil"></a>
 798
 799 Signature:
 800
 801     function ceil(x);
 802
 803 Returns the smallest integer value not less than `x`.
 804
 805 ### Math.cos <a id="math-cos"></a>
 806
 807 Signature:
 808
 809     function cos(x);
 810
 811 Returns the cosine of `x`.
 812
 813 ### Math.exp <a id="math-exp"></a>
 814
 815 Signature:
 816
 817     function exp(x);
 818
 819 Returns E raised to the `x`th power.
 820
 821 ### Math.floor <a id="math-floor"></a>
 822
 823 Signature:
 824
 825     function floor(x);
 826
 827 Returns the largest integer value not greater than `x`.
 828
 829 ### Math.isinf <a id="math-isinf"></a>
 830
 831 Signature:
 832
 833     function isinf(x);
 834
 835 Returns whether `x` is infinite.
 836
 837 ### Math.isnan <a id="math-isnan"></a>
 838
 839 Signature:
 840
 841     function isnan(x);
 842
 843 Returns whether `x` is NaN (not-a-number).
 844
 845 ### Math.log <a id="math-log"></a>
 846
 847 Signature:
 848
 849     function log(x);
 850
 851 Returns the natural logarithm of `x`.
 852
 853 ### Math.max <a id="math-max"></a>
 854
 855 Signature:
 856
 857     function max(...);
 858
 859 Returns the largest argument. A variable number of arguments can be specified.
 860 If no arguments are given, -Infinity is returned.
 861
 862 ### Math.min <a id="math-min"></a>
 863
 864 Signature:
 865
 866     function min(...);
 867
 868 Returns the smallest argument. A variable number of arguments can be specified.
 869 If no arguments are given, +Infinity is returned.
 870
 871 ### Math.pow <a id="math-pow"></a>
 872
 873 Signature:
 874
 875     function pow(x, y);
 876
 877 Returns `x` raised to the `y`th power.
 878
 879 ### Math.random <a id="math-random"></a>
 880
 881 Signature:
 882
 883     function random();
 884
 885 Returns a pseudo-random number between 0 and 1.
 886
 887 ### Math.round <a id="math-round"></a>
 888
 889 Signature:
 890
 891     function round(x);
 892
 893 Returns `x` rounded to the nearest integer value.
 894
 895 ### Math.sign <a id="math-sign"></a>
 896
 897 Signature:
 898
 899     function sign(x);
 900
 901 Returns -1 if `x` is negative, 1 if `x` is positive
 902 and 0 if `x` is 0.
 903
 904 ### Math.sin <a id="math-sin"></a>
 905
 906 Signature:
 907
 908     function sin(x);
 909
 910 Returns the sine of `x`.
 911
 912 ### Math.sqrt <a id="math-sqrt"></a>
 913
 914 Signature:
 915
 916     function sqrt(x);
 917
 918 Returns the square root of `x`.
 919
 920 ### Math.tan <a id="math-tan"></a>
 921
 922 Signature:
 923
 924     function tan(x);
 925
 926 Returns the tangent of `x`.
 927
 928 ## Json object <a id="json-object"></a>
 929
 930 The global `Json` object can be used to encode and decode JSON.
 931
 932 ### Json.encode <a id="json-encode"></a>
 933
 934 Signature:
 935
 936     function encode(x);
 937
 938 Encodes an arbitrary value into JSON.
 939
 940 ### Json.decode <a id="json-decode"></a>
 941
 942 Signature:
 943
 944     function decode(x);
 945
 946 Decodes a JSON string.
 947
 948 ## Number type <a id="number-type"></a>
 949
 950 ### Number#to_string <a id="number-to_string"></a>
 951
 952 Signature:
 953
 954     function to_string();
 955
 956 The `to_string` method returns a string representation of the number.
 957
 958 Example:
 959
 960     var example = 7
 961         example.to_string() /* Returns "7" */
 962
 963 ## Boolean type <a id="boolean-type"></a>
 964
 965 ### Boolean#to_string <a id="boolean-to_string"></a>
 966
 967 Signature:
 968
 969     function to_string();
 970
 971 The `to_string` method returns a string representation of the boolean value.
 972
 973 Example:
 974
 975     var example = true
 976         example.to_string() /* Returns "true" */
 977
 978 ## String type <a id="string-type"></a>
 979
 980 ### String#find <a id="string-find"></a>
 981
 982 Signature:
 983
 984     function find(str, start);
 985
 986 Returns the zero-based index at which the string `str` was found in the string. If the string
 987 was not found, -1 is returned. `start` specifies the zero-based index at which `find` should
 988 start looking for the string (defaults to 0 when not specified).
 989
 990 Example:
 991
 992     "Hello World".find("World") /* Returns 6 */
 993
 994 ### String#contains <a id="string-contains"></a>
 995
 996 Signature:
 997
 998     function contains(str);
 999
1000 Returns `true` if the string `str` was found in the string. If the string
1001 was not found, `false` is returned. Use [find](18-library-reference.md#string-find)
1002 for getting the index instead.
1003
1004 Example:
1005
1006     "Hello World".contains("World") /* Returns true */
1007
1008 ### String#len <a id="string-len"></a>
1009
1010 Signature
1011
1012     function len();
1013
1014 Returns the length of the string in bytes. Note that depending on the encoding type of the string
1015 this is not necessarily the number of characters.
1016
1017 Example:
1018
1019     "Hello World".len() /* Returns 11 */
1020
1021 ### String#lower <a id="string-lower"></a>
1022
1023 Signature:
1024
1025     function lower();
1026
1027 Returns a copy of the string with all of its characters converted to lower-case.
1028
1029 Example:
1030
1031     "Hello World".lower() /* Returns "hello world" */
1032
1033 ### String#upper <a id="string-upper"></a>
1034
1035 Signature:
1036
1037     function upper();
1038
1039 Returns a copy of the string with all of its characters converted to upper-case.
1040
1041 Example:
1042
1043     "Hello World".upper() /* Returns "HELLO WORLD" */
1044
1045 ### String#replace <a id="string-replace"></a>
1046
1047 Signature:
1048
1049     function replace(search, replacement);
1050
1051 Returns a copy of the string with all occurences of the string specified in `search` replaced
1052 with the string specified in `replacement`.
1053
1054 ### String#split <a id="string-split"></a>
1055
1056 Signature:
1057
1058     function split(delimiters);
1059
1060 Splits a string into individual parts and returns them as an array. The `delimiters` argument
1061 specifies the characters which should be used as delimiters between parts.
1062
1063 Example:
1064
1065     "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
1066
1067 ### String#substr <a id="string-substr"></a>
1068
1069 Signature:
1070
1071     function substr(start, len);
1072
1073 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
1074 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
1075
1076 Example:
1077
1078     "Hello World".substr(6) /* Returns "World" */
1079
1080 ### String#to_string <a id="string-to_string"></a>
1081
1082 Signature:
1083
1084     function to_string();
1085
1086 Returns a copy of the string.
1087
1088 ### String#reverse <a id="string-reverse"></a>
1089
1090 Signature:
1091
1092     function reverse();
1093
1094 Returns a copy of the string in reverse order.
1095
1096 ### String#trim <a id="string-trim"></a>
1097
1098 Signature:
1099
1100     function trim();
1101
1102 Removes trailing whitespaces and returns the string.
1103
1104 ## Object type <a id="object-type"></a>
1105
1106 This is the base type for all types in the Icinga application.
1107
1108 ### Object#clone <a id="object-clone"></a>
1109
1110 Signature:
1111
1112      function clone();
1113
1114 Returns a copy of the object. Note that for object elements which are
1115 reference values (e.g. objects such as arrays or dictionaries) the entire
1116 object is recursively copied.
1117
1118 ### Object#to_string <a id="object-to-string"></a>
1119
1120 Signature:
1121
1122     function to_string();
1123
1124 Returns a string representation for the object. Unless overridden this returns a string
1125 of the format "Object of type '<typename>'" where <typename> is the name of the
1126 object's type.
1127
1128 Example:
1129
1130     [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
1131
1132 ### Object#type <a id="object-type-field"></a>
1133
1134 Signature:
1135
1136     String type;
1137
1138 Returns the object's type name. This attribute is read-only.
1139
1140 Example:
1141
1142     get_host("localhost").type /* Returns "Host" */
1143
1144 ## Type type <a id="type-type"></a>
1145
1146 Inherits methods from the [Object type](18-library-reference.md#object-type).
1147
1148 The `Type` type provides information about the underlying type of an object or scalar value.
1149
1150 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.
1151
1152 ### Type#base <a id="type-base"></a>
1153
1154 Signature:
1155
1156     Type base;
1157
1158 Returns a reference to the type's base type. This attribute is read-only.
1159
1160 Example:
1161
1162     Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
1163
1164 ### Type#name <a id="type-name"></a>
1165
1166 Signature:
1167
1168     String name;
1169
1170 Returns the name of the type.
1171
1172 ### Type#prototype <a id="type-prototype"></a>
1173
1174 Signature:
1175
1176     Object prototype;
1177
1178 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.
1179
1180 The prototype functionality is used to implement methods.
1181
1182 Example:
1183
1184     3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
1185
1186 ## Array type <a id="array-type"></a>
1187
1188 Inherits methods from the [Object type](18-library-reference.md#object-type).
1189
1190 ### Array#add <a id="array-add"></a>
1191
1192 Signature:
1193
1194     function add(value);
1195
1196 Adds a new value after the last element in the array.
1197
1198 ### Array#clear <a id="array-clear"></a>
1199
1200 Signature:
1201
1202     function clear();
1203
1204 Removes all elements from the array.
1205
1206 ### Array#shallow_clone <a id="array-shallow-clone"></a>
1207
1208     function shallow_clone();
1209
1210 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
1211 as arrays and dictionaries) only the references are copied.
1212
1213 ### Array#contains <a id="array-contains"></a>
1214
1215 Signature:
1216
1217     function contains(value);
1218
1219 Returns true if the array contains the specified value, false otherwise.
1220
1221 ### Array#len <a id="array-len"></a>
1222
1223 Signature:
1224
1225     function len();
1226
1227 Returns the number of elements contained in the array.
1228
1229 ### Array#remove <a id="array-remove"></a>
1230
1231 Signature:
1232
1233     function remove(index);
1234
1235 Removes the element at the specified zero-based index.
1236
1237 ### Array#set <a id="array-set"></a>
1238
1239 Signature:
1240
1241     function set(index, value);
1242
1243 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
1244 which already exists in the array.
1245
1246 ### Array#get <a id="array-get"></a>
1247
1248 Signature:
1249
1250     function get(index);
1251
1252 Retrieves the element at the specified zero-based index.
1253
1254 ### Array#sort <a id="array-sort"></a>
1255
1256 Signature:
1257
1258     function sort(less_cmp);
1259
1260 Returns a copy of the array where all items are sorted. The items are
1261 compared using the `<` (less-than) operator. A custom comparator function
1262 can be specified with the `less_cmp` argument.
1263
1264 ### Array#join <a id="array-join"></a>
1265
1266 Signature:
1267
1268     function join(separator);
1269
1270 Joins all elements of the array using the specified separator.
1271
1272 ### Array#reverse <a id="array-reverse"></a>
1273
1274 Signature:
1275
1276     function reverse();
1277
1278 Returns a new array with all elements of the current array in reverse order.
1279
1280 ### Array#map <a id="array-map"></a>
1281
1282 Signature:
1283
1284     function map(func);
1285
1286 Calls `func(element)` for each of the elements in the array and returns
1287 a new array containing the return values of these function calls.
1288
1289 ### Array#reduce <a id="array-reduce"></a>
1290
1291 Signature:
1292
1293     function reduce(func);
1294
1295 Reduces the elements of the array into a single value by calling the provided
1296 function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
1297 or results from previous function calls.
1298
1299 ### Array#filter <a id="array-filter"></a>
1300
1301 Signature:
1302
1303     function filter(func);
1304
1305 Returns a copy of the array containing only the elements for which `func(element)`
1306 is true.
1307
1308 ### Array#any <a id="array-any"></a>
1309
1310 Signature:
1311
1312     function any(func);
1313
1314 Returns true if the array contains at least one element for which `func(element)`
1315 is true, false otherwise.
1316
1317 ### Array#all <a id="array-all"></a>
1318
1319 Signature:
1320
1321     function all(func);
1322
1323 Returns true if the array contains only elements for which `func(element)`
1324 is true, false otherwise.
1325
1326 ### Array#unique <a id="array-unique"></a>
1327
1328 Signature:
1329
1330     function unique();
1331
1332 Returns a copy of the array with all duplicate elements removed. The original order
1333 of the array is not preserved.
1334
1335 ## Dictionary type <a id="dictionary-type"></a>
1336
1337 Inherits methods from the [Object type](18-library-reference.md#object-type).
1338
1339 ### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
1340
1341 Signature:
1342
1343     function shallow_clone();
1344
1345 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
1346 as arrays and dictionaries) only the references are copied.
1347
1348 ### Dictionary#contains <a id="dictionary-contains"></a>
1349
1350 Signature:
1351
1352     function contains(key);
1353
1354 Returns true if a dictionary item with the specified `key` exists, false otherwise.
1355
1356 ### Dictionary#len <a id="dictionary-len"></a>
1357
1358 Signature:
1359
1360     function len();
1361
1362 Returns the number of items contained in the dictionary.
1363
1364 ### Dictionary#remove <a id="dictionary-remove"></a>
1365
1366 Signature:
1367
1368     function remove(key);
1369
1370 Removes the item with the specified `key`. Trying to remove an item which does not exist
1371 is a no-op.
1372
1373 ### Dictionary#set <a id="dictionary-set"></a>
1374
1375 Signature:
1376
1377     function set(key, value);
1378
1379 Creates or updates an item with the specified `key` and `value`.
1380
1381 ### Dictionary#get <a id="dictionary-get"></a>
1382
1383 Signature:
1384
1385     function get(key);
1386
1387 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
1388 in the dictionary.
1389
1390 ### Dictionary#keys <a id="dictionary-keys"></a>
1391
1392 Signature:
1393
1394     function keys();
1395
1396 Returns a list of keys for all items that are currently in the dictionary.
1397
1398 ### Dictionary#values <a id="dictionary-values"></a>
1399
1400 Signature:
1401
1402     function values();
1403
1404 Returns a list of values for all items that are currently in the dictionary.
1405
1406 ## Function type <a id="scriptfunction-type"></a>
1407
1408 Inherits methods from the [Object type](18-library-reference.md#object-type).
1409
1410 ### Function#call <a id="scriptfunction-call"></a>
1411
1412 Signature:
1413
1414     function call(thisArg, ...);
1415
1416 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1417 scope for the function. All other arguments are passed directly to the function.
1418
1419 Example:
1420
1421     function set_x(val) {
1422           this.x = val
1423         }
1424
1425         dict = {}
1426
1427         set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
1428
1429 ### Function#callv <a id="scriptfunction-callv"></a>
1430
1431 Signature:
1432
1433     function callv(thisArg, args);
1434
1435 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1436 scope for the function. The items in the `args` array are passed to the function as individual arguments.
1437
1438 Example:
1439
1440     function set_x(val) {
1441           this.x = val
1442         }
1443
1444         var dict = {}
1445
1446         var args = [ 7 ]
1447
1448         set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
1449
1450 ## DateTime type <a id="datetime-type"></a>
1451
1452 Inherits methods from the [Object type](18-library-reference.md#object-type).
1453
1454 ### DateTime constructor <a id="datetime-ctor"></a>
1455
1456 Signature:
1457
1458     function DateTime()
1459     function DateTime(unixTimestamp)
1460     function DateTime(year, month, day)
1461     function DateTime(year, month, day, hours, minutes, seconds)
1462
1463 Constructs a new DateTime object. When no arguments are specified for the constructor a new
1464 DateTime object representing the current time is created.
1465
1466 Example:
1467
1468     var d1 = DateTime() /* current time */
1469     var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
1470
1471 ### DateTime arithmetic <a id="datetime-arithmetic"></a>
1472
1473 Subtracting two DateTime objects yields the interval between them, in seconds.
1474
1475 Example:
1476
1477     var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */
1478
1479 Subtracting a number from a DateTime object yields a new DateTime object that is further in the past:
1480
1481 Example:
1482
1483     var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */
1484
1485 Adding a number to a DateTime object yields a new DateTime object that is in the future:
1486
1487 Example:
1488
1489     var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */
1490
1491 ### DateTime#format <a id="datetime-format"></a>
1492
1493 Signature:
1494
1495     function format(fmt)
1496
1497 Returns a string representation for the DateTime object using the specified format string.
1498 The format string may contain format conversion placeholders as specified in strftime(3).
1499
1500 Example:
1501
1502     var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
1503
1504 ### DateTime#to_string <a id="datetime-tostring"></a>
1505
1506 Signature:
1507
1508     function to_string()
1509
1510 Returns a string representation for the DateTime object. Uses a suitable default format.
1511
1512 Example:
1513
1514     var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */