Movatterモバイル変換

syntax-tree/hastPublic

NotificationsYou must be signed in to change notification settings
Fork27
Star870

Hypertext Abstract Syntax Tree format

unifiedjs.com

870 stars 27 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 107 Commits
.github/workflows		.github/workflows
.gitignore		.gitignore
.npmrc		.npmrc
logo.svg		logo.svg
package.json		package.json
readme.md		readme.md

Repository files navigation

HypertextAbstractSyntaxTree format.

hast is a specification for representingHTML(and embeddedSVG orMathML)as an abstract syntax tree.It implements theunist spec.

This document may not be released.Seereleases for released documents.The latest released version is2.4.0.

Introduction

This document defines a format for representing hypertext as anabstract syntax tree.Development of hast started in April 2016 forrehype.This specification is written in aWeb IDL-like grammar.

Where this specification fits

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

hast relates toJavaScript in that it has anecosystem of utilitiesfor working with compliant syntax trees in JavaScript.However,hast is not limited to JavaScript and can be used in other programminglanguages.

hast relates to theunified andrehypeprojects in that hast syntax trees are used throughout their ecosystems.

Virtual DOM

The reason for introducing a new “virtual” DOM is primarily:

TheDOM is very heavy to implement outside of the browser,a lean and stripped down virtual DOM can be used everywhere
Most virtual DOMs do not focus on ease of use in transformations
Other virtual DOMs cannot represent the syntax of HTML in its entirety(think comments and document types)
Neither the DOM nor virtual DOMs focus on positional information

Types

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

npm install @types/hast

Nodes (abstract)

`Literal`

interface Literal<: UnistLiteral {  value:string}

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

`Parent`

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

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

Its content is limited to only other hast content.

Nodes

`Comment`

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

Comment (Literal) represents aComment([DOM]).

For example,the following HTML:

<!--Charlie-->

Yields:

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

`Doctype`

interface Doctype<: Node {  type:'doctype'}

Doctype (Node) represents aDocumentType ([DOM]).

For example,the following HTML:

<!doctype html>

Yields:

{type:'doctype'}

`Element`

interface Element<: Parent {  type:'element'  tagName:string  properties: Properties  content: Root?  children: [Comment| Element|Text]}

Element (Parent) represents anElement([DOM]).

AtagName field must be present.It represents the element’slocal name([DOM]).

Theproperties field represents information associated with the element.The value of theproperties field implements theProperties interface.

If thetagName field is'template',acontent field can be present.The value of thecontent field implements theRoot interface.

If thetagName field is'template',the element must be aleaf.

If thetagName field is'noscript',itschildren should be represented as ifscripting is disabled ([HTML]).

For example,the following HTML:

<ahref="https://alpha.com"class="bravo"download></a>

Yields:

{type:'element',tagName:'a',properties:{href:'https://alpha.com',className:['bravo'],download:true},children:[]}

`Root`

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

Root (Parent) represents a document.

Root can be used as theroot of atree,or as a value of thecontent field on a'template'Element,never as achild.

`Text`

interfaceText<: Literal {  type:'text'}

Text (Literal) represents aText([DOM]).

For example,the following HTML:

<span>Foxtrot</span>

Yields:

{type:'element',tagName:'span',properties:{},children:[{type:'text',value:'Foxtrot'}]}

Other types

`Properties`

interface Properties {}

Properties represents information associated with an element.

Every field must be aPropertyName and every value aPropertyValue.

`PropertyName`

typedefstring PropertyName

Property names are keys onProperties objects and reflectHTML,SVG,ARIA,XML,XMLNS,or XLink attribute names.Often,they have the same value as the corresponding attribute(for example,id is a property name reflecting theid attribute name),but there are some notable differences.

These rules aren’t simple.Usehastscript(orproperty-information directly)to help.

The following rules are used to transform HTML attribute names to propertynames.These rules are based onhow ARIA is reflected in the DOM([ARIA]),and differs from how some(older)HTML attributes are reflected in the DOM.

