8000 issue #1573: Extending AQL clarifications · doublerebel/arangodb@406ac2e · GitHub
[go: up one dir, main page]
Skip to content

Commit 406ac2e

Browse files
jsteemannjsteemann
committed
issue arangodb#1573: Extending AQL clarifications
1 parent 9f6b7a6 commit 406ac2e

File tree

2 files changed

+54
-18
lines changed

2 files changed

+54
-18
lines changed

‎Documentation/Books/Users/AqlExtending/Conventions.mdpp

Lines changed: 40 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ will fail.
2525
!SECTION Variables and side effects
2626

2727
User functions can take any number of input arguments and should
28-
provide one result. They should be kept purely functional and thus free of
29-
side effects and state, and state modification.
28+
provide one result via a `return` statement. User functions should be kept
29+
purely functional and thus free of side effects and state, and state modification.
3030

3131
Modification of global variables is unsupported, as is changing
3232
the data of any collection from inside an AQL user function.
@@ -56,8 +56,8 @@ function (values) {
5656
}
5757
```
5858

59-
The above function can be made free of side effects by using the `var`
60-
keyword, so the variables become function-local variables:
59+
The above function can be made free of side effects by using the `var` or
60+
`let` keywords, so the variables become function-local variables:
6161

6262
```js
6363
function (values) {
@@ -71,14 +71,48 @@ function (values) {
7171
}
7272
```
7373

74+
!SECTION Input parameters
75+
76+
In order to return a result, a user function should use a `return` instruction
77+
rather than modifying its input parameters.
78+
79+
AQL user functions are allowed to modify their input parameters for input
80+
parameters that are null, boolean, numeric or string values. Modifying these
81+
input parameter types inside a user function should be free of side effects.
82+
However, user functions should not modify input parameters if the parameters are
83+
arrays or objects and as such passed by reference, as that may modify variables
84+
and state outside of the user function itself.
85+
7486
!SECTION Return values
7587

7688
User functions must only return primitive types (i.e. *null*, boolean
77-
values, numeric values, string values) or aggregate types (lists or
78-
documents) composed of these types.
89+
values, numeric values, string values) or aggregate types (arrays or
90+
objects) composed of these types.
7991
Returning any other JavaScript object type from a user function may lead
8092
to undefined behavior and should be avoided.
8193

94+
!SECTION Enforcing strict mode
95+
96+
By default, any user function code will not be executed in *strict mode* or
97+
*strong mode*. In order to make a user function function being run in strict
98+
mode, use `use strict` explicitly inside the user function, e.g.:
99+
100+
```js
101+
function (values) {
102+
"use strict"
103+
104+
for (var i = 0; i < values.length; ++i) {
105+
var name = values[i];
106+
if (name === "foo") {
107+
return i;
108+
}
109+
}
110+
return null;
111+
}
112+
```
113+
114+
Any violation of the strict mode will trigger a runtime error.
115+
82116
!SECTION Miscellaneous
83117

84118
Internally, user functions are stored in a system collection named

‎Documentation/Books/Users/AqlExtending/Functions.mdpp

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,8 @@ var 10000 aqlfunctions = require("@arangodb/aql/functions");
1010
To register a function, the fully qualified function name plus the
1111
function code must be specified.
1212

13-
!SUBSECTION Register
14-
<!-- js/common/modules/@arangodb/aql/functions.js -->
15-
13+
!SUBSECTION Registering an AQL user function
1614

17-
register an AQL user function
1815
`aqlfunctions.register(name, code, isDeterministic)`
1916

2017
Registers an AQL user function, identified by a fully qualified function
@@ -51,12 +48,21 @@ when it detects syntactially invalid function code.
5148
});
5249
```
5350

51+
The function code will not be executed in *strict mode* or *strong mode* by
52+
default. In order to make a user function function being run in strict mode, use
53+
`use strict` explicitly, e.g.:
54+
55+
```js
56+
require("@arangodb/aql/functions").register("myfunctions::temperature::celsiustofahrenheit",
57+
function (celsius) {
58+
"use strict";
59+
return celsius * 1.8 + 32;
60+
});
61+
```
5462

55-
!SUBSECTION Unregister
56-
<!-- js/common/modules/@arangodb/aql/functions.js -->
5763

64+
!SUBSECTION Deleting an existing AQL user function
5865

59-
delete an existing AQL user function
6066
`aqlfunctions.unregister(name)`
6167

6268
Unregisters an existing AQL user function, identified by the fully qualified
@@ -97,11 +103,8 @@ This will return the number of functions unregistered.
97103
```
98104

99105

100-
!SUBSECTION To Array
101-
<!-- js/common/modules/@arangodb/aql/functions.js -->
102-
106+
!SUBSECTION Listing all AQL user functions
103107

104-
list all AQL user functions
105108
`aqlfunctions.toArray()`
106109

107110
Returns all previously registered AQL user functions, with their fully
@@ -115,7 +118,6 @@ by specifying a group prefix:
115118

116119
**Examples**
117120

118-
119121
To list all available user functions:
120122

121123
```js

0 commit comments

Comments
 (0)
0