diff --git a/documentation/functions/global/require.md b/documentation/functions/global/require.md index 07e93fba6..7e7482e24 100644 --- a/documentation/functions/global/require.md +++ b/documentation/functions/global/require.md @@ -8,17 +8,38 @@ ts_ignore: true `require(...)` loads the specified JavaScript or JSON file, allowing to split your configuration across multiple files. +A better name for this function might be "include". + If the supplied `path` string ends with `.js`, the file is interpreted as JavaScript code, almost as though its contents had been included in the currently-executing file. If the path string ends with `.json`, `require()` returns the `JSON.parse()` of the file's contents. -If the path string begins with a `.`, it is interpreted relative to +If the path string begins with a `./`, it is interpreted relative to the currently-loading file (which may not be the file where the -`require()` statement is, if called within a function), otherwise it +`require()` statement is, if called within a function). Otherwise it is interpreted relative to the program's working directory at the time of the call. +### Example 1: Simple + +In this example, we separate our macros in one file, and put groups of domains +in 3 other files. The result is a cleaner separation of code vs. domains. + +{% code title="dnsconfig.js" %} +```javascript +require("lib/macros.json"); + +require("domains/main.json"); +require("domains/parked.json"); +require("domains/otherstuff.json"); +``` +{% endcode %} + +### Example 2: Complex + +Here's a more complex example: + {% code title="dnsconfig.js" %} ```javascript require("kubernetes/clusters.js"); @@ -60,7 +81,9 @@ function includeK8Sdev() { ``` {% endcode %} -You can also use it to require JSON files and initialize variables with it: +### Example 3: JSON + +Requiring JSON files initializes variables: {% code title="dnsconfig.js" %} ```javascript @@ -83,16 +106,13 @@ for (var domain in domains) { ``` {% endcode %} -# Future +# Notes -It might be better to rename the function to something like -`include()` instead, (leaving `require` as a deprecated alias) because -by analogy it is *much* closer to PHP's `include()` function than it -is to node's `require()`. After all, the reason node.js calls it -"require" is because it's a declarative statement saying the file is -needed, and so should be loaded if it hasn't already been loaded. +`require()` is *much* closer to PHP's `include()` function than it +is to node's `require()`. +Node's `require()` only includes a file once. In contrast, DNSControl's `require()` is actually an imperative command to -load the file and execute the code or parse the data from it. (So if -two files both `require("./tools.js")`, for example, then it will be -loaded twice, whereas in node.js it would only be loaded once.) +load the file and execute the code or parse the data from it. For example if +two files both `require("./tools.js")`, then it will be +loaded twice, whereas in node.js it would only be loaded once. diff --git a/documentation/functions/global/require_glob.md b/documentation/functions/global/require_glob.md index da7b4cd77..d56cad985 100644 --- a/documentation/functions/global/require_glob.md +++ b/documentation/functions/global/require_glob.md @@ -8,7 +8,7 @@ parameter_types: recursive: boolean --- -`require_glob()` can recursively load `.js` files, optionally non-recursive as well. +`require_glob()` recursively loads `.js` files that match a glob (wildcard). The recursion can be disabled. Possible parameters are: @@ -31,8 +31,13 @@ require_glob("./domains/", false); ``` {% endcode %} -One more important thing to note: `require_glob()` is as smart as `require()` is. It loads files always relative to the JavaScript -file where it's being executed in. Let's go with an example, as it describes it better: +# Comparison to require() + +`require_glob()` and `require()` both use the same rules for determining which directory path is +relative to. + +This will load files being present underneath `./domains/user1/` and **NOT** at below `./domains/`, as `require_glob()` +is called in the subfolder `domains/`. {% code title="dnsconfig.js" %} ```javascript @@ -45,6 +50,3 @@ require("domains/index.js"); require_glob("./user1/"); ``` {% endcode %} - -This will now load files being present underneath `./domains/user1/` and **NOT** at below `./domains/`, as `require_glob()` -is called in the subfolder `domains/`.