xml-twig 1.9.1 → 1.9.3

package/doc/twig.md

@@ -259,7 +259,8 @@ Purges the current, typically used after element has been processed.<br>The root
 <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.<br>
+Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.<br>
+The `elt` object is not purged. If you like to purge including `elt`, use `.purgeUpTo(elt.previous())`
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 
@@ -281,7 +282,8 @@ Escapes special XML characters. According W3C specification these are only `&, <
 <a name="Twig+isEmpty"></a>
 
 ### twig.isEmpty ⇒ <code>boolean</code>
-Returns `true` if the element is empty, otherwise `false`.
+Returns `true` if the element is empty, otherwise `false`.
+An empty element has no text nor any child elements, however empty elements can have attributes.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>boolean</code> - true if empty element  
@@ -316,7 +318,8 @@ The position in `#children` array. For root object 0
 <a name="Twig+path"></a>
 
 ### twig.path ⇒ <code>string</code>
-The X-Path position of the element
+The X-Path position of the element
+NOTE: Applies only to currently loaded elements.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - X-Path  
@@ -337,7 +340,8 @@ Returns the name of the element. Synonym for `twig.name`
 <a name="Twig+text"></a>
 
 ### twig.text ⇒ <code>string</code>
-The text of the element. No matter if given as text or CDATA entity.
+The text of the element. No matter if given as text or CDATA entity.
+If option `trim: true`, then whitespace from both ends of the string are removed
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - Element text or empty string  
@@ -416,7 +420,8 @@ Creates xml-writer from current element
 <a name="Twig+attr"></a>
 
 ### twig.attr ⇒ <code>string</code> \| <code>number</code> \| <code>object</code>
