xast-util-to-xml

xast utility to serialize to XML

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
xast-util-to-xml
4.0.09 months ago4 years agoMinified + gzip package size for xast-util-to-xml in KB

Popular Searches

Readme

xast-util-to-xml
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
xast utility to serialize as XML.

Contents

*   [`toXml(tree[, options])`](#toxmltree-options)
*   [`Options`](#options)
*   [`Quote`](#quote-1)
*   [`Raw`](#raw)

What is this?

This package is a utility that turns a xast tree into a string of XML.

When should I use this?

You can use this utility when you want to get the serialized XML that is represented by the syntax tree, either because you’re done with the syntax tree, or because you’re integrating with another tool that does not support syntax trees.
This utility has options to configure how the XML is serialized. These options help when building tools that make output pretty (such as formatters) or ugly (such as minifiers).
The utility xast-util-from-xmlxast-util-from-xml does the inverse of this utility. It turns XML into xast.
The utility hast-util-to-htmlhast-util-to-html does the same as this utility but for HTML: it turns hast into HTML.

Install

This package is ESM onlyesm. In Node.js (version 16+), install with npm:
npm install xast-util-to-xml

In Deno with esm.shesmsh:
import {toXml} from 'https://esm.sh/xast-util-to-xml@4'

In browsers with esm.shesmsh:
<script type="module">
  import {toXml} from 'https://esm.sh/xast-util-to-xml@4?bundle'
</script>

Use

import {u} from 'unist-builder'
import {x} from 'xastscript'
import {toXml} from 'xast-util-to-xml'

const tree = u('root', [
  u('instruction', {name: 'xml'}, 'version="1.0" encoding="utf-8"'),
  u('text', '\n'),
  x('ncx', {xmlns: 'http://www.daisy.org/z3986/2005/ncx/', version: '2005-1'}, [
    u('text', '\n  '),
    x('head', [
      u('text', '\n    '),
      x('meta', {name: 'dtb:uid', content: 'urn:isbn:9781234567891'}),
      u('text', '\n  ')
    ]),
    u('text', '\n  '),
    x('docTitle', [x('text', 'A Christmas Carol')]),
    u('text', '\n  '),
    x('docAuthor', [x('text', 'Charles Dickens')]),
    u('text', '\n')
  ])
])

console.log(toXml(tree))

Yields:
<?xml version="1.0" encoding="utf-8"?>
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">
  <head>
    <meta name="dtb:uid" content="urn:isbn:9781234567891"></meta>
  </head>
  <docTitle><text>A Christmas Carol</text></docTitle>
  <docAuthor><text>Charles Dickens</text></docAuthor>
</ncx>

API

This package exports the identifier toXmlapi-to-xml. There is no default export.

toXml(tree[, options])

Serialize a xast tree to XML.
Parameters
— xast node(s) to serialize
— configuration
Returns
Serialized XML (string).

Options

Configuration (TypeScript type).
Fields
allowDangerousXml
Allow raw nodes and insert them as raw XML (boolean, default: false).
When false, Raw nodes are encoded.
⚠️ Danger: only set this if you completely trust the content.
closeEmptyElements
Close elements without any content with slash (/) on the opening tag instead of an end tag: <circle /> instead of <circle></circle> (boolean, default: false).
See tightClose to control whether a space is used before the slash.
quote
Preferred quote to use (Quoteapi-quote, default: '"').
quoteSmart
Use the other quote if that results in less bytes (boolean, default: false).
tightClose
Do not use an extra space when closing self-closing elements: <circle/> instead of <circle /> (boolean, default: false).
👉 Note: only used if closeEmptyElements: true.

Quote

XML quotes for attribute values (TypeScript type).
Type
type Quote = '"' | "'"

Raw

Raw (TypeScript type).
Type
import type {Data, Literal} from 'xast'

interface Raw extends Literal {
  type: 'raw'
  data?: RawData | undefined
}

export interface RawData extends Data {}

Types

This package is fully typed with TypeScript. It exports the additional types Optionsapi-options, Quoteapi-quote, and Rawapi-raw.
It also registers the node type with @types/xast. If you’re working with the syntax tree, make sure to import this utility somewhere in your types, as that registers the new node types in the tree.
/**
 * @typedef {import('xast-util-to-xml')}
 */

import {visit} from 'unist-util-visit'

/** @type {import('xast').Root} */
const tree = getXastNodeSomeHow()

visit(tree, function (node) {
  // `node` can now be a raw node.
})

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, xast-util-to-xml@^4, compatible with Node.js 16.

Security

XML can be a dangerous language: don’t trust user-provided data.

Related

— parse from xml
— transform hast (html, svg) to xast (xml)
— create xast trees

Contribute

See contributing.mdcontributing in syntax-tree/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MITlicense © Titus Wormerauthor