Skip to content

flex-development/unist-util-stringify-position

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Folders and files

NameName
Last commit message
Last commit date
Oct 28, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jul 5, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jul 5, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Nov 4, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Jun 29, 2024
Nov 4, 2024

Repository files navigation

unist-util-stringify-position

github release npm codecov module type: esm license conventional commits typescript vitest yarn

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

Contents

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

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.