Support expanding XML entities

README.md

@@ -129,6 +129,15 @@ for every tag and it takes some time.
 The result is an object associating the attribute names (as object keys)
 to their attribute values (as object values).
 
+#### `Saxophone.parseEntities(text)`
+
+Parses a piece of XML text and expands all XML entities inside it to
+the character they represent. Just like attributes, this is not
+parsed automatically because it takes some time.
+
+This ignores invalid entities, including unrecognized ones, leaving them
+as-is.
+
 ### Events
 
 #### `tagopen`
@@ -166,6 +175,8 @@ instruction is passed.
 
 Emitted when a text node between two tags is parsed.
 An object with the `contents` of the text node is passed.
+You might need to expand XML entities inside the contents of
+the text node, using `Saxophone.parseEntities`.
 
 #### `cdata`
 

lib/index.js

@@ -25,3 +25,4 @@ const saxophonePrototype = Object.assign(
 
 // load the static properties and methods
 require('./static/attrs')(Saxophone);
+require('./static/entities')(Saxophone);

lib/static/entities.js

@@ -0,0 +1,71 @@
+const parseEntities = input => {
+    let position = 0, next = 0;
+    const parts = [];
+
+    while ((next = input.indexOf('&', position)) !== -1) {
+        // remember anything there was before the entity
+        if (next > position) {
+            parts.push(input.slice(position, next));
+        }
+
+        const end = input.indexOf(';', next);
+
+        // ignore unterminated entities
+        if (end === -1) {
+            break;
+        }
+
+        const entity = input.slice(next, end);
+
+        if (entity === '&quot') {
+            parts.push('"');
+        } else if (entity === '&amp') {
+            parts.push('&');
+        } else if (entity === '&apos') {
+            parts.push("'");
+        } else if (entity === '&lt') {
+            parts.push('<');
+        } else if (entity === '&gt') {
+            parts.push('>');
+        } else {
+            // ignore unrecognized character entities
+            if (entity[1] !== '#') {
+                parts.push(entity + ';');
+            } else {
+                // hexadecimal numeric entities
+                if (entity[2] == 'x') {
+                    const value = parseInt(entity.slice(3), 16);
+
+                    // ignore non-numeric numeric entities
+                    if (isNaN(value)) {
+                        parts.push(entity + ';');
+                    } else {
+                        parts.push(String.fromCharCode(value));
+                    }
+                } else {
+                    // decimal numeric entities
+                    const value = parseInt(entity.slice(2), 10);
+
+                    // ignore non-numeric numeric entities
+                    if (isNaN(value)) {
+                        parts.push(entity + ';');
+                    } else {
+                        parts.push(String.fromCharCode(value));
+                    }
+                }
+            }
+        }
+
+        position = end + 1;
+    }
+
+    if (position < input.length) {
+        parts.push(input.slice(position));
+    }
+
+    return parts.join('');
+};
+
+module.exports = Saxophone => {
+    Saxophone.parseEntities = parseEntities;
+};

lib/static/entities.test.js

@@ -0,0 +1,26 @@
+const test = require('tape');
+const Saxophone = require('../');
+
+test('should normalize character entity references', assert => {
+    assert.equal(Saxophone.parseEntities('"Run!", he said'), '"Run!", he said', 'normalize "');
+    assert.equal(Saxophone.parseEntities('& On & On & On'), '& On & On & On', 'normalize &');
+    assert.equal(Saxophone.parseEntities('J'irai demain'), "J'irai demain", 'normalize '');
+    assert.equal(Saxophone.parseEntities('&lt;thisIsNotATag&gt;'), '<thisIsNotATag>', 'normalize &gt; and &lt;');
+    assert.equal(Saxophone.parseEntities('&lt;&gt;&quot;&amp;&amp;&quot;&apos;&gt;'), '<>"&&"\'>', 'normalize several');
+    assert.end();
+});
+
+test('should normalize numeric character references', assert => {
+    assert.equal(Saxophone.parseEntities('&#xA7;'), '§', 'normalize hexadecimal entities');
+    assert.equal(Saxophone.parseEntities('&#167;'), '§', 'normalize decimal entities');
+    assert.equal(Saxophone.parseEntities('&#8258;&#x2612;&#12291;&#x2E3B;'), '⁂☒〃⸻', 'normalize mixed entities');
+    assert.end();
+});
+
+test('should ignore invalid character entity references', assert => {
+    assert.equal(Saxophone.parseEntities('&unknown;'), '&unknown;', 'ignore unknown entity references');
+    assert.equal(Saxophone.parseEntities('&amp'), '&amp', 'ignore unterminated entity references');
+    assert.equal(Saxophone.parseEntities('&#notanumber;'), '&#notanumber;', 'ignore non-numeric decimal character refrences');
+    assert.equal(Saxophone.parseEntities('&#xnotanumber;'), '&#xnotanumber;', 'ignore non-numeric hexa character refrences');
+    assert.end();
+});