Blob Blame History Raw
NAME
    Devel::Symdump - dump symbol names or the symbol table

SYNOPSIS
        # Constructor
        require Devel::Symdump;
        @packs = qw(some_package another_package);
        $obj = Devel::Symdump->new(@packs);        # no recursion
        $obj = Devel::Symdump->rnew(@packs);       # with recursion

        # Methods
        @array = $obj->packages;
        @array = $obj->scalars;
        @array = $obj->arrays;
        @array = $obj->hashes;
        @array = $obj->functions;
        @array = $obj->filehandles;  # deprecated, use ios instead
        @array = $obj->dirhandles;   # deprecated, use ios instead
        @array = $obj->ios;
        @array = $obj->unknowns;     # only perl version < 5.003 had some

        $string = $obj->as_string;
        $string = $obj->as_HTML;
        $string = $obj1->diff($obj2);

        $string = Devel::Symdump->isa_tree;    # or $obj->isa_tree
        $string = Devel::Symdump->inh_tree;    # or $obj->inh_tree

        # Methods with autogenerated objects
        # all of those call new(@packs) internally
        @array = Devel::Symdump->packages(@packs);
        @array = Devel::Symdump->scalars(@packs);
        @array = Devel::Symdump->arrays(@packs);
        @array = Devel::Symdump->hashes(@packs);
        @array = Devel::Symdump->functions(@packs);
        @array = Devel::Symdump->ios(@packs);
        @array = Devel::Symdump->unknowns(@packs);

DESCRIPTION
    This little package serves to access the symbol table of perl.

    "Devel::Symdump->rnew(@packages)"
        returns a symbol table object for all subtrees below @packages.
        Nested Modules are analyzed recursively. If no package is given as
        argument, it defaults to "main". That means to get the whole symbol
        table, just do a "rnew" without arguments.

        The global variable $Devel::Symdump::MAX_RECURSION limits the
        recursion to prevent contention. The default value is set to 97,
        just low enough to survive the test suite without a warning about
        deep recursion.

    "Devel::Symdump->new(@packages)"
        does not go into recursion and only analyzes the packages that are
        given as arguments.

    packages, scalars, arrays, hashes, functions, ios
        The methods packages(), scalars(), arrays(), hashes(), functions(),
        ios(), and (for older perls) unknowns() each return an array of
        fully qualified symbols of the specified type in all packages that
        are held within a Devel::Symdump object, but without the leading
        "$", "@" or "%". In a scalar context, they will return the number of
        such symbols. Unknown symbols are usually either formats or
        variables that haven't yet got a defined value.

        Note that scalar symbol table entries are a special case. If a
        symbol table entry exists at all, presence of a scalar is currently
        unknowable, due to a feature of Perl described in "Making
        References" in perlref point 7. For example, this package will mark
        a scalar value $foo as present if any of @foo, %foo, &foo etc. have
        been declared or used.

    as_string
    as_HTML
        As_string() and as_HTML() return a simple string/HTML
        representations of the object.

    diff
        Diff() prints the difference between two Devel::Symdump objects in
        human readable form. The format is similar to the one used by the
        as_string method.

    isa_tree
    inh_tree
        Isa_tree() and inh_tree() both return a simple string representation
        of the current inheritance tree. The difference between the two
        methods is the direction from which the tree is viewed: top-down or
        bottom-up. As I'm sure, many users will have different expectation
        about what is top and what is bottom, I'll provide an example what
        happens when the Socket module is loaded:

    % print Devel::Symdump->inh_tree
            AutoLoader
                    DynaLoader
                            Socket
            DynaLoader
                    Socket
            Exporter
                    Carp
                    Config
                    Socket

        The inh_tree method shows on the left hand side a package name and
        indented to the right the packages that use the former.

    % print Devel::Symdump->isa_tree
            Carp
                    Exporter
            Config
                    Exporter
            DynaLoader
                    AutoLoader
            Socket
                    Exporter
                    DynaLoader
                            AutoLoader

        The isa_tree method displays from left to right ISA relationships,
        so Socket IS A DynaLoader and DynaLoader IS A AutoLoader. (Actually,
        they were at the time this manpage was written)

    You may call both methods, isa_tree() and inh_tree(), with an object. If
    you do that, the object will store the output and retrieve it when you
    call the same method again later. The typical usage would be to use them
    as class methods directly though.

SUBCLASSING
    The design of this package is intentionally primitive and allows it to
    be subclassed easily. An example of a (maybe) useful subclass is
    Devel::Symdump::Export, a package which exports all methods of the
    Devel::Symdump package and turns them into functions.

SEE ALSO
    Routines for manipulating stashes: "Package::Stash"; to work with
    lexicals: "PadWalker".

AUTHORS
    Andreas Koenig <andk@cpan.org> and Tom Christiansen <tchrist@perl.com>.
    Based on the old dumpvar.pl by Larry Wall.

COPYRIGHT, LICENSE
    This module is

    Copyright (c) 1995, 1997, 2000, 2002, 2005, 2006 Andreas Koenig
    "<andk@cpan.org>".

    All rights reserved.

    This library is free software; you may use, redistribute and/or modify
    it under the same terms as Perl itself.