Add D_EXTEND (#885) (thanks to @ad8-bdl!)

* fix get-zones code block indentation

* extend D_EXTEND to handle subdomains

* fix targets: make absolute incl. subdomain where necessary

* clarify subdomain target test (not IP && not fqdn)

* Add parse_tests for D and D_EXTEND

* _getDomainObject: examine all domains

* human readable form

* consistent test IP addresses

* Improve docs and formatting

* propagate subdomain to canonicalisation

* en-US spelling

* rm extraneous console.log

* ignore subdomain for CF_REDIRECT

* clarify D_EXTEND doc re. CF_REDIRECT

* rm extraneous linebreak

* _getDomainObject: examine all domains

* human readable form

* consistent test IP addresses

* propagate subdomain to canonicalisation

* en-US spelling

* rm extraneous console.log

* ignore subdomain for CF_REDIRECT

* clarify D_EXTEND doc re. CF_REDIRECT

* rm extraneous linebreak

* GANDI_V5: Use github.com/go-gandi/go-gandi, not github.com/tiramiseb/go-gandi (#883)

* DOCUMENTATION: Fix error in CNAME.md (#877)

The current example `CNAME("def", "test.subdomain"), // def.example.com -> test.subdomain.example.com` is invalid (correctly raises a validation error, "ERROR: in CNAME def.example.com: target (test.subdomain) must end with a (.)")

* typos, fmt; example syntax fixes and real output

* formatting; re-add lost comment

* RecordConfig subdomain should be nullable

* providers/cscglobal/api.go: Fix fmt string

* More tests and docs

* go generate

Co-authored-by: Ben L <47653825+ad8-bdl@users.noreply.github.com>

docs/_functions/global/D_EXTEND.md

@@ -5,26 +5,83 @@ parameters:
   - modifiers...
 ---
 
-`D_EXTEND` adds records (and metadata) to a domain. The domain must have previously been defined by `D()`. `D_EXTEND()` behaves the same as `D()` in all other ways: The first argument is the domain name. See the documentation of `D` for further details.
+`D_EXTEND` adds records (and metadata) to a domain previously defined
+by `D()`. It can also be used to add subdomain records (and metadata)
+to a previously defined domain.
+
+The first argument is a domain name. If it exactly matches a
+previously defined domain, `D_EXTEND()` behaves the same as `D()`,
+simply adding records as if they had been specified in the original
+`D()`.
+
+If the domain name does not match an existing domain, but could be a
+(non-delegated) subdomain of an existing domain, the new records (and
+metadata) are added with the subdomain part appended to all record
+names (labels), and targets (as appropriate). See the examples below.
+
+Matching the domain name to previously-defined domains is done using a
+`longest match` algorithm.  If `domain.tld` and `sub.domain.tld` are
+defined as separate domains via separate `D()` statements, then
+`D_EXTEND('sub.sub.domain.tld', ...)` would match `sub.domain.tld`,
+not `domain.tld`.
+
+Some operators only act on an apex domain (e.g.
+`CF_REDIRECT` and `CF_TEMP_REDIRECT`). Using them 
+in a `D_EXTEND` subdomain may not be what you expect.
 
 Example:
+
 {% include startExample.html %}
 {% highlight js %}
-D('domain.tld', REG, DnsProvider(DNS),
-  A('@', "127.0.0.1")
-)
-D_EXTEND('domain.tld',
-  A('@', "127.0.0.2")
-)
+D("domain.tld", REG, DnsProvider(DNS),
+  A("@", "127.0.0.1"), // domain.tld
+  A("www", "127.0.0.2"), // www.domain.tld
+  CNAME("a", "b") // a.domain.tld -> b.domain.tld
+);
+D_EXTEND("domain.tld",
+  A("aaa", "127.0.0.3"), // aaa.domain.tld
+  CNAME("c", "d") // c.domain.tld -> d.domain.tld
+);
+D_EXTEND("sub.domain.tld",
+  A("bbb", "127.0.0.4"), // bbb.sub.domain.tld
+  A("ccc", "127.0.0.5"), // ccc.sub.domain.tld
+  CNAME("e", "f") // e.sub.domain.tld -> f.sub.domain.tld
+);
+D_EXTEND("sub.sub.domain.tld",
+  A("ddd", "127.0.0.6"), // ddd.sub.sub.domain.tld
+  CNAME("g", "h") // g.sub.sub.domain.tld -> h.sub.sub.domain.tld
+);
+D_EXTEND("sub.domain.tld",
+  A("@", "127.0.0.7"), // sub.domain.tld
+  CNAME("i", "j") // i.sub.domain.tld -> j.sub.domain.tld
+);
 {%endhighlight%}
 
-This will end up in following modifications:
+This will end up in the following modifications:
 ```
 ******************** Domain: domain.tld
------ Getting nameservers from: registrar
------ DNS Provider: registrar...3 corrections
-#1: CREATE A domain.tld 127.0.0.1 ttl=43200
-#2: CREATE A domain.tld 127.0.0.2 ttl=43200
-#3: REFRESH zone domain.tld
+----- Getting nameservers from: cloudflare
+----- DNS Provider: cloudflare...7 corrections
+#1: CREATE A aaa.domain.tld 127.0.0.3
+#2: CREATE A bbb.sub.domain.tld 127.0.0.4
+#3: CREATE A ccc.sub.domain.tld 127.0.0.5
+#4: CREATE A ddd.sub.sub.domain.tld 127.0.0.6
+#5: CREATE A sub.domain.tld 127.0.0.7
+#6: CREATE A www.domain.tld 127.0.0.2
+#7: CREATE A domain.tld 127.0.0.1
+#8: CREATE CNAME a.domain.tld b.domain.tld.
+#9: CREATE CNAME c.domain.tld d.domain.tld.
+#10: CREATE CNAME e.sub.domain.tld f.sub.domain.tld.
+#11: CREATE CNAME g.sub.sub.domain.tld h.sub.sub.domain.tld.
+#12: CREATE CNAME i.sub.domain.tld j.sub.domain.tld.
 ```
 {% include endExample.html %}
+
+ProTips: `D_EXTEND()` permits you to create very complex and
+sophisticated configurations, but you shouldn't. Be nice to the next
+person that edits the file, who may not be as expert as yourself.
+Enhance readability by putting any `D_EXTEND()` statements immediately
+after the original `D()`, like in above example.  Avoid the temptation
+to obscure the addition of records to existing domains with randomly
+placed `D_EXTEND()` statements. Don't build up a domain using loops of
+`D_EXTEND()` statements. You'll be glad you didn't.