xml-twig 1.0.6 → 1.1.1

package/README.md

@@ -5,7 +5,7 @@ Inspired by Perl module [XML::Twig](https://metacpan.org/pod/XML::Twig)
 
 
 ## When should I use this, motivation of this module
-When you need to read a XML file, then you have two pinciples:
+When you need to read a XML file, then you have two principles:
 
 * The **Document Object Model (DOM)** style. These parser read the entire XML document into memory. Usually they provide easy methods to navigate in the document tree or make modifications. 
 
@@ -20,20 +20,19 @@ This module tries to combine both principles. The XML document can be read in ch
 ## Dependencies
 XML documents are read either with [sax](https://www.npmjs.com/package/sax) or [node-expat](https://www.npmjs.com/package/node-expat) parser. More parser may be added in future releases. By default the `sax` parser is used.
 
-**NOTE: The `sax` or `node-expat` module is not automatically installed with this module. Install desired parser by yourself**
+**NOTE: The `node-expat` module is not automatically installed with this module. Install the parser by yourself, if you like to use it**
 
 ## Installation
 
-Install module like any other node module and the desired underlying parser:
+Install module like any other node module and optionally `node-expat`:
 ```
 npm install xml-twig
 
-npm install sax
-# and/or
+# and optionally 
 npm install node-expat
 
 ```
-In my tests I parsed a 750 MB big XML file, the `node-expat` is around two times faster than `sax` (node-expat: 2:20 Minutes, sax: 4:20 Minutes). However, you may run into problems when you try to install the `node-expat` parser. That's the reason why underlying parsers are not installed automatically. 
+In my tests I parsed a 750 MB big XML file, the `node-expat` is around two times faster than `sax` (node-expat: 2:20 Minutes, sax: 4:20 Minutes). However, you may run into problems when you try to install the `node-expat` parser. That's the reason why `node-expat` parsers is not installed automatically. 
 
 
 ## How to use it
@@ -42,7 +41,7 @@ In my tests I parsed a 750 MB big XML file, the `node-expat` is around two times
 
 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 whenver possible to avoid confusion.
+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
@@ -52,7 +51,7 @@ With option `{ namespaces : true }` you will get access to the `.namespace` prop
 
 ### Read XML Document
 
-- Read entire XML file at once
+- **Read entire XML file at once**
 
   This module is designed to read huge XML-Files. Of course, it works also well for small files. First create the Twig parser. Then create a Stream and pipe it to the parser.
 
@@ -61,57 +60,66 @@ With option `{ namespaces : true }` you will get access to the `.namespace` prop
    const twig = require('xml-twig')
 
    function rootHandler(elt) {
-      console.log(`${elt.name} finished after ${elt.line} lines`);
+      console.log(`<${elt.name}> finished after ${parser.currentLine} lines`);
    }
 
-   const parser = twig.createParser(rootHandler)
-   fs.createReadStream(`${__dirname}/node_modules/xml-twig/samples/bookstore.xml`).pipe(parser)
-   // Output -> bookstore finished after 48 lines
+   const parser = twig.createParser({ tag: twig.Root, function: rootHandler }, { method: 'sax' })
+   fs.createReadStream(`${__dirname}/bookstore.xml`).pipe(parser)
+
+   // Output -> <bookstore> finished after 48 lines
+
 
    // Or use a Parser object instead of a Stream - works only with 'expat'!
-   const expatParser = require('./twig.js').createParser(rootHandler, { method: 'expat' })
-   expatParser.write('<html><head><title>Hello World</title></head><body><p>Foobar</p></body></html>');
+   const parser = twig.createParser({ tag: twig.Root, function: rootHandler }, { method: 'expat' })
+   parser.write('<html><head><title>Hello World</title></head><body><p>Foobar</p></body></html>');
+
    // Output -> xml finished after 1 lines
+   ```
+
+   If you prefer [events](https://nodejs.org/api/events.html), then use `event` property instead of `function` in handler declaration:
 
    ```
+   const parser = twig.createParser({ tag: twig.Root, event: 'rootElement' }, { method: 'sax' })
+   fs.createReadStream(`${__dirname}/bookstore.xml`).pipe(parser)
 
-- Read XML Document in chucks
+   parser.on('rootElement', (elt) => {
+      console.log(`<${elt.name}> finished after ${parser.currentLine} lines`);
+   })
+   ```
+
+
+- **Read XML Document in chucks**
   
-  The key feature of this module is to read XML files and process it in chunks. You need to create handler function for elements you like to process. If you don't specify any `name` property, then handler is called on every element.
+  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.
 
 
    ```
-   const fs = require('fs')
-   const twig = require('xml-twig')
-
    function bookHandler(elt) {
-      console.log(`${elt.attr("category")} ${elt.name} at line ${elt.line}`)
+      console.log(`${elt.attr("category")} ${elt.name} at line ${parser.currentLine}`)
       elt.purge() // -> without `purge()` the entire XML document will be loaded into memory
    }
 
    // different styles: below `handle_book` are all equivalent (with sample file `bookstore.xml`)
    handle_book = [
-      { name: 'book', function: bookHandler },
-      { name: 'ebook', function: bookHandler }
-   ];
-   handle_book = [
-      { name: /book$/, function: bookHandler }
+      { tag: 'book', function: bookHandler },
+      { tag: 'ebook', function: bookHandler }
    ];
+   handle_book = { tag: /book$/, function: bookHandler };
    handle_book = [{
-      name: function(name,elt) { return name.endsWith('book') },
+      tag: function(name, elt) { return name.endsWith('book') },
       function: bookHandler
    }];
    handle_book = [{
-      name: function(name,elt) { return ['book', 'ebook'].includes(name) },
+      tag: function(name, elt) { return ['book', 'ebook'].includes(name) },
       function: bookHandler
    }];
    handle_book = [{
-      name: function(name,elt) { return ['book', 'ebook'].includes(elt.name) },
+      tag: function(name, elt) { return ['book', 'ebook'].includes(elt.name) },
       function: bookHandler
    }];
 
-   const parser = twig.createParser(handle_book)
-   fs.createReadStream(`${__dirname}/node_modules/xml-twig/samples/bookstore.xml`).pipe(parser)
+   const parser = twig.createParser(handle_book, { method: 'sax' })
+   fs.createReadStream(`${__dirname}/bookstore.xml`).pipe(parser)
 
    Output: 
    
@@ -123,32 +131,18 @@ With option `{ namespaces : true }` you will get access to the `.namespace` prop
    web book at line 48
    ```
 
-- Read every element from XML Document
-
-  Skip the `name` proeprty if you like to read every element one-by-one:
-
-
+- **Read every element from XML Document**
+  
    ```
-   const fs = require('fs')
-   const twig = require('xml-twig')
-
    function anyHandler(elt) {
-      console.log(`${'  '.repeat(elt.level)}${elt.name} => "${elt.text ?? ''}" at line ${elt.line}`)
+      console.log(`${'  '.repeat(elt.level)}${elt.name} => "${elt.text ?? ''}" at line ${parser.currentLine}`)
       elt.purge() // -> without `purge()` the entire XML document will be loaded into memory
-
-      // Be aware if you run methods like `elt.followingSibling()`, `elt.descendant()`, `elt.next()`, etc. on the current element.
-      // Such calls return emtpy result, because following element are not yet read from the XML file.
-      // You must navigate to an earlier element, e.g. 
-      `elt.root().children()[0].followingSibling()`
    }
 
-   const handle_any = [ { function: anyHandler } ];
-   
-   // or use regular expression which matches every element, if you prefer
-   const handle_any = [ { name: /./, function: anyHandler } ];
-
-   const parser = twig.createParser(handle_any)
-   fs.createReadStream(`${__dirname}/node_modules/xml-twig/samples/bookstore.xml`).pipe(parser)
+   const parser = twig.createParser({ tag: twig.Any, function: anyHandler }) 
+   // or with Regular Expression -> `{ tag: /i/, function: anyHandler }` 
+   // or with Function -> `{ tag: () => {return true}, function: anyHandler }`
+   fs.createReadStream(`${__dirname}/bookstore.xml`).pipe(parser)
 
    Output: 
 
@@ -167,51 +161,58 @@ With option `{ namespaces : true }` you will get access to the `.namespace` prop
 
    ```
 
+Be aware if you run methods like `elt.followingSibling()`, `elt.descendant()`, `elt.next()`, etc. on the current element. Such calls return empty result, because following element are not yet read from the XML file. You must navigate to an earlier element, e.g.<br>
+`elt.root().children()[0].followingSibling()`
 
-- Read only parts from XML Document
 
-   If you like to read only certain elements, use option `partial: true`. The `root` element is always read. 
+- **Read only parts from XML Document**
 
+   If you like to read only certain elements, use option `partial: true`. The `root` element is always read. 
 
-   This sample program reads the `root` element and `<ebook>` elements (include their children elements), and the brances to reach the element.
+   This sample program reads the `root` element and `<ebook>` elements (include their children elements), and the branches to reach the element.
 
    ```
-   const handle_ebook = [{ name: 'ebook', function: ebookHandler }];
-   const parser = require('./twig.js').createParser(handle_ebook, { partial: true })
-   fs.createReadStream(`${__dirname}/samples/bookstore.xml`).pipe(parser);
+   const handle_ebook = [
+      { tag: 'ebook', function: ebookHandler },
+      { tag: twig.Root, function: rootHandler }
+   ];
+   const parser = twig.createParser(handle_ebook, { partial: true })
+   fs.createReadStream(`${__dirname}/bookstore.xml`).pipe(parser);
 
    function ebookHandler(elt) {
-      console.log( elt.root().writer('  ').toString() );
-      elt.purge();
+      console.log(`${elt.name} at line ${parser.currentLine}`)
+   }
+
+   function rootHandler(elt) {
+      console.log( elt.writer('  ').toString() );
    }
 
+
    Output:
 
+   ebook at line 23
+   ebook at line 41
    <bookstore>
      <ebook category="fantasy">
-        <title lang="en">Harry Potter</title>
-        <author>Joanne Kathleen Rowling</author>
-        <year>2001</year>
-        <price>12.99</price>
-        <format>Kindle</format>
-        <device>ePub</device>
+       <title lang="en">Harry Potter</title>
+       <author>Joanne Kathleen Rowling</author>
+       <year>2001</year>
+       <price>12.99</price>
+       <format>Kindle</format>
+       <device>ePub</device>
      </ebook>
-   </bookstore>
-
-   <bookstore>
      <ebook category="biography">
-        <title lang="en">The Autobiography of Benjamin Franklin</title>
-        <author>Benjamin Franklin</author>
-        <year>1996</year>
-        <price>39.99</price>
-        <format>Kindle</format>
-        <device>ePub</device>
+       <title lang="en">The Autobiography of Benjamin Franklin</title>
+       <author>Benjamin Franklin</author>
+       <year>1996</year>
+       <price>39.99</price>
+       <format>Kindle</format>
+       <device>ePub</device>
      </ebook>
    </bookstore>
-
    ```
 
-For details about other options, see [ParserOptions](./doc/twig.md#ParserOptions)
+For details and other options, see [ParserOptions](./doc/twig.md#ParserOptions) and [TwigHandler](./doc/twig.md#TwigHandler)
 
 
 ### Access elements and attributes
@@ -220,9 +221,9 @@ For details about other options, see [ParserOptions](./doc/twig.md#ParserOptions
 
 `.hasAttribute(name)`: Checks if the attribute exists and returns `true` or `false`
 
-`.attr(cond)`: Returns the value of attribute. If more than one attribute matches, then it returns all attributes as object
+`.attr(condition)`: Returns the value of attribute. If more than one attribute matches, then it returns all attributes as object
 
-`.attribute(cond)`: Get attributes as object or `null` if no matching attribute was found. If `cond` is `undefined`, then all attributes are returned.
+`.attribute(condition)`: Get attributes as object or `null` if no matching attribute was found. If `condition` is `undefined`, then all attributes are returned.
 
    Specify attribute name or regular expression or custom condition. For details see [AttributeCondition](./doc/twig.md#AttributeCondition).<br>
    Let's assume an XML element like this: `<person firstName="Jean-Luc", lastName="Picard", age="59" />` 
@@ -288,7 +289,7 @@ Here are some examples the get attribute and values:
 
 `.find(condition)` - **Twig**: Find a specific element in current element and returns the first match. In principle `.descendant(condition)[0]`
 
-`.purge()` - void: Removes the current element from tree. Usually this methond is called after the element has been processed and when not needed anymore.
+`.purge()` - void: Removes the current element from tree. Usually this method is called after the element has been processed and when not needed anymore.
 
 `.purgeUpTo(elt)` - void: Purges up to the elt element. This allows you to keep part of the tree in memory when you purge. 
 
@@ -308,11 +309,11 @@ You can specify condition on above methods. You can filter elements by following
 
   Example: `/book$/i`
 
-- With `ElementConditionFilter` you can speficy any custom filter function.<br>
+- 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 direclty. 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.
 
   Example: `elt.children()[2]`
 
@@ -326,7 +327,7 @@ For methods which return a single **Twig** element (e.g. `elt.next("book")`) the
 
 #### Twig Properties
 
-`.isEmpty` - **boolean**: `true` if emtpy. An empty element ha no text nor any child elements, however empty elements can have attributes.
+`.isEmpty` - **boolean**: `true` if empty. An empty element ha no text nor any child elements, however empty elements can have attributes.
 
 `.level` - **integer**: The level of the element. Root element has 0, children have 1, grand-children 2 and so on
 
@@ -338,15 +339,11 @@ 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
 
-`.line` - **integer**: The line of the element (where the closing tag appears) in the XML-File. First line is 1
-
-`.column` - **integer**: The column of the element (where the closing tag appears) in the XML-File. First column is 1
-
 `.name` - **string**: Name of the element/tag
 
 `.tag` - **string**: Synonym for `name`
 
-`.text` - **string**: The text of an element, no matter if given as CDATA entitiy or plain character data node (PCDATA)
+`.text` - **string**: The text of an element, no matter if given as CDATA entity or plain character data node (PCDATA)
 
 `.attributes` - **object**: All attributes of the object
 
@@ -367,7 +364,7 @@ For methods which return a single **Twig** element (e.g. `elt.next("book")`) the
 
 ## 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. Create/update/delete methods are rather limited. Perhaps I will add it in later release.
+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.
 
 Accessing Twig-Elements by [XML-Path](https://www.w3.org/TR/xpath/) language is not supported. One reason it, the `Twig` class models more an [Element](https://www.w3schools.com/xml/xml_elements.asp) rather than a [Node](https://www.w3schools.com/xml/dom_nodes.asp) which would be more generic.