xml-twig 1.1.3 → 1.2.0

package/README.md

@@ -37,18 +37,6 @@ In my tests I parsed a 750 MB big XML file, the `node-expat` is around two times
 
 ## How to use it
 
-#### Names and Definitions
-
-In XML-Path, there are seven kinds of nodes: `element`, `attribute`, `text`, `namespace`, `processingInstruction`, `comment`, and `document`, see [Nodes at W3C](https://www.w3.org/TR/xpath-datamodel-31/#Node). XML documents are treated as trees of nodes.
-
-The [Twig](./doc/twig.md#Twig) Class models a "some-kind" Element tree.  I try to follow the [XML-Path](https://www.w3.org/TR/xpath/) conventions whenever possible to avoid confusion.
-
-
-#### XML-Namespaces
-
-When the XML-Files uses [Namespaces](https://www.w3schools.com/xml/xml_namespaces.asp) then you can address the elements as they appear in the file, for example `cd:data`. 
-With option `{ namespaces : true }` you will get access to the `.namespace` property.
-
 ### Read XML Document
 
 - **Read entire XML file at once**
@@ -90,7 +78,9 @@ With option `{ namespaces : true }` you will get access to the `.namespace` prop
 
 - **Read XML Document in chucks**
   
-  The key feature of this module is to read and process XML files in chunks. You need to create handler functions for elements you like to process.
+  The key feature of this module is to read and process XML files in chunks. You need to create handler functions for elements you like to process.<br>
+  The most notable difference to other parsers is the `purge()` and `purgeUpTo()` method. The parser reads the element and you decide how long you need to keep it in the memory. 
+  In many cases you will purge it immediately after you have used it but in some cases you may keep the element for later use. The parser knows the element position in the XML-Tree. 
 
 
    ```
@@ -215,6 +205,18 @@ Be aware if you run methods like `elt.followingSibling()`, `elt.descendant()`, `
 For details and other options, see [ParserOptions](./doc/twig.md#ParserOptions) and [TwigHandler](./doc/twig.md#TwigHandler)
 
 
+#### Names and Definitions
+
+In XML-Path, there are seven kinds of nodes: `element`, `attribute`, `text`, `namespace`, `processingInstruction`, `comment`, and `document`, see [Nodes at W3C](https://www.w3.org/TR/xpath-datamodel-31/#Node). XML documents are treated as trees of nodes.
+
+The [Twig](./doc/twig.md#Twig) Class models a "some-kind" Element tree.  I try to follow the [XML-Path](https://www.w3.org/TR/xpath/) conventions whenever possible to avoid confusion.
+
+
+#### XML-Namespaces
+
+When the XML-Files uses [Namespaces](https://www.w3schools.com/xml/xml_namespaces.asp) then you can address the elements as they appear in the file, for example `cd:data`. 
+With option `{ namespaces : true }` you will get access to the `.namespace` property.
+
 ### Access elements and attributes
 
 #### Get XML Attributes
@@ -301,20 +303,16 @@ You can specify condition on above methods. You can filter elements by following
 
 - If `undefined`, then all elements are returned.
 
-- If `string` then the element name must be equal to the string
-
+- If `string` then the element name must be equal to the string<br> 
   Example: `"book"`
 
-- If `RegExp` then the element name must match the Regular Expression
-
+- If `RegExp` then the element name must match the Regular Expression<br> 
   Example: `/book$/i`
 
 - With `ElementConditionFilter` you can specify any custom filter function.<br>
-
   Example: `(name, elt) => { return name === 'book' && elt.children().length > 1 }`
 
-- With a `Twig` object, you can specify the element directly. Apart from `purgeUpTo(elt)`, it is rarely used, because when you know the element then there is no reason to find it again.
-
+- With a `Twig` object, you can specify the element directly. Apart from `purgeUpTo(elt)`, it is rarely used, because when you know the element then there is no reason to find it again.<br> 
   Example: `elt.children()[2]`
 
 
@@ -339,7 +337,7 @@ For methods which return a single **Twig** element (e.g. `elt.next("book")`) the
 
 `.isLastChild` - **boolean**: `true` if the element is the last child in the parent
 
-`.index` - **integer**: The postion (starting at 0) of the element within the parent. The root element returns always 0
+`.index` - **integer**: The position (starting at 0) of the element within the parent. The root element returns always 0
 
 `.name` - **string**: Name of the element/tag
 
@@ -351,19 +349,39 @@ For methods which return a single **Twig** element (e.g. `elt.next("book")`) the
 
 `.comment` - **string|string[]**: Comments or array of comments inside the element
 
-`.declaration` - **object**: The XML-Declaration object, exist only on `root`. 
-
+`.declaration` - **object**: The XML-Declaration object, exist only on `root`.<br>
    Example  `{version: '1.0', encoding: 'UTF-8'}`. 
 
-`.PI` - **object**: Processing Instruction, exist only on `root`. 
-
+`.PI` - **object**: Processing Instruction, exist only on `root`.<br>
    Example `{ target: 'xml-stylesheet', data: 'type="text/xsl" href="style.xsl"' }`. 
 
-`.namespace` - **object**: Namespace of the element or `null`. Only available if parsed with option `xmlns: true`. 
-
+`.namespace` - **object**: Namespace of the element or `null`. Only available if parsed with option `xmlns: true`.<br>
    Example `{ local: 'h', uri: 'http://www.w3.org/TR/html4/' }`
 
 
+#### Update XML Elements
+
+To update the XML, use these methods. These methods modify the XML tree in the memory, not the input XML file. Use `writer()` to print modified XML or save it to a file.
+
+
+`.attribute(name, value)`: Updates an attribute.<br>
+   `name`: Name of the attribute. Regular Expression or other conditions are not supported<br>
+   `value`: Then new value
+
+`.deleteAttribute(name)`: Deletes the attribute.<br>
+   `name`: Name of the attribute. Regular Expression or other conditions are not supported
+
+`.text(value)`: Update the text (PCDATA) of current element<br>
+   `value`: The new text or `null` to remove any text
+
+`.addElement(name, text, attributes, position)`: Adds a new child element to the current element<br>
+   `name`: The name/tag of the new element<br>
+   `text`: The text (PCDATA) of the element or `null`<br>
+   `attributes`: Object of XML attributes, example: `{ id: 1, lang="en" }` or `null`<br>
+   `position`: The position in `children()` array where you like to add new child. You can also specify `'first'` or `'last'`
+
+
+
 ## Limitations
 
 This `xml-twig` module focus on reading a XML files. In principle it would be possible to create a XML file from scratch with the [Twig](./doc/twig.md#Twig) class. However, I think there are better modules available. Of course, you may run operations like `elt.root().children().push(elt.root().children()[0])`, but I think this is not so handy to use.

package/demo.js

@@ -0,0 +1,12 @@
+const fs = require('fs');
+const twig = require('./twig.js');
+
+
+const parser = twig.createParser({ tag: 'book', event: 'bookElement' });
+fs.createReadStream(`${__dirname}/samples/bookstore.xml`).pipe(parser);
+
+
+parser.on('bookElement', (elt) => {
+   console.log(`<${elt.name}> finished after ${parser.currentLine} lines`);
+}) 
+

package/doc/build.sh

@@ -1,6 +1,6 @@
-#!/bin/bash
-
-jsdoc2md --private ../twig.js > ./twig.md
-
-# see https://github.com/jsdoc2md/jsdoc-to-markdown
-
+#!/bin/bash
+
+jsdoc2md --private ../twig.js > ./twig.md
+
+# see https://github.com/jsdoc2md/jsdoc-to-markdown
+

package/doc/twig.md

@@ -5,6 +5,9 @@
 <dd></dd>
 <dt><a href="#Twig">Twig</a></dt>
 <dd></dd>
+<dt><a href="#NotImplementedYet">NotImplementedYet</a></dt>
+<dd><p>Generic error for non implemented feature</p>
+</dd>
 <dt><a href="#UnsupportedParser">UnsupportedParser</a></dt>
 <dd><p>Error for unsupported data types</p>
 </dd>
@@ -108,13 +111,16 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
 
 * [Twig](#Twig)
     * [new Twig()](#new_Twig_new)
-    * [new Twig(name, parent, attributes)](#new_Twig_new)
+    * [new Twig(name, parent, attributes, index)](#new_Twig_new)
     * [.attributes](#Twig+attributes) ℗
     * [.text](#Twig+text) ℗
     * [.name](#Twig+name) ℗
     * [.children](#Twig+children) ℗
     * [.parent](#Twig+parent) ℗
     * [.pinned](#Twig+pinned) ℗
+    * [.purge](#Twig+purge)
+    * [.purgeUpTo](#Twig+purgeUpTo)
+    * [.escapeEntity](#Twig+escapeEntity)
     * [.isEmpty](#Twig+isEmpty) ⇒ <code>boolean</code>
     * [.level](#Twig+level) ⇒ <code>number</code>
     * [.isRoot](#Twig+isRoot) ⇒ <code>boolean</code>
@@ -126,7 +132,6 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.text](#Twig+text)
     * [.pin](#Twig+pin)
     * [.pinned](#Twig+pinned) ⇒ <code>boolean</code>
-    * [.text](#Twig+text)
     * [.close](#Twig+close)
     * [.addChild](#Twig+addChild) ℗
     * [.writer](#Twig+writer) ⇒ <code>XMLWriter</code>
@@ -134,6 +139,7 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.attributes](#Twig+attributes) ⇒ <code>object</code>
     * [.hasAttribute](#Twig+hasAttribute) ⇒ <code>boolean</code>
     * [.attribute](#Twig+attribute) ⇒ <code>object</code>
+    * [.deleteAttribute](#Twig+deleteAttribute)
     * [.root](#Twig+root) ⇒ [<code>Twig</code>](#Twig)
     * [.parent](#Twig+parent) ⇒ [<code>Twig</code>](#Twig)
     * [.self](#Twig+self) ⇒ [<code>Twig</code>](#Twig)
@@ -155,8 +161,8 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.nextSibling](#Twig+nextSibling) ⇒ [<code>Twig</code>](#Twig)
     * [.prevSibling](#Twig+prevSibling) ⇒ [<code>Twig</code>](#Twig)
     * [.find](#Twig+find) ⇒ [<code>Twig</code>](#Twig)
-    * [.purge()](#Twig+purge)
-    * [.purgeUpTo(elt)](#Twig+purgeUpTo)
+    * [.addElement](#Twig+addElement) ⇒ [<code>Twig</code>](#Twig)
+    * [.delete](#Twig+delete)
     * [.setRoot(name)](#Twig+setRoot) ℗
     * [.filterElements(elements, condition)](#Twig+filterElements) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
     * [.testElement(element, condition)](#Twig+testElement) ⇒ <code>boolean</code>
@@ -168,7 +174,7 @@ Generic class modeling a XML Node
 
 <a name="new_Twig_new"></a>
 
-### new Twig(name, parent, attributes)
+### new Twig(name, parent, attributes, index)
 Create a new Twig object
 
 
@@ -177,6 +183,7 @@ Create a new Twig object
 | name | <code>string</code> | The name of the XML element |
 | parent | [<code>Twig</code>](#Twig) | The parent object |
 | attributes | <code>object</code> | Attribute object |
+| index | <code>string</code> \| <code>number</code> | Position name 'first', 'last' or the position in the current `children` array.<br>Defaults to 'last' |
 
 <a name="Twig+attributes"></a>
 
@@ -244,6 +251,34 @@ Create a new Twig object
 | --- | --- | --- |
 | #pinned | <code>boolean</code> | Determines whether twig is needed in partial load |
 
+<a name="Twig+purge"></a>
+
+### twig.purge
+Purges the current, typically used after element has been processed.<br>The root object cannot be purged.
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+<a name="Twig+purgeUpTo"></a>
+
+### twig.purgeUpTo
+Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| elt | [<code>Twig</code>](#Twig) | Up to this element the tree will be purged. The `elt` object itself is not purged.<br> If `undefined` then the current element is purged (i.e. `purge()`) |
+
+<a name="Twig+escapeEntity"></a>
+
+### twig.escapeEntity
+Escapes special XML characters. According W3C specification these are only `&, <, >, ", '` - this is a XML parser, not HTML!
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| text | <code>string</code> | Input text to be escaped |
+
 <a name="Twig+isEmpty"></a>
 
 ### twig.isEmpty ⇒ <code>boolean</code>
@@ -303,17 +338,17 @@ The text of the element. No matter if given as text or CDATA entity
 <a name="Twig+text"></a>
 
 ### twig.text
-Modifies the text of the element
+Update the text of the element
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Throws**:
 
-- [<code>UnsupportedType</code>](#UnsupportedType) - If value is not a string or numeric type
+- [<code>UnsupportedType</code>](#UnsupportedType) - If value is not a string, boolean or numeric type
 
 
 | Param | Type | Description |
 | --- | --- | --- |
-| value | <code>string</code> | New value of the attribute |
+| value | <code>string</code> \| <code>number</code> \| <code>bigint</code> \| <code>boolean</code> | New text of the element |
 
 <a name="Twig+pin"></a>
 
@@ -328,21 +363,6 @@ Checks if element is pinned
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>boolean</code> - `true` when the element is pinned  
-<a name="Twig+text"></a>
-
-### twig.text
-Modifies the text of the element
-
-**Kind**: instance property of [<code>Twig</code>](#Twig)  
-**Throws**:
-
-- [<code>UnsupportedType</code>](#UnsupportedType) - If value is not a string or numeric type
-
-
-| Param | Type | Description |
-| --- | --- | --- |
-| value | <code>string</code> | New value of the attribute |
-
 <a name="Twig+close"></a>
 
 ### twig.close
@@ -407,7 +427,7 @@ Check if the attribute exist or not
 <a name="Twig+attribute"></a>
 
 ### twig.attribute ⇒ <code>object</code>
-Retrieve or update XML attribute.
+Retrieve or update XML attribute. For update, the condition must be a string, i.e. must match to one attribute only.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>object</code> - Attributes or `null` if no matching attribute found  
@@ -415,12 +435,23 @@ Retrieve or update XML attribute.
 | Param | Type | Description |
 | --- | --- | --- |
 | condition | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attributes |
-| text | <code>string</code> \| <code>number</code> | New value of the attribute |
+| value | <code>string</code> \| <code>number</code> \| <code>bigint</code> \| <code>boolean</code> | New value of the attribute.<br>If `undefined` then existing attributes is returned. |
 
 **Example**  
 ```js
 attribute((name, val) => { return name === 'age' && val > 50})
 ```
+<a name="Twig+deleteAttribute"></a>
+
+### twig.deleteAttribute
+Delete the attribute
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| name | <code>string</code> | The attribute name |
+
 <a name="Twig+root"></a>
 
 ### twig.root ⇒ [<code>Twig</code>](#Twig)
@@ -647,23 +678,27 @@ Find a specific element within current element. Same as `.descendant(condition)[
 | --- | --- | --- |
 | condition | [<code>ElementCondition</code>](#ElementCondition) | Find condition |
 
-<a name="Twig+purge"></a>
-
-### twig.purge()
-Purges the current, typically used after element has been processed.<br>The root object cannot be purged.
+<a name="Twig+addElement"></a>
 
-**Kind**: instance method of [<code>Twig</code>](#Twig)  
-<a name="Twig+purgeUpTo"></a>
-
-### twig.purgeUpTo(elt)
-Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.
+### twig.addElement ⇒ [<code>Twig</code>](#Twig)
+Add a new element in the current element
 
-**Kind**: instance method of [<code>Twig</code>](#Twig)  
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Returns**: [<code>Twig</code>](#Twig) - - The appended element  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| elt | [<code>Twig</code>](#Twig) | Up to this element the tree will be purged. The `elt` object itself is not purged.<br> If `undefined` then the current element is purged (i.e. `purge()`) |
+| name | <code>string</code> | The tag name |
+| text | <code>string</code> | Text of the element |
+| attributes | <code>object</code> | Element attributes |
+| position | <code>name</code> \| <code>number</code> | Position name 'first', 'last' or the position in the `children` |
+
+<a name="Twig+delete"></a>
 
+### twig.delete
+Deletes the current element from tree, same as `purge()`. The root object cannot be deleted.
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
 <a name="Twig+setRoot"></a>
 
 ### twig.setRoot(name) ℗
@@ -709,13 +744,16 @@ Common function to filter Twig element
 
 * [Twig](#Twig)
     * [new Twig()](#new_Twig_new)
-    * [new Twig(name, parent, attributes)](#new_Twig_new)
+    * [new Twig(name, parent, attributes, index)](#new_Twig_new)
     * [.attributes](#Twig+attributes) ℗
     * [.text](#Twig+text) ℗
     * [.name](#Twig+name) ℗
     * [.children](#Twig+children) ℗
     * [.parent](#Twig+parent) ℗
     * [.pinned](#Twig+pinned) ℗
+    * [.purge](#Twig+purge)
+    * [.purgeUpTo](#Twig+purgeUpTo)
+    * [.escapeEntity](#Twig+escapeEntity)
     * [.isEmpty](#Twig+isEmpty) ⇒ <code>boolean</code>
     * [.level](#Twig+level) ⇒ <code>number</code>
     * [.isRoot](#Twig+isRoot) ⇒ <code>boolean</code>
@@ -727,7 +765,6 @@ Common function to filter Twig element
     * [.text](#Twig+text)
     * [.pin](#Twig+pin)
     * [.pinned](#Twig+pinned) ⇒ <code>boolean</code>
-    * [.text](#Twig+text)
     * [.close](#Twig+close)
     * [.addChild](#Twig+addChild) ℗
     * [.writer](#Twig+writer) ⇒ <code>XMLWriter</code>
@@ -735,6 +772,7 @@ Common function to filter Twig element
     * [.attributes](#Twig+attributes) ⇒ <code>object</code>
     * [.hasAttribute](#Twig+hasAttribute) ⇒ <code>boolean</code>
     * [.attribute](#Twig+attribute) ⇒ <code>object</code>
+    * [.deleteAttribute](#Twig+deleteAttribute)
     * [.root](#Twig+root) ⇒ [<code>Twig</code>](#Twig)
     * [.parent](#Twig+parent) ⇒ [<code>Twig</code>](#Twig)
     * [.self](#Twig+self) ⇒ [<code>Twig</code>](#Twig)
@@ -756,8 +794,8 @@ Common function to filter Twig element
     * [.nextSibling](#Twig+nextSibling) ⇒ [<code>Twig</code>](#Twig)
     * [.prevSibling](#Twig+prevSibling) ⇒ [<code>Twig</code>](#Twig)
     * [.find](#Twig+find) ⇒ [<code>Twig</code>](#Twig)
-    * [.purge()](#Twig+purge)
-    * [.purgeUpTo(elt)](#Twig+purgeUpTo)
+    * [.addElement](#Twig+addElement) ⇒ [<code>Twig</code>](#Twig)
+    * [.delete](#Twig+delete)
     * [.setRoot(name)](#Twig+setRoot) ℗
     * [.filterElements(elements, condition)](#Twig+filterElements) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
     * [.testElement(element, condition)](#Twig+testElement) ⇒ <code>boolean</code>
@@ -769,7 +807,7 @@ Generic class modeling a XML Node
 
 <a name="new_Twig_new"></a>
 
-### new Twig(name, parent, attributes)
+### new Twig(name, parent, attributes, index)
 Create a new Twig object
 
 
@@ -778,6 +816,7 @@ Create a new Twig object
 | name | <code>string</code> | The name of the XML element |
 | parent | [<code>Twig</code>](#Twig) | The parent object |
 | attributes | <code>object</code> | Attribute object |
+| index | <code>string</code> \| <code>number</code> | Position name 'first', 'last' or the position in the current `children` array.<br>Defaults to 'last' |
 
 <a name="Twig+attributes"></a>
 
@@ -845,6 +884,34 @@ Create a new Twig object
 | --- | --- | --- |
 | #pinned | <code>boolean</code> | Determines whether twig is needed in partial load |
 
+<a name="Twig+purge"></a>
+
+### twig.purge
+Purges the current, typically used after element has been processed.<br>The root object cannot be purged.
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+<a name="Twig+purgeUpTo"></a>
+
+### twig.purgeUpTo
+Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| elt | [<code>Twig</code>](#Twig) | Up to this element the tree will be purged. The `elt` object itself is not purged.<br> If `undefined` then the current element is purged (i.e. `purge()`) |
+
+<a name="Twig+escapeEntity"></a>
+
+### twig.escapeEntity
+Escapes special XML characters. According W3C specification these are only `&, <, >, ", '` - this is a XML parser, not HTML!
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| text | <code>string</code> | Input text to be escaped |
+
 <a name="Twig+isEmpty"></a>
 
 ### twig.isEmpty ⇒ <code>boolean</code>
@@ -904,17 +971,17 @@ The text of the element. No matter if given as text or CDATA entity
 <a name="Twig+text"></a>
 
 ### twig.text
-Modifies the text of the element
+Update the text of the element
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Throws**:
 
-- [<code>UnsupportedType</code>](#UnsupportedType) - If value is not a string or numeric type
+- [<code>UnsupportedType</code>](#UnsupportedType) - If value is not a string, boolean or numeric type
 
 
 | Param | Type | Description |
 | --- | --- | --- |
-| value | <code>string</code> | New value of the attribute |
+| value | <code>string</code> \| <code>number</code> \| <code>bigint</code> \| <code>boolean</code> | New text of the element |
 
 <a name="Twig+pin"></a>
 
@@ -929,21 +996,6 @@ Checks if element is pinned
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>boolean</code> - `true` when the element is pinned  
-<a name="Twig+text"></a>
-
-### twig.text
-Modifies the text of the element
-
-**Kind**: instance property of [<code>Twig</code>](#Twig)  
-**Throws**:
-
-- [<code>UnsupportedType</code>](#UnsupportedType) - If value is not a string or numeric type
-
-
-| Param | Type | Description |
-| --- | --- | --- |
-| value | <code>string</code> | New value of the attribute |
-
 <a name="Twig+close"></a>
 
 ### twig.close
@@ -1008,7 +1060,7 @@ Check if the attribute exist or not
 <a name="Twig+attribute"></a>
 
 ### twig.attribute ⇒ <code>object</code>
-Retrieve or update XML attribute.
+Retrieve or update XML attribute. For update, the condition must be a string, i.e. must match to one attribute only.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>object</code> - Attributes or `null` if no matching attribute found  
@@ -1016,12 +1068,23 @@ Retrieve or update XML attribute.
 | Param | Type | Description |
 | --- | --- | --- |
 | condition | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attributes |
-| text | <code>string</code> \| <code>number</code> | New value of the attribute |
+| value | <code>string</code> \| <code>number</code> \| <code>bigint</code> \| <code>boolean</code> | New value of the attribute.<br>If `undefined` then existing attributes is returned. |
 
 **Example**  
 ```js
 attribute((name, val) => { return name === 'age' && val > 50})
 ```
+<a name="Twig+deleteAttribute"></a>
+
+### twig.deleteAttribute
+Delete the attribute
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| name | <code>string</code> | The attribute name |
+
 <a name="Twig+root"></a>
 
 ### twig.root ⇒ [<code>Twig</code>](#Twig)
@@ -1248,23 +1311,27 @@ Find a specific element within current element. Same as `.descendant(condition)[
 | --- | --- | --- |
 | condition | [<code>ElementCondition</code>](#ElementCondition) | Find condition |
 
-<a name="Twig+purge"></a>
-
-### twig.purge()
-Purges the current, typically used after element has been processed.<br>The root object cannot be purged.
+<a name="Twig+addElement"></a>
 
-**Kind**: instance method of [<code>Twig</code>](#Twig)  
-<a name="Twig+purgeUpTo"></a>
+### twig.addElement ⇒ [<code>Twig</code>](#Twig)
+Add a new element in the current element
 
-### twig.purgeUpTo(elt)
-Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.
-
-**Kind**: instance method of [<code>Twig</code>](#Twig)  
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Returns**: [<code>Twig</code>](#Twig) - - The appended element  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| elt | [<code>Twig</code>](#Twig) | Up to this element the tree will be purged. The `elt` object itself is not purged.<br> If `undefined` then the current element is purged (i.e. `purge()`) |
+| name | <code>string</code> | The tag name |
+| text | <code>string</code> | Text of the element |
+| attributes | <code>object</code> | Element attributes |
+| position | <code>name</code> \| <code>number</code> | Position name 'first', 'last' or the position in the `children` |
+
+<a name="Twig+delete"></a>
 
+### twig.delete
+Deletes the current element from tree, same as `purge()`. The root object cannot be deleted.
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
 <a name="Twig+setRoot"></a>
 
 ### twig.setRoot(name) ℗
@@ -1303,6 +1370,12 @@ Common function to filter Twig element
 | element | [<code>Twig</code>](#Twig) | Element you like to filter |
 | condition | [<code>ElementCondition</code>](#ElementCondition) | The filter condition |
 
+<a name="NotImplementedYet"></a>
+
+## NotImplementedYet
+Generic error for non implemented feature
+
+**Kind**: global class  
 <a name="UnsupportedParser"></a>
 
 ## UnsupportedParser

package/package.json

@@ -5,13 +5,12 @@
   },
   "name": "xml-twig",
   "description": "Node module for processing huge XML documents in tree mode",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "main": "twig.js",
   "directories": {
     "doc": "doc"
   },
   "devDependencies": {
-    "jsdoc-to-markdown": "^8.0.0",
     "luxon": "^2.1.1",
     "node-expat": "^2.4.0"
   },

package/samples/sample.js

@@ -86,3 +86,11 @@ function rootHandler(elt) {
 }
 
 
+function bookHandler(elt) {
+   if (elt.attr('category') == 'fantasy') {
+      console.log(elt.writer(true).toString());
+      let t = elt.addElement('newTag', 'some Text > more', {id:1},2);
+      console.log(t.writer(true).toString());
+      console.log(elt.root().writer(true).toString());
+   }
+}

package/twig.js

@@ -123,7 +123,6 @@ function createParser(handler, options) {
          enumerable: true,
          get() { return parser._parser.column + 1 }
       });
-      parser.underlyingParser = parser._parser;
 
       closeEvent = "closetag";
       parser.on("opentagstart", function (node) {
@@ -199,7 +198,7 @@ function createParser(handler, options) {
          }
       })
       parser.on("cdata", function (str) {
-         current.text = str;
+         current.text = current.text ?? '' + str;
       })
 
       let hndl = Array.isArray(handler) ? handler : [handler];
@@ -221,7 +220,6 @@ function createParser(handler, options) {
          enumerable: true,
          get() { return parser.parser.getCurrentColumnNumber() }
       });
-      parser.underlyingParser = parser.parser;
       closeEvent = "endElement";
 
       parser.on("startElement", function (name, attrs) {
@@ -320,7 +318,7 @@ function createParser(handler, options) {
 
    // Common events
    parser.on('text', function (str) {
-      current.text = options.trim ? str.trim() : str;
+      current.text = current.text ?? '' + options.trim ? str.trim() : str;
    })
 
    parser.on("comment", function (str) {
@@ -352,7 +350,6 @@ function createParser(handler, options) {
    return parser;
 }
 
-
 /**
  * Generic class modeling a XML Node
  * @class Twig
@@ -435,9 +432,12 @@ class Twig {
    * @param {string} name - The name of the XML element
    * @param {Twig} parent - The parent object
    * @param {?object} attributes - Attribute object
+   * @param {string|number} index - Position name 'first', 'last' or the position in the current `children` array.<br>Defaults to 'last'
    */
-   constructor(name, parent, attributes) {
-      current = this;
+   constructor(name, parent, attributes, index) {
+      if (index === undefined)
+         current = this;
+
       if (name === null) {
          // Root element not available yet
          tree = this;
@@ -452,7 +452,16 @@ class Twig {
             this.#parent = parent;
             if (this.#parent.#pinned)
                this.#pinned = true;
-            parent.#children.push(this);
+            if (index === 'last' || index === undefined) {
+               parent.#children.push(this);
+            } else if (index === 'first') {
+               parent.#children.unshift(this);
+            } else if (typeof index === 'number') {
+               parent.#children = parent.#children.slice(0, index).concat(this, parent.#children.slice(index));
+            } else {
+               parent.#children.push(this);
+            }
+
          }
       }
    }
@@ -460,7 +469,7 @@ class Twig {
    /**
    * Purges the current, typically used after element has been processed.<br>The root object cannot be purged.
    */
-   purge() {
+   purge = function () {
       if (!this.isRoot)
          this.#parent.#children = this.#parent.#children.filter(x => !Object.is(this, x));
    }
@@ -470,7 +479,7 @@ class Twig {
    * @param {Twig} elt - Up to this element the tree will be purged. The `elt` object itself is not purged.<br>
    * If `undefined` then the current element is purged (i.e. `purge()`)
    */
-   purgeUpTo(elt) {
+   purgeUpTo = function (elt) {
       if (elt === undefined) {
          this.purge();
       } else {
@@ -486,6 +495,19 @@ class Twig {
       }
    }
 
+   /**
+   * Escapes special XML characters. According W3C specification these are only `&, <, >, ", '` - this is a XML parser, not HTML!
+   * @param {string} text - Input text to be escaped
+   */
+   escapeEntity = function (text) {
+      return text
+         .replaceAll("&", "&amp;")
+         .replaceAll("<", "&lt;")
+         .replaceAll(">", "&gt;")
+         .replaceAll('"', "&quot;")
+         .replaceAll("'", "&apos;");
+   }
+
    /**
    * Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
    * Used internally!
@@ -568,14 +590,17 @@ class Twig {
    }
 
    /**
-   * Modifies the text of the element
-   * @param {string} value - New value of the attribute
-   * @throws {UnsupportedType} - If value is not a string or numeric type
+   * Update the text of the element
+   * @param {string|number|bigint|boolean} value - New text of the element
+   * @throws {UnsupportedType} - If value is not a string, boolean or numeric type
    */
    set text(value) {
-      if (!['string', 'number', 'bigint'].includes(typeof value))
+      if (typeof value === 'string')
+         this.#text = value
+      else if (['number', 'bigint', 'boolean'].includes(typeof value))
+         this.#text = value.toString()
+      else
          throw new UnsupportedType(value);
-      this.#text = this.#text ?? '' + value;
    }
 
    /**
@@ -593,18 +618,6 @@ class Twig {
       return this.#pinned;
    }
 
-   /**
-   * Modifies the text of the element
-   * @param {string} value - New value of the attribute
-   * @throws {UnsupportedType} - If value is not a string or numeric type
-   */
-   set text(value) {
-      if (!['string', 'number', 'bigint'].includes(typeof value))
-         throw new UnsupportedType(value);
-      this.#text = this.#text ?? '' + value;
-   }
-
-
    /**
    * Closes the element
    */
@@ -681,17 +694,17 @@ class Twig {
    }
 
    /**
-   * Retrieve or update XML attribute.
+   * Retrieve or update XML attribute. For update, the condition must be a string, i.e. must match to one attribute only.
    * @param {?AttributeCondition} condition - Optional condition to select attributes
-   * @param {?string|number} text - New value of the attribute
+   * @param {?string|number|bigint|boolean} value - New value of the attribute.<br>If `undefined` then existing attributes is returned.
    * @returns {object} Attributes or `null` if no matching attribute found
    * @example attribute((name, val) => { return name === 'age' && val > 50})
    * attribute((name) => { return ['firstName', 'lastName'].includes(name) })
    * attribute('firstName')
    * attribute(/name/i)
    */
-   attribute = function (condition, text) {
-      if (text === undefined) {
+   attribute = function (condition, value) {
+      if (value === undefined) {
          let attr;
          if (condition === undefined) {
             attr = this.#attributes;
@@ -707,19 +720,26 @@ class Twig {
             return this.attribute();
          }
          return attr === null || Object.keys(attr).length == 0 ? null : attr;
+      } else if (typeof condition === 'string') {
+         if (typeof value === 'string')
+            this.#attributes[condition] = value
+         else if (['number', 'bigint', 'boolean'].includes(typeof value))
+            this.#attributes[condition] = value.toString()
+         else
+            throw new UnsupportedType(value);
       } else {
-         if (text === null) {
-            delete this.#attributes[condition];
-         } else {
-            if (!['string', 'number', 'bigint'].includes(typeof text))
-               throw new UnsupportedType(text);
-            if (typeof condition !== 'string')
-               throw new UnsupportedCondition(condition, ['string']);
-            this.#attributes[condition] = text;
-         }
+         console.warn('Condition must be a `string` if you like to update an attribute');
       }
    }
 
+   /**
+   * Delete the attribute
+   * @param {string} name - The attribute name
+   */
+   deleteAttribute = function (name) {
+      delete this.#attributes[name];
+   }
+
    /**
    * Returns the root object
    * @returns {Twig} The root element of XML tree
@@ -1068,6 +1088,40 @@ class Twig {
       return null;
    }
 
+   /**
+   * Add a new element in the current element
+   * @param {string} name - The tag name
+   * @param {?string} text - Text of the element
+   * @param {?object} attributes - Element attributes
+   * @param {name|number} position - Position name 'first', 'last' or the position in the `children`
+   * @returns {Twig} - The appended element
+   */
+   addElement = function (name, text, attributes, position) {
+      let twig = new Twig(name, this, attributes ?? {}, position ?? 'last');
+      twig.#text = text ?? null;
+      twig.close();
+      return twig;
+   }
+
+   /**
+   * Deletes the current element from tree, same as `purge()`. The root object cannot be deleted.
+   */
+   delete = function () {
+      this.purge();
+   }
+
+
+}
+
+
+/**
+ * Generic error for non implemented feature
+ * @exception NotImplementedYet
+ */
+class NotImplementedYet extends TypeError {
+   constructor() {
+      super(`Net yet implemented`);
+   }
 }
 
 
@@ -1084,7 +1138,6 @@ class UnsupportedParser extends TypeError {
    }
 }
 
-
 /**
  * Generic error for unsupported data types
  * @exception UnsupportedType
@@ -1112,5 +1165,6 @@ class UnsupportedCondition extends TypeError {
    }
 }
 
+
 module.exports = { createParser, Twig, Any, Root };