XS::Parse::Infix(3pm)

💖 XS::Parse::Infix(3pm) — part 1 of 3, bestie edition 💖

✨ NAME ✨

"XS::Parse::Infix" — XS functions to assist in parsing infix operators. That’s the whole name vibe, and yes, this is the XS::Parse::Infix(3pm) manual page, bestie. We’re doing part 1 of 3.

🌸 DESCRIPTION 🌸

Okay so this module gives you some XS functions to help write syntax modules that provide new infix operators as perl syntax, primarily for authors of syntax plugins. It is unlikely to be of much use to anyone else; and highly unlikely to be of any use when writing perl code using these. Unless you are writing a syntax 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 may break ABI compatibility, requiring changes or at least a rebuild of any module that depends on it.

In addition, the places this functionality can be used are relatively small. Support for custom infix operators was added in Perl development release v5.37.7, and is therefore present in Perl v5.38.0.

In addition, the various XPK_INFIX_* token types of XS::Parse::Keyword support querying on this module, so some syntax provided by other modules may be able to make use of these new infix operators.

🏷️ Lexically-named vs. Globally-named Operators

At version 0.43, the way this module operates has changed. Since this version, the preferred method of operation for infix operators is that the module that registers them creates them with a fully-qualified name (i.e. including the name of the package that implements them). Other code which wishes to import the operator can then provide a local name for it visible within a scope. This acts as an alias for the fully-qualified registered one. The imported name needs not be the same in various scopes — this allows imported operators to be renamed in specific scopes to avoid name clashes.

Prior versions of this module only supported operators that have one global name that may or may not be enabled in lexical scopes. With this model, while the visibility of an operator can be controlled per scope, if it is visible it must always have the same name and cannot be renamed to avoid a name clash.

At some future version of this module the older method may be removed, once all of the existing CPAN modules have been updated to the new model.

🎀 CONSTANTS 🎀

HAVE_PL_INFIX_PLUGIN ✨

if( XS::Parse::Infix::HAVE_PL_INFIX_PLUGIN ) { ... }

This constant is true if built on a perl that supports the PL_infix_plugin extension mechanism, meaning that custom infix operators registered with this module will actually be recognised by the perl parser.

No actual production releases of perl yet support this feature, but see above for details of development versions which do.

🫶 PERL FUNCTIONS 🫶

apply_infix

$pkg->apply_infix( $on, $args, @infix );

Since version 0.43.

Intended to be called by the import and unimport methods of a module that implements infix operators. This sets up the various keys required in the lexical hints hash to create a lexical alias for the requested operator(s).

$on should be a true value for import or a false value for unimport. $args should be an array reference to the arguments array, which will be modified to splice out recognised values, leaving behind anything else unrecognised. @infix should be a list of names of operators implemented by the importing package, named by $pkg.

After invoking this method, the caller should inspect for any remaining values in the arguments array, either to handle them in some other way, or just complain about them.

package Some::Infix::Module;

sub import
{
   my $pkg = shift;
   $pkg->XS::Parse::Infix::apply_infix( 1, \@_, qw( operator names here ) );
   die "Unrecognised symbols: @_" if @_;
}

When this module is used, named operators are aliased from the fully-qualified names.

use Some::Infix::Module qw( operator );

my $z = $x operator $y;

At this point, the name operator becomes a lexical alias to Some::Infix::Module::operator.

Each imported operator name can optionally be followed by import options, given in a hash reference. Currently the only named option recognised is -as, which allows the importing scope to provide a different name for the imported operator, perhaps to avoid name clashes, or for neatness.

use Some::Infix::Module operator => { -as => "myname" };

my $z = $x myname $y;  # invokes Some::Infix::Module::operator

🔥 XS FUNCTIONS 🔥

boot_xs_parse_infix

