tarsec 0.0.13 → 0.0.15

package/README.md

@@ -40,8 +40,16 @@ parser("hello there"); // failure
 
 ## Features
 - tarsec is entirely TypeScript. There's nothing to compile.
-- [Debug mode](/tutorials/debugging.md) that prints what's happening step-by-step
 - Derived types: tarsec will generate TypeScript types for your parser
+- [Debug mode](/tutorials/debugging.md) that prints what's happening step-by-step
+- Tools to debug your parser's [performance](/tutorials/performance.md)
 - Partial [backtracking](/tutorials/backtracking.md) support
+- A way to make your parser more [secure](/tutorials/security.md).
+
+## Examples
+- [A markdown parser](/tests/examples/markdown.ts)
+
+Read more about [use cases for tarsec](/tutorials/use-case.md).
 
-Read more about [use cases for tarsec](/tutorials/use-case.md).
+## Contributing
+PRs for documentation, tests, and bug fixes are welcome.

package/dist/combinators/seq.js

@@ -1,12 +1 @@
-(function (factory) {
-    if (typeof module === "object" && typeof module.exports === "object") {
-        var v = factory(require, exports);
-        if (v !== undefined) module.exports = v;
-    }
-    else if (typeof define === "function" && define.amd) {
-        define(["require", "exports"], factory);
-    }
-})(function (require, exports) {
-    "use strict";
-    Object.defineProperty(exports, "__esModule", { value: true });
-});
+export {};

package/dist/combinators.d.ts

@@ -1,4 +1,4 @@
-import { CaptureParser, GeneralParser, InferManyReturnType, MergedCaptures, MergedResults, Parser, PickParserType, PlainObject } from "./types";
+import { CaptureParser, GeneralParser, InferManyReturnType, MergedCaptures, MergedResults, Parser, 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:
@@ -7,7 +7,6 @@ import { CaptureParser, GeneralParser, InferManyReturnType, MergedCaptures, Merg
  * { captures: <array of captures> }
  * ```
  *
- * Fails on empty strings
  * @param parser - parser to run
  * @returns - parser that runs the given parser zero to many times,
  * and returns the result as an array
@@ -20,6 +19,12 @@ export declare function many<const T extends GeneralParser<any, any>>(parser: T)
  * @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.
@@ -27,7 +32,7 @@ export declare function many1<const T extends GeneralParser<any, any>>(parser: T
  * @param parser - parser to run
  * @returns - parser that runs the given parser `num` times and returns an array of the results
  */
-export declare function count<T>(num: number, parser: Parser<T>): Parser<T[]>;
+export declare function exactly<T>(num: number, parser: Parser<T>): Parser<T[]>;
 /**
  * Same as `many`, but joins the results into a single string.
  *
@@ -103,9 +108,37 @@ export declare function not(parser: Parser<any>): Parser<null>;
  * @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>>;
 /**
  * Returns a parser that consumes input till the given parser succeeds.
@@ -115,9 +148,73 @@ export declare function capture<T, const S extends string>(parser: Parser<T>, na
  * 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>;
-export declare function manyTillStr(str: string): Parser<string>;
-export declare function transform<R, C extends PlainObject, X>(parser: GeneralParser<R, C>, transformerFunc: (x: R) => X): GeneralParser<X, C>;
+/**
+ * `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.
@@ -146,6 +243,20 @@ export declare function search(parser: Parser<string>): Parser<string[]>;
  * @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;