=head1 Magic

[This section still under construction.  Ignore everything here.  Post no
bills.  Everything not permitted is forbidden.]

# Version 3, 95/1/6

Any SV may be magical, that is, it has special features that a normal
SV does not have.  These features are stored in the SV structure in a
linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.

The main routine Perl uses to deal with magical variables is:

    void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen);

The C<sv> argument is a pointer to the SV that is to acquire a new magical
feature.

If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
set the C<SVt_PVMG> flag for the C<sv>.  Perl then continues to make
the C<sv> magical, adding it to the end of the linked list of magical
features.

The C<name> and C<namlem> arguments, if non-null and non-zero respectively,
tell Perl that the C<sv> argument is the name of a variable. /* XXX */
The variable name is stored in the C<mg_ptr> field of the C<MAGIC> structure.

The C<how> argument specifies what kind of magicalness the C<sv> is
to receive.  This single character is stored in the C<mg_type> field
of the C<MAGIC> structure.

This argument also tells Perl which C routines within Perl should be used
when accessing the magical variable.  The C<mg_virtual> field in the
C<MAGIC> structure is a pointer to a C<MGVTBL>, which is a structure
of function pointers and stands for "Magic Virtual Table" to handle the
various operations that might be applied to that variable.

The C<MGVTBL> has five pointers to the following routine types:

    int  (*svt_get)(SV* sv, MAGIC* mg);
    int  (*svt_set)(SV* sv, MAGIC* mg);
    U32  (*svt_len)(SV* sv, MAGIC* mg);
    int  (*svt_clear)(SV* sv, MAGIC* mg);
    int  (*svt_free)(SV* sv, MAGIC* mg);

This MGVTBL structure is set at compile-time in C<perl.h> and there are
currently 19 types (or 21 with overloading turned on).  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 after 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.

For instance, the MGVTBL structure called C<vtbl_sv> contains:

    { magic_get, magic_set, magic_len, 0, 0 }

Thus, when an SV is determined to be magical, if a get operation is being
performed, the routine C<magic_get> is called.  All the various routines
for the various magical types begin with C<magic_>.

The current kinds of Magic Virtual Tables are:

    mg_type  MGVTBL              Type of magicalness
    -------  ------              -------------------
    \0       vtbl_sv             Regexp???
    A        vtbl_amagic         Operator Overloading
    a        vtbl_amagicelem     Operator Overloading
    c        0                   Used in Operator Overloading
    B        vtbl_bm             Boyer-Moore???
    E        vtbl_env            %ENV Hash???
    e        vtbl_envelem        %ENV hash???
    g        vtbl_mglob          Regexp /g flag???
    I        vtbl_isa            @ISA array
    i        vtbl_isaelem        @ISA array element
    L        0 (but sets RMAGICAL)     Perl Module/Debugger???
    l        vtbl_dbline         Debugger?
    P        vtbl_pack           Tied Array or Hash???
    p        vtbl_packelem       Tied Scalar or Handle???
    q        vtbl_packelem       Tied Scalar or Handle???
    S        vtbl_sig            Signal Hash
    s        vtbl_sigelem        Signal Hash element
    t        vtbl_taint          Taintedness
    U        vtbl_uvar	         ???
    v        vtbl_vec	         Vector
    x        vtbl_substr         Substring???
    *        vtbl_glob           GV???
    #        vtbl_arylen         Array Length???
    .        vtbl_pos	         ???
    ~        Reserved for extensions, but multiple extensions may clash

When an upper-case and lower-case letter both exist in the table, then the
upper-case letter is some kind of composite type (a list or a hash), and
the lower-case letter is an element of that composite type.

The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
structure.  If it is not the same as the C<sv> argument, the reference
count of the C<obj> object is incremented.  If it is the same, or if
the C<how> argument is "#", then C<obj> is merely stored, without the
reference count being incremented.

Another often-used routine is:

    MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */

This routine returns a pointer to the C<MAGIC> structure stored in the SV.
If the SV does not have that magical feature, C<NULL> is returned.  Also,
if the SV is not of type SVt_PVMG, Perl may core-dump.

    int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);

This routine checks to see what types of magic C<sv> has.  If the mg_type
field is an upper-case letter, then the mg_obj is copied to C<nsv>, but
the mg_type field is changed to be the lower-case letter.

