unist-util-stringify-position

unist utility to serialize the positional info of a node, point, position, or range

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • stringifyPosition([info][, options])
• Types
  • Info
  • LiteralLike
  • NodeLike
  • Options
  • ParentLike
  • PointLike
  • PositionLike
  • Range
• Related
• Contribute

What is this?

This is a tiny, but useful, package that takes any 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.

In Node.js (version 18+) with yarn:

yarn add @flex-development/unist-util-stringify-position

See Git - Protocols | Yarn  for details regarding installing from Git.

In Deno with esm.sh:

import { stringifyPosition } from 'https://esm.sh/@flex-development/unist-util-stringify-position'

In browsers with esm.sh:

<script type="module">
  import { stringifyPosition } from 'https://esm.sh/@flex-development/unist-util-stringify-position'
</script>

Use

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

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.

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 | null | undefined) — node, point, position, or range
• 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.

Info

Union of positional info objects (TypeScript type).

type Info =
  | Literal
  | LiteralLike
  | Node
  | NodeLike
  | Parent
  | ParentLike
  | Point
  | PointLike
  | Position
  | PositionLike
  | Range

LiteralLike

Loose literal (TypeScript type).

NodeLike

Loose node (TypeScript type).

Options

Configuration options (TypeScript type).

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 (TypeScript type).

PointLike

Loose point (TypeScript type).

PositionLike

Loose 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).

type Range = [
  start?: Point | PointLike | null | undefined,
  end?: Point | PointLike | null | undefined
]

Related

• unist-util-generated — check if a node is generated
• unist-util-position — get positional info of nodes
• unist-util-remove-position — remove positional info from trees
• unist-util-source — get the source of a value (node or position) in a file
• unist-util-types — utility types

Contribute

See CONTRIBUTING.md.

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