home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl501m.zip / pod / perlmagic.pod < prev    next >
Text File  |  1995-01-07  |  5KB  |  121 lines
  1. =head1 Magic
  2.  
  3. [This section still under construction.  Ignore everything here.  Post no
  4. bills.  Everything not permitted is forbidden.]
  5.  
  6. # Version 3, 95/1/6
  7.  
  8. Any SV may be magical, that is, it has special features that a normal
  9. SV does not have.  These features are stored in the SV structure in a
  10. linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
  11.  
  12. The main routine Perl uses to deal with magical variables is:
  13.  
  14.     void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen);
  15.  
  16. The C<sv> argument is a pointer to the SV that is to acquire a new magical
  17. feature.
  18.  
  19. If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
  20. set the C<SVt_PVMG> flag for the C<sv>.  Perl then continues to make
  21. the C<sv> magical, adding it to the end of the linked list of magical
  22. features.
  23.  
  24. The C<name> and C<namlem> arguments, if non-null and non-zero respectively,
  25. tell Perl that the C<sv> argument is the name of a variable. /* XXX */
  26. The variable name is stored in the C<mg_ptr> field of the C<MAGIC> structure.
  27.  
  28. The C<how> argument specifies what kind of magicalness the C<sv> is
  29. to receive.  This single character is stored in the C<mg_type> field
  30. of the C<MAGIC> structure.
  31.  
  32. This argument also tells Perl which C routines within Perl should be used
  33. when accessing the magical variable.  The C<mg_virtual> field in the
  34. C<MAGIC> structure is a pointer to a C<MGVTBL>, which is a structure
  35. of function pointers and stands for "Magic Virtual Table" to handle the
  36. various operations that might be applied to that variable.
  37.  
  38. The C<MGVTBL> has five pointers to the following routine types:
  39.  
  40.     int  (*svt_get)(SV* sv, MAGIC* mg);
  41.     int  (*svt_set)(SV* sv, MAGIC* mg);
  42.     U32  (*svt_len)(SV* sv, MAGIC* mg);
  43.     int  (*svt_clear)(SV* sv, MAGIC* mg);
  44.     int  (*svt_free)(SV* sv, MAGIC* mg);
  45.  
  46. This MGVTBL structure is set at compile-time in C<perl.h> and there are
  47. currently 19 types (or 21 with overloading turned on).  These different
  48. structures contain pointers to various routines that perform additional
  49. actions depending on which function is being called.
  50.  
  51.     Function pointer    Action taken
  52.     ----------------    ------------
  53.     svt_get             Do something after the value of the SV is retrieved.
  54.     svt_set             Do something after the SV is assigned a value.
  55.     svt_len             Report on the SV's length.
  56.     svt_clear        Clear something the SV represents.
  57.     svt_free            Free any extra storage associated with the SV.
  58.  
  59. For instance, the MGVTBL structure called C<vtbl_sv> contains:
  60.  
  61.     { magic_get, magic_set, magic_len, 0, 0 }
  62.  
  63. Thus, when an SV is determined to be magical, if a get operation is being
  64. performed, the routine C<magic_get> is called.  All the various routines
  65. for the various magical types begin with C<magic_>.
  66.  
  67. The current kinds of Magic Virtual Tables are:
  68.  
  69.     mg_type  MGVTBL              Type of magicalness
  70.     -------  ------              -------------------
  71.     \0       vtbl_sv             Regexp???
  72.     A        vtbl_amagic         Operator Overloading
  73.     a        vtbl_amagicelem     Operator Overloading
  74.     c        0                   Used in Operator Overloading
  75.     B        vtbl_bm             Boyer-Moore???
  76.     E        vtbl_env            %ENV Hash???
  77.     e        vtbl_envelem        %ENV hash???
  78.     g        vtbl_mglob          Regexp /g flag???
  79.     I        vtbl_isa            @ISA array
  80.     i        vtbl_isaelem        @ISA array element
  81.     L        0 (but sets RMAGICAL)     Perl Module/Debugger???
  82.     l        vtbl_dbline         Debugger?
  83.     P        vtbl_pack           Tied Array or Hash???
  84.     p        vtbl_packelem       Tied Scalar or Handle???
  85.     q        vtbl_packelem       Tied Scalar or Handle???
  86.     S        vtbl_sig            Signal Hash
  87.     s        vtbl_sigelem        Signal Hash element
  88.     t        vtbl_taint          Taintedness
  89.     U        vtbl_uvar             ???
  90.     v        vtbl_vec             Vector
  91.     x        vtbl_substr         Substring???
  92.     *        vtbl_glob           GV???
  93.     #        vtbl_arylen         Array Length???
  94.     .        vtbl_pos             ???
  95.     ~        Reserved for extensions, but multiple extensions may clash
  96.  
  97. When an upper-case and lower-case letter both exist in the table, then the
  98. upper-case letter is some kind of composite type (a list or a hash), and
  99. the lower-case letter is an element of that composite type.
  100.  
  101. The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
  102. structure.  If it is not the same as the C<sv> argument, the reference
  103. count of the C<obj> object is incremented.  If it is the same, or if
  104. the C<how> argument is "#", then C<obj> is merely stored, without the
  105. reference count being incremented.
  106.  
  107. Another often-used routine is:
  108.  
  109.     MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
  110.  
  111. This routine returns a pointer to the C<MAGIC> structure stored in the SV.
  112. If the SV does not have that magical feature, C<NULL> is returned.  Also,
  113. if the SV is not of type SVt_PVMG, Perl may core-dump.
  114.  
  115.     int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
  116.  
  117. This routine checks to see what types of magic C<sv> has.  If the mg_type
  118. field is an upper-case letter, then the mg_obj is copied to C<nsv>, but
  119. the mg_type field is changed to be the lower-case letter.
  120.  
  121.