Mercurial > hg > nginx-site
changeset 2934:41870b949ac9
Documented XML module in njs.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 02 Feb 2023 16:22:15 +0000 |
parents | 386ba17fac23 |
children | 918ec12be507 |
files | xml/en/docs/njs/reference.xml |
diffstat | 1 files changed, 212 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/njs/reference.xml Thu Feb 02 14:06:03 2023 +0000 +++ b/xml/en/docs/njs/reference.xml Thu Feb 02 16:22:15 2023 +0000 @@ -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 @@ - 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 @@ </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 = `<note><to b="bar" a= "foo" >Tove</to><from>Jani</from></note>`; +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) /* '<note><to a="foo" b="bar">Tove</to><from>Jani</from></note>' */ + +c14n = dec.decode(xml.exclusiveC14n(doc.note.to)); +console.log(c14n) /* '<to a="foo" b="bar">Tove</to>' */ + +c14n = dec.decode(xml.exclusiveC14n(doc.note, doc.note.to /* excluding 'to' */)); +console.log(c14n) /* '<note><from>Jani</from></note>' */ +</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>