any name referencing a combinations of multiple words(such as “stroke miter limit”) becomes a camelcased property namecapitalizing each word boundary;this includes combinations that are sometimes written as several words;for example,stroke-miterlimit becomesstrokeMiterLimit,autocorrect becomesautoCorrect,andallowfullscreen becomesallowFullScreen
any name that can be hyphenated,becomes a camelcased property name capitalizing each boundary;for example,“read-only” becomesreadOnly
compound words that are not used with spaces or hyphens are treated as anormal word and the previous rules apply;for example,“placeholder”,“strikethrough”,and “playback” stay the same
acronyms in names are treated as a normal word and the previous rules apply;for example,itemid becomeitemId andbgcolor becomesbgColor

Exceptions

Some jargon is seen as one word even though it may not be seen as such bydictionaries.For example,nohref becomesnoHref,playsinline becomesplaysInline,andaccept-charset becomesacceptCharset.

The HTML attributesclass andfor respectively becomeclassName andhtmlFor in alignment with the DOM.No other attributes gain different names as properties,other than a change in casing.

Notes

property-information lists all property names.

The property name rules differ from how HTML is reflected in the DOM for thefollowing attributes:

View list of differences

charoff becomescharOff (notchOff)
char stayschar (does not becomech)
rel staysrel (does not becomerelList)
checked stayschecked (does not becomedefaultChecked)
muted staysmuted (does not becomedefaultMuted)
value staysvalue (does not becomedefaultValue)
selected staysselected (does not becomedefaultSelected)
allowfullscreen becomesallowFullScreen (notallowFullscreen)
hreflang becomeshrefLang, nothreflang
autoplay becomesautoPlay, notautoplay
autocomplete becomesautoComplete (notautocomplete)
autofocus becomesautoFocus, notautofocus
enctype becomesencType, notenctype
formenctype becomesformEncType (notformEnctype)
vspace becomesvSpace, notvspace
hspace becomeshSpace, nothspace
lowsrc becomeslowSrc, notlowsrc

`PropertyValue`

typedef any PropertyValue

Property values should reflect the data type determined by their property name.For example,the HTML<div hidden></div> has ahidden attribute,which is reflected as ahidden property name set to the property valuetrue,and<input minlength="5">,which has aminlength attribute,is reflected as aminLength property name set to the property value5.

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

The DOM has strict rules on how it coerces HTML to expected values,whereas hast is more lenient in how it reflects the source.Where the DOM treats<div hidden="no"></div> as having a value oftrue and<img width="yes"> as having a value of0,these should be reflected as'no' and'yes',respectively,in hast.

The reason for this is to allow plugins and utilities to inspect thesenon-standard values.

The DOM also specifies comma separated and space separated lists attributevalues.In hast, these should be treated as ordered lists.For example,<div></div> is represented as['alpha', 'bravo'].

There’s no special format for the property value of thestyle property name.

Glossary

See§Glossary insyntax-tree/unist.

List of utilities

See§List of utilities insyntax-tree/unistfor more utilities.

