@futpib/parser 1.0.0

package/src/parserContext.test.ts

@@ -0,0 +1,154 @@
+import test from 'ava';
+import { ParserContextImplementation } from './parserContext.js';
+import { stringInputCompanion } from './inputCompanion.js';
+import { InputReaderImplementation } from './inputReader.js';
+import { ParserUnexpectedEndOfInputError } from './parserError.js';
+
+const commonParserContextArguments = [
+	undefined,
+	{
+		debugName: 'root',
+		errorJoinMode: 'all',
+	},
+] as const;
+
+test('parserContext.read', async t => {
+	const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function * () {
+		yield '';
+		yield 'abc';
+		yield 'def';
+		yield '';
+		yield 'gh';
+	})()), ...commonParserContextArguments);
+
+	t.is(await parserContext.read(0), 'a');
+	t.is(await parserContext.read(0), 'b');
+	t.is(await parserContext.read(5), 'h');
+
+	await t.throwsAsync(async () => parserContext.read(0), {
+		instanceOf: ParserUnexpectedEndOfInputError,
+	});
+});
+
+test('parserContext.lookahead', async t => {
+	const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function * () {
+		yield * 'abcdefgh';
+	})()), ...commonParserContextArguments);
+
+	const lookaheadContext1 = parserContext.lookahead();
+	const lookaheadContext2 = parserContext.lookahead();
+	const lookaheadContext3 = parserContext.lookahead({
+		sliceEnd: 3,
+	});
+
+	t.is(await lookaheadContext3.peek(2), 'c');
+	t.is(await lookaheadContext3.peek(3), undefined);
+	t.is(await lookaheadContext3.read(0), 'a');
+	t.is(await lookaheadContext3.read(0), 'b');
+	t.is(await lookaheadContext3.read(0), 'c');
+	t.is(await lookaheadContext3.peek(0), undefined);
+
+	t.is(await parserContext.peek(0), 'a');
+	t.is(await lookaheadContext1.peek(0), 'a');
+	t.is(await lookaheadContext2.peek(0), 'a');
+
+	t.is(await lookaheadContext1.read(0), 'a');
+	t.is(await parserContext.peek(0), 'a');
+	t.is(await lookaheadContext1.peek(0), 'b');
+	t.is(await lookaheadContext2.peek(0), 'a');
+
+	t.is(await parserContext.read(0), 'a');
+
+	t.is(parserContext.position, 1);
+	t.is(lookaheadContext1.position, 1);
+	t.is(lookaheadContext2.position, 0);
+	t.is(lookaheadContext3.position, 3);
+});
+
+test('parserContext.unlookahead', async t => {
+	const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function * () {
+		yield * 'abcdefgh';
+	})()), ...commonParserContextArguments);
+
+	const lookaheadContext = parserContext.lookahead();
+
+	t.is(await parserContext.peek(0), 'a');
+	t.is(await lookaheadContext.peek(0), 'a');
+
+	t.is(await lookaheadContext.read(0), 'a');
+	t.is(await parserContext.peek(0), 'a');
+	t.is(await lookaheadContext.peek(0), 'b');
+
+	lookaheadContext.unlookahead();
+
+	t.is(await lookaheadContext.read(0), 'b');
+	t.is(await lookaheadContext.read(0), 'c');
+});
+
+test('parserContext.unlookahead while peeking', async t => {
+	const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function * () {
+		yield * 'abcdefgh';
+	})()), ...commonParserContextArguments);
+
+	const lookaheadContext = parserContext.lookahead();
+
+	parserContext.skip(1);
+	lookaheadContext.skip(2);
+
+	const peekPromise = lookaheadContext.peek(0);
+
+	lookaheadContext.unlookahead();
+
+	t.is(await peekPromise, 'c');
+});
+
+test('parserContext deep unlookahead normal order', async t => {
+	const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function * () {
+		yield * 'abcdefgh';
+	})()), ...commonParserContextArguments);
+
+	const child = parserContext.lookahead();
+
+	t.is(await child.read(0), 'a');
+
+	const grandchild = child.lookahead();
+
+	t.is(await grandchild.read(0), 'b');
+
+	grandchild.unlookahead();
+
+	t.is(await child.read(0), 'c');
+
+	child.unlookahead();
+
+	t.is(await parserContext.read(0), 'd');
+});
+
+test('parserContext deep unlookahead weird order', async t => {
+	const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function * () {
+		yield * 'abcdefgh';
+	})()), ...commonParserContextArguments);
+
+	const child = parserContext.lookahead({
+		debugName: 'child',
+	});
+	const grandchild = child.lookahead({
+		debugName: 'grandchild',
+	});
+	const greatGrandchild = grandchild.lookahead({
+		debugName: 'greatGrandchild',
+	});
+
+	t.is(await greatGrandchild.read(0), 'a');
+
+	grandchild.unlookahead();
+
+	child.unlookahead();
+
+	greatGrandchild.unlookahead();
+
+	t.is(await greatGrandchild.read(0), 'b');
+	t.is(await grandchild.read(0), 'c');
+	t.is(await child.read(0), 'd');
+	t.is(await parserContext.read(0), 'e');
+});

