region-ast

Table of contents

• 🍵 Introduction
  • Where should I use this?
• 🚀 Get started
• 🧬 Structure rules
• 🔹 Nodes
• 🔗 API
  • Unified
  • Utils
• 🤝 Contribute
• 👑 Author
• ⚖️ License
• 📰 Changelog
• 🧱 Related packages

🍵 Introduction

region-ast is a specification for representing text regions (similar to VSCode regions) as an abstract syntax tree (AST). It implements the unist specification.

This library provides the type definitions, structure rules, unified plugins and utils for processing region-based text.

This specification defines a format for text nested within region markers. It is designed to handle line-by-line processing where lexical analysis identifies region boundaries.

It is widely useful for:

• Parsing folding ranges in editors.
• Extracting specific snippets from code files.
• Transforming region-annotated text.

Where should I use this?

This package defines the AST structure. It does not implement the parsing logic for specific editors (like VSCode).

region-ast is not intended to be self-sufficient. It expects region markers to match to be able to parse regions in plain text. For example, see the vscode-region-parser package that implements region-ast to parse VSCode regions.

Otherwise, feel free to implement this specification to fit your own needs! 👍

🚀 Get started

This package is published on NPM.

npm install region-ast

🧬 Structure rules

The AST is a tree where each node represents a part of the document.

1. Nesting: Regions can be deeply nested inside other regions.
2. Completeness: A Region node is only formed if both a Start and an End marker are matched.
3. Orphans: If a region start or end marker is "alone" (no corresponding pair found), it is treated as plain Text.
4. Processing: The parsing logic is line-by-line.

🔹 Nodes

This specification defines the following nodes:

• Root

  The Root node represents the entire document. It is the unique top-level node.

• Region

  A Region represents a matched block containing a start marker, optional content, and an end marker.

  • Children: Must contain exactly one RegionStart (first child) and one RegionEnd (last child). It may contain any number of Region or Text nodes in between.

• RegionStart

  Represents the specific line or token that initiates a region.

• RegionEnd

  Represents the specific line or token that closes a region.

• Text

  Represents any literal text that is not part of a successfully matched region structure. This includes:

  • Standard code or content.
  • Orphaned region markers (unpaired start/end tags).

💡 Please check the Types references and the hierarchy in the API documentation.

Example

Given the following source text (using VSCode-style markers as an example):

// #region Setup
const x = 10
// #endregion
console.log(x)

The resulting region-ast tree would look like this:

{
  type: 'root',
  children: [
    {
      type: 'region',
      name: 'Setup',
      children: [
        { type: 'regionStart', value: '// #region Setup\n' },
        { type: 'text', value: 'const x = 10\n' },
        { type: 'regionEnd', value: '// #endregion\n' }
      ]
    },
    {
      type: 'text',
      value: 'console.log(x)'
    }
  ]
}

🔗 API

This package expose some unified plugins and utils.

Unified

import { unified } from 'unified'
import region, { parse, stringify } from 'region-ast'

unified().use(region, { markers: [ /* ... */ ] })
// Parser only
unified().use(parse, { markers: [ /* ... */ ] })
// Compiler only
unified().use(stringify)

💡 Please check the plugins references documentation.

Utils

To create tree from string, use the fromString util:

import { fromString } from 'region-ast/utils'

const tree = fromString(
`// #region Setup
const x = 10
// #endregion
console.log(x)`
)

// => Tree: { type: 'root', children: [ ... ] }

Vice versa, to create string from tree, use the toString util:

import { toString } from 'region-ast/utils'

toString(tree)

A Region class is exposed and is intended to be extended. Overwrite the markers static property:

import { Region } from 'region-ast/utils'

class CustomRegion extends Region {
  public static markers: Marker[] = [
    // Define your markers
  ]
}

💡 Please check the utils references documentation.

🤝 Contribute

You would like to contribute to this project? You are welcome!

First, please check:

• the contribution guide
• the code of conduct

👑 Author

Made with ❤ by Hervé Perchec

⚖️ License

MIT

📰 Changelog

See all changes to this project in the CHANGELOG.md file.

🧱 Related packages

• unist
• unified
• vscode-region-parser

README.md - this file was auto generated with juisy README templater. Don't edit it.