NAME
perlanalyst - analyse your Perl documents (without running them)
VERSION
version 0.003
SYNOPSIS
perlanalyst [OPTIONS] [FILES OR DIRECTORIES]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.
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-filesFILE SELECTION
The Perlanalyst examines only files that end in .pl, .pm or .t 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.
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.
OPTIONS
- -a NAME, --analysis NAME
-
Run the analysis of the given NAME.
- -f NAME, --filter NAME
-
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.
- -q NAME, --question NAME
-
Ask the question of that name.
- --list-analyses
-
List available analyses.
- --list-filters
-
List available filters.
- --list-files
-
List files that would be examined. Does nothing else an exits afterwards.
- --list-questions
-
List available questions.
CONCEPTS
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.
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".
Question
A question is an analysis followed by one or more filters.
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.
PLAN
- 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.
- More basic level analyses, filters and questions.
-
Write more basic analyses using PPI and file operations. Write more filters and combine them in questions.
- 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
packageandourare used and in what scope. - 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.
- Build other tools around it.
-
The first one might be a simple web application (using Dancer?) to browse the database (using Dancer::Plugin::Database?).
The second one might be a simple RESTful server (using Dancer::Plugin::REST?).
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.
SEE ALSO
PPI is used for parsing the Perl documents.
Perl::Critic is a different kind of tool. It has the knowledge of experienced perl programmers built in and tells you if your code smells.
AUTHOR
Gregor Goldbach <glauschwuffel@nomaden.org>
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.