BaseRainterpreterSubParserNPE2

Inherits: ERC165, ISubParserV1

Base implementation of ISubParserV1. Inherit from this contract and override the virtual functions to align all the relevant pointers and metadata bytes so that it can actually run. The basic workflow for subparsing via this contract is:

The main parser will call subParse with the subparser's compatibility version and the data to parse.
The subparser will check the compatibility is an exact match and revert if not. This is the simplest and most conservative approach, if there's a new compatibility version, a new version of the subparser will need to be deployed even if the upstream changes are backwards compatible.
The subparser will then parse the data, using the subParserParseMeta function to get the metadata bytes, which must be overridden by the child contract in order to be useful. The sub parser meta bytes are constructed exactly the same as the main parser meta bytes, so the same types and libs can be used to build them. The key difference is that the index of each word in the authoring meta maps to a parser function pointer, rather than a handler function pointer. What this means is that the function at index N of subParserFunctionPointers is responsible for parsing whatever data the main parser has passed to subParse into whatever the final output of the subparser is. For example, the 5th parser function might convert some word string "foo" into the bytecode that represents an extern call on the main interpreter into the contract that provides that extern logic. This decoupling allows any subparser function to generate any runtime behaviour at all, provided it knows how to construct the opcode for it.
Currently the subparse handles literals and operands in the same way as the main parser, but this may change in future. Likely that there will be dedicated "sub literal" and "sub word" concepts, that should be more composable than the current approach.
The final result of the subparser is returned as a tuple of success, bytecode and constants. The success flag is used to indicate whether the subparser was able to parse the data, and the bytecode and constants are the same as the main parser, and are used to construct the final bytecode of the main parser. The expectation on failure is that there may be some other subparser that can parse the data, so the main parser will handle fallback logic.

Functions

subParserParseMeta

Overrideable function to allow implementations to define their parse meta bytes.

function subParserParseMeta() internal pure virtual returns (bytes memory);

subParserFunctionPointers

Overrideable function to allow implementations to define their function pointers to each sub parser.

function subParserFunctionPointers() internal pure virtual returns (bytes memory);

subParserOperandHandlers

Overrideable function to allow implementations to define their operand handlers.

function subParserOperandHandlers() internal pure virtual returns (bytes memory);

subParserLiteralParsers

Overrideable function to allow implementations to define their literal parsers.

function subParserLiteralParsers() internal pure virtual returns (bytes memory);

subParserCompatibility

Overrideable function to allow implementations to define their compatibility version.

function subParserCompatibility() internal pure virtual returns (bytes32);

subParse

A basic implementation of sub parsing that uses encoded function pointers to dispatch everything necessary in O(1) and allows for the child contract to override all relevant functions with some modest boilerplate. This is virtual but the expectation is that it generally DOES NOT need to be overridden, as the function pointers and metadata bytes are all that need to be changed to implement a new subparser.

function subParse(bytes32 compatibility, bytes memory data)
    external
    pure
    virtual
    returns (bool success, bytes memory bytecode, uint256[] memory constants);

Parameters

Name	Type	Description
`compatibility`	`bytes32`	The compatibility version of the data to parse. The sub parser is free to handle this however it likes, but it MUST revert if it is unsure how to handle the data. E.g. the sub parser MAY revert any compatibility version that is not an exact match to a singular known constant, or it may attempt to support several versions.
`data`	`bytes`	The data to parse. The main parser will provide arbitrary data that is expected to match the conventions implied by the compatibility version. As sub parsing is a read only operation, any corrupt data could only possibly harm the main parser, which in turn should be parsing as a read only operation to protect itself from malicious inputs.

Returns

Name	Type	Description
`success`	`bool`	The first return value is a success flag, yet the sub parser MAY REVERT under certain conditions. It is important to know when to revert and when to return false. The general rule is that if the inputs are understood by the subparser, and look wrong to the subparser, then the subparser MUST revert. If the inputs are not understood by the subparser, it MUST NOT revert, as it is not in a position to know if the inputs are wrong or not, and there is very likely some other subparser known to the main parser that can handle the data as a fallback. For example, the following situations are expected to revert: - The compatibility ID is not supported by the sub parser. Every sub parser knows what it is compatible with, so it is safe to revert anything incompatible. - The data parses to something the sub parser knows how to handle, but the data is malformed in some way. For example, the sub parser knows the word it is parsing, but perhaps some associated data such as the constants height is out of a valid range. Similarly, the following situations are expected to return false and not revert: - The compatibility ID is supported by the sub parser, and the data appears to have the correct structure, but there are no recognized words in the data. This MUST NOT revert, as some other sub parser MAY recognize the word and handle it as a fallback.
`bytecode`	`bytes`	If successful, the second return value is the bytecode that the subparser has generated. The main parser is expected to merge this into the main bytecode as-is, so it MUST match main parser behaviour as per the compatibility conventions. If unsuccessful, a zero length byte array.
`constants`	`uint256[]`	If successful, and the generated bytecode implies additions to the constants array, the third return value is the constants that the subparser has generated. The main parser is expected to merge this into the main constants array as-is. If the parsing is unsuccessful, or the generated bytecode does not require any new constants, a zero length array.

supportsInterface

See {IERC165-supportsInterface}.

function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool);