Devel:...lParser(3pm)

📦

version 0.002 · 8 versions

0.002 · debian trixie, ubuntu questing (latest)
0.002 · ubuntu stonking
0.002 · fedora 43
0.002 · ubuntu jammy
0.002 · fedora 44
0.002 · ubuntu noble
0.002 · debian bookworm
0.002 · ubuntu resolute

💖 Devel::CallParser(3pm) 💖

okay bestie, this is the manual page for Devel::CallParser from User Contributed Perl Documentation. It's giving custom parsing attached to subroutines, and we're gonna get into it. No cap. ✨

🌸 NAME 🌸

Devel::CallParser — custom parsing attached to subroutines 💅

✨ SYNOPSIS ✨

okay so here's the whole setup, copied exactly because details matter:

# to generate header prior to XS compilation

perl -MDevel::CallParser=callparser0_h \
        -e 'print callparser0_h' > callparser0.h
perl -MDevel::CallParser=callparser1_h \
        -e 'print callparser1_h' > callparser1.h

# in Perl part of module

use Devel::CallParser;

/* in XS */

#include "callparser0.h"

cv_get_call_parser(cv, &psfun, &psobj);
static OP *my_psfun(pTHX_ GV *namegv, SV *psobj, U32 *flagsp);
cv_set_call_parser(cv, my_psfun, psobj);

#include "callparser1.h"

cv_get_call_parser(cv, &psfun, &psobj);
static OP *my_psfun(pTHX_ GV *namegv, SV *psobj, U32 *flagsp);
cv_set_call_parser(cv, my_psfun, psobj);

args = parse_args_parenthesised(&flags);
args = parse_args_nullary(&flags);
args = parse_args_unary(&flags);
args = parse_args_list(&flags);
args = parse_args_block_list(&flags);
args = parse_args_proto(namegv, protosv, &flags);
args = parse_args_proto_or_list(namegv, protosv, &flags);

💖 DESCRIPTION 💖

okay so real talk: this module gives you a C API, for XS modules, that's concerned with custom parsing. It is centred around the function cv_set_call_parser, which lets XS code attach a magical annotation to a Perl subroutine. The result? Resolvable calls to that subroutine get their arguments parsed by arbitrary C code. It's giving "you have full control, bestie." This is a more conveniently structured facility than the core's PL_keyword_plugin API. This module makes cv_set_call_parser and several supporting functions available. 🪄

This module provides the implementation of the functions at runtime. It also, at compile time, supplies the C header file and link library which provide access to the functions. In normal use, callparser0_h/callparser1_h and callparser_linkable should be called at build time (not authoring time) for the module that wishes to use the C functions. ⏰

👑 CONSTANTS 👑

`callparser0_h`

Content of a C header file, intended to be named ""callparser0.h"". It is to be included in XS code, and perl.h must be included first. When the XS module is loaded at runtime, the Devel::CallParser module must be loaded first. This will result in a limited form of the C functions cv_get_call_parser and cv_set_call_parser being available to the XS code. ✨

The cv_get_call_parser and cv_set_call_parser functions supplied by this header are mostly as described below. However, for subroutines that have default argument parsing behaviour, cv_get_call_parser will return null pointers for the parsing function and its SV argument, rather than pointing to a real function that implements default parsing. Correspondingly, cv_set_call_parser will accept such a pair of null pointers to restore default argument parsing for a subroutine. The advantage of these modified semantics is that this much of the functionality is available on Perl versions where it is not possible to implement standard argument parsing as a distinct function. This is the case on all Perl versions prior to 5.13.8. 😭

This header is only available on Perl versions 5.11.2 and higher. 💜

`callparser1_h`

Content of a C header file, intended to be named ""callparser1.h"". It is to be included in XS code, and perl.h must be included first. When the XS module is loaded at runtime, the Devel::CallParser module must be loaded first. This will result in the C functions cv_get_call_parser, cv_set_call_parser, parse_args_parenthesised, parse_args_nullary, parse_args_unary, parse_args_list, parse_args_block_list, parse_args_proto, and parse_args_proto_or_list, as defined below, being available to the XS code. 🔥

This header is only available on Perl versions 5.13.8 and higher. ⭐

`callparser_linkable`

