@mattwca/little-parser-lib 1.0.3 → 1.0.5

package/README.md

@@ -8,8 +8,9 @@ A lightweight, flexible TypeScript library for building parsers using parser com
 - 🔍 **Built-in Tokenizer**: Flexible tokenization with regex and string matching
 - 📝 **TypeScript First**: Full type safety and IntelliSense support
 - 🎯 **Backtracking Support**: Automatic position restoration on parse failures
+- 🔒 **Infinite Loop Protection**: `many` combinator detects non-progressing parsers
 - 📦 **Zero Dependencies**: Lightweight with no external runtime dependencies
-- ✨ **Widely Compatible**: Packaged with [tsdown](https://tsdown.dev)
+- ✨ **Widely Compatible**: Packaged with [tsdown](https://tsdown.dev) for ESM and CJS support
 
 ## Installation
 
@@ -70,11 +71,29 @@ A parser function (`ParseFn<T>`) takes a `TokenStream` and returns a `ParserResu
 - `SuccessfulParserResult<T>`: Contains the parsed result
 - `FailedParserResult`: Contains error message and position
 
+### TokenStream
+
+The `TokenStream` class manages the token consumption and position tracking during parsing:
+
+**Core Methods:**
+- `peek()`: Look at the next token without consuming it
+- `consume()`: Consume and return the next token
+- `consumeIf(...types)`: Conditionally consume a token if it matches the specified types
+
+**Position Management:**
+- `storePosition()`: Save current position to the stack (for backtracking)
+- `clearPosition()`: Remove the most recent saved position
+- `restorePosition()`: Restore to the most recent saved position
+
+**Utility Methods:**
+- `peekRemainder()`: Get all remaining tokens as a string
+- `getPositionForError()`: Get current position info for error reporting
+
 ## Parser Combinators
 
 ### `and(...parsers)`
 
-Combines multiple parsers in sequence. All parsers must succeed.
+Combines multiple parsers in sequence. All parsers must succeed. Returns a tuple array preserving the types of each parser's result.
 
 ```typescript
 const parser = and(
@@ -82,6 +101,7 @@ const parser = and(
   anyOf('identifier'),
   anyOf('semicolon')
 );
+// Result type is [Token, Token, Token]
 ```
 
 ### `or(...parsers)`
@@ -98,7 +118,7 @@ const parser = or(
 
 ### `many(parser)`
 
-Applies a parser repeatedly until it fails (requires at least one success).
+Applies a parser repeatedly until it fails or stops making progress. Requires at least one successful match. Includes infinite loop protection by detecting when the parser doesn't advance the token position.
 
 ```typescript
 const parser = many(anyOf('digit')); // Parses one or more digits
@@ -178,15 +198,15 @@ const parser = and(
 
 ### `runParser(parser, tokenStream)`
 
-Runs a parser on a token stream. Throws `ParsingError` on failure.
+Runs a parser on a token stream. Throws `ParserError` on failure.
 
 ```typescript
 try {
   const result = runParser(myParser, tokenStream);
   console.log(result.result);
 } catch (error) {
-  if (error instanceof ParsingError) {
-    console.error(`Parse error at ${error.position.line}:${error.position.column}`);
+  if (error instanceof ParserError) {
+    console.error(`Parse error at ${error.location.line}:${error.location.column}`);
   }
 }
 ```
@@ -199,57 +219,18 @@ Convenience method to tokenize and parse in one step.
 const result = runParserOnString(myParser, 'input string', tokenizer);
 ```
 
-## Utilities
-
-The library provides utility functions to help with common parser result manipulation tasks.
-
-### `unwrapResult(items)`
-
-Flattens nested arrays that result from combining parsers like `and` and `many`. This is particularly useful when you have deeply nested parser structures and need a flat array of results.
-
-```typescript
-import { unwrapResult } from '@mattwca/little-parser-lib';
-
-// Parser results can be nested
-const parser = and(
-  many(anyOf('letter')),
-  many(anyOf('digit'))
-);
-
-const result = runParser(parser, stream);
-// result.result might be: [[token1, token2], [token3, token4]]
-
-const flattened = unwrapResult(result.result);
-// flattened is: [token1, token2, token3, token4]
-```
-
-**Parameters:**
-- `items: (T | T[])[]` - An array that may contain nested arrays
-
-**Returns:**
-- `T[]` - A flattened array with all nested items extracted
-
-**Example Use Cases:**
-
-```typescript
-// Use with map to process flattened results
-const tokenParser = map(
-  and(many(anyOf('letter')), many(anyOf('digit'))),
-  (results) => unwrapResult(results).map(t => t.value).join('')
-);
-```
-
 ## Example: Simple Expression Parser
 
 ```typescript
 import { 
   Tokenizer, 
-  TokenStream, 
+  isSuccessfulResult,
   anyOf, 
   and, 
   or, 
   many, 
   map, 
+  optional,
   runParserOnString 
 } from '@mattwca/little-parser-lib';
 
@@ -258,31 +239,43 @@ const tokenizer = new Tokenizer()
   .withTokenType('digit', /[0-9]/)
   .withTokenType('plus', '+')
   .withTokenType('minus', '-')
+  .withTokenType('multiply', '*')
+  .withTokenType('divide', '/')
   .withTokenType('whitespace', /\s/);
 
 // Define parsers
 const digit = anyOf('digit');
+const ws = optional(anyOf('whitespace'));
+
+// Parse a number (one or more digits)
 const number = map(
   many(digit),
   (tokens) => parseInt(tokens.map(t => t.value).join(''))
 );
 
+// Parse an operator
 const operator = or(
   anyOf('plus'),
-  anyOf('minus')
+  anyOf('minus'),
+  anyOf('multiply'),
+  anyOf('divide')
 );
 
+// Parse a complete expression: number operator number
 const expression = and(
   number,
-  optional(anyOf('whitespace')),
+  ws,
   operator,
-  optional(anyOf('whitespace')),
+  ws,
   number
 );
 
-// Parse
-const result = runParserOnString(expression, '10 + 5', tokenizer);
-console.log(result.result); // [10, null, {...}, null, 5]
+// Parse and extract values
+const result = runParserOnString(expression, '42 + 8', tokenizer);
+if (isSuccessfulResult(result)) {
+  const [leftNum, , op, , rightNum] = result.result;
+  console.log(`${leftNum} ${op.value} ${rightNum}`); // "42 + 8"
+}
 ```
 
 ## Error Handling
@@ -293,31 +286,101 @@ The library provides detailed error messages with position information:
 try {
   const result = runParser(myParser, stream);
 } catch (error) {
-  if (error instanceof ParsingError) {
+  if (error instanceof ParserError) {
     console.error(`
       Error: ${error.message}
-      Line: ${error.position.line}
-      Column: ${error.position.column}
-      Position: ${error.position.position}
+      Line: ${error.location.line}
+      Column: ${error.location.column}
+      Position: ${error.location.position}
     `);
   }
 }
 ```
 
+## Self-referencing ("recursive") parsing
+
+Parsers should be able to parse complex expressions, which can occasionally require a parser to be able to call itself, or call another parser which in turn calls it.
+
+Taking the expression parser example above, we can modify it to support parsing of nested algebraic expressions:
+
+```typescript
+type Expression = {
+  left: Expression | number;
+  operator: string;
+  right: Expression | number;
+};
+
+type AlgebraicExpression = {
+  symbol: string;
+  expression: Expression;
+};
+
+const tokenizer = new Tokenizer()
+  ...
+  .withTokenType('left_parenthesis', '(')
+  .withTokenType('right_parenthesis', ')')
+  .withTokenType('letter', /[a-zA-Z]/);
+
+let expression: ParseFn<number | AlgebraicExpression | Expression> | null = null;
+
+const letter = anyOf('letter');
+const leftParen = anyOf('left_parenthesis');
+const rightParen = anyOf('right_parenthesis');
+
+const algebraicExpression: ParseFn<AlgebraicExpression> = (ts) => {
+  return map(
+    and(letter, leftParen, expression!, rightParen),
+    ([{ value: symbol },, expression]) => {
+      return {
+        symbol,
+        expression
+      }
+    }
+  )(ts);
+};
+
+expression = map(
+  and(
+    or<number | AlgebraicExpression>(number, algebraicExpression!),
+    ws,
+    operator,
+    ws,
+    or<number | AlgebraicExpression>(number, algebraicExpression!),
+  ),
+  ([leftExpr,, { value: operator },, rightExpr]) => ({
+    left: leftExpr,
+    operator,
+    right: rightExpr,
+  })
+);
+
+const result = runParserOnString(expression, 'a(3 + b(7 + 8)) + c(1 + 2)', tokenizer);
+if (isSuccessfulResult(result)) {
+  console.log(JSON.stringify(result.result, null, 2));
+}
+```
+
 ## API Reference
 
 ### Classes
 
 - `Tokenizer`: Converts input strings into tokens
 - `TokenStream`: Manages token consumption and backtracking
-- `ParsingError`: Error thrown when parsing fails
+  - `peek()`: Look at the next token without consuming it
+  - `consume()`: Get and advance to the next token
+  - `consumeIf(...types)`: Conditionally consume token if it matches given types
+  - `peekRemainder()`: Get remaining unparsed tokens as a string
+  - `storePosition()`, `clearPosition()`, `restorePosition()`: Manual backtracking control
+- `ParserError`: Error thrown when parsing fails
 
 ### Types
 
 - `Token`: Represents a single token with type, value, and position
-- `TokenType`: String identifier for token types
+- `TokenType`: String identifier for token types (or 'end_of_input')
+- `TokenPosition`: Position info with line and column numbers
 - `ParseFn<T>`: Function that takes a TokenStream and returns ParserResult<T>
 - `ParserResult<T>`: Union of SuccessfulParserResult<T> and FailedParserResult
+- `ParserErrorPosition`: Extended position info including token stream position
 
 ### Combinators
 
@@ -341,7 +404,6 @@ try {
 - `runParserOnString(parser, input, tokenizer)`: Execute parser on string
 - `isSuccessfulResult(result)`: Type guard for successful results
 - `isFailedResult(result)`: Type guard for failed results
-- `unwrapResult(results)`: Unwrap nested parser results
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattwca/little-parser-lib",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",

package/src/index.ts

@@ -1,3 +1,2 @@
 export * from './tokenizer';
-export * from './parsers';
-export * from './utils';
+export * from './parsers';

package/src/parsers/ParserError.ts

@@ -0,0 +1,19 @@
+/**
+ * The position of a parsing error, including position in the token stream,
+ * source line number and column number.
+ */
+export type ParserErrorPosition = {
+  line: number;
+  column: number;
+  position: number;
+}
+
+/**
+ * Represents a parsing error with a specific message.
+ */
+export class ParserError extends Error {
+  constructor(message: string, public location: ParserErrorPosition) {
+    super(`Parser Error [${location.line}:${location.column}]: ${message}`);
+    this.location = location;
+  }
+}

package/src/parsers/combinators.ts

@@ -0,0 +1,195 @@
+import { TokenStream } from "../tokenizer";
+import { FailedParserResult, isFailedResult, isSuccessfulResult, ParseFn, SuccessfulParserResult } from "./types";
+
+/**
+ * A combinator which runs a sequence of parsers, returning a tuple of their results. If one of the parsers fail, the
+ * entire sequence fails (in which case the first failure encountered is returned).
+ * @typeParam Parsers A tuple of the ParseFn types to be combined. Used to infer the result tuple type. 
+ * @param parsers The parsers to run.
+ */
+export function and<Parsers extends ParseFn<any>[]>(
+  ...parsers: Parsers
+): ParseFn<{ [K in keyof Parsers]: Parsers[K] extends ParseFn<infer R> ? R : never }> {
+  return (tokenStream: TokenStream) => {
+    const results: any[] = [];
+
+    for (const parser of parsers) {
+      const parseResult = parser(tokenStream);
+
+      if (isFailedResult(parseResult)) {
+        return parseResult;
+      }
+
+      results.push(parseResult.result);
+    }
+
+    return { result: results } as any;
+  };
+}
+
+/**
+ * A combinator which attempts to run a given parser, restoring the token position (backtracking) if it fails. The
+ * result of the parser (successful or failed) will be returned.
+ * @typeParam T The type of the parse result.
+ * @param parser The parser to attempt.
+ * @returns A new parser that attempts to run the given parser, backtracking on failure.
+ */
+export function attempt<T>(parser: ParseFn<T>): ParseFn<T> {
+  return (tokenStream: TokenStream) => {
+    tokenStream.storePosition();
+
+    const result = parser(tokenStream);
+
+    if (isSuccessfulResult(result)) {
+      tokenStream.clearPosition();
+    } else {
+      tokenStream.restorePosition();
+    }
+
+    return result;
+  };
+}
+
+/**
+ * A combinator which makes a given parser optional. If the parser fails, it will still return a successful result,
+ * with a `null` value. By default, the parser will also backtrack on failure.
+ * @typeParam T The type of the parse result.
+ * @param parser The parser to make optional.
+ * @param shouldBacktrack Whether to backtrack the token stream position if the parser fails. Defaults to `true`.
+ * @returns A new parser that returns either the result of the given parser, or `null` if it fails.
+ */
+export function optional<T>(parser: ParseFn<T>, shouldBacktrack: boolean = true): ParseFn<T | null> {
+  return (tokenStream: TokenStream) => {
+    const parseFn = shouldBacktrack ? attempt(parser) : parser;
+    const result = parseFn(tokenStream);
+
+    if (isSuccessfulResult(result)) {
+      return result;
+    }
+
+    return { result: null };
+  };
+}
+
+/**
+ * A combinator which tries multiple parsers, returning the result of the first one that succeeds. If all parsers fail
+ * returns the error from the parser that got the furthest.
+ * @typeParam T The type of the parse result.
+ * @param parsers The parsers to try.
+ * @returns A new parser that tries each of the given parsers in sequence.
+ */
+export function or<T>(...parsers: ParseFn<T>[]): ParseFn<T> {
+  return (tokenStream: TokenStream) => {
+    let deepestError = null;
+    let deepestErrorPosition = -1;
+
+    for (const parser of parsers) {
+      const tryParse = attempt(parser);
+      const result = tryParse(tokenStream);
+
+      if (isSuccessfulResult(result)) {
+        return result as SuccessfulParserResult<T>;
+      }
+
+      if (isFailedResult(result)) {
+        const { position } = result;
+
+        if (position.position > deepestErrorPosition) {
+          deepestError = result;
+          deepestErrorPosition = position.position;
+        }
+      }
+    }
+
+    return deepestError as FailedParserResult;
+  };
+}
+
+/**
+ * A combinator which applies a parser repeatedly until it fails or doesn't make progress (move the position), collecting
+ * all successful results into an array. If the parser fails on the first attempt, it returns a failure.
+ * @typeParam T The type of the parse result.
+ * @param parser The parser to apply repeatedly.
+ * @returns A new parser that applies the given parser repeatedly, collecting results into an array.
+ */
+export function many<T>(parser: ParseFn<T>): ParseFn<T[]> {
+  return (tokenStream: TokenStream) => {
+    const results: T[] = [];
+
+    let parseFailure = null;
+
+    while (true) {
+      const positionBefore = tokenStream.position;
+      tokenStream.storePosition();
+
+      const result = parser(tokenStream);
+
+      if (isSuccessfulResult(result)) {
+        const positionAfter = tokenStream.position;
+
+        // Check if the parser made any progress - if it didn't, we break out to avoid infinite loops.
+        if (positionAfter === positionBefore) {
+          tokenStream.restorePosition();
+          break;
+        }
+
+        results.push(result.result);
+        tokenStream.clearPosition();
+      } else {
+        parseFailure = result;
+        tokenStream.restorePosition();
+        break;
+      }
+    }
+
+    if (parseFailure && results.length === 0) {
+      return parseFailure;
+    }
+
+    return { result: results };
+  };
+}
+
+/**
+ * A combinator which maps the successful result of a given parser using a mapping function. Failures are passed through unchanged.
+ * @typeParam T The type of the original parser's result.
+ * @typeParam U The type of the mapped result.
+ * @param parser The parser whose result to be mapped.
+ * @param mapFn A function that takes the parser's result and returns a new value.
+ * @returns A new parser that applies the mapping function to the result of the original parser.
+ */
+export function map<T, U>(parser: ParseFn<T>, mapper: (value: T) => U): ParseFn<U> {
+  return (tokenStream: TokenStream) => {
+    const result = parser(tokenStream);
+
+    if (isSuccessfulResult(result)) {
+      return { result: mapper(result.result) };
+    }
+
+    return result;
+  };
+}
+
+/**
+ * A combinator which prepends a given label to any error message(s) produced by a given parser.
+ * @typeParam T The type of the parse result.
+ * @param label The label to prefix the error message with.
+ * @param parser The parser to label.
+ * @returns A new parser that adds the label to any error messages from the original parser.
+ */
+export function label<T>(label: string, parser: ParseFn<T>): ParseFn<T> {
+  return (tokenStream: TokenStream) => {
+    const result = parser(tokenStream);
+
+    if (isSuccessfulResult(result)) {
+      return result;
+    }
+
+    const errorMessage = `${label}: ${result.errorMessage}`;
+
+    return {
+      errorMessage,
+      position: result.position,
+    };
+  }
+}

package/src/parsers/index.ts

@@ -1,3 +1,5 @@
+export * from './ParserError';
+export * from './types';
 export * from './parsers';
-export * from './ParsingError';
-export * from './types';
+export * from './combinators';
+export * from './runners';

package/src/parsers/parsers.ts

@@ -1,160 +1,10 @@
-import { Tokenizer, TokenStream } from "../tokenizer";
+import { TokenStream } from "../tokenizer";
 import { Token, TokenType } from "../tokenizer/types";
-import { ParsingError } from "./ParsingError";
-import { FailedParserResult, isFailedResult, isSuccessfulResult, ParseFn, ParserResult, SuccessfulParserResult } from "./types";
-
-/**
- * Combines multiple parsers in sequence, returning an array of their results.
- * If one of the parsers fails, the entire sequence fails.
- */
-export function and(...parsers: ParseFn<any>[]): ParseFn<any[]> {
-  return (tokenStream: TokenStream) => {
-    const results: any[] = [];
-
-    for (const parser of parsers) {
-      const parseResult = parser(tokenStream);
-
-      if (isFailedResult(parseResult)) {
-        return parseResult;
-      }
-
-      results.push(parseResult.result);
-    }
-
-    return { result: results };
-  };
-}
-
-/**
- * Attempts to run a parser, restoring the token position (backtracking) if it fails.
- */
-export function attempt<T>(parser: ParseFn<T>): ParseFn<T> {
-  return (tokenStream: TokenStream) => {
-    tokenStream.storePosition();
-
-    const result = parser(tokenStream);
-
-    if (isSuccessfulResult(result)) {
-      tokenStream.clearPosition();
-    } else {
-      tokenStream.restorePosition();
-    }
-
-    return result;
-  };
-}
-
-/**
- * Makes a given parser optional, returns `null` if it fails.
- */
-export function optional<T>(parser: ParseFn<T>, shouldBacktrack: boolean = true): ParseFn<T | null> {
-  return (tokenStream: TokenStream) => {
-    const parseFn = shouldBacktrack ? attempt(parser) : parser;
-    const result = parseFn(tokenStream);
-
-    if (isSuccessfulResult(result)) {
-      return result;
-    }
-
-    return { result: null };
-  };
-}
-
-/**
- * Tries multiple parsers in order, returning the result of the first successful parse.
- * If all parsers fail, returns the error from the parser that got the furthest.
- */
-export function or<T>(...parsers: ParseFn<T>[]): ParseFn<T> {
-  return (tokenStream: TokenStream) => {
-    let deepestError = null;
-    let deepestErrorPosition = -1;
-
-    for (const parser of parsers) {
-      const tryParse = attempt(parser);
-      const result = tryParse(tokenStream);
-
-      if (isSuccessfulResult(result)) {
-        return result as SuccessfulParserResult<T>;
-      }
-
-      if (isFailedResult(result)) {
-        const { position } = result;
-
-        if (position.position > deepestErrorPosition) {
-          deepestError = result;
-          deepestErrorPosition = position.position;
-        }
-      }
-    }
-
-    return deepestError as FailedParserResult;
-  };
-}
-
-/**
- * Applies a parser repeatedly until it fails or doesn't make progress (move the position), collecting
- * all successful results into an array. If the parser fails on the first attempt, returns a failure.
- */
-export function many(parser: ParseFn<any>): ParseFn<any> {
-  return (tokenStream: TokenStream) => {
-    const results: any[] = [];
-
-    let parseFailure = null;
-
-    while (true) {
-      const positionBefore = tokenStream.position;
-      tokenStream.storePosition();
-
-      const result = parser(tokenStream);
-
-      if (isSuccessfulResult(result)) {
-        const positionAfter = tokenStream.position;
-
-        // Check if the parser made any progress - if it didn't, we break out to avoid infinite loops.
-        if (positionAfter === positionBefore) {
-          tokenStream.restorePosition();
-          break;
-        }
-
-        results.push(result.result);
-        tokenStream.clearPosition();
-      } else {
-        parseFailure = result;
-        tokenStream.restorePosition();
-        break;
-      }
-    }
-
-    if (parseFailure && results.length === 0) {
-      return parseFailure;
-    }
-
-    return { result: results };
-  };
-}
-
-/**
- * Labels a parser with a custom error message for better context if it fails.
- */
-export function label<T>(label: string, parser: ParseFn<T>): ParseFn<T> {
-  return (tokenStream: TokenStream) => {
-    const result = parser(tokenStream);
-
-    if (isSuccessfulResult(result)) {
-      return result;
-    }
-
-    const errorMessage = `${label}: ${result.errorMessage}`;
-
-    return {
-      errorMessage,
-      position: result.position,
-    };
-  }
-}
+import { ParseFn } from "./types";
 
 /**
  * In-built utility parser that parses any token except those of the specified type(s).
+ * @param types The token types to exclude.
  */
 export function anyExcept(...types: TokenType[]): ParseFn<Token> {
   return (tokenStream: TokenStream) => {
@@ -173,6 +23,7 @@ export function anyExcept(...types: TokenType[]): ParseFn<Token> {
 
 /**
  * In-built utility parser that parses any token of the specified type(s).
+ * @param types The token types to match.
  */
 export function anyOf(...types: TokenType[]): ParseFn<Token> {
   return (tokenStream: TokenStream) => {
@@ -191,6 +42,7 @@ export function anyOf(...types: TokenType[]): ParseFn<Token> {
 
 /**
  * In-built utility parser that ensures the end of input has been reached.
+ * Returns a failed result if there are remaining tokens.
  */
 export function endOfInput(): ParseFn {
   return (tokenStream: TokenStream) => {
@@ -205,44 +57,4 @@ export function endOfInput(): ParseFn {
 
     return { result: null };
   };
-}
-
-/**
- * Transforms the result of a parser using a given mapping function.
- * @param parser The parser whose result is to be transformed.
- * @param mapFn A function that takes the parser's result and returns a new value.
- * @returns A new parser that applies the mapping function to the result of the original parser.
- */
-export function map<T, U>(parser: ParseFn<T>, mapFn: (value: T) => U): ParseFn<U> {
-  return (tokenStream: TokenStream) => {
-    const result = parser(tokenStream);
-
-    if (isSuccessfulResult(result)) {
-      return { result: mapFn(result.result) };
-    }
-
-    return result;
-  };
-}
-
-/**
- * Runs a parser on a given TokenStream, throwing an error if parsing fails.
- */
-export function runParser<T>(parser: ParseFn<T>, tokenStream: TokenStream): ParserResult<T> {
-  const test = parser(tokenStream);
-  if (isFailedResult(test)) {
-    throw new ParsingError(test.errorMessage, test.position);
-  }
-
-  return test;
-}
-
-/**
- * Runs a parser on a given input string, using the provided tokenizer to generate tokens.
- */
-export function runParserOnString<T>(parser: ParseFn<T>, input: string, tokenizer: Tokenizer): ParserResult<T> {
-  const tokens = tokenizer.tokenize(input);
-  const stream = new TokenStream(tokens);
-
-  return runParser<T>(parser, stream);
 }

package/src/parsers/runners.ts

@@ -0,0 +1,34 @@
+import { Tokenizer, TokenStream } from "../tokenizer";
+import { ParserError } from "./ParserError";
+import { isFailedResult, ParseFn, ParserResult } from "./types";
+
+/**
+ * Runs a parser on a given TokenStream, throwing an error if parsing fails.
+ * @param parser The parse function to be run.
+ * @param tokenStream The TokenStream to parse.
+ * @returns The successful ParserResult.
+ * @throws {ParserError} If the parser fails. Includes error and position information.
+ */
+export function runParser<T>(parser: ParseFn<T>, tokenStream: TokenStream): ParserResult<T> {
+  const test = parser(tokenStream);
+  if (isFailedResult(test)) {
+    throw new ParserError(test.errorMessage, test.position);
+  }
+
+  return test;
+}
+
+/**
+ * Runs a parser on a given input string, using the provided tokenizer to generate tokens.
+ * @param parser The parse function to be run.
+ * @param input The input string to parse.
+ * @param tokenizer The tokenizer to use for tokenizing the input string.
+ * @returns The ParserResult of the parsing operation.
+ * @throws {ParserError} If the parser fails. Includes error and position information.
+ */
+export function runParserOnString<T>(parser: ParseFn<T>, input: string, tokenizer: Tokenizer): ParserResult<T> {
+  const tokens = tokenizer.tokenize(input);
+  const stream = new TokenStream(tokens);
+
+  return runParser<T>(parser, stream);
+}

package/src/parsers/types.ts

@@ -1,10 +1,5 @@
 import { TokenStream } from "../tokenizer";
-
-export type ParsingErrorPosition = {
-  line: number;
-  column: number;
-  position: number;
-}
+import { ParserErrorPosition } from "./ParserError";
 
 export type SuccessfulParserResult<T> = {
   result: T;
@@ -12,7 +7,7 @@ export type SuccessfulParserResult<T> = {
 
 export type FailedParserResult = {
   errorMessage: string;
-  position: ParsingErrorPosition;
+  position: ParserErrorPosition;
 }
 
 export type ParserResult<T> = SuccessfulParserResult<T> | FailedParserResult;

package/src/parsers/ParsingError.ts

@@ -1,14 +0,0 @@
-import { ParsingErrorPosition } from "./types";
-
-/**
- * Represents a parsing error with a specific message.
- */
-export class ParsingError extends Error {
-  public location: ParsingErrorPosition;
-
-  constructor(message: string, location: ParsingErrorPosition) {
-    super(`Parsing Error [${location.line}:${location.column}]: ${message}`);
-
-    this.location = location;
-  }
-}

package/src/utils.ts

@@ -1,17 +0,0 @@
-/**
- * A method which unwraps a given generic array, taking each element and accumulating them, if the given item is a nested array, it is flattened into the result.
- * Useful for flattening parser results built with the `and` and `many` combinators, which can produce nested arrays.
- * @param items - An array of items or nested arrays of items to be unwrapped.
- * @returns A flattened array containing all individual items.
- */
-export const unwrapResult = <T>(items: (T | T[])[]): T[] => {
-  const result: T[] = [];
-  for (const item of items) {
-    if (Array.isArray(item)) {
-      result.push(...unwrapResult(item));
-    } else {
-      result.push(item);
-    }
-  }
-  return result;
-};