view release on metacpan or  search on metacpan

lib/PPI.pm  view on Meta::CPAN

The Perl Document Transformation API. Provides a standard interface and
abstract base class for objects and classes that manipulate Documents.

=back

=head1 INSTALLING

The core PPI distribution is pure Perl and has been kept as tight as
possible and with as few dependencies as possible.

It should download and install normally on any platform from within
the CPAN and CPANPLUS applications, or directly using the distribution
tarball. If installing by hand, you may need to install a few small
utility modules first. The exact ones will depend on your version of
perl.

There are no special install instructions for PPI, and the normal
C<Perl Makefile.PL>, C<make>, C<make test>, C<make install> instructions
apply.

=head1 EXTENDING

The PPI namespace itself is reserved for use by PPI itself.
You are recommended to use the PPIx:: namespace for PPI-specific
modifications or prototypes thereof, or Perl:: for modules which provide
a general Perl language-related functions.

If what you wish to implement looks like it fits into the PPIx:: namespace,
you should consider contacting the PPI maintainers on GitHub first, as what
you want may already be in progress, or you may wish to consider contributing
to PPI itself.

=head1 TO DO

- Many more analysis and utility methods for PDOM classes

- Creation of a PPI::Tutorial document

- Add many more key functions to PPI::XS

- We can B<always> write more and better unit tests

- Complete the full implementation of -E<gt>literal (1.200)

- Full understanding of scoping (due 1.300)

=head1 SUPPORT

The most recent version of PPI is available at the following address.

L<https://metacpan.org/pod/PPI>

PPI source is maintained in a GitHub repository at the following address.

L<https://github.com/Perl-Critic/PPI>

Contributions via GitHub pull request are welcome.

Bug fixes in the form of pull requests or bug reports with
new (failing) unit tests have the best chance of being addressed
by busy maintainers, and are B<strongly> encouraged.

If you cannot provide a test or fix, or don't have time to do so,
then regular bug reports are still accepted and appreciated via the
GitHub bug tracker.

L<https://github.com/Perl-Critic/PPI/issues>

The C<ppidump> utility that is part of the L<Perl::Critic> distribution
is a useful tool for demonstrating how PPI is parsing (or misparsing)
small code snippets, and for providing information for bug reports.

For other issues, questions, or commercial or media-related enquiries,
contact the author.

=head1 AUTHOR

Adam Kennedy E<lt>adamk@cpan.orgE<gt>

=head1 ACKNOWLEDGMENTS

A huge thank you to Phase N Australia
(L<https://web.archive.org/web/20240304122957/http://www.phase-n.com/>) for
permitting the original open sourcing and release of this distribution from
what was originally several thousand hours of commercial work.

Another big thank you to The Perl Foundation
(L<http://www.perlfoundation.org/>) for funding for the final big
refactoring and completion run.

Also, to the various co-maintainers that have contributed both large and
small with tests and patches and especially to those rare few who have
deep-dived into the guts to (gasp) add a feature.

  - Dan Brook       : PPIx::XPath, Acme::PerlML
  - Audrey Tang     : "Line Noise" Testing
  - Arjen Laarhoven : Three-element ->location support
  - Elliot Shank    : Perl 5.10 support, five-element ->location

And finally, thanks to those brave ( and foolish :) ) souls willing to dive
in and use, test drive and provide feedback on PPI before version 1.000,
in some cases before it made it to beta quality, and still did extremely
distasteful things (like eating 50 meg of RAM a second).

I owe you all a beer. Corner me somewhere and collect at your convenience.
If I missed someone who wasn't in my email history, thank you too :)

  # In approximate order of appearance
  - Claes Jacobsson
  - Michael Schwern
  - Jeff T. Parsons
  - CPAN Author "CHOCOLATEBOY"
  - Robert Rotherberg
  - CPAN Author "PODMASTER"
  - Richard Soderberg
  - Nadim ibn Hamouda el Khemir
  - Graciliano M. P.
  - Leon Brocard
  - Jody Belka
  - Curtis Ovid
  - Yuval Kogman