Mercurial > hg > nginx-site
comparison xml/en/docs/njs/reference.xml @ 2942:ee84a44fa7f7
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 |