.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XS::Parse::Keyword 3pm"
.TH XS::Parse::Keyword 3pm 2024-09-13 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
"XS::Parse::Keyword" \- XS functions to assist in parsing keyword syntax
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides some XS functions to assist in writing syntax modules
that provide new perl-visible syntax, primarily for authors of keyword plugins
using the \f(CW\*(C`PL_keyword_plugin\*(C'\fR 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.
.PP
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.
.SH "XS FUNCTIONS"
.IX Header "XS FUNCTIONS"
.SS boot_xs_parse_keyword
.IX Subsection "boot_xs_parse_keyword"
.Vb 1
\&   void boot_xs_parse_keyword(double ver);
.Ve
.PP
Call this function from your \f(CW\*(C`BOOT\*(C'\fR section in order to initialise the module
and parsing hooks.
.PP
\&\fIver\fR should either be 0 or a decimal number for the module version
requirement; e.g.
.PP
.Vb 1
\&   boot_xs_parse_keyword(0.14);
.Ve
.SS register_xs_parse_keyword
.IX Subsection "register_xs_parse_keyword"
.Vb 2
\&   void register_xs_parse_keyword(const char *keyword,
\&     const struct XSParseKeywordHooks *hooks, void *hookdata);
.Ve
.PP
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 \f(CW\*(C`XS::Parse::Keyword\*(C'\fR itself.
.SH "PARSE HOOKS"
.IX Header "PARSE HOOKS"
The \f(CW\*(C`XSParseKeywordHooks\*(C'\fR structure provides the following hook stages, which
are invoked in the given order.
.SS flags
.IX Subsection "flags"
The following flags are defined:
.ie n .IP """XPK_FLAG_EXPR""" 4
.el .IP \f(CWXPK_FLAG_EXPR\fR 4
.IX Item "XPK_FLAG_EXPR"
The parse or build function is expected to return \f(CW\*(C`KEYWORD_PLUGIN_EXPR\*(C'\fR.
.ie n .IP """XPK_FLAG_STMT""" 4
.el .IP \f(CWXPK_FLAG_STMT\fR 4
.IX Item "XPK_FLAG_STMT"
The parse or build function is expected to return \f(CW\*(C`KEYWORD_PLUGIN_STMT\*(C'\fR.
.Sp
These two flags are largely for the benefit of giving static information at
registration time to assist static parsing or other related tasks to know what
kind of grammatical element this keyword will produce.
.ie n .IP """XPK_FLAG_AUTOSEMI""" 4
.el .IP \f(CWXPK_FLAG_AUTOSEMI\fR 4
.IX Item "XPK_FLAG_AUTOSEMI"
The syntax forms a complete statement, which should be followed by a statement
separator semicolon (\f(CW\*(C`;\*(C'\fR). This semicolon is optional at the end of a block.
.Sp
The semicolon, if present, will be consumed automatically.
.ie n .IP """XPK_FLAG_BLOCKSCOPE""" 4
.el .IP \f(CWXPK_FLAG_BLOCKSCOPE\fR 4
.IX Item "XPK_FLAG_BLOCKSCOPE"
The entire parse and build process will be wrapped in a pair of
\&\f(CWblock_start()\fR and \f(CWblock_end()\fR calls. This ensures that, for example, any
newly-introduced lexical variables do not escape from the scope of the syntax
created by the keyword.
.ie n .SS "The ""permit"" Stage"
.el .SS "The \f(CWpermit\fP Stage"
.IX Subsection "The permit Stage"
.Vb 2
\&   const char *permit_hintkey;
\&   bool (*permit) (pTHX_ void *hookdata);
.Ve
.PP
Called by the installed keyword parser hook which is used to handle keywords
registered by "register_xs_parse_keyword".
.PP
As a shortcut for the common case, the \f(CW\*(C`permit_hintkey\*(C'\fR may point to a string
to look up from the hints hash. If the given key name is not found in the
hints hash then the keyword is not permitted. If the key is present then the
\&\f(CW\*(C`permit\*(C'\fR function is invoked as normal.
.PP
If not rejected by a hint key that was not found in the hints hash, the
function part of the stage is called next and should inspect whether the
keyword is permitted at this time perhaps by inspecting other lexical clues,
and return true only if the keyword is permitted.
.PP
Both the string and the function are optional. Either or both may be present.
If neither is present then the keyword is always permitted \- which is likely
not what you wanted to do.
.ie n .SS "The ""check"" Stage"
.el .SS "The \f(CWcheck\fP Stage"
.IX Subsection "The check Stage"
.Vb 1
\&   void (*check)(pTHX_ void *hookdata);
.Ve
.PP
Invoked once the keyword has been permitted. If present, this hook function
can check the surrounding lexical context, state, or other information and
throw an exception if it is unhappy that the keyword should apply in this
position.
.ie n .SS "The ""parse"" Stage"
.el .SS "The \f(CWparse\fP Stage"
.IX Subsection "The parse Stage"
This stage is invoked once the keyword has been checked, and actually
parses the incoming text into an optree. It is implemented by calling the
\&\fBfirst\fR of the following function pointers which is not NULL. The invoked
function may optionally build an optree to represent the parsed syntax, and
place it into the variable addressed by \f(CW\*(C`out\*(C'\fR. If it does not, then a simple
\&\f(CW\*(C`OP_NULL\*(C'\fR will be constructed in its place.
.PP
\&\f(CWlex_read_space()\fR is called both before and after this stage is invoked, so
in many simple cases the hook function itself does not need to bother with it.
.PP
.Vb 1
\&   int (*parse)(pTHX_ OP **out, void *hookdata);
.Ve
.PP
If present, this should consume text from the parser buffer by invoking
\&\f(CW\*(C`lex_*\*(C'\fR or \f(CW\*(C`parse_*\*(C'\fR functions and eventually return a \f(CW\*(C`KEYWORD_PLUGIN_*\*(C'\fR
result value.
.PP
This is the most generic and powerful of the options, but requires the most
amount of implementation work.
.PP
.Vb 1
\&   int (*build)(pTHX_ OP **out, XSParseKeywordPiece *args[], size_t nargs, void *hookdata);
.Ve
.PP
If \f(CW\*(C`parse\*(C'\fR is not present, this is called instead after parsing a sequence of
arguments, of types given by the \fIpieces\fR field; which should be a zero\-
terminated array of piece types.
.PP
This alternative is somewhat less generic and powerful than providing \f(CW\*(C`parse\*(C'\fR
yourself, but involves much less parsing work and is shorter and easier to
implement.
.PP
.Vb 1
\&   int (*build1)(pTHX_ OP **out, XSParseKeywordPiece *arg0, void *hookdata);
.Ve
.PP
If neither \f(CW\*(C`parse\*(C'\fR nor \f(CW\*(C`build\*(C'\fR are present, this is called as a simpler
variant of \f(CW\*(C`build\*(C'\fR when only a single argument is required. It takes its type
from the \f(CW\*(C`piece1\*(C'\fR field instead.
.SH "PIECES AND PIECE TYPES"
.IX Header "PIECES AND PIECE TYPES"
When using the \f(CW\*(C`build\*(C'\fR or \f(CW\*(C`build1\*(C'\fR alternatives for the \f(CW\*(C`parse\*(C'\fR phase, the
actual syntax is parsed automatically by this module, according to the
specification given by the \fIpieces\fR or \fIpiece1\fR field. The result of that
parsing step is placed into the \fIargs\fR or \fIarg0\fR parameter to the invoked
function, using a \f(CW\*(C`struct\*(C'\fR type consisting of the following fields:
.PP
.Vb 10
\&   typedef struct
\&      union {
\&         OP *op;
\&         CV *cv;
\&         SV *sv;
\&         int i;
\&         struct {
\&            SV *name;
\&            SV *value;
\&         } attr;
\&         PADOFFSET padix;
\&         struct XSParseInfixInfo *infix;
\&      };
\&      int line;
\&   } XSParseKeywordPiece;
.Ve
.PP
Which field of the anonymous union is set depends on the type of the piece.
The \fIline\fR field contains the line number of the source file where parsing of
that piece began.
.PP
Some piece types are "atomic", whose definition is self-contained. Others are
structural, defined in terms of inner pieces. Together these form an entire
tree-shaped definition of the syntax that the keyword expects to find.
.PP
Atomic types generally provide exactly one argument into the list of \fIargs\fR
(with the exception of literal matches, which do not provide anything).
Structural types may provide an initial argument themselves, followed by a
list of the values of each sub-piece they contained inside them. Thus, while
the data structure defining the syntax shape is a tree, the argument values it
parses into is passed as a flat array to the \f(CW\*(C`build\*(C'\fR function.
.PP
Some structural types need to be able to determine whether or not syntax
relating some optional part of them is present in the incoming source text. In
this case, the pieces relating to those optional parts must support "probing".
This ability is also noted below.
.PP
Many of the atomic piece types have a variant which is optional; if the given
input does not look like the expected syntax for the piece type then an
\&\f(CW\*(C`_OPT\*(C'\fR\-suffixed version of the type will instead yield \f(CW\*(C`NULL\*(C'\fR in its result
pointer.
.PP
The type of each piece should be one of the following macro values.
.SS XPK_BLOCK
.IX Subsection "XPK_BLOCK"
\&\fIatomic, can probe, emits op.\fR
.PP
.Vb 1
\&   XPK_BLOCK
.Ve
.PP
A brace-delimited block of code is expected, passed as an optree in the \fIop\fR
field. This will be parsed as a block within the current function scope.
.PP
This can be probed by checking for the presence of an open-brace (\f(CW\*(C`{\*(C'\fR)
character.
.PP
Be careful defining grammars with this because an open-brace is also a valid
character to start a term expression, for example. Given a choice between
\&\f(CW\*(C`XPK_BLOCK\*(C'\fR and \f(CW\*(C`XPK_TERMEXPR\*(C'\fR, either of them could try to consume such
code as
.PP
.Vb 1
\&   { 123, 456 }
.Ve
.SS "XPK_BLOCK_VOIDCTX, XPK_BLOCK_SCALARCTX, XPK_BLOCK_LISTCTX"
.IX Subsection "XPK_BLOCK_VOIDCTX, XPK_BLOCK_SCALARCTX, XPK_BLOCK_LISTCTX"
Variants of \f(CW\*(C`XPK_BLOCK\*(C'\fR which wrap a void, scalar or list-context scope
around the block.
.SS XPK_PREFIXED_BLOCK
.IX Subsection "XPK_PREFIXED_BLOCK"
\&\fIstructural, emits op.\fR
.PP
.Vb 1
\&   XPK_PREFIXED_BLOCK(pieces ...)
.Ve
.PP
Some pieces are expected, followed by a brace-delimited block of code, which
is passed as an optree in the \fIop\fR field. The prefix pieces are parsed first,
and their results are passed before the block itself.
.PP
The entire sequence, including the prefix items, is contained within a pair of
\&\f(CWblock_start()\fR / \f(CWblock_end()\fR calls. This permits the prefix pieces to
introduce new items into the lexical scope of the block \- for example by the
use of \f(CW\*(C`XPK_LEXVAR_MY\*(C'\fR.
.PP
A call to \f(CWintro_my()\fR is automatically made at the end of the prefix pieces,
before the block itself is parsed, ensuring any new lexical variables are now
visible.
.PP
In addition, the following extra piece types are recognised here:
.IP XPK_SETUP 4
.IX Item "XPK_SETUP"
.Vb 1
\&   void setup(pTHX_ void *hookdata);
\&
\&   XPK_SETUP(&setup)
.Ve
.Sp
\&\fIatomic, emits nothing.\fR
.Sp
This piece type runs a function given by pointer. Typically this function may
be used to introduce new lexical state into the parser, or in some other way
have some side-effect on the parsing context of the block to be parsed.
.SS XPK_PREFIXED_BLOCK_ENTERLEAVE
.IX Subsection "XPK_PREFIXED_BLOCK_ENTERLEAVE"
A variant of \f(CW\*(C`XPK_PREFIXED_BLOCK\*(C'\fR which additionally wraps the entire parsing
operation, including the \f(CWblock_start()\fR, \f(CWblock_end()\fR and any calls to
\&\f(CW\*(C`XPK_SETUP\*(C'\fR functions, within a \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR pair.
.PP
This should not make a difference to the standard parser pieces provided here,
but may be useful behaviour for the code in the setup function, especially if
it wishes to modify parser state and use the savestack to ensure it is
restored again when parsing has finished.
.SS XPK_ANONSUB
.IX Subsection "XPK_ANONSUB"
\&\fIatomic, emits cv.\fR
.PP
A brace-delimited block of code is expected, and assembled into the body of a
new anonymous subroutine. This will be passed as a protosub CV in the \fIcv\fR
field.
.SS XPK_STAGED_ANONSUB
.IX Subsection "XPK_STAGED_ANONSUB"
.Vb 1
\&   XPK_STAGED_ANONSUB(stages ...)
.Ve
.PP
\&\fIstructural, emits cv.\fR
.PP
A variant of \f(CW\*(C`XPK_ANONSUB\*(C'\fR which accepts additional function pointers to be
invoked at various points during parsing and compilation. These can be used to
interrupt the normal parsing in a manner similar to XS::Parse::Sublike,
though currently somewhat less flexibly.
.PP
The \fIstages\fR list may contain elements of the following types. Not every
stage must be present, but any that are present must be in the following
order. Multiple copies of each stage are permitted; they are invoked in the
written order, with parser code happening inbetween.
.IP XPK_ANONSUB_PREPARE 4
.IX Item "XPK_ANONSUB_PREPARE"
.Vb 1
\&   XPK_ANONSUB_PREPARE(&callback)
.Ve
.Sp
\&\fIatomic, emits nothing.\fR
.Sp
Invokes the callback before \f(CWstart_subparse()\fR.
.IP XPK_ANONSUB_START 4
.IX Item "XPK_ANONSUB_START"
.Vb 1
\&   XPK_ANONSUB_START(&callback)
.Ve
.Sp
\&\fIatomic, emits nothing.\fR
.Sp
Invokes the callback after \f(CWblock_start()\fR but before parsing the actual
block contents.
.IP XPK_ANONSUB_END 4
.IX Item "XPK_ANONSUB_END"
.Vb 1
\&   OP *op_wrapper_callback(pTHX_ OP *o, void *hookdata);
\&
\&   XPK_ANONSUB_END(&op_wrapper_callback)
.Ve
.Sp
\&\fIatomic, emits nothing.\fR
.Sp
Invokes the callback after parsing the block contents but before calling
\&\f(CWblock_end()\fR. The callback may modify the optree if required and return a
new one.
.IP XPK_ANONSUB_WRAP 4
.IX Item "XPK_ANONSUB_WRAP"
.Vb 1
\&   XPK_ANONSUB_WRAP(&op_wrapper_callback)
.Ve
.Sp
\&\fIatomic, emits nothing.\fR
.Sp
Invokes the callback after \f(CWblock_end()\fR but before passing the optree to
\&\f(CWnewATTRSUB()\fR. The callback may modify the optree if required and return a
new one.
.SS "XPK_ARITHEXPR. XPK_ARITHEXPR_OPT"
.IX Subsection "XPK_ARITHEXPR. XPK_ARITHEXPR_OPT"
\&\fIatomic, emits op.\fR
.PP
.Vb 1
\&   XPK_ARITHEXPR
.Ve
.PP
An arithmetic expression is expected, parsed using \f(CWparse_arithexpr()\fR, and
passed as an optree in the \fIop\fR field.
.SS "XPK_ARITHEXPR_VOIDCTX, XPK_ARITHEXPR_OPT"
.IX Subsection "XPK_ARITHEXPR_VOIDCTX, XPK_ARITHEXPR_OPT"
.SS "XPK_ARITHEXPR_SCALARCTX, XPK_ARITHEXPR_SCALARCTX_OPT"
.IX Subsection "XPK_ARITHEXPR_SCALARCTX, XPK_ARITHEXPR_SCALARCTX_OPT"
Variants of \f(CW\*(C`XPK_ARITHEXPR\*(C'\fR which puts the expression in void or scalar context.
.SS "XPK_TERMEXPR, XPK_TERMEXPR_OPT"
.IX Subsection "XPK_TERMEXPR, XPK_TERMEXPR_OPT"
\&\fIatomic, emits op.\fR
.PP
.Vb 1
\&   XPK_TERMEXPR
.Ve
.PP
A term expression is expected, parsed using \f(CWparse_termexpr()\fR, and passed as
an optree in the \fIop\fR field.
.SS "XPK_TERMEXPR_VOIDCTX, XPK_TERMEXPR_VOIDCTX"
.IX Subsection "XPK_TERMEXPR_VOIDCTX, XPK_TERMEXPR_VOIDCTX"
.SS "XPK_TERMEXPR_SCALARCTX, XPK_TERMEXPR_SCALARCTX_OPT"
.IX Subsection "XPK_TERMEXPR_SCALARCTX, XPK_TERMEXPR_SCALARCTX_OPT"
Variants of \f(CW\*(C`XPK_TERMEXPR\*(C'\fR which puts the expression in void or scalar context.
.SS "XPK_LISTEXPR, XPK_LISTEXPR_OPT"
.IX Subsection "XPK_LISTEXPR, XPK_LISTEXPR_OPT"
\&\fIatomic, emits op.\fR
.PP
.Vb 1
\&   XPK_LISTEXPR
.Ve
.PP
A list expression is expected, parsed using \f(CWparse_listexpr()\fR, and passed as
an optree in the \fIop\fR field.
.SS "XPK_LISTEXPR_LISTCTX, XPK_LISTEXPR_LISTCTX_OPT"
.IX Subsection "XPK_LISTEXPR_LISTCTX, XPK_LISTEXPR_LISTCTX_OPT"
Variant of \f(CW\*(C`XPK_LISTEXPR\*(C'\fR which puts the expression in list context.
.SS "XPK_PREFIXED_TERMEXPR_ENTERLEAVE, XPK_PREFIXED_LISTEXPR_ENTERLEAVE"
.IX Subsection "XPK_PREFIXED_TERMEXPR_ENTERLEAVE, XPK_PREFIXED_LISTEXPR_ENTERLEAVE"
.Vb 2
\&   XPK_PREFIXED_TERMEXPR_ENTERLEAVE(pieces ...)
\&   XPK_PREFIXED_LISTEXPR_ENTERLEAVE(pieces ...)
.Ve
.PP
Variants of \f(CW\*(C`XPK_TERMEXPR\*(C'\fR or \f(CW\*(C`XPK_LISTEXPR\*(C'\fR which expect a sequence pieces
first before it parses a term expression, similar to how
\&\f(CW\*(C`XPK_PREFIXED_BLOCK_ENTERLEAVE\*(C'\fR works. The entire operation is wrapped in an
\&\f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR pair.
.PP
These are intended just for use of \f(CW\*(C`XPK_SETUP\*(C'\fR pieces as prefixes. Any other
pieces which actually parse real input are likely to cause overly-complex,
subtle, or outright ambiguous grammars, and should be avoided.
.SS "XPK_IDENT, XPK_IDENT_OPT"
.IX Subsection "XPK_IDENT, XPK_IDENT_OPT"
\&\fIatomic, can probe, emits sv.\fR
.PP
A bareword identifier name is expected, and passed as an SV containing a PV
in the \fIsv\fR field. An identifier is not permitted to contain a double colon
(\f(CW\*(C`::\*(C'\fR).
.SS "XPK_PACKAGENAME, XPK_PACKAGENAME_OPT"
.IX Subsection "XPK_PACKAGENAME, XPK_PACKAGENAME_OPT"
\&\fIatomic, can probe, emits sv.\fR
.PP
A bareword package name is expected, and passed as an SV containing a PV in
the \fIsv\fR field. A package name is similar to an identifier, except it permits
double colons in the middle.
.SS XPK_LEXVARNAME
.IX Subsection "XPK_LEXVARNAME"
\&\fIatomic, emits sv.\fR
.PP
.Vb 1
\&   XPK_LEXVARNAME(kind)
.Ve
.PP
A lexical variable name is expected, and passed as an SV containing a PV in
the \fIsv\fR field. The \f(CW\*(C`kind\*(C'\fR argument specifies what kinds of variable are
permitted, and should be a bitmask of one or more bits from
\&\f(CW\*(C`XPK_LEXVAR_SCALAR\*(C'\fR, \f(CW\*(C`XPK_LEXVAR_ARRAY\*(C'\fR and \f(CW\*(C`XPK_LEXVAR_HASH\*(C'\fR. A convenient
shortcut \f(CW\*(C`XPK_LEXVAR_ANY\*(C'\fR permits all three.
.SS XPK_ATTRIBUTES
.IX Subsection "XPK_ATTRIBUTES"
\&\fIatomic, emits i followed by more args.\fR
.PP
A list of \f(CW\*(C`:\*(C'\fR\-prefixed attributes is expected, in the same format as sub or
variable attributes. An optional leading \f(CW\*(C`:\*(C'\fR indicates the presence of
attributes, then one or more of them are parsed. Attributes may be optionally
separated by additional \f(CW\*(C`:\*(C'\fRs, but this is not required.
.PP
Each attribute is expected to be an identifier name, followed by an optional
value wrapped in parentheses. Whitespace is \fBNOT\fR permitted between the name
and value, as per standard Perl parsing rules.
.PP
.Vb 2
\&   :attrname
\&   :attrname(value)
.Ve
.PP
The \fIi\fR field indicates how many attributes were found. That number of
additional arguments are then passed, each containing two SVs in the
\&\fIattr.name\fR and \fIattr.value\fR fields. This number may be zero.
.PP
It is not an error for there to be no attributes present, or for the optional
colon to be missing. In this case \fIi\fR will be set to zero.
.SS "XPK_VSTRING, XPK_VSTRING_OPT"
.IX Subsection "XPK_VSTRING, XPK_VSTRING_OPT"
\&\fIatomic, can probe, emits sv.\fR
.PP
A version string is expected, of the form \f(CW\*(C`v1.234\*(C'\fR including the leading \f(CW\*(C`v\*(C'\fR
character. It is passed as a version SV object in the \fIsv\fR field.
.SS XPK_LEXVAR
.IX Subsection "XPK_LEXVAR"
\&\fIatomic, emits padix.\fR
.PP
.Vb 1
\&   XPK_LEXVAR(kind)
.Ve
.PP
A lexical variable name is expected and looked up from the current pad. The
resulting pad index is passed in the \fIpadix\fR field. No error happens if the
variable is not found; the value \f(CW\*(C`NOT_IN_PAD\*(C'\fR is passed instead.
.PP
The \f(CW\*(C`kind\*(C'\fR argument specifies what kinds of variable are permitted, as per
\&\f(CW\*(C`XPK_LEXVARNAME\*(C'\fR.
.SS XPK_LEXVAR_MY
.IX Subsection "XPK_LEXVAR_MY"
\&\fIatomic, emits padix.\fR
.PP
.Vb 1
\&   XPK_LEXVAR_MY(kind)
.Ve
.PP
A lexical variable name is expected, added to the current pad as if specified
in a \f(CW\*(C`my\*(C'\fR expression, and passed as the pad index in the \fIpadix\fR field.
.PP
The \f(CW\*(C`kind\*(C'\fR argument specifies what kinds of variable are permitted, as per
\&\f(CW\*(C`XPK_LEXVARNAME\*(C'\fR.
.SS "XPK_COMMA, XPK_COLON, XPK_EQUALS"
.IX Subsection "XPK_COMMA, XPK_COLON, XPK_EQUALS"
\&\fIatomic, can probe, emits nothing.\fR
.PP
A literal character (\f(CW\*(C`,\*(C'\fR, \f(CW\*(C`:\*(C'\fR or \f(CW\*(C`=\*(C'\fR) is expected. No argument value is passed.
.SS XPK_AUTOSEMI
.IX Subsection "XPK_AUTOSEMI"
\&\fIatomic, emits nothing.\fR
.PP
A literal semicolon (\f(CW\*(C`;\*(C'\fR) as a statement terminator is optionally expected.
If the next token is a closing brace to indicate the end of a block, then a
semicolon is not required. If anything else is encountered an error will be
raised.
.PP
This piece type is the same as specifying the \f(CW\*(C`XPK_FLAG_AUTOSEMI\*(C'\fR. It is
useful to put at the end of a sequence that forms part of a choice of syntax,
where some forms indicate a statement ending in a semicolon, whereas others
may end in a full block that does not need one.
.SS XPK_INFIX_*
.IX Subsection "XPK_INFIX_*"
\&\fIatomic, can probe, emits infix.\fR
.PP
An infix operator as recognised by XS::Parse::Infix. The returned pointer
points to a structure allocated by \f(CW\*(C`XS::Parse::Infix\*(C'\fR describing the
operator.
.PP
Various versions of the macro are provided, each using a different selection
filter to choose certain available infix operators:
.PP
.Vb 4
\&   XPK_INFIX_RELATION         # any relational operator
\&   XPK_INFIX_EQUALITY         # an equality operator like \`==\` or \`eq\`
\&   XPK_INFIX_MATCH_NOSMART    # any sort of "match"\-like operator, except smartmatch
\&   XPK_INFIX_MATCH_SMART      # XPK_INFIX_MATCH_NOSMART plus smartmatch
.Ve
.SS XPK_LITERAL
.IX Subsection "XPK_LITERAL"
\&\fIatomic, can probe, emits nothing.\fR
.PP
.Vb 1
\&   XPK_LITERAL("literal")
.Ve
.PP
A literal string match is expected. No argument value is passed.
.PP
This form should generally be avoided if at all possible, because it is very
easy to abuse to make syntaxes which confuse humans and code tools alike.
Generally it is best reserved just for the first component of a
\&\f(CW\*(C`XPK_OPTIONAL\*(C'\fR or \f(CW\*(C`XPK_REPEATED\*(C'\fR sequence, to provide a "secondary keyword"
that such a repeated item can look out for.
.SS XPK_KEYWORD
.IX Subsection "XPK_KEYWORD"
\&\fIatomic, can probe, emits nothing.\fR
.PP
.Vb 1
\&   XPK_KEYWORD("keyword")
.Ve
.PP
A literal string match is expected. No argument value is passed.
.PP
This is similar to \f(CW\*(C`XPK_LITERAL\*(C'\fR except that it additionally checks that the
following character is not an identifier character. This ensures that the
expected keyword-like behaviour is preserved. For example, given the input
\&\f(CW"keyword"\fR, the piece \f(CWXPK_LITERAL("key")\fR would match it, whereas
\&\f(CWXPK_KEYWORD("key")\fR would not because of the subsequent \f(CW"w"\fR character.
.SS XPK_INTRO_MY
.IX Subsection "XPK_INTRO_MY"
\&\fIatomic, emits nothing.\fR
.PP
Calls the core perl \f(CWintro_my()\fR function immediately. No input is consumed
and no output value is generated. This is often useful after \f(CW\*(C`XPK_LEXVAR_MY\*(C'\fR.
.SS XPK_WARNING
.IX Subsection "XPK_WARNING"
\&\fIatomic, emits nothing.\fR
.PP
.Vb 1
\&   XPK_WARNING("message here")
.Ve
.PP
Emits a warning by calling the core perl \f(CWwarn()\fR function on the given
string literal. This is equivalent to simply calling \f(CWwarn()\fR from the build
function, except that it is emitted immediately at parse time, so line
numbering will be more accurate. Also, by placing it as part of an optional or
choice sequence, the warning will only be emitted conditionally if that part
of the grammar structure is encountered.
.SS XPK_WARNING_...
.IX Subsection "XPK_WARNING_..."
Several variants of \f(CW\*(C`XPK_WARNING\*(C'\fR exist that are conditional on particular
warning categories being enabled. These are ones that are likely to be useful
at parse time:
.PP
.Vb 5
\&   XPK_WARNING_AMBIGUOUS
\&   XPK_WARNING_DEPRECATED
\&   XPK_WARNING_EXPERIMENTAL
\&   XPK_WARNING_PRECEDENCE
\&   XPK_WARNING_SYNTAX
.Ve
.SS XPK_SEQUENCE
.IX Subsection "XPK_SEQUENCE"
\&\fIstructural, might support probe, emits nothing.\fR
.PP
.Vb 1
\&   XPK_SEQUENCE(pieces ...)
.Ve
.PP
A structural type which contains a number of pieces. This is normally
equivalent to simply placing the pieces in sequence inside their own
container, but it is useful inside \f(CW\*(C`XPK_CHOICE\*(C'\fR or \f(CW\*(C`XPK_TAGGEDCHOICE\*(C'\fR.
.PP
An \f(CW\*(C`XPK_SEQUENCE\*(C'\fR supports probe if its first contained piece does; i.e.
is transparent to probing.
.SS XPK_OPTIONAL
.IX Subsection "XPK_OPTIONAL"
\&\fIstructural, emits i.\fR
.PP
.Vb 1
\&   XPK_OPTIONAL(pieces ...)
.Ve
.PP
A structural type which may expects to find its contained pieces, or is happy
not to. This will pass an argument whose \fIi\fR field contains either 1 or 0,
depending whether the contents were found. The first piece type within must
support probe.
.SS XPK_REPEATED
.IX Subsection "XPK_REPEATED"
\&\fIstructural, emits i.\fR
.PP
.Vb 1
\&   XPK_REPEATED(pieces ...)
.Ve
.PP
A structural type which expects to find zero or more repeats of its contained
pieces. This will pass an argument whose \fIi\fR field contains the count of the
number of repeats it found. The first piece type within must support probe.
.SS XPK_CHOICE
.IX Subsection "XPK_CHOICE"
\&\fIstructural, can probe, emits i.\fR
.PP
.Vb 1
\&   XPK_CHOICE(options ...)
.Ve
.PP
A structural type which expects to find one of a number of alternative
options. An ordered list of types is provided, all of which must support
probe. This will pass an argument whose \fIi\fR field gives the index of the
first choice that was accepted. The first option takes the value 0.
.PP
As each of the options is interpreted as an alternative, not a sequence, you
should use \f(CW\*(C`XPK_SEQUENCE\*(C'\fR if a sequence of multiple items should be
considered as a single alternative.
.PP
It is not an error if no choice matches. At that point, the \fIi\fR field will be
set to \-1.
.PP
If you require a failure message in this case, set the final choice to be of
type \f(CW\*(C`XPK_FAILURE\*(C'\fR. This will cause an error message to be printed instead.
.PP
.Vb 1
\&   XPK_FAILURE("message string")
.Ve
.SS XPK_TAGGEDCHOICE
.IX Subsection "XPK_TAGGEDCHOICE"
\&\fIstructural, can probe, emits i.\fR
.PP
.Vb 1
\&   XPK_TAGGEDCHOICE(choice, tag, ...)
.Ve
.PP
A structural type similar to \f(CW\*(C`XPK_CHOICE\*(C'\fR, except that each choice type is
followed by an element of type \f(CW\*(C`XPK_TAG\*(C'\fR which gives an integer. It is that
integer value, rather than the positional index of the choice within the list,
which is passed in the \fIi\fR field.
.PP
.Vb 1
\&   XPK_TAG(value)
.Ve
.PP
As each of the options is interpreted as an alternative, not a sequence, you
should use \f(CW\*(C`XPK_SEQUENCE\*(C'\fR if a sequence of multiple items should be
considered as a single alternative.
.SS XPK_COMMALIST
.IX Subsection "XPK_COMMALIST"
\&\fIstructural, might support probe, emits i.\fR
.PP
.Vb 1
\&   XPK_COMMALIST(pieces ...)
.Ve
.PP
A structural type which expects to find one or more repeats of its contained
pieces, separated by literal comma (\f(CW\*(C`,\*(C'\fR) characters. This is somewhat similar
to \f(CW\*(C`XPK_REPEATED\*(C'\fR, except that it needs at least one copy, needs commas
between its items, but does not require that the first contained piece support
probe (the comma itself is sufficient to indicate a repeat).
.PP
An \f(CW\*(C`XPK_COMMALIST\*(C'\fR supports probe if its first contained piece does; i.e.
is transparent to probing.
.SS XPK_PARENS
.IX Subsection "XPK_PARENS"
\&\fIstructural, can probe, emits nothing.\fR
.PP
.Vb 1
\&   XPK_PARENS(pieces ...)
.Ve
.PP
A structural type which expects to find a sequence of pieces, all contained in
parentheses as \f(CW\*(C`( ... )\*(C'\fR. This will pass no extra arguments.
.SS XPK_ARGS
.IX Subsection "XPK_ARGS"
\&\fIstructural, emits nothing.\fR
.PP
.Vb 1
\&   XPK_ARGS(pieces ...)
.Ve
.PP
A structural type similar to \f(CW\*(C`XPK_PARENS\*(C'\fR, except that the parentheses
themselves are optional; much like Perl's parsing of calls to known functions.
.PP
If parentheses are encountered in the input, they will be consumed by this
piece and it will behave identically to \f(CW\*(C`XPK_PARENS\*(C'\fR. If there is no open
parenthesis, this piece will behave like \f(CW\*(C`XPK_SEQUENCE\*(C'\fR and consume all the
pieces inside it, without expecting a closing parenthesis.
.SS XPK_BRACKETS
.IX Subsection "XPK_BRACKETS"
\&\fIstructural, can probe, emits nothing.\fR
.PP
.Vb 1
\&   XPK_BRACKETS(pieces ...)
.Ve
.PP
A structural type which expects to find a sequence of pieces, all contained in
square brackets as \f(CW\*(C`[ ... ]\*(C'\fR. This will pass no extra arguments.
.SS XPK_BRACES
.IX Subsection "XPK_BRACES"
\&\fIstructural, can probe, emits nothing.\fR
.PP
.Vb 1
\&   XPK_BRACES(pieces ...)
.Ve
.PP
A structural type which expects to find a sequence of pieces, all contained in
braces as \f(CW\*(C`{ ... }\*(C'\fR. This will pass no extra arguments.
.PP
Note that this is not necessary to use with \f(CW\*(C`XPK_BLOCK\*(C'\fR or \f(CW\*(C`XPK_ANONSUB\*(C'\fR;
those will already consume a set of braces. This is intended for special
constrained syntax that should not just accept an arbitrary block.
.SS XPK_CHEVRONS
.IX Subsection "XPK_CHEVRONS"
\&\fIstructural, can probe, emits nothing.\fR
.PP
.Vb 1
\&   XPK_CHEVRONS(pieces ...)
.Ve
.PP
A structural type which expects to find a sequence of pieces, all contained in
angle brackets as \f(CW\*(C`< ... >\*(C'\fR. This will pass no extra arguments.
.PP
Remember that expressions like \f(CW\*(C`a > b\*(C'\fR are valid term expressions, so the
contents of this scope shouldn't allow arbitrary expressions or the closing
bracket will be ambiguous.
.SS "XPK_PARENS_OPT, XPK_BRACKETS_OPT, XPK_BRACES_OPT, XPK_CHEVRONS_OPT"
.IX Subsection "XPK_PARENS_OPT, XPK_BRACKETS_OPT, XPK_BRACES_OPT, XPK_CHEVRONS_OPT"
\&\fIstructural, can probe, emits i.\fR
.PP
.Vb 4
\&   XPK_PARENS_OPT(pieces ...)
\&   XPK_BRACKETS_OPT(pieces ...)
\&   XPK_BRACES_OPT(pieces ...)
\&   XPK_CHEVERONS_OPT(pieces ...)
.Ve
.PP
Each of the four contained structure macros above has an optional variant,
whose name is suffixed by \f(CW\*(C`_OPT\*(C'\fR. These pass an argument whose \fIi\fR field is
either true or false, indicating whether the scope was found, followed by the
values from the scope itself.
.PP
This is a convenient shortcut to nesting the scope within a \f(CW\*(C`XPK_OPTIONAL\*(C'\fR
macro.
.SS XPK_..._pieces
.IX Subsection "XPK_..._pieces"
.Vb 3
\&   XPK_SEQUENCE_pieces(ptr)
\&   XPK_OPTIONAL_pieces(ptr)
\&   ...
.Ve
.PP
For each of the \f(CW\*(C`XPK_...\*(C'\fR macros that takes a variable-length list of pieces,
there is a variant whose name ends with \f(CW\*(C`..._pieces\*(C'\fR, taking a single pointer
argument directly. This must point at a \f(CW\*(C`const XSParseKeywordPieceType []\*(C'\fR
array whose final element is the zero element.
.PP
Normally hand-written C code of a fixed grammar would be unlikely to use these
forms, but they may be useful in dynamically-generated cases.
.SH AUTHOR
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>