\descr{\lstinline|fun matchSubString (subj, patt, pos)|}{Takes two strings "\lstinline|subj|" and "\lstinline|patt|" and integer position "\lstinline|pos|" and
checks if a substring of "\lstinline|subj|" starting at position "\lstinline|pos|" is equal to "\lstinline|patt|"; returns integer value, treated as a boolean.}
\descr{\lstinline|infix =?= at < (x, y)|}{A generic comparison operator similar to \lstinline|compare|, but capable of handling cyclic/shared data structures.}
\descr{\lstinline|infix === at == (x, y)|}{A generic equality operator capable of handling cyclic/shared data structures.}
\descr{\lstinline|fun timer ()|}{Creates a timer. Creates a zero-argument function which, being called, returns the elapsed time in microseconds since its creation.}
\descr{\lstinline|fun toSeconds (n)|}{Converts an integer value, interpreted as microseconds, into a floating-point string.}
\descr{\lstinline|fun randomArray (f, n)|}{Generates a random array of \emph{deep} size \lstinline|n|. The length of the array is chosen randomly, and \lstinline|f| is intended to be an element-generating function which takes the size of the element as an argument.}
\descr{\lstinline|fun split (n, k)|}{Splits a non-negative integer \lstinline|n| in \lstinline|k| random summands. Returns an array if length \lstinline|k|. \lstinline|k| has to be non-negative.}
\newsavebox\strubox
\begin{lrbox}{\strubox}
\begin{lstlisting}
structure (100,
[[2, fun ([x, y]) {Add (x, y)}],
[2, fun ([x, y]) {Sub (x, y)}]],
fun () {Const (randomInt ())}
)
\end{lstlisting}
\end{lrbox}
\descr{\lstinline|fun structure (n, nodeSpec, leaf)|}{Generates a random tree-shaped data structure of size \lstinline|n|. \lstinline|nodeSpec| is an array of pairs \lstinline|[$k$, $f_k$]|, where $k$ is a non-negative integer and $f_k$ is a function which takes an array of length $k$ as its argument. Each pair describes a generator of a certain kind of interior node with degree $k$. \lstinline|leaf| is a zero-argument function which generates the leaves of the tree. For example, the following code
\usebox\strubox
can be used to generate a random arithmetic expression of size 100.}
Collections, implemented as AVL-trees. Four types of collections are provided: sets of ordered elements, maps of ordered keys to other values, memo
tables and hash tables. For sets and maps the generic "\lstinline|compare|" function from the unit "\lstinline|Std|" is used
as ordering relation. For memo table and hash tables the comparison of generic hash values, delivered by function "\lstinline|hash|" of unit "\lstinline|Std|"
\descr{\lstinline|fun emptyMap (f)|}{Creates an empty map. An argument is a comparison function, which returns zero, positive or negative integer values depending on
\descr{\lstinline|fun addMap (m, k, v)|}{Adds a binding of a key "\lstinline|k|" to a value "\lstinline|v|" into a map "\lstinline|m|". As a result, a new map is
returned.}
\descr{\lstinline|fun findMap (m, k)|}{Finds a binding for a key "\lstinline|k|" in the map "\lstinline|m|". Returns the value "\lstinline|None|" if
no binding is found, and "\lstinline|Some (v)|" if "\lstinline|k|" is bound to "\lstinline|v|".}
\descr{\lstinline|fun removeMap (m, k)|}{Removes the binding for "\lstinline|k|" from the map "\lstinline|m|" and returns a new map. This function
\descr{\lstinline|fun emptySet (f)|}{Creates an empty set. An argument is a comparison function, which returns zero, positive or negative integer values depending on
\descr{\lstinline|fun elements (s)|}{Returns a list of elements of a given set in ascending order.}
\descr{\lstinline|fun union (a, b)|}{Returns a union of given sets as a new set.}
\descr{\lstinline|fun diff (a, b)|}{Returns a difference between sets "\lstinline|a|" and "\lstinline|b|" (a set of those elements
of "\lstinline|a|" which are not in "\lstinline|b|") as a new set.}
\descr{\lstinline|fun listSet (l)|}{Converts a list into a set. }
\descr{\lstinline|fun iterSet (f, s)|}{Applied a function "\lstinline|f|" to each element of the set "\lstinline|s|". The elements are
enumerated in ascending order.}
\descr{\lstinline|fun mapSet (f, s)|}{Applies a function "\lstinline|f|" to each element of the set "\lstinline|s|" and returns a new set of images. The
\descr{\lstinline|fun foldSet (f, acc, s)|}{Folds a set "\lstinline|s|" using the function "\lstinline|f|" and initial value "\lstinline|acc|". The function
\descr{\lstinline|fun emptyCustomMemo (p, c)|}{Creates an empty customized memo table; \lstinline|p| is a predicate to filter out certain data structures (returns true on
data structures which \emph{should not be} hash-consed; ``\lstinline|\{\}|'' can be specified for always false predicate); \lstinline|c| is a custom comparison function.}
\descr{\lstinline|fun emptyMemo ()|}{Creates an empty memo table. Equivalent to \lstinline|emptyCustomMemo (\{\}, compare)|.}
\descr{\lstinline|fun addHashTab (t, k, v)|}{Adds a binding of "\lstinline|k|" to "\lstinline|v|" to the hash table "\lstinline|t|" and returns a
new hash table.}
\descr{\lstinline|fun findHashTab (t, k)|}{Searches for a binding for a key "\lstinline|k|" in the table "\lstinline|t|". Returns "\lstinline|None|"
if no binding is found and "\lstinline|Some (v)|" otherwise, where "\lstinline|v|" is a bound value.}
\descr{\lstinline|fun removeHashTab (t, k)|}{Removes a binding for the key "\lstinline|k|" from hash table "\lstinline|t|" and returns a new hash table.
\descr{\lstinline|fun flatten (l)|}{Flattens a list of lists into a regular list. The order of elements is preserved in both senses.}
\descr{\lstinline|fun deepFlatten (l)|}{Flattens an arbitrary nesting of lists of \emph{boxed} values into a regular list. The order of elements is preserved in both senses.}
\descr{\lstinline|fun emptyBuffer ()|}{Creates an empty buffer.}
\descr{\lstinline|fun singletonBuffer (x)|}{Creates a buffer from a single element.}
\descr{\lstinline|fun listBuffer (x)|}{Creates a buffer from a list.}
\descr{\lstinline|fun getBuffer (buf)|}{Gets the contents of a buffer as a list.}
\descr{\lstinline|fun addBuffer (buf, x)|}{Adds an element \lstinline|x| to the end of buffer \lstinline|buf| and returns the updated buffer. The buffer \lstinline|buf| can be updated in-place.}
\descr{\lstinline|fun concatBuffer (buf, x)|}{Adds buffer \lstinline|x| to the end of buffer \lstinline|buf| and returns the updated buffer. The buffer \lstinline|buf| can be updated in-place.}
\descr{\lstinline|infixl <+> before + (b1, b2)|}{Infix synonym for \lstinline|concatBuffer|.}
\descr{\lstinline|infix <+ at <+> (b, x)|}{Infix synonym for \lstinline|addBuffer|.}
\descr{\lstinline|fun matchString (m, s)|}{Tests if a matcher "\lstinline|m|" at current position matches the string "\lstinline|s|".
Return value represents parsing result as per "\lstinline|Ostap|".}
\descr{\lstinline|fun matchRegexp (m, r)|}{Tests if a matcher "\lstinline|m|" at current position matches the regular expression "\lstinline|r|", which
has to be constructed using the function "\lstinline|createRegexp|". Return value represents parsing result as per "\lstinline|Ostap|".}
Unit "\lstinline|Ostap|" implements monadic parser combinators in continuation-passing style with memoization~\cite{MonPC,MemoParsing,Meerkat}.
A parser is a function of the shape
\begin{lstlisting}
fun (k) {
fun (s) {...}
}
\end{lstlisting}
where "\lstinline|k|"~--- a \emph{continuation}, "\lstinline|s|"~--- an input stream. A parser returns either "\lstinline|Succ (v, s)|", where "\lstinline|v|"~--- some value,
representing the result of parsing, "\lstinline|s|"~--- residual input stream, or "\lstinline|Fail (err, line, col)|", where "\lstinline|err|"~--- a string, describing
a parser error, "\lstinline|line|", "\lstinline|col|"~--- line and column at which the error was encountered.
The unit describes some primitive parsers and combinators which allow to construct new parsers from existing ones.
\descr{\lstinline|fun initOstap ()|}{Clears and initializes the internal memoization tables. Called implicitly at unit initiliation time.}
\descr{\lstinline|fun memo (f)|}{Takes a parser "\lstinline|a|" and returns its memoized version. Needed for some parsers (for expamle, left-recursive ones).}
\descr{\lstinline|fun token (x)|}{Takes a string or a representation of regular expression, returned by "\lstinline|createRegexp|" (see unit \texttt{Matcher}),
and returns a parser which recognizes exactly this string/regular expression.}
\descr{\lstinline|fun alt (a, b)|}{A parser combinator which constructs a parser alternating between "\lstinline|a|" and "\lstinline|b|".}
\descr{\lstinline|fun seq (a, b)|}{A parser combinator which construct a sequential composition of "\lstinline|a|" and "\lstinline|b|". While
"\lstinline|a|" is a reqular parser, "\lstinline|b|" is a \emph{function} which takes the result of parsing by "\lstinline|a|" and
returns a parser (\emph{monadicity}).}
\descr{\lstinline|infixr \| before !! (a, b)|}{Infix synonym for "\lstinline|alt|".}
\descr{\lstinline|infixr \|> after \| (a, b)|}{Infix synonym for "\lstinline|seq|".}
\descr{\lstinline|infix @ at * (a, f)|}{An operation which attaches a semantics action "\lstinline|f|" to a parser "\lstinline|a|". Returns a
parser which behaves exactly as "\lstinline|a|", but additionally applies "\lstinline|f|" to the result if the parsing is succesfull.}
\descr{\lstinline|fun lift (f)|}{Lifts "\lstinline|f|" into a function which ignores its argument.}
\descr{\lstinline|fun bypass (f)|}{Convert "\lstinline|f|" into a function which parser with "\lstinline|f|" but returns its argument.
Literally, "\lstinline|bypass (f) = fun (x) {f @ lift (x)}|"}
\descr{\lstinline|fun opt (a)|}{For a parser "\lstinline|a|" returns a parser which parser either "\lstinline|a|" of empty string.}
\descr{\lstinline|fun rep0 (a)|}{For a parser "\lstinline|a|" returns a parser which parser a zero or more repetitions of "\lstinline|a|"}
\descr{\lstinline|fun rep (a)|}{For a parser "\lstinline|a|" returns a parser which parser a one or more repetitions of "\lstinline|a|"}
\descr{\lstinline|fun listBy (item, sep)|}{Constructs a parser which parses a non-empty list of "\lstinline|item|" delimited by "\lstinline|sep|".}
\descr{\lstinline|fun list0By (item, sep)|}{Constructs a parser which parses a possibly empty list of "\lstinline|item|" delimited by "\lstinline|sep|".}
\descr{\lstinline|fun list (item)|}{Constructs a parser which parses a non-empty list of "\lstinline|item|" delimited by ",".}
\descr{\lstinline|fun list0 (item)|}{Constructs a parser which parses a possibly empty list of "\lstinline|item|" delimited by ",".}
\descr{\lstinline|fun parse (p, m)|}{Parsers a matcher "\lstinline|m|" with a parser "\lstinline|p|". Returns ether "\lstinline|Succ (v)|" where
"\lstinline|v|"~--- a parsed value, or "\lstinline|Fail (err, line, col)|", where "\lstinline|err|"~--- a stirng describing parse error, "\lstinline|line|",
"\lstinline|col|"~--- this error's coordinates. This function may fail if detects the ambiguity of parsing.}
\descr{\lstinline|fun parseString (p, s)|}{Parsers a string "\lstinline|s|" with a parser "\lstinline|p|". Returns ether "\lstinline|Succ (v)|" where
"\lstinline|v|"~--- a parsed value, or "\lstinline|Fail (err, line, col)|", where "\lstinline|err|"~--- a stirng describing parse error, "\lstinline|line|",
"\lstinline|col|"~--- this error's coordinates. This function may fail if detects the ambiguity of parsing.}
a list of infix operator descriptors. Each element of the list describes one \emph{precedence level} with precedence increasing from head to tail. A descriptor on
each level is a pair, where the first element describes the associativity at the given level ("\lstinline|Left|", "\lstinline|Right|" or "\lstinline|Nona|") and
the second element is a list of pairs~--- a parser for an infix operator and the semantics action (a three-argument function accepting the left parser operand, that that
infix operator parser returns, and the right operand). For example,