-Returns attribute value or `null` if not found.<br>
+Returns attribute value or `null` if not found.<br>
+If more than one  matches the condition, then it returns object as [attribute()](#attribute)
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> \| <code>number</code> \| <code>object</code> - - The value of the attribute or `null` if the  does not exist  
@@ -459,7 +464,10 @@ Retrieve or update XML attribute. For update, the condition must be a string, i.
 
 **Example**  
 ```js
-attribute((name, val) => { return name === 'age' && val > 50})
+attribute((name, val) => { return name === 'age' && val > 50})
+attribute((name) => { return ['firstName', 'lastName'].includes(name) })
+attribute('firstName')
+attribute(/name/i)
 ```
 <a name="Twig+deleteAttribute"></a>
 
@@ -744,7 +752,8 @@ Deletes the current element from tree, same as `purge()`. The root object cannot
 <a name="Twig+setRoot"></a>
 
 ### twig.setRoot(name) ℗
-Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
+Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
+Used internally!
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
 **Access**: private  
@@ -925,7 +934,8 @@ Purges the current, typically used after element has been processed.<br>The root
 <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.<br>
+Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.<br>
+The `elt` object is not purged. If you like to purge including `elt`, use `.purgeUpTo(elt.previous())`
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 
@@ -947,7 +957,8 @@ Escapes special XML characters. According W3C specification these are only `&, <
 <a name="Twig+isEmpty"></a>
 
 ### twig.isEmpty ⇒ <code>boolean</code>
-Returns `true` if the element is empty, otherwise `false`.
+Returns `true` if the element is empty, otherwise `false`.
+An empty element has no text nor any child elements, however empty elements can have attributes.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>boolean</code> - true if empty element  
@@ -982,7 +993,8 @@ The position in `#children` array. For root object 0
 <a name="Twig+path"></a>
 
 ### twig.path ⇒ <code>string</code>
-The X-Path position of the element
+The X-Path position of the element
+NOTE: Applies only to currently loaded elements.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - X-Path  
@@ -1003,7 +1015,8 @@ Returns the name of the element. Synonym for `twig.name`
 <a name="Twig+text"></a>
 
 ### twig.text ⇒ <code>string</code>
-The text of the element. No matter if given as text or CDATA entity.
+The text of the element. No matter if given as text or CDATA entity.
+If option `trim: true`, then whitespace from both ends of the string are removed
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - Element text or empty string  
@@ -1082,7 +1095,8 @@ Creates xml-writer from current element
 <a name="Twig+attr"></a>
 
 ### twig.attr ⇒ <code>string</code> \| <code>number</code> \| <code>object</code>
-Returns attribute value or `null` if not found.<br>
+Returns attribute value or `null` if not found.<br>
+If more than one  matches the condition, then it returns object as [attribute()](#attribute)
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> \| <code>number</code> \| <code>object</code> - - The value of the attribute or `null` if the  does not exist  
@@ -1125,7 +1139,10 @@ Retrieve or update XML attribute. For update, the condition must be a string, i.
 
 **Example**  
 ```js
-attribute((name, val) => { return name === 'age' && val > 50})
+attribute((name, val) => { return name === 'age' && val > 50})
+attribute((name) => { return ['firstName', 'lastName'].includes(name) })
+attribute('firstName')
+attribute(/name/i)
 ```
 <a name="Twig+deleteAttribute"></a>
 
@@ -1410,7 +1427,8 @@ Deletes the current element from tree, same as `purge()`. The root object cannot
 <a name="Twig+setRoot"></a>
 
 ### twig.setRoot(name) ℗
-Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
+Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
+Used internally!
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
 **Access**: private  
@@ -1510,7 +1528,7 @@ Generic error for unsupported condition
 
 ## SAX
 **Kind**: global constant  
-**Version:**: 1.9.1  
+**Version:**: 1.9.3  
 **Author:**: Wernfried Domscheit  
 **Copyright:**: Copyright (c) 2025 Wernfried Domscheit. All rights reserved.  
 **Website:**: https://www.npmjs.com/package/xml-twig  
@@ -1593,7 +1611,9 @@ Optional settings for the Twig parser
 <a name="TwigHandler"></a>
 
 ## TwigHandler
-Reference to handler functions for Twig objects.<br> 
+Reference to handler functions for Twig objects.<br> 
+Element can be specified as string, Regular Expression, custom function, `Twig.Root` or `Twig.Any`<br> 
+You can specify a `function` or a `event` name
 
 **Kind**: global typedef  
 **Properties**
@@ -1607,7 +1627,13 @@ Reference to handler functions for Twig objects.<br>
 <a name="HandlerCondition"></a>
 
 ## HandlerCondition : <code>string</code> \| <code>Array.&lt;string&gt;</code> \| <code>RegExp</code> \| [<code>HandlerConditionFilter</code>](#HandlerConditionFilter) \| [<code>Root</code>](#Root) \| [<code>Any</code>](#Any)
-Condition to specify when handler shall be called<br> 
- If `string` then the element name must be equal to the string
- If `string[]` then the element name must be included in string array
- If `RegExp` then the element name must match the Regular Expression
- If [HandlerConditionFilter](#HandlerConditionFilter) then function must return `true`
- Use `Twig.Root` to call the handler on root element, i.e. when the end of document is reached
- Use `Twig.Any` to call the handler on every element
+Condition to specify when handler shall be called<br> 
+- If `string` then the element name must be equal to the string
+- If `string[]` then the element name must be included in string array
+- If `RegExp` then the element name must match the Regular Expression
+- If [HandlerConditionFilter](#HandlerConditionFilter) then function must return `true`
+- Use `Twig.Root` to call the handler on root element, i.e. when the end of document is reached
+- Use `Twig.Any` to call the handler on every element
 
 **Kind**: global typedef  
 <a name="HandlerFunction"></a>
@@ -1636,7 +1662,12 @@ Custom filter function to specify when handler shall be called
 <a name="ElementCondition"></a>
 
 ## ElementCondition : <code>string</code> \| <code>RegExp</code> \| [<code>ElementConditionFilter</code>](#ElementConditionFilter) \| [<code>Twig</code>](#Twig) \| <code>undefined</code>
-Optional condition to get elements<br> 
- If `undefined`, then all elements are returned.<br> 
- If `string` then the element name must be equal to the string
- If `RegExp` then the element name must match the Regular Expression
- If [ElementConditionFilter](#ElementConditionFilter) then function must return `true`
- Use [Twig](#Twig) object to find a specific element
+Optional condition to get elements<br> 
+- If `undefined`, then all elements are returned.<br> 
+- If `string` then the element name must be equal to the string
+- If `RegExp` then the element name must match the Regular Expression
+- If [ElementConditionFilter](#ElementConditionFilter) then function must return `true`
+- Use [Twig](#Twig) object to find a specific element
 
 **Kind**: global typedef  
 <a name="ElementConditionFilter"></a>
@@ -1670,7 +1701,11 @@ Custom filter function to select desired elements
 <a name="AttributeCondition"></a>
 
 ## AttributeCondition : <code>string</code> \| <code>RegExp</code> \| [<code>AttributeConditionFilter</code>](#AttributeConditionFilter)
-Optional condition to get attributes<br> 
- If `undefined`, then all attributes are returned.<br> 
- If `string` then the attribute name must be equal to the string
- If `RegExp` then the attribute name must match the Regular Expression
- If [AttributeConditionFilter](#AttributeConditionFilter) then the attribute must filter function
+Optional condition to get attributes<br> 
+- If `undefined`, then all attributes are returned.<br> 
+- If `string` then the attribute name must be equal to the string
+- If `RegExp` then the attribute name must match the Regular Expression
+- If [AttributeConditionFilter](#AttributeConditionFilter) then the attribute must filter function
 
 **Kind**: global typedef  
 <a name="AttributeConditionFilter"></a>

package/package.json

@@ -5,7 +5,7 @@
   },
   "name": "xml-twig",
   "description": "Node module for processing huge XML documents in tree mode",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "main": "twig.js",
   "directories": {
     "doc": "doc"
@@ -15,8 +15,8 @@
     "doc/*.md"
   ],
   "devDependencies": {
-    "jsdoc-to-markdown": "^9.1.1",
-    "luxon": "^3.6.1",
+    "jsdoc-to-markdown": "^9.1.3",
+    "luxon": "^3.7.2",
     "node-expat": "^2.4.1"
   },
   "scripts": {

package/twig.js

@@ -1,5 +1,5 @@
 /**
-* @version: 1.9.1
+* @version: 1.9.3
 * @author: Wernfried Domscheit
 * @copyright: Copyright (c) 2025 Wernfried Domscheit. All rights reserved.
 * @website: https://www.npmjs.com/package/xml-twig