Parser API

Table of Contents

Include this API as

#include <wtk/Parser.h>

Members of this API live in the following namespace

namespace wtk { ...

The Parser API is parameterized on a Number_T template. Number_T should be integer-like enough to be parsed from a string. This API is abstract and implemented by parsers for various IR formats.

template<typename Number_T> struct Parser

The Parser will read the IR’s front matter before delegating to an wtk::ArithmeticParser<Number_T> or a wtk::BooleanParser.

The struct’s public data members are set to default values (mostly 0) at construction and assigned concrete values as parse methods are invoked. The parser methods are expected to be called in the correct order (parseHeader(), parseResource(), and finally for relations only parseParameters()). A helper for calling them in the correct order is provided as parseHdrResParams().

When the front-matter has been parsed, one of arithmetic(), arithmetic64(), arithmetic32(), or boolean() may be invoked to delegate parsing the body to either of wtk::ArithemticParser<…​> or wtk::BooleanParser.

bool parseHeader()

Parses the resources header section setting the following attributes.

Returns true on success, false if a parse error occurs.

virtual bool parseHeader() = 0;

bool parseResource()

Parses the resource type and sets the wtk::Resource resource attribute.

Returns true on success, false if a parse error occurs.

virtual bool parseResource() = 0;

bool parseParameters()

Parses the relation’s parameters and sets the following attributes.

Returns true on success, false if a parse error occurs.

WARNING

parseParameters() should only be used if resource == wtk::Resource::relation.

virtual bool parseParameters() = 0;

bool parseHdrResParams()

This is a helper to call parseHeader(), parseResource(), and, if necessary, parseParameters() in sequence.

Returns true on success, false if a parse error occurs.

virtual bool parseHdrResParams() = 0;

struct { …​ } version

The version is the first line of an IR resource. Although WizToolKit tends to be tied to a particular IR version, the Parser does not make any checks for the particular IR version.

The version consists of major, minor, and patch elements, all of type size_t.

struct {
  size_t major = 0;
  size_t minor = 0;
  size_t patch = 0;
} version;

Number_T characteristic

The field’s prime modulus or "characteristic". The parser does not check for primality.

Number_T characteristic = Number_T(0);

size_t degree

The field’s degree. The IR requires this to be 1, although the parser does not test this.

size_t degree = 0;

wtk::Resource resource

The resource type which is currently being parsed. This has type wtk::Resource.

wtk::Resource resource = Resource::invalid;

wtk::GateSet gateSet

The set of gates to be allowed within the relation. This has type wtk::GateSet.

WARNING

gateSet may only be used if resource == wtk::Resource::relation.

wtk::GateSet gateSet;

wtk::FeatureToggles featureToggles

The IR structural features to be allowed within the relation. This has type wtk::FeatureToggles.

WARNING

featureToggles may only be used if resource == wtk::Resource::relation.

wtk::FeatureToggles featureToggles;

wtk::ArithemticParser<Number_T>* arithmetic()

This method returns a delegate parser for an arithmetic resource.

WARNING

When parsing a relation, use of an arithmetic parser for parsing a non-arithmetic gateset will result in parse errors.

void wtk::ArithmeticParser<Number_T>*  arithmetic() = 0;

wtk::ArithemticParser<uint64_t>* arithmetic()

This method returns a delegate parser for an arithmetic resource. However the Number_T template is downgraded to a uint64_t.

WARNING

When parsing a relation, use of an arithmetic parser for parsing a non-arithmetic gateset will result in parse errors.

void wtk::ArithmeticParser<uint64_t>*  arithmetic64() = 0;

wtk::ArithemticParser<uint32_t>* arithmetic()

This method returns a delegate parser for an arithmetic resource. However the Number_T template is downgraded to a uint32_t.

WARNING

When parsing a relation, use of an arithmetic parser for parsing a non-arithmetic gateset will result in parse errors.

void wtk::ArithmeticParser<uint32_t>*  arithmetic32() = 0;

wtk::BooleanParser* boolean()

This method returns a delegate parser for a boolean resource.

NOTE

The Number_T template is removed for wtk::BooleanParser, and uint8_t is always used in its place.

WARNING

When parsing a relation, use of a boolean parser for parsing a non-boolean gateset will result in parse errors.

void wtk::BooleanParser*  boolean() = 0;

template<typename Number_T> struct ArithmeticParser

This is a delegate parser for the body of an arithmetic IR resource. Its interface is substantially similar to wtk::BooleanParser. In general, this type should not be constructed, but rather obtained from parser.arithmetic().

bool parseStream(wtk::ArithmeticStreamHandler<Number_T>* handler)

Parses the body of an arithmetic IR-Simple relation, passing each gate off to the handler in a streaming fashion. The parser.resource must be wtk::Resource::relation.

The handler parameter must be nonnull. The method returns false on failure, including if either the parser.gateSet or parser.featureToggles are violated. It does not make any other well-formedness checks.

virtual bool parseStream(wtk::ArithmeticStreamHandler<Number_T>* handler) = 0;

wtk:IRTree<Number_T> parseTree()

Parses the body of any arithmetic relation, constructing a syntax tree. The parser.resource must be wtk::Resource::relation. If a parse failure occurs, nullptr is returned, including if either the parser.gateSet or parser.featureToggles are violated. It does not make any other well-formedness checks.

virtual wtk::IRTree<Number_T>* parseTree() = 0;

wtk::InputStream<Number_T>* instance()

Returns an wtk::InputStream<Number_T>* which will parse the instance one value at a time. The parser.resource must be wtk::Resource::instance.

This method will never return nullptr, instead returned wtk::InputStream<Number_T>* will return wtk::StreamStatus::error as necessary.

virtual wtk::InputStream<Number_T>* instance() = 0;

wtk::InputStream<Number_T>* shortWitness()

Returns an wtk::InputStream<Number_T>* which will parse the short witness one value at a time. The parser.resource must be wtk::Resource::shortWitness.

This method will never return nullptr, instead returned wtk::InputStream<Number_T>* will return wtk::StreamStatus::error as necessary.

virtual wtk::InputStream<Number_T>* shortWitness() = 0;

struct BooleanParser

This is a delegate parser for the body of an boolean IR resource. Its interface is substantially similar to wtk::ArithmeticParser<Number_T>. In general, this type should not be constructed, but rather obtained from parser.boolean(). Note that this struct is not parameterized by Number_T. Instead anywhere the a field/numeric literal would be expected, uint8_t is used instead.

bool parseStream(wtk::BooleanStreamHandler* handler)

Parses the body of an boolean IR-Simple relation, passing each gate off to the handler in a streaming fashion. The parser.resource must be wtk::Resource::relation.

The handler parameter must be nonnull. The method returns false on failure, including if either the parser.gateSet or parser.featureToggles are violated. It does not make any other well-formedness checks.

virtual bool parseStream(wtk::BooleanStreamHandler* handler) = 0;

wtk:IRTree<uint8_t> parseTree()

Parses the body of any arithmetic relation, constructing a syntax tree. The parser.resource must be wtk::Resource::relation. If a parse failure occurs, nullptr is returned, including if either the parser.gateSet or parser.featureToggles are violated. It does not make any other well-formedness checks.

virtual wtk::IRTree<uint8_t>* parseTree() = 0;

wtk::InputStream<uint8_t>* instance()

Returns an wtk::InputStream<uint8_t>* which will parse the instance one value at a time. The parser.resource must be wtk::Resource::instance.

This method will never return nullptr, instead returned wtk::InputStream<Number_T>* will return wtk::StreamStatus::error as necessary.

virtual wtk::InputStream<uint8_t>* instance() = 0;

wtk::InputStream<uint8_t>* shortWitness()

Returns an wtk::InputStream<uint8_t>* which will parse the short witness one value at a time. The parser.resource must be wtk::Resource::shortWitness.

This method will never return nullptr, instead returned wtk::InputStream<Number_T>* will return wtk::StreamStatus::error as necessary.

virtual wtk::InputStream<uint8_t>* shortWitness() = 0;

template<typename Number_T> struct InputStream

The InputStream represents either an instance or a short witness, and and allows the user to consume one value at a time from the stream. Do not attempt to construct one manually. Instead retrieve one from arithmeticParser.instance(), arithmeticParser.shortWitness(), booleanParser.instance(), or booleanParser.shortWitness().

StreamStatus next(Number_T* num)

Consumes a single value from the stream, placing it in the num parameter. This operation may fail if a parse error or the end of file is reached, returning an wtk::StreamStatus error code.

virtual StreamStatus next(Number_T* num) = 0;

size_t lineNum()

If the parser supports line numbering, then this method returns the line number corresponding to the prior invocation of this→next(…​). If line numbering is not supported then 0 is returned.

If this→next(…​) has not been called, it returned wtk::StreamStatus::end, or it returned wtk::StreamStatus::error then this→lineNum() may return any of 0, the line number on which the error or end occurred, or the line number of the most recent successful call to this→next(…​).

virtual size_t lineNum();

enum StreamStatus

This enumeration indicates the success or means of failure for an wtk::InputStream<Number_T>. It may take one of the following values.

wtk::StreamStatus::success

Successfully retrieved an item from the stream.

wtk::StreamStatus::end

Reached the end of the stream.

wtk::StreamStatus::error

A parse error occurred.