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 ### dirname <a id="global-functions-dirname"></a>
432 function dirname(path)
434 Returns the directory portion of the specified path.
439 Icinga 2 (version: v2.7.0)
440 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
443 "/etc/icinga2/scripts"
445 ### basename <a id="global-functions-basename"></a>
449 function basename(path)
451 Returns the filename portion of the specified path.
456 Icinga 2 (version: v2.7.0)
457 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
459 <2> => basename(path)
460 "xmpp-notification.pl"
462 ### path\_exists <a id="global-functions-path-exists"></a>
466 function path_exists(path)
468 Returns true if the specified path exists, false otherwise.
473 Icinga 2 (version: v2.7.0)
474 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
476 <2> => path_exists(path)
479 ### glob <a id="global-functions-glob"></a>
483 function glob(pathSpec, type)
485 Returns an array containing all paths which match the
488 The `type` argument is optional and specifies which types
489 of paths are matched. This can be a combination of the `GlobFile`
490 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
493 Icinga 2 (version: v2.7.0)
494 <1> => var pathSpec = "/etc/icinga2/conf.d/*.conf"
496 <2> => glob(pathSpec)
497 [ "/etc/icinga2/conf.d/app.conf", "/etc/icinga2/conf.d/commands.conf", ... ]
499 ### glob\_recursive <a id="global-functions-glob-recursive"></a>
503 function glob_recursive(path, pattern, type)
505 Recursively descends into the specified directory and returns an array containing
506 all paths which match the `pattern` argument.
508 The `type` argument is optional and specifies which types
509 of paths are matched. This can be a combination of the `GlobFile`
510 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
513 Icinga 2 (version: v2.7.0)
514 <1> => var path = "/etc/icinga2/zones.d/"
516 <2> => var pattern = "*.conf"
518 <3> => glob_recursive(path, pattern)
519 [ "/etc/icinga2/zones.d/global-templates/templates.conf", "/etc/icinga2/zones.d/master/hosts.conf", ... ]
521 ### escape_shell_arg <a id="global-functions-escape_shell_arg"></a>
525 function escape_shell_arg(text)
527 Escapes a string for use as a single shell argument.
532 Icinga 2 (version: v2.7.0)
533 <1> => escape_shell_arg("'$host.name$' '$service.name$'")
534 "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
536 ### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a>
540 function escape_shell_cmd(text)
542 Escapes shell meta characters in a string.
547 Icinga 2 (version: v2.7.0)
548 <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
549 "/bin/echo 'shell test' \\$ENV"
551 ### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a>
555 function escape_create_process_arg(text)
557 Escapes a string for use as an argument for CreateProcess(). Windows only.
559 ### sleep <a id="global-functions-sleep"></a>
563 function sleep(interval)
565 Sleeps for the specified amount of time (in seconds).
568 ## Scoped Functions <a id="scoped-functions"></a>
570 This chapter describes functions which are only available
573 ### macro <a id="scoped-functions-macro"></a>
578 function macro("$macro_name$")
581 The `macro` function can be used to resolve [runtime macro](03-monitoring-basics.md#runtime-macros)
582 strings into their values.
583 The returned value depends on the attribute value which is resolved
584 from the specified runtime macro.
586 This function is only available in runtime evaluated functions, e.g.
587 for [custom attributes](03-monitoring-basics.md#custom-attributes-functions) which
588 use the [abbreviated lambda syntax](17-language-reference.md#nullary-lambdas).
590 This example sets the `snmp_address` custom attribute
591 based on `$address$` and `$address6`.
594 vars.snmp_address = {{
595 var addr_v4 = macro("$address$")
596 var addr_v6 = macro("$address6$")
601 return "udp6:[" + addr_v6 + "]"
606 More reference examples are available inside the [Icinga Template Library](10-icinga-template-library.md#icinga-template-library)
607 and the [object accessors chapter](08-advanced-topics.md#access-object-attributes-at-runtime).
609 ## Object Accessor Functions <a id="object-accessor-functions"></a>
611 These functions can be used to retrieve a reference to another object by name.
613 ### get_check_command <a id="objref-get_check_command"></a>
617 function get_check_command(name);
619 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
621 ### get_event_command <a id="objref-get_event_command"></a>
625 function get_event_command(name);
627 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
629 ### get_notification_command <a id="objref-get_notification_command"></a>
633 function get_notification_command(name);
635 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
637 ### get_host <a id="objref-get_host"></a>
641 function get_host(host_name);
643 Returns the Host object with the specified name, or `null` if no such Host object exists.
646 ### get_service <a id="objref-get_service"></a>
650 function get_service(host_name, service_name);
651 function get_service(host, service_name);
653 Returns the Service object with the specified host name or object and service name pair,
654 or `null` if no such Service object exists.
656 Example in the [debug console](11-cli-commands.md#cli-command-console)
657 which fetches the `disk` service object from the current Icinga 2 node:
660 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
661 Icinga 2 (version: v2.7.0)
663 <1> => get_service(NodeName, "disk")
664 <2> => get_service(NodeName, "disk").__name
665 "icinga2-master1.localdomain!disk"
667 <3> => get_service(get_host(NodeName), "disk").__name
668 "icinga2-master1.localdomain!disk"
671 ### get_services <a id="objref-get_services"></a>
675 function get_services(host_name);
676 function get_services(host);
678 Returns an [array](17-language-reference.md#array) of service objects for the specified host name or object,
679 or `null` if no such host object exists.
681 Example in the [debug console](11-cli-commands.md#cli-command-console)
682 which fetches all service objects from the current Icinga 2 node:
685 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
686 Icinga 2 (version: v2.7.0)
688 <1> => get_services(NodeName).map(s => s.name)
689 [ "disk", "disk /", "http", "icinga", "load", "ping4", "ping6", "procs", "ssh", "users" ]
692 Note: [map](18-library-reference.md#array-map) takes a [lambda function](17-language-reference.md#lambdas) as argument. In this example
693 we only want to collect and print the `name` attribute with `s => s.name`.
695 This works in a similar fashion for a host object where you can extract all service states
696 in using the [map](18-library-reference.md#array-map) functionality:
699 <2> => get_services(get_host(NodeName)).map(s => s.state)
700 [ 2.000000, 2.000000, 2.000000, 0.000000, 0.000000, 0.000000, 2.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000 ]
703 ### get_user <a id="objref-get_user"></a>
707 function get_user(name);
709 Returns the User object with the specified name, or `null` if no such User object exists.
711 ### get_host_group <a id="objref-get_host_group"></a>
715 function get_host_group(name);
717 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
720 ### get_service_group <a id="objref-get_service_group"></a>
724 function get_service_group(name);
726 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
728 ### get_user_group <a id="objref-get_user_group"></a>
732 function get_user_group(name);
734 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
737 ### get_time_period <a id="objref-get_time_period"></a>
741 function get_time_period(name);
743 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
746 ### get_object <a id="objref-get_object"></a>
750 function get_object(type, name);
752 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
756 ### get_objects <a id="objref-get_objects"></a>
760 function get_objects(type);
762 Returns an array of objects whose type matches the specified type. `type` must refer
766 ## Math object <a id="math-object"></a>
768 The global `Math` object can be used to access a number of mathematical constants
771 ### Math.E <a id="math-e"></a>
775 ### Math.LN2 <a id="math-ln2"></a>
777 Natural logarithm of 2.
779 ### Math.LN10 <a id="math-ln10"></a>
781 Natural logarithm of 10.
783 ### Math.LOG2E <a id="math-log2e"></a>
785 Base 2 logarithm of E.
787 ### Math.PI <a id="math-pi"></a>
789 The mathematical constant Pi.
791 ### Math.SQRT1_2 <a id="math-sqrt1_2"></a>
795 ### Math.SQRT2 <a id="math-sqrt2"></a>
799 ### Math.abs <a id="math-abs"></a>
805 Returns the absolute value of `x`.
807 ### Math.acos <a id="math-acos"></a>
813 Returns the arccosine of `x`.
815 ### Math.asin <a id="math-asin"></a>
821 Returns the arcsine of `x`.
823 ### Math.atan <a id="math-atan"></a>
829 Returns the arctangent of `x`.
831 ### Math.atan2 <a id="math-atan2"></a>
835 function atan2(y, x);
837 Returns the arctangent of the quotient of `y` and `x`.
839 ### Math.ceil <a id="math-ceil"></a>
845 Returns the smallest integer value not less than `x`.
847 ### Math.cos <a id="math-cos"></a>
853 Returns the cosine of `x`.
855 ### Math.exp <a id="math-exp"></a>
861 Returns E raised to the `x`th power.
863 ### Math.floor <a id="math-floor"></a>
869 Returns the largest integer value not greater than `x`.
871 ### Math.isinf <a id="math-isinf"></a>
877 Returns whether `x` is infinite.
879 ### Math.isnan <a id="math-isnan"></a>
885 Returns whether `x` is NaN (not-a-number).
887 ### Math.log <a id="math-log"></a>
893 Returns the natural logarithm of `x`.
895 ### Math.max <a id="math-max"></a>
901 Returns the largest argument. A variable number of arguments can be specified.
902 If no arguments are given, -Infinity is returned.
904 ### Math.min <a id="math-min"></a>
910 Returns the smallest argument. A variable number of arguments can be specified.
911 If no arguments are given, +Infinity is returned.
913 ### Math.pow <a id="math-pow"></a>
919 Returns `x` raised to the `y`th power.
921 ### Math.random <a id="math-random"></a>
927 Returns a pseudo-random number between 0 and 1.
929 ### Math.round <a id="math-round"></a>
935 Returns `x` rounded to the nearest integer value.
937 ### Math.sign <a id="math-sign"></a>
943 Returns -1 if `x` is negative, 1 if `x` is positive
946 ### Math.sin <a id="math-sin"></a>
952 Returns the sine of `x`.
954 ### Math.sqrt <a id="math-sqrt"></a>
960 Returns the square root of `x`.
962 ### Math.tan <a id="math-tan"></a>
968 Returns the tangent of `x`.
970 ## Json object <a id="json-object"></a>
972 The global `Json` object can be used to encode and decode JSON.
974 ### Json.encode <a id="json-encode"></a>
980 Encodes an arbitrary value into JSON.
982 ### Json.decode <a id="json-decode"></a>
988 Decodes a JSON string.
990 ## Number type <a id="number-type"></a>
992 ### Number#to_string <a id="number-to_string"></a>
996 function to_string();
998 The `to_string` method returns a string representation of the number.
1003 example.to_string() /* Returns "7" */
1005 ## Boolean type <a id="boolean-type"></a>
1007 ### Boolean#to_string <a id="boolean-to_string"></a>
1011 function to_string();
1013 The `to_string` method returns a string representation of the boolean value.
1018 example.to_string() /* Returns "true" */
1020 ## String type <a id="string-type"></a>
1022 ### String#find <a id="string-find"></a>
1026 function find(str, start);
1028 Returns the zero-based index at which the string `str` was found in the string. If the string
1029 was not found, -1 is returned. `start` specifies the zero-based index at which `find` should
1030 start looking for the string (defaults to 0 when not specified).
1034 "Hello World".find("World") /* Returns 6 */
1036 ### String#contains <a id="string-contains"></a>
1040 function contains(str);
1042 Returns `true` if the string `str` was found in the string. If the string
1043 was not found, `false` is returned. Use [find](18-library-reference.md#string-find)
1044 for getting the index instead.
1048 "Hello World".contains("World") /* Returns true */
1050 ### String#len <a id="string-len"></a>
1056 Returns the length of the string in bytes. Note that depending on the encoding type of the string
1057 this is not necessarily the number of characters.
1061 "Hello World".len() /* Returns 11 */
1063 ### String#lower <a id="string-lower"></a>
1069 Returns a copy of the string with all of its characters converted to lower-case.
1073 "Hello World".lower() /* Returns "hello world" */
1075 ### String#upper <a id="string-upper"></a>
1081 Returns a copy of the string with all of its characters converted to upper-case.
1085 "Hello World".upper() /* Returns "HELLO WORLD" */
1087 ### String#replace <a id="string-replace"></a>
1091 function replace(search, replacement);
1093 Returns a copy of the string with all occurences of the string specified in `search` replaced
1094 with the string specified in `replacement`.
1096 ### String#split <a id="string-split"></a>
1100 function split(delimiters);
1102 Splits a string into individual parts and returns them as an array. The `delimiters` argument
1103 specifies the characters which should be used as delimiters between parts.
1107 "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
1109 ### String#substr <a id="string-substr"></a>
1113 function substr(start, len);
1115 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
1116 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
1120 "Hello World".substr(6) /* Returns "World" */
1122 ### String#to_string <a id="string-to_string"></a>
1126 function to_string();
1128 Returns a copy of the string.
1130 ### String#reverse <a id="string-reverse"></a>
1136 Returns a copy of the string in reverse order.
1138 ### String#trim <a id="string-trim"></a>
1144 Removes trailing whitespaces and returns the string.
1146 ## Object type <a id="object-type"></a>
1148 This is the base type for all types in the Icinga application.
1150 ### Object#clone <a id="object-clone"></a>
1156 Returns a copy of the object. Note that for object elements which are
1157 reference values (e.g. objects such as arrays or dictionaries) the entire
1158 object is recursively copied.
1160 ### Object#to_string <a id="object-to-string"></a>
1164 function to_string();
1166 Returns a string representation for the object. Unless overridden this returns a string
1167 of the format "Object of type '<typename>'" where <typename> is the name of the
1172 [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
1174 ### Object#type <a id="object-type-field"></a>
1180 Returns the object's type name. This attribute is read-only.
1184 get_host("localhost").type /* Returns "Host" */
1186 ## Type type <a id="type-type"></a>
1188 Inherits methods from the [Object type](18-library-reference.md#object-type).
1190 The `Type` type provides information about the underlying type of an object or scalar value.
1192 All types are registered as global variables. For example, in order to obtain a reference to the `String` type the global variable `String` can be used.
1194 ### Type#base <a id="type-base"></a>
1200 Returns a reference to the type's base type. This attribute is read-only.
1204 Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
1206 ### Type#name <a id="type-name"></a>
1212 Returns the name of the type.
1214 ### Type#prototype <a id="type-prototype"></a>
1220 Returns the prototype object for the type. When an attribute is accessed on an object that doesn't exist the prototype object is checked to see if an attribute with the requested name exists. If it does, the attribute's value is returned.
1222 The prototype functionality is used to implement methods.
1226 3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
1228 ## Array type <a id="array-type"></a>
1230 Inherits methods from the [Object type](18-library-reference.md#object-type).
1232 ### Array#add <a id="array-add"></a>
1236 function add(value);
1238 Adds a new value after the last element in the array.
1240 ### Array#clear <a id="array-clear"></a>
1246 Removes all elements from the array.
1248 ### Array#shallow_clone <a id="array-shallow-clone"></a>
1250 function shallow_clone();
1252 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
1253 as arrays and dictionaries) only the references are copied.
1255 ### Array#contains <a id="array-contains"></a>
1259 function contains(value);
1261 Returns true if the array contains the specified value, false otherwise.
1263 ### Array#len <a id="array-len"></a>
1269 Returns the number of elements contained in the array.
1271 ### Array#remove <a id="array-remove"></a>
1275 function remove(index);
1277 Removes the element at the specified zero-based index.
1279 ### Array#set <a id="array-set"></a>
1283 function set(index, value);
1285 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
1286 which already exists in the array.
1288 ### Array#get <a id="array-get"></a>
1292 function get(index);
1294 Retrieves the element at the specified zero-based index.
1296 ### Array#sort <a id="array-sort"></a>
1300 function sort(less_cmp);
1302 Returns a copy of the array where all items are sorted. The items are
1303 compared using the `<` (less-than) operator. A custom comparator function
1304 can be specified with the `less_cmp` argument.
1306 ### Array#join <a id="array-join"></a>
1310 function join(separator);
1312 Joins all elements of the array using the specified separator.
1314 ### Array#reverse <a id="array-reverse"></a>
1320 Returns a new array with all elements of the current array in reverse order.
1322 ### Array#map <a id="array-map"></a>
1328 Calls `func(element)` for each of the elements in the array and returns
1329 a new array containing the return values of these function calls.
1331 ### Array#reduce <a id="array-reduce"></a>
1335 function reduce(func);
1337 Reduces the elements of the array into a single value by calling the provided
1338 function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
1339 or results from previous function calls.
1341 ### Array#filter <a id="array-filter"></a>
1345 function filter(func);
1347 Returns a copy of the array containing only the elements for which `func(element)`
1350 ### Array#any <a id="array-any"></a>
1356 Returns true if the array contains at least one element for which `func(element)`
1357 is true, false otherwise.
1359 ### Array#all <a id="array-all"></a>
1365 Returns true if the array contains only elements for which `func(element)`
1366 is true, false otherwise.
1368 ### Array#unique <a id="array-unique"></a>
1374 Returns a copy of the array with all duplicate elements removed. The original order
1375 of the array is not preserved.
1377 ## Dictionary type <a id="dictionary-type"></a>
1379 Inherits methods from the [Object type](18-library-reference.md#object-type).
1381 ### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
1385 function shallow_clone();
1387 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
1388 as arrays and dictionaries) only the references are copied.
1390 ### Dictionary#contains <a id="dictionary-contains"></a>
1394 function contains(key);
1396 Returns true if a dictionary item with the specified `key` exists, false otherwise.
1398 ### Dictionary#len <a id="dictionary-len"></a>
1404 Returns the number of items contained in the dictionary.
1406 ### Dictionary#remove <a id="dictionary-remove"></a>
1410 function remove(key);
1412 Removes the item with the specified `key`. Trying to remove an item which does not exist
1415 ### Dictionary#set <a id="dictionary-set"></a>
1419 function set(key, value);
1421 Creates or updates an item with the specified `key` and `value`.
1423 ### Dictionary#get <a id="dictionary-get"></a>
1429 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
1432 ### Dictionary#keys <a id="dictionary-keys"></a>
1438 Returns a list of keys for all items that are currently in the dictionary.
1440 ### Dictionary#values <a id="dictionary-values"></a>
1446 Returns a list of values for all items that are currently in the dictionary.
1448 ## Function type <a id="scriptfunction-type"></a>
1450 Inherits methods from the [Object type](18-library-reference.md#object-type).
1452 ### Function#call <a id="scriptfunction-call"></a>
1456 function call(thisArg, ...);
1458 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1459 scope for the function. All other arguments are passed directly to the function.
1463 function set_x(val) {
1469 set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
1471 ### Function#callv <a id="scriptfunction-callv"></a>
1475 function callv(thisArg, args);
1477 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1478 scope for the function. The items in the `args` array are passed to the function as individual arguments.
1482 function set_x(val) {
1490 set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
1492 ## DateTime type <a id="datetime-type"></a>
1494 Inherits methods from the [Object type](18-library-reference.md#object-type).
1496 ### DateTime constructor <a id="datetime-ctor"></a>
1501 function DateTime(unixTimestamp)
1502 function DateTime(year, month, day)
1503 function DateTime(year, month, day, hours, minutes, seconds)
1505 Constructs a new DateTime object. When no arguments are specified for the constructor a new
1506 DateTime object representing the current time is created.
1510 var d1 = DateTime() /* current time */
1511 var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
1513 ### DateTime arithmetic <a id="datetime-arithmetic"></a>
1515 Subtracting two DateTime objects yields the interval between them, in seconds.
1519 var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */
1521 Subtracting a number from a DateTime object yields a new DateTime object that is further in the past:
1525 var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */
1527 Adding a number to a DateTime object yields a new DateTime object that is in the future:
1531 var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */
1533 ### DateTime#format <a id="datetime-format"></a>
1537 function format(fmt)
1539 Returns a string representation for the DateTime object using the specified format string.
1540 The format string may contain format conversion placeholders as specified in strftime(3).
1544 var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
1546 ### DateTime#to_string <a id="datetime-tostring"></a>
1550 function to_string()
1552 Returns a string representation for the DateTime object. Uses a suitable default format.
1556 var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */