tarsec 0.0.1

package/lib/parsers.test.ts

@@ -0,0 +1,300 @@
+import { describe, expect, it, test } from "vitest";
+import {
+  alphanum,
+  digit,
+  letter,
+  noneOf,
+  num,
+  oneOf,
+  space,
+  spaces,
+  str,
+  word,
+  char,
+} from "./parsers";
+import { success, failure } from "../vitest.globals.js";
+import {
+  capture,
+  many,
+  many1,
+  many1WithJoin,
+  not,
+  optional,
+  or,
+  seq,
+} from "./combinators";
+test.skip("hello", () => {
+  describe("Parser Tests", () => {
+    describe("optional parser", () => {
+      const parser = optional(char("a"));
+
+      it("should parse the character if it exists", () => {
+        const result = parser("a");
+        expect(result).toEqual(success({ rest: "", match: "a" }));
+      });
+
+      it("should return an empty string if the character is missing", () => {
+        const result = parser("b");
+        expect(result).toEqual(success({ rest: "b", match: "" }));
+      });
+
+      it("should not consume any input if it fails", () => {
+        // @ts-ignore
+        const parser2 = optional(seq(many1WithJoin(letter), char("!")));
+        const result1 = parser2("hello!");
+        expect(result1).toEqual(
+          success({ rest: "", match: "hello!", captures: {} })
+        );
+
+        const result2 = parser2("hello");
+        expect(result2).toEqual(success({ rest: "hello", match: "" }));
+      });
+    });
+
+    describe("not parser", () => {
+      const parser = not(char("a"));
+
+      it("should fail if the character is present", () => {
+        const result = parser("a");
+        expect(result).toEqual(
+          failure({ rest: "a", message: "unexpected match" })
+        );
+      });
+
+      it("should return an empty string if the character is missing", () => {
+        const result = parser("b");
+        expect(result).toEqual(success({ rest: "b", match: "" }));
+      });
+    });
+
+    describe("space parser", () => {
+      it("should parse a space character", () => {
+        const result = space(" ");
+        expect(result).toEqual(success({ rest: "", match: " " }));
+      });
+
+      it("should fail if the character is not a space", () => {
+        const result = space("a");
+        expect(result).toEqual(
+          failure({ rest: "a", message: "expected  , got a" })
+        );
+      });
+    });
+
+    describe("spaces parser", () => {
+      it("should parse multiple space characters", () => {
+        const result = spaces("  ");
+        expect(result).toEqual(success({ rest: "", match: "  " }));
+      });
+
+      it("should fail if no space characters found", () => {
+        const result = spaces("abc");
+        expect(result).toEqual(
+          failure({ rest: "abc", message: "expected at least one match" })
+        );
+      });
+    });
+
+    describe("digit parser", () => {
+      it("should parse a single digit", () => {
+        const result = digit("1");
+        expect(result).toEqual(success({ rest: "", match: "1" }));
+      });
+
+      it("should fail if the character is not a digit", () => {
+        const result = digit("a");
+        expect(result).toEqual(
+          failure({ rest: "a", message: "expected one of 0123456789" })
+        );
+      });
+    });
+
+    describe("letter parser", () => {
+      it("should parse a single letter", () => {
+        const result = letter("a");
+        expect(result).toEqual(success({ rest: "", match: "a" }));
+      });
+
+      it("should fail if the character is not a letter", () => {
+        const result = letter("1");
+        expect(result).toEqual(
+          failure({
+            rest: "1",
+            message: "expected one of abcdefghijklmnopqrstuvwxyz",
+          })
+        );
+      });
+    });
+
+    describe("alphanum parser", () => {
+      it("should parse a single alphanumeric character", () => {
+        const result = alphanum("1");
+        expect(result).toEqual(success({ rest: "", match: "1" }));
+      });
+
+      it("should fail if the character is not alphanumeric", () => {
+        const result = alphanum("_");
+        expect(result).toEqual(
+          failure({
+            rest: "_",
+            message: "expected one of abcdefghijklmnopqrstuvwxyz0123456789",
+          })
+        );
+      });
+    });
+
+    describe("word parser", () => {
+      const parser = word;
+
+      it("should parse a single word", () => {
+        const result = parser("hello");
+        expect(result).toEqual(success({ rest: "", match: "hello" }));
+      });
+
+      it("should fail if no word characters found", () => {
+        const result = parser("123");
+        expect(result).toEqual(
+          failure({ rest: "123", message: "expected at least one match" })
+        );
+      });
+    });
+
+    describe("number parser", () => {
+      const parser = num;
+
+      it("should parse a single number", () => {
+        const result = parser("123");
+        expect(result).toEqual(success({ rest: "", match: "123" }));
+      });
+
+      it("should fail if no number characters found", () => {
+        const result = parser("abc");
+        expect(result).toEqual(
+          failure({ rest: "abc", message: "expected at least one match" })
+        );
+      });
+    });
+  });
+
+  describe("seq parser", () => {
+    const parser = seq([char("a"), char("b")]);
+
+    it("should parse both characters in sequence", () => {
+      const result = parser("ab");
+      expect(result).toEqual(success({ rest: "", match: "ab", captures: {} }));
+    });
+
+    it("should fail if any of the parsers fail", () => {
+      const result = parser("ac");
+      expect(result).toEqual(
+        failure({ rest: "c", message: "expected b, got c" })
+      );
+    });
+  });
+
+  describe("seq parser - hello world", () => {
+    it("multiple char parsers", () => {
+      const parser = seq([
+        char("h"),
+        char("e"),
+        char("l"),
+        char("l"),
+        char("o"),
+      ]);
+      const result = parser("hello world");
+      expect(result).toEqual(
+        success({ match: "hello", rest: " world", captures: {} })
+      );
+    });
+
+    it("multiple str parsers", () => {
+      const parser = seq([str("hello"), space, str("world")]);
+      const result = parser("hello world");
+      expect(result).toEqual(
+        success({ match: "hello world", rest: "", captures: {} })
+      );
+    });
+
+    it("multiple str parsers + capture", () => {
+      const parser = seq([str("hello"), space, capture(str("world"), "name")]);
+      const result = parser("hello world");
+      expect(result).toEqual(
+        success({ match: "hello world", rest: "", captures: { name: "world" } })
+      );
+    });
+  });
+
+  /* test("quote parser - single quote", () => {
+  const input = "'";
+  const result = quote(input);
+  expect(result).toEqual(success({ rest: "", match: "'", captures: {} }));
+});
+
+test("quote parser - double quote", () => {
+  const input = '"';
+  const result = quote(input);
+  expect(result).toEqual(success({ rest: "", match: '"', captures: {} }));
+});
+
+test("quote parser - invalid quote", () => {
+  const input = "`";
+  const result = quote(input);
+  expect(result).toEqual(
+    failure({ rest: "`", message: "unexpected end of input" })
+  );
+});
+
+// Test for anyChar parser
+test("anyChar parser - non-empty input", () => {
+  const input = "abc";
+  const result = anyChar(input);
+  expect(result).toEqual(success({ rest: "bc", match: "a", captures: {} }));
+});
+
+test("anyChar parser - empty input", () => {
+  const input = "";
+  const result = anyChar(input);
+  expect(result).toEqual(
+    failure({ rest: "", message: "unexpected end of input" })
+  );
+});
+
+// Test for between parser
+test("between parser - valid input", () => {
+  const open = quote;
+  const close = quote;
+  const parser = anyChar;
+  const input = "'abc'";
+  const result = between(open, close, parser)(input);
+  expect(result).toEqual(success({ rest: "", match: "a", captures: {} }));
+});
+
+test("between parser - invalid input", () => {
+  const open = quote;
+  const close = quote;
+  const parser = anyChar;
+  const input = "\"abc'";
+  const result = between(open, close, parser)(input);
+  expect(result).toEqual(
+    failure({ rest: "abc'", message: "unexpected end of input" })
+  );
+});
+
+// Test for sepBy parser
+test("sepBy parser - valid input", () => {
+  const separator = anyChar;
+  const parser = anyChar;
+  const input = "a,b,c";
+  const result = sepBy(separator, parser)(input);
+  expect(result).toEqual(success({ rest: "", match: "abc", captures: {} }));
+});
+
+test("sepBy parser - invalid input", () => {
+  const separator = quote;
+  const parser = anyChar;
+  const input = '"a"bc';
+  const result = sepBy(separator, parser)(input);
+  expect(result).toEqual(success({ rest: "bc", match: "a", captures: {} }));
+});
+ */
+});

