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

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