Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/flex-development/unist-util-stringify-position
unist utility to serialize the positional info of a node, point, position, or range
https://github.com/flex-development/unist-util-stringify-position
point position range stringify syntax-tree unist unist-util
Last synced: 3 months ago
JSON representation
unist utility to serialize the positional info of a node, point, position, or range
- Host: GitHub
- URL: https://github.com/flex-development/unist-util-stringify-position
- Owner: flex-development
- License: bsd-3-clause
- Created: 2024-06-29T03:18:56.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2024-11-01T22:02:43.000Z (3 months ago)
- Last Synced: 2024-11-01T23:16:45.193Z (3 months ago)
- Topics: point, position, range, stringify, syntax-tree, unist, unist-util
- Language: JavaScript
- Homepage: https://github.com/flex-development/unist-util-stringify-position
- Size: 2.13 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# unist-util-stringify-position
[](https://github.com/flex-development/unist-util-stringify-position/releases/latest)
[](https://npmjs.com/package/@flex-development/unist-util-stringify-position)
[](https://codecov.io/gh/flex-development/unist-util-stringify-position)
[](https://github.com/voxpelli/badges-cjs-esm)
[](LICENSE.md)
[](https://conventionalcommits.org/)
[](https://typescriptlang.org/)
[](https://vitest.dev/)
[](https://yarnpkg.com/)
[unist][unist] utility to serialize the positional info of a node, point, position, or range
## Contents
- [What is this?](#what-is-this)
- [When should I use this?](#when-should-i-use-this)
- [Install](#install)
- [Use](#use)
- [API](#api)
- [`stringifyPosition([info][, options])`](#stringifypositioninfo-options)
- [Types](#types)
- [`Info`](#info)
- [`LiteralLike`](#literallike)
- [`NodeLike`](#nodelike)
- [`Options`](#options)
- [`ParentLike`](#parentlike)
- [`PointLike`](#pointlike)
- [`PositionLike`](#positionlike)
- [`Range`](#range)
- [Related](#related)
- [Contribute](#contribute)
## What is this?
This is a tiny, but useful, package that takes any [unist][unist] node, point, position, or range and serializes its
positional info.
## When should I use this?
Use this package when you want a standard format for serialized positional info, such as when inspecting trees, or
throwing errors.
## Install
This package is [ESM only][esm].
In Node.js (version 18+) with [yarn][yarn]:
```sh
yarn add @flex-development/unist-util-stringify-position
```
See Git - Protocols | Yarn
for details regarding installing from Git.
In Deno with [`esm.sh`][esmsh]:
```ts
import { stringifyPosition } from 'https://esm.sh/@flex-development/unist-util-stringify-position'
```
In browsers with [`esm.sh`][esmsh]:
```html
import { stringifyPosition } from 'https://esm.sh/@flex-development/unist-util-stringify-position'
```
## Use
```ts
import { u } from '@flex-development/unist-util-builder'
import {
stringifyPosition,
type LiteralLike,
type PointLike,
type PositionLike,
type Range
} from '@flex-development/unist-util-stringify-position'
const node: LiteralLike = u('text', {
position: {
end: { column: 13, line: 1, offset: 12 },
start: { column: 1, line: 1, offset: 0 }
},
value: 'hello world!'
})
const point: PointLike = { column: 9, line: 6 }
const position: PositionLike = { end: { line: 8 }, start: { line: 7 } }
const range: Range = [{ column: 2, line: 3 }, { column: 2, line: 5 }]
console.log('node:', stringifyPosition(node, { offsets: true }))
console.log('point:', stringifyPosition(point))
console.log('position:', stringifyPosition(position))
console.log('range:', stringifyPosition(range))
```
...yields
```sh
node: 1:1-1:13, 0-12
point: 6:9
position: 7:1-8:1
range: 3:2-5:2
```
## API
This package exports the identifier [`stringifyPosition`](#stringifypositioninfo-options).
There is no default export.
### `stringifyPosition([info][, options])`
Serialize the positional info of a node, point, position, or range.
The serialized info is returned in one the following formats:
- `ls:cs-le:ce, os-oe` (node, position, range)
- `ls:cs-le:ce` (node, position, range)
- `l:c` (point)
where `l` stands for line, `c` for column, `o` for offset, `s` for `start`, and `e` for end.
An empty string (`''`) is returned if the given info is neither node, point, position, nor range.
#### Parameters
- `info` ([`Info`](#info) | `null` | `undefined`) — node, point, position, or range
- `options` ([`Options`](#options) | `null` | `undefined`) — configuration options
- `options.offsets` (`boolean | null | undefined`) — serialize offsets if `info` is a node, position, or range
#### Returns
(`string`) Pretty printed positional info.
## Types
This package is fully typed with [TypeScript][typescript].
### `Info`
Union of positional info objects (TypeScript type).
```ts
type Info =
| Literal
| LiteralLike
| Node
| NodeLike
| Parent
| ParentLike
| Point
| PointLike
| Position
| PositionLike
| Range
```
### `LiteralLike`
Loose [literal][literal] (TypeScript type).
### `NodeLike`
Loose [node][node] (TypeScript type).
### `Options`
Configuration options (TypeScript type).
```ts
type Options = {
offsets?: boolean | null | undefined
}
```
#### Fields
- `offsets` (`boolean | null | undefined`) — serialize offsets if positional info is a node, position, or range
### `ParentLike`
Loose [parent][parent] (TypeScript type).
### `PointLike`
Loose [point][point] (TypeScript type).
### `PositionLike`
Loose [position][position] (TypeScript type).
### `Range`
List, where the first value is the place of the first character in a source region, and the last is the place of the
last character in the region. (TypeScript type).
```ts
type Range = [
start?: Point | PointLike | null | undefined,
end?: Point | PointLike | null | undefined
]
```
## Related
- [`unist-util-generated`][unist-util-generated] — check if a node is generated
- [`unist-util-position`][unist-util-position] — get positional info of nodes
- [`unist-util-remove-position`][unist-util-remove-position] — remove positional info from trees
- [`unist-util-source`][unist-util-source] — get the source of a value (node or position) in a file
- [`unist-util-types`][unist-util-types] — utility types
## Contribute
See [`CONTRIBUTING.md`](CONTRIBUTING.md).
This project has a [code of conduct](CODE_OF_CONDUCT.md). By interacting with this repository, organization, or
community you agree to abide by its terms.
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh/
[literal]: https://github.com/syntax-tree/unist#literal
[node]: https://github.com/syntax-tree/unist#node
[parent]: https://github.com/syntax-tree/unist#parent
[point]: https://github.com/syntax-tree/unist#point
[position]: https://github.com/syntax-tree/unist#position
[typescript]: https://www.typescriptlang.org
[unist-util-generated]: https://github.com/syntax-tree/unist-util-generated
[unist-util-position]: https://github.com/syntax-tree/unist-util-position
[unist-util-remove-position]: https://github.com/syntax-tree/unist-util-remove-position
[unist-util-source]: https://github.com/syntax-tree/unist-util-source
[unist-util-types]: https://github.com/flex-development/unist-util-types
[unist]: https://github.com/syntax-tree/unist
[yarn]: https://yarnpkg.com