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

Special XML Elements

Name: tessl/npm-elementtree
Author: tessl

Support for XML comments, CDATA sections, and processing instructions.

Capabilities

Comment Elements

Create XML comment elements for documentation and markup.

/**
 * Create XML comment element
 * @param {string} text - Comment text content
 * @returns {Element} Element representing XML comment
 */
function Comment(text);

Usage Examples:

const et = require('elementtree');

// Create comment
const comment = et.Comment('This is a comment');

// Add to document
const root = et.Element('root');
root.append(comment);

const xml = et.tostring(root, {xml_declaration: false});
console.log(xml);
// Output: <root><!--This is a comment--></root>

// Comment with complex text
const detailedComment = et.Comment('TODO: Add validation here');
const container = et.Element('form');
container.append(detailedComment);

const formXml = et.tostring(container, {xml_declaration: false, indent: 2});
console.log(formXml);
/* Output:
<form>
  <!--TODO: Add validation here-->
</form>
*/

CDATA Sections

Create CDATA sections for including literal text that may contain XML markup.

/**
 * Create CDATA section element
 * @param {string} text - CDATA text content
 * @returns {Element} Element representing CDATA section
 */
function CData(text);

Usage Examples:

const et = require('elementtree');

// Create CDATA section
const script = et.CData('if (x < 10 && y > 5) { alert("Hello <world>!"); }');

// Add to document
const html = et.Element('script');
html.set('type', 'text/javascript');
html.append(script);

const xml = et.tostring(html, {xml_declaration: false});
console.log(xml);
// Output: <script type="text/javascript"><![CDATA[if (x < 10 && y > 5) { alert("Hello <world>!"); }]]></script>

// CDATA with XML content
const xmlContent = et.CData('<root><item>data</item></root>');
const example = et.Element('example');
example.append(xmlContent);

const exampleXml = et.tostring(example, {xml_declaration: false});
console.log(exampleXml);
// Output: <example><![CDATA[<root><item>data</item></root>]]></example>

Processing Instructions

Create XML processing instructions for application-specific metadata.

/**
 * Create processing instruction element
 * @param {string} target - PI target name
 * @param {string} text - Optional PI text content
 * @returns {Element} Element representing processing instruction
 */
function ProcessingInstruction(target, text);

// Alias for ProcessingInstruction
const PI = ProcessingInstruction;

Usage Examples:

const et = require('elementtree');

// Create processing instruction
const stylesheet = et.ProcessingInstruction('xml-stylesheet', 'type="text/xsl" href="style.xsl"');

// Add to document
const root = et.Element('document');
root.append(stylesheet);

const xml = et.tostring(root, {xml_declaration: false});
console.log(xml);
// Output: <document><?xml-stylesheet type="text/xsl" href="style.xsl"?></document>

// Using PI alias (shorthand)
const stylesheetPI = et.PI('xml-stylesheet', 'type="text/css" href="main.css"');

// PI with just target
const simplePI = et.ProcessingInstruction('target-only');
const container = et.Element('container');
container.append(simplePI);

const containerXml = et.tostring(container, {xml_declaration: false});
console.log(containerXml);
// Output: <container><?target-only?></container>

Special Element Aliases

ElementTree provides convenient aliases for processing instructions.

// PI is an alias for ProcessingInstruction
const PI = et.PI;

// Same as et.ProcessingInstruction
const pi = PI('target', 'content');

Usage Examples:

const et = require('elementtree');

// Using PI alias
const instruction = et.PI('php', 'echo "Hello World";');

const doc = et.Element('document');
doc.append(instruction);

const xml = et.tostring(doc, {xml_declaration: false});
console.log(xml);
// Output: <document><?php echo "Hello World";?></document>

Mixed Content with Special Elements

Combine special elements with regular content for complex document structures.

Usage Examples:

const et = require('elementtree');

// Create complex document with mixed special elements
const html = et.Element('html');

// Add processing instruction
const stylesheet = et.PI('xml-stylesheet', 'type="text/css" href="styles.css"');
html.append(stylesheet);

// Add comment
const comment = et.Comment('Generated by ElementTree');
html.append(comment);

// Add regular content
const head = et.SubElement(html, 'head');
const title = et.SubElement(head, 'title');
title.text = 'Test Page';

const body = et.SubElement(html, 'body');

// Add script with CDATA
const script = et.SubElement(body, 'script');
script.set('type', 'text/javascript');
const scriptContent = et.CData(`
  function init() {
    console.log("Page loaded <script>");
    if (x < 10) { alert("Low value"); }
  }
`);
script.append(scriptContent);

// Serialize with pretty printing
const xml = et.tostring(html, {xml_declaration: false, indent: 2});
console.log(xml);
/* Output:
<html>
  <?xml-stylesheet type="text/css" href="styles.css"?>
  <!--Generated by ElementTree-->
  <head>
    <title>Test Page</title>
  </head>
  <body>
    <script type="text/javascript">
      <![CDATA[
        function init() {
          console.log("Page loaded <script>");
          if (x < 10) { alert("Low value"); }
        }
      ]]>
    </script>
  </body>
</html>
*/

Special Element Properties

Special elements are still Element instances with standard properties.

Usage Examples:

const et = require('elementtree');

// Create special elements
const comment = et.Comment('This is a comment');
const cdata = et.CData('Raw data <content>');
const pi = et.PI('target', 'instruction content');

// Check element properties
console.log(comment.tag); // [Function: Comment]
console.log(comment.text); // "This is a comment"

console.log(cdata.tag); // [Function: CData]
console.log(cdata.text); // "Raw data <content>"

console.log(pi.tag); // [Function: ProcessingInstruction]
console.log(pi.text); // "target instruction content"

// Special elements can have attributes (though rarely used)
comment.set('author', 'system');
console.log(comment.get('author')); // "system"

Empty Special Elements

Create special elements without content.

Usage Examples:

const et = require('elementtree');

// Empty comment
const emptyComment = et.Comment();
console.log(emptyComment.text); // null

// Empty CDATA
const emptyCData = et.CData();
console.log(emptyCData.text); // null

// Empty PI (target only)
const emptyPI = et.PI('target');
console.log(emptyPI.text); // "target"

// Serialize empty special elements
const root = et.Element('root');
root.append(emptyComment);
root.append(emptyCData);
root.append(emptyPI);

const xml = et.tostring(root, {xml_declaration: false});
console.log(xml);
// Output: <root><!----><![CDATA[]]><?target?></root>

Special Elements in Parsing

Special elements are preserved when parsing XML documents.

Usage Examples:

const et = require('elementtree');

const xmlWithSpecial = `
<?xml version="1.0"?>
<document>
  <!-- This is a comment -->
  <?xml-stylesheet type="text/xsl" href="style.xsl"?>
  <script><![CDATA[if (x < 10) alert("test");]]></script>
</document>
`;

const etree = et.parse(xmlWithSpecial);

// Find elements (special elements may not be preserved in all cases)
// Note: Comment and PI handling may vary depending on parser configuration
const script = etree.find('script');
console.log(script.text); // May contain CDATA content

// Reserialize
const output = etree.write({xml_declaration: false, indent: 2});
console.log(output);

Install with Tessl CLI