From 2d7f66116e374c78dcf18cb5b9fea7b79ac82b5b Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Thu, 7 May 2015 10:28:43 -0600 Subject: [PATCH] perlapi: Use C<> instead of I<> for parameter names, etc The majority of perlapi uses C<> to specify these things, but a few things used I<> instead. Standardize to C<>. --- cop.h | 34 ++++----- hv.c | 22 +++--- mathoms.c | 2 +- mg.c | 2 +- numeric.c | 52 +++++++------- op.c | 234 +++++++++++++++++++++++++++++++------------------------------- op.h | 24 +++---- pad.c | 38 +++++----- sv.c | 4 +- sv.h | 18 ++--- toke.c | 60 ++++++++-------- 11 files changed, 245 insertions(+), 245 deletions(-) diff --git a/cop.h b/cop.h index bf287a1..70e7817 100644 --- a/cop.h +++ b/cop.h @@ -154,10 +154,10 @@ typedef struct refcounted_he COPHH; /* =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 with the key specified by -I and I. If I has the C bit set, +Look up the entry in the cop hints hash C with the key specified by +C and C. If C has the C bit set, the key octets are interpreted as UTF-8, otherwise they are interpreted -as Latin-1. I is a precomputed hash of the key string, or zero if +as Latin-1. C 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. @@ -208,7 +208,7 @@ string/length pair. =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. I is currently +key/value pairs in the cop hints hash C. C is currently unused and must be zero. =cut @@ -220,7 +220,7 @@ unused and must be zero. /* =for apidoc Amx|COPHH *|cophh_copy|COPHH *cophh -Make and return a complete copy of the cop hints hash I. +Make and return a complete copy of the cop hints hash C. =cut */ @@ -230,7 +230,7 @@ Make and return a complete copy of the cop hints hash I. /* =for apidoc Amx|void|cophh_free|COPHH *cophh -Discard the cop hints hash I, freeing all resources associated +Discard the cop hints hash C, freeing all resources associated with it. =cut @@ -251,18 +251,18 @@ Generate and return a fresh cop hints hash containing no entries. /* =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, +Stores a value, associated with a key, in the cop hints hash C, 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 if you need both hashes. -The key is specified by I and I. If I has the +The key is specified by C and C. If C has the C bit set, the key octets are interpreted as UTF-8, -otherwise they are interpreted as Latin-1. I is a precomputed +otherwise they are interpreted as Latin-1. C is a precomputed hash of the key string, or zero if it has not been precomputed. -I is the scalar value to store for this key. I is copied +C is the scalar value to store for this key. C 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 @@ -313,15 +313,15 @@ string/length pair. /* =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, +Delete a key and its associated value from the cop hints hash C, 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 if you need both hashes. -The key is specified by I and I. If I has the +The key is specified by C and C. If C has the C bit set, the key octets are interpreted as UTF-8, -otherwise they are interpreted as Latin-1. I is a precomputed +otherwise they are interpreted as Latin-1. C is a precomputed hash of the key string, or zero if it has not been precomputed. =cut @@ -457,10 +457,10 @@ struct cop { /* =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 with the key specified by -I and I. If I has the C bit set, +Look up the hint entry in the cop C with the key specified by +C and C. If C has the C bit set, the key octets are interpreted as UTF-8, otherwise they are interpreted -as Latin-1. I is a precomputed hash of the key string, or zero if +as Latin-1. C 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. @@ -511,7 +511,7 @@ string/length pair. =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. I is currently unused and must +hint entries in the cop C. C is currently unused and must be zero. =cut diff --git a/hv.c b/hv.c index 2fd36ee..469221f 100644 --- a/hv.c +++ b/hv.c @@ -1490,10 +1490,10 @@ Perl_newHVhv(pTHX_ HV *ohv) /* =for apidoc Am|HV *|hv_copy_hints_hv|HV *ohv -A specialised version of L for copying C<%^H>. I must be +A specialised version of L for copying C<%^H>. C must be a pointer to a hash (which may have C<%^H> magic, but should be generally non-magical), or C (interpreted as an empty hash). The content -of I is copied to a new hash, which has the C<%^H>-specific magic +of C 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 @@ -3064,7 +3064,7 @@ S_refcounted_he_value(pTHX_ const struct refcounted_he *he) Generates and returns a C representing the content of a C chain. -I is currently unused and must be zero. +C is currently unused and must be zero. =cut */ @@ -3171,9 +3171,9 @@ Perl_refcounted_he_chain_2hv(pTHX_ const struct refcounted_he *chain, U32 flags) =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 chain for an entry with the key specified -by I and I. If I has the C +by C and C. If C has the C bit set, the key octets are interpreted as UTF-8, otherwise they -are interpreted as Latin-1. I is a precomputed hash of the key +are interpreted as Latin-1. C 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. @@ -3310,25 +3310,25 @@ be empty), and thus forms a longer chain. When using the longer chain, 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 and I. If I has +The new key is specified by C and C. If C has the C bit set, the key octets are interpreted -as UTF-8, otherwise they are interpreted as Latin-1. I is +as UTF-8, otherwise they are interpreted as Latin-1. C is a precomputed hash of the key string, or zero if it has not been precomputed. -I is the scalar value to store for this key. I is copied +C is the scalar value to store for this key. C 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. Complex types of scalar will not be stored with referential integrity, but will be coerced to strings. -I may be either null or C<&PL_sv_placeholder> to indicate that no +C 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 points to the rest of the C chain to be +C points to the rest of the C chain to be attached to the new C. This function takes ownership -of one reference to I, and returns one reference to the new +of one reference to C, and returns one reference to the new C. =cut diff --git a/mathoms.c b/mathoms.c index d659883..7da0068 100644 --- a/mathoms.c +++ b/mathoms.c @@ -1795,7 +1795,7 @@ Perl_utf8_to_uvuni(pTHX_ const U8 *s, STRLEN *retlen) /* =for apidoc Am|HV *|pad_compname_type|PADOFFSET po -Looks up the type of the lexical variable at position I in the +Looks up the type of the lexical variable at position C 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 is returned. diff --git a/mg.c b/mg.c index b4a368d..6ec7628 100644 --- a/mg.c +++ b/mg.c @@ -579,7 +579,7 @@ Perl_mg_free(pTHX_ SV *sv) /* =for apidoc Am|void|mg_free_type|SV *sv|int how -Remove any magic of type I from the SV I. See L. +Remove any magic of type C from the SV C. See L. =cut */ diff --git a/numeric.c b/numeric.c index be85adb..1900d10 100644 --- a/numeric.c +++ b/numeric.c @@ -107,23 +107,23 @@ Perl_cast_uv(NV f) converts a string representing a binary number to numeric form. -On entry I and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I should be NULL or a pointer to an NV. +On entry C and C<*len> give the string to scan, C<*flags> gives +conversion flags, and C 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 is set in I<*flags>, encountering an +Unless C 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 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 +and nothing is written to C<*result>. If the value is > UV_MAX C returns UV_MAX, sets C in the output flags, -and writes the value to I<*result> (or the value is discarded if I +and writes the value to C<*result> (or the value is discarded if C is NULL). The binary number may optionally be prefixed with "0b" or "b" unless -C is set in I<*flags> on entry. If -C is set in I<*flags> then the binary +C is set in C<*flags> on entry. If +C is set in C<*flags> then the binary number may use '_' characters to separate digits. =cut @@ -230,23 +230,23 @@ Perl_grok_bin(pTHX_ const char *start, STRLEN *len_p, I32 *flags, NV *result) converts a string representing a hex number to numeric form. -On entry I and I<*len_p> give the string to scan, I<*flags> gives -conversion flags, and I should be NULL or a pointer to an NV. +On entry C and C<*len_p> give the string to scan, C<*flags> gives +conversion flags, and C 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 is set in I<*flags>, encountering an +Unless C 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 +and nothing is written to C<*result>. If the value is > UV_MAX C returns UV_MAX, sets C in the output flags, -and writes the value to I<*result> (or the value is discarded if I +and writes the value to C<*result> (or the value is discarded if C is NULL). The hex number may optionally be prefixed with "0x" or "x" unless -C is set in I<*flags> on entry. If -C is set in I<*flags> then the hex +C is set in C<*flags> on entry. If +C is set in C<*flags> then the hex number may use '_' characters to separate digits. =cut @@ -351,21 +351,21 @@ Perl_grok_hex(pTHX_ const char *start, STRLEN *len_p, I32 *flags, NV *result) converts a string representing an octal number to numeric form. -On entry I and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I should be NULL or a pointer to an NV. +On entry C and C<*len> give the string to scan, C<*flags> gives +conversion flags, and C 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 is set in I<*flags>, encountering an +Unless C 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 +and nothing is written to C<*result>. If the value is > UV_MAX C returns UV_MAX, sets C in the output flags, -and writes the value to I<*result> (or the value is discarded if I +and writes the value to C<*result> (or the value is discarded if C is NULL). -If C is set in I<*flags> then the octal +If C is set in C<*flags> then the octal number may use '_' characters to separate digits. =cut diff --git a/op.c b/op.c index 9d3d0fa..d97f916 100644 --- a/op.c +++ b/op.c @@ -1442,7 +1442,7 @@ S_alloc_LOGOP(pTHX_ I32 type, OP *first, OP* other) =for apidoc Am|OP *|op_contextualize|OP *o|I32 context Applies a syntactic context to an op tree representing an expression. -I is the op tree, and I must be C, C, +C is the op tree, and C must be C, C, or C to specify the context to apply. The modified op tree is returned. @@ -2584,7 +2584,7 @@ S_finalize_op(pTHX_ OP* o) =for apidoc Amx|OP *|op_lvalue|OP *o|I32 type Propagate lvalue ("modifiable") context to an op and its children. -I represents the context type, roughly based on the type of op that +C represents the context type, roughly based on the type of op that would do the modifying, although C is represented by OP_NULL, because it has no op type of its own (it is signalled by a flag on the lvalue op). @@ -3905,9 +3905,9 @@ Perl_block_start(pTHX_ int full) /* =for apidoc Am|OP *|block_end|I32 floor|OP *seq -Handles compile-time scope exit. I +Handles compile-time scope exit. C is the savestack index returned by -C, and I is the body of the block. Returns the block, +C, and C is the body of the block. Returns the block, possibly modified. =cut @@ -4455,10 +4455,10 @@ S_gen_constant_list(pTHX_ OP *o) =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 is the list-type op, -and I is the op to append to the list. I specifies the -intended opcode for the list. If I is not already a list of the -right type, it will be upgraded into one. If either I or I +op, returning the lengthened list. C is the list-type op, +and C is the op to append to the list. C specifies the +intended opcode for the list. If C is not already a list of the +right type, it will be upgraded into one. If either C or C is null, the other is returned unchanged. =cut @@ -4488,10 +4488,10 @@ Perl_op_append_elem(pTHX_ I32 type, OP *first, OP *last) =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 and I are the list-type ops -to concatenate. I specifies the intended opcode for the list. -If either I or I is not already a list of the right type, -it will be upgraded into one. If either I or I is null, +returning the combined list. C and C are the list-type ops +to concatenate. C specifies the intended opcode for the list. +If either C or C is not already a list of the right type, +it will be upgraded into one. If either C or C is null, the other is returned unchanged. =cut @@ -4526,10 +4526,10 @@ Perl_op_append_list(pTHX_ I32 type, OP *first, OP *last) =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 is the op to prepend to the -list, and I is the list-type op. I specifies the intended -opcode for the list. If I is not already a list of the right type, -it will be upgraded into one. If either I or I is null, +op, returning the lengthened list. C is the op to prepend to the +list, and C is the list-type op. C specifies the intended +opcode for the list. If C is not already a list of the right type, +it will be upgraded into one. If either C or C is null, the other is returned unchanged. =cut @@ -4563,8 +4563,8 @@ Perl_op_prepend_elem(pTHX_ I32 type, OP *first, OP *last) /* =for apidoc Am|OP *|op_convert_list|I32 type|I32 flags|OP *o -Converts I into a list op if it is not one already, and then converts it -into the specified I, calling its check function, allocating a target if +Converts C into a list op if it is not one already, and then converts it +into the specified C, 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, @@ -4664,9 +4664,9 @@ S_force_list(pTHX_ OP *o, bool nullit) /* =for apidoc Am|OP *|newLISTOP|I32 type|I32 flags|OP *first|OP *last -Constructs, checks, and returns an op of any list type. I is -the opcode. I gives the eight bits of C, except that -C will be set automatically if required. I and I +Constructs, checks, and returns an op of any list type. C is +the opcode. C gives the eight bits of C, except that +C will be set automatically if required. C and C 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. @@ -4722,7 +4722,7 @@ Perl_newLISTOP(pTHX_ I32 type, I32 flags, OP *first, OP *last) =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 is the opcode. I gives the +has no extra fields). C is the opcode. C gives the eight bits of C, and, shifted up eight bits, the eight bits of C. @@ -4761,11 +4761,11 @@ Perl_newOP(pTHX_ I32 type, I32 flags) /* =for apidoc Am|OP *|newUNOP|I32 type|I32 flags|OP *first -Constructs, checks, and returns an op of any unary type. I is -the opcode. I gives the eight bits of C, except that +Constructs, checks, and returns an op of any unary type. C is +the opcode. C gives the eight bits of C, except that C will be set automatically if required, and, shifted up eight bits, the eight bits of C, except that the bit with value 1 -is automatically set. I supplies an optional op to be the direct +is automatically set. C 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. @@ -4851,10 +4851,10 @@ Perl_newUNOP_AUX(pTHX_ I32 type, I32 flags, OP *first, UNOP_AUX_item *aux) =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 is the opcode. I gives the eight +evaluated at runtime. C is the opcode. C gives the eight bits of C, except that C will be set automatically, and, shifted up eight bits, the eight bits of C, except that -the bit with value 1 is automatically set. I supplies an +the bit with value 1 is automatically set. C 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. @@ -4908,9 +4908,9 @@ Perl_newMETHOP (pTHX_ I32 type, I32 flags, OP* dynamic_meth) { =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 is the opcode. I gives the eight bits of +method name. C is the opcode. C gives the eight bits of C, and, shifted up eight bits, the eight bits of -C. I supplies a constant method name; +C. C supplies a constant method name; it must be a shared COW string. Supported optypes: OP_METHOD_NAMED. @@ -4926,11 +4926,11 @@ Perl_newMETHOP_named (pTHX_ I32 type, I32 flags, SV* const_meth) { /* =for apidoc Am|OP *|newBINOP|I32 type|I32 flags|OP *first|OP *last -Constructs, checks, and returns an op of any binary type. I -is the opcode. I gives the eight bits of C, except +Constructs, checks, and returns an op of any binary type. C +is the opcode. C gives the eight bits of C, except that C will be set automatically, and, shifted up eight bits, the eight bits of C, except that the bit with value 1 or -2 is automatically set as required. I and I supply up to +2 is automatically set as required. C and C 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. @@ -5332,7 +5332,7 @@ S_pmtrans(pTHX_ OP *o, OP *expr, OP *repl) =for apidoc Am|OP *|newPMOP|I32 type|I32 flags Constructs, checks, and returns an op of any pattern matching type. -I is the opcode. I gives the eight bits of C +C is the opcode. C gives the eight bits of C and, shifted up eight bits, the eight bits of C. =cut @@ -5773,8 +5773,8 @@ Perl_pmruntime(pTHX_ OP *o, OP *expr, OP *repl, bool isreg, I32 floor) =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 is the opcode. I gives the eight bits -of C. I gives the SV to embed in the op; this function +embedded SV. C is the opcode. C gives the eight bits +of C. C gives the SV to embed in the op; this function takes ownership of one reference to it. =cut @@ -5836,9 +5836,9 @@ Perl_newDEFSVOP(pTHX) =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 is the opcode. I gives the +reference to a pad element. C is the opcode. C gives the eight bits of C. A pad slot is automatically allocated, and -is populated with I; this function takes ownership of one reference +is populated with C; this function takes ownership of one reference to it. This function only exists if Perl has been compiled to use ithreads. @@ -5881,8 +5881,8 @@ Perl_newPADOP(pTHX_ I32 type, I32 flags, SV *sv) =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 is the opcode. I gives the -eight bits of C. I identifies the GV that the op should +embedded reference to a GV. C is the opcode. C gives the +eight bits of C. C identifies the GV that the op should reference; calling this function does not transfer ownership of any reference to it. @@ -5905,8 +5905,8 @@ Perl_newGVOP(pTHX_ I32 type, I32 flags, GV *gv) =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 is the opcode. I gives -the eight bits of C. I supplies the C-level pointer, which +embedded C-level pointer (PV). C is the opcode. C gives +the eight bits of C. C supplies the C-level pointer, which must have been allocated using C; the memory will be freed when the op is destroyed. @@ -6221,11 +6221,11 @@ Perl_dofile(pTHX_ OP *term, I32 force_builtin) =for apidoc Am|OP *|newSLICEOP|I32 flags|OP *subscript|OP *listval -Constructs, checks, and returns an C (list slice) op. I +Constructs, checks, and returns an C (list slice) op. C gives the eight bits of C, except that C will be set automatically, and, shifted up eight bits, the eight bits of C, except that the bit with value 1 or 2 is automatically -set as required. I and I supply the parameters of +set as required. C and C supply the parameters of the slice; they are consumed by this function and become part of the constructed op tree. @@ -6433,19 +6433,19 @@ S_aassign_common_vars_aliases_only(pTHX_ OP *o) /* =for apidoc Am|OP *|newASSIGNOP|I32 flags|OP *left|I32 optype|OP *right -Constructs, checks, and returns an assignment op. I and I +Constructs, checks, and returns an assignment op. C and C supply the parameters of the assignment; they are consumed by this function and become part of the constructed op tree. -If I is C, C, or C, then -a suitable conditional optree is constructed. If I is the opcode +If C is C, C, or C, then +a suitable conditional optree is constructed. If C is the opcode of a binary operator, such as C, then an op is constructed that performs the binary operation and assigns the result to the left argument. -Either way, if I is non-zero then I has no effect. +Either way, if C is non-zero then C has no effect. -If I is zero, then a plain scalar or list assignment is +If C is zero, then a plain scalar or list assignment is constructed. Which type of assignment it is is automatically determined. -I gives the eight bits of C, except that C +C gives the eight bits of C, except that C will be set automatically, and, shifted up eight bits, the eight bits of C, except that the bit with value 1 or 2 is automatically set as required. @@ -6660,13 +6660,13 @@ Perl_newASSIGNOP(pTHX_ I32 flags, OP *left, I32 optype, OP *right) Constructs a state op (COP). The state op is normally a C op, but will be a C op if debugging is enabled for currently-compiled code. The state op is populated from C (or C). -If I