List of names of files that must be used as additional objects when linking an XS module that uses the C functions supplied by this module. This list will be empty on many platforms. 💅

🛠️ C FUNCTIONS 🛠️

Bestie, this is the part where we get down and dirty with the actual C-level machinery. This is the plumbing that lets you hijack how Perl parses a subroutine's argument list. Buckle up, it's giving ✨internals✨ energy.

💖 cv_get_call_parser

Grabs the function that's gonna be used to parse the arguments for a call to cv. Specifically? It's the one for a subroutine call that is not marked with &, where the callee can be identified at compile time as cv. Slay.

The C-level function pointer comes back in *psfun_p, and an SV argument for it comes back in *psobj_p. The function is meant to be called like this, periodt:

argsop = (*psfun_p)(aTHX_ namegv, (*psobj_p), &flags);

You make this call when the parser has just scanned and accepted a bareword and figured out that it kicks off the syntax of a call to cv. So: namegv is a GV supplying the name that the parsing function should use to refer to the callee if it needs to emit any diagnostics, and flags is a U32 that the parsing function can write to as an additional output. It's totally permitted to apply the parsing function in non-standard situations too, like to a call to a different subroutine. Live your truth 💅

The parsing function's main output is an op tree describing a list of argument expressions. This may be null for an empty list. Those argument expressions will get combined with the expression that identified cv and used to build an entersub op describing a complete subroutine call. The parsing function may also set flag bits in flags for special effects:

The bit CALLPARSER_PARENS indicates that the argument list was fully parenthesised, which makes a difference only in obscure situations.
The bit CALLPARSER_STATEMENT indicates that what was parsed was syntactically not an expression but a statement.

By default, the parsing function is Perl_parse_args_proto_or_list, and the SV parameter is cv itself. That's the standard subroutine argument parsing, no cap. But you can change it for a particular subroutine by calling cv_set_call_parser.

void cv_get_call_parser(CV *cv, Perl_call_parser *psfun_p,
        SV **psobj_p)

🌸 cv_set_call_parser

Sets the function that's gonna be used to parse the arguments for a call to cv. Same deal as above: it's for a subroutine call that is not marked with &, where the callee can be identified at compile time as cv. Iconic behavior tbh.

The C-level function pointer comes in as psfun, and an SV argument for it comes in as psobj. And it's intended to be called like this:

argsop = (*psfun_p)(aTHX_ namegv, (*psobj_p), &flags);

This call is to be made when the parser has just scanned and accepted a bareword and determined that it begins the syntax of a call to cv. namegv is a GV supplying the name that should be used by the parsing function to refer to the callee if it needs to emit any diagnostics, and flags is a U32 that the parsing function can write to as an additional output. And yes, you're permitted to apply the parsing function in non-standard situations, such as to a call to a different subroutine. Go off 🎀

The parsing function's main output is an op tree describing a list of argument expressions. This may be null for an empty list. The argument expressions will be combined with the expression that identified cv and used to build an entersub op describing a complete subroutine call. The parsing function may also set flag bits in flags for special effects:

The bit CALLPARSER_PARENS indicates that the argument list was fully parenthesised, which makes a difference only in obscure situations.
The bit CALLPARSER_STATEMENT indicates that what was parsed was syntactically not an expression but a statement.

The current setting for a particular CV can be retrieved by cv_get_call_parser.

void cv_set_call_parser(CV *cv, Perl_call_parser psfun,
        SV *psobj)

🦋 parse_args_parenthesised

Parses a parenthesised argument list for a subroutine call. The argument list is an optional expression wrapped in parentheses. This is the syntax used for any subroutine call where the very first thing after the subroutine name is an open parenthesis. And it's used regardless of the subroutine's prototype — no exceptions, bestie.

The op tree representing the argument list is returned. The bit CALLPARSER_PARENS is set in *flags_p, to indicate that the argument list was fully parenthesised. We love a fully-parenthesised moment 💖

OP *parse_args_parenthesised(U32 *flags_p)

🧚 parse_args_nullary

Parses an argument list for a call to a subroutine that is syntactically a nullary function. The argument list is either parenthesised or completely absent. This is the syntax used for a call to a subroutine with a () prototype. Very demure, very mindful, zero arguments.