package/src/parserContext.ts

@@ -0,0 +1,316 @@
+import invariant from 'invariant';
+import { type InputCompanion } from './inputCompanion.js';
+import { type InputReader } from './inputReader.js';
+import { ParserParsingFailedError, ParserUnexpectedEndOfInputError, ParserParsingInvariantError, ParserParsingJoinNoneError, ParserParsingJoinAllError, ParserParsingJoinDeepestError, ParserParsingJoinFurthestError } from './parserError.js';
+import { RunParserOptions } from './parser.js';
+import { Falsy, parserInvariant, ValueOrAccessor } from './parserInvariant.js';
+
+type LookaheadOptions = {
+	debugName?: string;
+	sliceEnd?: number;
+};
+
+type ParserContextOptions<Sequence, Element> =
+	& RunParserOptions<unknown, Sequence, Element>
+	& LookaheadOptions
+;
+
+export type ParserContext<Sequence, Element> = {
+	from(elements: Element[]): Sequence;
+	length(sequence: Sequence): number;
+	at(sequence: Sequence, index: number): Element | undefined;
+
+	get position(): number;
+	peek(offset: number): Promise<Element | undefined>;
+	skip(offset: number): void;
+
+	read(offset: number): Promise<Element>;
+
+	lookahead(options?: LookaheadOptions): ParserContext<Sequence, Element>;
+	unlookahead(): void;
+	dispose(): void;
+
+	invariant<T>(value: T, format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy>;
+	invariantJoin<T>(value: T, childErrors: ParserParsingFailedError[], format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy>;
+};
+
+let parserContextId = 0;
+
+export class ParserContextImplementation<Sequence, Element> implements ParserContext<Sequence, Element> {
+	private readonly _id = parserContextId++;
+	private readonly _depth: number;
+
+	private _exclusiveChildParserContext: ParserContext<Sequence, Element> | undefined = undefined;
+
+	constructor(
+		private readonly _inputCompanion: InputCompanion<Sequence, Element>,
+		private _inputReader: InputReader<Sequence, Element>,
+		private _parentParserContext: ParserContextImplementation<Sequence, Element> | undefined = undefined,
+		private readonly _options: ParserContextOptions<Sequence, Element>,
+	) {
+		this._depth = _parentParserContext ? _parentParserContext._depth + 1 : 0;
+	}
+
+	get [Symbol.toStringTag]() {
+		return [
+			'ParserContext',
+			[
+				this._options.debugName,
+				'(',
+				this._id,
+				')',
+			].join(''),
+			this._inputReader.toString(),
+		].join(' ');
+	}
+
+	from(elements: Element[]): Sequence {
+		return this._inputCompanion.from(elements);
+	}
+
+	length(sequence: Sequence): number {
+		return this._inputCompanion.length(sequence);
+	}
+
+	at(sequence: Sequence, index: number): Element | undefined {
+		return this._inputCompanion.at(sequence, index);
+	}
+
+	get position() {
+		return this._inputReader.position;
+	}
+
+	async peek(offset: number): Promise<Element | undefined> {
+		if (
+			this._options.sliceEnd !== undefined
+				&& (this.position + offset) >= this._options.sliceEnd
+		) {
+			return undefined;
+		}
+
+		return this._inputReader.peek(offset);
+	}
+
+	skip(offset: number) {
+		this._inputReader.skip(offset);
+	}
+
+	async read(offset: number): Promise<Element> {
+		const element = await this.peek(offset);
+
+		if (element === undefined) {
+			throw new ParserUnexpectedEndOfInputError('', this._depth, this.position);
+		}
+
+		this.skip(offset + 1);
+
+		return element;
+	}
+
+	lookahead(options: LookaheadOptions = {}): ParserContext<Sequence, Element> {
+		const lookaheadInputReader = this._inputReader.lookahead();
+
+		if (this.position !== lookaheadInputReader.position) {
+			debugger;
+		}
+
+		invariant(
+			this.position === lookaheadInputReader.position,
+			'lookahead this.position (%s) === lookaheadInputReader.position (%s)',
+			this.position,
+			lookaheadInputReader.position,
+		);
+
+		const lookaheadParserContext = new ParserContextImplementation(
+			this._inputCompanion,
+			lookaheadInputReader,
+			this,
+			{
+				...this._options,
+				...options,
+				debugName: [
+					this._options.debugName,
+					'(',
+					this._id,
+					')',
+					'/',
+					options.debugName,
+				].join(''),
+			},
+		);
+
+		if (this.position !== lookaheadParserContext.position) {
+			debugger;
+		}
+
+		invariant(
+			this.position === lookaheadParserContext.position,
+			'lookahead this.position (%s) === lookaheadParserContext.position (%s)',
+			this.position,
+			lookaheadParserContext.position,
+		);
+
+		return lookaheadParserContext;
+	}
+
+	unlookahead() {
+		invariant(this._parentParserContext !== undefined, 'this._parentParserContext !== undefined');
+		invariant(
+			(
+				this._parentParserContext._exclusiveChildParserContext === undefined
+				|| this._parentParserContext._exclusiveChildParserContext === this
+			),
+			[
+				'Parent\'s exclusive child must be undefined or this',
+				'this: %s',
+				'parent: %s',
+				'parent.exclusiveChild: %s',
+			].join('\n'),
+			this.toString(),
+			this._parentParserContext.toString(),
+			this._parentParserContext._exclusiveChildParserContext?.toString(),
+		);
+		invariant(
+			this._parentParserContext.position <= this.position,
+			'unlookahead this._parentParserContext.position (%s) <= this.position (%s)',
+			this._parentParserContext.position,
+			this.position,
+		);
+
+		const offset = this._inputReader.position - this._parentParserContext._inputReader.position;
+
+		this._parentParserContext.skip(offset);
+
+		invariant(
+			this._parentParserContext.position === this.position,
+			'unlookahead this._parentParserContext.position (%s) === this.position (%s)',
+			this._parentParserContext.position,
+			this.position,
+		);
+
+		this._inputReader = this._parentParserContext._inputReader;
+		this._parentParserContext._exclusiveChildParserContext = this;
+
+		if (this._exclusiveChildParserContext) {
+			this._exclusiveChildParserContext.unlookahead();
+		}
+	}
+
+	dispose() {
+		invariant(this._parentParserContext !== undefined, 'this._parentParserContext !== undefined');
+		invariant(
+			(
+				this._parentParserContext._exclusiveChildParserContext === undefined
+				|| this._parentParserContext._exclusiveChildParserContext === this
+			),
+			[
+				'Parent\'s exclusive child must be undefined or this',
+				'this: %s',
+				'parent: %s',
+				'parent.exclusiveChild: %s',
+			].join('\n'),
+			this.toString(),
+			this._parentParserContext.toString(),
+			this._parentParserContext._exclusiveChildParserContext?.toString(),
+		);
+
+		this._parentParserContext._exclusiveChildParserContext = undefined;
+		this._parentParserContext = undefined;
+	}
+
+	invariant<T>(value: T, format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy> {
+		const parserContext = this;
+
+		return parserInvariant(function (message: string) {
+			return new ParserParsingInvariantError(message, parserContext._depth, parserContext.position);
+		}, value, format, ...formatArguments);
+	}
+
+	invariantJoin<T>(value: T, childErrors: ParserParsingFailedError[], format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy> {
+		invariant(childErrors.length > 0, 'childErrors.length > 0');
+
+		const errorJoinMode = this._options.errorJoinMode ?? 'none';
+		const parserContext = this;
+
+		if (errorJoinMode === 'none') {
+			return parserInvariant(function (message: string) {
+				return new ParserParsingJoinNoneError(message, parserContext._depth, parserContext.position);
+			}, value, format, ...formatArguments);
+		}
+
+		if (errorJoinMode === 'furthest') {
+			return parserInvariant(function (message: string) {
+				let furthestPosition = 0;
+				let furthestChildErrors: ParserParsingFailedError[] = [];
+
+				for (const childError of childErrors) {
+					if (childError.position < furthestPosition) {
+						continue;
+					}
+
+					if (childError.position > furthestPosition) {
+						furthestPosition = childError.position;
+						furthestChildErrors = [ childError ];
+						continue;
+					}
+
+					furthestChildErrors.push(childError);
+				}
+
+				message += [
+					'',
+					'Furthest child error stacks, indented:',
+					...furthestChildErrors.flatMap(furthestChildError => furthestChildError.stack?.split('\n').map(line => '  ' + line)),
+					'End of furthest child error stacks',
+				].join('\n');
+
+				return new ParserParsingJoinFurthestError(message, parserContext._depth, furthestPosition, furthestChildErrors);
+			}, value, format, ...formatArguments);
+		}
+
+		if (errorJoinMode === 'deepest') {
+			return parserInvariant(function (message: string) {
+				let deepestDepth = 0;
+				let deepestChildErrors: ParserParsingFailedError[] = [];
+
+				for (const childError of childErrors) {
+					if (childError.depth < deepestDepth) {
+						continue;
+					}
+
+					if (childError.depth > deepestDepth) {
+						deepestDepth = childError.depth;
+						deepestChildErrors = [ childError ];
+						continue;
+					}
+
+					deepestChildErrors.push(childError);
+				}
+
+				message += [
+					'',
+					'Deepest child error stacks, indented:',
+					...deepestChildErrors.flatMap(deepestChildError => deepestChildError.stack?.split('\n').map(line => '  ' + line)),
+					'End of deepest child error stacks',
+				].join('\n');
+
+				return new ParserParsingJoinDeepestError(message, deepestDepth, parserContext.position, deepestChildErrors);
+			}, value, format, ...formatArguments);
+		}
+
+		if (errorJoinMode === 'all') {
+			return parserInvariant(function (message: string) {
+				message += [
+					'',
+					'Child error stacks, indented:',
+					...childErrors.flatMap(childError => childError.stack?.split('\n').map(line => '  ' + line)),
+					'End of child error stacks',
+				].join('\n');
+
+				return new ParserParsingJoinAllError(message, parserContext._depth, parserContext.position, childErrors);
+			}, value, format, ...formatArguments);
+		}
+
+		invariant(false, 'Unsupported errorJoinMode: %s', errorJoinMode);
+	}
+}

package/src/parserCreatorCompose.ts

@@ -0,0 +1,23 @@
+import { Parser } from "./parser.js";
+import { DeriveSequenceElement } from "./sequence.js";
+
+export function parserCreatorCompose<
+	Arguments extends unknown[],
+	OutputA,
+	OutputB,
+	Sequence,
+	Element = DeriveSequenceElement<Sequence>,
+>(
+	f1: (...args: Arguments) => Parser<OutputA, Sequence, Element>,
+	f2: (outputA: OutputA) => Parser<OutputB, Sequence, Element>,
+): (...args: Arguments) => Parser<OutputB, Sequence, Element> {
+	return (...args) => {
+		const parserA = f1(...args);
+
+		return async parserContext => {
+			const outputA = await parserA(parserContext);
+			const parserB = f2(outputA);
+			return parserB(parserContext);
+		};
+	};
+}

package/src/parserError.ts

@@ -0,0 +1,85 @@
+
+export class ParserError extends Error {
+	name = 'ParserError';
+}
+
+export class ParserImplementationError extends ParserError {
+	name = 'ParserImplementationError';
+}
+export class ParserImplementationInvariantError extends ParserImplementationError {
+	name = 'ParserImplementationInvariantError';
+}
+
+export class ParserParsingFailedError extends ParserError {
+	name = 'ParserParsingFailedError';
+
+	constructor(
+		message: string,
+		public readonly depth: number,
+		public readonly position: number,
+	) {
+		super([
+			'(position: ',
+			position,
+			') ',
+			message,
+		].join(''));
+	}
+}
+
+export class ParserParsingJoinError extends ParserParsingFailedError {
+	name = 'ParserParsingJoinError';
+
+	public readonly childErrors: ParserParsingFailedError[] = [];
+}
+
+export class ParserParsingJoinNoneError extends ParserParsingJoinError {
+	name = 'ParserParsingJoinNoneError';
+}
+
+export class ParserParsingJoinAllError extends ParserParsingJoinError {
+	name = 'ParserParsingJoinAllError';
+
+	constructor(
+		message: string,
+		depth: number,
+		position: number,
+		public readonly childErrors: ParserParsingFailedError[],
+	) {
+		super(message, depth, position);
+	}
+}
+
+export class ParserParsingJoinDeepestError extends ParserParsingJoinError {
+	name = 'ParserParsingJoinDeepestError';
+
+	constructor(
+		message: string,
+		depth: number,
+		position: number,
+		public readonly childErrors: ParserParsingFailedError[],
+	) {
+		super(message, depth, position);
+	}
+}
+
+export class ParserParsingJoinFurthestError extends ParserParsingJoinError {
+	name = 'ParserParsingJoinFurthestError';
+
+	constructor(
+		message: string,
+		depth: number,
+		position: number,
+		public readonly childErrors: ParserParsingFailedError[],
+	) {
+		super(message, depth, position);
+	}
+}
+
+export class ParserParsingInvariantError extends ParserParsingFailedError {
+	name = 'ParserParsingInvariantError';
+}
+
+export class ParserUnexpectedEndOfInputError extends ParserParsingFailedError {
+	name = 'ParserUnexpectedEndOfInputError';
+}

package/src/parserImplementationInvariant.ts

@@ -0,0 +1,6 @@
+import { ParserImplementationInvariantError } from './parserError.js';
+import { type Falsy, parserInvariant, type ValueOrAccessor } from './parserInvariant.js';
+
+export function parserImplementationInvariant<T>(value: T, format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy> {
+	return parserInvariant(ParserImplementationInvariantError, value, format, ...formatArguments);
+}

package/src/parserInvariant.ts

@@ -0,0 +1,26 @@
+import { type Constructor } from 'type-fest';
+
+export type Falsy = '' | 0 | false | undefined;
+
+export type ValueOrAccessor<T> = T | (() => T);
+
+export function parserInvariant<T>(
+	ErrorConstructor: Constructor<Error, [message: string]> | ((message: string) => Error),
+	value: T,
+	formatOrFormatLines: ValueOrAccessor<string | string[]>,
+	...formatArguments: any[]
+): Exclude<T, Falsy> {
+	if (value) {
+		return value as any;
+	}
+
+	let format = typeof formatOrFormatLines === 'function' ? formatOrFormatLines() : formatOrFormatLines;
+	format = Array.isArray(format) ? format.join('\n') : format;
+
+	throw new (ErrorConstructor as Constructor<Error>)(
+		format.replaceAll('%s', () => {
+			const argumentOrAccessor = formatArguments.shift();
+			return typeof argumentOrAccessor === 'function' ? argumentOrAccessor() : argumentOrAccessor;
+		}),
+	);
+}

package/src/promiseCompose.ts

@@ -0,0 +1,7 @@
+
+export function promiseCompose<A, B, C>(
+	f1: (a: A) => Promise<B>,
+	f2: (b: B) => C | Promise<C>,
+): (a: A) => Promise<C> {
+	return async a => f1(a).then(f2);
+}

package/src/sequence.ts

@@ -0,0 +1,10 @@
+
+export type DeriveSequenceElement<Sequence> = (
+	Sequence extends string
+		? string
+		: (
+			Sequence extends Uint8Array
+				? number
+				: never
+		)
+);

package/src/sequenceBuffer.test.ts

@@ -0,0 +1,50 @@
+import test from 'ava';
+import { SequenceBufferImplementation } from './sequenceBuffer.js';
+import { stringInputCompanion } from './inputCompanion.js';
+
+test('sequenceBuffer', t => {
+	const sequenceBuffer = new SequenceBufferImplementation(stringInputCompanion);
+
+	t.is(sequenceBuffer.peek(0), undefined);
+
+	sequenceBuffer.push('');
+
+	t.is(sequenceBuffer.peek(0), undefined);
+
+	sequenceBuffer.push('abc');
+
+	t.is(sequenceBuffer.peek(0), 'a');
+	t.is(sequenceBuffer.peek(1), 'b');
+	t.is(sequenceBuffer.peek(2), 'c');
+	t.is(sequenceBuffer.peek(3), undefined);
+
+	sequenceBuffer.push('def');
+
+	t.is(sequenceBuffer.peek(0), 'a');
+	t.is(sequenceBuffer.peek(3), 'd');
+	t.is(sequenceBuffer.peek(6), undefined);
+
+	sequenceBuffer.push('');
+
+	t.is(sequenceBuffer.peek(0), 'a');
+	t.is(sequenceBuffer.peek(3), 'd');
+	t.is(sequenceBuffer.peek(6), undefined);
+
+	sequenceBuffer.skip(1);
+
+	t.is(sequenceBuffer.peek(0), 'b');
+	t.is(sequenceBuffer.peek(3), 'e');
+	t.is(sequenceBuffer.peek(5), undefined);
+
+	sequenceBuffer.skip(3);
+
+	t.is(sequenceBuffer.peek(0), 'e');
+	t.is(sequenceBuffer.peek(2), undefined);
+
+	sequenceBuffer.push('gh');
+
+	t.is(sequenceBuffer.peek(0), 'e');
+	t.is(sequenceBuffer.peek(2), 'g');
+	t.is(sequenceBuffer.peek(3), 'h');
+	t.is(sequenceBuffer.peek(4), undefined);
+});