Skip to content

flex-development/unist-util-stringify-position

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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.