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:
@ -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.
|
||||||
|
@ -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/`.
|
|
||||||
|
Reference in New Issue
Block a user