muggle-string 0.4.1 → 1.0.0-alpha.0

package/README.md

@@ -1,72 +1,40 @@
-This library aims to provide codegen helpers and data structure for Vue language plugin API v1.x that does not depend on Volar runtime.
+Ranked, conflict-free rewrites of a source text, rendered as format-neutral segments.
 
-## Why "Muggle"?
+muggle-string has no dependencies and knows no mapping format: a rewrite renders text and source runs to a sink, and the consumer turns them into whatever its tooling maps with.
 
-A better situation is Volar can use magic-string on the Vue plugin API, but currently can't do this easily.
+> 1.0 replaces the segment-array helpers of 0.4 (`replace`, `replaceSourceRange`, `toString`, ...). They are gone, not deprecated.
 
-This solution is just for Vue language plugin API v1.x and planned to be deprecate in v2.
+## Model
 
-## Usage
-
-The example is base-on [magic-string readme](https://github.com/rich-harris/magic-string#usage).
-
-```html
-<script>problems = 99</script>
+- Writers have ranks. A higher rank sits outside a lower one, and `core` sits outside all.
+- `insertBefore(offset, code)` and `insertAfter(offset, code)` attach code to a side of a char, so it goes wherever that char goes. `replace(start, end, code)` removes the text and puts `code` in the place of its first char.
+- Removals add up, so edits of different writers never conflict.
+- Only `core` moves text, with `cut(start, end, { data, placeholder })`. Cuts are nested or disjoint. A cut renders its text, with the edits of all writers in it, wherever its slice is placed, exactly once; the cut around it renders `placeholder` instead.
+- Code at the head or tail of a cut belongs to the outermost cut that has that edge.
+- `order` sorts the entries of one writer at one side of one char; equal keys keep call order.
+- The first render freezes the rewrite.
 
-<more-script lang="js">console.log( answer )</more-script>
-```
+## Usage
 
 ```ts
-import {
-	toString,
-	replace,
-} from 'muggle-string';
-
-/** @type {import('@volar/vue-language-core').VueLanguagePlugin} */
-const plugin = () => {
-	return {
-		name: 'example-vue-language-plugin',
-		version: 1,
-		resolveEmbeddedFile(fileName, sfc, embeddedFile) {
-			if (embeddedFile.fileName.replace(fileName, '').match(/^\.(js|ts|jsx|tsx)$/)) {
-
-				const s = embeddedFile.content;
-				toString(s); // 'problems = 99'
-
-				replace(s, 'problems', 'answer');
-				toString(s); // 'answer = 99'
-
-				replace(s, '99', '42');
-				toString(s); // 'answer = 42'
-
-				// add string by Array method directly
-				s.unshift('var ');
-				s.push(';');
-				toString(s); // 'var answer = 42;'
-
-				for (const block of sfc.customBlocks) {
-					if (block.type === 'more-script') {
-						s.push([
-							block.content, // text to add
-							block.name, // source
-							0, // content offset in source
-							{
-								// language capabilities to enable in this segment
-								hover: true,
-								references: true,
-								definition: true,
-								diagnostic: true,
-								rename: true,
-								completion: true,
-								semanticTokens: true,
-							},
-						]);
-						toString(s); // 'var answer = 42;console.log( answer )'
-					}
-				}
-			}
-		}
-	};
-};
-module.exports = plugin;
+import { createSourceRewrite, type MappedSegment, type Segment } from 'muggle-string';
+
+const text = 'const props = defineProps<{ a: string }>();';
+const rewrite = createSourceRewrite<string, string>('setup', text);
+const { core } = rewrite;
+
+const body = core.cut(0, text.length, { data: 'body' });
+const typeArg = core.cut(text.indexOf('{'), text.lastIndexOf('}') + 1, { data: 'alias', placeholder: '__VLS_Props' });
+core.insertBefore(0, () => ['type __VLS_Props = ', typeArg, ';\n']);
+
+const segments: Segment<string, string>[] = [];
+body.render({
+	text: text => segments.push(text),
+	source: (rewrite, start, end, data) => segments.push([rewrite.text.slice(start, end), rewrite.source, start, data]),
+	segment: (segment: MappedSegment<string, string>) => segments.push(segment),
+});
+// type __VLS_Props = { a: string };
+// const props = defineProps<__VLS_Props>();
 ```
+
+Code is a string, or a function, called at most once and only if the code renders, that yields strings, mapped segments, and slices.

package/out/index.d.ts

@@ -1,10 +1,2 @@
-import { Segment } from "./types";
+export * from './sourceRewrite';
 export * from './types';
-export * from './track';
-export declare function getLength(segments: Segment<any>[]): number;
-export declare function toString<T extends Segment<any>>(segments: T[]): string;
-export declare function create(source: string): Segment[];
-export declare function replace<T extends Segment<any>>(segments: T[], pattern: string | RegExp, ...replacers: (T | ((match: string) => T))[]): void;
-export declare function replaceAll<T extends Segment<any>>(segments: T[], pattern: RegExp, ...replacers: (T | ((match: string) => T))[]): void;
-export declare function replaceSourceRange<T extends Segment<any>>(segments: T[], source: string | undefined, startOffset: number, endOffset: number, ...newSegments: T[]): boolean;
-export declare function replaceRange<T extends Segment<any>>(segments: T[], startOffset: number, endOffset: number, ...newSegments: T[]): void;

package/out/index.js

@@ -14,153 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.replaceRange = exports.replaceSourceRange = exports.replaceAll = exports.replace = exports.create = exports.toString = exports.getLength = void 0;
-const binarySearch_1 = require("./binarySearch");
-const track_1 = require("./track");
+__exportStar(require("./sourceRewrite"), exports);
 __exportStar(require("./types"), exports);
-__exportStar(require("./track"), exports);
-function getLength(segments) {
-    let length = 0;
-    for (const segment of segments) {
-        length += typeof segment == 'string' ? segment.length : segment[0].length;
-    }
-    return length;
-}
-exports.getLength = getLength;
-function toString(segments) {
-    return segments.map(s => typeof s === 'string' ? s : s[0]).join('');
-}
-exports.toString = toString;
-function create(source) {
-    return [[source, undefined, 0]];
-}
-exports.create = create;
-function replace(segments, pattern, ...replacers) {
-    const str = toString(segments);
-    const match = str.match(pattern);
-    if (match && match.index !== undefined) {
-        const startOffset = match.index;
-        const endOffset = startOffset + match[0].length;
-        (0, track_1.offsetStack)();
-        replaceRange(segments, startOffset, endOffset, ...replacers.map(replacer => typeof replacer === 'function' ? replacer(match[0]) : replacer));
-        (0, track_1.resetOffsetStack)();
-    }
-}
-exports.replace = replace;
-function replaceAll(segments, pattern, ...replacers) {
-    const str = toString(segments);
-    const allMatch = str.matchAll(pattern);
-    let length = str.length;
-    let lengthDiff = 0;
-    for (const match of allMatch) {
-        if (match.index !== undefined) {
-            const startOffset = match.index + lengthDiff;
-            const endOffset = startOffset + match[0].length;
-            (0, track_1.offsetStack)();
-            replaceRange(segments, startOffset, endOffset, ...replacers.map(replacer => typeof replacer === 'function' ? replacer(match[0]) : replacer));
-            (0, track_1.resetOffsetStack)();
-            const newLength = getLength(segments);
-            lengthDiff += newLength - length;
-            length = newLength;
-        }
-    }
-}
-exports.replaceAll = replaceAll;
-function replaceSourceRange(segments, source, startOffset, endOffset, ...newSegments) {
-    for (const segment of segments) {
-        if (typeof segment === 'string') {
-            continue;
-        }
-        if (segment[1] === source) {
-            const segmentStart = segment[2];
-            const segmentEnd = segment[2] + segment[0].length;
-            if (segmentStart <= startOffset && segmentEnd >= endOffset) {
-                const inserts = [];
-                if (startOffset > segmentStart) {
-                    inserts.push(trimSegmentEnd(segment, startOffset - segmentStart));
-                }
-                for (const newSegment of newSegments) {
-                    inserts.push(newSegment);
-                }
-                if (endOffset < segmentEnd) {
-                    inserts.push(trimSegmentStart(segment, endOffset - segmentEnd));
-                }
-                combineStrings(inserts);
-                (0, track_1.offsetStack)();
-                segments.splice(segments.indexOf(segment), 1, ...inserts);
-                (0, track_1.resetOffsetStack)();
-                return true;
-            }
-        }
-    }
-    return false;
-}
-exports.replaceSourceRange = replaceSourceRange;
-function replaceRange(segments, startOffset, endOffset, ...newSegments) {
-    const offsets = toOffsets(segments);
-    const startIndex = (0, binarySearch_1.binarySearch)(offsets, startOffset);
-    const endIndex = (0, binarySearch_1.binarySearch)(offsets, endOffset);
-    const startSegment = segments[startIndex];
-    const endSegment = segments[endIndex];
-    const startSegmentStart = offsets[startIndex];
-    const endSegmentStart = offsets[endIndex];
-    const endSegmentEnd = offsets[endIndex] + (typeof endSegment === 'string' ? endSegment.length : endSegment[0].length);
-    const inserts = [];
-    if (startOffset > startSegmentStart) {
-        inserts.push(trimSegmentEnd(startSegment, startOffset - startSegmentStart));
-    }
-    for (const newSegment of newSegments) {
-        inserts.push(newSegment);
-    }
-    if (endOffset < endSegmentEnd) {
-        inserts.push(trimSegmentStart(endSegment, endOffset - endSegmentStart));
-    }
-    combineStrings(inserts);
-    (0, track_1.offsetStack)();
-    segments.splice(startIndex, endIndex - startIndex + 1, ...inserts);
-    (0, track_1.resetOffsetStack)();
-}
-exports.replaceRange = replaceRange;
-function combineStrings(segments) {
-    for (let i = segments.length - 1; i >= 1; i--) {
-        if (typeof segments[i] === 'string' && typeof segments[i - 1] === 'string') {
-            segments[i - 1] = segments[i - 1] + segments[i];
-            (0, track_1.offsetStack)();
-            segments.splice(i, 1);
-            (0, track_1.resetOffsetStack)();
-        }
-    }
-}
-function trimSegmentEnd(segment, trimEnd) {
-    if (typeof segment === 'string') {
-        return segment.slice(0, trimEnd);
-    }
-    return [
-        segment[0].slice(0, trimEnd),
-        ...segment.slice(1),
-    ];
-}
-function trimSegmentStart(segment, trimStart) {
-    if (typeof segment === 'string') {
-        return segment.slice(trimStart);
-    }
-    if (trimStart < 0) {
-        trimStart += segment[0].length;
-    }
-    return [
-        segment[0].slice(trimStart),
-        segment[1],
-        segment[2] + trimStart,
-        ...segment.slice(3),
-    ];
-}
-function toOffsets(segments) {
-    const offsets = [];
-    let offset = 0;
-    for (const segment of segments) {
-        offsets.push(offset);
-        offset += typeof segment == 'string' ? segment.length : segment[0].length;
-    }
-    return offsets;
-}
 //# sourceMappingURL=index.js.map

package/out/sourceRewrite.d.ts

@@ -0,0 +1,57 @@
+import type { MappedSegment, Segment } from './types';
+/** Generated code: eager text, or a function that is called at most once, and only if the code renders. */
+export type RewriteCode<Source, Data> = string | (() => Iterable<Segment<Source, Data> | RewriteSlice<Source, Data>>);
+export interface InsertOptions {
+    /** Ascending among the entries of one writer at one side of one char; equal keys keep call order. Default 0. */
+    order?: number;
+}
+/** Where a slice renders to. */
+export interface RewriteSink<Source, Data> {
+    /** Generated text, never empty. */
+    text(text: string): void;
+    /** The kept chars `start`..`end` (never empty) of the text of `rewrite`, owned by a cut whose data is `data`. */
+    source(rewrite: SourceRewrite<Source, Data>, start: number, end: number, data: Data): void;
+    /** A mapped segment that generated code carries. */
+    segment(segment: MappedSegment<Source, Data>): void;
+}
+export interface RewriteWriter<Source, Data> {
+    /**
+     * `code` right before the text that starts at `offset`; it goes wherever that text goes. At the end of the text,
+     * no text starts there: the code stays after all text.
+     */
+    insertBefore(offset: number, code: RewriteCode<Source, Data>, options?: InsertOptions): void;
+    /**
+     * `code` right after the text that ends at `offset`; it goes wherever that text goes. At 0, no text ends there: the
+     * code stays before all text.
+     */
+    insertAfter(offset: number, code: RewriteCode<Source, Data>, options?: InsertOptions): void;
+    /** The text at `start`..`end` (not empty) is not rendered; `code` takes the place of its first char. */
+    replace(start: number, end: number, code: RewriteCode<Source, Data>, options?: InsertOptions): void;
+}
+export interface CoreRewriteWriter<Source, Data> extends RewriteWriter<Source, Data> {
+    /**
+     * The text at `start`..`end`, with the edits of all writers in it, rendered where the returned slice is placed,
+     * exactly once. In the cut that contains it, `placeholder` takes its place. Cuts are nested or disjoint, and of two
+     * cuts of one range the later is inside the earlier. A zero-width cut owns no char and has no placeholder; on an
+     * empty text, the first one renders the inserts.
+     */
+    cut(start: number, end: number, options: {
+        data: Data;
+        placeholder?: RewriteCode<Source, Data>;
+    }): RewriteSlice<Source, Data>;
+}
+export interface RewriteSlice<Source, Data> {
+    render(sink: RewriteSink<Source, Data>): void;
+}
+/**
+ * Edits of one source text by ranked writers. Inserts attach to a side of a char, removals add up, and only core
+ * moves text, by nested cuts, so edits never conflict. The first render freezes the edits.
+ */
+export interface SourceRewrite<Source, Data> {
+    readonly source: Source;
+    readonly text: string;
+    readonly core: CoreRewriteWriter<Source, Data>;
+    /** The writer of `rank`, a non-negative integer. A higher rank sits outside a lower one, and core outside all. */
+    writer(rank: number): RewriteWriter<Source, Data>;
+}
+export declare function createSourceRewrite<Source, Data>(source: Source, text: string): SourceRewrite<Source, Data>;