README

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

SYNOPSIS
  Using Perl::Tags to assist your development
    "Perl::Tags" is designed to be integrated into your development
    environment. Here are a few ways to use it:

   With Vim
    "Perl::Tags" was originally designed to be used with vim. See
    <https://github.com/osfameron/perl-tags-vim> for an easily installable
    Plugin.

    NB: You will need to have a vim with perl compiled in it. Debuntu
    packages this as "vim-perl". Alternatively you can compile from source
    (you'll need Perl + the development headers "libperl-dev").

    (Note that "perl-tags-vim" includes its own copy of "Perl::Tags" through
    the magic of git submodules and App::FatPacker, so you don't need to
    install this module from CPAN if you are only intending to use it with
    Vim as above!)

   From the Command Line
    See the "perl-tags" in bin script provided.

   From other editors
    Any editor that supports ctags should be able to use this output.
    Documentation and code patches on how to do this are welcome.

  Using the Perl::Tags module within your code
            use Perl::Tags;
            my $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
            $naive_tagger->process(
                files => ['Foo.pm', 'bar.pl'],
                refresh=>1 
            );

            print $naive_tagger; # stringifies to ctags file

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

DETAILS
    There are several taggers distributed with this distribution, including:

    Perl::Tags::Naive
        This is a more-or-less straight ripoff, slightly updated, of the
        original pltags code. This is a "naive" tagger, in that it makes
        pragmatic assumptions about what Perl code usually looks like (e.g.
        it doesn't actually parse the code.) This is fast, lightweight, and
        often Good Enough.

        This has additional subclasses such as Perl::Tags::Naive::Moose to
        parse Moose declarations, and Perl::Tags::Naive::Lib to parse "use
        lib".

    Perl::Tags::PPI
        Uses the PPI module to do a deeper analysis and parsing of your Perl
        code. This is more accurate, but slower.

    Perl::Tags::Hybrid
        Can run multiple taggers, such as ::Naive and ::PPI, combining the
        results.

EXTENDING
    Documentation patches are welcome: in the meantime, have a look at
    Perl::Tags::Naive and its subclasses for a simple line-by-line method of
    tagging files. Alternatively Perl::Tags::PPI uses PPI's built in method
    of parsing Perl documents.

    In general, you will want to override the "get_tags_for_file" method,
    returning a list of "Perl::Tags::Tag" objects to be registered.

    For recursively checking other modules, return a
    "Perl::Tags::Tag::Recurse" object, which does *not* create a new tag in
    the resulting perltags file, but instead processes the next file
    recursively.

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

METHODS
  "new"
    Perl::Tags is an abstract baseclass. Use a class such as
    Perl::Tags::Naive and instantiate it 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

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

        print $tagger;

  "clean_file"
    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

  "output"
    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.

  "process"
    Scan one or more Perl file for tags

        $tagger->process( 
            files => [ 'Module.pm',  'script.pl' ] 
        );
        $tagger->process(
            files   => 'script.pl',
            refresh => 1,
        );

  "queue", "popqueue"
    Internal methods managing the processing

  "process_item", "process_file", "get_tags_for_file"
    Do the heavy lifting for "process" above.

    Taggers *must* override the abstract method "get_tags_for_file".

  "register"
    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.

    Note that if your tagger wants to register not a new *declaration* but
    rather a *usage* of another module, then your tagger should return a
    "Perl::Tags::Tag::Recurse" object. This is a pseudo-tag which causes the
    linked module to be scanned in turn. See Perl::Tags::Naive's handling of
    "use" statements as an example!

SEE ALSO
    "perl-tags" in bin

CONTRIBUTIONS
    Contributions are always welcome. The repo is in git:

        http://github.com/osfameron/perl-tags

    Please fork and make pull request. Maint bits available on request.

    DMITRI
        many patches for features and bugfixes

    wolverian
        ::PPI subclass

    Ian Tegebo
        patch to use File::Temp

    drbean
        ::Naive::Moose, ::Naive::Spiffy and ::Naive::Lib subclasses

    Alias
        prodding me to make repo public

    tsee
        Command line interface, applying patches

    nothingmuch
    Andreas Koenig
    ether

AUTHOR and LICENSE
        osfameron (2006-2014) - osfameron@cpan.org
                                and contributors, as above

    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).