$3

Each element that matches a given selector is passed to the matching
function, with the signature (elm: Element) => Element | undefined,
and elements are structured as follows (as typescript):

``typescript
interface Element {
name: string
text?: string
attributes: Record
children: Element[]
}
`

$3

In addition to a rules argument, createReadStream can also take
a second Options argument. This object has the follow parameters.

`typescript
interface Options {
// Whether to check and enforce the validity of created and modified
// XML element names and attributes. If true, will throw an error
// if you create an XML element with a disallowed name (e.g.,
// ) or with an invalid attribute name
// ()
//
// This only checks the syntax of the XML element names and attributes.
// It does not perform any further validation, like if used namespaces
// are valid.
//
// default: true
validate: boolean // true

// Options defined by the "saxes" library, and passed to the "saxes" parser
//
// https://github.com/lddubeau/saxes/blob/4968bd09b5fd0270a989c69913614b0e640dae1b/src/saxes.ts#L557
// https://www.npmjs.com/package/saxes
saxes?: SaxesOptions
}

// The createXMLEditor function takes the options object as an optional
// second argument.
const transformer = createXMLEditor(rules, options)
`

Examples

Start with this input as simpsons.xml:

`xml




`javascript
import { createReadStream } from 'node:fs'
import { pipeline } from 'node:stream/promises'
import { createXMLEditor, newElement } from 'xml-stream-editor'

// The keys of this object are selector strings, and the
// values are functions that get called with matching elements.
const rules = {
"main character": (elm) => {
switch (elm.text) {
case "Marge Simpson":
elm.attributes["hair"] = "blue"
break
case "Homer Simpson":
elm.text += " (Sr.)"
break
case "Lisa Simpson":
elm.text = ""

// Create an element and make it a child element.
const instrumentElm = newElement("instrument")
instrumentElm.text = "saxophone"
elm.children.push(instrumentElm)

// Also create a new element, and also make it a child
// element.
const nameElm = newElement("name")
nameElm.text = "Lisa Simpson"
elm.children.push(nameElm)
break
case "Bart Simpson":
// Remove the node by not returning an element.
return
}
return elm
}
}
await pipeline(
createReadStream("simpsons.xml"), // above example
createXMLEditor(rules),
process.stdout
)
`

And you'll find this printed to STDOUT (reformatted and annotated):

`xml




`javascript
import { createReadStream } from 'node:fs'
import { pipeline } from 'node:stream/promises'
import { createXMLEditor, newElement } from 'xml-stream-editor'

const rules = {
// This rule will match first, since the "main" element will be
// identified first during parsing.
"main character": (elm) => {
// editing goes here
return elm
},
// And as a result, this rule will never match the "Disco Stu"
// or "Julius Hibbert" elements, since anytime the "character" selector
// would match a element, that element will
// have already been matched by the above "main character" selector.
//
// However, this selector would match (and so this function would
// be called with) the two elements that are children
// of the element.
"character": (elm) => {
// this function would never be called in this document.
return elm
},
}
await pipeline(
createReadStream("simpsons.xml"), // above example
createXMLEditor(rules),
process.stdout
)
`

Motivation