@spakhm/ts-parsec 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Slava Akhmechet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+
+This is a parser combinator library written in typescript. Design
+goals:
+
+- Produces recursive descent parsers capable of parsing PEG grammars.
+- For throwaway projects only. Will never grow big, have complex
+  optimizations, or other fancy featues.
+- Small, so I can understand every detail. The library is under 500
+  lines of code and took maybe a couple of days to write.
+- Type safe. The syntax tree types are inferred from the combinators.
+  It's beautiful and really fun to use.
+
+## Installation
+```sh
+npm install @spakhm/ts-parsec
+```
+
+## Example
+
+Here is a simple example:
+
+```ts
+const digit = range('0', '9');
+const lower = range('a', 'z');
+const upper = range('A', 'Z');
+const alpha = either(lower, upper);
+const alnum = either(alpha, digit);
+
+const ident = lex(seq(alpha, many(alnum))).map(([first, rest]) =>
+  [first, ...rest].join(""));
+
+const input = "Hello";
+const stream = fromString(input);
+ident(stream);
+```
+
+## Limitations
+
+- No error reporting at all.

package/dist/index.js

@@ -0,0 +1,8 @@
+
+'use strict'
+
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('./ts-parsec.cjs.production.min.js')
+} else {
+  module.exports = require('./ts-parsec.cjs.development.js')
+}

package/package.json

@@ -0,0 +1 @@
+{"version":"0.1.2","license":"MIT","main":"dist/index.js","typings":"dist/index.d.ts","files":["dist","src"],"engines":{"node":">=10"},"scripts":{"start":"tsdx watch","build":"tsdx build","test":"tsdx test","lint":"tsdx lint","prepare":"tsdx build","size":"size-limit","analyze":"size-limit --why"},"husky":{"hooks":{"pre-commit":"tsdx lint"}},"prettier":{"printWidth":80,"semi":true,"singleQuote":true,"trailingComma":"es5"},"name":"@spakhm/ts-parsec","author":"Slava Akhmechet","module":"dist/ts-parsec.esm.js","size-limit":[{"path":"dist/ts-parsec.cjs.production.min.js","limit":"10 KB"},{"path":"dist/ts-parsec.esm.js","limit":"10 KB"}],"devDependencies":{"@size-limit/preset-small-lib":"^11.1.6","husky":"^9.1.6","size-limit":"^11.1.6","tsdx":"^0.14.1","tslib":"^2.7.0","typescript":"^3.9.10"}}

package/src/base.ts

@@ -0,0 +1,105 @@
+import type { stream } from './stream';
+
+/*
+  Result handling
+*/
+export type result<T, E> = { type: 'ok', res: T, } | { type: 'err', err: E, };
+export type parser_error = { row: number, col: number, msg: string, };
+
+export const ok = <T>(res: T): result<T, never> => ({ type: 'ok', res, });
+export const err = (row: number, col: number, msg: string): result<never, parser_error> =>
+  ({ type: 'err', err: { row, col, msg, }});
+
+/*
+  Parser types
+*/
+export type parserFn<T> = (source: stream) => result<T, parser_error>;
+export type parser<T> = parserFn<T> & {
+  map: <U>(fn: ((value: T) => U)) => parser<U>,
+};
+export type parserlike<T> = parserFn<T> | parser<T> | string;
+
+/*
+  Allowing functions and strings to act like parsers
+*/
+export function toParser<T extends string>(p: T): parser<T>;
+export function toParser<T>(p: parserlike<T>): parser<T>;
+export function toParser <T>(pl: parserlike<T>) {
+  if (typeof pl == 'string') {
+    return str(pl);
+  }
+
+  if ('map' in pl) {
+    return pl;
+  }
+
+  const fn_: parser<T> = pl as parser<T>;
+
+  fn_.map = <U>(fnTransform: (value: T) => U): parser<U> => {
+    return toParser((source: stream): result<U, parser_error> => {
+      const res = fn_(source);
+      if (res.type == 'ok') {
+        return ok(fnTransform(res.res));
+      } else {
+        return res;
+      }
+    });
+  };
+
+  return fn_;
+}
+
+/*
+  The most basic of parsers
+*/
+export const str = <T extends string>(match: T): parser<T> =>
+  lex(toParser((source: stream) => {
+    for (let i = 0; i < match.length; i++) {
+      if(source.next() != match[i]) {
+        return err(0, 0, '');
+      }
+    }
+    return ok(match);
+  }));
+
+export const lex = <T>(p: parserlike<T>) => keepWs((source: stream) => {
+  ws(source);
+  return toParser(p)(source);
+});
+
+export const keepWs = <T>(p: parserlike<T>) =>
+  toParser((source: stream) => {
+    const prev_drop_ws = source.drop_ws;
+    source.drop_ws = false;
+    const res = toParser(p)(source);
+    source.drop_ws = prev_drop_ws;
+    return res;
+  });
+
+export const ws = toParser((source: stream) => {
+  while (true) {
+    source.push();
+    const ch = source.next();
+    if (ch?.trim() === "") {
+      source.pop_continue();
+    } else {
+      source.pop_rollback();
+      break;
+    }
+  }
+  return ok({});
+});
+
+/*
+  Laziness helper
+*/
+export const fwd = <T>(thunk: (() => parserlike<T>)): parser<T> =>
+  toParser((source: stream) => toParser(thunk())(source));
+
+/*
+  TODO:
+  - In `either('foo').map(...)` the string 'foo' gets mapped to unknown.
+    Should fix that.
+  - If I could push infinite regress through map, it would be trivial to
+    just specify the AST type in map, and avoid the trick in `form`.
+*/

