basant307/AI_Governance_Project
045
1# hast-util-from-parse52 3[![Build][badge-build-image]][badge-build-url]4[![Coverage][badge-coverage-image]][badge-coverage-url]5[![Downloads][badge-downloads-image]][badge-downloads-url]6[![Size][badge-size-image]][badge-size-url]7 8[hast][github-hast] utility to transform from the9[`parse5`][github-parse5] AST.10 11## Contents12 13* [What is this?](#what-is-this)14* [When should I use this?](#when-should-i-use-this)15* [Install](#install)16* [Use](#use)17* [API](#api)18 * [`fromParse5(tree[, options])`](#fromparse5tree-options)19 * [`Options`](#options)20 * [`Space`](#space-1)21* [Types](#types)22* [Compatibility](#compatibility)23* [Security](#security)24* [Related](#related)25* [Contribute](#contribute)26* [License](#license)27 28## What is this?29 30This package is a utility that can turn a parse5 tree into a hast tree.31 32## When should I use this?33 34You can use this package when using `parse5` as an HTML parser and wanting to35work with hast.36 37The utility [`hast-util-to-parse5`][github-hast-util-to-parse5] does the38inverse of this utility.39It generates `parse5`s AST again.40 41The utility [`hast-util-from-html`][github-hast-util-from-html] wraps this42utility and `parse5` to both parse HTML and generate hast from it.43 44## Install45 46This package is [ESM only][github-gist-esm].47In Node.js (version 16+),48install with [npm][npmjs-install]:49 50```sh51npm install hast-util-from-parse552```53 54In Deno with [`esm.sh`][esmsh]:55 56```js57import {fromParse5} from "https://esm.sh/hast-util-from-parse5@8"58```59 60In browsers with [`esm.sh`][esmsh]:61 62```html63<script type="module">64 import {fromParse5} from "https://esm.sh/hast-util-from-parse5@8?bundle"65</script>66```67 68## Use69 70Say our document `example.html` contains:71 72```html73<!doctype html><title>Hello!</title><h1 id="world">World!<!--after-->74```75 76…and our module `example.js` looks as follows:77 78```js79import {fromParse5} from 'hast-util-from-parse5'80import {parse} from 'parse5'81import {read} from 'to-vfile'82import {inspect} from 'unist-util-inspect'83 84const file = await read('example.html')85const p5ast = parse(String(file), {sourceCodeLocationInfo: true})86const hast = fromParse5(p5ast, {file})87 88console.log(inspect(hast))89```90 91…now running `node example.js` yields:92 93```text94root[2] (1:1-2:1, 0-70)95│ data: {"quirksMode":false}96├─0 doctype (1:1-1:16, 0-15)97└─1 element<html>[2]98 │ properties: {}99 ├─0 element<head>[1]100 │ │ properties: {}101 │ └─0 element<title>[1] (1:16-1:37, 15-36)102 │ │ properties: {}103 │ └─0 text "Hello!" (1:23-1:29, 22-28)104 └─1 element<body>[1]105 │ properties: {}106 └─0 element<h1>[3] (1:37-2:1, 36-70)107 │ properties: {"id":"world"}108 ├─0 text "World!" (1:52-1:58, 51-57)109 ├─1 comment "after" (1:58-1:70, 57-69)110 └─2 text "\n" (1:70-2:1, 69-70)111```112 113## API114 115This package exports the identifier [`fromParse5`][api-from-parse5].116There is no default export.117 118### `fromParse5(tree[, options])`119 120Transform a `parse5` AST to hast.121 122###### Parameters123 124* `tree`125 ([`Parse5Node`][github-parse5-node])126 — `parse5` tree to transform127* `options`128 ([`Options`][api-options], optional)129 — configuration130 131###### Returns132 133hast tree ([`HastNode`][github-hast-nodes]).134 135### `Options`136 137Configuration (TypeScript type).138 139##### Fields140 141###### `file`142 143File used to add positional info to nodes144([`VFile`][github-vfile], optional).145 146If given,147the file should represent the original HTML source.148 149###### `space`150 151Which space the document is in152([`Space`][api-space], default: `'html'`).153 154When an `<svg>` element is found in the HTML space,155this package already automatically switches to and from the SVG space when156entering and exiting it.157 158###### `verbose`159 160Whether to add extra positional info about starting tags,161closing tags,162and attributes to elements163(`boolean`, default: `false`).164 165> 👉 **Note**:166> only used when `file` is given.167 168For the following HTML:169 170```html171<img src="http://example.com/fav.ico" alt="foo" title="bar">172```173 174The verbose info would looks as follows:175 176```js177{178 type: 'element',179 tagName: 'img',180 properties: {src: 'http://example.com/fav.ico', alt: 'foo', title: 'bar'},181 children: [],182 data: {183 position: {184 opening: {185 start: {line: 1, column: 1, offset: 0},186 end: {line: 1, column: 61, offset: 60}187 },188 closing: null,189 properties: {190 src: {191 start: {line: 1, column: 6, offset: 5},192 end: {line: 1, column: 38, offset: 37}193 },194 alt: {195 start: {line: 1, column: 39, offset: 38},196 end: {line: 1, column: 48, offset: 47}197 },198 title: {199 start: {line: 1, column: 49, offset: 48},200 end: {line: 1, column: 60, offset: 59}201 }202 }203 }204 },205 position: {206 start: {line: 1, column: 1, offset: 0},207 end: {line: 1, column: 61, offset: 60}208 }209}210```211 212### `Space`213 214Namespace (TypeScript type).215 216###### Type217 218```ts219type Space = 'html' | 'svg'220```221 222## Types223 224This package is fully typed with [TypeScript][].225It exports the additional types [`Options`][api-options] and226[`Space`][api-space].227 228## Compatibility229 230Projects maintained by the unified collective are compatible with maintained231versions of Node.js.232 233When we cut a new major release,234we drop support for unmaintained versions of Node.235This means we try to keep the current release line,236`hast-util-from-parse5@8`,237compatible with Node.js 16.238 239## Security240 241Use of `hast-util-from-parse5` can open you up to a242[cross-site scripting (XSS)][wikipedia-xss] attack if Parse5’s AST is unsafe.243 244## Related245 246* [`hast-util-to-parse5`][github-hast-util-to-parse5]247 — transform hast to Parse5’s AST248* [`hast-util-to-nlcst`](https://github.com/syntax-tree/hast-util-to-nlcst)249 — transform hast to nlcst250* [`hast-util-to-mdast`](https://github.com/syntax-tree/hast-util-to-mdast)251 — transform hast to mdast252* [`hast-util-to-xast`](https://github.com/syntax-tree/hast-util-to-xast)253 — transform hast to xast254* [`mdast-util-to-hast`](https://github.com/syntax-tree/mdast-util-to-hast)255 — transform mdast to hast256* [`mdast-util-to-nlcst`](https://github.com/syntax-tree/mdast-util-to-nlcst)257 — transform mdast to nlcst258 259## Contribute260 261See [`contributing.md`][health-contributing]262in263[`syntax-tree/.github`][health]264for ways to get started.265See [`support.md`][health-support] for ways to get help.266 267This project has a [code of conduct][health-coc].268By interacting with this repository,269organization,270or community you agree to abide by its terms.271 272## License273 274[MIT][file-license] © [Titus Wormer][wooorm]275 276<!-- Definitions -->277 278[api-from-parse5]: #fromparse5tree-options279 280[api-options]: #options281 282[api-space]: #space-1283 284[badge-build-image]: https://github.com/syntax-tree/hast-util-from-parse5/workflows/main/badge.svg285 286[badge-build-url]: https://github.com/syntax-tree/hast-util-from-parse5/actions287 288[badge-coverage-image]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-from-parse5.svg289 290[badge-coverage-url]: https://codecov.io/github/syntax-tree/hast-util-from-parse5291 292[badge-downloads-image]: https://img.shields.io/npm/dm/hast-util-from-parse5.svg293 294[badge-downloads-url]: https://www.npmjs.com/package/hast-util-from-parse5295 296[badge-size-image]: https://img.shields.io/bundlejs/size/hast-util-from-parse5297 298[badge-size-url]: https://bundlejs.com/?q=hast-util-from-parse5299 300[esmsh]: https://esm.sh301 302[file-license]: license303 304[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c305 306[github-hast]: https://github.com/syntax-tree/hast307 308[github-hast-nodes]: https://github.com/syntax-tree/hast#nodes309 310[github-hast-util-from-html]: https://github.com/syntax-tree/hast-util-from-html311 312[github-hast-util-to-parse5]: https://github.com/syntax-tree/hast-util-to-parse5313 314[github-parse5]: https://github.com/inikulin/parse5315 316[github-parse5-node]: https://github.com/inikulin/parse5/blob/master/packages/parse5/lib/tree-adapters/default.ts317 318[github-vfile]: https://github.com/vfile/vfile319 320[health]: https://github.com/syntax-tree/.github321 322[health-coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md323 324[health-contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md325 326[health-support]: https://github.com/syntax-tree/.github/blob/main/support.md327 328[npmjs-install]: https://docs.npmjs.com/cli/install329 330[typescript]: https://www.typescriptlang.org331 332[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting333 334[wooorm]: https://wooorm.com335