Monocart Locator

A lightweight source code position locator for converting between offset and line/column, with built-in line and comment parsing. Zero dependencies.

Features

• Convert between offset and line/column positions
• Parse source code into lines with metadata (length, indent, blank, comment)
• Detect line comments (//) and block comments (/* */) with template literal (${}) support
• O(log n) position lookups via binary search

Install

npm i monocart-locator

Usage

Locator

The main API for source code position conversion.

const { Locator } = require('monocart-locator');
// or
// import { Locator } from 'monocart-locator';

const locator = new Locator(source);

// Convert 1-based line/column to offset
const offset = locator.locationToOffset({ line: 2, column: 5 });

// Convert offset to 1-based location
const loc = locator.offsetToLocation(100);
// { line, column, length, indent, start, end, blank, comment, text }

// Get source substring
const slice = locator.getSlice(0, 10);

// Get line info by 1-based line number
const lineInfo = locator.getLine(1);

// Access all parsed lines and comments
console.log(locator.lines);     // LineItem[]
console.log(locator.comments);  // CommentItem[]

LineParser

Parse source code into lines with metadata.

const { LineParser } = require('monocart-locator');

const lineParser = new LineParser(source);

console.log(lineParser.lines);     // LineItem[]
console.log(lineParser.comments);  // CommentItem[]

// Find line by offset
const lineInfo = lineParser.findLine(100);

CommentParser

Detect all line and block comments in source code.

const { CommentParser } = require('monocart-locator');

const commentParser = new CommentParser(source);

console.log(commentParser.comments);  // CommentItem[]

// Check if a range is inside a comment
const isComment = commentParser.isComment(start, end);

API

Locator

| Property / Method | Description | |---|---| | source | Original source string | | lines | LineItem[] - all parsed lines | | comments | CommentItem[] - all parsed comments | | locationToOffset({ line, column }) | Convert 1-based line and column to offset | | offsetToLocation(offset) | Convert offset to LocationItem (1-based line and column) | | getSlice(start, end) | Get source substring by offsets | | getLine(line) | Get LineItem by 1-based line number |

LineItem

| Property | Type | Description | |---|---|---| | line | number | 0-based line number | | length | number | Line length (excluding newline) | | indent | number | Leading whitespace count | | start | number | Start offset in source | | end | number | End offset in source | | blank | boolean | Whether line has no non-whitespace content | | comment | boolean | Whether first non-whitespace is inside a comment | | text | string | Line text (excluding newline) |

LocationItem

Returned by offsetToLocation(). Extends LineItem with 1-based position: | Property | Type | Description | |---|---|---| | line | number | 1-based line number | | column | number | 0-based column offset |

CommentItem

| Property | Type | Description | |---|---|---| | block | boolean | true for block comments (/* */), false for line comments (//) | | start | number | Start offset in source | | end | number | End offset in source | | text | string | Comment text including delimiters |

License

MIT