osfameron > Perl-Tags-0.23 > Perl::Tags



Annotate this POD


Open  2
View/Report Bugs
Module Version: 0.23   Source   Latest Release: Perl-Tags-0.28


Perl::Tags - Generate (possibly exuberant) Ctags style tags for Perl sourcecode


        use Perl::Tags;
        my $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
            files => ['Foo.pm', 'bar.pl'],

Recursively follows use and require statements, up to a maximum of max_level.

The implemented tagger, Perl::Tags::Naive is a more-or-less straight ripoff, slightly updated, of the original pltags code, and is rather naive. It should be possible to subclass using something like PPI or Text::Balanced, though be aware that this is alpha software and the internals are subject to change (so get in touch to let me know what you want to do and I'll try to help).


    * Recursive, incremental tagging.
    * parses `use_ok`/`require_ok` line from Test::More

USING with VIM ^

Perl::Tags is designed to be used with vim. My ~/.vim/ftplugin/perl.vim contains the following:

    setlocal iskeyword+=:  " make tags with :: in them useful

    if ! exists("s:defined_functions")
    function s:init_tags()
        perl <<EOF
            use Perl::Tags;
            $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
                # only go one level down by default

    function s:do_tags(filename)
        perl <<EOF
            my $filename = VIM::Eval('a:filename');

            $naive_tagger->process(files => $filename, refresh=>1 );

            # we'll now do a global (for this PID) tags file which will get updated as you source dive.

            my $tagsfile="/tmp/tags_$$";

            # of course, it may not even output, for example, if there's nothing new to process
            $naive_tagger->output( outfile => $tagsfile );

    call s:init_tags() " only the first time

    let s:defined_functions = 1

    call s:do_tags(expand('%'))



Perl::Tags is an abstract baseclass. Perl::Tags::Naive is provided and can be instantiated with new.

    $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );

Accepts the following parameters

    max_level:    levels of "use" statements to descend into, default 2
    do_variables: tag variables?  default 1 (true)
    exts:         use the Exuberant extensions


A Perl::Tags object will stringify to a textual representation of a ctags file.

    print $tagger;


Delete all tags, but without touching the "order" seen, that way, if the tags are recreated, they will remain near the top of the "interestingness" tree


Save the file to disk if it has changed. (The private {is_dirty} attribute is used, as the tags object may be made up incrementally and recursively within your IDE.


Scan one or more Perl file for tags

        files => [ 'Module.pm',  'script.pl' ] 
        files   => 'script.pl',
        refresh => 1,

queue, popqueue

Internal methods managing the processing

process_item, process_file

Do the heavy lifting for process above.


The parsing is done by a number of lightweight objects (parsers) which look for subroutine references, variables, module inclusion etc. When they are successful, they call the register method in the main tags object.


Return the parses for this object. Abstract, see Perl::Tags::Naive below.

Perl::Tags::Naive ^

A naive implementation. That is to say, it's based on the classic pltags.pl script distributed with Perl, which is by and large a better bet than the results produced by ctags. But a "better" approach may be to integrate this with PPI.


See TodoTagger in the t/ directory of the distribution for a fully working example (tested in <t/02_subclass.t>). You may want to reuse parsers in the ::Naive package, or use all of the existing parsers and add your own.

    package My::Tagger;
    use Perl::Tags;
    our @ISA = qw( Perl::Tags::Naive );

    sub get_parsers {
        my $self = shift;
        return (
            $self->can('todo_line'),     # a new parser
            $self->SUPER::get_parsers(), # all ::Naive's parsers
            # or maybe...
            $self->can('variable'),      # one of ::Naive's parsers

    sub todo_line { 
        # your new parser code here!
    sub package_line {
        # override one of ::Naive's parsers

Because ::Naive uses can('parser') instead of \&parser, you can just override a particular parser by redefining in the subclass.


The following parsers are defined by this module.


A filter rather than a parser, removes whitespace and comments.


Tags definitions of my, our, and local variables. Unlike pltags.pl, we don't yet handle continuations for this or for other parsers (e.g.

    my ( $var1,
         $var2 );   # <--- $var2 won't be tagged

Returns a Perl::Tags::Tag::Var if found


Parse a package declaration, returning a Perl::Tags::Tag::Package if found.


Parse the declaration of a subroutine, returning a Perl::Tags::Tag::Sub if found.


Parse a use, require, and also a use_ok line (from Test::More). Uses a dummy tag (Perl::Tags::Tag::Recurse to do so).

Perl::Tags::Tag ^

A superclass for tags


Returns a new tag object

type, modify_options

Abstract methods


A tag stringifies to an appropriate line in a ctags file.


Allows tag to meddle with process when registered with the main tagger object. Return false if want to prevent registration (true normally).`

Perl::Tags::Tag::Package ^

type: p


Sets static=0


Sets the package name

Perl::Tags::Tag::Var ^

type: v


        Make a tag for this variable unless we're told not to.  We
        assume that a variable is always static, unless it appears
        in a package before any sub.  (Not necessarily true, but
        it's ok for most purposes and Vim works fine even if it is
            - pltags.pl comments

Perl::Tags::Tag::Sub ^

type: s


        Make a tag for this sub unless we're told not to.  We assume
        that a sub is static, unless it appears in a package.  (Not
        necessarily true, but it's ok for most purposes and Vim works
        fine even if it is incorrect)
            - pltags comments

Perl::Tags::Tag::Recurse ^

type: dummy


Recurse adding this new module to the queue.


    osfameron (2006) - osfameron@gmail.com

For support, try emailing me or grabbing me on irc #london.pm on irc.perl.org

This was originally ripped off pltags.pl, as distributed with vim and available from http://www.mscha.com/mscha.html?pltags#tools Version 2.3, 28 February 2002 Written by Michael Schaap <pltags@mscha.com>.

This is licensed under the same terms as Perl itself. (Or as Vim if you prefer).

syntax highlighting: