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 highly experimental, consisting currently of pieces
    of code extracted and refactored from Future::AsyncAwait and
    Object::Pad. It is hoped eventually this will be useful for other
    modules too, as well as providing a potential mechanism by which
    multiple of these kinds of modules can coperate when parsing the same
    file, and combine their effects. As yet this part of the mechanism does
    not exist.

XS FUNCTIONS

 boot_xs_parse_sublike

       boot_xs_parse_sublike()

    Call this function from your BOOT section in order to initialise the
    module and parsing hooks.

 xs_parse_sublike

       int result = xs_parse_sublike(&hooks, 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.

    hooks should be a structure that can provide optional function pointers
    used to customise the parsing process at various stages. The structure
    should be declared using the following:

       struct XSParseSublikeHooks hooks = { 0 };

PARSE HOOKS

    The XSParseSublikeHooks structure provides the following hook stages,
    in the given order:

 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>

