1 # Library Reference <a id="library-reference"></a>
3 ## Global functions <a id="global-functions"></a>
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).
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.
13 ### regex <a id="global-functions-regex"></a>
17 function regex(pattern, value, mode)
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).
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`.
27 **Tip**: In case you are looking for regular expression tests try [regex101](https://regex101.com).
29 Example for string values:
32 Icinga 2 (version: v2.7.0)
33 <1> => host.vars.os_type = "Linux/Unix"
35 <2> => regex("^Linux", host.vars.os_type)
37 <3> => regex("^Linux$", host.vars.os_type)
40 Example for an array of string values:
43 Icinga 2 (version: v2.7.0)
44 <1> => host.vars.databases = [ "db-prod1", "db-prod2", "db-dev" ]
46 <2> => regex("^db-prod\\d+", host.vars.databases, MatchAny)
48 <3> => regex("^db-prod\\d+", host.vars.databases, MatchAll)
52 ### match <a id="global-functions-match"></a>
56 function match(pattern, text, mode)
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).
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`.
66 Example for string values:
69 Icinga 2 (version: v2.7.0)
70 <1> => var name = "db-prod-sfo-657"
72 <2> => match("*prod-sfo*", name)
74 <3> => match("*-dev-*", name)
77 Example for an array of string values:
80 Icinga 2 (version: v2.7.0-28)
81 <1> => host.vars.application_types = [ "web-wp", "web-rt", "db-local" ]
83 <2> => match("web-*", host.vars.application_types, MatchAll)
85 <3> => match("web-*", host.vars.application_types, MatchAny)
89 ### cidr_match <a id="global-functions-cidr_match"></a>
93 function cidr_match(pattern, ip, mode)
95 Returns true if the CIDR pattern matches the IP address, false otherwise.
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`.
103 Example for a single IP address:
106 Icinga 2 (version: v2.7.0)
107 <1> => host.address = "192.168.56.101"
109 <2> => cidr_match("192.168.56.0/24", host.address)
111 <3> => cidr_match("192.168.56.0/26", host.address)
114 Example for an array of IP addresses:
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" ]
120 <2> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAll)
122 <3> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAny)
125 ### range <a id="global-functions-range"></a>
130 function range(start, end)
131 function range(start, end, increment)
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
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
146 Icinga 2 (version: v2.7.0)
148 [ 0.000000, 1.000000, 2.000000, 3.000000, 4.000000 ]
150 [ 2.000000, 3.000000 ]
152 [ 2.000000, 4.000000, 6.000000, 8.000000 ]
154 ### len <a id="global-functions-len"></a>
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.
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).
170 Icinga 2 (version: v2.7.0)
171 <1> => host.groups = [ "linux-servers", "db-servers" ]
173 <2> => host.groups.len()
175 <3> => host.vars.disks["/"] = {}
177 <4> => host.vars.disks["/var"] = {}
179 <5> => host.vars.disks.len()
181 <6> => host.vars.os_type = "Linux/Unix"
183 <7> => host.vars.os_type.len()
187 ### union <a id="global-functions-union"></a>
191 function union(array, array, ...)
193 Returns an array containing all unique elements from the specified arrays.
198 Icinga 2 (version: v2.7.0)
199 <1> => var dev_notification_groups = [ "devs", "slack" ]
201 <2> => var host_notification_groups = [ "slack", "noc" ]
203 <3> => union(dev_notification_groups, host_notification_groups)
204 [ "devs", "noc", "slack" ]
206 ### intersection <a id="global-functions-intersection"></a>
210 function intersection(array, array, ...)
212 Returns an array containing all unique elements which are common to all
218 Icinga 2 (version: v2.7.0)
219 <1> => var dev_notification_groups = [ "devs", "slack" ]
221 <2> => var host_notification_groups = [ "slack", "noc" ]
223 <3> => intersection(dev_notification_groups, host_notification_groups)
226 ### keys <a id="global-functions-keys"></a>
232 Returns an array containing the dictionary's keys.
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).
240 Icinga 2 (version: v2.7.0)
241 <1> => host.vars.disks["/"] = {}
243 <2> => host.vars.disks["/var"] = {}
245 <3> => host.vars.disks.keys()
248 ### string <a id="global-functions-string"></a>
252 function string(value)
254 Converts the value to a string.
256 **Note**: Instead of using this global function you are advised to use the type's
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)
268 Icinga 2 (version: v2.7.0)
271 <2> => false.to_string()
273 <3> => "abc".to_string()
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"
282 ### number <a id="global-functions-number"></a>
286 function number(value)
288 Converts the value to a number.
293 Icinga 2 (version: v2.7.0)
299 ### bool <a id="global-functions-bool"></a>
305 Converts the value to a bool.
310 Icinga 2 (version: v2.7.0)
316 ### random <a id="global-functions-random"></a>
322 Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h).
325 Icinga 2 (version: v2.7.0)
331 ### log <a id="global-functions-log"></a>
337 Writes a message to the log. Non-string values are converted to a JSON string.
341 function log(severity, facility, value)
343 Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`,
344 `LogInformation`, `LogWarning`, and `LogCritical`.
346 Non-string values are converted to a JSON string.
351 Icinga 2 (version: v2.7.0)
352 <1> => log(LogCritical, "Console", "First line")
353 critical/Console: First line
355 <2> => var groups = [ "devs", "slack" ]
357 <3> => log(LogCritical, "Console", groups)
358 critical/Console: ["devs","slack"]
361 ### typeof <a id="global-functions-typeof"></a>
365 function typeof(value)
367 Returns the [Type](18-library-reference.md#type-type) object for a value.
372 Icinga 2 (version: v2.7.0)
373 <1> => typeof(3) == Number
375 <2> => typeof("str") == String
377 <3> => typeof(true) == Boolean
379 <4> => typeof([ 1, 2, 3]) == Array
381 <5> => typeof({ a = 2, b = 3 }) == Dictionary
384 ### get_time <a id="global-functions-get_time"></a>
390 Returns the current UNIX timestamp as floating point number.
395 Icinga 2 (version: v2.7.0)
401 ### parse_performance_data <a id="global-functions-parse_performance_data"></a>
405 function parse_performance_data(pd)
407 Parses a performance data string and returns an array describing the values.
412 Icinga 2 (version: v2.7.0)
413 <1> => var pd = "'time'=1480074205.197363;;;"
415 <2> => parse_performance_data(pd)
422 type = "PerfdataValue"
424 value = 1480074205.197363
428 ### getenv <a id="global-functions-getenv"></a>
434 Returns the value from the specified environment variable key.
438 $ MY_ENV_VAR=icinga2 icinga2 console
439 Icinga 2 (version: v2.11.0)
440 Type $help to view available commands.
441 <1> => getenv("MY_ENV_VAR")
444 ### dirname <a id="global-functions-dirname"></a>
448 function dirname(path)
450 Returns the directory portion of the specified path.
455 Icinga 2 (version: v2.7.0)
456 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
459 "/etc/icinga2/scripts"
461 ### basename <a id="global-functions-basename"></a>
465 function basename(path)
467 Returns the filename portion of the specified path.
472 Icinga 2 (version: v2.7.0)
473 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
475 <2> => basename(path)
476 "xmpp-notification.pl"
478 ### path\_exists <a id="global-functions-path-exists"></a>
482 function path_exists(path)
484 Returns true if the specified path exists, false otherwise.
489 Icinga 2 (version: v2.7.0)
490 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
492 <2> => path_exists(path)
495 ### glob <a id="global-functions-glob"></a>
499 function glob(pathSpec, type)
501 Returns an array containing all paths which match the
504 The `type` argument is optional and specifies which types
505 of paths are matched. This can be a combination of the `GlobFile`
506 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
509 Icinga 2 (version: v2.7.0)
510 <1> => var pathSpec = "/etc/icinga2/conf.d/*.conf"
512 <2> => glob(pathSpec)
513 [ "/etc/icinga2/conf.d/app.conf", "/etc/icinga2/conf.d/commands.conf", ... ]
515 ### glob\_recursive <a id="global-functions-glob-recursive"></a>
519 function glob_recursive(path, pattern, type)
521 Recursively descends into the specified directory and returns an array containing
522 all paths which match the `pattern` argument.
524 The `type` argument is optional and specifies which types
525 of paths are matched. This can be a combination of the `GlobFile`
526 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
529 Icinga 2 (version: v2.7.0)
530 <1> => var path = "/etc/icinga2/zones.d/"
532 <2> => var pattern = "*.conf"
534 <3> => glob_recursive(path, pattern)
535 [ "/etc/icinga2/zones.d/global-templates/templates.conf", "/etc/icinga2/zones.d/master/hosts.conf", ... ]
537 ### escape_shell_arg <a id="global-functions-escape_shell_arg"></a>
541 function escape_shell_arg(text)
543 Escapes a string for use as a single shell argument.
548 Icinga 2 (version: v2.7.0)
549 <1> => escape_shell_arg("'$host.name$' '$service.name$'")
550 "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
552 ### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a>
556 function escape_shell_cmd(text)
558 Escapes shell meta characters in a string.
563 Icinga 2 (version: v2.7.0)
564 <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
565 "/bin/echo 'shell test' \\$ENV"
567 ### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a>
571 function escape_create_process_arg(text)
573 Escapes a string for use as an argument for CreateProcess(). Windows only.
575 ### sleep <a id="global-functions-sleep"></a>
579 function sleep(interval)
581 Sleeps for the specified amount of time (in seconds).
584 ## Scoped Functions <a id="scoped-functions"></a>
586 This chapter describes functions which are only available
589 ### macro <a id="scoped-functions-macro"></a>
594 function macro("$macro_name$")
597 The `macro` function can be used to resolve [runtime macro](03-monitoring-basics.md#runtime-macros)
598 strings into their values.
599 The returned value depends on the attribute value which is resolved
600 from the specified runtime macro.
602 This function is only available in runtime evaluated functions, e.g.
603 for [custom attributes](03-monitoring-basics.md#custom-attributes-functions) which
604 use the [abbreviated lambda syntax](17-language-reference.md#nullary-lambdas).
606 This example sets the `snmp_address` custom attribute
607 based on `$address$` and `$address6$`.
610 vars.snmp_address = {{
611 var addr_v4 = macro("$address$")
612 var addr_v6 = macro("$address6$")
617 return "udp6:[" + addr_v6 + "]"
622 More reference examples are available inside the [Icinga Template Library](10-icinga-template-library.md#icinga-template-library)
623 and the [object accessors chapter](08-advanced-topics.md#access-object-attributes-at-runtime).
625 ## Object Accessor Functions <a id="object-accessor-functions"></a>
627 These functions can be used to retrieve a reference to another object by name.
629 ### get_check_command <a id="objref-get_check_command"></a>
633 function get_check_command(name);
635 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
637 ### get_event_command <a id="objref-get_event_command"></a>
641 function get_event_command(name);
643 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
645 ### get_notification_command <a id="objref-get_notification_command"></a>
649 function get_notification_command(name);
651 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
653 ### get_host <a id="objref-get_host"></a>
657 function get_host(host_name);
659 Returns the Host object with the specified name, or `null` if no such Host object exists.
662 ### get_service <a id="objref-get_service"></a>
666 function get_service(host_name, service_name);
667 function get_service(host, service_name);
669 Returns the Service object with the specified host name or object and service name pair,
670 or `null` if no such Service object exists.
672 Example in the [debug console](11-cli-commands.md#cli-command-console)
673 which fetches the `disk` service object from the current Icinga 2 node:
676 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
677 Icinga 2 (version: v2.7.0)
679 <1> => get_service(NodeName, "disk")
680 <2> => get_service(NodeName, "disk").__name
681 "icinga2-master1.localdomain!disk"
683 <3> => get_service(get_host(NodeName), "disk").__name
684 "icinga2-master1.localdomain!disk"
687 ### get_services <a id="objref-get_services"></a>
691 function get_services(host_name);
692 function get_services(host);
694 Returns an [array](17-language-reference.md#array) of service objects for the specified host name or object,
695 or `null` if no such host object exists.
697 Example in the [debug console](11-cli-commands.md#cli-command-console)
698 which fetches all service objects from the current Icinga 2 node:
701 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
702 Icinga 2 (version: v2.7.0)
704 <1> => get_services(NodeName).map(s => s.name)
705 [ "disk", "disk /", "http", "icinga", "load", "ping4", "ping6", "procs", "ssh", "users" ]
708 Note: [map](18-library-reference.md#array-map) takes a [lambda function](17-language-reference.md#lambdas) as argument. In this example
709 we only want to collect and print the `name` attribute with `s => s.name`.
711 This works in a similar fashion for a host object where you can extract all service states
712 in using the [map](18-library-reference.md#array-map) functionality:
715 <2> => get_services(get_host(NodeName)).map(s => s.state)
716 [ 2.000000, 2.000000, 2.000000, 0.000000, 0.000000, 0.000000, 2.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000 ]
719 ### get_user <a id="objref-get_user"></a>
723 function get_user(name);
725 Returns the User object with the specified name, or `null` if no such User object exists.
727 ### get_host_group <a id="objref-get_host_group"></a>
731 function get_host_group(name);
733 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
736 ### get_service_group <a id="objref-get_service_group"></a>
740 function get_service_group(name);
742 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
744 ### get_user_group <a id="objref-get_user_group"></a>
748 function get_user_group(name);
750 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
753 ### get_time_period <a id="objref-get_time_period"></a>
757 function get_time_period(name);
759 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
762 ### get_object <a id="objref-get_object"></a>
766 function get_object(type, name);
768 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
772 ### get_objects <a id="objref-get_objects"></a>
776 function get_objects(type);
778 Returns an array of objects whose type matches the specified type. `type` must refer
782 ## Math object <a id="math-object"></a>
784 The global `Math` object can be used to access a number of mathematical constants
787 ### Math.E <a id="math-e"></a>
791 ### Math.LN2 <a id="math-ln2"></a>
793 Natural logarithm of 2.
795 ### Math.LN10 <a id="math-ln10"></a>
797 Natural logarithm of 10.
799 ### Math.LOG2E <a id="math-log2e"></a>
801 Base 2 logarithm of E.
803 ### Math.PI <a id="math-pi"></a>
805 The mathematical constant Pi.
807 ### Math.SQRT1_2 <a id="math-sqrt1_2"></a>
811 ### Math.SQRT2 <a id="math-sqrt2"></a>
815 ### Math.abs <a id="math-abs"></a>
821 Returns the absolute value of `x`.
823 ### Math.acos <a id="math-acos"></a>
829 Returns the arccosine of `x`.
831 ### Math.asin <a id="math-asin"></a>
837 Returns the arcsine of `x`.
839 ### Math.atan <a id="math-atan"></a>
845 Returns the arctangent of `x`.
847 ### Math.atan2 <a id="math-atan2"></a>
851 function atan2(y, x);
853 Returns the arctangent of the quotient of `y` and `x`.
855 ### Math.ceil <a id="math-ceil"></a>
861 Returns the smallest integer value not less than `x`.
863 ### Math.cos <a id="math-cos"></a>
869 Returns the cosine of `x`.
871 ### Math.exp <a id="math-exp"></a>
877 Returns E raised to the `x`th power.
879 ### Math.floor <a id="math-floor"></a>
885 Returns the largest integer value not greater than `x`.
887 ### Math.isinf <a id="math-isinf"></a>
893 Returns whether `x` is infinite.
895 ### Math.isnan <a id="math-isnan"></a>
901 Returns whether `x` is NaN (not-a-number).
903 ### Math.log <a id="math-log"></a>
909 Returns the natural logarithm of `x`.
911 ### Math.max <a id="math-max"></a>
917 Returns the largest argument. A variable number of arguments can be specified.
918 If no arguments are given, -Infinity is returned.
920 ### Math.min <a id="math-min"></a>
926 Returns the smallest argument. A variable number of arguments can be specified.
927 If no arguments are given, +Infinity is returned.
929 ### Math.pow <a id="math-pow"></a>
935 Returns `x` raised to the `y`th power.
937 ### Math.random <a id="math-random"></a>
943 Returns a pseudo-random number between 0 and 1.
945 ### Math.round <a id="math-round"></a>
951 Returns `x` rounded to the nearest integer value.
953 ### Math.sign <a id="math-sign"></a>
959 Returns -1 if `x` is negative, 1 if `x` is positive
962 ### Math.sin <a id="math-sin"></a>
968 Returns the sine of `x`.
970 ### Math.sqrt <a id="math-sqrt"></a>
976 Returns the square root of `x`.
978 ### Math.tan <a id="math-tan"></a>
984 Returns the tangent of `x`.
986 ## Json object <a id="json-object"></a>
988 The global `Json` object can be used to encode and decode JSON.
990 ### Json.encode <a id="json-encode"></a>
996 Encodes an arbitrary value into JSON.
998 ### Json.decode <a id="json-decode"></a>
1004 Decodes a JSON string.
1006 ## Number type <a id="number-type"></a>
1008 ### Number#to_string <a id="number-to_string"></a>
1012 function to_string();
1014 The `to_string` method returns a string representation of the number.
1019 example.to_string() /* Returns "7" */
1021 ## Boolean type <a id="boolean-type"></a>
1023 ### Boolean#to_string <a id="boolean-to_string"></a>
1027 function to_string();
1029 The `to_string` method returns a string representation of the boolean value.
1034 example.to_string() /* Returns "true" */
1036 ## String type <a id="string-type"></a>
1038 ### String#find <a id="string-find"></a>
1042 function find(str, start);
1044 Returns the zero-based index at which the string `str` was found in the string. If the string
1045 was not found, -1 is returned. `start` specifies the zero-based index at which `find` should
1046 start looking for the string (defaults to 0 when not specified).
1050 "Hello World".find("World") /* Returns 6 */
1052 ### String#contains <a id="string-contains"></a>
1056 function contains(str);
1058 Returns `true` if the string `str` was found in the string. If the string
1059 was not found, `false` is returned. Use [find](18-library-reference.md#string-find)
1060 for getting the index instead.
1064 "Hello World".contains("World") /* Returns true */
1066 ### String#len <a id="string-len"></a>
1072 Returns the length of the string in bytes. Note that depending on the encoding type of the string
1073 this is not necessarily the number of characters.
1077 "Hello World".len() /* Returns 11 */
1079 ### String#lower <a id="string-lower"></a>
1085 Returns a copy of the string with all of its characters converted to lower-case.
1089 "Hello World".lower() /* Returns "hello world" */
1091 ### String#upper <a id="string-upper"></a>
1097 Returns a copy of the string with all of its characters converted to upper-case.
1101 "Hello World".upper() /* Returns "HELLO WORLD" */
1103 ### String#replace <a id="string-replace"></a>
1107 function replace(search, replacement);
1109 Returns a copy of the string with all occurences of the string specified in `search` replaced
1110 with the string specified in `replacement`.
1112 ### String#split <a id="string-split"></a>
1116 function split(delimiters);
1118 Splits a string into individual parts and returns them as an array. The `delimiters` argument
1119 specifies the characters which should be used as delimiters between parts.
1123 "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
1125 ### String#substr <a id="string-substr"></a>
1129 function substr(start, len);
1131 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
1132 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
1136 "Hello World".substr(6) /* Returns "World" */
1138 ### String#to_string <a id="string-to_string"></a>
1142 function to_string();
1144 Returns a copy of the string.
1146 ### String#reverse <a id="string-reverse"></a>
1152 Returns a copy of the string in reverse order.
1154 ### String#trim <a id="string-trim"></a>
1160 Removes trailing whitespaces and returns the string.
1162 ## Object type <a id="object-type"></a>
1164 This is the base type for all types in the Icinga application.
1166 ### Object#clone <a id="object-clone"></a>
1172 Returns a copy of the object. Note that for object elements which are
1173 reference values (e.g. objects such as arrays or dictionaries) the entire
1174 object is recursively copied.
1176 ### Object#to_string <a id="object-to-string"></a>
1180 function to_string();
1182 Returns a string representation for the object. Unless overridden this returns a string
1183 of the format "Object of type '<typename>'" where <typename> is the name of the
1188 [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
1190 ### Object#type <a id="object-type-field"></a>
1196 Returns the object's type name. This attribute is read-only.
1200 get_host("localhost").type /* Returns "Host" */
1202 ## Type type <a id="type-type"></a>
1204 Inherits methods from the [Object type](18-library-reference.md#object-type).
1206 The `Type` type provides information about the underlying type of an object or scalar value.
1208 All types are registered as global variables. For example, in order to obtain a reference to the `String` type the global variable `String` can be used.
1210 ### Type#base <a id="type-base"></a>
1216 Returns a reference to the type's base type. This attribute is read-only.
1220 Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
1222 ### Type#name <a id="type-name"></a>
1228 Returns the name of the type.
1230 ### Type#prototype <a id="type-prototype"></a>
1236 Returns the prototype object for the type. When an attribute is accessed on an object that doesn't exist the prototype object is checked to see if an attribute with the requested name exists. If it does, the attribute's value is returned.
1238 The prototype functionality is used to implement methods.
1242 3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
1244 ## Array type <a id="array-type"></a>
1246 Inherits methods from the [Object type](18-library-reference.md#object-type).
1248 ### Array#add <a id="array-add"></a>
1252 function add(value);
1254 Adds a new value after the last element in the array.
1256 ### Array#clear <a id="array-clear"></a>
1262 Removes all elements from the array.
1264 ### Array#shallow_clone <a id="array-shallow-clone"></a>
1266 function shallow_clone();
1268 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
1269 as arrays and dictionaries) only the references are copied.
1271 ### Array#contains <a id="array-contains"></a>
1275 function contains(value);
1277 Returns true if the array contains the specified value, false otherwise.
1279 ### Array#freeze <a id="array-freeze"></a>
1285 Disallows further modifications to this array. Trying to modify the array will result in an exception.
1287 ### Array#len <a id="array-len"></a>
1293 Returns the number of elements contained in the array.
1295 ### Array#remove <a id="array-remove"></a>
1299 function remove(index);
1301 Removes the element at the specified zero-based index.
1303 ### Array#set <a id="array-set"></a>
1307 function set(index, value);
1309 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
1310 which already exists in the array.
1312 ### Array#get <a id="array-get"></a>
1316 function get(index);
1318 Retrieves the element at the specified zero-based index.
1320 ### Array#sort <a id="array-sort"></a>
1324 function sort(less_cmp);
1326 Returns a copy of the array where all items are sorted. The items are
1327 compared using the `<` (less-than) operator. A custom comparator function
1328 can be specified with the `less_cmp` argument.
1330 ### Array#join <a id="array-join"></a>
1334 function join(separator);
1336 Joins all elements of the array using the specified separator.
1338 ### Array#reverse <a id="array-reverse"></a>
1344 Returns a new array with all elements of the current array in reverse order.
1346 ### Array#map <a id="array-map"></a>
1352 Calls `func(element)` for each of the elements in the array and returns
1353 a new array containing the return values of these function calls.
1355 ### Array#reduce <a id="array-reduce"></a>
1359 function reduce(func);
1361 Reduces the elements of the array into a single value by calling the provided
1362 function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
1363 or results from previous function calls.
1365 ### Array#filter <a id="array-filter"></a>
1369 function filter(func);
1371 Returns a copy of the array containing only the elements for which `func(element)`
1374 ### Array#any <a id="array-any"></a>
1380 Returns true if the array contains at least one element for which `func(element)`
1381 is true, false otherwise.
1383 ### Array#all <a id="array-all"></a>
1389 Returns true if the array contains only elements for which `func(element)`
1390 is true, false otherwise.
1392 ### Array#unique <a id="array-unique"></a>
1398 Returns a copy of the array with all duplicate elements removed. The original order
1399 of the array is not preserved.
1401 ## Dictionary type <a id="dictionary-type"></a>
1403 Inherits methods from the [Object type](18-library-reference.md#object-type).
1405 ### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
1409 function shallow_clone();
1411 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
1412 as arrays and dictionaries) only the references are copied.
1414 ### Dictionary#contains <a id="dictionary-contains"></a>
1418 function contains(key);
1420 Returns true if a dictionary item with the specified `key` exists, false otherwise.
1422 ### Dictionary#freeze <a id="dictionary-freeze"></a>
1428 Disallows further modifications to this dictionary. Trying to modify the dictionary will result in an exception.
1430 ### Dictionary#len <a id="dictionary-len"></a>
1436 Returns the number of items contained in the dictionary.
1438 ### Dictionary#remove <a id="dictionary-remove"></a>
1442 function remove(key);
1444 Removes the item with the specified `key`. Trying to remove an item which does not exist
1447 ### Dictionary#clear <a id="dictionary-clear"></a>
1453 Removes all items from the dictionary.
1455 ### Dictionary#set <a id="dictionary-set"></a>
1459 function set(key, value);
1461 Creates or updates an item with the specified `key` and `value`.
1463 ### Dictionary#get <a id="dictionary-get"></a>
1469 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
1472 ### Dictionary#keys <a id="dictionary-keys"></a>
1478 Returns a list of keys for all items that are currently in the dictionary.
1480 ### Dictionary#values <a id="dictionary-values"></a>
1486 Returns a list of values for all items that are currently in the dictionary.
1488 ## Function type <a id="scriptfunction-type"></a>
1490 Inherits methods from the [Object type](18-library-reference.md#object-type).
1492 ### Function#call <a id="scriptfunction-call"></a>
1496 function call(thisArg, ...);
1498 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1499 scope for the function. All other arguments are passed directly to the function.
1503 function set_x(val) {
1509 set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
1511 ### Function#callv <a id="scriptfunction-callv"></a>
1515 function callv(thisArg, args);
1517 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1518 scope for the function. The items in the `args` array are passed to the function as individual arguments.
1522 function set_x(val) {
1530 set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
1532 ## DateTime type <a id="datetime-type"></a>
1534 Inherits methods from the [Object type](18-library-reference.md#object-type).
1536 ### DateTime constructor <a id="datetime-ctor"></a>
1541 function DateTime(unixTimestamp)
1542 function DateTime(year, month, day)
1543 function DateTime(year, month, day, hours, minutes, seconds)
1545 Constructs a new DateTime object. When no arguments are specified for the constructor a new
1546 DateTime object representing the current time is created.
1550 var d1 = DateTime() /* current time */
1551 var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
1553 ### DateTime arithmetic <a id="datetime-arithmetic"></a>
1555 Subtracting two DateTime objects yields the interval between them, in seconds.
1559 var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */
1561 Subtracting a number from a DateTime object yields a new DateTime object that is further in the past:
1565 var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */
1567 Adding a number to a DateTime object yields a new DateTime object that is in the future:
1571 var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */
1573 ### DateTime#format <a id="datetime-format"></a>
1577 function format(fmt)
1579 Returns a string representation for the DateTime object using the specified format string.
1580 The format string may contain format conversion placeholders as specified in strftime(3).
1584 var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
1586 ### DateTime#to_string <a id="datetime-tostring"></a>
1590 function to_string()
1592 Returns a string representation for the DateTime object. Uses a suitable default format.
1596 var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */