tessl/npm-elementtree

XML Serialization and Parsing module based on Python's ElementTree.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

XML Serialization

Name: tessl/npm-elementtree
Author: tessl

Convert XML documents and elements to string format with comprehensive formatting and namespace options.

Capabilities

tostring Function

Serialize an individual element to XML string format.

/**
 * Serialize element to XML string
 * @param {Element} element - Element to serialize
 * @param {object} options - Serialization options
 * @returns {string} XML string representation
 */
function tostring(element, options);

Usage Examples:

const et = require('elementtree');

const element = et.Element('item', {id: '123'});
element.text = 'Hello World';

// Basic serialization
const xml = et.tostring(element);
console.log(xml);
// Output: <?xml version='1.0' encoding='utf-8'?>
// <item id="123">Hello World</item>

// Without XML declaration
const xmlNoDecl = et.tostring(element, {xml_declaration: false});
console.log(xmlNoDecl);
// Output: <item id="123">Hello World</item>

ElementTree Write Method

Serialize an entire ElementTree document to XML string format.

/**
 * Serialize ElementTree to XML string
 * @param {object} options - Serialization options
 * @returns {string} XML string representation of entire document
 */
write(options): string;

Usage Examples:

const et = require('elementtree');

const root = et.Element('root');
const child = et.SubElement(root, 'child');
child.text = 'Content';

const etree = new et.ElementTree(root);

// Basic serialization
const xml = etree.write();
console.log(xml);
// Output: <?xml version='1.0' encoding='utf-8'?>
// <root><child>Content</child></root>

Serialization Options

Comprehensive options for controlling XML output format.

interface WriteOptions {
  /** Output encoding, default: 'utf-8' */
  encoding?: string;
  
  /** Include XML declaration, default: true */
  xml_declaration?: boolean;
  
  /** Default namespace URI */
  default_namespace?: string;
  
  /** Serialization method: 'xml' or 'text', default: 'xml' */
  method?: string;
  
  /** Number of spaces for indentation (enables pretty printing) */
  indent?: number;
}

Pretty Printing

Format XML with indentation for improved readability.

Usage Examples:

const et = require('elementtree');

const root = et.Element('library');
const book = et.SubElement(root, 'book', {id: '1'});
const title = et.SubElement(book, 'title');
title.text = 'JavaScript Guide';
const author = et.SubElement(book, 'author');
author.text = 'John Doe';

const etree = new et.ElementTree(root);

// Pretty print with 2-space indentation
const prettyXml = etree.write({indent: 2});
console.log(prettyXml);
/* Output:
<?xml version='1.0' encoding='utf-8'?>
<library>
  <book id="1">
    <title>JavaScript Guide</title>
    <author>John Doe</author>
  </book>
</library>
*/

// Pretty print with 4-space indentation
const prettyXml4 = etree.write({indent: 4});
console.log(prettyXml4);
/* Output:
<?xml version='1.0' encoding='utf-8'?>
<library>
    <book id="1">
        <title>JavaScript Guide</title>
        <author>John Doe</author>
    </book>
</library>
*/

XML Declaration Control

Control whether to include the XML declaration.

Usage Examples:

const et = require('elementtree');

const element = et.Element('data');
element.text = 'content';

// With XML declaration (default)
const withDeclaration = et.tostring(element);
console.log(withDeclaration);
// Output: <?xml version='1.0' encoding='utf-8'?>
// <data>content</data>

// Without XML declaration
const withoutDeclaration = et.tostring(element, {xml_declaration: false});
console.log(withoutDeclaration);
// Output: <data>content</data>

// Explicitly enable XML declaration
const explicitDeclaration = et.tostring(element, {xml_declaration: true});
console.log(explicitDeclaration);
// Same as default behavior

Encoding Options

Specify character encoding for XML output.

Usage Examples:

const et = require('elementtree');

const element = et.Element('data');
element.text = 'content';

// Default UTF-8 encoding
const utf8 = et.tostring(element);
console.log(utf8);
// Output: <?xml version='1.0' encoding='utf-8'?>
// <data>content</data>

// Custom encoding
const iso = et.tostring(element, {encoding: 'iso-8859-1'});
console.log(iso);
// Output: <?xml version='1.0' encoding='iso-8859-1'?>
// <data>content</data>

