git.maemo.org Git - dh-make-perl/blob - dev/arm/libdevel-symdump-perl/libdevel-symdump-perl-2.08/README

   1 NAME
   2     Devel::Symdump - dump symbol names or the symbol table
   3
   4 SYNOPSIS
   5         # Constructor
   6         require Devel::Symdump;
   7         @packs = qw(some_package another_package);
   8         $obj = Devel::Symdump->new(@packs);        # no recursion
   9         $obj = Devel::Symdump->rnew(@packs);       # with recursion
  10
  11         # Methods
  12         @array = $obj->packages;
  13         @array = $obj->scalars;
  14         @array = $obj->arrays;
  15         @array = $obj->hashes;
  16         @array = $obj->functions;
  17         @array = $obj->filehandles;  # deprecated, use ios instead
  18         @array = $obj->dirhandles;   # deprecated, use ios instead
  19         @array = $obj->ios;
  20         @array = $obj->unknowns;     # only perl version < 5.003 had some
  21
  22         $string = $obj->as_string;
  23         $string = $obj->as_HTML;
  24         $string = $obj1->diff($obj2);
  25
  26         $string = Devel::Symdump->isa_tree;    # or $obj->isa_tree
  27         $string = Devel::Symdump->inh_tree;    # or $obj->inh_tree
  28
  29         # Methods with autogenerated objects
  30         # all of those call new(@packs) internally
  31         @array = Devel::Symdump->packages(@packs);
  32         @array = Devel::Symdump->scalars(@packs);
  33         @array = Devel::Symdump->arrays(@packs);
  34         @array = Devel::Symdump->hashes(@packs);
  35         @array = Devel::Symdump->functions(@packs);
  36         @array = Devel::Symdump->ios(@packs);
  37         @array = Devel::Symdump->unknowns(@packs);
  38
  39 DESCRIPTION
  40     This little package serves to access the symbol table of perl.
  41
  42     "Devel::Symdump->rnew(@packages)"
  43         returns a symbol table object for all subtrees below @packages.
  44         Nested Modules are analyzed recursively. If no package is given as
  45         argument, it defaults to "main". That means to get the whole symbol
  46         table, just do a "rnew" without arguments.
  47
  48         The global variable $Devel::Symdump::MAX_RECURSION limits the
  49         recursion to prevent contention. The default value is set to 97,
  50         just low enough to survive the test suite without a warning about
  51         deep recursion.
  52
  53     "Devel::Symdump->new(@packages)"
  54         does not go into recursion and only analyzes the packages that are
  55         given as arguments.
  56
  57     packages, scalars, arrays, hashes, functions, ios
  58         The methods packages(), scalars(), arrays(), hashes(), functions(),
  59         ios(), and (for older perls) unknowns() each return an array of
  60         fully qualified symbols of the specified type in all packages that
  61         are held within a Devel::Symdump object, but without the leading
  62         "$", "@" or "%". In a scalar context, they will return the number of
  63         such symbols. Unknown symbols are usually either formats or
  64         variables that haven't yet got a defined value.
  65
  66     as_string
  67     as_HTML
  68         As_string() and as_HTML() return a simple string/HTML
  69         representations of the object.
  70
  71     diff
  72         Diff() prints the difference between two Devel::Symdump objects in
  73         human readable form. The format is similar to the one used by the
  74         as_string method.
  75
  76     isa_tree
  77     inh_tree
  78         Isa_tree() and inh_tree() both return a simple string representation
  79         of the current inheritance tree. The difference between the two
  80         methods is the direction from which the tree is viewed: top-down or
  81         bottom-up. As I'm sure, many users will have different expectation
  82         about what is top and what is bottom, I'll provide an example what
  83         happens when the Socket module is loaded:
  84
  85     % print Devel::Symdump->inh_tree
  86             AutoLoader
  87                     DynaLoader
  88                             Socket
  89             DynaLoader
  90                     Socket
  91             Exporter
  92                     Carp
  93                     Config
  94                     Socket
  95
  96         The inh_tree method shows on the left hand side a package name and
  97         indented to the right the packages that use the former.
  98
  99     % print Devel::Symdump->isa_tree
 100             Carp
 101                     Exporter
 102             Config
 103                     Exporter
 104             DynaLoader
 105                     AutoLoader
 106             Socket
 107                     Exporter
 108                     DynaLoader
 109                             AutoLoader
 110
 111         The isa_tree method displays from left to right ISA relationships,
 112         so Socket IS A DynaLoader and DynaLoader IS A AutoLoader. (Actually,
 113         they were at the time this manpage was written)
 114
 115     You may call both methods, isa_tree() and inh_tree(), with an object. If
 116     you do that, the object will store the output and retrieve it when you
 117     call the same method again later. The typical usage would be to use them
 118     as class methods directly though.
 119
 120 SUBCLASSING
 121     The design of this package is intentionally primitive and allows it to
 122     be subclassed easily. An example of a (maybe) useful subclass is
 123     Devel::Symdump::Export, a package which exports all methods of the
 124     Devel::Symdump package and turns them into functions.
 125
 126 AUTHORS
 127     Andreas Koenig <andk@cpan.org> and Tom Christiansen <tchrist@perl.com>.
 128     Based on the old dumpvar.pl by Larry Wall.
 129
 130 COPYRIGHT, LICENSE
 131     This module is
 132
 133     Copyright (c) 1995, 1997, 2000, 2002, 2005, 2006 Andreas Koenig
 134     "<andk@cpan.org>".
 135
 136     All rights reserved.
 137
 138     This library is free software; you may use, redistribute and/or modify
 139     it under the same terms as Perl itself.
 140