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 coöperate 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.

    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

       register_xs_parse_sublike(keyword, &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".

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>