package/lib/parsers.ts

@@ -0,0 +1,108 @@
+import { many1, many1WithJoin, seq, transform } from "./combinators";
+import { trace } from "./trace";
+import { Parser, ParserResult } from "./types";
+import { escape } from "./utils";
+export function char(c: string): Parser<string> {
+  return trace(`char(${escape(c)})`, (input: string) => {
+    if (input.length === 0) {
+      return {
+        success: false,
+        rest: input,
+        message: "unexpected end of input",
+      };
+    }
+    if (input[0] === c) {
+      return { success: true, match: c, rest: input.slice(1) };
+    }
+    return {
+      success: false,
+      rest: input,
+      message: `expected ${c}, got ${input[0]}`,
+    };
+  });
+}
+
+export function str(s: string): Parser<string> {
+  return trace(`str(${escape(s)})`, (input: string) => {
+    if (input.substring(0, s.length) === s) {
+      return { success: true, match: s, rest: input.slice(s.length) };
+    }
+    return {
+      success: false,
+      rest: input,
+      message: `expected ${s}, got ${input.substring(0, s.length)}`,
+    };
+  });
+}
+
+export function oneOf(chars: string): Parser<string> {
+  return trace(`oneOf(${escape(chars)})`, (input: string) => {
+    if (input.length === 0) {
+      return {
+        success: false,
+        rest: input,
+        message: "unexpected end of input",
+      };
+    }
+    const c = input[0];
+    if (chars.includes(c)) {
+      return char(c)(input);
+    }
+    return {
+      success: false,
+      rest: input,
+      message: `expected one of ${escape(chars)}, got ${c}`,
+    };
+  });
+}
+
+export function noneOf(chars: string): Parser<string> {
+  return trace(`noneOf(${escape(chars)})`, (input: string) => {
+    if (input.length === 0) {
+      return {
+        success: false,
+        rest: input,
+        message: "unexpected end of input",
+      };
+    }
+    if (chars.includes(input[0])) {
+      return {
+        success: false,
+        rest: input,
+        message: `expected none of ${chars}`,
+      };
+    }
+    return char(input[0])(input);
+  });
+}
+
+export function anyChar(input: string): Parser<string> {
+  return trace("anyChar", (input: string) => {
+    if (input.length === 0) {
+      return {
+        success: false,
+        rest: input,
+        message: "unexpected end of input",
+      };
+    }
+    return { success: true, match: input[0], rest: input.slice(1) };
+  });
+}
+
+export const space: Parser<string> = oneOf(" \t\n\r");
+export const spaces: Parser<string> = many1WithJoin(space);
+export const digit: Parser<string> = oneOf("0123456789");
+export const letter: Parser<string> = oneOf("abcdefghijklmnopqrstuvwxyz");
+export const alphanum: Parser<string> = oneOf(
+  "abcdefghijklmnopqrstuvwxyz0123456789"
+);
+export const word: Parser<string> = many1WithJoin(letter);
+export const num: Parser<string> = many1WithJoin(digit);
+export const quote: Parser<string> = oneOf(`'"`);
+export const tab: Parser<string> = char("\t");
+export const newline: Parser<string> = char("\n");
+
+export const quotedString = transform(
+  seq<any, string>([quote, word, quote], "quotedString"),
+  (x) => x.join("")
+);

