NAME
XS::Parse::Sublike - XS functions to assist in parsing sub-like syntax
DESCRIPTION
This module provides some XS functions to assist in writing parsers for sub-like syntax, primarily for authors of keyword plugins using the PL_keyword_plugin hook mechanism. It is unlikely to be of much use to anyone else; and highly unlikely to be any use when writing perl code using these. Unless you are writing a keyword plugin using XS, this module is not for you.
This module is also currently experimental, and the design is still evolving and subject to change. Later versions will likely break ABI compatibility, requiring changes to any module that depends on it.
It is hoped eventually this will be useful for other modules too.
XS FUNCTIONS
boot_xs_parse_sublike
void boot_xs_parse_sublike(double ver)Call this function from your BOOT section in order to initialise the module and parsing hooks.
ver should either be 0 or a decimal number for the module version requirement; e.g.
boot_xs_parse_sublike(0.04);xs_parse_sublike
int xs_parse_sublike(const struct XSParseSublikeHooks *hooks, OP **op_ptr)This function performs the actual parsing of a sub-like keyword. It expects the lexer to be at a position just after the introduction keyword has been consumed, and will proceed to parse an optional name, list of attributes, signature (if enabled by use feature 'signatures'), and code body. The return value and op_ptr can be used directly from the keyword plugin function. It is intended this function be invoked from it, and the result returned directly.
For a more automated handling of keywords, see "register_xs_parse_sublike".
hooks should be a structure that can provide optional function pointers used to customise the parsing process at various stages.
register_xs_parse_sublike
void register_xs_parse_sublike(const char *keyword,
const struct XSParseSublikeHooks *hooks)This function installs a set of parsing hooks to be associated with the given keyword. Such a keyword will then be handled automatically by a keyword parser installed by XS::Parse::Sublike itself.
When the keyword is encountered, the hook's permit function is first tested to see if the keyword is permitted at this point. If the function returns true then the keyword is consumed and parsed as per "xs_parse_sublike".
xs_parse_sublike_any
int xs_parse_sublike_any(const struct XSParseSublikeHooks *hooks, OP **op_ptr)This function expects to consume an introduction keyword at the lexer position which is either sub or the name of another sub-like keyword, which has been previously registered using "register_xs_parse_sublike". It then proceeds to parse the subsequent syntax similar to how it would have parsed if encountered by the module's own keyword parser plugin, except that the second set of hooks given here also take effect.
If a regular sub is encountered, then this is parsed using the hooks in a similar way to xs_parse_sublike().
If a different registered sub-like keyword is encountered, then parsing is performed using both sets of hooks - the ones given to this function as well as the ones registered with the keyword. This allows their effects to combined. The hooks given by the hooks argument are considered to be on the "outside" from those of the registered keyword "inside". The outside ones run first for all stages, except pre_blockend which runs them inside-out.
PARSE HOOKS
The XSParseSublikeHooks structure provides the following hook stages, in the given order:
permit
bool (*permit)(pTHX)Called by the installed keyword parser hook which is used to handle keywords registered by "register_xs_parse_sublike". This hook stage should inspect whether the keyword is permitted at this time (typically by inspecting the hints hash GvHV(PL_hintgv) for some imported key) and return true only if the keyword is permitted.
post_blockstart
void (*post_blockstart)(pTHX)Invoked after the optional name and list of attributes have been parsed and the block_start() function has been called. This hook stage may wish to perform any alterations of PL_compcv or related, inspect or alter the lexical pad, provide hints hash values, or any other tasks before the signature and code body are parsed.
pre_blockend
OP * (*pre_blockend)(pTHX_ OP *body)Invoked after the signature and body of the function have been parsed, just before the block_end() function is invoked. This hook is passed the optree as it has been parsed. The hook stage may wish to inspect or alter the optree, and should return it. The return value will then be passed to newATTRSUB().
post_newcv
void (*post_newcv)(pTHX_ CV *cv)Invoked just after newATTRSUB() has been invoked on the optree. The hook stage may wish to inspect or alter the CV.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>