xml-twig 1.9.0 → 1.9.1

package/doc/twig.md

@@ -127,6 +127,7 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.children](#Twig+children) : [<code>Array.&lt;Twig&gt;</code>](#Twig) ℗
     * [.parent](#Twig+parent) : [<code>Twig</code>](#Twig) \| <code>undefined</code> ℗
     * [.pinned](#Twig+pinned) : <code>boolean</code> ℗
+    * [.trim](#Twig+trim) : <code>boolean</code> ℗
     * [.purge](#Twig+purge)
     * [.purgeUpTo](#Twig+purgeUpTo)
     * [.escapeEntity](#Twig+escapeEntity)
@@ -240,6 +241,13 @@ The parent object. Undefined on root element
 ### twig.pinned : <code>boolean</code> ℗
 Determines whether twig is needed in partial load
 
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Access**: private  
+<a name="Twig+trim"></a>
+
+### twig.trim : <code>boolean</code> ℗
+Determines whether text is trimmed
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
 <a name="Twig+purge"></a>
@@ -251,8 +259,7 @@ 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>
-The `elt` object is not purged. If you like to purge including `elt`, use `.purgeUpTo(elt.previous())`
+Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.<br>
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 
@@ -274,8 +281,7 @@ 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`.
-An empty element has no text nor any child elements, however empty elements can have attributes.
+Returns `true` if the element is empty, otherwise `false`.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>boolean</code> - true if empty element  
@@ -310,8 +316,7 @@ 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
-NOTE: Applies only to currently loaded elements.
+The X-Path position of the element
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - X-Path  
@@ -332,7 +337,7 @@ 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.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - Element text or empty string  
@@ -411,8 +416,7 @@ 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>
-If more than one  matches the condition, then it returns object as [attribute()](#attribute)
+Returns attribute value or `null` if not found.<br>
 
 **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  
@@ -455,10 +459,7 @@ 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) => { return ['firstName', 'lastName'].includes(name) })
-attribute('firstName')
-attribute(/name/i)
+attribute((name, val) => { return name === 'age' && val > 50})
 ```
 <a name="Twig+deleteAttribute"></a>
 
@@ -743,8 +744,7 @@ 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>
-Used internally!
+Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
 **Access**: private  
@@ -793,6 +793,7 @@ Common function to filter Twig element
     * [.children](#Twig+children) : [<code>Array.&lt;Twig&gt;</code>](#Twig) ℗
     * [.parent](#Twig+parent) : [<code>Twig</code>](#Twig) \| <code>undefined</code> ℗
     * [.pinned](#Twig+pinned) : <code>boolean</code> ℗
+    * [.trim](#Twig+trim) : <code>boolean</code> ℗
     * [.purge](#Twig+purge)
     * [.purgeUpTo](#Twig+purgeUpTo)
     * [.escapeEntity](#Twig+escapeEntity)
@@ -906,6 +907,13 @@ The parent object. Undefined on root element
 ### twig.pinned : <code>boolean</code> ℗
 Determines whether twig is needed in partial load
 
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Access**: private  
+<a name="Twig+trim"></a>
+
+### twig.trim : <code>boolean</code> ℗
+Determines whether text is trimmed
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
 <a name="Twig+purge"></a>
@@ -917,8 +925,7 @@ 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>
-The `elt` object is not purged. If you like to purge including `elt`, use `.purgeUpTo(elt.previous())`
+Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.<br>
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 
@@ -940,8 +947,7 @@ 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`.
-An empty element has no text nor any child elements, however empty elements can have attributes.
+Returns `true` if the element is empty, otherwise `false`.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>boolean</code> - true if empty element  
@@ -976,8 +982,7 @@ 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
-NOTE: Applies only to currently loaded elements.
+The X-Path position of the element
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - X-Path  
@@ -998,7 +1003,7 @@ 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.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - Element text or empty string  
@@ -1077,8 +1082,7 @@ 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>
-If more than one  matches the condition, then it returns object as [attribute()](#attribute)
+Returns attribute value or `null` if not found.<br>
 
 **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  
@@ -1121,10 +1125,7 @@ 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) => { return ['firstName', 'lastName'].includes(name) })
-attribute('firstName')
-attribute(/name/i)
+attribute((name, val) => { return name === 'age' && val > 50})
 ```
 <a name="Twig+deleteAttribute"></a>
 
@@ -1409,8 +1410,7 @@ 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>
-Used internally!
+Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
 **Access**: private  
@@ -1510,7 +1510,7 @@ Generic error for unsupported condition
 
 ## SAX
 **Kind**: global constant  
-**Version:**: 1.9.0  
+**Version:**: 1.9.1  
 **Author:**: Wernfried Domscheit  
 **Copyright:**: Copyright (c) 2025 Wernfried Domscheit. All rights reserved.  
 **Website:**: https://www.npmjs.com/package/xml-twig  
@@ -1593,9 +1593,7 @@ Optional settings for the Twig parser
 <a name="TwigHandler"></a>
 
 ## TwigHandler
-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
+Reference to handler functions for Twig objects.<br> 
 
 **Kind**: global typedef  
 **Properties**
@@ -1609,13 +1607,7 @@ You can specify a `function` or a `event` name
 <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
- 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> 
 
 **Kind**: global typedef  
 <a name="HandlerFunction"></a>
@@ -1644,12 +1636,7 @@ 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
- 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> 
 
 **Kind**: global typedef  
 <a name="ElementConditionFilter"></a>
@@ -1683,11 +1670,7 @@ 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
- 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> 
 
 **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.0",
+  "version": "1.9.1",
   "main": "twig.js",
   "directories": {
     "doc": "doc"

package/twig.js

@@ -1,5 +1,5 @@
 /**
-* @version: 1.9.0
+* @version: 1.9.1
 * @author: Wernfried Domscheit
 * @copyright: Copyright (c) 2025 Wernfried Domscheit. All rights reserved.
 * @website: https://www.npmjs.com/package/xml-twig
@@ -278,6 +278,12 @@ function createParser(handler, options = {}) {
       enumerable: true
    });
 
+   Object.defineProperty(parser, 'trimText', {
+      value: options.trim,
+      writable: false,
+      enumerable: true
+   });
+
    if (options.file != null) {
       Object.defineProperty(parser, 'file', {
          value: options.file,
@@ -289,7 +295,7 @@ function createParser(handler, options = {}) {
    // Common events
    parser.on('text', function (str) {
       if (parser.twig.current === null) return;
-      parser.twig.current.text = options.trim ? str.trim() : str;
+      parser.twig.current.text = str;
    });
 
    parser.on("comment", function (str) {
@@ -513,6 +519,12 @@ class Twig {
    */
    #pinned = false;
 
+   /**
+    * Determines whether text is trimmed
+   * @type {boolean}
+   */
+   #trim = true;
+
    /**
    * Create a new Twig object
    * @param {Parser} parser - The main parser object
@@ -525,6 +537,7 @@ class Twig {
       if (index === undefined)
          parser.twig.current = this;
 
+      this.#trim = parser.trimText;
       if (name === null) {
          // Root element not available yet
          parser.twig.tree = this;
@@ -698,11 +711,15 @@ class Twig {
    }
 
    /**
-   * 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
    * @returns {string} Element text or empty string
    */
    get text() {
-      return this.#text ?? '';
+      if (this.#text === null)
+         return ''
+      else
+         return this.#trim ? this.#text.trim() : this.#text;
    }
 
    /**