/*
=for apidoc Amx|SV *|cophh_fetch_pvn|const COPHH *cophh|const char *keypv|STRLEN keylen|U32 hash|U32 flags
-Look up the entry in the cop hints hash I<cophh> with the key specified by
-I<keypv> and I<keylen>. If I<flags> has the C<COPHH_KEY_UTF8> bit set,
+Look up the entry in the cop hints hash C<cophh> with the key specified by
+C<keypv> and C<keylen>. If C<flags> has the C<COPHH_KEY_UTF8> bit set,
the key octets are interpreted as UTF-8, otherwise they are interpreted
-as Latin-1. I<hash> is a precomputed hash of the key string, or zero if
+as Latin-1. C<hash> is a precomputed hash of the key string, or zero if
it has not been precomputed. Returns a mortal scalar copy of the value
associated with the key, or C<&PL_sv_placeholder> if there is no value
associated with the key.
=for apidoc Amx|HV *|cophh_2hv|const COPHH *cophh|U32 flags
Generates and returns a standard Perl hash representing the full set of
-key/value pairs in the cop hints hash I<cophh>. I<flags> is currently
+key/value pairs in the cop hints hash C<cophh>. C<flags> is currently
unused and must be zero.
=cut
/*
=for apidoc Amx|COPHH *|cophh_copy|COPHH *cophh
-Make and return a complete copy of the cop hints hash I<cophh>.
+Make and return a complete copy of the cop hints hash C<cophh>.
=cut
*/
/*
=for apidoc Amx|void|cophh_free|COPHH *cophh
-Discard the cop hints hash I<cophh>, freeing all resources associated
+Discard the cop hints hash C<cophh>, freeing all resources associated
with it.
=cut
/*
=for apidoc Amx|COPHH *|cophh_store_pvn|COPHH *cophh|const char *keypv|STRLEN keylen|U32 hash|SV *value|U32 flags
-Stores a value, associated with a key, in the cop hints hash I<cophh>,
+Stores a value, associated with a key, in the cop hints hash C<cophh>,
and returns the modified hash. The returned hash pointer is in general
not the same as the hash pointer that was passed in. The input hash is
consumed by the function, and the pointer to it must not be subsequently
used. Use L</cophh_copy> if you need both hashes.
-The key is specified by I<keypv> and I<keylen>. If I<flags> has the
+The key is specified by C<keypv> and C<keylen>. If C<flags> has the
C<COPHH_KEY_UTF8> bit set, the key octets are interpreted as UTF-8,
-otherwise they are interpreted as Latin-1. I<hash> is a precomputed
+otherwise they are interpreted as Latin-1. C<hash> is a precomputed
hash of the key string, or zero if it has not been precomputed.
-I<value> is the scalar value to store for this key. I<value> is copied
+C<value> is the scalar value to store for this key. C<value> is copied
by this function, which thus does not take ownership of any reference
to it, and later changes to the scalar will not be reflected in the
value visible in the cop hints hash. Complex types of scalar will not
/*
=for apidoc Amx|COPHH *|cophh_delete_pvn|COPHH *cophh|const char *keypv|STRLEN keylen|U32 hash|U32 flags
-Delete a key and its associated value from the cop hints hash I<cophh>,
+Delete a key and its associated value from the cop hints hash C<cophh>,
and returns the modified hash. The returned hash pointer is in general
not the same as the hash pointer that was passed in. The input hash is
consumed by the function, and the pointer to it must not be subsequently
used. Use L</cophh_copy> if you need both hashes.
-The key is specified by I<keypv> and I<keylen>. If I<flags> has the
+The key is specified by C<keypv> and C<keylen>. If C<flags> has the
C<COPHH_KEY_UTF8> bit set, the key octets are interpreted as UTF-8,
-otherwise they are interpreted as Latin-1. I<hash> is a precomputed
+otherwise they are interpreted as Latin-1. C<hash> is a precomputed
hash of the key string, or zero if it has not been precomputed.
=cut
/*
=for apidoc Am|SV *|cop_hints_fetch_pvn|const COP *cop|const char *keypv|STRLEN keylen|U32 hash|U32 flags
-Look up the hint entry in the cop I<cop> with the key specified by
-I<keypv> and I<keylen>. If I<flags> has the C<COPHH_KEY_UTF8> bit set,
+Look up the hint entry in the cop C<cop> with the key specified by
+C<keypv> and C<keylen>. If C<flags> has the C<COPHH_KEY_UTF8> bit set,
the key octets are interpreted as UTF-8, otherwise they are interpreted
-as Latin-1. I<hash> is a precomputed hash of the key string, or zero if
+as Latin-1. C<hash> is a precomputed hash of the key string, or zero if
it has not been precomputed. Returns a mortal scalar copy of the value
associated with the key, or C<&PL_sv_placeholder> if there is no value
associated with the key.
=for apidoc Am|HV *|cop_hints_2hv|const COP *cop|U32 flags
Generates and returns a standard Perl hash representing the full set of
-hint entries in the cop I<cop>. I<flags> is currently unused and must
+hint entries in the cop C<cop>. C<flags> is currently unused and must
be zero.
=cut
/*
=for apidoc Am|HV *|hv_copy_hints_hv|HV *ohv
-A specialised version of L</newHVhv> for copying C<%^H>. I<ohv> must be
+A specialised version of L</newHVhv> for copying C<%^H>. C<ohv> must be
a pointer to a hash (which may have C<%^H> magic, but should be generally
non-magical), or C<NULL> (interpreted as an empty hash). The content
-of I<ohv> is copied to a new hash, which has the C<%^H>-specific magic
+of C<ohv> is copied to a new hash, which has the C<%^H>-specific magic
added to it. A pointer to the new hash is returned.
=cut
Generates and returns a C<HV *> representing the content of a
C<refcounted_he> chain.
-I<flags> is currently unused and must be zero.
+C<flags> is currently unused and must be zero.
=cut
*/
=for apidoc m|SV *|refcounted_he_fetch_pvn|const struct refcounted_he *chain|const char *keypv|STRLEN keylen|U32 hash|U32 flags
Search along a C<refcounted_he> chain for an entry with the key specified
-by I<keypv> and I<keylen>. If I<flags> has the C<REFCOUNTED_HE_KEY_UTF8>
+by C<keypv> and C<keylen>. If C<flags> has the C<REFCOUNTED_HE_KEY_UTF8>
bit set, the key octets are interpreted as UTF-8, otherwise they
-are interpreted as Latin-1. I<hash> is a precomputed hash of the key
+are interpreted as Latin-1. C<hash> is a precomputed hash of the key
string, or zero if it has not been precomputed. Returns a mortal scalar
representing the value associated with the key, or C<&PL_sv_placeholder>
if there is no value associated with the key.
the new key/value pair takes precedence over any entry for the same key
further along the chain.
-The new key is specified by I<keypv> and I<keylen>. If I<flags> has
+The new key is specified by C<keypv> and C<keylen>. If C<flags> has
the C<REFCOUNTED_HE_KEY_UTF8> bit set, the key octets are interpreted
-as UTF-8, otherwise they are interpreted as Latin-1. I<hash> is
+as UTF-8, otherwise they are interpreted as Latin-1. C<hash> is
a precomputed hash of the key string, or zero if it has not been
precomputed.
-I<value> is the scalar value to store for this key. I<value> is copied
+C<value> is the scalar value to store for this key. C<value> is copied
by this function, which thus does not take ownership of any reference
to it, and later changes to the scalar will not be reflected in the
value visible in the C<refcounted_he>. Complex types of scalar will not
be stored with referential integrity, but will be coerced to strings.
-I<value> may be either null or C<&PL_sv_placeholder> to indicate that no
+C<value> may be either null or C<&PL_sv_placeholder> to indicate that no
value is to be associated with the key; this, as with any non-null value,
takes precedence over the existence of a value for the key further along
the chain.
-
I<parent> points to the rest of the C<refcounted_he> chain to be
+
C<parent> points to the rest of the C<refcounted_he> chain to be
attached to the new C<refcounted_he>. This function takes ownership
-of one reference to
I<parent>, and returns one reference to the new
+of one reference to
C<parent>, and returns one reference to the new
C<refcounted_he>.
=cut
/*
=for apidoc Am|HV *|pad_compname_type|PADOFFSET po
-Looks up the type of the lexical variable at position
I<po> in the
+Looks up the type of the lexical variable at position
C<po> in the
currently-compiling pad. If the variable is typed, the stash of the
class to which it is typed is returned. If not, C<NULL> is returned.
/*
=for apidoc Am|void|mg_free_type|SV *sv|int how
-Remove any magic of type I<how> from the SV I<sv>. See L</sv_magic>.
+Remove any magic of type C<how> from the SV C<sv>. See L</sv_magic>.
=cut
*/
converts a string representing a binary number to numeric form.
-On entry I<start> and I<*len> give the string to scan, I<*flags> gives
-conversion flags, and I<result> should be NULL or a pointer to an NV.
+On entry C<start> and C<*len> give the string to scan, C<*flags> gives
+conversion flags, and C<result> should be NULL or a pointer to an NV.
The scan stops at the end of the string, or the first invalid character.
-Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in C<*flags>, encountering an
invalid character will also trigger a warning.
-On return I<*len> is set to the length of the scanned string,
-and I<*flags> gives output flags.
+On return C<*len> is set to the length of the scanned string,
+and C<*flags> gives output flags.
If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
+and nothing is written to C<*result>. If the value is > UV_MAX C<grok_bin>
returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
-and writes the value to I<*result> (or the value is discarded if I<result>
+and writes the value to C<*result> (or the value is discarded if C<result>
is NULL).
The binary number may optionally be prefixed with "0b" or "b" unless
-C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
-C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
+C<PERL_SCAN_DISALLOW_PREFIX> is set in C<*flags> on entry. If
+C<PERL_SCAN_ALLOW_UNDERSCORES> is set in C<*flags> then the binary
number may use '_' characters to separate digits.
=cut
converts a string representing a hex number to numeric form.
-On entry I<start> and I<*len_p> give the string to scan, I<*flags> gives
-conversion flags, and I<result> should be NULL or a pointer to an NV.
+On entry C<start> and C<*len_p> give the string to scan, C<*flags> gives
+conversion flags, and C<result> should be NULL or a pointer to an NV.
The scan stops at the end of the string, or the first invalid character.
-Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in C<*flags>, encountering an
invalid character will also trigger a warning.
-On return I<*len> is set to the length of the scanned string,
-and I<*flags> gives output flags.
+On return C<*len> is set to the length of the scanned string,
+and C<*flags> gives output flags.
If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
+and nothing is written to C<*result>. If the value is > UV_MAX C<grok_hex>
returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
-and writes the value to I<*result> (or the value is discarded if I<result>
+and writes the value to C<*result> (or the value is discarded if C<result>
is NULL).
The hex number may optionally be prefixed with "0x" or "x" unless
-C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
-C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
+C<PERL_SCAN_DISALLOW_PREFIX> is set in C<*flags> on entry. If
+C<PERL_SCAN_ALLOW_UNDERSCORES> is set in C<*flags> then the hex
number may use '_' characters to separate digits.
=cut
converts a string representing an octal number to numeric form.
-On entry I<start> and I<*len> give the string to scan, I<*flags> gives
-conversion flags, and I<result> should be NULL or a pointer to an NV.
+On entry C<start> and C<*len> give the string to scan, C<*flags> gives
+conversion flags, and C<result> should be NULL or a pointer to an NV.
The scan stops at the end of the string, or the first invalid character.
-Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in C<*flags>, encountering an
8 or 9 will also trigger a warning.
-On return I<*len> is set to the length of the scanned string,
-and I<*flags> gives output flags.
+On return C<*len> is set to the length of the scanned string,
+and C<*flags> gives output flags.
If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
+and nothing is written to C<*result>. If the value is > UV_MAX C<grok_oct>
returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
-and writes the value to I<*result> (or the value is discarded if I<result>
+and writes the value to C<*result> (or the value is discarded if C<result>
is NULL).
-If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
+If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in C<*flags> then the octal
number may use '_' characters to separate digits.
=cut
=for apidoc Am|OP *|op_contextualize|OP *o|I32 context
Applies a syntactic context to an op tree representing an expression.
-I<o> is the op tree, and I<context> must be C<G_SCALAR>, C<G_ARRAY>,
+C<o> is the op tree, and C<context> must be C<G_SCALAR>, C<G_ARRAY>,
or C<G_VOID> to specify the context to apply. The modified op tree
is returned.
=for apidoc Amx|OP *|op_lvalue|OP *o|I32 type
Propagate lvalue ("modifiable") context to an op and its children.
-I<type> represents the context type, roughly based on the type of op that
+C<type> represents the context type, roughly based on the type of op that
would do the modifying, although C<local()> is represented by OP_NULL,
because it has no op type of its own (it is signalled by a flag on
the lvalue op).
/*
=for apidoc Am|OP *|block_end|I32 floor|OP *seq
-Handles compile-time scope exit. I<floor>
+Handles compile-time scope exit. C<floor>
is the savestack index returned by
-C<block_start>, and I<seq> is the body of the block. Returns the block,
+C<block_start>, and C<seq> is the body of the block. Returns the block,
possibly modified.
=cut
=for apidoc Am|OP *|op_append_elem|I32 optype|OP *first|OP *last
Append an item to the list of ops contained directly within a list-type
-op, returning the lengthened list. I<first> is the list-type op,
-and I<last> is the op to append to the list. I<optype> specifies the
-intended opcode for the list. If I<first> is not already a list of the
-right type, it will be upgraded into one. If either I<first> or I<last>
+op, returning the lengthened list. C<first> is the list-type op,
+and C<last> is the op to append to the list. C<optype> specifies the
+intended opcode for the list. If C<first> is not already a list of the
+right type, it will be upgraded into one. If either C<first> or C<last>
is null, the other is returned unchanged.
=cut
=for apidoc Am|OP *|op_append_list|I32 optype|OP *first|OP *last
Concatenate the lists of ops contained directly within two list-type ops,
-returning the combined list. I<first> and I<last> are the list-type ops
-to concatenate. I<optype> specifies the intended opcode for the list.
-If either I<first> or I<last> is not already a list of the right type,
-it will be upgraded into one. If either I<first> or I<last> is null,
+returning the combined list. C<first> and C<last> are the list-type ops
+to concatenate. C<optype> specifies the intended opcode for the list.
+If either C<first> or C<last> is not already a list of the right type,
+it will be upgraded into one. If either C<first> or C<last> is null,
the other is returned unchanged.
=cut
=for apidoc Am|OP *|op_prepend_elem|I32 optype|OP *first|OP *last
Prepend an item to the list of ops contained directly within a list-type
-op, returning the lengthened list. I<first> is the op to prepend to the
-list, and I<last> is the list-type op. I<optype> specifies the intended
-opcode for the list. If I<last> is not already a list of the right type,
-it will be upgraded into one. If either I<first> or I<last> is null,
+op, returning the lengthened list. C<first> is the op to prepend to the
+list, and C<last> is the list-type op. C<optype> specifies the intended
+opcode for the list. If C<last> is not already a list of the right type,
+it will be upgraded into one. If either C<first> or C<last> is null,
the other is returned unchanged.
=cut
/*
=for apidoc Am|OP *|op_convert_list|I32 type|I32 flags|OP *o
-Converts I<o> into a list op if it is not one already, and then converts it
-into the specified I<type>, calling its check function, allocating a target if
+Converts C<o> into a list op if it is not one already, and then converts it
+into the specified C<type>, calling its check function, allocating a target if
it needs one, and folding constants.
A list-type op is usually constructed one kid at a time via C<newLISTOP>,
/*
=for apidoc Am|OP *|newLISTOP|I32 type|I32 flags|OP *first|OP *last
-Constructs, checks, and returns an op of any list type. I<type> is
-the opcode. I<flags> gives the eight bits of C<op_flags>, except that
-C<OPf_KIDS> will be set automatically if required. I<first> and I<last>
+Constructs, checks, and returns an op of any list type. C<type> is
+the opcode. C<flags> gives the eight bits of C<op_flags>, except that
+C<OPf_KIDS> will be set automatically if required. C<first> and C<last>
supply up to two ops to be direct children of the list op; they are
consumed by this function and become part of the constructed op tree.
=for apidoc Am|OP *|newOP|I32 type|I32 flags
Constructs, checks, and returns an op of any base type (any type that
-has no extra fields). I<type> is the opcode. I<flags> gives the
+has no extra fields). C<type> is the opcode. C<flags> gives the
eight bits of C<op_flags>, and, shifted up eight bits, the eight bits
of C<op_private>.
/*
=for apidoc Am|OP *|newUNOP|I32 type|I32 flags|OP *first
-Constructs, checks, and returns an op of any unary type. I<type> is
-the opcode. I<flags> gives the eight bits of C<op_flags>, except that
+Constructs, checks, and returns an op of any unary type. C<type> is
+the opcode. C<flags> gives the eight bits of C<op_flags>, except that
C<OPf_KIDS> will be set automatically if required, and, shifted up eight
bits, the eight bits of C<op_private>, except that the bit with value 1
-is automatically set. I<first> supplies an optional op to be the direct
+is automatically set. C<first> supplies an optional op to be the direct
child of the unary op; it is consumed by this function and become part
of the constructed op tree.
=for apidoc Am|OP *|newMETHOP|I32 type|I32 flags|OP *first
Constructs, checks, and returns an op of method type with a method name
-evaluated at runtime. I<type> is the opcode. I<flags> gives the eight
+evaluated at runtime. C<type> is the opcode. C<flags> gives the eight
bits of C<op_flags>, except that C<OPf_KIDS> will be set automatically,
and, shifted up eight bits, the eight bits of C<op_private>, except that
-the bit with value 1 is automatically set. I<dynamic_meth> supplies an
+the bit with value 1 is automatically set. C<dynamic_meth> supplies an
op which evaluates method name; it is consumed by this function and
become part of the constructed op tree.
Supported optypes: OP_METHOD.
=for apidoc Am|OP *|newMETHOP_named|I32 type|I32 flags|SV *const_meth
Constructs, checks, and returns an op of method type with a constant
-method name. I<type> is the opcode. I<flags> gives the eight bits of
+method name. C<type> is the opcode. C<flags> gives the eight bits of
C<op_flags>, and, shifted up eight bits, the eight bits of
-C<op_private>. I<const_meth> supplies a constant method name;
+C<op_private>. C<const_meth> supplies a constant method name;
it must be a shared COW string.
Supported optypes: OP_METHOD_NAMED.
/*
=for apidoc Am|OP *|newBINOP|I32 type|I32 flags|OP *first|OP *last
-Constructs, checks, and returns an op of any binary type. I<type>
-is the opcode. I<flags> gives the eight bits of C<op_flags>, except
+Constructs, checks, and returns an op of any binary type. C<type>
+is the opcode. C<flags> gives the eight bits of C<op_flags>, except
that C<OPf_KIDS> will be set automatically, and, shifted up eight bits,
the eight bits of C<op_private>, except that the bit with value 1 or
-2 is automatically set as required. I<first> and I<last> supply up to
+2 is automatically set as required. C<first> and C<last> supply up to
two ops to be the direct children of the binary op; they are consumed
by this function and become part of the constructed op tree.
=for apidoc Am|OP *|newPMOP|I32 type|I32 flags
Constructs, checks, and returns an op of any pattern matching type.
-I<type> is the opcode. I<flags> gives the eight bits of C<op_flags>
+C<type> is the opcode. C<flags> gives the eight bits of C<op_flags>
and, shifted up eight bits, the eight bits of C<op_private>.
=cut
=for apidoc Am|OP *|newSVOP|I32 type|I32 flags|SV *sv
Constructs, checks, and returns an op of any type that involves an
-embedded SV. I<type> is the opcode. I<flags> gives the eight bits
-of C<op_flags>. I<sv> gives the SV to embed in the op; this function
+embedded SV. C<type> is the opcode. C<flags> gives the eight bits
+of C<op_flags>. C<sv> gives the SV to embed in the op; this function
takes ownership of one reference to it.
=cut
=for apidoc Am|OP *|newPADOP|I32 type|I32 flags|SV *sv
Constructs, checks, and returns an op of any type that involves a
-reference to a pad element. I<type> is the opcode. I<flags> gives the
+reference to a pad element. C<type> is the opcode. C<flags> gives the
eight bits of C<op_flags>. A pad slot is automatically allocated, and
-is populated with I<sv>; this function takes ownership of one reference
+is populated with C<sv>; this function takes ownership of one reference
to it.
This function only exists if Perl has been compiled to use ithreads.
=for apidoc Am|OP *|newGVOP|I32 type|I32 flags|GV *gv
Constructs, checks, and returns an op of any type that involves an
-embedded reference to a GV. I<type> is the opcode. I<flags> gives the
-eight bits of C<op_flags>. I<gv> identifies the GV that the op should
+embedded reference to a GV. C<type> is the opcode. C<flags> gives the
+eight bits of C<op_flags>. C<gv> identifies the GV that the op should
reference; calling this function does not transfer ownership of any
reference to it.
=for apidoc Am|OP *|newPVOP|I32 type|I32 flags|char *pv
Constructs, checks, and returns an op of any type that involves an
-embedded C-level pointer (PV). I<type> is the opcode. I<flags> gives
-the eight bits of C<op_flags>.
I<pv> supplies the C-level pointer, which
+embedded C-level pointer (PV). C<type> is the opcode. C<flags> gives
+the eight bits of C<op_flags>.
C<pv> supplies the C-level pointer, which
must have been allocated using C<PerlMemShared_malloc>; the memory will
be freed when the op is destroyed.
=for apidoc Am|OP *|newSLICEOP|I32 flags|OP *subscript|OP *listval
-Constructs, checks, and returns an C<lslice> (list slice) op. I<flags>
+Constructs, checks, and returns an C<lslice> (list slice) op. C<flags>
gives the eight bits of C<op_flags>, except that C<OPf_KIDS> will
be set automatically, and, shifted up eight bits, the eight bits of
C<op_private>, except that the bit with value 1 or 2 is automatically
-set as required. I<listval> and I<subscript> supply the parameters of
+set as required. C<listval> and C<subscript> supply the parameters of
the slice; they are consumed by this function and become part of the
constructed op tree.
/*
=for apidoc Am|OP *|newASSIGNOP|I32 flags|OP *left|I32 optype|OP *right
-Constructs, checks, and returns an assignment op. I<left> and I<right>
+Constructs, checks, and returns an assignment op. C<left> and C<right>
supply the parameters of the assignment; they are consumed by this
function and become part of the constructed op tree.
-If I<optype> is C<OP_ANDASSIGN>, C<OP_ORASSIGN>, or C<OP_DORASSIGN>, then
-a suitable conditional optree is constructed. If I<optype> is the opcode
+If C<optype> is C<OP_ANDASSIGN>, C<OP_ORASSIGN>, or C<OP_DORASSIGN>, then
+a suitable conditional optree is constructed. If C<optype> is the opcode
of a binary operator, such as C<OP_BIT_OR>, then an op is constructed that
performs the binary operation and assigns the result to the left argument.
-Either way, if I<optype> is non-zero then I<flags> has no effect.
+Either way, if C<optype> is non-zero then C<flags> has no effect.
-If I<optype> is zero, then a plain scalar or list assignment is
+If C<optype> is zero, then a plain scalar or list assignment is
constructed. Which type of assignment it is is automatically determined.
-I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS>
+C<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS>
will be set automatically, and, shifted up eight bits, the eight bits
of C<op_private>, except that the bit with value 1 or 2 is automatically
set as required.
Constructs a state op (COP). The state op is normally a C<nextstate> op,
but will be a C<dbstate> op if debugging is enabled for currently-compiled
code. The state op is populated from C<PL_curcop> (or C<PL_compiling>).
-If I<label> is non-null, it supplies the name of a label to attach to
+If C<label> is non-null, it supplies the name of a label to attach to
the state op; this function takes ownership of the memory pointed at by
-I<label>, and will free it. I<flags> gives the eight bits of C<op_flags>
+C<label>, and will free it. C<flags> gives the eight bits of C<op_flags>
for the state op.
-If I<o> is null, the state op is returned. Otherwise the state op is
-combined with I<o> into a C<lineseq> list op, which is returned. I<o>
+If C<o> is null, the state op is returned. Otherwise the state op is
+combined with C<o> into a C<lineseq> list op, which is returned. C<o>
is consumed by this function and becomes part of the returned op tree.
=cut
/*
=for apidoc Am|OP *|newLOGOP|I32 type|I32 flags|OP *first|OP *other
-Constructs, checks, and returns a logical (flow control) op. I<type>
-is the opcode. I<flags> gives the eight bits of C<op_flags>, except
+Constructs, checks, and returns a logical (flow control) op. C<type>
+is the opcode. C<flags> gives the eight bits of C<op_flags>, except
that C<OPf_KIDS> will be set automatically, and, shifted up eight bits,
the eight bits of C<op_private>, except that the bit with value 1 is
-automatically set. I<first> supplies the expression controlling the
-flow, and I<other> supplies the side (alternate) chain of ops; they are
+automatically set. C<first> supplies the expression controlling the
+flow, and C<other> supplies the side (alternate) chain of ops; they are
consumed by this function and become part of the constructed op tree.
=cut
=for apidoc Am|OP *|newCONDOP|I32 flags|OP *first|OP *trueop|OP *falseop
Constructs, checks, and returns a conditional-expression (C<cond_expr>)
-op. I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS>
+op. C<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS>
will be set automatically, and, shifted up eight bits, the eight bits of
C<op_private>, except that the bit with value 1 is automatically set.
-I<first> supplies the expression selecting between the two branches,
-and I<trueop> and I<falseop> supply the branches; they are consumed by
+C<first> supplies the expression selecting between the two branches,
+and C<trueop> and C<falseop> supply the branches; they are consumed by
this function and become part of the constructed op tree.
=cut
=for apidoc Am|OP *|newRANGE|I32 flags|OP *left|OP *right
Constructs and returns a C<range> op, with subordinate C<flip> and
-C<flop> ops. I<flags> gives the eight bits of C<op_flags> for the
+C<flop> ops. C<flags> gives the eight bits of C<op_flags> for the
C<flip> op and, shifted up eight bits, the eight bits of C<op_private>
for both the C<flip> and C<range> ops, except that the bit with value
-1 is automatically set. I<left> and I<right> supply the expressions
+1 is automatically set. C<left> and C<right> supply the expressions
controlling the endpoints of the range; they are consumed by this function
and become part of the constructed op tree.
Constructs, checks, and returns an op tree expressing a loop. This is
only a loop in the control flow through the op tree; it does not have
the heavyweight loop structure that allows exiting the loop by C<last>
-and suchlike. I<flags> gives the eight bits of C<op_flags> for the
+and suchlike. C<flags> gives the eight bits of C<op_flags> for the
top-level op, except that some bits will be set automatically as required.
-I<expr> supplies the expression controlling loop iteration, and I<block>
+C<expr> supplies the expression controlling loop iteration, and C<block>
supplies the body of the loop; they are consumed by this function and
-become part of the constructed op tree. I<debuggable> is currently
+become part of the constructed op tree. C<debuggable> is currently
unused and should always be 1.
=cut
This is a heavyweight loop, with structure that allows exiting the loop
by C<last> and suchlike.
-I<loop> is an optional preconstructed C<enterloop> op to use in the
+C<loop> is an optional preconstructed C<enterloop> op to use in the
loop; if it is null then a suitable op will be constructed automatically.
-I<expr> supplies the loop's controlling expression. I<block> supplies the
-main body of the loop, and I<cont> optionally supplies a C<continue> block
+C<expr> supplies the loop's controlling expression. C<block> supplies the
+main body of the loop, and C<cont> optionally supplies a C<continue> block
that operates as a second half of the body. All of these optree inputs
are consumed by this function and become part of the constructed op tree.
-I<flags> gives the eight bits of C<op_flags> for the C<leaveloop>
+C<flags> gives the eight bits of C<op_flags> for the C<leaveloop>
op and, shifted up eight bits, the eight bits of C<op_private> for
the C<leaveloop> op, except that (in both cases) some bits will be set
-automatically. I<debuggable> is currently unused and should always be 1.
-I<has_my> can be supplied as true to force the
+automatically. C<debuggable> is currently unused and should always be 1.
+C<has_my> can be supplied as true to force the
loop body to be enclosed in its own scope.
=cut
loop (iteration through a list of values). This is a heavyweight loop,
with structure that allows exiting the loop by C<last> and suchlike.
-I<sv> optionally supplies the variable that will be aliased to each
+C<sv> optionally supplies the variable that will be aliased to each
item in turn; if null, it defaults to C<$_> (either lexical or global).
-I<expr> supplies the list of values to iterate over. I<block> supplies
-the main body of the loop, and I<cont> optionally supplies a C<continue>
+C<expr> supplies the list of values to iterate over. C<block> supplies
+the main body of the loop, and C<cont> optionally supplies a C<continue>
block that operates as a second half of the body. All of these optree
inputs are consumed by this function and become part of the constructed
op tree.
-I<flags> gives the eight bits of C<op_flags> for the C<leaveloop>
+C<flags> gives the eight bits of C<op_flags> for the C<leaveloop>
op and, shifted up eight bits, the eight bits of C<op_private> for
the C<leaveloop> op, except that (in both cases) some bits will be set
automatically.
=for apidoc Am|OP *|newLOOPEX|I32 type|OP *label
Constructs, checks, and returns a loop-exiting op (such as C<goto>
-or C<last>). I<type> is the opcode. I<label> supplies the parameter
+or C<last>). C<type> is the opcode. C<label> supplies the parameter
determining the target of the op; it is consumed by this function and
becomes part of the constructed op tree.
=for apidoc Am|OP *|newGIVENOP|OP *cond|OP *block|PADOFFSET defsv_off
Constructs, checks, and returns an op tree expressing a C<given> block.
-I<cond> supplies the expression that will be locally assigned to a lexical
-variable, and I<block> supplies the body of the C<given> construct; they
+C<cond> supplies the expression that will be locally assigned to a lexical
+variable, and C<block> supplies the body of the C<given> construct; they
are consumed by this function and become part of the constructed op tree.
-I<defsv_off> is the pad offset of the scalar lexical variable that will
+C<defsv_off> is the pad offset of the scalar lexical variable that will
be affected. If it is 0, the global $_ will be used.
=cut
=for apidoc Am|OP *|newWHENOP|OP *cond|OP *block
Constructs, checks, and returns an op tree expressing a C<when> block.
-I<cond> supplies the test expression, and I<block> supplies the block
+C<cond> supplies the test expression, and C<block> supplies the block
that will be executed if the test evaluates to true; they are consumed
-by this function and become part of the constructed op tree. I<cond>
+by this function and become part of the constructed op tree. C<cond>
will be interpreted DWIMically, often as a comparison against C<$_>,
and may be null to generate a C<default> block.
/*
=for apidoc U||newXS
-Used by C<xsubpp> to hook up XSUBs as Perl subs. I<filename> needs to be
+Used by C<xsubpp> to hook up XSUBs as Perl subs. C<filename> needs to be
static storage, as it is used directly as CvFILE(), without a copy being made.
=cut
Examines an op, which is expected to identify a subroutine at runtime,
and attempts to determine at compile time which subroutine it identifies.
This is normally used during Perl compilation to determine whether
-a prototype can be applied to a function call. I<cvop> is the op
+a prototype can be applied to a function call. C<cvop> is the op
being considered, normally an C<rv2cv> op. A pointer to the identified
subroutine is returned, if it could be determined statically, and a null
pointer is returned if it was not possible to determine statically.
the subroutine statically: this flag is used to suppress compile-time
magic on a subroutine call, forcing it to use default runtime behaviour.
-If I<flags> has the bit C<RV2CVOPCV_MARK_EARLY> set, then the handling
+If C<flags> has the bit C<RV2CVOPCV_MARK_EARLY> set, then the handling
of a GV reference is modified. If a GV was examined and its CV slot was
found to be empty, then the C<gv> op has the C<OPpEARLY_CV> flag set.
If the op is not optimised away, and the CV slot is later populated with
a subroutine having a prototype, that flag eventually triggers the warning
"called too early to check prototype".
-If I<flags> has the bit C<RV2CVOPCV_RETURN_NAME_GV> set, then instead
+If C<flags> has the bit C<RV2CVOPCV_RETURN_NAME_GV> set, then instead
of returning a pointer to the subroutine it returns a pointer to the
GV giving the most appropriate name for the subroutine in this context.
Normally this is just the C<CvGV> of the subroutine, but for an anonymous
not marked with C<&>, where the callee can be identified at compile time
and has a prototype.
-
I<protosv> supplies the subroutine prototype to be applied to the call.
+
C<protosv> supplies the subroutine prototype to be applied to the call.
It may be a normal defined scalar, of which the string value will be used.
Alternatively, for convenience, it may be a subroutine object (a C<CV*>
that has been cast to C<SV*>) which has a prototype. The prototype
The error is reflected in the parser state, normally resulting in a single
exception at the top level of parsing which covers all the compilation
errors that occurred. In the error message, the callee is referred to
-by the name defined by the I<namegv> parameter.
+by the name defined by the C<namegv> parameter.
=cut
*/
This is the standard treatment used on a subroutine call, not marked
with C<&>, where the callee can be identified at compile time.
-
I<protosv> supplies the subroutine prototype to be applied to the call,
+
C<protosv> supplies the subroutine prototype to be applied to the call,
or indicates that there is no prototype. It may be a normal scalar,
in which case if it is defined then the string value will be used
as a prototype, and if it is undefined then there is no prototype.
The error is reflected in the parser state, normally resulting in a single
exception at the top level of parsing which covers all the compilation
errors that occurred. In the error message, the callee is referred to
-by the name defined by the I<namegv> parameter.
+by the name defined by the C<namegv> parameter.
=cut
*/
/*
=for apidoc Am|void|cv_get_call_checker|CV *cv|Perl_call_checker *ckfun_p|SV **ckobj_p
-Retrieves the function that will be used to fix up a call to I<cv>.
+Retrieves the function that will be used to fix up a call to C<cv>.
Specifically, the function is applied to an C<entersub> op tree for a
subroutine call, not marked with C<&>, where the callee can be identified
-at compile time as I<cv>.
+at compile time as C<cv>.
-The C-level function pointer is returned in I<*ckfun_p>, and an SV
-argument for it is returned in I<*ckobj_p>. The function is intended
+The C-level function pointer is returned in C<*ckfun_p>, and an SV
+argument for it is returned in C<*ckobj_p>. The function is intended
to be called in this manner:
entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
-In this call, I<entersubop> is a pointer to the C<entersub> op,
-which may be replaced by the check function, and I<namegv> is a GV
+In this call, C<entersubop> is a pointer to the C<entersub> op,
+which may be replaced by the check function, and C<namegv> is a GV
supplying the name that should be used by the check function to refer
to the callee of the C<entersub> op if it needs to emit any diagnostics.
It is permitted to apply the check function in non-standard situations,
By default, the function is
L<Perl_ck_entersub_args_proto_or_list|/ck_entersub_args_proto_or_list>,
-and the SV parameter is I<cv> itself. This implements standard
+and the SV parameter is C<cv> itself. This implements standard
prototype processing. It can be changed, for a particular subroutine,
by L</cv_set_call_checker>.
/*
=for apidoc Am|void|cv_set_call_checker_flags|CV *cv|Perl_call_checker ckfun|SV *ckobj|U32 flags
-Sets the function that will be used to fix up a call to I<cv>.
+Sets the function that will be used to fix up a call to C<cv>.
Specifically, the function is applied to an C<entersub> op tree for a
subroutine call, not marked with C<&>, where the callee can be identified
-at compile time as I<cv>.
+at compile time as C<cv>.
-The C-level function pointer is supplied in I<ckfun>, and an SV argument
-for it is supplied in I<ckobj>. The function should be defined like this:
+The C-level function pointer is supplied in C<ckfun>, and an SV argument
+for it is supplied in C<ckobj>. The function should be defined like this:
STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
-In this call, I<entersubop> is a pointer to the C<entersub> op,
-which may be replaced by the check function, and I<namegv> supplies
+In this call, C<entersubop> is a pointer to the C<entersub> op,
+which may be replaced by the check function, and C<namegv> supplies
the name that should be used by the check function to refer
to the callee of the C<entersub> op if it needs to emit any diagnostics.
It is permitted to apply the check function in non-standard situations,
such as to a call to a different subroutine or to a method call.
-I<namegv> may not actually be a GV. For efficiency, perl may pass a
+C<namegv> may not actually be a GV. For efficiency, perl may pass a
CV or other SV instead. Whatever is passed can be used as the first
argument to L</cv_name>. You can force perl to pass a GV by including
-C<CALL_CHECKER_REQUIRE_GV> in the I<flags>.
+C<CALL_CHECKER_REQUIRE_GV> in the C<flags>.
The current setting for a particular CV can be retrieved by
L</cv_get_call_checker>.
Puts a C function into the chain of check functions for a specified op
type. This is the preferred way to manipulate the L</PL_check> array.
-I<opcode> specifies which type of op is to be affected. I<new_checker>
+C<opcode> specifies which type of op is to be affected. C<new_checker>
is a pointer to the C function that is to be added to that opcode's
-check chain, and
I<old_checker_p> points to the storage location where a
+check chain, and
C<old_checker_p> points to the storage location where a
pointer to the next function in the chain will be stored. The value of
-I<new_pointer> is written into the L</PL_check> array, while the value
-previously stored there is written to I<*old_checker_p>.
+C<new_pointer> is written into the L</PL_check> array, while the value
+previously stored there is written to C<*old_checker_p>.
The function should be defined like this:
new_checker(aTHX_ op)
-
I<old_checker_p> should be defined like this:
+
C<old_checker_p> should be defined like this:
static Perl_check_t old_checker_p;
L</PL_check> is global to an entire process, and a module wishing to
hook op checking may find itself invoked more than once per process,
typically in different threads. To handle that situation, this function
-is idempotent. The location I<*old_checker_p> must initially (once
+is idempotent. The location C<*old_checker_p> must initially (once
per process) contain a null pointer. A C variable of static duration
(declared at file scope, typically also marked C<static> to give
it internal linkage) will be implicitly initialised appropriately,
if it does not have an explicit initialiser. This function will only
-actually modify the check chain if it finds I<*old_checker_p> to be null.
+actually modify the check chain if it finds C<*old_checker_p> to be null.
This function is also thread safe on the small scale. It uses appropriate
locking to avoid race conditions in accessing L</PL_check>.
-When this function is called, the function referenced by I<new_checker>
-must be ready to be called, except for I<*old_checker_p> being unfilled.
-In a threading situation, I<new_checker> may be called immediately,
-even before this function has returned. I<*old_checker_p> will always
-be appropriately set before I<new_checker> is called. If I<new_checker>
+When this function is called, the function referenced by C<new_checker>
+must be ready to be called, except for C<*old_checker_p> being unfilled.
+In a threading situation, C<new_checker> may be called immediately,
+even before this function has returned. C<*old_checker_p> will always
+be appropriately set before C<new_checker> is called. If C<new_checker>
decides not to do anything special with an op that it is given (which
is the usual case for most uses of op check hooking), it must chain the
-check function referenced by I<*old_checker_p>.
+check function referenced by C<*old_checker_p>.
If you want to influence compilation of calls to a specific subroutine,
then use L</cv_set_call_checker> rather than hooking checking of all
Given the root of an optree, link the tree in execution order using the
C<op_next> pointers and return the first op executed. If this has
already been done, it will not be redone, and C<< o->op_next >> will be
-returned. If C<< o->op_next >> is not already set, I<o> should be at
+returned. If C<< o->op_next >> is not already set, C<o> should be at
least an C<UNOP>.
=cut
Return the BHK's flags.
=for apidoc mx|void *|BhkENTRY|BHK *hk|which
-Return an entry from the BHK structure. I<which> is a preprocessor token
+Return an entry from the BHK structure. C<which> is a preprocessor token
indicating which entry to return. If the appropriate flag is not set
this will return NULL. The type of the return value depends on which
entry you ask for.
=for apidoc Amx|void|BhkENTRY_set|BHK *hk|which|void *ptr
Set an entry in the BHK structure, and set the flags to indicate it is
-valid. I<which> is a preprocessing token indicating which entry to set.
-The type of
I<ptr> depends on the entry.
+valid. C<which> is a preprocessing token indicating which entry to set.
+The type of
C<ptr> depends on the entry.
=for apidoc Amx|void|BhkDISABLE|BHK *hk|which
Temporarily disable an entry in this BHK structure, by clearing the
-appropriate flag. I<which> is a preprocessor token indicating which
+appropriate flag. C<which> is a preprocessor token indicating which
entry to disable.
=for apidoc Amx|void|BhkENABLE|BHK *hk|which
Re-enable an entry in this BHK structure, by setting the appropriate
-flag. I<which> is a preprocessor token indicating which entry to enable.
+flag. C<which> is a preprocessor token indicating which entry to enable.
This will assert (under -DDEBUGGING) if the entry doesn't contain a valid
pointer.
=for apidoc mx|void|CALL_BLOCK_HOOKS|which|arg
-Call all the registered block hooks for type I<which>. I<which> is a
-preprocessing token; the type of I<arg> depends on I<which>.
+Call all the registered block hooks for type C<which>. C<which> is a
+preprocessing token; the type of C<arg> depends on C<which>.
=cut
*/
Return the XOP's flags.
=for apidoc Am||XopENTRY|XOP *xop|which
-Return a member of the XOP structure. I<which> is a cpp token
+Return a member of the XOP structure. C<which> is a cpp token
indicating which entry to return. If the member is not set
this will return a default value. The return type depends
-on I<which>. This macro evaluates its arguments more than
+on C<which>. This macro evaluates its arguments more than
once. If you are using C<Perl_custom_op_xop> to retreive a
C<XOP *> from a C<OP *>, use the more efficient L</XopENTRYCUSTOM> instead.
=for apidoc Am||XopENTRYCUSTOM|const OP *o|which
Exactly like C<XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which)> but more
-efficient. The I<which> parameter is identical to L</XopENTRY>.
+efficient. The C<which> parameter is identical to L</XopENTRY>.
=for apidoc Am|void|XopENTRY_set|XOP *xop|which|value
-Set a member of the XOP structure. I<which> is a cpp token
+Set a member of the XOP structure. C<which> is a cpp token
indicating which entry to set. See L<perlguts/"Custom Operators">
for details about the available members and how
they are used. This macro evaluates its argument
Allocates a place in the currently-compiling
pad (via L<perlapi/pad_alloc>) and
-then stores a name for that entry. I<name> is adopted and
+then stores a name for that entry. C<name> is adopted and
becomes the name entry; it must already contain the name
-string.
I<typestash> and I<ourstash> and the C<padadd_STATE>
-flag get added to I<name>. None of the other
+string.
C<typestash> and C<ourstash> and the C<padadd_STATE>
+flag get added to C<name>. None of the other
processing of L<perlapi/pad_add_name_pvn>
is done. Returns the offset of the allocated pad slot.
pad, and makes preparations to manage the variable's lexical scoping.
Returns the offset of the allocated pad slot.
-I<namepv>/I<namelen> specify the variable's name, including leading sigil.
-If I<typestash> is non-null, the name is for a typed lexical, and this
-identifies the type. If I<ourstash> is non-null, it's a lexical reference
+C<namepv>/C<namelen> specify the variable's name, including leading sigil.
+If C<typestash> is non-null, the name is for a typed lexical, and this
+identifies the type. If C<ourstash> is non-null, it's a lexical reference
to a package variable, and this identifies the package. The following
flags can be OR'ed together:
Allocates a place in the currently-compiling pad,
returning the offset of the allocated pad slot.
No name is initially attached to the pad slot.
-I<tmptype> is a set of flags indicating the kind of pad entry required,
+C<tmptype> is a set of flags indicating the kind of pad entry required,
which will be set in the value SV for the allocated pad entry:
SVs_PADMY named lexical variable ("my", "our", "state")
tells C<pad_alloc> that it I<will> be made read-only (by the caller), or at
least should be treated as such.
-I<optype> should be an opcode indicating the type of operation that the
+C<optype> should be an opcode indicating the type of operation that the
pad entry is to support. This doesn't affect operational semantics,
but is used for debugging.
Allocates a place in the currently-compiling pad (via L</pad_alloc>)
for an anonymous function that is lexically scoped inside the
currently-compiling function.
-The function I<func> is linked into the pad, and its C<CvOUTSIDE> link
+The function C<func> is linked into the pad, and its C<CvOUTSIDE> link
to the outer scope is weakened to avoid a reference loop.
One reference count is stolen, so you may need to do C<SvREFCNT_inc(func)>.
-I<optype> should be an opcode indicating the type of operation that the
+C<optype> should be an opcode indicating the type of operation that the
pad entry is to support. This doesn't affect operational semantics,
but is used for debugging.
Given the name of a lexical variable, find its position in the
currently-compiling pad.
-I<namepv>/I<namelen> specify the variable's name, including leading sigil.
-I<flags> is reserved and must be zero.
+C<namepv>/C<namelen> specify the variable's name, including leading sigil.
+C<flags> is reserved and must be zero.
If it is not in the current pad but appears in the pad of any lexically
enclosing scope, then a pseudo-entry for it is added in the current pad.
Returns the offset in the current pad,
/*
=for apidoc Am|SV *|pad_sv|PADOFFSET po
-Get the value at offset
I<po> in the current (compiling or executing) pad.
+Get the value at offset
C<po> in the current (compiling or executing) pad.
Use macro PAD_SV instead of calling this function directly.
=cut
/*
=for apidoc Am|void|pad_setsv|PADOFFSET po|SV *sv
-Set the value at offset
I<po> in the current (compiling or executing) pad.
+Set the value at offset
C<po> in the current (compiling or executing) pad.
Use the macro PAD_SETSV() rather than calling this function directly.
=cut
Tidy up a pad at the end of compilation of the code to which it belongs.
Jobs performed here are: remove most stuff from the pads of anonsub
-prototypes; give it a @_; mark temporaries as such. I<type> indicates
+prototypes; give it a @_; mark temporaries as such. C<type> indicates
the kind of subroutine:
padtidy_SUB ordinary subroutine
/*
=for apidoc Am|CV *|cv_clone|CV *proto
-Clone a CV, making a lexical closure.
I<proto> supplies the prototype
+Clone a CV, making a lexical closure.
C<proto> supplies the prototype
of the function: its code, pad structure, and other attributes.
The prototype is combined with a capture of outer lexicals to which the
code refers, which are taken from the currently-executing instance of
to it and it will be returned. Otherwise the returned SV will be a new
mortal.
-If the I<flags> include CV_NAME_NOTQUAL, then the package name will not be
+If the C<flags> include CV_NAME_NOTQUAL, then the package name will not be
included. If the first argument is neither a CV nor a GV, this flag is
ignored (subject to change).
/*
=for apidoc newPADNAMEpvn
-Constructs and returns a new pad name. I<s> must be a UTF8 string. Do not
+Constructs and returns a new pad name. C<s> must be a UTF8 string. Do not
use this for pad names that point to outer lexicals. See
L</newPADNAMEouter>.
=for apidoc newPADNAMEouter
Constructs and returns a new pad name. Only use this function for names
-that refer to outer lexicals. (See also L</newPADNAMEpvn>.) I<outer> is
+that refer to outer lexicals. (See also L</newPADNAMEpvn>.) C<outer> is
the outer pad name that this one mirrors. The returned pad name has the
PADNAMEt_OUTER flag already set.
lenp is non-zero, it does the same to lenp, but this time starting from
the offset, rather than from the start
of the string. Handles type coercion.
-I<flags> is passed to C<SvPV_flags>, and usually should be
+C<flags> is passed to C<SvPV_flags>, and usually should be
C<SV_GMAGIC|SV_CONST_RETURN> to handle magic.
=cut
Converts the offset from a count of bytes from the start of the string, to
a count of the equivalent number of UTF-8 chars. Handles type coercion.
-I<flags> is passed to C<SvPV_flags>, and usually should be
+C<flags> is passed to C<SvPV_flags>, and usually should be
C<SV_GMAGIC|SV_CONST_RETURN> to handle magic.
=cut
SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
=for apidoc Am|SV*|SvREFCNT_inc_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you know I<sv>
+Same as SvREFCNT_inc, but can only be used if you know C<sv>
is not NULL. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|void|SvREFCNT_inc_void_NN|SV* sv
Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that I<sv> is not NULL. The macro doesn't need
+value, and you know that C<sv> is not NULL. The macro doesn't need
to return a meaningful value, or check for NULLness, so it's smaller
and faster.
effects. Since we don't have to store a temporary value, it's faster.
=for apidoc Am|SV*|SvREFCNT_inc_simple_NN|SV* sv
-Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
+Same as SvREFCNT_inc_simple, but can only be used if you know C<sv>
is not NULL. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|void|SvREFCNT_inc_simple_void_NN|SV* sv
Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that I<sv> is not NULL. The macro doesn't need
+value, and you know that C<sv> is not NULL. The macro doesn't need
to return a meaningful value, or check for NULLness, so it's smaller
and faster.
=for apidoc Am|void|SvREFCNT_dec|SV* sv
-Decrements the reference count of the given SV. I<sv> may be NULL.
+Decrements the reference count of the given SV. C<sv> may be NULL.
=for apidoc Am|void|SvREFCNT_dec_NN|SV* sv
-Same as SvREFCNT_dec, but can only be used if you know I<sv>
+Same as SvREFCNT_dec, but can only be used if you know C<sv>
is not NULL. Since we don't have to check the NULLness, it's faster
and smaller.
/*
=for apidoc Am|void|SvOOK_offset|NN SV*sv|STRLEN len
-Reads into I<len> the offset from SvPVX back to the true start of the
+Reads into C<len> the offset from SvPVX back to the true start of the
allocated buffer, which will be non-zero if C<sv_chop> has been used to
efficiently remove characters from start of the buffer. Implemented as a
-macro, which takes the address of I<len>, which must be of type C<STRLEN>.
-Evaluates I<sv> more than once. Sets I<len> to 0 if C<SvOOK(sv)> is false.
+macro, which takes the address of C<len>, which must be of type C<STRLEN>.
+Evaluates C<sv> more than once. Sets C<len> to 0 if C<SvOOK(sv)> is false.
=cut
*/
will be destroyed and the former value of L</PL_parser> will be restored.
Nothing else need be done to clean up the parsing context.
-The code to be parsed comes from I<line> and I<rsfp>. I<line>, if
+The code to be parsed comes from C<line> and C<rsfp>. C<line>, if
non-null, provides a string (in SV form) containing code to be parsed.
-A copy of the string is made, so subsequent modification of I<line>
-does not affect parsing. I<rsfp>, if non-null, provides an input stream
+A copy of the string is made, so subsequent modification of C<line>
+does not affect parsing. C<rsfp>, if non-null, provides an input stream
from which code will be read to be parsed. If both are non-null, the
-code in I<line> comes first and must consist of complete lines of input,
-and I<rsfp> supplies the remainder of the source.
+code in C<line> comes first and must consist of complete lines of input,
+and C<rsfp> supplies the remainder of the source.
-The I<flags> parameter is reserved for future use. Currently it is only
+The C<flags> parameter is reserved for future use. Currently it is only
used by perl internally, so extensions should always pass zero.
=cut
=for apidoc Amx|char *|lex_grow_linestr|STRLEN len
Reallocates the lexer buffer (L</PL_parser-E<gt>linestr>) to accommodate
-at least I<len> octets (including terminating C<NUL>). Returns a
+at least C<len> octets (including terminating C<NUL>). Returns a
pointer to the reallocated buffer. This is necessary before making
any direct modification of the buffer that would increase its length.
L</lex_stuff_pvn> provides a more convenient way to insert text into
uses of this facility run the risk of the inserted characters being
interpreted in an unintended manner.
-The string to be inserted is represented by I<len> octets starting
-at
I<pv>. These octets are interpreted as either UTF-8 or Latin-1,
-according to whether the C<LEX_STUFF_UTF8> flag is set in I<flags>.
+The string to be inserted is represented by C<len> octets starting
+at
C<pv>. These octets are interpreted as either UTF-8 or Latin-1,
+according to whether the C<LEX_STUFF_UTF8> flag is set in C<flags>.
The characters are recoded for the lexer buffer, according to how the
buffer is currently being interpreted (L</lex_bufutf8>). If a string
to be inserted is available as a Perl scalar, the L</lex_stuff_sv>
uses of this facility run the risk of the inserted characters being
interpreted in an unintended manner.
-The string to be inserted is represented by octets starting at
I<pv>
+The string to be inserted is represented by octets starting at
C<pv>
and continuing to the first nul. These octets are interpreted as either
UTF-8 or Latin-1, according to whether the C<LEX_STUFF_UTF8> flag is set
-in I<flags>. The characters are recoded for the lexer buffer, according
+in C<flags>. The characters are recoded for the lexer buffer, according
to how the buffer is currently being interpreted (L</lex_bufutf8>).
If it is not convenient to nul-terminate a string to be inserted, the
L</lex_stuff_pvn> function is more appropriate.
uses of this facility run the risk of the inserted characters being
interpreted in an unintended manner.
-The string to be inserted is the string value of I<sv>. The characters
+The string to be inserted is the string value of C<sv>. The characters
are recoded for the lexer buffer, according to how the buffer is currently
being interpreted (L</lex_bufutf8>). If a string to be inserted is
not already a Perl scalar, the L</lex_stuff_pvn> function avoids the
=for apidoc Amx|void|lex_unstuff|char *ptr
Discards text about to be lexed, from L</PL_parser-E<gt>bufptr> up to
-
I<ptr>. Text following I<ptr> will be moved, and the buffer shortened.
+
C<ptr>. Text following C<ptr> will be moved, and the buffer shortened.
This hides the discarded text from any lexing code that runs later,
as if the text had never appeared.
=for apidoc Amx|void|lex_read_to|char *ptr
Consume text in the lexer buffer, from L</PL_parser-E<gt>bufptr> up
-to
I<ptr>. This advances L</PL_parser-E<gt>bufptr> to match I<ptr>,
+to
C<ptr>. This advances L</PL_parser-E<gt>bufptr> to match C<ptr>,
performing the correct bookkeeping whenever a newline character is passed.
This is the normal way to consume lexed text.
=for apidoc Amx|void|lex_discard_to|char *ptr
Discards the first part of the L</PL_parser-E<gt>linestr> buffer,
-up to
I<ptr>. The remaining content of the buffer will be moved, and
-all pointers into the buffer updated appropriately.
I<ptr> must not
+up to
C<ptr>. The remaining content of the buffer will be moved, and
+all pointers into the buffer updated appropriately.
C<ptr> must not
be later in the buffer than the position of L</PL_parser-E<gt>bufptr>:
it is not permitted to discard text that has yet to be lexed.
If L</PL_parser-E<gt>bufptr> is pointing to the very end of the current
chunk (i.e., the current chunk has been entirely consumed), normally the
current chunk will be discarded at the same time that the new chunk is
-read in. If I<flags> includes C<LEX_KEEP_PREVIOUS>, the current chunk
+read in. If C<flags> includes C<LEX_KEEP_PREVIOUS>, the current chunk
will not be discarded. If the current chunk has not been entirely
consumed, then it will not be discarded regardless of the flag.
If the next character is in (or extends into) the next chunk of input
text, the next chunk will be read in. Normally the current chunk will be
-discarded at the same time, but if I<flags> includes C<LEX_KEEP_PREVIOUS>
+discarded at the same time, but if C<flags> includes C<LEX_KEEP_PREVIOUS>
then the current chunk will not be discarded.
If the input is being interpreted as UTF-8 and a UTF-8 encoding error
If the next character is in (or extends into) the next chunk of input
text, the next chunk will be read in. Normally the current chunk will be
-discarded at the same time, but if I<flags> includes C<LEX_KEEP_PREVIOUS>
+discarded at the same time, but if C<flags> includes C<LEX_KEEP_PREVIOUS>
then the current chunk will not be discarded.
If the input is being interpreted as UTF-8 and a UTF-8 encoding error
If spaces extend into the next chunk of input text, the next chunk will
be read in. Normally the current chunk will be discarded at the same
-time, but if I<flags> includes C<LEX_KEEP_PREVIOUS> then the current
+time, but if C<flags> includes C<LEX_KEEP_PREVIOUS> then the current
chunk will not be discarded.
=cut
down to the bit shift operators. The expression must be followed (and thus
terminated) either by a comparison or lower-precedence operator or by
something that would normally terminate an expression such as semicolon.
-If
I<flags> includes C<PARSE_OPTIONAL> then the expression is optional,
+If
C<flags> includes C<PARSE_OPTIONAL> then the expression is optional,
otherwise it is mandatory. It is up to the caller to ensure that the
dynamic parser state (L</PL_parser> et al) is correctly set to reflect
the source of the code to be parsed and the lexical context for the
down to the assignment operators. The expression must be followed (and thus
terminated) either by a comma or lower-precedence operator or by
something that would normally terminate an expression such as semicolon.
-If
I<flags> includes C<PARSE_OPTIONAL> then the expression is optional,
+If
C<flags> includes C<PARSE_OPTIONAL> then the expression is optional,
otherwise it is mandatory. It is up to the caller to ensure that the
dynamic parser state (L</PL_parser> et al) is correctly set to reflect
the source of the code to be parsed and the lexical context for the
down to the comma operator. The expression must be followed (and thus
terminated) either by a low-precedence logic operator such as C<or> or by
something that would normally terminate an expression such as semicolon.
-If
I<flags> includes C<PARSE_OPTIONAL> then the expression is optional,
+If
C<flags> includes C<PARSE_OPTIONAL> then the expression is optional,
otherwise it is mandatory. It is up to the caller to ensure that the
dynamic parser state (L</PL_parser> et al) is correctly set to reflect
the source of the code to be parsed and the lexical context for the
as C<or>. The expression must be followed (and thus terminated) by a
token that an expression would normally be terminated by: end-of-file,
closing bracketing punctuation, semicolon, or one of the keywords that
-signals a postfix expression-statement modifier. If I<flags> includes
+signals a postfix expression-statement modifier. If C<flags> includes
C<PARSE_OPTIONAL> then the expression is optional, otherwise it is
mandatory. It is up to the caller to ensure that the dynamic parser
state (L</PL_parser> et al) is correctly set to reflect the source of
level of parsing which covers all the compilation errors that occurred.
Some compilation errors, however, will throw an exception immediately.
-The I<flags> parameter is reserved for future use, and must always
+The C<flags> parameter is reserved for future use, and must always
be zero.
=cut
level of parsing which covers all the compilation errors that occurred.
Some compilation errors, however, will throw an exception immediately.
-The I<flags> parameter is reserved for future use, and must always
+The C<flags> parameter is reserved for future use, and must always
be zero.
=cut
Parse a single label, possibly optional, of the type that may prefix a
Perl statement. It is up to the caller to ensure that the dynamic parser
state (L</PL_parser> et al) is correctly set to reflect the source of
-the code to be parsed. If
I<flags> includes C<PARSE_OPTIONAL> then the
+the code to be parsed. If
C<flags> includes C<PARSE_OPTIONAL> then the
label is optional, otherwise it is mandatory.
The name of the label is returned in the form of a fresh scalar. If an
level of parsing which covers all the compilation errors that occurred.
Some compilation errors, however, will throw an exception immediately.
-The I<flags> parameter is reserved for future use, and must always
+The C<flags> parameter is reserved for future use, and must always
be zero.
=cut
which covers all the compilation errors that occurred. Some compilation
errors, however, will throw an exception immediately.
-The I<flags> parameter is reserved for future use, and must always
+The C<flags> parameter is reserved for future use, and must always
be zero.
=cut
https://perl5.git.perl.org / perl5.git / commitdiff