From a9b0660e46fd1dc59e1f97eed13330e3a3ed9087 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Sat, 10 Dec 2011 12:57:05 -0700 Subject: [PATCH] perlguts: nits This fixes a few typos, adds a few clarifications, and fixes too wide verbatim lines --- pod/perlguts.pod | 172 ++++++++++++++++++++++------------------- t/porting/known_pod_issues.dat | 1 - 2 files changed, 94 insertions(+), 79 deletions(-) diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 40b66ca..9a4d6d4 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -59,7 +59,8 @@ the NUL) bytes of storage allocated, accessible via SvPVX. In both cases the SV has value undef. SV *sv = newSV(0); /* no storage allocated */ - SV *sv = newSV(10); /* 10 (+1) bytes of uninitialised storage allocated */ + SV *sv = newSV(10); /* 10 (+1) bytes of uninitialised storage + * allocated */ To change the value of an I SV, there are eight routines: @@ -69,7 +70,8 @@ To change the value of an I SV, there are eight routines: void sv_setpv(SV*, const char*); void sv_setpvn(SV*, const char*, STRLEN) void sv_setpvf(SV*, const char*, ...); - void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool *); + void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *, + SV **, I32, bool *); void sv_setsv(SV*, SV*); Notice that you can choose to specify the length of the string to be @@ -77,7 +79,8 @@ assigned by using C, C, or C, or you may allow Perl to calculate the length by using C or by specifying 0 as the second argument to C. Be warned, though, that Perl will determine the string's length by using C, which depends on the -string terminating with a NUL character. +string terminating with a NUL character, and not otherwise containing +NULs. The arguments of C are processed like C, and the formatted output becomes the value. @@ -144,7 +147,7 @@ Perl to allocate more memory for your SV, you can use the macro which will determine if more memory needs to be allocated. If so, it will call the function C. Note that C can only increase, not decrease, the allocated memory of an SV and that it does not automatically -add a byte for the a trailing NUL (perl's own string functions typically do +add space for the trailing NUL byte (perl's own string functions typically do C). If you have an SV and want to know what kind of data Perl thinks is stored @@ -173,7 +176,8 @@ you can use the following functions: void sv_catpv(SV*, const char*); void sv_catpvn(SV*, const char*, STRLEN); void sv_catpvf(SV*, const char*, ...); - void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool); + void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, + I32, bool); void sv_catsv(SV*, SV*); The first function calculates the length of the string to be appended by @@ -416,7 +420,7 @@ Like their AV counterparts, C deletes all the entries in the hash table but does not actually delete the hash table. The C deletes both the entries and the hash table itself. -Perl keeps the actual data in linked list of structures with a typedef of HE. +Perl keeps the actual data in a linked list of structures with a typedef of HE. These contain the actual key and value pointers (plus extra administrative overhead). The key is a string pointer; the value is an C. However, once you have an C, to get the actual key and value, use the routines @@ -559,7 +563,7 @@ new undefined value using the C function, for example: =head2 References References are a special type of scalar that point to other data types -(including references). +(including other references). To create a reference, use either of the following functions: @@ -639,11 +643,12 @@ is non-null. SV* sv_setref_pv(SV* rv, const char* classname, void* pv); -The following function copies string into an SV whose reference is C. +The following function copies a string into an SV whose reference is C. Set length to 0 to let Perl calculate the string length. SV is blessed if C is non-null. - SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN length); + SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, + STRLEN length); The following function tests whether the SV is blessed into the specified class. It does not check inheritance relationships. @@ -916,7 +921,7 @@ Note this is current as of patchlevel 0, and could change at any time. Perl adds magic to an SV using the sv_magic function: - void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen); + void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen); The C argument is a pointer to the SV that is to acquire a new magical feature. @@ -989,7 +994,8 @@ routine types: int (*svt_clear)(SV* sv, MAGIC* mg); int (*svt_free)(SV* sv, MAGIC* mg); - int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv, const char *name, I32 namlen); + int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv, + const char *name, I32 namlen); int (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param); int (*svt_local)(SV *nsv, MAGIC *mg); @@ -999,17 +1005,18 @@ currently 32 types. These different structures contain pointers to various routines that perform additional actions depending on which function is being called. - Function pointer Action taken - ---------------- ------------ - svt_get Do something before the value of the SV is retrieved. - svt_set Do something after the SV is assigned a value. - svt_len Report on the SV's length. - svt_clear Clear something the SV represents. - svt_free Free any extra storage associated with the SV. + Function pointer Action taken + ---------------- ------------ + svt_get Do something before the value of the SV is + retrieved. + svt_set Do something after the SV is assigned a value. + svt_len Report on the SV's length. + svt_clear Clear something the SV represents. + svt_free Free any extra storage associated with the SV. - svt_copy copy tied variable magic to a tied element - svt_dup duplicate a magic structure during thread cloning - svt_local copy magic to local value during 'local' + svt_copy copy tied variable magic to a tied element + svt_dup duplicate a magic structure during thread cloning + svt_local copy magic to local value during 'local' For instance, the MGVTBL structure called C (which corresponds to an C of C) contains: @@ -1031,61 +1038,68 @@ to change. The current kinds of Magic Virtual Tables are: - mg_type - (old-style char and macro) MGVTBL Type of magic - -------------------------- ------ ------------- - \0 PERL_MAGIC_sv vtbl_sv Special scalar variable - # PERL_MAGIC_arylen vtbl_arylen Array length ($#ary) - % PERL_MAGIC_rhash (none) extra data for restricted - hashes - . PERL_MAGIC_pos vtbl_pos pos() lvalue - : PERL_MAGIC_symtab (none) extra data for symbol tables - < PERL_MAGIC_backref vtbl_backref for weak ref data - @ PERL_MAGIC_arylen_p (none) to move arylen out of XPVAV - A PERL_MAGIC_overload vtbl_amagic %OVERLOAD hash - a PERL_MAGIC_overload_elem vtbl_amagicelem %OVERLOAD hash element - B PERL_MAGIC_bm vtbl_regexp Boyer-Moore - (fast string search) - c PERL_MAGIC_overload_table vtbl_ovrld Holds overload table - (AMT) on stash - D PERL_MAGIC_regdata vtbl_regdata Regex match position data - (@+ and @- vars) - d PERL_MAGIC_regdatum vtbl_regdatum Regex match position data - element - E PERL_MAGIC_env vtbl_env %ENV hash - e PERL_MAGIC_envelem vtbl_envelem %ENV hash element - f PERL_MAGIC_fm vtbl_regdata Formline ('compiled' format) - G PERL_MAGIC_study vtbl_regdata study()ed string - g PERL_MAGIC_regex_global vtbl_mglob m//g target - H PERL_MAGIC_hints vtbl_hints %^H hash - h PERL_MAGIC_hintselem vtbl_hintselem %^H hash element - I PERL_MAGIC_isa vtbl_isa @ISA array - i PERL_MAGIC_isaelem vtbl_isaelem @ISA array element - k PERL_MAGIC_nkeys vtbl_nkeys scalar(keys()) lvalue - L PERL_MAGIC_dbfile (none) Debugger %_ structure stored in the SV. If the SV does not have that magical feature, C is returned. If the @@ -1475,7 +1490,8 @@ L): PUSHs(sv_2mortal(newSVuv(an_unsigned_integer))) PUSHs(sv_2mortal(newSVnv(a_double))) PUSHs(sv_2mortal(newSVpv("Some String",0))) - /* Although the last example is better written as the more efficient: */ + /* Although the last example is better written as the more + * efficient: */ PUSHs(newSVpvs_flags("Some String", SVs_TEMP)) And now the Perl program calling C, the two values will be assigned diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat index e4f256c..fee8797 100644 --- a/t/porting/known_pod_issues.dat +++ b/t/porting/known_pod_issues.dat @@ -224,7 +224,6 @@ pod/perlgit.pod Verbatim line length including indents exceeds 79 by 14 pod/perlgpl.pod Verbatim line length including indents exceeds 79 by 50 pod/perlguts.pod ? Should you be using F<...> or maybe L<...> instead of 2 pod/perlguts.pod ? Should you be using L<...> instead of 1 -pod/perlguts.pod Verbatim line length including indents exceeds 79 by 25 pod/perlhack.pod ? Should you be using L<...> instead of 1 pod/perlhack.pod Verbatim line length including indents exceeds 79 by 1 pod/perlhacktips.pod Verbatim line length including indents exceeds 79 by 1 -- 2.7.4