package/lib/trace.ts

@@ -0,0 +1,40 @@
+import { ParserResult, Parser } from "./types";
+import { escape } from "./utils";
+const STEP = 2;
+
+export function resultToString<T>(
+  name: string,
+  result: ParserResult<T, string>
+): string {
+  if (result.success) {
+    return `✅ ${name} -- match: ${escape(result.match)}, rest: ${escape(
+      result.rest
+    )}`;
+  }
+  return `❌ ${name} -- message: ${escape(result.message)}, rest: ${escape(
+    result.rest
+  )}`;
+}
+
+let level = 0;
+
+export function trace<T>(name: string, parser: Parser<T>): Parser<T> {
+  return (input: string) => {
+    if (process.env.DEBUG) {
+      console.log(" ".repeat(level) + `🔍 ${name} -- input: ${escape(input)}`);
+    }
+    level += STEP;
+    const result = parser(input);
+    level -= STEP;
+    if (process.env.DEBUG) {
+      console.log(" ".repeat(level) + resultToString(name, result));
+      if (result.success && result.captures) {
+        console.log(
+          " ".repeat(level) +
+            `⭐ ${name} -- captures: ${JSON.stringify(result.captures)}`
+        );
+      }
+    }
+    return result;
+  };
+}

package/lib/types.ts

@@ -0,0 +1,24 @@
+export type Object = Record<string, string>;
+export type ParserSuccess<M, C extends string> = {
+  success: true;
+  match: M;
+  captures?: Record<C, any>;
+  rest: string;
+};
+
+export type ParserFailure = {
+  success: false;
+  rest: string;
+  message: string;
+};
+
+export type ParserOptions = {
+  capture: string;
+};
+
+export type ParserResult<M, C extends string> =
+  | ParserSuccess<M, C>
+  | ParserFailure;
+export type Parser<M, C extends string = string> = (
+  input: string
+) => ParserResult<M, C>;

package/lib/utils.ts

@@ -0,0 +1,33 @@
+export function escape(str: any) {
+  return JSON.stringify(str);
+}
+
+export function merge(a: any | any[], b: any | any[]): any[] {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return [...a, ...b];
+  } else if (Array.isArray(a)) {
+    return [...a, b];
+  } else if (Array.isArray(b)) {
+    return [a, ...b];
+  } else {
+    return [a, b];
+  }
+}
+
+export function mergeCaptures(
+  a: Record<string, any>,
+  b: Record<string, any>
+): Record<string, any> {
+  const result: Record<string, any> = {};
+  Object.keys(a).forEach((key) => {
+    result[key] = a[key];
+  });
+  Object.keys(b).forEach((key) => {
+    if (result[key]) {
+      result[key] = merge(result[key], b[key]);
+    } else {
+      result[key] = b[key];
+    }
+  });
+  return result;
+}

package/makefile

@@ -0,0 +1,5 @@
+all:
+	npm run build && npm run start
+
+test:
+	npm run test

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "tarsec",
+  "version": "0.0.1",
+  "description": "A parser combinator library for TypeScript, inspired by Parsec.",
+  "scripts": {
+    "test": "vitest",
+    "build": "tsc",
+    "start": "cd dist && node index.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^20.11.28",
+    "vitest": "^1.4.0"
+  }
+}

package/tests/combinators/many.test.ts

@@ -0,0 +1,18 @@
+import { many } from "@/lib/combinators";
+import { digit } from "@/lib/parsers";
+import { describe, it, expect } from "vitest";
+import { success } from "vitest.globals";
+
+describe("many combinator", () => {
+  const parser = many(digit);
+
+  it("should parse multiple digits", () => {
+    const result = parser("1234");
+    expect(result).toEqual(success({ rest: "", match: ["1", "2", "3", "4"] }));
+  });
+
+  it("should return an empty string if no matches found", () => {
+    const result = parser("abc");
+    expect(result).toEqual(success({ rest: "abc", match: [] }));
+  });
+});

package/tests/combinators/many1.test.ts

@@ -0,0 +1,20 @@
+import { many1 } from "@/lib/combinators";
+import { digit } from "@/lib/parsers";
+import { describe, it, expect } from "vitest";
+import { success, failure } from "vitest.globals";
+
+describe("many1 combinator", () => {
+  const parser = many1(digit);
+
+  it("should parse multiple digits", () => {
+    const result = parser("1234");
+    expect(result).toEqual(success({ rest: "", match: ["1", "2", "3", "4"] }));
+  });
+
+  it("should fail if no matches found", () => {
+    const result = parser("abc");
+    expect(result).toEqual(
+      failure({ rest: "abc", message: "expected at least one match" })
+    );
+  });
+});

package/tests/combinators/or.test.ts

@@ -0,0 +1,25 @@
+import { or } from "@/lib/combinators";
+import { char } from "@/lib/parsers";
+import { describe, it, expect } from "vitest";
+import { success, failure } from "vitest.globals";
+
+describe("or parser", () => {
+  const parser = or<string>([char("a"), char("b")]);
+
+  it("should parse the first parser if it succeeds", () => {
+    const result = parser("a");
+    expect(result).toEqual(success({ rest: "", match: "a" }));
+  });
+
+  it("should parse the second parser if the first one fails", () => {
+    const result = parser("b");
+    expect(result).toEqual(success({ rest: "", match: "b" }));
+  });
+
+  it("should fail if all parsers fail", () => {
+    const result = parser("c");
+    expect(result).toEqual(
+      failure({ rest: "c", message: "all parsers failed" })
+    );
+  });
+});

package/tests/combinators/seq.test.ts

@@ -0,0 +1,38 @@
+import { seq, capture } from "@/lib/combinators";
+import { char, str, space } from "@/lib/parsers";
+import { describe, it, expect } from "vitest";
+import { success } from "vitest.globals";
+
+describe("seq parser - hello world", () => {
+  it("multiple char parsers", () => {
+    const parser = seq([char("h"), char("e"), char("l"), char("l"), char("o")]);
+    const result = parser("hello world");
+    expect(result).toEqual(
+      success({
+        match: ["h", "e", "l", "l", "o"],
+        rest: " world",
+        captures: {},
+      })
+    );
+  });
+
+  it("multiple str parsers", () => {
+    const parser = seq([str("hello"), space, str("world")]);
+    const result = parser("hello world");
+    expect(result).toEqual(
+      success({ match: ["hello", " ", "world"], rest: "", captures: {} })
+    );
+  });
+
+  it("multiple str parsers + capture", () => {
+    const parser = seq([str("hello"), space, capture(str("world"), "name")]);
+    const result = parser("hello world");
+    expect(result).toEqual(
+      success({
+        match: ["hello", " ", "world"],
+        rest: "",
+        captures: { name: "world" },
+      })
+    );
+  });
+});

package/tests/integration/hello_capture.test.ts

@@ -0,0 +1,21 @@
+import { seq, capture, many1, many1WithJoin } from "@/lib/combinators";
+import { char, str, space, noneOf } from "@/lib/parsers";
+import { ParserSuccess } from "@/lib/types";
+import { describe, it, expect } from "vitest";
+import { success } from "vitest.globals";
+
+describe("hello world", () => {
+  it("parses + captures name", () => {
+    const parser = seq([
+      str("hello"),
+      space,
+      capture(many1WithJoin(noneOf("!")), "name"),
+      char("!"),
+    ]);
+    const result = parser("hello adit!");
+    expect(result.success).toEqual(true);
+    expect((result as ParserSuccess<string[], string>).captures).toEqual({
+      name: "adit",
+    });
+  });
+});

package/tests/integration/hello_world.test.ts

@@ -0,0 +1,14 @@
+import { seq, capture } from "@/lib/combinators";
+import { char, str, space } from "@/lib/parsers";
+import { describe, it, expect } from "vitest";
+import { success } from "vitest.globals";
+
+describe("hello world", () => {
+  it("parses", () => {
+    const parser = seq([str("hello"), space, str("world")]);
+    const result = parser("hello world");
+    expect(result).toEqual(
+      success({ match: ["hello", " ", "world"], rest: "", captures: {} })
+    );
+  });
+});