Brunobkr/llama.cpp_AlgMor24_github

1# hastscript2 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 create trees with ease.9 10## Contents11 12* [What is this?](#what-is-this)13* [When should I use this?](#when-should-i-use-this)14* [Install](#install)15* [Use](#use)16* [API](#api)17  * [`h(selector?[, properties][, …children])`](#hselector-properties-children)18  * [`s(selector?[, properties][, …children])`](#sselector-properties-children)19  * [`Child`](#child)20  * [`Properties`](#properties-1)21  * [`Result`](#result)22* [Syntax tree](#syntax-tree)23* [JSX](#jsx)24* [Compatibility](#compatibility)25* [Security](#security)26* [Related](#related)27* [Contribute](#contribute)28* [License](#license)29 30## What is this?31 32This package is a hyperscript interface (like `createElement` from React and33`h` from Vue and such) to help with creating hast trees.34 35## When should I use this?36 37You can use this utility in your project when you generate hast syntax trees38with code.39It helps because it replaces most of the repetition otherwise needed in a syntax40tree with function calls.41It also helps as it improves the attributes you pass by turning them into the42form that is required by hast.43 44You can instead use [`unist-builder`][github-unist-builder]45when creating any unist nodes and46[`xastscript`][github-xastscript] when creating xast (XML) nodes.47 48## Install49 50This package is [ESM only][github-gist-esm].51In Node.js (version 16+),52install with [npm][npmjs-install]:53 54```sh55npm install hastscript56```57 58In Deno with [`esm.sh`][esmsh]:59 60```js61import {h} from 'https://esm.sh/hastscript@9'62```63 64In browsers with [`esm.sh`][esmsh]:65 66```html67<script type="module">68  import {h} from 'https://esm.sh/hastscript@9?bundle'69</script>70```71 72## Use73 74```js75import {h, s} from 'hastscript'76 77console.log(78  h('.foo#some-id', [79    h('span', 'some text'),80    h('input', {type: 'text', value: 'foo'}),81    h('a.alpha', {class: 'bravo charlie', download: 'download'}, [82      'delta',83      'echo'84    ])85  ])86)87 88console.log(89  s('svg', {viewbox: '0 0 500 500', xmlns: 'http://www.w3.org/2000/svg'}, [90    s('title', 'SVG `<circle>` element'),91    s('circle', {cx: 120, cy: 120, r: 100})92  ])93)94```95 96Yields:97 98```js99{100  type: 'element',101  tagName: 'div',102  properties: {className: ['foo'], id: 'some-id'},103  children: [104    {105      type: 'element',106      tagName: 'span',107      properties: {},108      children: [{type: 'text', value: 'some text'}]109    },110    {111      type: 'element',112      tagName: 'input',113      properties: {type: 'text', value: 'foo'},114      children: []115    },116    {117      type: 'element',118      tagName: 'a',119      properties: {className: ['alpha', 'bravo', 'charlie'], download: true},120      children: [{type: 'text', value: 'delta'}, {type: 'text', value: 'echo'}]121    }122  ]123}124{125  type: 'element',126  tagName: 'svg',127  properties: {viewBox: '0 0 500 500', xmlns: 'http://www.w3.org/2000/svg'},128  children: [129    {130      type: 'element',131      tagName: 'title',132      properties: {},133      children: [{type: 'text', value: 'SVG `<circle>` element'}]134    },135    {136      type: 'element',137      tagName: 'circle',138      properties: {cx: 120, cy: 120, r: 100},139      children: []140    }141  ]142}143```144 145## API146 147This package exports the identifiers [`h`][api-h] and [`s`][api-s].148There is no default export.149It exports the additional [TypeScript][] types150[`Child`][api-child],151[`Properties`][api-properties],152and153[`Result`][api-result].154 155The export map supports the automatic JSX runtime.156You can pass `hastscript` or `hastscript/svg` to your build tool157(TypeScript, Babel, SWC)158with an `importSource` option or similar.159 160### `h(selector?[, properties][, …children])`161 162Create virtual **[hast][github-hast]** trees for HTML.163 164##### Signatures165 166* `h(): root`167* `h(null[, …children]): root`168* `h(selector[, properties][, …children]): element`169 170##### Parameters171 172###### `selector`173 174Simple CSS selector175(`string`, optional).176When string, builds an [`Element`][github-hast-element].177When nullish, builds a [`Root`][github-hast-root] instead.178The selector can contain a tag name (`foo`),179IDs (`#bar`),180and classes (`.baz`).181If the selector is a string but there is no tag name in it then `h` defaults to182build a `div` element and `s` to a `g` element.183`selector` is parsed by184[`hast-util-parse-selector`][github-hast-util-parse-selector].185 186###### `properties`187 188Properties of the element189([`Properties`][api-properties], optional).190 191###### `children`192 193Children of the node ([`Child`][api-child] or `Array<Child>`, optional).194 195##### Returns196 197Created tree ([`Result`][api-result]).198 199[`Element`][github-hast-element] when a `selector` is passed,200otherwise [`Root`][github-hast-root].201 202### `s(selector?[, properties][, …children])`203 204Create virtual **[hast][github-hast]** trees for SVG.205 206Signatures, parameters, and return value are the same as `h` above.207Importantly,208the `selector` and `properties` parameters are interpreted as SVG.209 210### `Child`211 212(Lists of) children (TypeScript type).213 214When strings or numbers are encountered,215they are turned into [`Text`][github-hast-text]216nodes.217[`Root`][github-hast-root] nodes are treated as “fragments”,218meaning that their children are used instead.219 220###### Type221 222```ts223type Child =224  | Array<Node | number | string | null | undefined>225  | Node226  | number227  | string228  | null229  | undefined230```231 232### `Properties`233 234Map of properties (TypeScript type).235Keys should match either the HTML attribute name or the DOM property name,236but are case-insensitive.237 238###### Type239 240```ts241type Properties = Record<242  string,243  | boolean244  | number245  | string246  | null247  | undefined248  // For comma- and space-separated values such as `className`:249  | Array<number | string>250  // Accepts value for `style` prop as object.251  | Record<string, number | string>252>253```254 255### `Result`256 257Result from a `h` (or `s`) call (TypeScript type).258 259###### Type260 261```ts262type Result = Element | Root263```264 265## Syntax tree266 267The syntax tree is [hast][github-hast].268 269## JSX270 271This package can be used with JSX.272You should use the automatic JSX runtime set to `hastscript` or273`hastscript/svg`.274 275> 👉 **Note**276> while `h` supports dots (`.`) for classes or number signs (`#`)277> for IDs in `selector`,278> those are not supported in JSX.279 280> 🪦 **Legacy**:281> you can also use the classic JSX runtime,282> but this is not recommended.283> To do so,284> import `h` (or `s`) yourself and define it as the pragma285> (plus set the fragment to `null`).286 287The Use example above can then be written like so,288using inline pragmas,289so that SVG can be used too:290 291`example-html.jsx`:292 293```js294/** @jsxImportSource hastscript */295console.log(296  <div class="foo" id="some-id">297    <span>some text</span>298    <input type="text" value="foo" />299    <a class="alpha bravo charlie" download>300      deltaecho301    </a>302  </div>303)304```305 306`example-svg.jsx`:307 308```js309/** @jsxImportSource hastscript/svg */310console.log(311  <svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 500 500">312    <title>SVG `&lt;circle&gt;` element</title>313    <circle cx={120} cy={120} r={100} />314  </svg>315)316```317 318## Compatibility319 320Projects maintained by the unified collective are compatible with maintained321versions of Node.js.322 323When we cut a new major release,324we drop support for unmaintained versions of Node.325This means we try to keep the current release line,326`hastscript@9`,327compatible with Node.js 16.328 329## Security330 331Use of `hastscript` can open you up to a332[cross-site scripting (XSS)][wikipedia-xss]333when you pass user-provided input to it because values are injected into the334syntax tree.335 336The following example shows how an image is injected that fails loading and337therefore runs code in a browser.338 339```js340const tree = h()341 342// Somehow someone injected these properties instead of an expected `src` and343// `alt`:344const otherProps = {onError: 'alert(1)', src: 'x'}345 346tree.children.push(h('img', {src: 'default.png', ...otherProps}))347```348 349Yields:350 351```html352<img onerror="alert(1)" src="x">353```354 355The following example shows how code can run in a browser because someone stored356an object in a database instead of the expected string.357 358```js359const tree = h()360 361// Somehow this isn’t the expected `'wooorm'`.362const username = {363  type: 'element',364  tagName: 'script',365  children: [{type: 'text', value: 'alert(2)'}]366}367 368tree.children.push(h('span.handle', username))369```370 371Yields:372 373```html374<span class="handle"><script>alert(2)</script></span>375```376 377Either do not use user-provided input in `hastscript` or use378[`hast-util-santize`][github-hast-util-sanitize].379 380## Related381 382* [`unist-builder`][github-unist-builder]383  — create unist trees384* [`xastscript`][github-xastscript]385  — create xast trees386* [`hast-to-hyperscript`](https://github.com/syntax-tree/hast-to-hyperscript)387  — turn hast into React, Preact, Vue, etc388* [`hast-util-to-html`](https://github.com/syntax-tree/hast-util-to-html)389  — turn hast into HTML390* [`hast-util-to-dom`](https://github.com/syntax-tree/hast-util-to-dom)391  — turn hast into DOM trees392* [`estree-util-build-jsx`](https://github.com/syntax-tree/estree-util-build-jsx)393  — compile JSX away394 395## Contribute396 397See398[`contributing.md`][health-contributing]399in400[`syntax-tree/.github`][health]401for ways to get started.402See [`support.md`][health-support] for ways to get help.403 404This project has a [code of conduct][health-coc].405By interacting with this repository,406organization,407or community you agree to abide by its terms.408 409## License410 411[MIT][file-license] © [Titus Wormer][wooorm]412 413<!-- Definitions -->414 415[api-child]: #child416 417[api-h]: #hselector-properties-children418 419[api-properties]: #properties-1420 421[api-result]: #result422 423[api-s]: #sselector-properties-children424 425[badge-build-image]: https://github.com/syntax-tree/hastscript/workflows/main/badge.svg426 427[badge-build-url]: https://github.com/syntax-tree/hastscript/actions428 429[badge-coverage-image]: https://img.shields.io/codecov/c/github/syntax-tree/hastscript.svg430 431[badge-coverage-url]: https://codecov.io/github/syntax-tree/hastscript432 433[badge-downloads-image]: https://img.shields.io/npm/dm/hastscript.svg434 435[badge-downloads-url]: https://www.npmjs.com/package/hastscript436 437[badge-size-image]: https://img.shields.io/bundlejs/size/hastscript438 439[badge-size-url]: https://bundlejs.com/?q=hastscript440 441[esmsh]: https://esm.sh442 443[file-license]: license444 445[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c446 447[github-hast]: https://github.com/syntax-tree/hast448 449[github-hast-element]: https://github.com/syntax-tree/hast#element450 451[github-hast-root]: https://github.com/syntax-tree/hast#root452 453[github-hast-text]: https://github.com/syntax-tree/hast#text454 455[github-hast-util-parse-selector]: https://github.com/syntax-tree/hast-util-parse-selector456 457[github-hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize458 459[github-unist-builder]: https://github.com/syntax-tree/unist-builder460 461[github-xastscript]: https://github.com/syntax-tree/xastscript462 463[health]: https://github.com/syntax-tree/.github464 465[health-coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md466 467[health-contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md468 469[health-support]: https://github.com/syntax-tree/.github/blob/main/support.md470 471[npmjs-install]: https://docs.npmjs.com/cli/install472 473[typescript]: https://www.typescriptlang.org474 475[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting476 477[wooorm]: https://wooorm.com478