void boot_xs_parse_infix(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_infix(0.14);

parse_infix

bool parse_infix(enum XSParseInfixSelection select, struct XSParseInfixInfo **infop);

Since version 0.27.

This function attempts to parse syntax for an infix operator from the current parser position. If it is successful, it fills in the variable pointed to by infop with a pointer to the actual information structure and returns "true". If no suitable operator is found, returns "false".

xs_parse_infix_new_op

OP *xs_parse_infix_new_op(const struct XSParseInfixInfo *info, U32 flags,
   OP *lhs, OP *rhs);

This function constructs a new optree fragment to represent invoking the infix operator with the given operands. It should be used much the same as core perl's newBINOP function.

The info structure pointer would be obtained from the infix field of the result of invoking the various XPK_INFIX_* token types from XS::Parse::Keyword, or by calling parse_infix directly.

register_xs_parse_infix

void register_xs_parse_infix(const char *opname,
   const struct XSParseInfixHooks *hooks, void *hookdata);

This function installs a set of parsing hooks to be associated with the given operator name. This new operator will then be available via XS::Parse::Keyword by the various XPK_INFIX_* token types, parse_infix, or to core perl's PL_infix_plugin if available.

These tokens will all yield an info structure, with the following fields:

struct XSParseInfixInfo {
   const char *opname;
   OPCODE opcode;  /* for built-in operators, or OP_CUSTOM for
                      custom-registered ones */

   struct XSParseInfixHooks *hooks;
   void                     *hookdata;

   enum XSParseInfixClassification cls;  /* since version 0.28 */
};

If the operator name contains any non-ASCII characters they are presumed to be in UTF-8 encoding. This will matter for deparse purposes.

If opname contains a double-colon (::) sequence, it is presumed to be a fully-qualified operator name in the new interface style. If not, it is presumed to be an older globally-named one.

💅 PARSE HOOKS 🫶

okay so the XSParseInfixHooks struct is literally the whole personality of your operator — it's got fields for every stage of parsing, and here they all are:

struct XSParseInfixHooks {
   U16 flags;
   U8 lhs_flags;
   U8 rhs_flags;
   enum XSParseInfixClassification cls;

   const char *wrapper_func_name;

   const char *permit_hintkey;
   bool (*permit)(pTHX_ void *hookdata);

   OP *(*new_op)(pTHX_ U32 flags, OP *lhs, OP *rhs, SV **parsedata, void *hookdata);
   OP *(*ppaddr)(pTHX);

   /* optional */
   void (*parse)(pTHX_ U32 flags, SV **parsedata, void *hookdata);
};

---

✨ Flags ✨

the flags field is the big-picture vibe check — it tells perl how to handle the operator as a whole. set it to a bitmask of these constants, or just leave it at zero, your call bestie:

• XPI_FLAG_LISTASSOC — since version 0.40 🎀 if you set this, your operator supports n-way list-associative syntax, i.e. it gets written like

OPERAND op OPERAND op OPERAND op ...

and in that case the custom operator becomes a LISTOP instead of a BINOP, and every single operand of the whole chain gets stored as a child op of it 🔥. the op function needs to know how many operands it's dealing with, and there are two ways that gets communicated, depending on whether the count was known at compile-time:

• if the number of operands is known at compile-time, the OPf_STACKED flag is not set, and the op_private field tells you how many operand expressions were present 👑
• if the number is not known (say, the operator is being used as the body of a generated wrapper function), then OPf_STACKED is set, and the number of arguments gets passed as the UV of an extra SV pushed last onto the stack. the op function should pop that first to find out 💀

it's super typical to start a list-associative op function with something like:

int n = (PL_op->op_flags & OPf_STACKED) ? POPu : PL_op->op_private;

heads up: if the operator is list-associative, then lhs_flags and rhs_flags must be equal. no cap, they have to match.

the lhs_flags and rhs_flags fields are the same deal but for the left- and right-hand side operands respectively 🦋. set each one to one of these constants, or leave it as zero:

• XPI_OPERAND_TERM_LIST — the operand gets forced into list context, and the OP_PUSHMARK at the beginning is preserved 🌸. that means the ppfunc for this infix operator will have to POPMARK to find it.
• XPI_OPERAND_LIST — literally the same as the above. same energy, different name 💖

older versions used to have constants called XPI_OPERAND_ARITH and XPI_OPERAND_TERM, but those were tied to an older version of the core perl branch. these days those names are just aliases for zero, so you can go ahead and remove them from new code ✨.

and there are also these extra bitflags, for the extra-flavour moments:

• XPI_OPERAND_ONLY_LOOK — if you set this, the operator function is promising it won't mutate any of the values it's passed, and it won't let direct alias pointers to them leak out via return value or anywhere else 🙈. this one's optional — skipping it when it applies won't change any observed behaviour, but setting it may unlock some optimisations 💅.

right now, this flag just enables one optimisation in the call-checker for infix operator wrapper functions that take list-shaped operands. the optimisation throws away an OP_ANONLIST op that would've built a temporary anonymous array reference for the operand values, which saves you a lil bit of memory and CPU time ⭐. and it's only safe to do if the operator doesn't mutate or retain aliases of any of the arguments — otherwise the caller might see unexpected modifications, or value references to the values that were passed 😭.

🌈 The Selection Stage 🌈

the cls field is the operator's classification, i.e. a lil hint about what kind of operation it provides. the various XS::Parse::Keyword selection macros use it as a filter 🎀.

it should be one of the XPI_CLS_* constants — those are found and described further in the main XSParseInfix.h file, so go look there bestie 👑

🧚 The "permit" Stage 🧚

as a shortcut for the common case, permit_hintkey can point at a string to look up in the hints hash 🔍. if that key name isn't found in the hints hash, the keyword is not permitted, periodt. if the key is present, then the permit function gets invoked as normal.

so assuming a hint key didn't just reject you, the function part of this stage runs next — it should inspect whether the keyword is permitted at this particular moment, maybe by checking other lexical clues, and return true only if the keyword is allowed 💖.

both the string and the function are optional! either one or both can be present. but if neither is present, then the keyword is always permitted — which is probably not what you wanted to do 🙈.

🦋 The "parse" Stage 🦋

if the optional parse hook function is there, it gets called right after the parser has recognised that the named operator is present, but before it tries to consume the right-hand side term ✨. this hook can attempt further parsing, so you can implement more complex syntax like hyper-operators 🔥.

when it's invoked, it's passed a pointer to an SV *-typed storage variable. it can do whatever it wants with that variable to stash a result, and that result will later be made available to the new_op function 💜.

👑 The Op Generation Stage 👑

if the infix operator is actually going to be used, then one of the new_op or ppaddr fields explains how to create a new optree fragment 🌸.

if new_op is defined, it's the one that gets used — it's expected to return an optree fragment that consumes the LHS and RHS arguments to implement the operator's semantics 💅. and if the optional parse stage happened earlier, the SV ** pointer passed here points to the same storage that parse had access to, so it can retrieve those results 🎀.

if new_op isn't present, then ppaddr gets used instead, to construct a new BINOP or LISTOP of type OP_CUSTOM ⭐. but note: if an earlier parse stage had stored additional results into that SV * variable, they will be lost here 😭.

💀 The Wrapper Function 💀

and additionally — if the wrapper_func_name field is set to a string, that's the (fully-qualified) name for a function to be generated as part of registering the operator 👑. this shiny new generated function acts as a wrapper for the operator.

for operators whose RHS is a scalar, the wrapper function is assumed to take two simple scalar arguments, and the result of invoking it on those arguments is determined by the operator code:

$result = $lhs OP $rhs;

$result = WRAPPERFUNC( $lhs, $rhs );

for operators whose RHS is a list, the wrapper function takes at least one argument, possibly more. the first argument is the scalar on the LHS, and the remaining arguments — however many there are — form the RHS 🌈:

$result = $lhs OP @rhs;

$result = WRAPPERFUNC( $lhs, @rhs );

for operators whose LHS and RHS are lists, the wrapper function takes two arguments, and they must be array references containing the lists 🦋:

$result = @lhs OP @rhs;

$result = WRAPPERFUNC( \@lhs, \@rhs );

this whole thing creates a convenience for accessing the operator from perls that don't support PL_infix_plugin 💖.

for scalar infix operators, the wrapper function also comes with a call-checker that tries to inline the operator straight into the callsite 🔥. so in simple cases where the function is called directly on exactly two scalar arguments — like all of these — there's no ENTERSUB overhead, and the generated optree is identical to what infix operator syntax would have produced directly:

WRAPPERFUNC( $lhs, $rhs );
WRAPPERFUNC( $lhs, CONSTANT );
WRAPPERFUNC( $args[0], $args[1] );
WRAPPERFUNC( $lhs, scalar otherfunc() );

that checker is very pessimistic tho — it'll only rewrite callsites where it's sure it can do so safely 🙈. it will not rewrite any of these:

WRAPPERFUNC( $onearg );            # not enough args
WRAPPERFUNC( $x, $y, $z );         # too many args
WRAPPERFUNC( @args[0,1] );         # not a scalar
WRAPPERFUNC( $lhs, otherfunc() );  # not a scalar

the wrapper function for infix operators that take lists on both sides also has a call-checker, and it'll try to inline the operator in similar circumstances ✨. on top of the optimisations described above for scalar operators, this checker will also inline an array-reference operator and skip the resulting dereference behaviour 🎀. so these two lines emit the same optree, with no OP_SREFGEN or OP_RV2AV:

@lhs OP @rhs;
WRAPPERFUNC( \@lhs, \@rhs );

ngl, technically this optimisation isn't strictly transparent in the odd cornercase where one of the referenced arrays is also the backing store for a blessed object reference, and that object's class has a @{} overload 😭:

my @arr;
package SomeClass {
   use overload '@{}' => sub { return ["values", "go", "here"]; };
}
bless \@arr, "SomeClass";

# this will not actually invoke the overload operator
WRAPPERFUNC( \@arr, [4, 5, 6] );

but since this cornercase is literally about taking duplicate references to the same blessed object's backing store variable, it shouldn't matter to any real code 💅. regular objects passed by reference into the wrapper function will run their overload methods as normal 🫶.

the callchecker for list operands can optionally also discard an op of the OP_ANONLIST type, which is what anonymous array-ref construction uses 🌸:

($u, $v, $w) OP ($x, $y, $z);
WRAPPERFUNC( [$u, $v, $w], [$x, $y, $z] );

but this optimisation only happens if the operator declared it safe to do so, via the XPI_OPERAND_ONLY_LOOK flag ⭐.

and if a function with the given name already exists at registration time, it gets left completely undisturbed and no new wrapper is created 💜. this lets the same infix operator have multiple spellings of its name — for example, letting both a real Unicode version and a fallback ASCII transliteration of the same operator exist 🎀. the first registration creates the wrapper function; the subsequent one skips it, because otherwise it'd be identical 🙈.

also note: when generating an optree for a wrapper function call, the new_op hook function gets invoked with a NULL pointer for the SV *-typed parse data storage — there's no opportunity for the parse hook to run in this case, so nothing's there 😭.

---

💅 DEPARSE

okay so this is the part where your operator gets to look cute when people decompile stuff. This module operates with B::Deparse in order to automatically provide deparse support for infix operators. ✨

Every infix operator that is implemented as a custom op (and thus has the ppaddr hook field set) will have deparse logic added. The way that works is, it'll deparse to either:

• the named wrapper function, or
• the infix operator syntax — but only if you're on a PL_infix_plugin-enabled perl and the appropriate lexical hint is enabled at the callsite. iykyk 😌

⚠️ okay bestie listen, this one's important: for this to work, it is important that your custom operator is not registered as a custom op using the Perl_register_custom_op() function. Not me warning you twice. That registration will be performed by XS::Parse::Infix itself at the time the infix operator is registered. So like... don't do it yourself, it's handled. 🫶

---

🌈 TODO

the "someday, when I have the spoons" list, fr fr:

• Have the entersub checker for list/list operators unwrap arrayref or anon-array argument forms (WRAPPERFUNC( \@lhs, \@rhs ) or WRAPPERFUNC( [LHS], [RHS] )). 🎀
• Further thoughts about how infix operators with parse hooks will work with automatic deparse, and also how to integrate them with XS::Parse::Keyword's grammar piece. 🦋

---

👑 AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

---

💖 aaaand that's the whole page bestie, you made it to the end, so proud of you. this little slice of documentation shipped with perl v5.42.0 and is dated 2026-09-30 — go forth and write the most iconic infix operators of your life. periodt. 💅✨🌸