package/src/lib.ts

@@ -0,0 +1,162 @@
+import type { stream } from './stream';
+import type { parser, parserlike } from './base';
+import { err, ok, toParser, lex } from './base';
+
+export const attempt = <T>(parser: parserlike<T>): parser<T> =>
+  toParser((source: stream) => {
+    source.push();
+    const res = toParser(parser)(source);
+    if (res.type == 'ok') {
+      source.pop_continue();
+    } else {
+      source.pop_rollback();
+    }
+    return res;
+  });
+
+export const range = (start: string, end: string): parser<string> =>
+  toParser((source: stream) => {
+    const next = source.next();
+    if (!next) return err(0, 0, '');
+    if (next >= start[0] && next <= end[0]) return ok(next);
+    return err(0, 0, '');
+  });
+    
+export const either = <Ts extends any[]>(...parsers: { [K in keyof Ts]: parserlike<Ts[K]> }): parser<Ts[number]> =>
+  toParser((source: stream) => {
+    for (const parser of parsers) {
+      const res = attempt(parser)(source);
+      if (res.type == 'ok') {
+        return res;
+      }
+    }
+    return err(0, 0, '');
+  });
+
+export type seq_parser<T extends any[]> = parser<T> & {
+  map2: <U>(fn: ((...values: T) => U)) => parser<U>,
+};
+
+export const seq = <Ts extends any[]>(...parsers: { [K in keyof Ts]: parserlike<Ts[K]> }): seq_parser<Ts> => {
+  const p = toParser((source: stream) => {
+    const res: unknown[] = [];
+    for (const parser of parsers) {
+      const res_ = toParser(parser)(source);
+      if (res_.type == 'ok') {
+        res.push(res_.res);
+      } else {
+        return err(0, 0, '');
+      }
+    }
+    return ok(res as any);
+  }) as seq_parser<Ts>;
+  p.map2 = <U>(fn: ((...values: Ts) => U)) =>
+    p.map(x => fn(...x));
+  return p;
+}
+
+export const many = <T>(parser: parserlike<T>): parser<T[]> =>
+  toParser((source: stream) => {
+    const res: T[] = [];
+    while (true) {
+      const _res = attempt(parser)(source);
+      if (_res.type == 'ok') {
+        res.push(_res.res);
+      } else {
+        break;
+      }
+    }
+
+    return ok(res);
+  });
+
+export const some = <T>(parser: parserlike<T>): parser<T[]> =>
+  seq(parser, many(parser)).map2((ft, rt) => [ft, ...rt]);
+
+export const digit = range('0', '9');
+
+export const nat = lex(some(digit)).map((val) =>
+  parseInt(val.join("")));
+
+export const maybe = <T>(p: parserlike<T>) =>
+  toParser((source: stream) => {
+    const res = attempt(p)(source);
+    return res.type == 'ok' ? res : ok(null);
+  });
+
+export const int = seq(maybe(either('-', '+')), nat).map2((sign, val) => {
+  if (sign === '-') {
+    return -val;
+  } else {
+    return val;
+  }
+});
+
+export const lower = range('a', 'z');
+export const upper = range('A', 'Z');
+export const alpha = either(lower, upper);
+export const alnum = either(alpha, digit);
+
+export const sepBy = <T, U>(item: parserlike<T>, sep: parserlike<U>, allowTrailingSep: boolean = true): parser<T[]> =>
+  toParser((source: stream) => {
+    const res: T[] = [];
+
+    const res_ = attempt(item)(source);
+    if (res_.type == 'err') {
+      return ok(res);
+    } else {
+      res.push(res_.res);
+    }
+
+    while (true) {
+      const sepres_ = attempt(sep)(source);
+      if (sepres_.type == 'err') {
+        return ok(res);
+      }
+  
+      const res_ = attempt(item)(source);
+      if (res_.type == 'err') {
+        return allowTrailingSep ? ok(res) : err(0, 0, '');
+      } else {
+        res.push(res_.res);
+      }
+    }
+  });
+
+export function binop<O, D, N>(
+  operator: parserlike<O>,
+  operand: parserlike<D>,
+  makeNode: (op: O, left: D | N, right: D) => N
+): parser<N | D> {
+  return toParser((source: stream) => {
+    const p = seq(operand, many(seq(operator, operand))).map2<N | D>((left, rights) => {
+      const acc = rights.reduce<N | D>(
+        (acc, [op, right]) => makeNode(op, acc, right), left);
+      return acc;
+    });
+    return p(source);
+  });
+}
+
+export function binopr<O, D, N>(
+  operator: parserlike<O>,
+  operand: parserlike<D>,
+  makeNode: (op: O, left: D, right: D | N) => N
+): parser<N | D> {
+  return toParser((source: stream) => {
+    const p = seq(operand, many(seq(operator, operand))).map2<N | D>((left, rights) => {
+      if (rights.length === 0) return left;
+
+      // Start from the last operand and reduce from right to left
+      let acc: D | N = rights[rights.length - 1][1];
+      for (let i = rights.length - 2; i >= 0; i--) {
+        const [op, right] = rights[i];
+        acc = makeNode(op, right, acc);
+      }
+
+      return makeNode(rights[0][0], left, acc);
+    });
+
+    return p(source);
+  });
+}

