#! /usr/bin/env perl
# ABSTRACT: analyse your Perl documents (without running them)
# PODNAME: perlanalyst
use strict;
use warnings;
use FindBin qw($Bin);
use lib "$Bin/../lib/perl5";
use App::Perlanalyst;
my $app = App::Perlanalyst->new();
$app->process_args(@ARGV);
exit( $app->run ? 0 : 1 );
__END__
=pod
=head1 NAME
perlanalyst - analyse your Perl documents (without running them)
=head1 VERSION
version 0.004
=head1 SYNOPSIS
perlanalyst [OPTIONS] [FILES OR DIRECTORIES]
=head1 DESCRIPTION
Perlanalyst is a tool to analyse your Perl documents. This is done via
static analysis, e.g. the code is analysed without running it.
=head1 USAGE EXAMPLES
Before getting into all the gory details, here are some basic usage
examples to help get you started.
# find all subroutine declarations, recursively process all Perl
# files beneath directory
perlanalyst -all Sub
# the same, but show only the declaration of the subroutine "foo"
perlanalyst -all Sub --filter Name=foo
# the same, but asked as a question
perlananalyst --question Sub::Name=foo
# the same, but look in another directory
perlananalyst -q Sub::Name=foo ~/perl5/lib/perl5/Test
# see a list of the files that would be examined
perlanalyst --list-files
=head1 FILE SELECTION
The Perlanalyst examines only files that end in C, C or C except
if you specify the file names directly on the command line.
It can also list files that would be analysed, without actually searching
them.
=head1 DIRECTORY SELECTION
The program descends through the directory tree of the starting directories
specified. If no file or directory is specified, perlanalyst descends through
the current directory.
=head1 OPTIONS
=over 4
=item B>, B>
Run the analysis of the given I.
=item B>, B>
Send the results of the analysis through this filter. Can be specified
multiple times, the filters are run in the order they appear one the command
line.
=item B>, B>
Ask the question of that name.
=item B
List available analyses.
=item B
List available filters.
=item B
List files that would be examined. Does nothing else an exits
afterwards.
=item B
List available questions.
=back
=head1 CONCEPTS
=head2 Analysis
An analysis examines a file in a simple way and returns a list of results.
For example, a very simple analysis is: Give me all declarations of lexical
variables.
=head2 Filter
A filter takes the results of an analysis and ... um ... filters it. An example
would be: Give me all lexical variables with the name "foo".
=head2 Question
A question is an analysis followed by one or more filters.
=head1 STATUS
This is a proof of concept that was hacked together whilst enjoying the
13th German Perl Workshop in Frankfurt. Hacking was done on the train to and
from Frankfurt and at the workshop itself.
=head1 PLAN
=over 4
=item Add database support.
The results of each analysis will be written to a database. Filters run
on the data that was read from the database so analysis and questions can
be performed in different steps.
=item More basic level analyses, filters and questions.
Write more basic analyses using PPI and file operations. Write more filters
and combine them in questions.
=item Introduce higher level analysis, filters and questions.
Higher level anaylses combine results from lower level analyses. For example,
to see what package variables are declared, we have to know where the keywords
C and C are used and in what scope.
=item Run analyses only once per unmodified file.
Perform an analyses once to get that initial data for a file and then only
if it was modified.
=item Build other tools around it.
The first one might be a simple web application (using L?) to browse
the database (using L?).
The second one might be a simple RESTful server (using
L?).
The third one could be some kind of connection to Perl::Critic. Since this
feels so natural and obvious to me, it might actually be the first one that
should be built.
=back
=head1 SEE ALSO
L is used for parsing the Perl documents.
L is a different kind of tool. It has the knowledge of experienced
perl programmers built in and tells you if your code smells.
=head1 AUTHOR
Gregor Goldbach
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Gregor Goldbach.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut