hwtest.parsers

The type of a Parser that, when given a Src (essentially an iterator through text), consumes characters to produce a value of type T.

Every Parser should begin by discarding any leading whitespace.

Returns a new parser built from the given parser and function.

When run, the new parser runs the given parser and transforms its result using the function. The transformed result is then returned as the result of the new parser.

chain also comes in versions that are given up to six parsers instead of one, together with a function that transforms the combined results of the given parsers.

Notice that the given parser (pa) is a delayed (by-name) parameter, which allows chain to be used in recursive definitions. For example, consider

 def pNat: Int =
   choose(
     'S' -> chain(pNat, _+1),
     'Z' -> const(0)
   )

Without the by-name parameter in chain, pNat would always fall into infinite recursion.

Like chain[A,T] but takes two parsers and a function.

Like chain[A,T] but takes three parsers and a function.

Like chain[A,T] but takes four parsers and a function.

Like chain[A,T] but takes five parsers and a function.

Like chain[A,T] but takes six parsers and a function.

Returns a Parser that, when run, uses the next non-whitespace character (the "tag") to decide which of several parsers to run next.

Example: Parse an Either[Int, Int].

 def pEitherIntInt: Parser[Either[Int, Int]] =
   choose(
     'L' -> chain(rInt, Left(_)),
     'R' -> chain(rInt, Right(_))
   )

This would parse L 5 as Left(5) and R -99 as Right(-99). Whitespace can be omitted between the tag and the subsequent value, so R-99 would also be parsed Right(-99). (This is one of the very few places where whitespace can be omitted.)

WARNINGS:

• Tags are case sensitive.
• All tags within a single choose should be distinct.
• Tags should not be whitespace characters.
• Do NOT use $ as a tag, because it has special meaning in the tester as marking the end of a test.

Returns a Parser that produces v without consuming any characters from src.

Wraps a function (like _.toInt) that converts a String to another type, but that might throw an exception, into one that will do the same conversion but will call call parseError instead.

Returns a Parser for a Array of As.

The test data is formatted as

 (<element1> <element2> ... <elementN>)

A parser for BigInts.

Throws an exception if the next token cannot be converted to a BigInt, or if there is no next token.

Returns the next Boolean from the source.

In the test data, the Boolean should be formatted as F or T.

Reads a collection of As.

Many built-in collections, such as list, arrays, sets, and maps, will be formatted in the test data as

 (element1 element2 ... elementN)

instead of using Polish notation.

An empty collection is written as

 ()

pColl will use pa to read each element, save them all in a list, and then call convert on the list of all the just-read elements to produce the final result. Usually, that result will be some kind of collection, such as a list or array or set, but convert has the flexibility to return other types as well.

A parser for Doubles.

Throws an exception if the next token cannot be converted to a Double, or if there is no next token.

A parser for Ints.

Throws an exception if the next token cannot be converted to an Int, or if there is no next token.

Returns a Parser for a List of As.

The test data is formatted as

 (<element1> <element2> ... <elementN>)

A parser for Longs.

Throws an exception if the next token cannot be converted to a Long, or if there is no next token.

Returns a Parser for an immutable Map of keys (K) and values (V).

The test data is formatted as

 (<key1> <value1> <key2> <value2> ... <keyN> <valueN>)

Note that there are NOT extra parentheses around each individual key-value pair.

Warning: The parser makes no effort to check for equivalent keys. The creator of the test data should avoid including two keys in the same set if they might be considered equivalent.

Returns the next Option[A] from the source.

In the test data, the Option[A] should be formatted as 'N' or S <data>. The latter can also be written as S<data> (without the space).

Returns a Parser for an immutable Set of As.

The test data is formatted as

 (<element1> <element2> ... <elementN>)

Warning: The parser makes no effort to check for equivalent elements. The creator of the test data should avoid including two elements in the same set if they might be considered equivalent.

Generic parser for binary trees with data at internal nodes but no data at external nodes.

When called, the parser reads trees formatted as

• E for the empty tree
• T <data> <left-subtree> <right-subtree> for a node with data
• L <data> for a node with data and two empty subtrees Note that L <data> is merely shorthand for T <data> E E. It is mainly useful when generating test data by hand. If you are generating test data programmatically, just use E and T.

Whitespace is optional after the tag so T <data> E E could also be written as T<data> E E.

Example:

 enum SizedBST:
   case Empty
   case Node(left: SizedBST, item: Int, right: SizedBST, size: Int)

 def pSizedBST: SizedBST =
   pTree(pTuple(pInt,pInt),
         Empty,
         (tup,left,right) => Node(left, tup._1, right, tup._2))

Then the tree Node(Empty, 10, Node(Empty, 20, Empty, 1), 2) could be formatted in a test as

 T10 2 E T20 1 E E

or

 T 10 2 E L 20 1

Although T is normally some type of tree, it is also possible to use pTree on tree-like input data, even if the final result is not itself a tree.

Returns a parser for a 2-tuple of values.

The test data is formatted as

 <element1> <element2>

Note that the test data does NOT include parentheses around the elements.

Returns a parser for a 3-tuple of values.

The test data is formatted as

 <element1> <element2> <element3>

Note that the test data does NOT include parentheses around the elements.

Returns a parser for a 4-tuple of values.

The test data is formatted as

 <element1> <element2> <element3> <element4>

Note that the test data does NOT include parentheses around the elements.

Returns a parser for a 5-tuple of values.

The test data is formatted as

 <element1> <element2> <element3> <element4> <element5>

Note that the test data does NOT include parentheses around the elements.

Returns a parser for a 6-tuple of values.

The test data is formatted as

 <element1> <element2> <element3> <element4> <element5> <element6>

Note that the test data does NOT include parentheses around the elements.

Prints an error message (extended with some hints), and halts the program.

Reads the next chunk of simple text from the source, where "simple" means letters, digits, -, +, and ..

Stops at the first non-simple character, which might or might not be whitespace, or at the end of the source. For example, if the source was

 __-123.4) ...

where the __ represents whitespace, token would skip the whitespace, and return the -123.4, leaving the ) still in the source.

Throws a ParseError if the chunk is empty.