# HG changeset patch
# User Yaroslav Zhuravlev <yar@nginx.com>
# Date 1675354935 0
# Node ID 41870b949ac973fe93818de03454a05f1c441908
# Parent  386ba17fac2398fea1375d508e99766b5f873a00
Documented XML module in njs.

diff --git a/xml/en/docs/njs/reference.xml b/xml/en/docs/njs/reference.xml
--- a/xml/en/docs/njs/reference.xml
+++ b/xml/en/docs/njs/reference.xml
@@ -9,7 +9,7 @@
 <article name="Reference"
         link="/en/docs/njs/reference.html"
         lang="en"
-        rev="97">
+        rev="98">
 
 <section id="summary">
 
@@ -1881,7 +1881,7 @@ that represents the input to the derivat
 - the initial key material for the derivation function:
 for example, for <literal>PBKDF2</literal> it might be a password,
 imported as a <literal>CryptoKey</literal> using
-<link id="crypto_sublte_import_key"><literal>сrypto.subtle.importKey()</literal></link>.
+<link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link>.
 </tag-desc>
 
 <tag-name id="crypto_derive_key_derivedkeyalg"><literal>derivedKeyAlgorithm</literal></tag-name>
@@ -5110,6 +5110,216 @@ and should not be used directly.
 
 </section>
 
