xastscript

xast utility to create trees

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
xastscript
904.0.09 months ago4 years agoMinified + gzip package size for xastscript in KB

Popular Searches

Readme

xastscript
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
xast utility to create trees with ease.

Contents

*   [`x(name?[, attributes][, …children])`](#xname-attributes-children)
*   [`Attributes`](#attributes-1)
*   [`Child`](#child)
*   [`Result`](#result)

What is this?

This package is a hyperscript interface (like createElement from React and such) to help with creating xast trees.

When should I use this?

You can use this utility in your project when you generate xast syntax trees with code. It helps because it replaces most of the repetition otherwise needed in a syntax tree with function calls.
You can instead use unist-builderu when creating any unist nodes and hastscripth when creating hast (HTML) nodes.

Install

This package is ESM onlyesm. In Node.js (version 16+), install with npm:
npm install xastscript

In Deno with esm.shesmsh:
import {x} from 'https://esm.sh/xastscript@4'

In browsers with esm.shesmsh:
<script type="module">
  import {x} from 'https://esm.sh/xastscript@4?bundle'
</script>

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

This package exports the identifier xapi-x. There is no default export.
The export map supports the automatic JSX runtime. You can pass xastscript to your build tool (TypeScript, Babel, SWC) with an importSource option or similar.

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

Create xast trees.
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 Elementelement is built. When nullish, a Rootroot is built instead.
attributes
Attributes of the element (Attributesapi-attributes, optional).
children
Children of the node (Array<Child>api-child or Child, optional).
Returns
Created tree (Resultapi-result).
Elementelement when a name is passed, otherwise Rootroot.

Attributes

Map of attributes (TypeScript type).
Nullish (null or undefined) or NaN values are ignored, other values are turned to strings.
Type
type Attributes = Record<string, boolean | number | string | null | undefined>

Child

(Lists of) children (TypeScript type).
When strings or numbers are encountered, they are turned into Texttext nodes. Rootroot nodes are treated as “fragments”, meaning that their children are used instead.
Type
type Child =
  | Array<Node | boolean | number | string | null | undefined>
  | Node
  | boolean
  | number
  | string
  | null
  | undefined

Result

Result from a x call (TypeScript type).
Type
type Result = Element | Root

Syntax tree

The syntax tree is xast.

JSX

This package can be used with JSX. You should use the automatic JSX runtime set to xastscript.
🪦 Legacy: you can also use the classic JSX runtime, but this is not recommended. To do so, import x yourself and define it as the pragma (plus set the fragment to null).

The Use example above (omitting the second) can then be written like so:
/** @jsxImportSource xastscript */

import {u} from 'unist-builder'

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>
  </>
)

Types

This package is fully typed with TypeScript. It exports the additional types Attributesapi-attributes, Childapi-child, and Resultapi-result.

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, xastscript@^4, compatible with Node.js 16.

Security

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

Related

— create any unist tree
— create a hast tree
— serialize xast as XML
— parse xast from XML
— transform hast to xast

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