Module::ExtractUse(3pm) 				User Contributed Perl Documentation				   Module::ExtractUse(3pm)

NAME

       Module::ExtractUse - Find out what modules are used

VERSION

       version 0.27

SYNOPSIS

	 use Module::ExtractUse;

	 # get a parser
	 my $p=Module::ExtractUse->new;

	 # parse from a file
	 $p->extract_use('/path/to/module.pm');

	 # or parse from a ref to a string in memory
	 $p->extract_use($string_containg_code);

	 # use some reporting methods
	 my $used=$p->used;	      # $used is a HASHREF
	 print $p->used('strict')     # true if code includes 'use strict'

	 my @used=$p->array;
	 my $used=$p->string;

DESCRIPTION

       Module::ExtractUse is basically a Parse::RecDescent grammar to parse Perl code. It tries very hard to find all modules (whether pragmas,
       Core, or from CPAN) used by the parsed code.

       "Usage" is defined by either calling "use" or "require".

   Methods
       new

	my $p=Module::ExtractUse->new;

       Returns a parser object

       extract_use

	 $p->extract_use('/path/to/module.pm');
	 $p->extract_use($string_containg_code);

       Runs the parser.

       $code_to_parse can be either a SCALAR, in which case Module::ExtractUse tries to open the file specified in $code_to_parse. Or a reference
       to a SCALAR, in which case Module::ExtractUse assumes the referenced scalar contains the source code.

       The code will be stripped from POD (using Pod::Strip) and split on ";" (semicolon). Each statement (i.e. the stuff between two semicolons)
       is checked by a simple regular expression.

       If the statement contains either 'use' or 'require', the statment is handed over to the parser, who then tries to figure out, what is used
       or required. The results will be saved in a data structure that you can examine afterwards.

       You can call "extract_use" several times on different files. It will count how many files where examined and how often each module was
       used.

   Accessor Methods
       Those are various ways to get at the result of the parse.

       Note that "extract_use" returns the parser object, so you can say

	 print $p->extract_use($code_to_parse)->string;

       used

	   my $used=$p->used;		# $used is a HASHREF
	   print $p->used('strict')	# true if code includes 'use strict'

       If called without an argument, returns a reference to an hash of all used modules. Keys are the names of the modules, values are the number
       of times they were used.

       If called with an argument, looks up the value of the argument in the hash and returns the number of times it was found during parsing.

       This is the preferred accessor.

       string

	   print $p->string($seperator)

       Returns a sorted string of all used modules, joined using the value of $seperator or using a blank space as a default;

       Module names are sorted by ascii value (i.e by "sort")

       array

	   my @array = $p->array;

       Returns an array of all used modules.

       arrayref

	   my $arrayref = $p->arrayref;

       Returns a reference to an array of all used modules. Surprise!

       files

       Returns the number of files parsed by the parser object.

RE-COMPILING THE GRAMMAR
       If - for some reasons - you need to alter the grammar, edit the file grammar and afterwards run:

	 perl -MParse::RecDescent - grammar Module::ExtractUse::Grammar

       Make sure you're in the right directory, i.e. in .../Module/ExtractUse/

EXPORTS

       Nothing.

SEE ALSO

       Parse::RecDescent, Module::ScanDeps, Module::Info, Module::CPANTS::Analyse

AUTHOR

       Thomas Klausner <domm@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2012 by Thomas Klausner.

       This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

perl v5.14.2							    2012-04-14						   Module::ExtractUse(3pm)