Namespace Serialization

Handle XML namespaces during serialization.

Usage Examples:

const et = require('elementtree');

// Register namespace prefix
et.register_namespace('custom', 'http://example.com/custom');

// Create namespaced element
const nsElement = et.Element('{http://example.com/custom}item');
nsElement.text = 'namespaced content';

const xml = et.tostring(nsElement, {xml_declaration: false});
console.log(xml);
// Output: <custom:item xmlns:custom="http://example.com/custom">namespaced content</custom:item>

// With default namespace
const rootWithDefaultNs = et.Element('root');
const child = et.SubElement(rootWithDefaultNs, 'child');
child.text = 'content';

const etree = new et.ElementTree(rootWithDefaultNs);
const xmlWithDefaultNs = etree.write({
  xml_declaration: false,
  default_namespace: 'http://example.com/default'
});
console.log(xmlWithDefaultNs);
// Output: <root xmlns="http://example.com/default"><child>content</child></root>

Text-only Serialization

Extract only text content without XML markup.

Usage Examples:

const et = require('elementtree');

const root = et.Element('document');
const p1 = et.SubElement(root, 'paragraph');
p1.text = 'First paragraph.';
const p2 = et.SubElement(root, 'paragraph');
p2.text = 'Second paragraph.';

const etree = new et.ElementTree(root);

// Text-only serialization
const textOnly = etree.write({
  method: 'text',
  xml_declaration: false
});
console.log(textOnly);
// Output: First paragraph.Second paragraph.

Character Escaping

ElementTree automatically handles XML character escaping.

Usage Examples:

const et = require('elementtree');

const element = et.Element('data');
element.text = 'Text with <special> & "quoted" characters\nand newlines';
element.set('attr', 'Value with & < > " characters');

const xml = et.tostring(element, {xml_declaration: false});
console.log(xml);
// Output: <data attr="Value with &amp; &lt; &gt; &quot; characters">Text with &lt;special&gt; &amp; "quoted" characters
// and newlines</data>

Self-closing Tags

Empty elements are automatically serialized as self-closing tags.

Usage Examples:

const et = require('elementtree');

const root = et.Element('root');
const empty = et.SubElement(root, 'empty');
const withText = et.SubElement(root, 'withText');
withText.text = 'content';
const withAttr = et.SubElement(root, 'withAttr', {id: '123'});

const xml = et.tostring(root, {xml_declaration: false, indent: 2});
console.log(xml);
/* Output:
<root>
  <empty />
  <withText>content</withText>
  <withAttr id="123" />
</root>
*/

Complex Serialization Example

Comprehensive example showing multiple serialization features.

const et = require('elementtree');

// Register custom namespace
et.register_namespace('book', 'http://example.com/book');

// Create complex document
const library = et.Element('library');
library.set('version', '2.0');

const metadata = et.SubElement(library, 'metadata');
const created = et.SubElement(metadata, 'created');
created.text = '2024-01-01';

const books = et.SubElement(library, 'books');

// Add namespaced book
const book1 = et.SubElement(books, '{http://example.com/book}book');
book1.set('isbn', '978-0123456789');
const title1 = et.SubElement(book1, 'title');
title1.text = 'Advanced JavaScript & Node.js';

// Add regular book
const book2 = et.SubElement(books, 'book');
book2.set('isbn', '978-9876543210');
const title2 = et.SubElement(book2, 'title');
title2.text = 'Web Development <Essentials>';

const etree = new et.ElementTree(library);

// Serialize with pretty printing
const xml = etree.write({
  indent: 2,
  xml_declaration: true,
  encoding: 'utf-8'
});

console.log(xml);
/* Output:
<?xml version='1.0' encoding='utf-8'?>
<library version="2.0">
  <metadata>
    <created>2024-01-01</created>
  </metadata>
  <books>
    <book:book isbn="978-0123456789" xmlns:book="http://example.com/book">
      <title>Advanced JavaScript &amp; Node.js</title>
    </book:book>
    <book isbn="978-9876543210">
      <title>Web Development &lt;Essentials&gt;</title>
    </book>
  </books>
</library>
*/

Install with Tessl CLI