tarsec 0.0.17 → 0.0.19

package/README.md

@@ -19,14 +19,14 @@ npm install tarsec
 ## Hello world
 
 ```ts
-import { getResults, str, seq, space } from "tarsec";
+import { str, seqR, space } from "tarsec";
 
 // define a parser
-const parser = seq([
+const parser = seqR(
     str("hello"),
     space,
     str("world")
-], getResults);
+);
 
 // then use it
 parser("hello world"); // success

package/dist/combinators/seq.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/combinators/seq.js

@@ -0,0 +1 @@
+export {};

package/dist/combinators.d.ts

@@ -0,0 +1,359 @@
+import { CaptureParser, GeneralParser, InferManyReturnType, MergedCaptures, MergedResults, Parser, ParserResult, PickParserType, 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:
+ *
+ * ```ts
+ * { captures: <array of captures> }
+ * ```
+ *
+ * @param parser - parser to run
+ * @returns - parser that runs the given parser zero to many times,
+ * and returns the result as an array
+ */
+export declare function many<const T extends GeneralParser<any, any>>(parser: T): InferManyReturnType<T>;
+/**
+ * Same as `many`, but fails if the parser doesn't match at least once.
+ *
+ * @param parser - parser to run
+ * @returns a parser that runs the given parser one to many times,
+ */
+export declare function many1<const T extends GeneralParser<any, any>>(parser: T): InferManyReturnType<T>;
+/**
+ * Takes a parser, runs it, and returns the number of times it succeeded.
+ * @param parser - parser to run
+ * @returns - the number of times the parser succeeded.
+ */
+export declare function count<T>(parser: Parser<T>): Parser<number>;
+/**
+ * Takes a parser, runs it n times, and returns the results as an array.
+ * If it cannot run the parser n times, it fails without consuming input.
+ * @param num - number of times to run the parser
+ * @param parser - parser to run
+ * @returns - parser that runs the given parser `num` times and returns an array of the results
+ */
+export declare function exactly<T>(num: number, parser: Parser<T>): Parser<T[]>;
+/**
+ * Same as `many`, but joins the results into a single string.
+ *
+ * @param parser - parser to run. The parser must return a string as its result.
+ * @returns - parser that runs the given parser zero to many times,
+ * and returns the result as a single string
+ */
+export declare function manyWithJoin<const T extends GeneralParser<string, any>>(parser: T): GeneralParser<string, any>;
+/**
+ * Same as `many1`, but joins the results into a single string.
+ *
+ * @param parser - parser to run. The parser must return a string as its result.
+ * @returns - parser that runs the given parser one to many times,
+ * and returns the result as a single string
+ */
+export declare function many1WithJoin(parser: Parser<string>): Parser<string>;
+/**
+ * `or` takes an array of parsers and runs them sequentially.
+ * It returns the results of the first parser that succeeds.
+ * You can use `capture` in an `or`:
+ *
+ * ```ts
+ * const parser = or(capture(digit, "num"), capture(word, "name"));
+ * ```
+ *
+ * `or` supports backtracking by returning a `nextParser`:
+ *
+ * ```ts
+ * const parser = or(str("hello"), str("hello!"));
+ *
+ * // this will match the first parser
+ * const result = parser("hello");
+ *
+ * // but or returns the untried parsers as a new parser
+ * result.nextParser("hello!"); // works
+ *
+ * // result.nextParser is the same as or(str("hello!"))
+ * ```
+ *
+ * @param parsers - parsers to try
+ * @returns - a parser that tries each parser in order. Returns the result of the first parser that succeeds.
+ */
+export declare function or<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): PickParserType<T>;
+/**
+ * Takes a parser and runs it. If the parser fails,
+ * optional returns a success with a null result.
+ *
+ * @param parser - parser to run
+ * @returns - a parser that runs the given parser.
+ * If it fails, returns a success with a null result.
+ */
+export declare function optional<T>(parser: Parser<T>): Parser<T | null>;
+/**
+ * Takes a parser and runs it. If the parser fails,
+ * `not` returns a success with a `null` result.
+ * If the parser succeeds, `not` returns a failure.
+ *
+ * @param parser - parser to run
+ * @returns - a parser that runs the given parser.
+ * If it fails, returns a success with a `null` result.
+ * If it succeeds, returns a failure.
+ */
+export declare function not(parser: Parser<any>): Parser<null>;
+/**
+ * Takes three parsers, `open`, `close`, and `parser`.
+ * `between` matches something that matches `parser`,
+ * surrounded by `open` and `close`. It returns the result of `parser`.
+ * If any of the parsers fail, `between` fails.
+ *
+ * @param open - parser for the opening delimiter
+ * @param close - parser for the closing delimiter
+ * @param parser - parser for the content
+ * @returns a parser that returns the result of `parser`.
+ */
+export declare function between<O, C, P>(open: Parser<O>, close: Parser<C>, parser: Parser<P>): Parser<P>;
+/**
+ * Parses many instances of the parser separated by separator.
+ * @param separator
+ * @param parser
+ * @returns a parser that runs the given parser zero to many times, separated by the separator parser.
+ */
+export declare function sepBy<S, P>(separator: Parser<S>, parser: Parser<P>): Parser<P[]>;
+/**
+ * Convenience function to use as the second argument to `seq` to get all the results from `seq`
+ * @param results
+ * @param captures
+ * @returns `results`
+ */
+export declare function getResults<R, C>(results: R, captures: C): R;
+/**
+ * Convenience function to use as the second argument to seq to get all the captures.
+ * @param results
+ * @param captures
+ * @returns `captures`
+ */
+export declare function getCaptures<R, C>(results: R, captures: C): C;
+/**
+ * `capture` is the only way to create a capture. Given a parser and a name,
+ * `capture` runs the parser and saves its result in a captures object
+ * with the given name as the key. It returns the result from the parser,
+ * and attaches the captures object along with it.
+ *
+ * @param parser - parser to run
+ * @param name - name of the capture
+ * @returns - the results of the parser, with the captures object attached.
+ */
+export declare function capture<T, const S extends string>(parser: Parser<T>, name: S): CaptureParser<T, Record<S, T>>;
+/**
+ * `captureCaptures` lifts your captures up a level. Suppose you have a parser like this:
+ *
+ * ```ts
+ * const greeting = seqC(
+ *   str("hello"),
+ *   spaces,
+ *   capture(word, "name"),
+ *   str("!"),
+ *   spaces,
+ *   capture(manynTillStr("?"), "secondPart")
+ * )
+ *
+ * This parses a greeting like "hello Adit! How was your day?" into:
+ *
+ * ```ts
+ * {
+ *   name: "Adit",
+ *   secondPart: "How was your day?"
+ * }
+ * ```
+ *
+ * Now, suppose you decide to refactor this parser into two parsers:
+ *
+ * ```ts
+ * const firstPart = seqC(
+ *   str("hello"),
+ *   spaces,
+ *   capture(word, "name"),
+ *   str("!")
+ * )
+ *
+ * const secondPart = seqC(
+ *   spaces,
+ *   capture(manyTillStr("?"), "secondPart")
+ * )
+ * ```
+ *
+ * And put them together:
+ *
+ * ```ts
+ * const greeting = seqC(
+ *   firstPart,
+ *   secondPart
+ * )
+ * ```
+ *
+ * Unfortunately, this will no longer return an object in that shape,
+ * because it's not actually capturing anything. Captures in `firstPart`
+ * and `secondPart` won't get propagated up. Suppose you try to use `capture` like this:
+ * ```ts
+ * const greeting = seqC(
+ *   capture(firstPart, "firstPart"),
+ *   capture(secondPart, "secondPart")
+ * )
+ * ```
+ * Now you'll get an object that looks like this instead:
+ *
+ * ```ts
+ * {
+ *   firstPart: {
+ *     name: "Adit"
+ *   },
+ *   secondPart: {
+ *     secondPart: "How was your day?"
+ *   }
+ * }
+ * ```
+ *
+ * What you want is for the captures in the child parsers to get merged up to the parent parser. For that, use `captureCaptures`:
+ *
+ * ```ts
+ * const greeting = seqC(
+ *   captureCaptures(firstPart),
+ *   captureCaptures(secondPart)
+ * )
+ * ```
+ * @param parser - parser to capture captures from
+ * @returns - the parser's result set as the captures object
+ */
+export declare function captureCaptures<T extends PlainObject>(parser: Parser<T>): CaptureParser<T, T>;
+/**
+ * Returns a parser that consumes input till the given parser succeeds.
+ * @param parser - the stop parser
+ * @returns a parser that consumes the input string until the stop parser succeeds.
+ * Then it returns the consumed input as a string.
+ * The stop parser's match is not included in the result.
+ */
+export declare function manyTill<T>(parser: Parser<T>): Parser<string>;
+/**
+ * Just like `manyTill`, but fails unless at least one character of input is consumed.
+ * @param parser - the stop parser
+ * @returns a parser that consumes the input string until the stop parser succeeds.
+ */
+export declare function many1Till<T>(parser: Parser<T>): Parser<string>;
+/**
+ * `manyTillOneOf` is an optimized version of `manyTill`.
+ * The `manyTill` combinator is slow because it runs the given parser
+ * on every character of the string until it succeeds. However, if you
+ * just want to consume input until you get to a substring,
+ * use `manyTillOneOf`. It uses `indexOf`, which is significantly faster
+ * than running a parser over every character.
+ *
+ * Given an array of strings, this parser consumes input until it hits one of those strings.
+ * If none of the strings is found, the parser will consume all input and return success.
+ *
+ * @param str - the string to stop at
+ * @param options - object of optional parameters. { insensitive: boolean }
+ * @returns a parser that consumes the input string until one of the given strings is found.
+ */
+export declare function manyTillOneOf(stops: string[], { insensitive }?: {
+    insensitive?: boolean;
+}): Parser<string>;
+/**
+ * `manyTillStr` is an optimized version of `manyTill`.
+ * The `manyTill` combinator is slow because it runs the given parser
+ * on every character of the string until it succeeds. However, if you
+ * just want to consume input until you get to a substring,
+ * use `manyTillStr`. It uses `indexOf`, which is significantly faster
+ * than running a parser over every character.
+ *
+ * @param str - the string to stop at
+ * @param options - object of optional parameters. { insensitive: boolean }
+ * @returns a parser that consumes the input string until the given string is found.
+ */
+export declare function manyTillStr(str: string, { insensitive }?: {
+    insensitive?: boolean;
+}): Parser<string>;
+/**
+ * Like `manyTillStr`, but case insensitive.
+ * @param str - the string to stop at
+ * @returns a parser that consumes the input string until the given string is found.
+ */
+export declare function iManyTillStr(str: string): Parser<string>;
+/**
+ * `map` is a parser combinator that takes a parser and a mapper function.
+ * If the parser succeeds, it maps its result using the mapper function.
+ * You can think of map as a general `map`, like for functors, applied to a parser.
+ * Since `map` itself is a parser, you can use it in `seq` or other combinators.
+ *
+ * @param parser - parser to run
+ * @param mapperFunc - function to map the result of the parser
+ * @returns
+ */
+export declare function map<R, C extends PlainObject, X>(parser: GeneralParser<R, C>, mapperFunc: (x: R) => X): GeneralParser<X, C>;
+/**
+ * Given a parser that returns a string, `search` looks for all substrings in a string that match that parser.
+ * For example, given a parser that matches quoted strings, `search` will return an array of all the quoted strings
+ * it finds in the input, as an array.
+ *
+ * The rest of the input that isn't part of the result is simply joined together and returned as a string.
+ * If you need a more structured result + rest, you can use `within` instead.
+ *
+ * @param parser - a parser that returns a string
+ * @returns - a parser that returns an array of strings
+ */
+export declare function search(parser: Parser<string>): Parser<string[]>;
+/**
+ * seq takes an array of parsers and runs them sequentially.
+ * If any of the parsers fail, seq fails without consuming any input.
+ *
+ * The second argument to seq is a function.
+ * The first argument of that function is an array of results:
+ * one result from each of the parsers you gave to seq.
+ * The second is an object containing any captures.
+ * You can use this second argument, the transformer function,
+ * to transform these however you want and return a result
+ *
+ * Tarsec includes the utility functions `getResults` and `getCaptures`
+ * to just return the results array or captures object respectively for you.
+ *
+ * Finally, you don't need to use seq at all. You can just hand write the logic.
+ * But you'll need to do the error handling
+ * and pass the remaining input to the next parser yourself.
+ * seq also does some backtracking for you that you will need to do yourself.
+ *
+ * Also see `seqR` and `seqC` for convenience functions that return the results or captures respectively.
+ *
+ * @param parsers - parsers to run sequentially
+ * @param transform - function to transform the results and captures. The params are the results and captures
+ * @param debugName - optional name for trace debugging
+ * @returns
+ */
+export declare function seq<const T extends readonly GeneralParser<any, any>[], U>(parsers: T, transform: (results: MergedResults<T>[], captures: MergedCaptures<T>) => U, debugName?: string): Parser<U>;
+/** Just like seq except it returns the results.
+ * It's like using `seq([parsers], getResults)`.
+ */
+export declare function seqR<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): Parser<MergedResults<T>[]>;
+/** Just like seq except it returns the captures.
+ * It's like using `seq([parsers], getCaptures)`.
+ */
+export declare function seqC<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): Parser<MergedCaptures<T>>;
+/**
+ * Match takes an input string and a parser. If the parser matches the input string
+ * and consumes the entire input string, `match` returns `true`. Otherwise it returns `false`.
+ *
+ * @param input - input string
+ * @param parser - parser to match input against
+ * @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>, const ELSE extends GeneralParser<any, any>, 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 T extends readonly GeneralParser<any, any>[]>(...parsers: T): PickParserType<T>;