Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2942:ee84a44fa7f7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented XMLNode API for modification XML docs in njs. Also xml methods sorted alphabetically, some descriptions of existing xml methods were updated.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 23 Feb 2023 13:05:14 +0000
parents 8f50cc590cd7
children a412c1fffbf1
comparison
equal deleted inserted replaced
2941:8f50cc590cd7 2942:ee84a44fa7f7
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="Reference" 9 <article name="Reference"
10 link="/en/docs/njs/reference.html" 10 link="/en/docs/njs/reference.html"
11 lang="en" 11 lang="en"
12 rev="99"> 12 rev="100">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 <link doc="index.xml">njs</link> provides objects, methods and properties 17 <link doc="index.xml">njs</link> provides objects, methods and properties
5113 5113
5114 <section id="xml" name="XML"> 5114 <section id="xml" name="XML">
5115 5115
5116 <para> 5116 <para>
5117 The XML module allows working with XML documents 5117 The XML module allows working with XML documents
5118 (<link doc="changes.xml" id="njs0.7.10">0.7.10</link>). 5118 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
5119 The XML module object is returned by 5119 The XML module object is returned by
5120 <literal>require('xml')</literal>. 5120 <literal>require('xml')</literal>.
5121 </para> 5121 </para>
5122 5122
5123 <para> 5123 <para>
5150 <value>Buffer</value>)</literal></tag-name> 5150 <value>Buffer</value>)</literal></tag-name>
5151 <tag-desc> 5151 <tag-desc>
5152 Parses a string or Buffer for an XML document, 5152 Parses a string or Buffer for an XML document,
5153 returns an 5153 returns an
5154 <link id="xml_doc"><literal>XMLDoc</literal></link> wrapper object 5154 <link id="xml_doc"><literal>XMLDoc</literal></link> wrapper object
5155 around XML structure. 5155 representing the parsed XML document.
5156 </tag-desc> 5156 </tag-desc>
5157 5157
5158 <tag-name id="xml_c14n"><literal>xml.c14n(<value>root_node</value>[, 5158 <tag-name id="xml_c14n"><literal>c14n(<value>root_node</value>[,
5159 <value>excluding_node</value>]])</literal></tag-name> 5159 <value>excluding_node</value>])</literal></tag-name>
5160 <tag-desc> 5160 <tag-desc>
5161 Canonicalizes <literal>root_node</literal> and its children according to 5161 Canonicalizes <literal>root_node</literal> and its children according to
5162 <link url="https://www.w3.org/TR/xml-c14n">Canonical XML Version 1.1</link>. 5162 <link url="https://www.w3.org/TR/xml-c14n">Canonical XML Version 1.1</link>.
5163 The <literal>root_node</literal> can be
5164 <link id="xml_node"><literal>XMLNode</literal></link> or
5165 <link id="xml_doc"><literal>XMLDoc</literal></link> wrapper object
5166 around XML structure.
5167 Returns Buffer object that contains canonicalized output.
5163 5168
5164 <para> 5169 <para>
5165 <list type="tag"> 5170 <list type="tag">
5166 5171
5167 <tag-name><literal>excluding_node</literal></tag-name> 5172 <tag-name><literal>excluding_node</literal></tag-name>
5172 </list> 5177 </list>
5173 </para> 5178 </para>
5174 5179
5175 </tag-desc> 5180 </tag-desc>
5176 5181
5177 <tag-name id="xml_exclusiveC14n"><literal>xml.exclusiveC14n(<value>root_node</value>[, 5182 <tag-name id="xml_exclusivec14n"><literal>exclusiveC14n(<value>root_node</value>[,
5178 <value>excluding_node</value>[, 5183 <value>excluding_node</value>[,
5179 <value>withComments</value> 5184 <value>withComments</value>
5180 [,<value>prefix_list</value>]]])</literal></tag-name> 5185 [,<value>prefix_list</value>]]])</literal></tag-name>
5181 <tag-desc> 5186 <tag-desc>
5182 Canonicalizes <literal>root_node</literal> and its children according to 5187 Canonicalizes <literal>root_node</literal> and its children according to
5183 <link url="https://www.w3.org/TR/xml-exc-c14n/">Exclusive XML 5188 <link url="https://www.w3.org/TR/xml-exc-c14n/">Exclusive XML
5184 Canonicalization Version 1.0</link>. 5189 Canonicalization Version 1.0</link>.
5185 5190
5186 <para> 5191 <para>
5187 <list type="tag"> 5192 <list type="tag">
5193
5194 <tag-name><literal>root_node</literal></tag-name>
5195 <tag-desc>
5196 is
5197 <link id="xml_node"><literal>XMLNode</literal></link> or
5198 <link id="xml_doc"><literal>XMLDoc</literal></link> wrapper object
5199 around XML structure
5200 </tag-desc>
5188 5201
5189 <tag-name><literal>excluding_node</literal></tag-name> 5202 <tag-name><literal>excluding_node</literal></tag-name>
5190 <tag-desc> 5203 <tag-desc>
5191 allows omitting from the output a part of the document 5204 allows omitting from the output a part of the document
5192 corresponding to the node and its children 5205 corresponding to the node and its children
5196 <tag-desc> 5209 <tag-desc>
5197 a boolean value, <literal>false</literal> by default. 5210 a boolean value, <literal>false</literal> by default.
5198 If <literal>true</literal>, canonicalization corresponds to 5211 If <literal>true</literal>, canonicalization corresponds to
5199 <link url="http://www.w3.org/2001/10/xml-exc-c14n#WithComments">Exclusive XML 5212 <link url="http://www.w3.org/2001/10/xml-exc-c14n#WithComments">Exclusive XML
5200 Canonicalization Version 1.0</link>. 5213 Canonicalization Version 1.0</link>.
5214 Returns Buffer object that contains canonicalized output.
5201 </tag-desc> 5215 </tag-desc>
5202 5216
5203 <tag-name><literal>prefix_list</literal></tag-name> 5217 <tag-name><literal>prefix_list</literal></tag-name>
5204 <tag-desc> 5218 <tag-desc>
5205 an optional string with a space separated namespace prefixes 5219 an optional string with a space separated namespace prefixes
5209 </list> 5223 </list>
5210 </para> 5224 </para>
5211 5225
5212 </tag-desc> 5226 </tag-desc>
5213 5227
5228 <tag-name id="xml_serialize"><literal>serialize()</literal></tag-name>
5229 <tag-desc>
5230 The same as
5231 <link id="xml_c14n"><literal>xml.c14n()</literal></link>
5232 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
5233 </tag-desc>
5234
5235 <tag-name id="xml_serialize_tostring"><literal>serializeToString()</literal></tag-name>
5236 <tag-desc>
5237 The same as
5238 <link id="xml_c14n"><literal>xml.c14n()</literal></link>
5239 except it returns the result as a <literal>string</literal>
5240 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
5241 </tag-desc>
5242
5214 <tag-name id="xml_doc"><literal>XMLDoc</literal></tag-name> 5243 <tag-name id="xml_doc"><literal>XMLDoc</literal></tag-name>
5215 <tag-desc> 5244 <tag-desc>
5216 An XMLDoc wrapper object around XML structure. 5245 An XMLDoc wrapper object around XML structure,
5217 5246 the root node of the document.
5218 <para> 5247
5219 <list type="tag"> 5248 <para>
5220 5249 <list type="tag">
5221 <tag-name id="xml_doc_root"><literal>$root</literal></tag-name> 5250
5222 <tag-desc> 5251 <tag-name id="xml_doc_root"><literal>doc.$root</literal></tag-name>
5223 the root tag as 5252 <tag-desc>
5253 the document's root by its name or undefined
5254 </tag-desc>
5255
5256 <tag-name id="xml_doc_xxx"><literal>doc.<value>abc</value></literal></tag-name>
5257 <tag-desc>
5258 the first root tag named <value>abc</value> as
5224 <link id="xml_node"><literal>XMLNode</literal></link> wrapper object 5259 <link id="xml_node"><literal>XMLNode</literal></link> wrapper object
5225 </tag-desc> 5260 </tag-desc>
5226 5261
5227 <tag-name id="xml_doc_xxx"><literal>doc.<value>xxx</value></literal></tag-name>
5228 <tag-desc>
5229 the first root tag named <value>xxx</value> as
5230 <link id="xml_node"><literal>XMLNode</literal></link> wrapper object
5231 </tag-desc>
5232
5233 </list> 5262 </list>
5234 </para> 5263 </para>
5235 5264
5236 </tag-desc> 5265 </tag-desc>
5237 5266
5239 <tag-desc> 5268 <tag-desc>
5240 An XMLNode wrapper object around XML tag node. 5269 An XMLNode wrapper object around XML tag node.
5241 <para> 5270 <para>
5242 <list type="tag"> 5271 <list type="tag">
5243 5272
5244 <tag-name id="xml_node_tag"><literal>node.$tag$<value>xxx</value></literal></tag-name> 5273 <tag-name id="node_abc"><literal>node.<value>abc</value></literal></tag-name>
5245 <tag-desc> 5274 <tag-desc>
5246 the first child tag named <value>xxx</value> as 5275 the same as
5247 <link id="xml_node"><literal>XMLNode</literal></link> wrapper object 5276 <link id="node_tag"><literal>node.$tag$<value>abc</value></literal></link>
5248 </tag-desc> 5277 </tag-desc>
5249 5278
5250 <tag-name><literal>node.<value>xxx</value></literal></tag-name> 5279 <tag-name id="node_attr"><literal>node.$attr$<value>abc</value></literal></tag-name>
5251 <tag-desc> 5280 <tag-desc>
5252 a shorthand syntax for 5281 the node's attribute value of <value>abc</value>,
5253 <link id="xml_node_tag"><literal>node.$tag$<value>xxx</value></literal></link> 5282 writable
5254 </tag-desc> 5283 since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>
5255 5284 </tag-desc>
5256 <tag-name><literal>node.$tags$<value>xxx</value></literal></tag-name> 5285
5257 <tag-desc> 5286 <tag-name id="node_attr_value"><literal>node.$attr$<value>abc</value></literal>=<value>xyz</value></tag-name>
5258 an array of all children tags named <value>xxx</value> 5287 <tag-desc>
5259 </tag-desc> 5288 the same as
5260 5289 <link id="node_setattribute"><literal>node.setAttribute('<value>abc</value>',
5261 <tag-name><literal>node.$tags</literal></tag-name> 5290 <value>xyz</value>)</literal></link>
5291 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
5292 </tag-desc>
5293
5294 <tag-name id="node_attrs"><literal>node.$attrs</literal></tag-name>
5295 <tag-desc>
5296 an <link id="xml_xmlattr"><literal>XMLAttr</literal></link> wrapper object
5297 for all attributes of the node
5298 </tag-desc>
5299
5300 <tag-name id="node_name"><literal>node.$name</literal></tag-name>
5301 <tag-desc>
5302 the name of the node
5303 </tag-desc>
5304
5305 <tag-name id="node_ns"><literal>node.$ns</literal></tag-name>
5306 <tag-desc>
5307 the namespace of the node
5308 </tag-desc>
5309
5310 <tag-name id="node_parent"><literal>node.$parent</literal></tag-name>
5311 <tag-desc>
5312 the parent node of the current node
5313 </tag-desc>
5314
5315 <tag-name id="node_tag"><literal>node.$tag$<value>abc</value></literal></tag-name>
5316 <tag-desc>
5317 the first child tag of the node named <value>abc</value>,
5318 writable
5319 since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>
5320 </tag-desc>
5321
5322 <tag-name id="node_tags"><literal>node.$tags</literal></tag-name>
5262 <tag-desc> 5323 <tag-desc>
5263 an array of all children tags 5324 an array of all children tags
5264 </tag-desc> 5325 </tag-desc>
5265 5326
5266 <tag-name><literal>node.$attr$<value>xxx</value></literal></tag-name> 5327 <tag-name id="node_tags_"><literal>node.$tags = [node1, node2, ...]</literal></tag-name>
5267 <tag-desc> 5328 <tag-desc>
5268 an attribute value of <value>xxx</value> 5329 the same as
5269 </tag-desc> 5330 <link id="node_removechildren"><literal>node.removeChildren</literal>()</link>;
5270 5331 <link id="node_addchild"><literal>node.addChild(<value>node1</value>)</literal></link>;
5271 <tag-name><literal>node.$attrs</literal></tag-name> 5332 <link id="node_addchild"><literal>node.addChild(<value>node2</value>)</literal></link>
5272 <tag-desc> 5333 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
5273 an <link id="xml_xmlattr"><literal>XMLAttr</literal></link> wrapper object 5334 </tag-desc>
5274 </tag-desc> 5335
5275 5336 <tag-name id="node_tags_abc"><literal>node.$tags$<value>abc</value></literal></tag-name>
5276 <tag-name><literal>node.$name</literal></tag-name> 5337 <tag-desc>
5277 <tag-desc> 5338 all children tags named <value>abc</value> of the node,
5278 the tag name of the node 5339 writable
5279 </tag-desc> 5340 since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>
5280 5341 </tag-desc>
5281 <tag-name><literal>node.$ns</literal></tag-name> 5342
5282 <tag-desc> 5343 <tag-name id="node_text"><literal>node.$text</literal></tag-name>
5283 the namespace of the node 5344 <tag-desc>
5284 </tag-desc> 5345 the content of the node,
5285 5346 writable
5286 <tag-name><literal>node.$parent</literal></tag-name> 5347 since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>
5287 <tag-desc> 5348 </tag-desc>
5288 the parent of the node 5349
5289 </tag-desc> 5350 <tag-name id="node_text_abc"><literal>node.$text = 'abc' </literal></tag-name>
5290 5351 <tag-desc>
5291 <tag-name><literal>node.$text</literal></tag-name> 5352 the same as
5292 <tag-desc> 5353 <link id="node_settext"><literal>node.setText('abc')</literal></link>
5293 the node's content 5354 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
5355 </tag-desc>
5356
5357 <tag-name id="node_addchild"><literal>node.addChild(<value>nd</value>)</literal></tag-name>
5358 <tag-desc>
5359 adds XMLNode as a child to node
5360 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
5361 <literal>nd</literal> is recursively copied before adding to the node
5362 </tag-desc>
5363
5364 <tag-name id="node_removeallattr"><literal>node.removeAllAttributes()</literal></tag-name>
5365 <tag-desc>
5366 removes all attributes of the node
5367 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
5368 </tag-desc>
5369
5370 <tag-name id="node_removeattr"><literal>node.removeAttribute(<value>attr_name</value>)</literal></tag-name>
5371 <tag-desc>
5372 removes the attribute named <literal>attr_name</literal>
5373 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
5374 </tag-desc>
5375
5376 <tag-name id="node_removechildren"><literal>node.removeChildren(<value>tag_name</value>)</literal></tag-name>
5377 <tag-desc>
5378 removes all the children tags named <literal>tag_name</literal>
5379 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
5380 If <literal>tag_name</literal> is absent, all children tags are removed
5381 </tag-desc>
5382
5383 <tag-name id="node_removetext"><literal>node.removeText()</literal></tag-name>
5384 <tag-desc>
5385 removes the node's text value
5386 (<link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
5387 </tag-desc>
5388
5389 <tag-name id="node_setattr"><literal>node.setAttribute(<value>attr_name</value>,
5390 <value>value</value>)</literal></tag-name>
5391 <tag-desc>
5392 sets a value for an <literal>attr_name</literal>
5393 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
5394 When the value is <literal>null</literal>,
5395 the attribute named <literal>attr_name</literal> is deleted
5396 </tag-desc>
5397
5398 <tag-name id="node_settext"><literal>node.setText(<value>value</value>)</literal></tag-name>
5399 <tag-desc>
5400 sets a text value for the node
5401 (since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
5402 When the value is <literal>null</literal>, the text of the node is deleted.
5294 </tag-desc> 5403 </tag-desc>
5295 5404
5296 </list> 5405 </list>
5297 </para> 5406 </para>
5298 5407
5303 An XMLAttrs wrapper object around XML node attributes. 5412 An XMLAttrs wrapper object around XML node attributes.
5304 5413
5305 <para> 5414 <para>
5306 <list type="tag"> 5415 <list type="tag">
5307 5416
5308 <tag-name id="xmlattr_x"><literal>attr.<value>xxx</value></literal></tag-name> 5417 <tag-name id="xmlattr_x"><literal>attr.<value>abc</value></literal></tag-name>
5309 <tag-desc> 5418 <tag-desc>
5310 a value of the <value>xxx</value> attribute 5419 the attribute value of <value>abc</value>
5311 </tag-desc> 5420 </tag-desc>
5312 5421
5313 </list> 5422 </list>
5314 </para> 5423 </para>
5315 5424