hastscript— create trees
hast-util-assert— assert nodes
hast-util-class-list— simulate the browser’sclassList API for hast nodes
hast-util-classnames— merge class names together
hast-util-embedded— check if a node is an embedded element
hast-util-excerpt— truncate the tree to a comment
hast-util-find-and-replace— find and replace text in a tree
hast-util-format— format whitespace
hast-util-from-dom— transform from DOM tree
hast-util-from-html— parse from HTML
hast-util-from-parse5— transform from Parse5’s AST
hast-util-from-selector— parse CSS selectors to nodes
hast-util-from-string— set the plain-text value of a node (textContent)
hast-util-from-text— set the plain-text value of a node (innerText)
hast-util-from-webparser— transform Webparser’s AST to hast
hast-util-has-property— check if an element has a certain property
hast-util-heading— check if a node is heading content
hast-util-heading-rank— get the rank (also known as depth or level) of headings
hast-util-interactive— check if a node is interactive
hast-util-is-body-ok-link— check if alink element is “Body OK”
hast-util-is-conditional-comment— check ifnode is a conditional comment
hast-util-is-css-link— check ifnode is a CSSlink
hast-util-is-css-style— check ifnode is a CSSstyle
hast-util-is-element— check ifnode is a (certain) element
hast-util-is-event-handler— check ifproperty is an event handler
hast-util-is-javascript— check ifnode is a JavaScriptscript
hast-util-labelable— check ifnode is labelable
hast-util-minify-whitespace— minify whitespace between elements
hast-util-parse-selector— create an element from a simple CSS selector
hast-util-phrasing— check if a node is phrasing content
hast-util-raw— parse a tree again
hast-util-reading-time— estimate the reading time
hast-util-sanitize— sanitize nodes
hast-util-script-supporting— check ifnode is script-supporting content
hast-util-select—querySelector,querySelectorAll, andmatches
hast-util-sectioning— check ifnode is sectioning content
hast-util-shift-heading— change heading rank (depth, level)
hast-util-table-cell-style— transform deprecated styling attributes on table cells to inline styles
hast-util-to-dom— transform to a DOM tree
hast-util-to-estree— transform to estree (JavaScript AST) JSX
hast-util-to-html— serialize as HTML
hast-util-to-jsx— transform hast to JSX
hast-util-to-jsx-runtime— transform to preact, react, solid, svelte, vue, etc
hast-util-to-mdast— transform to mdast (markdown)
hast-util-to-nlcst— transform to nlcst (natural language)
hast-util-to-parse5— transform to Parse5’s AST
hast-util-to-portable-text— transform to portable text
hast-util-to-string— get the plain-text value of a node (textContent)
hast-util-to-text— get the plain-text value of a node (innerText)
hast-util-to-xast— transform to xast (xml)
hast-util-transparent— check ifnode is transparent content
hast-util-truncate— truncate the tree to a certain number of characters
hast-util-whitespace— check ifnode is inter-element whitespace

Related HTML utilities

a-rel— List of link types forrel ona /area
aria-attributes— List of ARIA attributes
collapse-white-space— Replace multiple white-space characters with a single space
comma-separated-tokens— Parse/stringify comma separated tokens
html-tag-names— List of HTML tag names
html-dangerous-encodings— List of dangerous HTML character encoding labels
html-encodings— List of HTML character encoding labels
html-element-attributes— Map of HTML attributes
html-event-attributes— List of HTML event handler content attributes
html-void-elements— List of void HTML tag names
link-rel— List of link types forrel onlink
mathml-tag-names— List of MathML tag names
meta-name— List of values forname onmeta
property-information— Information on HTML properties
space-separated-tokens— Parse/stringify space separated tokens
svg-tag-names— List of SVG tag names
svg-element-attributes— Map of SVG attributes
svg-event-attributes— List of SVG event handler content attributes
web-namespaces— Map of web namespaces

References

unist:Universal Syntax Tree.T. Wormer; et al.
JavaScript:ECMAScript Language Specification.Ecma International.
HTML:HTML Standard,A. van Kesteren; et al.WHATWG.
DOM:DOM Standard,A. van Kesteren,A. Gregor,Ms2ger.WHATWG.
SVG:Scalable Vector Graphics (SVG),N. Andronikos,R. Atanassov,T. Bah,B. Birtles,B. Brinza,C. Concolato,E. Dahlström,C. Lilley,C. McCormack,D. Schepers,R. Schwerdtfeger,D. Storey,S. Takagi,J. Watt.W3C.
MathML:Mathematical Markup Language Standard,D. Carlisle,P. Ion,R. Miner.W3C.
ARIA:Accessible Rich Internet Applications (WAI-ARIA),J. Diggs,J. Craig,S. McCarron,M. Cooper.W3C.
JSONThe JavaScript Object Notation (JSON) Data Interchange Format,T. Bray.IETF.
Web IDL:Web IDL,C. McCormack.W3C.

Security

As hast represents HTML,and improper use of HTML can open you up to across-site scripting (XSS) attack,improper use of hast is also unsafe.Always be careful with user input and usehast-util-santize to make the hast tree safe.