1# Library Reference <a id="library-reference"></a> 2 3## Global functions <a id="global-functions"></a> 4 5These 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) 7and the [Icinga 2 debug console](11-cli-commands.md#cli-command-console). 8 9You can use the [Icinga 2 debug console](11-cli-commands.md#cli-command-console) 10as a sandbox to test these functions before implementing 11them in your scenarios. 12 13### basename <a id="global-functions-basename"></a> 14 15Signature: 16 17``` 18function basename(path) 19``` 20 21Returns the filename portion of the specified path. 22 23Example: 24 25``` 26$ icinga2 console 27Icinga 2 (version: v2.11.0) 28<1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl" 29null 30<2> => basename(path) 31"xmpp-notification.pl" 32``` 33 34### bool <a id="global-functions-bool"></a> 35 36Signature: 37 38``` 39function bool(value) 40``` 41 42Converts the value to a bool. 43 44Example: 45 46``` 47$ icinga2 console 48Icinga 2 (version: v2.11.0) 49<1> => bool(1) 50true 51<2> => bool(0) 52false 53``` 54 55### cidr_match <a id="global-functions-cidr_match"></a> 56 57Signature: 58 59``` 60function cidr_match(pattern, ip, mode) 61``` 62 63Returns true if the CIDR pattern matches the IP address, false otherwise. 64 65IPv4 addresses are converted to IPv4-mapped IPv6 addresses before being 66matched against the pattern. The `mode` argument is optional and can be 67either `MatchAll` (in which case all elements for an array have to match) or `MatchAny` 68(in which case at least one element has to match). The default mode is `MatchAll`. 69 70Example for a single IP address: 71 72``` 73$ icinga2 console 74Icinga 2 (version: v2.11.0) 75<1> => host.address = "192.168.56.101" 76null 77<2> => cidr_match("192.168.56.0/24", host.address) 78true 79<3> => cidr_match("192.168.56.0/26", host.address) 80false 81``` 82 83Example for an array of IP addresses: 84 85``` 86$ icinga2 console 87Icinga 2 (version: v2.11.0) 88<1> => host.vars.vhost_ips = [ "192.168.56.101", "192.168.56.102", "10.0.10.99" ] 89null 90<2> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAll) 91false 92<3> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAny) 93true 94``` 95 96### dirname <a id="global-functions-dirname"></a> 97 98Signature: 99 100``` 101function dirname(path) 102``` 103 104Returns the directory portion of the specified path. 105 106Example: 107 108``` 109$ icinga2 console 110Icinga 2 (version: v2.11.0) 111<1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl" 112null 113<2> => dirname(path) 114"/etc/icinga2/scripts" 115``` 116 117### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a> 118 119Signature: 120 121``` 122function escape_create_process_arg(text) 123``` 124 125Escapes a string for use as an argument for CreateProcess(). Windows only. 126 127### escape_shell_arg <a id="global-functions-escape_shell_arg"></a> 128 129Signature: 130 131``` 132function escape_shell_arg(text) 133``` 134 135Escapes a string for use as a single shell argument. 136 137Example: 138 139``` 140$ icinga2 console 141Icinga 2 (version: v2.11.0) 142<1> => escape_shell_arg("'$host.name$' '$service.name$'") 143"''\\''$host.name$'\\'' '\\''$service.name$'\\'''" 144``` 145 146### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a> 147 148Signature: 149 150``` 151function escape_shell_cmd(text) 152``` 153 154Escapes shell meta characters in a string. 155 156Example: 157 158``` 159$ icinga2 console 160Icinga 2 (version: v2.11.0) 161<1> => escape_shell_cmd("/bin/echo 'shell test' $ENV") 162"/bin/echo 'shell test' \\$ENV" 163``` 164 165### get_time <a id="global-functions-get_time"></a> 166 167Signature: 168 169``` 170function get_time() 171``` 172 173Returns the current UNIX timestamp as floating point number. 174 175Example: 176 177``` 178$ icinga2 console 179Icinga 2 (version: v2.11.0) 180<1> => get_time() 1811480072135.633008 182<2> => get_time() 1831480072140.401207 184``` 185 186### getenv <a id="global-functions-getenv"></a> 187 188Signature: 189 190``` 191function getenv(key) 192``` 193 194Returns the value from the specified environment variable key. 195 196Example: 197 198``` 199$ MY_ENV_VAR=icinga2 icinga2 console 200Icinga 2 (version: v2.11.0) 201Type $help to view available commands. 202<1> => getenv("MY_ENV_VAR") 203"icinga2" 204``` 205 206### glob <a id="global-functions-glob"></a> 207 208Signature: 209 210``` 211function glob(pathSpec, type) 212``` 213 214Returns an array containing all paths which match the 215`pathSpec` argument. 216 217The `type` argument is optional and specifies which types 218of paths are matched. This can be a combination of the `GlobFile` 219and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`. 220 221``` 222$ icinga2 console 223Icinga 2 (version: v2.11.0) 224<1> => var pathSpec = "/etc/icinga2/conf.d/*.conf" 225null 226<2> => glob(pathSpec) 227[ "/etc/icinga2/conf.d/app.conf", "/etc/icinga2/conf.d/commands.conf", ... ] 228``` 229 230### glob\_recursive <a id="global-functions-glob-recursive"></a> 231 232Signature: 233 234``` 235function glob_recursive(path, pattern, type) 236``` 237 238Recursively descends into the specified directory and returns an array containing 239all paths which match the `pattern` argument. 240 241The `type` argument is optional and specifies which types 242of paths are matched. This can be a combination of the `GlobFile` 243and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`. 244 245``` 246$ icinga2 console 247Icinga 2 (version: v2.11.0) 248<1> => var path = "/etc/icinga2/zones.d/" 249null 250<2> => var pattern = "*.conf" 251null 252<3> => glob_recursive(path, pattern) 253[ "/etc/icinga2/zones.d/global-templates/templates.conf", "/etc/icinga2/zones.d/master/hosts.conf", ... ] 254``` 255 256### intersection <a id="global-functions-intersection"></a> 257 258Signature: 259 260``` 261function intersection(array, array, ...) 262``` 263 264Returns an array containing all unique elements which are common to all 265specified arrays. 266 267Example: 268 269``` 270$ icinga2 console 271Icinga 2 (version: v2.11.0) 272<1> => var dev_notification_groups = [ "devs", "slack" ] 273null 274<2> => var host_notification_groups = [ "slack", "noc" ] 275null 276<3> => intersection(dev_notification_groups, host_notification_groups) 277[ "slack" ] 278``` 279 280### keys <a id="global-functions-keys"></a> 281 282Signature: 283 284``` 285function keys(dict) 286``` 287 288Returns an array containing the dictionary's keys. 289 290**Note**: Instead of using this global function you are advised to use the type's 291prototype method: [Dictionary#keys](18-library-reference.md#dictionary-keys). 292 293Example: 294 295``` 296$ icinga2 console 297Icinga 2 (version: v2.11.0) 298<1> => host.vars.disks["/"] = {} 299null 300<2> => host.vars.disks["/var"] = {} 301null 302<3> => host.vars.disks.keys() 303[ "/", "/var" ] 304``` 305 306### len <a id="global-functions-len"></a> 307 308Signature: 309 310``` 311function len(value) 312``` 313 314Returns the length of the value, i.e. the number of elements for an array 315or dictionary, or the length of the string in bytes. 316 317**Note**: Instead of using this global function you are advised to use the type's 318prototype method: [Array#len](18-library-reference.md#array-len), [Dictionary#len](18-library-reference.md#dictionary-len) and 319[String#len](18-library-reference.md#string-len). 320 321Example: 322 323``` 324$ icinga2 console 325Icinga 2 (version: v2.11.0) 326<1> => host.groups = [ "linux-servers", "db-servers" ] 327null 328<2> => host.groups.len() 3292.000000 330<3> => host.vars.disks["/"] = {} 331null 332<4> => host.vars.disks["/var"] = {} 333null 334<5> => host.vars.disks.len() 3352.000000 336<6> => host.vars.os_type = "Linux/Unix" 337null 338<7> => host.vars.os_type.len() 33910.000000 340``` 341 342### log <a id="global-functions-log"></a> 343 344Signature: 345 346``` 347function log(value) 348``` 349 350Writes a message to the log. Non-string values are converted to a JSON string. 351 352Signature: 353 354``` 355function log(severity, facility, value) 356``` 357 358Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`, 359`LogInformation`, `LogWarning`, and `LogCritical`. 360 361Non-string values are converted to a JSON string. 362 363Example: 364 365``` 366$ icinga2 console 367Icinga 2 (version: v2.11.0) 368<1> => log(LogCritical, "Console", "First line") 369critical/Console: First line 370null 371<2> => var groups = [ "devs", "slack" ] 372null 373<3> => log(LogCritical, "Console", groups) 374critical/Console: ["devs","slack"] 375null 376``` 377 378### match <a id="global-functions-match"></a> 379 380Signature: 381 382``` 383function match(pattern, value, mode) 384``` 385 386Returns true if the wildcard (`?*`) `pattern` matches the `value`, false otherwise. 387The `value` can be of the type [String](18-library-reference.md#string-type) or [Array](18-library-reference.md#array-type) (which 388contains string elements). 389 390The `mode` argument is optional and can be either `MatchAll` (in which case all elements 391for an array have to match) or `MatchAny` (in which case at least one element has to match). 392The default mode is `MatchAll`. 393 394Example for string values: 395 396``` 397$ icinga2 console 398Icinga 2 (version: v2.11.0) 399<1> => var name = "db-prod-sfo-657" 400null 401<2> => match("*prod-sfo*", name) 402true 403<3> => match("*-dev-*", name) 404false 405``` 406 407Example for an array of string values: 408 409``` 410$ icinga2 console 411Icinga 2 (version: v2.11.0-28) 412<1> => host.vars.application_types = [ "web-wp", "web-rt", "db-local" ] 413null 414<2> => match("web-*", host.vars.application_types, MatchAll) 415false 416<3> => match("web-*", host.vars.application_types, MatchAny) 417true 418``` 419 420### number <a id="global-functions-number"></a> 421 422Signature: 423 424``` 425function number(value) 426``` 427 428Converts the value to a number. 429 430Example: 431 432``` 433$ icinga2 console 434Icinga 2 (version: v2.11.0) 435<1> => number(false) 4360.000000 437<2> => number("78") 43878.000000 439``` 440 441### parse_performance_data <a id="global-functions-parse_performance_data"></a> 442 443Signature: 444 445``` 446function parse_performance_data(pd) 447``` 448 449Parses a performance data string and returns an array describing the values. 450 451Example: 452 453``` 454$ icinga2 console 455Icinga 2 (version: v2.11.0) 456<1> => var pd = "'time'=1480074205.197363;;;" 457null 458<2> => parse_performance_data(pd) 459{ 460 counter = false 461 crit = null 462 label = "time" 463 max = null 464 min = null 465 type = "PerfdataValue" 466 unit = "" 467 value = 1480074205.197363 468 warn = null 469} 470``` 471 472### path\_exists <a id="global-functions-path-exists"></a> 473 474Signature: 475 476``` 477function path_exists(path) 478``` 479 480Returns true if the specified path exists, false otherwise. 481 482Example: 483 484``` 485$ icinga2 console 486Icinga 2 (version: v2.11.0) 487<1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl" 488null 489<2> => path_exists(path) 490true 491``` 492 493### random <a id="global-functions-random"></a> 494 495Signature: 496 497``` 498function random() 499``` 500 501Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h). 502 503``` 504$ icinga2 console 505Icinga 2 (version: v2.11.0) 506<1> => random() 5071263171996.000000 508<2> => random() 509108402530.000000 510``` 511 512### range <a id="global-functions-range"></a> 513 514Signature: 515 516``` 517function range(end) 518function range(start, end) 519function range(start, end, increment) 520``` 521 522Returns an array of numbers in the specified range. 523If you specify one parameter, the first element starts at `0`. 524The following array numbers are incremented by `1` and stop before 525the specified end. 526If you specify the start and end numbers, the returned array 527number are incremented by `1`. They start at the specified start 528number and stop before the end number. 529Optionally you can specify the incremented step between numbers 530as third parameter. 531 532Example: 533 534``` 535$ icinga2 console 536Icinga 2 (version: v2.11.0) 537<1> => range(5) 538[ 0.000000, 1.000000, 2.000000, 3.000000, 4.000000 ] 539<2> => range(2,4) 540[ 2.000000, 3.000000 ] 541<3> => range(2,10,2) 542[ 2.000000, 4.000000, 6.000000, 8.000000 ] 543``` 544 545### regex <a id="global-functions-regex"></a> 546 547Signature: 548 549``` 550function regex(pattern, value, mode) 551``` 552 553Returns true if the regular expression `pattern` matches the `value`, false otherwise. 554The `value` can be of the type [String](18-library-reference.md#string-type) or [Array](18-library-reference.md#array-type) (which 555contains string elements). 556 557The `mode` argument is optional and can be either `MatchAll` (in which case all elements 558for an array have to match) or `MatchAny` (in which case at least one element has to match). 559The default mode is `MatchAll`. 560 561**Tip**: In case you are looking for regular expression tests try [regex101](https://regex101.com). 562 563Example for string values: 564 565``` 566$ icinga2 console 567Icinga 2 (version: v2.11.0) 568<1> => host.vars.os_type = "Linux/Unix" 569null 570<2> => regex("^Linux", host.vars.os_type) 571true 572<3> => regex("^Linux$", host.vars.os_type) 573false 574``` 575 576Example for an array of string values: 577 578``` 579$ icinga2 console 580Icinga 2 (version: v2.11.0) 581<1> => host.vars.databases = [ "db-prod1", "db-prod2", "db-dev" ] 582null 583<2> => regex("^db-prod\\d+", host.vars.databases, MatchAny) 584true 585<3> => regex("^db-prod\\d+", host.vars.databases, MatchAll) 586false 587``` 588 589### sleep <a id="global-functions-sleep"></a> 590 591Signature: 592 593``` 594function sleep(interval) 595``` 596 597Sleeps for the specified amount of time (in seconds). 598 599### string <a id="global-functions-string"></a> 600 601Signature: 602 603``` 604function string(value) 605``` 606 607Converts the value to a string. 608 609**Note**: Instead of using this global function you are advised to use the type's 610prototype method: 611 612* [Number#to_string](18-library-reference.md#number-to_string) 613* [Boolean#to_string](18-library-reference.md#boolean-to_string) 614* [String#to_string](18-library-reference.md#string-to_string) 615* [Object#to_string](18-library-reference.md#object-to-string) for Array and Dictionary types 616* [DateTime#to_string](18-library-reference.md#datetime-tostring) 617 618Example: 619 620``` 621$ icinga2 console 622Icinga 2 (version: v2.11.0) 623<1> => 5.to_string() 624"5" 625<2> => false.to_string() 626"false" 627<3> => "abc".to_string() 628"abc" 629<4> => [ "dev", "slack" ].to_string() 630"[ \"dev\", \"slack\" ]" 631<5> => { "/" = {}, "/var" = {} }.to_string() 632"{\n\t\"/\" = {\n\t}\n\t\"/var\" = {\n\t}\n}" 633<6> => DateTime(2016, 11, 25).to_string() 634"2016-11-25 00:00:00 +0100" 635``` 636 637### typeof <a id="global-functions-typeof"></a> 638 639Signature: 640 641``` 642function typeof(value) 643``` 644 645Returns the [Type](18-library-reference.md#type-type) object for a value. 646 647Example: 648 649``` 650$ icinga2 console 651Icinga 2 (version: v2.11.0) 652<1> => typeof(3) == Number 653true 654<2> => typeof("str") == String 655true 656<3> => typeof(true) == Boolean 657true 658<4> => typeof([ 1, 2, 3]) == Array 659true 660<5> => typeof({ a = 2, b = 3 }) == Dictionary 661true 662``` 663 664### union <a id="global-functions-union"></a> 665 666Signature: 667 668``` 669function union(array, array, ...) 670``` 671 672Returns an array containing all unique elements from the specified arrays. 673 674Example: 675``` 676$ icinga2 console 677Icinga 2 (version: v2.11.0) 678<1> => var dev_notification_groups = [ "devs", "slack" ] 679null 680<2> => var host_notification_groups = [ "slack", "noc" ] 681null 682<3> => union(dev_notification_groups, host_notification_groups) 683[ "devs", "noc", "slack" ] 684``` 685 686## Scoped Functions <a id="scoped-functions"></a> 687 688This chapter describes functions which are only available 689in a specific scope. 690 691### macro <a id="scoped-functions-macro"></a> 692 693Signature: 694 695``` 696function macro("$macro_name$") 697``` 698 699The `macro` function can be used to resolve [runtime macro](03-monitoring-basics.md#runtime-macros) 700strings into their values. 701The returned value depends on the attribute value which is resolved 702from the specified runtime macro. 703 704This function is only available in runtime evaluated functions, e.g. 705for [custom variables](03-monitoring-basics.md#custom-variables-functions) which 706use the [abbreviated lambda syntax](17-language-reference.md#nullary-lambdas). 707 708This example sets the `snmp_address` custom variable 709based on `$address$` and `$address6$`. 710 711``` 712 vars.snmp_address = {{ 713 var addr_v4 = macro("$address$") 714 var addr_v6 = macro("$address6$") 715 716 if (addr_v4) { 717 return addr_v4 718 } else { 719 return "udp6:[" + addr_v6 + "]" 720 } 721 }} 722``` 723 724More reference examples are available inside the [Icinga Template Library](10-icinga-template-library.md#icinga-template-library) 725and the [object accessors chapter](08-advanced-topics.md#access-object-attributes-at-runtime). 726 727## Object Accessor Functions <a id="object-accessor-functions"></a> 728 729These functions can be used to retrieve a reference to another object by name. 730 731### get_check_command <a id="objref-get_check_command"></a> 732 733Signature: 734 735``` 736function get_check_command(name); 737``` 738 739Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists. 740 741### get_event_command <a id="objref-get_event_command"></a> 742 743Signature: 744 745``` 746function get_event_command(name); 747``` 748 749Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists. 750 751### get_host <a id="objref-get_host"></a> 752 753Signature: 754 755``` 756function get_host(host_name); 757``` 758 759Returns the Host object with the specified name, or `null` if no such Host object exists. 760 761### get_host_group <a id="objref-get_host_group"></a> 762 763Signature: 764 765``` 766function get_host_group(name); 767``` 768 769Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists. 770 771### get_notification_command <a id="objref-get_notification_command"></a> 772 773Signature: 774 775``` 776function get_notification_command(name); 777``` 778 779Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists. 780 781### get_object <a id="objref-get_object"></a> 782 783Signature: 784 785``` 786function get_object(type, name); 787``` 788 789Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer 790to a type object. 791 792### get_objects <a id="objref-get_objects"></a> 793 794Signature: 795 796``` 797function get_objects(type); 798``` 799 800Returns an array of objects whose type matches the specified type. `type` must refer 801to a type object. 802 803### get_service <a id="objref-get_service"></a> 804 805Signature: 806 807``` 808function get_service(host_name, service_name); 809function get_service(host, service_name); 810``` 811 812Returns the Service object with the specified host name or object and service name pair, 813or `null` if no such Service object exists. 814 815Example in the [debug console](11-cli-commands.md#cli-command-console) 816which fetches the `disk` service object from the current Icinga 2 node: 817 818``` 819$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' 820Icinga 2 (version: v2.11.0) 821 822<1> => get_service(NodeName, "disk") 823<2> => get_service(NodeName, "disk").__name 824"icinga2-master1.localdomain!disk" 825 826<3> => get_service(get_host(NodeName), "disk").__name 827"icinga2-master1.localdomain!disk" 828``` 829 830### get_service_group <a id="objref-get_service_group"></a> 831 832Signature: 833 834``` 835function get_service_group(name); 836``` 837 838Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists. 839 840### get_services <a id="objref-get_services"></a> 841 842Signature: 843 844``` 845function get_services(host_name); 846function get_services(host); 847``` 848 849Returns an [array](17-language-reference.md#array) of service objects for the specified host name or object, 850or `null` if no such host object exists. 851 852Example in the [debug console](11-cli-commands.md#cli-command-console) 853which fetches all service objects from the current Icinga 2 node: 854 855``` 856$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' 857Icinga 2 (version: v2.11.0) 858 859<1> => get_services(NodeName).map(s => s.name) 860[ "disk", "disk /", "http", "icinga", "load", "ping4", "ping6", "procs", "ssh", "users" ] 861``` 862 863Note: [map](18-library-reference.md#array-map) takes a [lambda function](17-language-reference.md#lambdas) as argument. In this example 864we only want to collect and print the `name` attribute with `s => s.name`. 865 866This works in a similar fashion for a host object where you can extract all service states 867in using the [map](18-library-reference.md#array-map) functionality: 868 869``` 870<2> => get_services(get_host(NodeName)).map(s => s.state) 871[ 2.000000, 2.000000, 2.000000, 0.000000, 0.000000, 0.000000, 2.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000 ] 872``` 873 874### get_template <a id="objref-get_template"></a> 875 876Signature: 877 878``` 879function get_template(type, name); 880``` 881 882Returns the template with the specified type and name, or `null` if no such object exists. `type` must refer 883to a type object. 884 885> **Note** 886> 887> Only the name and debug info attributes are available for templates accessed in the DSL. 888> Object attributes are not available in this scope. 889 890You can use this functionality to check whether a template exists e.g. on a satellite endpoint 891and if not, import a different template. 892 893``` 894object Host "icinga-agent47.localdomain" { 895 if (get_template(Host, "master-host-tmpl")) { 896 import "master-host-tmpl" 897 } else { 898 import "generic-host" 899 } 900} 901``` 902 903### get_templates <a id="objref-get_templates"></a> 904 905Signature: 906 907``` 908function get_templates(type); 909``` 910 911Returns an array of templates whose type matches the specified type. `type` must refer 912to a type object. 913 914> **Note** 915> 916> Only the name and debug info attributes are available for templates accessed in the DSL. 917> Object attributes are not available in this scope. 918 919You can use this function to iterate over all available template names, similar to what 920the [templates API URL endpoint](12-icinga2-api.md#icinga2-api-config-templates) provides. 921 922``` 923<1> => get_templates(Host).map(n => n.name) 924[ "ssh-agent" ] 925``` 926 927### get_time_period <a id="objref-get_time_period"></a> 928 929Signature: 930 931``` 932function get_time_period(name); 933``` 934 935Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists. 936 937### get_user <a id="objref-get_user"></a> 938 939Signature: 940 941``` 942function get_user(name); 943``` 944 945Returns the User object with the specified name, or `null` if no such User object exists. 946 947### get_user_group <a id="objref-get_user_group"></a> 948 949Signature: 950 951``` 952function get_user_group(name); 953``` 954 955Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists. 956 957## Json object <a id="json-object"></a> 958 959The global `Json` object can be used to encode and decode JSON. 960 961### Json.decode <a id="json-decode"></a> 962 963Signature: 964 965``` 966function decode(x); 967``` 968 969Decodes a JSON string. 970 971### Json.encode <a id="json-encode"></a> 972 973Signature: 974 975``` 976function encode(x); 977``` 978 979Encodes an arbitrary value into JSON. 980 981## Math object <a id="math-object"></a> 982 983The global `Math` object can be used to access a number of mathematical constants 984and functions. 985 986### Math.E <a id="math-e"></a> 987 988Euler's constant. 989 990### Math.LN2 <a id="math-ln2"></a> 991 992Natural logarithm of 2. 993 994### Math.LN10 <a id="math-ln10"></a> 995 996Natural logarithm of 10. 997 998### Math.LOG2E <a id="math-log2e"></a> 999 1000Base 2 logarithm of E. 1001 1002### Math.PI <a id="math-pi"></a> 1003 1004The mathematical constant Pi. 1005 1006### Math.SQRT1_2 <a id="math-sqrt1_2"></a> 1007 1008Square root of 1/2. 1009 1010### Math.SQRT2 <a id="math-sqrt2"></a> 1011 1012Square root of 2. 1013 1014### Math.abs <a id="math-abs"></a> 1015 1016Signature: 1017 1018``` 1019function abs(x); 1020``` 1021 1022Returns the absolute value of `x`. 1023 1024### Math.acos <a id="math-acos"></a> 1025 1026Signature: 1027 1028``` 1029function acos(x); 1030``` 1031 1032Returns the arccosine of `x`. 1033 1034### Math.asin <a id="math-asin"></a> 1035 1036Signature: 1037 1038``` 1039function asin(x); 1040``` 1041 1042Returns the arcsine of `x`. 1043 1044### Math.atan <a id="math-atan"></a> 1045 1046Signature: 1047 1048``` 1049function atan(x); 1050``` 1051 1052Returns the arctangent of `x`. 1053 1054### Math.atan2 <a id="math-atan2"></a> 1055 1056Signature: 1057 1058``` 1059function atan2(y, x); 1060``` 1061Returns the arctangent of the quotient of `y` and `x`. 1062 1063### Math.ceil <a id="math-ceil"></a> 1064 1065Signature: 1066 1067``` 1068function ceil(x); 1069``` 1070 1071Returns the smallest integer value not less than `x`. 1072 1073### Math.cos <a id="math-cos"></a> 1074 1075Signature: 1076 1077``` 1078function cos(x); 1079``` 1080 1081Returns the cosine of `x`. 1082 1083### Math.exp <a id="math-exp"></a> 1084 1085Signature: 1086 1087``` 1088function exp(x); 1089``` 1090 1091Returns E raised to the `x`th power. 1092 1093### Math.floor <a id="math-floor"></a> 1094 1095Signature: 1096 1097``` 1098function floor(x); 1099``` 1100 1101Returns the largest integer value not greater than `x`. 1102 1103### Math.isinf <a id="math-isinf"></a> 1104 1105Signature: 1106 1107``` 1108function isinf(x); 1109``` 1110 1111Returns whether `x` is infinite. 1112 1113### Math.isnan <a id="math-isnan"></a> 1114 1115Signature: 1116 1117``` 1118function isnan(x); 1119``` 1120 1121Returns whether `x` is NaN (not-a-number). 1122 1123### Math.log <a id="math-log"></a> 1124 1125Signature: 1126 1127``` 1128function log(x); 1129``` 1130 1131Returns the natural logarithm of `x`. 1132 1133### Math.max <a id="math-max"></a> 1134 1135Signature: 1136 1137``` 1138function max(...); 1139``` 1140 1141Returns the largest argument. A variable number of arguments can be specified. 1142If no arguments are given, -Infinity is returned. 1143 1144### Math.min <a id="math-min"></a> 1145 1146Signature: 1147 1148``` 1149function min(...); 1150``` 1151 1152Returns the smallest argument. A variable number of arguments can be specified. 1153If no arguments are given, +Infinity is returned. 1154 1155### Math.pow <a id="math-pow"></a> 1156 1157Signature: 1158 1159``` 1160function pow(x, y); 1161``` 1162 1163Returns `x` raised to the `y`th power. 1164 1165### Math.random <a id="math-random"></a> 1166 1167Signature: 1168 1169``` 1170function random(); 1171``` 1172 1173Returns a pseudo-random number between 0 and 1. 1174 1175### Math.round <a id="math-round"></a> 1176 1177Signature: 1178 1179``` 1180function round(x); 1181``` 1182 1183Returns `x` rounded to the nearest integer value. 1184 1185### Math.sign <a id="math-sign"></a> 1186 1187Signature: 1188 1189``` 1190function sign(x); 1191``` 1192 1193Returns -1 if `x` is negative, 1 if `x` is positive 1194and 0 if `x` is 0. 1195 1196### Math.sin <a id="math-sin"></a> 1197 1198Signature: 1199 1200``` 1201function sin(x); 1202``` 1203 1204Returns the sine of `x`. 1205 1206### Math.sqrt <a id="math-sqrt"></a> 1207 1208Signature: 1209 1210``` 1211function sqrt(x); 1212``` 1213 1214Returns the square root of `x`. 1215 1216### Math.tan <a id="math-tan"></a> 1217 1218Signature: 1219 1220``` 1221function tan(x); 1222``` 1223 1224Returns the tangent of `x`. 1225 1226## Array type <a id="array-type"></a> 1227 1228Inherits methods from the [Object type](18-library-reference.md#object-type). 1229 1230### Array#add <a id="array-add"></a> 1231 1232Signature: 1233 1234``` 1235function add(value); 1236``` 1237 1238Adds a new value after the last element in the array. 1239 1240### Array#all <a id="array-all"></a> 1241 1242Signature: 1243 1244``` 1245function all(func); 1246``` 1247 1248Returns true if the array contains only elements for which `func(element)` 1249is true, false otherwise. 1250 1251### Array#any <a id="array-any"></a> 1252 1253Signature: 1254 1255``` 1256function any(func); 1257``` 1258 1259Returns true if the array contains at least one element for which `func(element)` 1260is true, false otherwise. 1261 1262### Array#clear <a id="array-clear"></a> 1263 1264Signature: 1265 1266``` 1267function clear(); 1268``` 1269 1270Removes all elements from the array. 1271 1272### Array#contains <a id="array-contains"></a> 1273 1274Signature: 1275 1276``` 1277function contains(value); 1278``` 1279 1280Returns true if the array contains the specified value, false otherwise. 1281 1282### Array#filter <a id="array-filter"></a> 1283 1284Signature: 1285 1286``` 1287function filter(func); 1288``` 1289 1290Returns a copy of the array containing only the elements for which `func(element)` 1291is true. 1292 1293### Array#freeze <a id="array-freeze"></a> 1294 1295Signature: 1296 1297``` 1298function freeze() 1299``` 1300 1301Disallows further modifications to this array. Trying to modify the array will result in an exception. 1302 1303### Array#get <a id="array-get"></a> 1304 1305Signature: 1306 1307``` 1308function get(index); 1309``` 1310 1311Retrieves the element at the specified zero-based index. 1312 1313### Array#join <a id="array-join"></a> 1314 1315Signature: 1316 1317``` 1318function join(separator); 1319``` 1320 1321Joins all elements of the array using the specified separator. 1322 1323### Array#len <a id="array-len"></a> 1324 1325Signature: 1326 1327``` 1328function len(); 1329``` 1330 1331Returns the number of elements contained in the array. 1332 1333### Array#map <a id="array-map"></a> 1334 1335Signature: 1336 1337``` 1338function map(func); 1339``` 1340 1341Calls `func(element)` for each of the elements in the array and returns 1342a new array containing the return values of these function calls. 1343 1344### Array#reduce <a id="array-reduce"></a> 1345 1346Signature: 1347 1348``` 1349function reduce(func); 1350``` 1351 1352Reduces the elements of the array into a single value by calling the provided 1353function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array 1354or results from previous function calls. 1355 1356### Array#remove <a id="array-remove"></a> 1357 1358Signature: 1359 1360``` 1361function remove(index); 1362``` 1363 1364Removes the element at the specified zero-based index. 1365 1366### Array#reverse <a id="array-reverse"></a> 1367 1368Signature: 1369 1370``` 1371function reverse(); 1372``` 1373 1374Returns a new array with all elements of the current array in reverse order. 1375 1376### Array#set <a id="array-set"></a> 1377 1378Signature: 1379 1380``` 1381function set(index, value); 1382``` 1383 1384Sets the element at the zero-based index to the specified value. The `index` must refer to an element 1385which already exists in the array. 1386 1387### Array#shallow_clone <a id="array-shallow-clone"></a> 1388 1389``` 1390function shallow_clone(); 1391``` 1392 1393Returns a copy of the array. Note that for elements which are reference values (e.g. objects such 1394as arrays and dictionaries) only the references are copied. 1395 1396### Array#sort <a id="array-sort"></a> 1397 1398Signature: 1399 1400``` 1401function sort(less_cmp); 1402``` 1403 1404Returns a copy of the array where all items are sorted. The items are 1405compared using the `<` (less-than) operator. A custom comparator function 1406can be specified with the `less_cmp` argument. 1407 1408### Array#unique <a id="array-unique"></a> 1409 1410Signature: 1411 1412``` 1413function unique(); 1414``` 1415 1416Returns a copy of the array with all duplicate elements removed. The original order 1417of the array is not preserved. 1418 1419## Boolean type <a id="boolean-type"></a> 1420 1421### Boolean#to_string <a id="boolean-to_string"></a> 1422 1423Signature: 1424 1425``` 1426function to_string(); 1427``` 1428 1429The `to_string` method returns a string representation of the boolean value. 1430 1431Example: 1432 1433``` 1434var example = true 1435 example.to_string() /* Returns "true" */ 1436``` 1437 1438## DateTime type <a id="datetime-type"></a> 1439 1440Inherits methods from the [Object type](18-library-reference.md#object-type). 1441 1442### DateTime constructor <a id="datetime-ctor"></a> 1443 1444Signature: 1445 1446``` 1447function DateTime() 1448function DateTime(unixTimestamp) 1449function DateTime(year, month, day) 1450function DateTime(year, month, day, hours, minutes, seconds) 1451``` 1452 1453Constructs a new DateTime object. When no arguments are specified for the constructor a new 1454DateTime object representing the current time is created. 1455 1456Example: 1457 1458``` 1459var d1 = DateTime() /* current time */ 1460var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */ 1461``` 1462 1463### DateTime arithmetic <a id="datetime-arithmetic"></a> 1464 1465Subtracting two DateTime objects yields the interval between them, in seconds. 1466 1467Example: 1468 1469``` 1470var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */ 1471``` 1472 1473Subtracting a number from a DateTime object yields a new DateTime object that is further in the past: 1474 1475Example: 1476 1477``` 1478var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */ 1479``` 1480 1481Adding a number to a DateTime object yields a new DateTime object that is in the future: 1482 1483Example: 1484 1485``` 1486var dt = DateTime() + 24 * 60 * 60 /* Current time plus 24 hours */ 1487``` 1488 1489### DateTime#format <a id="datetime-format"></a> 1490 1491Signature: 1492 1493``` 1494function format(fmt) 1495``` 1496 1497Returns a string representation for the DateTime object using the specified format string. 1498The format string may contain format conversion placeholders as specified in strftime(3). 1499 1500Example: 1501 1502``` 1503var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */ 1504``` 1505 1506### DateTime#to_string <a id="datetime-tostring"></a> 1507 1508Signature: 1509 1510``` 1511function to_string() 1512``` 1513 1514Returns a string representation for the DateTime object. Uses a suitable default format. 1515 1516Example: 1517 1518``` 1519var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */ 1520``` 1521 1522## Dictionary type <a id="dictionary-type"></a> 1523 1524Inherits methods from the [Object type](18-library-reference.md#object-type). 1525 1526### Dictionary#clear <a id="dictionary-clear"></a> 1527 1528Signature: 1529 1530``` 1531function clear(); 1532``` 1533 1534Removes all items from the dictionary. 1535 1536### Dictionary#contains <a id="dictionary-contains"></a> 1537 1538Signature: 1539 1540``` 1541function contains(key); 1542``` 1543 1544Returns true if a dictionary item with the specified `key` exists, false otherwise. 1545 1546### Dictionary#freeze <a id="dictionary-freeze"></a> 1547 1548Signature: 1549 1550``` 1551function freeze() 1552``` 1553 1554Disallows further modifications to this dictionary. Trying to modify the dictionary will result in an exception. 1555 1556### Dictionary#get <a id="dictionary-get"></a> 1557 1558Signature: 1559 1560``` 1561function get(key); 1562``` 1563 1564Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist 1565in the dictionary. 1566 1567### Dictionary#keys <a id="dictionary-keys"></a> 1568 1569Signature: 1570 1571``` 1572function keys(); 1573``` 1574 1575Returns a list of keys for all items that are currently in the dictionary. 1576 1577### Dictionary#len <a id="dictionary-len"></a> 1578 1579Signature: 1580 1581``` 1582function len(); 1583``` 1584 1585Returns the number of items contained in the dictionary. 1586 1587### Dictionary#remove <a id="dictionary-remove"></a> 1588 1589Signature: 1590 1591``` 1592function remove(key); 1593``` 1594 1595Removes the item with the specified `key`. Trying to remove an item which does not exist 1596is a no-op. 1597 1598### Dictionary#set <a id="dictionary-set"></a> 1599 1600Signature: 1601 1602``` 1603function set(key, value); 1604``` 1605 1606Creates or updates an item with the specified `key` and `value`. 1607 1608### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a> 1609 1610Signature: 1611 1612``` 1613function shallow_clone(); 1614``` 1615 1616Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such 1617as arrays and dictionaries) only the references are copied. 1618 1619### Dictionary#values <a id="dictionary-values"></a> 1620 1621Signature: 1622 1623``` 1624function values(); 1625``` 1626 1627Returns a list of values for all items that are currently in the dictionary. 1628 1629## Function type <a id="scriptfunction-type"></a> 1630 1631Inherits methods from the [Object type](18-library-reference.md#object-type). 1632 1633### Function#call <a id="scriptfunction-call"></a> 1634 1635Signature: 1636 1637``` 1638function call(thisArg, ...); 1639``` 1640 1641Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this` 1642scope for the function. All other arguments are passed directly to the function. 1643 1644Example: 1645 1646``` 1647function set_x(val) { 1648 this.x = val 1649} 1650 1651dict = {} 1652 1653set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */ 1654``` 1655 1656### Function#callv <a id="scriptfunction-callv"></a> 1657 1658Signature: 1659 1660``` 1661function callv(thisArg, args); 1662``` 1663 1664Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this` 1665scope for the function. The items in the `args` array are passed to the function as individual arguments. 1666 1667Example: 1668 1669``` 1670function set_x(val) { 1671 this.x = val 1672} 1673 1674var dict = {} 1675 1676var args = [ 7 ] 1677 1678set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */ 1679``` 1680 1681## Number type <a id="number-type"></a> 1682 1683### Number#to_string <a id="number-to_string"></a> 1684 1685Signature: 1686 1687``` 1688function to_string(); 1689``` 1690 1691The `to_string` method returns a string representation of the number. 1692 1693Example: 1694 1695``` 1696var example = 7 1697 example.to_string() /* Returns "7" */ 1698``` 1699 1700## Object type <a id="object-type"></a> 1701 1702This is the base type for all types in the Icinga application. 1703 1704### Object#clone <a id="object-clone"></a> 1705 1706Signature: 1707 1708``` 1709 function clone(); 1710``` 1711 1712Returns a copy of the object. Note that for object elements which are 1713reference values (e.g. objects such as arrays or dictionaries) the entire 1714object is recursively copied. 1715 1716### Object#to_string <a id="object-to-string"></a> 1717 1718Signature: 1719 1720``` 1721function to_string(); 1722``` 1723 1724Returns a string representation for the object. Unless overridden this returns a string 1725of the format "Object of type '<typename>'" where <typename> is the name of the 1726object's type. 1727 1728Example: 1729 1730``` 1731[ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */ 1732``` 1733 1734### Object#type <a id="object-type-field"></a> 1735 1736Signature: 1737 1738String type; 1739 1740Returns the object's type name. This attribute is read-only. 1741 1742Example: 1743 1744``` 1745get_host("localhost").type /* Returns "Host" */ 1746``` 1747 1748## String type <a id="string-type"></a> 1749 1750### String#contains <a id="string-contains"></a> 1751 1752Signature: 1753 1754``` 1755function contains(str); 1756``` 1757 1758Returns `true` if the string `str` was found in the string. If the string 1759was not found, `false` is returned. Use [find](18-library-reference.md#string-find) 1760for getting the index instead. 1761 1762Example: 1763 1764``` 1765"Hello World".contains("World") /* Returns true */ 1766``` 1767 1768### String#find <a id="string-find"></a> 1769 1770Signature: 1771 1772``` 1773function find(str, start); 1774``` 1775 1776Returns the zero-based index at which the string `str` was found in the string. If the string 1777was not found, -1 is returned. `start` specifies the zero-based index at which `find` should 1778start looking for the string (defaults to 0 when not specified). 1779 1780Example: 1781 1782``` 1783"Hello World".find("World") /* Returns 6 */ 1784``` 1785 1786### String#len <a id="string-len"></a> 1787 1788Signature 1789 1790``` 1791function len(); 1792``` 1793 1794Returns the length of the string in bytes. Note that depending on the encoding type of the string 1795this is not necessarily the number of characters. 1796 1797Example: 1798 1799``` 1800"Hello World".len() /* Returns 11 */ 1801``` 1802 1803### String#lower <a id="string-lower"></a> 1804 1805Signature: 1806 1807``` 1808function lower(); 1809``` 1810 1811Returns a copy of the string with all of its characters converted to lower-case. 1812 1813Example: 1814 1815``` 1816"Hello World".lower() /* Returns "hello world" */ 1817``` 1818 1819### String#replace <a id="string-replace"></a> 1820 1821Signature: 1822 1823``` 1824function replace(search, replacement); 1825``` 1826 1827Returns a copy of the string with all occurences of the string specified in `search` replaced 1828with the string specified in `replacement`. 1829 1830### String#reverse <a id="string-reverse"></a> 1831 1832Signature: 1833 1834``` 1835function reverse(); 1836``` 1837 1838Returns a copy of the string in reverse order. 1839 1840### String#split <a id="string-split"></a> 1841 1842Signature: 1843 1844``` 1845function split(delimiters); 1846``` 1847 1848Splits a string into individual parts and returns them as an array. The `delimiters` argument 1849specifies the characters which should be used as delimiters between parts. 1850 1851Example: 1852 1853``` 1854"x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */ 1855``` 1856 1857### String#substr <a id="string-substr"></a> 1858 1859Signature: 1860 1861``` 1862function substr(start, len); 1863``` 1864 1865Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins. 1866The optional `len` argument specifies the length of the part ("until the end of the string" if omitted). 1867 1868Example: 1869 1870``` 1871"Hello World".substr(6) /* Returns "World" */ 1872``` 1873 1874### String#to_string <a id="string-to_string"></a> 1875 1876Signature: 1877 1878``` 1879function to_string(); 1880``` 1881 1882Returns a copy of the string. 1883 1884### String#trim <a id="string-trim"></a> 1885 1886Signature: 1887 1888``` 1889function trim(); 1890``` 1891 1892Removes trailing whitespaces and returns the string. 1893 1894### String#upper <a id="string-upper"></a> 1895 1896Signature: 1897 1898``` 1899function upper(); 1900``` 1901 1902Returns a copy of the string with all of its characters converted to upper-case. 1903 1904Example: 1905 1906``` 1907"Hello World".upper() /* Returns "HELLO WORLD" */ 1908``` 1909 1910## Type type <a id="type-type"></a> 1911 1912Inherits methods from the [Object type](18-library-reference.md#object-type). 1913 1914The `Type` type provides information about the underlying type of an object or scalar value. 1915 1916All 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. 1917 1918### Type#base <a id="type-base"></a> 1919 1920Signature: 1921 1922``` 1923Type base; 1924``` 1925 1926Returns a reference to the type's base type. This attribute is read-only. 1927 1928Example: 1929 1930``` 1931Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */ 1932``` 1933 1934### Type#name <a id="type-name"></a> 1935 1936Signature: 1937 1938``` 1939String name; 1940``` 1941 1942Returns the name of the type. 1943 1944### Type#prototype <a id="type-prototype"></a> 1945 1946Signature: 1947 1948``` 1949Object prototype; 1950``` 1951 1952Returns 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. 1953 1954The prototype functionality is used to implement methods. 1955 1956Example: 1957 1958``` 19593.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */ 1960``` 1961