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