xastscript

xast utility to create XML trees (like hastscript for hast and unist-builder for unist).

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install xastscript

Use

import {u} from 'unist-builder'
import {x} from 'xastscript'

// Children as an array:
console.log(
  x('album', {id: 123}, [
    x('name', 'Born in the U.S.A.'),
    x('artist', 'Bruce Springsteen'),
    x('releasedate', '1984-04-06')
  ])
)

// Children as arguments:
console.log(
  x(
    'album',
    {id: 123},
    x('name', 'Exile in Guyville'),
    x('artist', 'Liz Phair'),
    x('releasedate', '1993-06-22')
  )
)

// For other xast nodes, such as comments, instructions, doctypes, or cdata
// can be created with unist-builder:
console.log(
  x(null, [
    u('instruction', {name: 'xml'}, 'version="1.0" encoding="UTF-8"'),
    x('album', [
      u('comment', 'Great album!'),
      x('name', 'Born in the U.S.A.'),
      x('description', [u('cdata', '3 < 5 & 8 > 13')])
    ])
  ])
)

Yields:

{
  type: 'element',
  name: 'album',
  attributes: {id: '123'},
  children: [
    {
      type: 'element',
      name: 'name',
      attributes: {},
      children: [{type: 'text', value: 'Born in the U.S.A.'}]
    },
    {
      type: 'element',
      name: 'artist',
      attributes: {},
      children: [{type: 'text', value: 'Bruce Springsteen'}]
    },
    {
      type: 'element',
      name: 'releasedate',
      attributes: {},
      children: [{type: 'text', value: '1984-04-06'}]
    }
  ]
}
{
  type: 'element',
  name: 'album',
  attributes: {id: '123'},
  children: [
    {
      type: 'element',
      name: 'name',
      attributes: {},
      children: [{type: 'text', value: 'Exile in Guyville'}]
    },
    {
      type: 'element',
      name: 'artist',
      attributes: {},
      children: [{type: 'text', value: 'Liz Phair'}]
    },
    {
      type: 'element',
      name: 'releasedate',
      attributes: {},
      children: [{type: 'text', value: '1993-06-22'}]
    }
  ]
}
{
  type: 'root',
  children: [
    {type: 'instruction', name: 'xml', value: 'version="1.0" encoding="UTF-8"'},
    {
      type: 'element',
      name: 'album',
      attributes: {},
      children: [
        {type: 'comment', value: 'Great album!'},
        {
          type: 'element',
          name: 'name',
          attributes: {},
          children: [{type: 'text', value: 'Born in the U.S.A.'}]
        },
        {
          type: 'element',
          name: 'description',
          attributes: {},
          children: [{type: 'cdata', value: '3 < 5 & 8 > 13'}]
        }
      ]
    }
  ]
}

API

x(name?[, attributes][, …children])

Create XML trees in xast.

Signatures

• x(): root
• x(null[, …children]): root
• x(name[, attributes][, …children]): element

Parameters

name

Qualified name (string, optional). Case sensitive and can contain a namespace prefix (such as rdf:RDF). When string, an Element is built. When nullish, a Root is built instead.

attributes

Map of attributes (Object.<*>, optional). Nullish (null or undefined) or NaN values are ignored, other values are turned to strings.

Cannot be given if building a Root. Cannot be omitted when building an Element if the first child is a Node.

children

(Lists of) children (string, number, Node, Array.<children>, optional). When strings or numbers are encountered, they are mapped to Text nodes. If a Root node is given, its children are used instead.

Returns

Element or Root.

JSX

xastscript can be used as a pragma for JSX. The example above (omitting the second) can then be written like so:

import {u} from 'unist-builder'
import {x} from 'xastscript'

console.log(
  <album id={123}>
    <name>Born in the U.S.A.</name>
    <artist>Bruce Springsteen</artist>
    <releasedate>1984-04-06</releasedate>
  </album>
)

console.log(
  <>
    {u('instruction', {name: 'xml'}, 'version="1.0" encoding="UTF-8"')}
    <album>
      {u('comment', 'Great album!')}
      <name>Born in the U.S.A.</name>
      <description>{u('cdata', '3 < 5 & 8 > 13')}</description>
    </album>
  </>
)

Note that you must still import xastscript yourself and configure your JavaScript compiler to use the identifier you assign it to as a pragma (and pass null for fragments).

For bublé, this can be done by setting jsx: 'x' and jsxFragment: 'null' (note that jsxFragment is currently only available on the API, not the CLI).

For Babel, use @babel/plugin-transform-react-jsx (in classic mode), and pass pragma: 'x' and pragmaFrag: 'null'.

Babel also lets you configure this in a script:

/** @jsx x @jsxFrag null */
import {x} from 'xastscript'

console.log(<music />)

For TypeScript, this can be done by setting "jsx": "react", "jsxFactory": "x", and "jsxFragmentFactory": "null" in the compiler options. For more details on configuring JSX for TypeScript, see the TypeScript JSX handbook page.

TypeScript also lets you configure this in a script:

/** @jsx x @jsxFrag null */
import {x} from 'xastscript'

console.log(<music />)

Security

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

Related

• unist-builder — Create any unist tree
• hastscript — Create a hast (HTML or SVG) unist tree
• xast-util-to-xml — Serialize nodes to XML
• xast-util-from-xml — Parse from XML
• hast-util-to-xast — Transform hast (html, svg) to xast (xml)

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer