tarsec 0.0.15 → 0.0.16

package/dist/combinators.d.ts

@@ -1,4 +1,4 @@
-import { CaptureParser, GeneralParser, InferManyReturnType, MergedCaptures, MergedResults, Parser, PickParserType, PlainObject } from "./types.js";
+import { CaptureParser, GeneralParser, InferManyReturnType, MergedCaptures, MergedResults, Parser, ParserResult, PickParserType, PickParserTypeArray, PlainObject } from "./types.js";
 /**
  * Takes a parser and runs it zero or more times, returning the results as an array.
  * If the parser is a capture parser, it returns the captures as an array in this form:
@@ -260,3 +260,19 @@ export declare function seqC<const T extends readonly GeneralParser<any, any>[]>
  * @returns - true if the parser matches the input and consumes all input, false otherwise
  */
 export declare function match(input: string, parser: GeneralParser<any, any>): boolean;
+export declare function ifElse<const IF extends GeneralParser<any, any, I>, const ELSE extends GeneralParser<any, any, I>, I = string>(condition: boolean, ifParser: IF, elseParser: ELSE): IF | ELSE;
+/**
+ * Apply multiple parsers to the same input and collect all the results.
+ * Consumes no input.
+ *
+ * @param parsers - parsers to try
+ * @returns
+ */
+export declare function manyParsers<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): Parser<ParserResult<MergedResults<T>>[]>;
+/**
+ * Runs all the given parsers. If they all succeed, returns their results as an array.
+ * Otherwise fails. Consumes no input.
+ * @param parsers - parsers to try
+ * @returns - An array of results, or a failure.
+ */
+export declare function and<const I, const T extends readonly GeneralParser<any, any>[]>(...parsers: T): PickParserTypeArray<T, I>;

package/dist/combinators.js

@@ -1,6 +1,6 @@
 import { within } from "./parsers/within.js";
 import { trace } from "./trace.js";
-import { captureSuccess, createTree, failure, isCaptureResult, success, } from "./types.js";
+import { captureSuccess, createTree, failure, isCaptureResult, isSuccess, success, } from "./types.js";
 import { escape, findAncestorWithNextParser, popMany } from "./utils.js";
 /**
  * Takes a parser and runs it zero or more times, returning the results as an array.
@@ -615,3 +615,50 @@ export function match(input, parser) {
     const result = parser(input);
     return result.success && result.rest === "";
 }
+export function ifElse(condition, ifParser, elseParser) {
+    return trace(`ifElse(${escape(condition)})`, (input) => {
+        if (condition) {
+            return ifParser(input);
+        }
+        return elseParser(input);
+    });
+}
+/**
+ * Apply multiple parsers to the same input and collect all the results.
+ * Consumes no input.
+ *
+ * @param parsers - parsers to try
+ * @returns
+ */
+export function manyParsers(...parsers) {
+    return trace(`manyParsers()`, (input) => {
+        const results = [];
+        for (let i = 0; i < parsers.length; i++) {
+            let result = parsers[i](input);
+            results.push(result);
+        }
+        if (results.some(isSuccess)) {
+            return success(results, input);
+        }
+        return failure("no parsers succeeded", input);
+    });
+}
+/**
+ * Runs all the given parsers. If they all succeed, returns their results as an array.
+ * Otherwise fails. Consumes no input.
+ * @param parsers - parsers to try
+ * @returns - An array of results, or a failure.
+ */
+export function and(...parsers) {
+    return trace(`and()`, (input) => {
+        const results = manyParsers(...parsers)(input);
+        if (results.success) {
+            const successes = results.result.filter(isSuccess);
+            if (successes.length === results.result.length) {
+                return success(results.result.map((r) => r.result), input);
+            }
+            return failure("not all parsers succeeded", input);
+        }
+        return results;
+    });
+}

package/dist/parsers.d.ts

@@ -143,3 +143,70 @@ export declare function captureRegex<const T extends string[]>(str: string | Reg
  * @returns
  */
 export declare function set<const K extends string, const V>(key: K, value: V): CaptureParser<null, Record<K, V>>;
+/**
+ * A parser that always succeeds with the given value.
+ * @param value - value to succeed with
+ * @returns value
+ */
+export declare function succeed<T, I = string>(value: T): Parser<T>;
+/**
+ * A parser that always fails with the given message.
+ * @param message - message to fail with
+ * @returns failure
+ */
+export declare function fail<I = string>(message: string): Parser<never>;
+/**
+ * Takes a string. Succeeds if the given input contains that string.
+ * Consumes no input.
+ *
+ * @param substr - substring to find
+ * @returns - parser that succeeds if the given input contains that string
+ */
+export declare function includes<const S extends string>(substr: S): Parser<S>;
+/**
+ * Like `includes`, but case-insensitive.
+ *
+ * @param substr - substring to find
+ * @returns - parser that succeeds if the given input contains that string
+ */
+export declare function iIncludes<const S extends string>(substr: S): Parser<S>;
+/**
+ * Returns a parser that takes some input, runs the transformer function over it,
+ * and returns the result as `rest`, so it can be chained to another parser.
+ * It always returns null as its result. Always succeeds.
+ *
+ * `shape` is useful for modifying the user's input before running parsers over it.
+ * For example, here is a parser that takes in a chapter
+ * and checks that its title starts with "Once upon a time"
+ *
+ * ```ts
+ * const parser = seqR(
+ * shape((c: Chapter) => c.title),
+ *   istr("Once upon a time"),
+ *   )
+ * );
+ * ```
+ *
+ * Now you might be thinking, why not just use the chapter's title as input?
+ * `shape` is most useful when you want to parse multiple properties.
+ *
+ * ```ts
+ * const titleParser = seqR(
+ *   shape((c: Chapter) => c.title),
+ *   istr("Once upon a time"),
+ * );
+ *
+ * const textParser = seqR(
+ *   shape((c: Chapter) => c.text),
+ *   istr("There was a princess"),
+ * );
+ *
+ * const parser = and(titleParser, textParser);
+ * ```
+ *
+ * `parser` now takes a chapter as input and parses its title and text correctly.
+ *
+ * @param transformer - function to transform the input
+ * @returns a parser that takes some input and runs the transformer function over it
+ */
+export declare function shape<const X, const I>(transformer: (item: X) => I): Parser<null>;

package/dist/parsers.js

@@ -246,3 +246,96 @@ export function set(key, value) {
         return captureSuccess(null, input, { [key]: value });
     });
 }
+/**
+ * A parser that always succeeds with the given value.
+ * @param value - value to succeed with
+ * @returns value
+ */
+export function succeed(value) {
+    return trace(`succeed(${value})`, (input) => {
+        return success(value, input);
+    });
+}
+/**
+ * A parser that always fails with the given message.
+ * @param message - message to fail with
+ * @returns failure
+ */
+export function fail(message) {
+    return trace(`fail(${message})`, (input) => {
+        return failure(message, input);
+    });
+}
+/**
+ * Takes a string. Succeeds if the given input contains that string.
+ * Consumes no input.
+ *
+ * @param substr - substring to find
+ * @returns - parser that succeeds if the given input contains that string
+ */
+export function includes(substr) {
+    return trace(`includes(${substr})`, (input) => {
+        if (input.includes(substr)) {
+            return success(substr, input);
+        }
+        return failure(`expected ${escape(input)} to include ${escape(substr)}`, input);
+    });
+}
+/**
+ * Like `includes`, but case-insensitive.
+ *
+ * @param substr - substring to find
+ * @returns - parser that succeeds if the given input contains that string
+ */
+export function iIncludes(substr) {
+    return trace(`iIncludes(${substr})`, (input) => {
+        if (input.toLowerCase().includes(substr.toLowerCase())) {
+            return success(substr, input);
+        }
+        return failure(`expected "${input}" to include "${substr}" (case-insensitive)`, input);
+    });
+}
+/**
+ * Returns a parser that takes some input, runs the transformer function over it,
+ * and returns the result as `rest`, so it can be chained to another parser.
+ * It always returns null as its result. Always succeeds.
+ *
+ * `shape` is useful for modifying the user's input before running parsers over it.
+ * For example, here is a parser that takes in a chapter
+ * and checks that its title starts with "Once upon a time"
+ *
+ * ```ts
+ * const parser = seqR(
+ * shape((c: Chapter) => c.title),
+ *   istr("Once upon a time"),
+ *   )
+ * );
+ * ```
+ *
+ * Now you might be thinking, why not just use the chapter's title as input?
+ * `shape` is most useful when you want to parse multiple properties.
+ *
+ * ```ts
+ * const titleParser = seqR(
+ *   shape((c: Chapter) => c.title),
+ *   istr("Once upon a time"),
+ * );
+ *
+ * const textParser = seqR(
+ *   shape((c: Chapter) => c.text),
+ *   istr("There was a princess"),
+ * );
+ *
+ * const parser = and(titleParser, textParser);
+ * ```
+ *
+ * `parser` now takes a chapter as input and parses its title and text correctly.
+ *
+ * @param transformer - function to transform the input
+ * @returns a parser that takes some input and runs the transformer function over it
+ */
+export function shape(transformer) {
+    return trace(`shape()`, (_input) => {
+        return success(null, transformer(_input));
+    });
+}

package/dist/types.d.ts

@@ -1,10 +1,10 @@
 /** A generic object type. */
 export type PlainObject = Record<string, unknown>;
 /** Represents a parse success with no captures. */
-export type ParserSuccess<T> = {
+export type ParserSuccess<T, R = string> = {
     success: true;
     result: T;
-    rest: string;
+    rest: R;
     nextParser?: Parser<any>;
 };
 /** Represents a parse success with captures. Notice nextParser is also a CaptureParser. */
@@ -16,27 +16,47 @@ export type CaptureParserSuccess<T, C extends PlainObject> = {
     nextParser?: CaptureParser<any, any>;
 };
 /** Represents a parse failure. */
-export type ParserFailure = {
+export type ParserFailure<R = string> = {
     success: false;
-    rest: string;
+    rest: R;
     message: string;
 };
-export type ParserResult<T> = ParserSuccess<T> | ParserFailure;
-export type CaptureParserResult<T, C extends PlainObject> = CaptureParserSuccess<T, C> | ParserFailure;
-/** A parser is any function that takes a string and returns a ParserResult. */
-export type Parser<T> = (input: string) => ParserResult<T>;
-/** A capture parser is any function that takes a string and returns a CaptureParserResult.
+export type ParserResult<T, R = string> = ParserSuccess<T, R> | ParserFailure<R>;
+export type CaptureParserResult<T, C extends PlainObject, R = string> = CaptureParserSuccess<T, C> | ParserFailure<R>;
+/** A parser is any function that takes an arg and returns a ParserResult. */
+export type Parser<T, I = string> = (input: I) => ParserResult<T>;
+/** A string parser is any function that takes a string and returns a ParserResult. */
+export type StringParser<T> = (input: string) => ParserResult<T>;
+/** A capture parser is any function that takes an arg and returns a CaptureParserResult.
  * A CaptureParserResult is the same as a ParserResult, except it also includes captures,
  * i.e. matches selected using `capture`. */
-export type CaptureParser<T, C extends PlainObject> = (input: string) => CaptureParserResult<T, C>;
-export type GeneralParser<T, C extends PlainObject> = Parser<T> | CaptureParser<T, C>;
+export type CaptureParser<T, C extends PlainObject, I = string> = (input: I) => CaptureParserResult<T, C>;
+/** A string capture parser is any function that takes a string and returns a CaptureParserResult. */
+export type StringCaptureParser<T, C extends PlainObject> = (input: string) => CaptureParserResult<T, C>;
+export type GeneralParser<T, C extends PlainObject, I = string> = Parser<T, I> | CaptureParser<T, C, I>;
+export type GeneralStringParser<T, C extends PlainObject> = Parser<T, string> | CaptureParser<T, C, string>;
 export declare function isCaptureResult<T, C extends PlainObject>(result: ParserResult<T>): result is CaptureParserSuccess<T, C>;
+/**
+ * This typed function is helpful in filtering out the successes
+ * from an array of results while preserving type information. For example:
+ *
+ * ```
+ * // type is ParserSuccess[]
+ * results.filter(isSuccess);
+ *
+ * // type is ParserResult[]
+ * results.filter(r => r.success);
+ * ```
+ * @param result - a parser result
+ * @returns - true if the result is a success, otherwise false
+ */
+export declare function isSuccess<T, R = string>(result: ParserResult<T, R>): result is ParserSuccess<T, R>;
 /** Convenience function to return a ParserSuccess */
-export declare function success<T>(result: T, rest: string): ParserSuccess<T>;
+export declare function success<T, R = string>(result: T, rest: R): ParserSuccess<T, R>;
 /** Convenience function to return a CaptureParserSuccess */
 export declare function captureSuccess<T, C extends PlainObject>(result: T, rest: string, captures: C): CaptureParserSuccess<T, C>;
 /** Convenience function to return a ParserFailure */
-export declare function failure(message: string, rest: string): ParserFailure;
+export declare function failure<R = string>(message: string, rest: R): ParserFailure<R>;
 /** Prettify an intersected type, to make it easier to read. */
 export type Prettify<T> = {
     [K in keyof T]: T[K];
@@ -71,7 +91,15 @@ export type HasCaptureParsers<T extends readonly GeneralParser<any, any>[]> = Ex
  * the result and capture types. This is useful for a combinator like `or`
  * which is not able to infer its return type correctly.
  */
-export type PickParserType<T extends readonly GeneralParser<any, any>[]> = HasCaptureParsers<T> extends true ? CaptureParser<MergedResults<T>, UnionOfCaptures<T>> : Parser<MergedResults<T>>;
+export type PickParserType<T extends readonly GeneralParser<any, any>[], I = string> = I extends string ? PickParserTypeString<T> : PickParserTypeGeneral<T, I>;
+/** split out to make types more readable */
+export type PickParserTypeGeneral<T extends readonly GeneralParser<any, any>[], I = string> = HasCaptureParsers<T> extends true ? CaptureParser<MergedResults<T>, UnionOfCaptures<T>, I> : Parser<MergedResults<T>, I>;
+export type PickParserTypeString<T extends readonly GeneralParser<any, any>[]> = HasCaptureParsers<T> extends true ? StringCaptureParser<MergedResults<T>, UnionOfCaptures<T>> : StringParser<MergedResults<T>>;
+/**
+ * Like `PickParserType`, but the result is an array of the result types,
+ * instead of just a union.
+ */
+export type PickParserTypeArray<T extends readonly GeneralParser<any, any>[], I = string> = HasCaptureParsers<T> extends true ? CaptureParser<MergedResults<T>, UnionOfCaptures<T>, I> : Parser<MergedResults<T>[], I>;
 /** This is used to generate a return type for the `many` and `many1` combinators.
  * Given a parser we want to apply `many` to. Suppose its type is `Parser<string>`.
  * This will return `Parser<string[]>` as the return type.

package/dist/types.js

@@ -1,6 +1,23 @@
 export function isCaptureResult(result) {
     return "captures" in result;
 }
+/**
+ * This typed function is helpful in filtering out the successes
+ * from an array of results while preserving type information. For example:
+ *
+ * ```
+ * // type is ParserSuccess[]
+ * results.filter(isSuccess);
+ *
+ * // type is ParserResult[]
+ * results.filter(r => r.success);
+ * ```
+ * @param result - a parser result
+ * @returns - true if the result is a success, otherwise false
+ */
+export function isSuccess(result) {
+    return result.success;
+}
 /** Convenience function to return a ParserSuccess */
 export function success(result, rest) {
     return { success: true, result, rest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarsec",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {
@@ -21,6 +21,7 @@
       "require": "./dist/index.js"
     }
   },
+  "type": "module",
   "types": "./dist/index.d.ts",
   "keywords": ["parser", "parser combinator", "parsec"],
   "author": "",