Blame README

Packit b48d6e
NAME
Packit b48d6e
    Devel::Symdump - dump symbol names or the symbol table
Packit b48d6e
Packit b48d6e
SYNOPSIS
Packit b48d6e
        # Constructor
Packit b48d6e
        require Devel::Symdump;
Packit b48d6e
        @packs = qw(some_package another_package);
Packit b48d6e
        $obj = Devel::Symdump->new(@packs);        # no recursion
Packit b48d6e
        $obj = Devel::Symdump->rnew(@packs);       # with recursion
Packit b48d6e
Packit b48d6e
        # Methods
Packit b48d6e
        @array = $obj->packages;
Packit b48d6e
        @array = $obj->scalars;
Packit b48d6e
        @array = $obj->arrays;
Packit b48d6e
        @array = $obj->hashes;
Packit b48d6e
        @array = $obj->functions;
Packit b48d6e
        @array = $obj->filehandles;  # deprecated, use ios instead
Packit b48d6e
        @array = $obj->dirhandles;   # deprecated, use ios instead
Packit b48d6e
        @array = $obj->ios;
Packit b48d6e
        @array = $obj->unknowns;     # only perl version < 5.003 had some
Packit b48d6e
Packit b48d6e
        $string = $obj->as_string;
Packit b48d6e
        $string = $obj->as_HTML;
Packit b48d6e
        $string = $obj1->diff($obj2);
Packit b48d6e
Packit b48d6e
        $string = Devel::Symdump->isa_tree;    # or $obj->isa_tree
Packit b48d6e
        $string = Devel::Symdump->inh_tree;    # or $obj->inh_tree
Packit b48d6e
Packit b48d6e
        # Methods with autogenerated objects
Packit b48d6e
        # all of those call new(@packs) internally
Packit b48d6e
        @array = Devel::Symdump->packages(@packs);
Packit b48d6e
        @array = Devel::Symdump->scalars(@packs);
Packit b48d6e
        @array = Devel::Symdump->arrays(@packs);
Packit b48d6e
        @array = Devel::Symdump->hashes(@packs);
Packit b48d6e
        @array = Devel::Symdump->functions(@packs);
Packit b48d6e
        @array = Devel::Symdump->ios(@packs);
Packit b48d6e
        @array = Devel::Symdump->unknowns(@packs);
Packit b48d6e
Packit b48d6e
DESCRIPTION
Packit b48d6e
    This little package serves to access the symbol table of perl.
Packit b48d6e
Packit b48d6e
    "Devel::Symdump->rnew(@packages)"
Packit b48d6e
        returns a symbol table object for all subtrees below @packages.
Packit b48d6e
        Nested Modules are analyzed recursively. If no package is given as
Packit b48d6e
        argument, it defaults to "main". That means to get the whole symbol
Packit b48d6e
        table, just do a "rnew" without arguments.
Packit b48d6e
Packit b48d6e
        The global variable $Devel::Symdump::MAX_RECURSION limits the
Packit b48d6e
        recursion to prevent contention. The default value is set to 97,
Packit b48d6e
        just low enough to survive the test suite without a warning about
Packit b48d6e
        deep recursion.
Packit b48d6e
Packit b48d6e
    "Devel::Symdump->new(@packages)"
Packit b48d6e
        does not go into recursion and only analyzes the packages that are
Packit b48d6e
        given as arguments.
Packit b48d6e
Packit b48d6e
    packages, scalars, arrays, hashes, functions, ios
Packit b48d6e
        The methods packages(), scalars(), arrays(), hashes(), functions(),
Packit b48d6e
        ios(), and (for older perls) unknowns() each return an array of
Packit b48d6e
        fully qualified symbols of the specified type in all packages that
Packit b48d6e
        are held within a Devel::Symdump object, but without the leading
Packit b48d6e
        "$", "@" or "%". In a scalar context, they will return the number of
Packit b48d6e
        such symbols. Unknown symbols are usually either formats or
Packit b48d6e
        variables that haven't yet got a defined value.
Packit b48d6e
Packit b48d6e
        Note that scalar symbol table entries are a special case. If a
Packit b48d6e
        symbol table entry exists at all, presence of a scalar is currently
Packit b48d6e
        unknowable, due to a feature of Perl described in "Making
Packit b48d6e
        References" in perlref point 7. For example, this package will mark
