Summary

A Note about Types

Types are given in the descriptions for each of the parsers and functions listed below. The format here is just something that makes reasonable sense. These are not TypeScript types or anything that's actually useful in code. The types are just to make it easy to talk about their interface.

Some of the definitions don't, in fact, represent anything that's actually legal. alt, for example, is given this type information: alt(...ps: Parser[], m?: string). In JavaScript, you can't declare a function parameter after you declare a rest parameter (the one with the ... in front of it). In fact, in code, this function's signature is just alt(...args). But the code looks for an optional string at the end, so the type that we provide here is useful for discussing how alt works.

A best effort is given to give useful types for documentation, but there's no way to make them perfect.

Assertions in the library do take care of most of the problem. If a 3-character string gets passed to char, for example, an error will be thrown whether or not the type system can express that.

Parsers

There are three kinds of entries in these tables: parsers, functions that produce parsers, and combinators. Since each of these either is or produces a parser, they are all referred to as parsers unless there is reason to differentiate.

Additionally, parsers are often said to return a value or to have a value as a result. Parsers all return Reply objects, but when return or result is used, it's meant to refer to the value held by the Result object inside that Reply object. It should be unambiguous.

Table 1: Single character parsers

Parser	Description
char	Parses a single character.
ichar	Parses a single character, but without case sensitivity.
satisfy	Parses a single character for which a predicate returns true.
range	Parses a single character whose code point is between two other characters.
any	Parses any one character.
oneof	Parses a single character which is included in a string or an array.
noneof	Parses a single character which is not in included in a string or an array.
digit	Parses a single decimal digit (0-9).
hex	Parses a single hexadecmial digit (0-9, a-f, or A-F).
octal	Parses a single octal digit (0-7).
letter	Parses a single ASCII letter (a-z or A-Z).
alpha	Parses a single ASCII alphanumeric character (0-9, a-z, or A-Z).
lower	Parses a single ASCII lowercase letter (a-z).
upper	Parses a single ASCII uppercase letter (A-Z).
uletter	Parses a single UTF-8 letter.
ualpha	Parses a single UTF-8 alphanumeric character.
ulower	Parses a single UTF-8 lowercase letter.
uupper	Parses a single UTF-8 uppercase letter.

Table 2: String (multiple-character) parsers

Parser	Description
str	Parses a string.
istr	Parses a string, but without case sensitivity.
regex	Parses a string matching a regular expression pattern.
all	Parses the remainder of the input as a string.
anystr	Parses a string of a certain number of characters.

Table 3: Whitespace parsers

Parser	Description
newline	Parses a single ASCII newline character (\r, \n, or \r\n).
space	Parses a single ASCII whitespace character (, \t, or a newline).
spaces	Skips zero or more ASCII whitespace characters.
spaces1	Skips one or more ASCII whitespace characters.
unewline	Parses a single UTF-8 newline character.
uspace	Parses a single UTF-8 whitespace character (including newlines.md).
uspaces	Skips zero or more UTF-8 whitespace characters.
uspaces1	Skips one or more UTF-8 whitespace characters.
eof	Succeeds only at the end of the input.

Table 4: Miscellaneous parsers

Parser	Description
always	Always succeeds and returns a value.
fail	Fails with a generic message.
fatal	Fails fatally with a generic message.

Table 5: Sequence combinators

Parser	Description
seq	Executes a series of parsers in order, returning their results in an array.
left	Executes two parsers in order and returns the result of the first one.
right	Executes two parsers in order and returns the result of the second one.
many	Executes a parser zero or more times until it fails, returning all of the results in an array.
many1	Executes a parser one or more times until it fails, returning all of the results in an array.
sepby	Executes a content parser zero or more times with an application of a separator parser between each. Returns the content parser results.
sepby1	Executes a content parser one or more times with an application of a separator parser between each. Returns the content parser results.
endby	Executes a content parser zero or more times with an application of a separator parser between each and optionally at the end. Returns the content parser results.
endby1	Executes a content parser one or more times with an application of a separator parser between each and optionally at the end. Returns the content parser results.
count	Executes a parser a certain number of times, returning the results in an array.
pipe	Executes a series of parsers in order, then passes the results as arguments to a function, then returns the result of that function.
between	Executes a content parser between two other parsers, returning only the content parser's result.
until	Executes a content parser zero or more times until an end parser succeeds. Returns the content parser's results.
lassoc	Executes a content parser zero or more times with an application of an operator parser between each. Returns the value obtained by left associative application of all functions returned by the operator parser to the results returned by the content parser.
lassoc1	Executes a content parser one or more times with an application of an operator parser between each. Returns the value obtained by left associative application of all functions returned by the operator parser to the results returned by the content parser.
rassoc	Executes a content parser zero or more times with an application of an operator parser between each. Returns the value obtained by right associative application of all functions returned by the operator parser to the results returned by the content parser.
rassoc1	Executes a content parser one or more times with an application of an operator parser between each. Returns the value obtained by right associative application of all functions returned by the operator parser to the results returned by the content parser.

Table 6: Alternative and conditional combinators

Parser	Description
alt	Executes a series of parsers one at a time until one succeeds.
opt	Executes a parser and returns its result on success. On failure, succeeds but returns nothing.
def	Executes a parser and returns either its result upon success or a default value upon failure.
peek	Executes a parser and returns its result without consuming input.
empty	Executes a parser and fails if the parser succeeds but consumes input.
not	Executes a parser and succeeds without consuming input if that parser fails.

Table 7: Backtracking combinators

Parser	Description
attempt	Executes a parser, backtracking to its original position if the parser fails and consumes input.
bseq	Executes a series of parsers in order, returning their results in an array. Backtracks to where the first parser was applied if any other of its parsers fails.
bblock	Runs a generator function. The generator can yield parsers, whose results will be returned as the result of the yield expressions. Returns the result of the generator. Backtracks to where the first yielded parser was applied if any later parser fails.
bchain	Executes a parser, then applies a function to the result, then applies the parser returned by the function. Backtracks to where the first parser was applied if the parser returned by the function fails.
bapply	Parses content and a function, returning the result of the function when passed the content. Backtracks to where the first parser was applied if the second parser fails.
bleft	Executes two parsers in order and returns the result of the first one. Backtracks to the location where the first parser was applied if the second one fails.
bright	Executes two parsers in order and returns the result of the second one. Backtracks to the location where the first parser was applied if the second one fails.
bpipe	Executes a series of parsers in order, then passes the results as arguments to a function, then returns the result of that function. Backtracks to where the first parser was applied if any other parser fails.
bcount	Executes a parser a certain number of times, returning the results in an array. Backtracks to where the first parser was applied if any other parser fails.
buntil	Executes a content parser zero or more times until an end parser succeeds. Returns the content parser's results. Backtracks to where the content parser was first applied if it fails before the end parser succeeds.
bbetween	Executes a content parser between two other parsers, returning only the content parser's result. Backtracks to where the first parser was applied if either other parser fails.

Table 8: Chaining combinators

Parser	Description
chain	Applies a parser, then applies a function to the result, then applies the parser returned by the function.
map	Applies a parser, then applies a function to the result, then returns the result of that function.
apply	Parses content and a function, returning the result of the function when passed the content.
value	Executes a parser and returns a value.
nth	Executes a parser and returns the nth element of the resulting array.
first	Executes a parser and returns the first element of the resulting array.
second	Executes a parser and returns the second element of the resulting array.
third	Executes a parser and returns the third element of the resulting array.
fourth	Executes a parser and returns the fourth element of the resulting array.
fifth	Executes a parser and returns the fifth element of the resulting array.
join	Executes a parser and returns its resulting array elements joined together into a string.
flat	Executes a parser and returns its resulting array with all sub-arrays flattened into a single-level array.
clean	Executes a parser and returns its resulting array with null and undefined values filtered out.

Table 9: Miscellaneous combinators

Parser	Description
block	Runs a generator function. The generator can yield parsers, whose results will be returned as the result of the yield expressions. Returns the result of the generator.
skip	Executes a parser and discards the result.
label	Provides an alternative error message if its contained parser fails.
lazy	Defers the execution of a parser factory until parsers are executed; allows definition of recursive parsers.

Tools

Tools provide ways to run parsers and ways to write new parsers (if block isn't good enough). Regular users will use the functions in Table 10, but those in Tables 11 and 12 are going to be of interest only to parser authors.

Table 10: Running parsers

Function	Description
parse	Executes a parser.
succeeded	Determines whether a parser result was successful.
status	Returns the status of a parser result.
success	Returns the value from a parser result if it was successful.
failure	Returns the error message from a parser result if it failed.
run	Executes a parser and either returns a successful result or throws an error.

Table 11: Error generation

Function	Description
expected	Creates an error list containing a single expected error message.
unexpected	Creates an error list containing a single unexpected error message.
generic	Creates an error list containing a single generic error message.
nested	Adds a nested error to an error list.
compound	Adds a compound error to an error list.
other	Creates an error list containing a single other error message.
merge	Merges two error lists.
formatErrors	Generates an error message out of a parser context and result.
getPosition	Determines the line/column position of a given context.

Table 12: Authoring parsers

Function	Description
parser	Creates a new parser.
okReply	Generates a reply representing a success.
failReply	Generates a reply representing a failure.
fatalReply	Generates a reply representing a fatal failure.

Types

Kessel is written in JavaScript, which is a dynamically typed language, and so none of these types actually exist within the code. However, there is a lot of consistency around what functions expect from parameters and what they provide as return values, and we are able to document that here.

For TypeScript users, there will be a declaration file provided which will codify all of these types.

Table 13: Types

Type	Description
CompoundError	A nested error that happened at a different location than the current context and has its own error message.
Context	The parsing context, which changes as more of the input is parsed.
ErrorList	A list of parsing errors.
ErrorType	The type of a parsing error, used to determine how it should be displayed in an error message.
Formatter	A function that formats error information into a string.
Input	Parser input text, which can be in one of several different forms.
LocalError	A simple parsing error.
NestedError	An error that happened at a different location than the current context.
Parser	A function which actually performs parsing.
Reply	The state of a parser after it has performed its parsing, consisting of an updated context and a result.
Result	The output of a parser, consisting of either a parsed value or a parsing error.
Status	The condition of a parser result, including whether the parse succeeded or not.