Re: [PATCH] Hash::Util::FieldHash

[p5sagit/p5-mst-13.2.git] / pod / perlguts.pod

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index d37a381..aa32b06 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -126,11 +126,11 @@ Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len),
 len);>. It might work with your compiler, but it won't work for everyone.
 Break this sort of statement up into separate assignments:
 
-       SV *s;
-       STRLEN len;
-       char * ptr;
-       ptr = SvPV(s, len);
-       foo(ptr, len);
+    SV *s;
+    STRLEN len;
+    char * ptr;
+    ptr = SvPV(s, len);
+    foo(ptr, len);
 
 If you want to know if the scalar value is TRUE, you can use:
 
@@ -1038,6 +1038,8 @@ The current kinds of Magic Virtual Tables are:
     e  PERL_MAGIC_envelem        vtbl_envelem   %ENV hash element
     f  PERL_MAGIC_fm             vtbl_fm        Formline ('compiled' format)
     g  PERL_MAGIC_regex_global   vtbl_mglob     m//g target / study()ed string
+    H  PERL_MAGIC_hints          vtbl_sig       %^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
@@ -1060,7 +1062,6 @@ The current kinds of Magic Virtual Tables are:
     y  PERL_MAGIC_defelem        vtbl_defelem   Shadow "foreach" iterator
                                                variable / smart parameter
                                                vivification
-    *  PERL_MAGIC_glob           vtbl_glob      GV (typeglob)
     #  PERL_MAGIC_arylen         vtbl_arylen    Array length ($#ary)
     .  PERL_MAGIC_pos            vtbl_pos       pos() lvalue
     <  PERL_MAGIC_backref        vtbl_backref   back pointer to a weak ref 
@@ -1110,6 +1111,17 @@ sv_magic, so you can safely allocate it on the stack.
         uf.uf_index = 0;
         sv_magic(sv, 0, PERL_MAGIC_uvar, (char*)&uf, sizeof(uf));
 
+Attaching C<PERL_MAGIC_uvar> to arrays is permissible but has no effect.
+
+For hashes there is a specialized hook that gives control over hash
+keys (but not values).  This hook calls C<PERL_MAGIC_uvar> 'get' magic
+if the "set" function in the C<ufuncs> structure is NULL.  The hook
+is activated whenever the hash is accessed with a key specified as
+an C<SV> through the functions C<hv_store_ent>, C<hv_fetch_ent>,
+C<hv_delete_ent>, and C<hv_exists_ent>.  Accessing the key as a string
+through the functions without the C<..._ent> suffix circumvents the
+hook.  See L<Hash::Util::Fieldhash/Guts> for a detailed description.
+
 Note that because multiple extensions may be using C<PERL_MAGIC_ext>
 or C<PERL_MAGIC_uvar> magic, it is important for extensions to take
 extra care to avoid conflict.  Typically only using the magic on
@@ -2184,16 +2196,18 @@ after that are the arguments. The first column is a set of flags:
 
 =item A
 
-This function is a part of the public API.
+This function is a part of the public API. All such functions should also
+have 'd', very few do not.
 
 =item p
 
-This function has a C<Perl_> prefix; i.e. it is defined as C<Perl_av_fetch>
+This function has a C<Perl_> prefix; i.e. it is defined as
+C<Perl_av_fetch>.
 
 =item d
 
 This function has documentation using the C<apidoc> feature which we'll
-look at in a second.
+look at in a second.  Some functions have 'd' but not 'A'; docs are good.
 
 =back
 
@@ -2203,12 +2217,13 @@ Other available flags are:
 
 =item s
 
-This is a static function and is defined as C<S_whatever>, and usually
-called within the sources as C<whatever(...)>.
+This is a static function and is defined as C<STATIC S_whatever>, and
+usually called within the sources as C<whatever(...)>.
 
 =item n
 
-This does not use C<aTHX_> and C<pTHX> to pass interpreter context. (See
+This does not need a interpreter context, so the definition has no
+C<pTHX>, and it follows that callers don't use C<aTHX>.  (See
 L<perlguts/Background and PERL_IMPLICIT_CONTEXT>.)
 
 =item r
@@ -2253,6 +2268,10 @@ This function is visible to extensions included in the Perl core.
 Binary backward compatibility; this function is a macro but also has
 a C<Perl_> implementation (which is exported).
 
+=item others
+
+See the comments at the top of C<embed.fnc> for others.
+
 =back
 
 If you edit F<embed.pl> or F<embed.fnc>, you will need to run
@@ -2596,7 +2615,7 @@ define your own ops. This is primarily to allow the building of
 interpreters for other languages in the Perl core, but it also allows
 optimizations through the creation of "macro-ops" (ops which perform the
 functions of multiple ops which are usually executed together, such as
-C<gvsv, gvsv, add>.) 
+C<gvsv, gvsv, add>.)
 
 This feature is implemented as a new op type, C<OP_CUSTOM>. The Perl
 core does not "know" anything special about this op type, and so it will