prsc.md

Home > prsc

prsc package

Functions

Function	Description
codepoint(isMatch, expected)	Creates a Parser that skips the next code point if the given predicate returns true.This counts in unicode characters (code points), not UTF-16 code units.To match a sequence of code points, consider using codepoints instead.
codepoints(isMatch, expected)	Creates a Parser that skips code points while the given predicate returns true.This counts in unicode characters (code points), not UTF-16 code units.This acts like starConsumed(codepoint(isMatch, [])) if expected is not set, or as plusConsumed(codepoint(isMatch, expected)) if it is, but is much more efficient than either of those combinations.
collect(gen)	Helper to collect both the yielded values and the returned value from a generator.
complete(parser)	Creates a Parser that applies the given parser and only succeeds (returning the inner parser's result) if parsing concludes at the end of the input string.
consume(parser)	Creates a Parser that applies the given parser but discards the resulting value.
cut(parser)	Creates a Parser that turns errors returned by the inner parser into fatal errors. Parsers such as or and star will not continue to attempt additional matches if a parser returns a fatal error, and will usually return the error instead.
delimited(open, inner, close, cutAfterOpen)	Creates a Parser that applies the given parsers in sequence, returning the result value of the middle parser at the offset of the third if all are successful. If any parser fails, the error is returned as-is.Optionally makes errors by the second and third parsers fatal if cutAfterOpen is true.
dispatch(mapping, otherwise, extraOffset, expected)	Creates a parser that looks at a single codepoint to determine which parser to invoke. Can be used as an alternative to large or parsers if looking ahead can narrow down the options.Can optionally look ahead further than the current codepoint, which is useful when nesting several dispatch parsers.
error(offset, expected, fatal)	Creates an unsuccessful ParseResult (parse error) at the given offset.
except(match, except, expected)	Creates a Parser that matches only if the first Parser matches input at the starting position, but the second Parser does not.
filter(parser, filter, expected, fatal)	Creates a Parser that uses the given filter predicate to check values generated by the given parser. Values that pass the predicate are passed through, those that don't return a parse error instead.
filterUndefined(parser)	Creates a parser that discards undefined values from the array produced by the given parser.Useful in combination with star, or and consume:

const a: Parser<string> = token('a');
const b: Parser<void> = consume(token('b'));
const abs: Parser<(string | void)[]> = star(or<string | void>([a, b]));
const as: Parser<string[]> = filterUndefined(abs);

| | first(x, y) | Returns the first of the given two arguments. Useful as a join function for then. See also followed. | | followed(parser, after) | Creates a Parser that applies the given two parsers in sequence, returning the result value of the first at the offset of the second if both succeed. If either parser fails the error is returned as-is.Equivalent to then(parser, after, first). | | map(parser, map) | Creates a Parser that applies the given function to each value generated by the given parser. | | not(parser, expected) | Creates a Parser that succeeds at the starting offset if the given parser fails and vice-versa. | | ok(offset) | Creates a successful ParseResult with an undefined value. Use this to signal success in cases where no value is required. | | okWithValue(offset, value) | Creates a successful ParseResult containing the given value. | | optional(parser) | Creates a Parser that tries to apply the given parser optionally. It returns the inner parser's result if succesful, and otherwise indicates success at the starting offset with a null value.If the inner parser returns a fatal failure, the error is returned as-is. | | or(parsers, expected) | Creates a Parser that applies each of the given parsers in turn until one matches, then returns that parser's result. If no parser matches, an error is returned reflecting the furthest offset reached in the input string. If any parser returns a fatal error, no further branches are tried. | | peek(parser) | Creates a Parser that applies the given parser without consuming any input. That is, if the inner parser is successful, success is returned (with the resulting value) at the starting offset, effectively making the parser consume no input.Errors returned by the inner parser are returned as-is. | | plus(parser) | Creates a Parser that tries to apply the given parser one or more times in sequence. Values for successful matches are collected in an array. Once the inner parser no longer matches, success is returned at the offset reached with the accumulated values. The parser is required to match at least once, so an initial failure is returned as-is.If the inner parser returns a fatal failure, the error is returned as-is. | | plusConsumed(parser) | Creates a Parser that tries to apply the given parser one or more times in sequence. Values for successful matches are discarded. Once the inner parser no longer matches, success is returned at the offset reached. The parser is required to match at least once, so an initial failure is returned as-is.If the inner parser returns a fatal failure, the error is returned as-is. | | preceded(before, parser) | Creates a Parser that applies the given two parsers in sequence, returning the result of the second if the first succeeds.Equivalent to then(before, parser, second). | | range(firstCodePoint, lastCodePoint, expected) | Creates a Parser that matches a single character from a range of codepoints.Use recognize if you need the character that was matched. | | recognize(parser) | Creates a Parser that applies the given parser. If successful, the inner parser's value is discarded and the substring that was consumed from the input is returned as value instead. Errors are returned as-is.When using this in combination with star or plus, consider using starConsumed or plusConsumed instead for efficiency. | | second(x, y) | Returns the second of the given two arguments. Useful as a join function for then. See also preceded. | | sequence(parsers) | Creates a parser that applies the given parsers in sequence, returning a tuple of the corresponding values if all of them accept.This can be slightly less efficient than nesting then and its variations, but may be a lot more readable. If you don't care about any of the values produced, consider using sequenceConsumed instead. | | sequenceConsumed(parsers) | Creates a parser that applies the given parsers in sequence, discarding all of the values produced. | | skipChars(nCodepoints) | Creates a Parser that skips the given number of characters.This counts in unicode characters (code points), not UTF-16 code units. | | star(parser) | Creates a Parser that tries to apply the given parser zero or more times in sequence. Values for successful matches are collected in an array. Once the inner parser no longer matches, success is returned at the offset reached with the accumulated values.If the inner parser returns a fatal failure, the error is returned as-is. | | starConsumed(parser) | Creates a Parser that tries to apply the given parser zero or more times in sequence. Values for successful matches are discarded. Once the inner parser no longer matches, success is returned at the offset reached.If the inner parser returns a fatal failure, the error is returned as-is. | | streaming(parser) | Creates a StreamingParser which applies the given Parser and yields the value produced if it matches. | | streamingComplete(parser) | Creates a StreamingParser that applies the given parser and directly yields values produced by it, and then only succeeds if parsing concludes at the end of the input string. | | streamingFilterUndefined(parser) | Creates a StreamingParser which discards undefined values yielded by the given StreamingParser. | | streamingOptional(parser) | Creates a StreamingParser that tries to apply the given parser optionally. It only yields the values produced by the inner parser if it matches successfully, and does not yield anything otherwise. | | streamingStar(parser) | Creates a StreamingParser that tries to apply the given StreamingParser zero or more times in sequence. Values produced during each iteration are only yielded whenever the inner parser matches successfully. | | streamingThen(parser1, parser2) | Creates a StreamingParser which applies the given two StreamingParsers in sequence.Unlike then, this does not combine values using a function, but instead simply yields the values produced by both parsers as they produce them. | | then(parser1, parser2, join) | Creates a Parser that applies the given two parsers in sequence, returning success only if both succeed. The given join function is used to combine the values from both parsers into the single value to return. If either parser fails, the failure is returned as-is. | | token(token) | Creates a Parser that matches the given string. |

Variables

Variable	Description
end	A parser that only succeeds if the end of the input string is reached.
start	A parser that only succeeds at the start of the input string.

Type Aliases

Type Alias	Description
Parser	A parser is a function that tries to match whatever it expects at the given offset in the input string. Returns a ParseResult.
ParseResult	The result of parsing - either success (with an offset at which to resume parsing the next thing) or failure. If a failure is fatal, parsing should not continue to try alternative options.A ParseResult may contain a value that represents the parsed input.
StreamingParser	A StreamingParser is similar to a Parser, but instead of returning a value when parsing is complete it can parse incrementally and yield values as they are produced. The generator returns a ParseResult when iteration is done which indicates whether parsing was successful.