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>
18 function regex(pattern, value, mode)
21 Returns true if the regular expression `pattern` matches the `value`, false otherwise.
22 The `value` can be of the type [String](18-library-reference.md#string-type) or [Array](18-library-reference.md#array-type) (which
23 contains string elements).
25 The `mode` argument is optional and can be either `MatchAll` (in which case all elements
26 for an array have to match) or `MatchAny` (in which case at least one element has to match).
27 The default mode is `MatchAll`.
29 **Tip**: In case you are looking for regular expression tests try [regex101](https://regex101.com).
31 Example for string values:
35 Icinga 2 (version: v2.11.0)
36 <1> => host.vars.os_type = "Linux/Unix"
38 <2> => regex("^Linux", host.vars.os_type)
40 <3> => regex("^Linux$", host.vars.os_type)
44 Example for an array of string values:
48 Icinga 2 (version: v2.11.0)
49 <1> => host.vars.databases = [ "db-prod1", "db-prod2", "db-dev" ]
51 <2> => regex("^db-prod\\d+", host.vars.databases, MatchAny)
53 <3> => regex("^db-prod\\d+", host.vars.databases, MatchAll)
57 ### match <a id="global-functions-match"></a>
62 function match(pattern, text, mode)
65 Returns true if the wildcard (`?*`) `pattern` matches the `value`, false otherwise.
66 The `value` can be of the type [String](18-library-reference.md#string-type) or [Array](18-library-reference.md#array-type) (which
67 contains string elements).
69 The `mode` argument is optional and can be either `MatchAll` (in which case all elements
70 for an array have to match) or `MatchAny` (in which case at least one element has to match).
71 The default mode is `MatchAll`.
73 Example for string values:
77 Icinga 2 (version: v2.11.0)
78 <1> => var name = "db-prod-sfo-657"
80 <2> => match("*prod-sfo*", name)
82 <3> => match("*-dev-*", name)
86 Example for an array of string values:
90 Icinga 2 (version: v2.11.0-28)
91 <1> => host.vars.application_types = [ "web-wp", "web-rt", "db-local" ]
93 <2> => match("web-*", host.vars.application_types, MatchAll)
95 <3> => match("web-*", host.vars.application_types, MatchAny)
99 ### cidr_match <a id="global-functions-cidr_match"></a>
104 function cidr_match(pattern, ip, mode)
107 Returns true if the CIDR pattern matches the IP address, false otherwise.
109 IPv4 addresses are converted to IPv4-mapped IPv6 addresses before being
110 matched against the pattern. The `mode` argument is optional and can be
111 either `MatchAll` (in which case all elements for an array have to match) or `MatchAny`
112 (in which case at least one element has to match). The default mode is `MatchAll`.
115 Example for a single IP address:
119 Icinga 2 (version: v2.11.0)
120 <1> => host.address = "192.168.56.101"
122 <2> => cidr_match("192.168.56.0/24", host.address)
124 <3> => cidr_match("192.168.56.0/26", host.address)
128 Example for an array of IP addresses:
132 Icinga 2 (version: v2.11.0)
133 <1> => host.vars.vhost_ips = [ "192.168.56.101", "192.168.56.102", "10.0.10.99" ]
135 <2> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAll)
137 <3> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAny)
141 ### range <a id="global-functions-range"></a>
147 function range(start, end)
148 function range(start, end, increment)
151 Returns an array of numbers in the specified range.
152 If you specify one parameter, the first element starts at `0`.
153 The following array numbers are incremented by `1` and stop before
155 If you specify the start and end numbers, the returned array
156 number are incremented by `1`. They start at the specified start
157 number and stop before the end number.
158 Optionally you can specify the incremented step between numbers
165 Icinga 2 (version: v2.11.0)
167 [ 0.000000, 1.000000, 2.000000, 3.000000, 4.000000 ]
169 [ 2.000000, 3.000000 ]
171 [ 2.000000, 4.000000, 6.000000, 8.000000 ]
174 ### len <a id="global-functions-len"></a>
182 Returns the length of the value, i.e. the number of elements for an array
183 or dictionary, or the length of the string in bytes.
185 **Note**: Instead of using this global function you are advised to use the type's
186 prototype method: [Array#len](18-library-reference.md#array-len), [Dictionary#len](18-library-reference.md#dictionary-len) and
187 [String#len](18-library-reference.md#string-len).
193 Icinga 2 (version: v2.11.0)
194 <1> => host.groups = [ "linux-servers", "db-servers" ]
196 <2> => host.groups.len()
198 <3> => host.vars.disks["/"] = {}
200 <4> => host.vars.disks["/var"] = {}
202 <5> => host.vars.disks.len()
204 <6> => host.vars.os_type = "Linux/Unix"
206 <7> => host.vars.os_type.len()
210 ### union <a id="global-functions-union"></a>
215 function union(array, array, ...)
218 Returns an array containing all unique elements from the specified arrays.
223 Icinga 2 (version: v2.11.0)
224 <1> => var dev_notification_groups = [ "devs", "slack" ]
226 <2> => var host_notification_groups = [ "slack", "noc" ]
228 <3> => union(dev_notification_groups, host_notification_groups)
229 [ "devs", "noc", "slack" ]
232 ### intersection <a id="global-functions-intersection"></a>
237 function intersection(array, array, ...)
240 Returns an array containing all unique elements which are common to all
247 Icinga 2 (version: v2.11.0)
248 <1> => var dev_notification_groups = [ "devs", "slack" ]
250 <2> => var host_notification_groups = [ "slack", "noc" ]
252 <3> => intersection(dev_notification_groups, host_notification_groups)
256 ### keys <a id="global-functions-keys"></a>
264 Returns an array containing the dictionary's keys.
266 **Note**: Instead of using this global function you are advised to use the type's
267 prototype method: [Dictionary#keys](18-library-reference.md#dictionary-keys).
273 Icinga 2 (version: v2.11.0)
274 <1> => host.vars.disks["/"] = {}
276 <2> => host.vars.disks["/var"] = {}
278 <3> => host.vars.disks.keys()
282 ### string <a id="global-functions-string"></a>
287 function string(value)
290 Converts the value to a string.
292 **Note**: Instead of using this global function you are advised to use the type's
295 * [Number#to_string](18-library-reference.md#number-to_string)
296 * [Boolean#to_string](18-library-reference.md#boolean-to_string)
297 * [String#to_string](18-library-reference.md#string-to_string)
298 * [Object#to_string](18-library-reference.md#object-to-string) for Array and Dictionary types
299 * [DateTime#to_string](18-library-reference.md#datetime-tostring)
305 Icinga 2 (version: v2.11.0)
308 <2> => false.to_string()
310 <3> => "abc".to_string()
312 <4> => [ "dev", "slack" ].to_string()
313 "[ \"dev\", \"slack\" ]"
314 <5> => { "/" = {}, "/var" = {} }.to_string()
315 "{\n\t\"/\" = {\n\t}\n\t\"/var\" = {\n\t}\n}"
316 <6> => DateTime(2016, 11, 25).to_string()
317 "2016-11-25 00:00:00 +0100"
320 ### number <a id="global-functions-number"></a>
325 function number(value)
328 Converts the value to a number.
334 Icinga 2 (version: v2.11.0)
341 ### bool <a id="global-functions-bool"></a>
349 Converts the value to a bool.
355 Icinga 2 (version: v2.11.0)
362 ### random <a id="global-functions-random"></a>
370 Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h).
374 Icinga 2 (version: v2.11.0)
381 ### log <a id="global-functions-log"></a>
389 Writes a message to the log. Non-string values are converted to a JSON string.
394 function log(severity, facility, value)
397 Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`,
398 `LogInformation`, `LogWarning`, and `LogCritical`.
400 Non-string values are converted to a JSON string.
406 Icinga 2 (version: v2.11.0)
407 <1> => log(LogCritical, "Console", "First line")
408 critical/Console: First line
410 <2> => var groups = [ "devs", "slack" ]
412 <3> => log(LogCritical, "Console", groups)
413 critical/Console: ["devs","slack"]
417 ### typeof <a id="global-functions-typeof"></a>
422 function typeof(value)
425 Returns the [Type](18-library-reference.md#type-type) object for a value.
431 Icinga 2 (version: v2.11.0)
432 <1> => typeof(3) == Number
434 <2> => typeof("str") == String
436 <3> => typeof(true) == Boolean
438 <4> => typeof([ 1, 2, 3]) == Array
440 <5> => typeof({ a = 2, b = 3 }) == Dictionary
444 ### get_time <a id="global-functions-get_time"></a>
452 Returns the current UNIX timestamp as floating point number.
458 Icinga 2 (version: v2.11.0)
465 ### parse_performance_data <a id="global-functions-parse_performance_data"></a>
470 function parse_performance_data(pd)
473 Parses a performance data string and returns an array describing the values.
479 Icinga 2 (version: v2.11.0)
480 <1> => var pd = "'time'=1480074205.197363;;;"
482 <2> => parse_performance_data(pd)
489 type = "PerfdataValue"
491 value = 1480074205.197363
496 ### getenv <a id="global-functions-getenv"></a>
504 Returns the value from the specified environment variable key.
509 $ MY_ENV_VAR=icinga2 icinga2 console
510 Icinga 2 (version: v2.11.0)
511 Type $help to view available commands.
512 <1> => getenv("MY_ENV_VAR")
516 ### dirname <a id="global-functions-dirname"></a>
521 function dirname(path)
524 Returns the directory portion of the specified path.
530 Icinga 2 (version: v2.11.0)
531 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
534 "/etc/icinga2/scripts"
537 ### basename <a id="global-functions-basename"></a>
542 function basename(path)
545 Returns the filename portion of the specified path.
551 Icinga 2 (version: v2.11.0)
552 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
554 <2> => basename(path)
555 "xmpp-notification.pl"
558 ### path\_exists <a id="global-functions-path-exists"></a>
563 function path_exists(path)
566 Returns true if the specified path exists, false otherwise.
572 Icinga 2 (version: v2.11.0)
573 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
575 <2> => path_exists(path)
579 ### glob <a id="global-functions-glob"></a>
584 function glob(pathSpec, type)
587 Returns an array containing all paths which match the
590 The `type` argument is optional and specifies which types
591 of paths are matched. This can be a combination of the `GlobFile`
592 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
596 Icinga 2 (version: v2.11.0)
597 <1> => var pathSpec = "/etc/icinga2/conf.d/*.conf"
599 <2> => glob(pathSpec)
600 [ "/etc/icinga2/conf.d/app.conf", "/etc/icinga2/conf.d/commands.conf", ... ]
603 ### glob\_recursive <a id="global-functions-glob-recursive"></a>
608 function glob_recursive(path, pattern, type)
611 Recursively descends into the specified directory and returns an array containing
612 all paths which match the `pattern` argument.
614 The `type` argument is optional and specifies which types
615 of paths are matched. This can be a combination of the `GlobFile`
616 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
620 Icinga 2 (version: v2.11.0)
621 <1> => var path = "/etc/icinga2/zones.d/"
623 <2> => var pattern = "*.conf"
625 <3> => glob_recursive(path, pattern)
626 [ "/etc/icinga2/zones.d/global-templates/templates.conf", "/etc/icinga2/zones.d/master/hosts.conf", ... ]
629 ### escape_shell_arg <a id="global-functions-escape_shell_arg"></a>
634 function escape_shell_arg(text)
637 Escapes a string for use as a single shell argument.
643 Icinga 2 (version: v2.11.0)
644 <1> => escape_shell_arg("'$host.name$' '$service.name$'")
645 "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
648 ### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a>
653 function escape_shell_cmd(text)
656 Escapes shell meta characters in a string.
662 Icinga 2 (version: v2.11.0)
663 <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
664 "/bin/echo 'shell test' \\$ENV"
667 ### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a>
672 function escape_create_process_arg(text)
675 Escapes a string for use as an argument for CreateProcess(). Windows only.
677 ### sleep <a id="global-functions-sleep"></a>
682 function sleep(interval)
685 Sleeps for the specified amount of time (in seconds).
688 ## Scoped Functions <a id="scoped-functions"></a>
690 This chapter describes functions which are only available
693 ### macro <a id="scoped-functions-macro"></a>
698 function macro("$macro_name$")
701 The `macro` function can be used to resolve [runtime macro](03-monitoring-basics.md#runtime-macros)
702 strings into their values.
703 The returned value depends on the attribute value which is resolved
704 from the specified runtime macro.
706 This function is only available in runtime evaluated functions, e.g.
707 for [custom attributes](03-monitoring-basics.md#custom-attributes-functions) which
708 use the [abbreviated lambda syntax](17-language-reference.md#nullary-lambdas).
710 This example sets the `snmp_address` custom attribute
711 based on `$address$` and `$address6$`.
714 vars.snmp_address = {{
715 var addr_v4 = macro("$address$")
716 var addr_v6 = macro("$address6$")
721 return "udp6:[" + addr_v6 + "]"
726 More reference examples are available inside the [Icinga Template Library](10-icinga-template-library.md#icinga-template-library)
727 and the [object accessors chapter](08-advanced-topics.md#access-object-attributes-at-runtime).
729 ## Object Accessor Functions <a id="object-accessor-functions"></a>
731 These functions can be used to retrieve a reference to another object by name.
733 ### get_check_command <a id="objref-get_check_command"></a>
738 function get_check_command(name);
741 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
743 ### get_event_command <a id="objref-get_event_command"></a>
748 function get_event_command(name);
751 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
753 ### get_notification_command <a id="objref-get_notification_command"></a>
758 function get_notification_command(name);
761 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
763 ### get_host <a id="objref-get_host"></a>
768 function get_host(host_name);
771 Returns the Host object with the specified name, or `null` if no such Host object exists.
774 ### get_service <a id="objref-get_service"></a>
779 function get_service(host_name, service_name);
780 function get_service(host, service_name);
783 Returns the Service object with the specified host name or object and service name pair,
784 or `null` if no such Service object exists.
786 Example in the [debug console](11-cli-commands.md#cli-command-console)
787 which fetches the `disk` service object from the current Icinga 2 node:
790 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
791 Icinga 2 (version: v2.11.0)
793 <1> => get_service(NodeName, "disk")
794 <2> => get_service(NodeName, "disk").__name
795 "icinga2-master1.localdomain!disk"
797 <3> => get_service(get_host(NodeName), "disk").__name
798 "icinga2-master1.localdomain!disk"
801 ### get_services <a id="objref-get_services"></a>
806 function get_services(host_name);
807 function get_services(host);
810 Returns an [array](17-language-reference.md#array) of service objects for the specified host name or object,
811 or `null` if no such host object exists.
813 Example in the [debug console](11-cli-commands.md#cli-command-console)
814 which fetches all service objects from the current Icinga 2 node:
817 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
818 Icinga 2 (version: v2.11.0)
820 <1> => get_services(NodeName).map(s => s.name)
821 [ "disk", "disk /", "http", "icinga", "load", "ping4", "ping6", "procs", "ssh", "users" ]
824 Note: [map](18-library-reference.md#array-map) takes a [lambda function](17-language-reference.md#lambdas) as argument. In this example
825 we only want to collect and print the `name` attribute with `s => s.name`.
827 This works in a similar fashion for a host object where you can extract all service states
828 in using the [map](18-library-reference.md#array-map) functionality:
831 <2> => get_services(get_host(NodeName)).map(s => s.state)
832 [ 2.000000, 2.000000, 2.000000, 0.000000, 0.000000, 0.000000, 2.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000 ]
835 ### get_user <a id="objref-get_user"></a>
840 function get_user(name);
843 Returns the User object with the specified name, or `null` if no such User object exists.
845 ### get_host_group <a id="objref-get_host_group"></a>
850 function get_host_group(name);
853 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
856 ### get_service_group <a id="objref-get_service_group"></a>
861 function get_service_group(name);
864 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
866 ### get_user_group <a id="objref-get_user_group"></a>
871 function get_user_group(name);
874 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
877 ### get_time_period <a id="objref-get_time_period"></a>
882 function get_time_period(name);
885 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
888 ### get_object <a id="objref-get_object"></a>
893 function get_object(type, name);
896 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
900 ### get_objects <a id="objref-get_objects"></a>
905 function get_objects(type);
908 Returns an array of objects whose type matches the specified type. `type` must refer
912 ## Math object <a id="math-object"></a>
914 The global `Math` object can be used to access a number of mathematical constants
917 ### Math.E <a id="math-e"></a>
921 ### Math.LN2 <a id="math-ln2"></a>
923 Natural logarithm of 2.
925 ### Math.LN10 <a id="math-ln10"></a>
927 Natural logarithm of 10.
929 ### Math.LOG2E <a id="math-log2e"></a>
931 Base 2 logarithm of E.
933 ### Math.PI <a id="math-pi"></a>
935 The mathematical constant Pi.
937 ### Math.SQRT1_2 <a id="math-sqrt1_2"></a>
941 ### Math.SQRT2 <a id="math-sqrt2"></a>
945 ### Math.abs <a id="math-abs"></a>
953 Returns the absolute value of `x`.
955 ### Math.acos <a id="math-acos"></a>
963 Returns the arccosine of `x`.
965 ### Math.asin <a id="math-asin"></a>
973 Returns the arcsine of `x`.
975 ### Math.atan <a id="math-atan"></a>
983 Returns the arctangent of `x`.
985 ### Math.atan2 <a id="math-atan2"></a>
990 function atan2(y, x);
992 Returns the arctangent of the quotient of `y` and `x`.
994 ### Math.ceil <a id="math-ceil"></a>
1002 Returns the smallest integer value not less than `x`.
1004 ### Math.cos <a id="math-cos"></a>
1012 Returns the cosine of `x`.
1014 ### Math.exp <a id="math-exp"></a>
1022 Returns E raised to the `x`th power.
1024 ### Math.floor <a id="math-floor"></a>
1032 Returns the largest integer value not greater than `x`.
1034 ### Math.isinf <a id="math-isinf"></a>
1042 Returns whether `x` is infinite.
1044 ### Math.isnan <a id="math-isnan"></a>
1052 Returns whether `x` is NaN (not-a-number).
1054 ### Math.log <a id="math-log"></a>
1062 Returns the natural logarithm of `x`.
1064 ### Math.max <a id="math-max"></a>
1072 Returns the largest argument. A variable number of arguments can be specified.
1073 If no arguments are given, -Infinity is returned.
1075 ### Math.min <a id="math-min"></a>
1083 Returns the smallest argument. A variable number of arguments can be specified.
1084 If no arguments are given, +Infinity is returned.
1086 ### Math.pow <a id="math-pow"></a>
1094 Returns `x` raised to the `y`th power.
1096 ### Math.random <a id="math-random"></a>
1104 Returns a pseudo-random number between 0 and 1.
1106 ### Math.round <a id="math-round"></a>
1114 Returns `x` rounded to the nearest integer value.
1116 ### Math.sign <a id="math-sign"></a>
1124 Returns -1 if `x` is negative, 1 if `x` is positive
1127 ### Math.sin <a id="math-sin"></a>
1135 Returns the sine of `x`.
1137 ### Math.sqrt <a id="math-sqrt"></a>
1145 Returns the square root of `x`.
1147 ### Math.tan <a id="math-tan"></a>
1155 Returns the tangent of `x`.
1157 ## Json object <a id="json-object"></a>
1159 The global `Json` object can be used to encode and decode JSON.
1161 ### Json.encode <a id="json-encode"></a>
1169 Encodes an arbitrary value into JSON.
1171 ### Json.decode <a id="json-decode"></a>
1179 Decodes a JSON string.
1181 ## Number type <a id="number-type"></a>
1183 ### Number#to_string <a id="number-to_string"></a>
1188 function to_string();
1191 The `to_string` method returns a string representation of the number.
1197 example.to_string() /* Returns "7" */
1200 ## Boolean type <a id="boolean-type"></a>
1202 ### Boolean#to_string <a id="boolean-to_string"></a>
1207 function to_string();
1210 The `to_string` method returns a string representation of the boolean value.
1216 example.to_string() /* Returns "true" */
1219 ## String type <a id="string-type"></a>
1221 ### String#find <a id="string-find"></a>
1226 function find(str, start);
1229 Returns the zero-based index at which the string `str` was found in the string. If the string
1230 was not found, -1 is returned. `start` specifies the zero-based index at which `find` should
1231 start looking for the string (defaults to 0 when not specified).
1236 "Hello World".find("World") /* Returns 6 */
1239 ### String#contains <a id="string-contains"></a>
1244 function contains(str);
1247 Returns `true` if the string `str` was found in the string. If the string
1248 was not found, `false` is returned. Use [find](18-library-reference.md#string-find)
1249 for getting the index instead.
1254 "Hello World".contains("World") /* Returns true */
1257 ### String#len <a id="string-len"></a>
1265 Returns the length of the string in bytes. Note that depending on the encoding type of the string
1266 this is not necessarily the number of characters.
1271 "Hello World".len() /* Returns 11 */
1274 ### String#lower <a id="string-lower"></a>
1282 Returns a copy of the string with all of its characters converted to lower-case.
1287 "Hello World".lower() /* Returns "hello world" */
1290 ### String#upper <a id="string-upper"></a>
1298 Returns a copy of the string with all of its characters converted to upper-case.
1303 "Hello World".upper() /* Returns "HELLO WORLD" */
1306 ### String#replace <a id="string-replace"></a>
1311 function replace(search, replacement);
1314 Returns a copy of the string with all occurences of the string specified in `search` replaced
1315 with the string specified in `replacement`.
1317 ### String#split <a id="string-split"></a>
1322 function split(delimiters);
1325 Splits a string into individual parts and returns them as an array. The `delimiters` argument
1326 specifies the characters which should be used as delimiters between parts.
1331 "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
1334 ### String#substr <a id="string-substr"></a>
1339 function substr(start, len);
1342 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
1343 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
1348 "Hello World".substr(6) /* Returns "World" */
1351 ### String#to_string <a id="string-to_string"></a>
1356 function to_string();
1359 Returns a copy of the string.
1361 ### String#reverse <a id="string-reverse"></a>
1369 Returns a copy of the string in reverse order.
1371 ### String#trim <a id="string-trim"></a>
1379 Removes trailing whitespaces and returns the string.
1381 ## Object type <a id="object-type"></a>
1383 This is the base type for all types in the Icinga application.
1385 ### Object#clone <a id="object-clone"></a>
1393 Returns a copy of the object. Note that for object elements which are
1394 reference values (e.g. objects such as arrays or dictionaries) the entire
1395 object is recursively copied.
1397 ### Object#to_string <a id="object-to-string"></a>
1402 function to_string();
1405 Returns a string representation for the object. Unless overridden this returns a string
1406 of the format "Object of type '<typename>'" where <typename> is the name of the
1412 [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
1415 ### Object#type <a id="object-type-field"></a>
1421 Returns the object's type name. This attribute is read-only.
1426 get_host("localhost").type /* Returns "Host" */
1429 ## Type type <a id="type-type"></a>
1431 Inherits methods from the [Object type](18-library-reference.md#object-type).
1433 The `Type` type provides information about the underlying type of an object or scalar value.
1435 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.
1437 ### Type#base <a id="type-base"></a>
1445 Returns a reference to the type's base type. This attribute is read-only.
1450 Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
1453 ### Type#name <a id="type-name"></a>
1461 Returns the name of the type.
1463 ### Type#prototype <a id="type-prototype"></a>
1471 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.
1473 The prototype functionality is used to implement methods.
1478 3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
1481 ## Array type <a id="array-type"></a>
1483 Inherits methods from the [Object type](18-library-reference.md#object-type).
1485 ### Array#add <a id="array-add"></a>
1490 function add(value);
1493 Adds a new value after the last element in the array.
1495 ### Array#clear <a id="array-clear"></a>
1503 Removes all elements from the array.
1505 ### Array#shallow_clone <a id="array-shallow-clone"></a>
1508 function shallow_clone();
1511 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
1512 as arrays and dictionaries) only the references are copied.
1514 ### Array#contains <a id="array-contains"></a>
1519 function contains(value);
1522 Returns true if the array contains the specified value, false otherwise.
1524 ### Array#freeze <a id="array-freeze"></a>
1532 Disallows further modifications to this array. Trying to modify the array will result in an exception.
1534 ### Array#len <a id="array-len"></a>
1542 Returns the number of elements contained in the array.
1544 ### Array#remove <a id="array-remove"></a>
1549 function remove(index);
1552 Removes the element at the specified zero-based index.
1554 ### Array#set <a id="array-set"></a>
1559 function set(index, value);
1562 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
1563 which already exists in the array.
1565 ### Array#get <a id="array-get"></a>
1570 function get(index);
1573 Retrieves the element at the specified zero-based index.
1575 ### Array#sort <a id="array-sort"></a>
1580 function sort(less_cmp);
1583 Returns a copy of the array where all items are sorted. The items are
1584 compared using the `<` (less-than) operator. A custom comparator function
1585 can be specified with the `less_cmp` argument.
1587 ### Array#join <a id="array-join"></a>
1592 function join(separator);
1595 Joins all elements of the array using the specified separator.
1597 ### Array#reverse <a id="array-reverse"></a>
1605 Returns a new array with all elements of the current array in reverse order.
1607 ### Array#map <a id="array-map"></a>
1615 Calls `func(element)` for each of the elements in the array and returns
1616 a new array containing the return values of these function calls.
1618 ### Array#reduce <a id="array-reduce"></a>
1623 function reduce(func);
1626 Reduces the elements of the array into a single value by calling the provided
1627 function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
1628 or results from previous function calls.
1630 ### Array#filter <a id="array-filter"></a>
1635 function filter(func);
1638 Returns a copy of the array containing only the elements for which `func(element)`
1641 ### Array#any <a id="array-any"></a>
1649 Returns true if the array contains at least one element for which `func(element)`
1650 is true, false otherwise.
1652 ### Array#all <a id="array-all"></a>
1660 Returns true if the array contains only elements for which `func(element)`
1661 is true, false otherwise.
1663 ### Array#unique <a id="array-unique"></a>
1671 Returns a copy of the array with all duplicate elements removed. The original order
1672 of the array is not preserved.
1674 ## Dictionary type <a id="dictionary-type"></a>
1676 Inherits methods from the [Object type](18-library-reference.md#object-type).
1678 ### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
1683 function shallow_clone();
1686 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
1687 as arrays and dictionaries) only the references are copied.
1689 ### Dictionary#contains <a id="dictionary-contains"></a>
1694 function contains(key);
1697 Returns true if a dictionary item with the specified `key` exists, false otherwise.
1699 ### Dictionary#freeze <a id="dictionary-freeze"></a>
1707 Disallows further modifications to this dictionary. Trying to modify the dictionary will result in an exception.
1709 ### Dictionary#len <a id="dictionary-len"></a>
1717 Returns the number of items contained in the dictionary.
1719 ### Dictionary#remove <a id="dictionary-remove"></a>
1724 function remove(key);
1727 Removes the item with the specified `key`. Trying to remove an item which does not exist
1730 ### Dictionary#clear <a id="dictionary-clear"></a>
1738 Removes all items from the dictionary.
1740 ### Dictionary#set <a id="dictionary-set"></a>
1745 function set(key, value);
1748 Creates or updates an item with the specified `key` and `value`.
1750 ### Dictionary#get <a id="dictionary-get"></a>
1758 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
1761 ### Dictionary#keys <a id="dictionary-keys"></a>
1769 Returns a list of keys for all items that are currently in the dictionary.
1771 ### Dictionary#values <a id="dictionary-values"></a>
1779 Returns a list of values for all items that are currently in the dictionary.
1781 ## Function type <a id="scriptfunction-type"></a>
1783 Inherits methods from the [Object type](18-library-reference.md#object-type).
1785 ### Function#call <a id="scriptfunction-call"></a>
1790 function call(thisArg, ...);
1793 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1794 scope for the function. All other arguments are passed directly to the function.
1799 function set_x(val) {
1805 set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
1808 ### Function#callv <a id="scriptfunction-callv"></a>
1813 function callv(thisArg, args);
1816 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1817 scope for the function. The items in the `args` array are passed to the function as individual arguments.
1822 function set_x(val) {
1830 set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
1833 ## DateTime type <a id="datetime-type"></a>
1835 Inherits methods from the [Object type](18-library-reference.md#object-type).
1837 ### DateTime constructor <a id="datetime-ctor"></a>
1843 function DateTime(unixTimestamp)
1844 function DateTime(year, month, day)
1845 function DateTime(year, month, day, hours, minutes, seconds)
1848 Constructs a new DateTime object. When no arguments are specified for the constructor a new
1849 DateTime object representing the current time is created.
1854 var d1 = DateTime() /* current time */
1855 var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
1858 ### DateTime arithmetic <a id="datetime-arithmetic"></a>
1860 Subtracting two DateTime objects yields the interval between them, in seconds.
1865 var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */
1868 Subtracting a number from a DateTime object yields a new DateTime object that is further in the past:
1873 var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */
1876 Adding a number to a DateTime object yields a new DateTime object that is in the future:
1881 var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */
1884 ### DateTime#format <a id="datetime-format"></a>
1889 function format(fmt)
1892 Returns a string representation for the DateTime object using the specified format string.
1893 The format string may contain format conversion placeholders as specified in strftime(3).
1898 var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
1901 ### DateTime#to_string <a id="datetime-tostring"></a>
1906 function to_string()
1909 Returns a string representation for the DateTime object. Uses a suitable default format.
1914 var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */