syntax-tree/xastscriptPublic

NotificationsYou must be signed in to change notification settings
Fork3
Star12

utility to create xast trees

License

MIT license

12 stars 3 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.github/workflows		.github/workflows
lib		lib
script		script
test-d		test-d
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
index.js		index.js
jsx-dev-runtime.js		jsx-dev-runtime.js
jsx-runtime.js		jsx-runtime.js
license		license
package.json		package.json
readme.md		readme.md
tsconfig.json		tsconfig.json

Repository files navigation

xastscript

xast utility to create trees with ease.

What is this?

This package is a hyperscript interface (likecreateElement from React andsuch) to help with creating xast trees.

When should I use this?

You can use this utility in your project when you generate xast syntax treeswith code.It helps because it replaces most of the repetition otherwise needed in a syntaxtree with function calls.

You can instead useunist-builder when creating any unist nodes andhastscript when creating hast (HTML) nodes.

Install

This package isESM only.In Node.js (version 16+), install withnpm:

npm install xastscript

In Deno withesm.sh:

import{x}from'https://esm.sh/xastscript@4'

In browsers withesm.sh:

<scripttype="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 identifierx.There is no default export.

The export map supports the automatic JSX runtime.You can passxastscript to your build tool (TypeScript, Babel, SWC) with animportSource option or similar.

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

Createxast 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 asrdf:RDF).When string, anElement is built.When nullish, aRoot is built instead.

`attributes`

Attributes of the element (Attributes, optional).

`children`

Children of the node (Array<Child> orChild, optional).

Returns

Created tree (Result).

Element when aname is passed, otherwiseRoot.

`Attributes`

Map of attributes (TypeScript type).

Nullish (null orundefined) orNaN values are ignored, other values areturned to strings.

Type

typeAttributes=Record<string,boolean|number|string|null|undefined>

`Child`

(Lists of) children (TypeScript type).

When strings or numbers are encountered, they are turned intoTextnodes.Root nodes are treated as “fragments”, meaning that their childrenare used instead.

Type

typeChild=|Array<Node|boolean|number|string|null|undefined>|Node|boolean|number|string|null|undefined

`Result`

Result from ax call (TypeScript type).

Type

typeResult=Element|Root

Syntax tree

The syntax tree isxast.

JSX

This package can be used with JSX.You should use the automatic JSX runtime set toxastscript.

🪦Legacy: you can also use the classic JSX runtime, but this is notrecommended.To do so, importx yourself and define it as the pragma (plus set thefragment tonull).

The Use example above (omitting the second) can then be written like so:

/**@jsxImportSource xastscript */import{u}from'unist-builder'console.log(<albumid={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 withTypeScript.It exports the additional typesAttributes,Child, andResult.

Compatibility

Projects maintained by the unified collective are compatible with maintainedversions of Node.js.

When we cut a new major release, we drop support for unmaintained versions ofNode.This means we try to keep the current release line,xastscript@^4, compatiblewith Node.js 16.