Packit b48d6e
        a scalar value $foo as present if any of @foo, %foo, &foo etc. have
Packit b48d6e
        been declared or used.
Packit b48d6e
Packit b48d6e
    as_string
Packit b48d6e
    as_HTML
Packit b48d6e
        As_string() and as_HTML() return a simple string/HTML
Packit b48d6e
        representations of the object.
Packit b48d6e
Packit b48d6e
    diff
Packit b48d6e
        Diff() prints the difference between two Devel::Symdump objects in
Packit b48d6e
        human readable form. The format is similar to the one used by the
Packit b48d6e
        as_string method.
Packit b48d6e
Packit b48d6e
    isa_tree
Packit b48d6e
    inh_tree
Packit b48d6e
        Isa_tree() and inh_tree() both return a simple string representation
Packit b48d6e
        of the current inheritance tree. The difference between the two
Packit b48d6e
        methods is the direction from which the tree is viewed: top-down or
Packit b48d6e
        bottom-up. As I'm sure, many users will have different expectation
Packit b48d6e
        about what is top and what is bottom, I'll provide an example what
Packit b48d6e
        happens when the Socket module is loaded:
Packit b48d6e
Packit b48d6e
    % print Devel::Symdump->inh_tree
Packit b48d6e
            AutoLoader
Packit b48d6e
                    DynaLoader
Packit b48d6e
                            Socket
Packit b48d6e
            DynaLoader
Packit b48d6e
                    Socket
Packit b48d6e
            Exporter
Packit b48d6e
                    Carp
Packit b48d6e
                    Config
Packit b48d6e
                    Socket
Packit b48d6e
Packit b48d6e
        The inh_tree method shows on the left hand side a package name and
Packit b48d6e
        indented to the right the packages that use the former.
Packit b48d6e
Packit b48d6e
    % print Devel::Symdump->isa_tree
Packit b48d6e
            Carp
Packit b48d6e
                    Exporter
Packit b48d6e
            Config
Packit b48d6e
                    Exporter
Packit b48d6e
            DynaLoader
Packit b48d6e
                    AutoLoader
Packit b48d6e
            Socket
Packit b48d6e
                    Exporter
Packit b48d6e
                    DynaLoader
Packit b48d6e
                            AutoLoader
Packit b48d6e
Packit b48d6e
        The isa_tree method displays from left to right ISA relationships,
Packit b48d6e
        so Socket IS A DynaLoader and DynaLoader IS A AutoLoader. (Actually,
Packit b48d6e
        they were at the time this manpage was written)
Packit b48d6e
Packit b48d6e
    You may call both methods, isa_tree() and inh_tree(), with an object. If
Packit b48d6e
    you do that, the object will store the output and retrieve it when you
Packit b48d6e
    call the same method again later. The typical usage would be to use them
Packit b48d6e
    as class methods directly though.
Packit b48d6e
Packit b48d6e
SUBCLASSING
Packit b48d6e
    The design of this package is intentionally primitive and allows it to
Packit b48d6e
    be subclassed easily. An example of a (maybe) useful subclass is
Packit b48d6e
    Devel::Symdump::Export, a package which exports all methods of the
Packit b48d6e
    Devel::Symdump package and turns them into functions.
Packit b48d6e
Packit b48d6e
SEE ALSO
Packit b48d6e
    Routines for manipulating stashes: "Package::Stash"; to work with
Packit b48d6e
    lexicals: "PadWalker".
Packit b48d6e
Packit b48d6e
AUTHORS
Packit b48d6e
    Andreas Koenig <andk@cpan.org> and Tom Christiansen <tchrist@perl.com>.
Packit b48d6e
    Based on the old dumpvar.pl by Larry Wall.
Packit b48d6e
Packit b48d6e
COPYRIGHT, LICENSE
Packit b48d6e
    This module is
Packit b48d6e
Packit b48d6e
    Copyright (c) 1995, 1997, 2000, 2002, 2005, 2006 Andreas Koenig
Packit b48d6e
    "<andk@cpan.org>".
Packit b48d6e
Packit b48d6e
    All rights reserved.
Packit b48d6e
Packit b48d6e
    This library is free software; you may use, redistribute and/or modify
Packit b48d6e
    it under the same terms as Perl itself.
Packit b48d6e