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