+
+<section id="xml" name="XML">
+
+<para>
+The XML module allows working with XML documents
+(<link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
+The XML module object is returned by
+<literal>require('xml')</literal>.
+</para>
+
+<para>
+Example:
+<example>
+const xml = require("xml");
+let data = `&lt;note&gt;&lt;to b="bar" a= "foo" &gt;Tove&lt;/to&gt;&lt;from&gt;Jani&lt;/from&gt;&lt;/note&gt;`;
+let doc = xml.parse(data);
+
+console.log(doc.note.to.$text) /* 'Tove' */
+console.log(doc.note.to.$attr$b) /* 'bar' */
+console.log(doc.note.$tags[1].$text) /* 'Jani' */
+
+let dec = new TextDecoder();
+let c14n = dec.decode(xml.exclusiveC14n(doc.note));
+console.log(c14n) /* '&lt;note&gt;&lt;to a="foo" b="bar"&gt;Tove&lt;/to&gt;&lt;from&gt;Jani&lt;/from&gt;&lt;/note&gt;' */
+
+c14n = dec.decode(xml.exclusiveC14n(doc.note.to));
+console.log(c14n) /* '&lt;to a="foo" b="bar">Tove&lt;/to&gt;' */
+
+c14n = dec.decode(xml.exclusiveC14n(doc.note, doc.note.to /* excluding 'to' */));
+console.log(c14n) /* '&lt;note&gt;&lt;from&gt;Jani&lt;/from&gt;&lt;/note&gt;' */
+</example>
+</para>
+
+<para>
+<list type="tag">
+
+<tag-name id="xml_parse"><literal>parse(<value>string</value> |
+<value>Buffer</value>)</literal></tag-name>
+<tag-desc>
+Parses a string or Buffer for an XML document,
+returns an
+<link id="xml_doc"><literal>XMLDoc</literal></link> wrapper object
+ around XML structure.
+</tag-desc>
+
+<tag-name id="xml_c14n"><literal>xml.c14n(<value>root_node</value>[,
+<value>excluding_node</value>]])</literal></tag-name>
+<tag-desc>
+Canonicalizes <literal>root_node</literal> and its children according to
+<link url="https://www.w3.org/TR/xml-c14n">Canonical XML Version 1.1</link>.
+
+<para>
+<list type="tag">
+
+<tag-name><literal>excluding_node</literal></tag-name>
+<tag-desc>
+allows omitting from the output a part of the document
+</tag-desc>
+
+</list>
+</para>
+
+</tag-desc>
+
+<tag-name id="xml_exclusiveC14n"><literal>xml.exclusiveC14n(<value>root_node</value>[,
+<value>excluding_node</value>[,
+<value>withComments</value>
+[,<value>prefix_list</value>]]])</literal></tag-name>
+<tag-desc>
+Canonicalizes <literal>root_node</literal>  and its children according to
+<link url="https://www.w3.org/TR/xml-exc-c14n/">Exclusive XML
+Canonicalization Version 1.0</link>.
+
+<para>
+<list type="tag">
+
+<tag-name><literal>excluding_node</literal></tag-name>
+<tag-desc>
+allows omitting from the output a part of the document
+corresponding to the node and its children
+</tag-desc>
+
+<tag-name><literal>withComments</literal></tag-name>
+<tag-desc>
+a boolean value, <literal>false</literal> by default.
+If <literal>true</literal>, canonicalization corresponds to
+<link url="http://www.w3.org/2001/10/xml-exc-c14n#WithComments">Exclusive XML
+Canonicalization Version 1.0</link>.
+</tag-desc>
+
+<tag-name><literal>prefix_list</literal></tag-name>
+<tag-desc>
+an optional string with a space separated namespace prefixes
+for namespaces that should also be included into the output
+</tag-desc>
+
+</list>
+</para>
+
+</tag-desc>
+
+<tag-name id="xml_doc"><literal>XMLDoc</literal></tag-name>
+<tag-desc>
+An XMLDoc wrapper object around XML structure.
+
+<para>
+<list type="tag">
+
+<tag-name id="xml_doc_root"><literal>$root</literal></tag-name>
+<tag-desc>
+the root tag as
+<link id="xml_node"><literal>XMLNode</literal></link> wrapper object
+</tag-desc>
+
+<tag-name id="xml_doc_xxx"><literal>doc.<value>xxx</value></literal></tag-name>
+<tag-desc>
+the first root tag named <value>xxx</value> as
+<link id="xml_node"><literal>XMLNode</literal></link> wrapper object
+</tag-desc>
+
+</list>
+</para>
+
+</tag-desc>
+
+<tag-name id="xml_node"><literal>XMLNode</literal></tag-name>
+<tag-desc>
+An XMLNode wrapper object around XML tag node.
+<para>
+<list type="tag">
+
+<tag-name id="xml_node_tag"><literal>node.$tag$<value>xxx</value></literal></tag-name>
+<tag-desc>
+the first child tag named <value>xxx</value> as
+<link id="xml_node"><literal>XMLNode</literal></link> wrapper object
+</tag-desc>
+
+<tag-name><literal>node.<value>xxx</value></literal></tag-name>
+<tag-desc>
+a shorthand syntax for
+<link id="xml_node_tag"><literal>node.$tag$<value>xxx</value></literal></link>
+</tag-desc>
+
+<tag-name><literal>node.$tags$<value>xxx</value></literal></tag-name>
+<tag-desc>
+an array of all children tags named <value>xxx</value>
+</tag-desc>
+
+<tag-name><literal>node.$tags$</literal></tag-name>
+<tag-desc>
+an array of all children tags
+</tag-desc>
+
+<tag-name><literal>node.$attr$<value>xxx</value></literal></tag-name>
+<tag-desc>
+an attribute value of <value>xxx</value>
+</tag-desc>
+
+<tag-name><literal>node.$attrs</literal></tag-name>
+<tag-desc>
+an <link id="xml_xmlattr"><literal>XMLAttr</literal></link> wrapper object
+</tag-desc>
+
+<tag-name><literal>node.$name</literal></tag-name>
+<tag-desc>
+the tag name of the node
+</tag-desc>
+
+<tag-name><literal>node.$ns</literal></tag-name>
+<tag-desc>
+the namespace of the node
+</tag-desc>
+
+<tag-name><literal>node.$parent</literal></tag-name>
+<tag-desc>
+the parent of the node
+</tag-desc>
+
+<tag-name><literal>node.$text</literal></tag-name>
+<tag-desc>
+the node's content
+</tag-desc>
+
+</list>
+</para>
+
+</tag-desc>
+
+<tag-name id="xml_xmlattr"><literal>XMLAttr</literal></tag-name>
+<tag-desc>
+An XMLAttrs wrapper object around XML node attributes.
+
+<para>
+<list type="tag">
+
+<tag-name id="xmlattr_x"><literal>attr.<value>xxx</value></literal></tag-name>
+<tag-desc>
+a value of the <value>xxx</value> attribute
+</tag-desc>
+
+</list>
+</para>
+
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
 </section>
 
 </article>