From 01b6669dfa8b6ed2dce217f2850b46291387b7e1 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Thu, 12 Mar 2020 12:41:00 -0400 Subject: [PATCH] Documentation: Clarify require() name and usage (#690) * Clarify require() doc * fixup! Co-authored-by: Tom Limoncelli --- docs/_functions/global/require.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/docs/_functions/global/require.md b/docs/_functions/global/require.md index c431d29fb..fa3c9c48d 100644 --- a/docs/_functions/global/require.md +++ b/docs/_functions/global/require.md @@ -4,9 +4,19 @@ parameters: - path --- -`require(...)` behaves similarly to its equivalent in node.js. You can use it -to split your configuration across multiple files. If the path starts with a -`.`, it is calculated relative to the current file. For example: +`require(...)` loads the specified JavaScript or JSON file, allowing +to split your configuration across multiple files. + +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 +the currently-loading file (which may not be the file where the +`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. {% include startExample.html %} {% highlight js %} @@ -76,3 +86,17 @@ for (var domain in domains) { } {%endhighlight} {% include endExample.html %} + +# Future + +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. + +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.)