package/src/stream.ts

@@ -0,0 +1,63 @@
+
+export type stream = {
+  row: number,
+  col: number,
+  drop_ws: boolean,
+  next: () => string | null,
+  push: () => void,
+  pop_continue: () => void,
+  pop_rollback: () => void,
+};
+
+class string_stream {
+  row: number = 1;
+  col: number = 1;
+  idx: number = 0;
+
+  stack: {
+    row: number,
+    col: number,
+    idx: number,
+  }[] = [];
+
+  constructor(public source: string, public drop_ws: boolean = true) {}
+
+  next(): string | null {
+    if (this.idx == this.source.length) {
+      return null;
+    }
+    const ch = this.source[this.idx++];
+    this.col++;
+    if (ch == '\n') {
+      this.row++;
+      this.col = 1;
+    }
+
+    if (this.drop_ws && ch.trim() === "") {
+      return this.next();
+    } else {
+      return ch;
+    }
+  }
+
+  push() {
+    this.stack.push({
+      row: this.row, col: this.col, idx: this.idx,
+    })
+  }
+
+  pop_continue() {
+    this.stack.pop();
+  }
+
+  pop_rollback() {
+    const x = this.stack.pop()!;
+    this.row = x.row;
+    this.col = x.col;
+    this.idx = x.idx;
+  }
+}
+
+export const fromString = (source: string): stream => {
+  return new string_stream(source);
+}