1
0
mirror of https://github.com/StackExchange/dnscontrol.git synced 2024-05-11 05:55:12 +00:00

Improve require() docs (#2553)

This commit is contained in:
Tom Limoncelli
2023-09-14 10:25:45 -04:00
committed by GitHub
parent af91e37043
commit 5b95f29082
2 changed files with 41 additions and 19 deletions

View File

@ -8,17 +8,38 @@ ts_ignore: true
`require(...)` loads the specified JavaScript or JSON file, allowing `require(...)` loads the specified JavaScript or JSON file, allowing
to split your configuration across multiple files. 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 If the supplied `path` string ends with `.js`, the file is interpreted
as JavaScript code, almost as though its contents had been included in as JavaScript code, almost as though its contents had been included in
the currently-executing file. If the path string ends with `.json`, the currently-executing file. If the path string ends with `.json`,
`require()` returns the `JSON.parse()` of the file's contents. `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 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 is interpreted relative to the program's working directory at the time
of the call. 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" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
require("kubernetes/clusters.js"); require("kubernetes/clusters.js");
@ -60,7 +81,9 @@ function includeK8Sdev() {
``` ```
{% endcode %} {% 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" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
@ -83,16 +106,13 @@ for (var domain in domains) {
``` ```
{% endcode %} {% endcode %}
# Future # Notes
It might be better to rename the function to something like `require()` is *much* closer to PHP's `include()` function than it
`include()` instead, (leaving `require` as a deprecated alias) because is to node's `require()`.
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.
Node's `require()` only includes a file once.
In contrast, DNSControl's `require()` is actually an imperative command to 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 load the file and execute the code or parse the data from it. For example if
two files both `require("./tools.js")`, for example, then it will be two files both `require("./tools.js")`, then it will be
loaded twice, whereas in node.js it would only be loaded once.) loaded twice, whereas in node.js it would only be loaded once.

View File

@ -8,7 +8,7 @@ parameter_types:
recursive: boolean 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: Possible parameters are:
@ -31,8 +31,13 @@ require_glob("./domains/", false);
``` ```
{% endcode %} {% endcode %}
One more important thing to note: `require_glob()` is as smart as `require()` is. It loads files always relative to the JavaScript # Comparison to require()
file where it's being executed in. Let's go with an example, as it describes it better:
`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" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
@ -45,6 +50,3 @@ require("domains/index.js");
require_glob("./user1/"); require_glob("./user1/");
``` ```
{% endcode %} {% 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/`.