Repository files navigation

ExtensibleAbstractSyntaxTree format.

xast is a specification for representingXML as an abstractsyntax tree.It implements theunist spec.

This document may not be released.Seereleases for released documents.The latest released version is1.0.0.

• Introduction
  • Where this specification fits
  • Scope
• Types
• Nodes (abstract)
  • Literal
  • Parent
• Nodes
  • Cdata
  • Comment
  • Doctype
  • Element
  • Instruction
  • Root
  • Text
• Other types
  • Attributes
  • AttributeName
  • AttributeValue
• Glossary
• List of utilities
• References
• Related
• Contribute
• Acknowledgments
• License

This document defines a format for representing XML as anabstract syntaxtree.This specification is written in aWeb IDL-like grammar.Development started in January 2020.

xast extendsunist,a format for syntax trees,to benefit from itsecosystem of utilities.

xast relates toJavaScript in that it has anecosystem ofutilities for working with compliant syntax trees inJavaScript.However,xast is not limited to JavaScript and can be used in other programminglanguages.

xast relates to theunified project in that xast syntax trees are usedthroughout its ecosystem.

xast represents XML syntax,not semantics:there are no namespaces or local names;only qualified names.

xast supports a sensible subset of XML by omitting the ostensibly bad DTD.XML processors are not guaranteed to process DTDs,making them unsafe.

xast represents expanded entities and therefore does not deal with entities orcharacter references.It is suggested that utilities around xast,that parse or serialize,donot supportparameter-entity references orentity references other than thepredefined entities(< for< U+003C LESS THAN;> for> U+003E GREATER THAN;& for& U+0026 AMPERSAND;' for' U+0027 APOSTROPHE;" for" U+0022 QUOTATION MARK).This preventsbillion laughs attacks.

Declarations ([XML]) other thandoctype have no representation in xast:

<!ELEMENT %name.para; %content.para;><!ATTLIST poem xml:space (default|preserve) 'preserve'><!ENTITY % ISOLat2 SYSTEM "http://www.xml.com/iso/isolat2-xml.entities"><!ENTITY Pub-Status "This is a pre-release of the specification."><![%draft;[<!ELEMENT book (comments*, title, body, supplements?)>]]><![%final;[<!ELEMENT book (title, body, supplements?)>]]>

Internal document type declarations have no representation in xast:

<!DOCTYPEgreeting [  <!ELEMENT greeting (#PCDATA)>]><greeting>Hello, world!</greeting>

If you are using TypeScript,you can use the xast types by installing them with npm:

npm install @types/xast

interface Literal<: UnistLiteral {  value:string}

Literal (UnistLiteral) represents a node in xastcontaining a value.

interface Parent<: UnistParent {  children: [Cdata| Comment| Doctype| Element| Instruction|Text]}

Parent (UnistParent) represents a node in xastcontaining other nodes (said to bechildren).

Its content is limited to only other xast content.

interface Cdata<: Literal {  type:'cdata'}

Cdata (Literal) represents aCDATA section ([XML]).

For example,the following XML:

<![CDATA[<greeting>Hello, world!</greeting>]]>

Yields:

{type:'cdata',value:'<greeting>Hello, world!</greeting>'}

interface Comment<: Literal {  type:'comment'}

Comment (Literal) represents acomment ([XML]).

For example,the following XML:

<!--Charlie-->

Yields:

{type:'comment',value:'Charlie'}

interface Doctype<: Node {  type:'doctype'  name:string  public:string?  system:string?}

Doctype (Node) represents adoctype ([XML]).

Aname field must be present.

Apublic field should be present.If present,it must be set to a string,and represents the document’s public identifier.

Asystem field should be present.If present,it must be set to a string,and represents the document’s system identifier.

For example,the following XML:

<!DOCTYPEHTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">

Yields:

{type:'doctype',name:'HTML',public:'-//W3C//DTD HTML 4.0 Transitional//EN',system:'http://www.w3.org/TR/REC-html40/loose.dtd'}

interface Element<: Parent {  type:'element'  name:string  attributes: Attributes?  children: [Cdata| Comment| Element| Instruction|Text]}

Element (Parent) represents anelement ([XML]).

Thename field must be present.It represents the element’sname ([XML]),specifically itsqualified name([XML-NAMES]).

Thechildren field should be present.

Theattributes field should be present.It represents information associated with the element.The value of theattributes field implements theAttributes interface.

For example,the following XML:

<packageunique-identifier="id"xmlns="http://www.idpf.org/2007/opf" />

Yields:

{type:'element',name:'package',attributes:{'unique-identifier':'id',xmlns:'http://www.idpf.org/2007/opf'},children:[]}

interface Instruction<: Literal {  type:'instruction'  name:string}

Instruction (Literal) represents aprocessing instruction ([XML]).

Aname field must be present.

For example,the following XML:

<?xml version="1.0" encoding="UTF-8"?>

Yields:

{type:'instruction',name:'xml',value:'version="1.0" encoding="UTF-8"'}

interface Root<: Parent {  type:'root'}

Root (Parent) represents a document fragment or a wholedocument.

Root should be used as theroot of atree andmust not be used as achild.

XML specifies that documents should have exactly oneelementchild,therefore a root should have exactly one element child when representing awhole document.

interfaceText<: Literal {  type:'text'}

Text (Literal) representscharacter data ([XML]).

For example,the following XML:

<dc:language>en</dc:language>

Yields:

{type:'element',name:'dc:language',attributes:{},children:[{type:'text',value:'en'}]}

interface Attributes {}

Attributes represents information associated with an element.

Every field must be aAttributeName and every value anAttributeValue.

typedefstring AttributeName

Attribute names are keys onAttributes objects and mustreflect XML attribute names exactly.

typedefstring AttributeValue

Attribute values are values onAttributes objects and mustreflect XML attribute values exactly as a string.

InJSON,the valuenull must be treated as if the attribute was not included.InJavaScript,bothnull andundefined must be similarly ignored.

See theunist glossary.

See theunist list of utilities for more utilities.

• xastscript— create trees
• xast-util-feed— build feeds (RSS, Atom)
• xast-util-from-xml— parse from XML
• xast-util-sitemap— buildsitemap.xml
• xast-util-to-string— get the text value
• xast-util-to-xml— serialize to XML
• hast-util-to-xast— transform to xast

• JSONThe JavaScript Object Notation (JSON) Data Interchange Format,T. Bray.IETF.
• JavaScript:ECMAScript Language Specification.Ecma International.
• unist:Universal Syntax Tree.T. Wormer; et al.
• XML:Extensible Markup Language (XML) 1.0 (Fifth Edition)T. Bray; et al.W3C.
• XML-NAMES:Namespaces in XML 1.0 (Third Edition)T. Bray; et al.W3C.
• Web IDL:Web IDL,C. McCormack.W3C.

• hast— Hypertext Abstract Syntax Tree format
• mdast— Markdown Abstract Syntax Tree format
• nlcst— Natural Language Concrete Syntax Tree format

Seecontributing.md insyntax-tree/.github forways to get started.Seesupport.md for ways to get help.Ideas for new utilities and tools can be posted insyntax-tree/ideas.

A curated list of awesomesyntax-tree,unist,hast,mdast,nlcst,and xast resources can be found inawesome syntax-tree.

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

The initial release of this project was authored by@wooorm.

CC-BY-4.0 ©Titus Wormer