.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Module::ExtractUse 3pm"
.TH Module::ExtractUse 3pm "2018-11-17" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Module::ExtractUse \- Find out what modules are used
.SH "VERSION"
.IX Header "VERSION"
version 0.343
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Module::ExtractUse;
\&  
\&  # get a parser
\&  my $p=Module::ExtractUse\->new;
\&  
\&  # parse from a file
\&  $p\->extract_use(\*(Aq/path/to/module.pm\*(Aq);
\&  
\&  # or parse from a ref to a string in memory
\&  $p\->extract_use(\e$string_containg_code);
\&  
\&  # use some reporting methods
\&  my $used=$p\->used;           # $used is a HASHREF
\&  print $p\->used(\*(Aqstrict\*(Aq)     # true if code includes \*(Aquse strict\*(Aq
\&  
\&  my @used=$p\->array;
\&  my $used=$p\->string;
\&  
\&  # you can get optional modules, that is use in eval context, in the same style
\&  my $used=$p\->used_in_eval;           # $used is a HASHREF
\&  print $p\->used_in_eval(\*(Aqstrict\*(Aq)     # true if code includes \*(Aquse strict\*(Aq
\&  
\&  my @used=$p\->array_in_eval;
\&  my $used=$p\->string_in_eval;
\&  
\&  # and mandatory modules, that is use out of eval context, in the same style, also.
\&  my $used=$p\->used_out_of_eval;           # $used is a HASHREF
\&  print $p\->used_out_of_eval(\*(Aqstrict\*(Aq)     # true if code includes \*(Aquse strict\*(Aq
\&  
\&  my @used=$p\->array_out_of_eval;
\&  my $used=$p\->string_out_of_eval;
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1CPAN\s0) used by the parsed code.
.PP
\&\*(L"Usage\*(R" is defined by either calling \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR.
.SS "Methods"
.IX Subsection "Methods"
\fInew\fR
.IX Subsection "new"
.PP
.Vb 1
\& my $p=Module::ExtractUse\->new;
.Ve
.PP
Returns a parser object
.PP
\fIextract_use\fR
.IX Subsection "extract_use"
.PP
.Vb 2
\&  $p\->extract_use(\*(Aq/path/to/module.pm\*(Aq);
\&  $p\->extract_use(\e$string_containg_code);
.Ve
.PP
Runs the parser.
.PP
\&\f(CW$code_to_parse\fR can be either a \s-1SCALAR,\s0 in which case
Module::ExtractUse tries to open the file specified in
\&\f(CW$code_to_parse\fR. Or a reference to a \s-1SCALAR,\s0 in which case
Module::ExtractUse assumes the referenced scalar contains the source
code.
.PP
The code will be stripped from \s-1POD\s0 (using Pod::Strip) and split on \*(L";\*(R"
(semicolon). Each statement (i.e. the stuff between two semicolons) is
checked by a simple regular expression.
.PP
If the statement contains either 'use' or 'require', the statement is
handed over to the parser, who then tries to figure out, \fBwhat\fR is
used or required. The results will be saved in a data structure that
you can examine afterwards.
.PP
You can call \f(CW\*(C`extract_use\*(C'\fR several times on different files. It will
count how many files where examined and how often each module was used.
.SS "Accessor Methods"
.IX Subsection "Accessor Methods"
Those are various ways to get at the result of the parse.
.PP
Note that \f(CW\*(C`extract_use\*(C'\fR returns the parser object, so you can say
.PP
.Vb 1
\&  print $p\->extract_use($code_to_parse)\->string;
.Ve
.PP
\fIused\fR
.IX Subsection "used"
.PP
.Vb 2
\&    my $used=$p\->used;           # $used is a HASHREF
\&    print $p\->used(\*(Aqstrict\*(Aq)     # true if code includes \*(Aquse strict\*(Aq
.Ve
.PP
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.
.PP
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.
.PP
This is the preferred accessor.
.PP
\fIused_in_eval\fR
.IX Subsection "used_in_eval"
.PP
Same as \f(CW\*(C`used\*(C'\fR, except for considering in-eval-context only.
.PP
\fIused_out_of_eval\fR
.IX Subsection "used_out_of_eval"
.PP
Same as \f(CW\*(C`used\*(C'\fR, except for considering NOT-in-eval-context only.
.PP
\fIrequired\fR
.IX Subsection "required"
.PP
Same as \f(CW\*(C`used\*(C'\fR, except for considering 'require'd modules only.
.PP
\fIrequired_in_eval\fR
.IX Subsection "required_in_eval"
.PP
Same as \f(CW\*(C`required\*(C'\fR, except for considering in-eval-context only.
.PP
\fIrequired_out_of_eval\fR
.IX Subsection "required_out_of_eval"
.PP
Same as \f(CW\*(C`required\*(C'\fR, except for considering NOT-in-eval-context only.
.PP
\fInoed\fR
.IX Subsection "noed"
.PP
Same as \f(CW\*(C`used\*(C'\fR, except for considering 'no'ed modules only.
.PP
\fInoed_in_eval\fR
.IX Subsection "noed_in_eval"
.PP
Same as \f(CW\*(C`noed\*(C'\fR, except for considering in-eval-context only.
.PP
\fInoed_out_of_eval\fR
.IX Subsection "noed_out_of_eval"
.PP
Same as \f(CW\*(C`noed\*(C'\fR, except for considering NOT-in-eval-context only.
.PP
\fIstring\fR
.IX Subsection "string"
.PP
.Vb 1
\&    print $p\->string($seperator)
.Ve
.PP
Returns a sorted string of all used modules, joined using the value of
\&\f(CW$seperator\fR or using a blank space as a default;
.PP
Module names are sorted by ascii value (i.e by \f(CW\*(C`sort\*(C'\fR)
.PP
\fIstring_in_eval\fR
.IX Subsection "string_in_eval"
.PP
Same as \f(CW\*(C`string\*(C'\fR, except for considering in-eval-context only.
.PP
\fIstring_out_of_eval\fR
.IX Subsection "string_out_of_eval"
.PP
Same as \f(CW\*(C`string\*(C'\fR, except for considering NOT-in-eval-context only.
.PP
\fIarray\fR
.IX Subsection "array"
.PP
.Vb 1
\&    my @array = $p\->array;
.Ve
.PP
Returns an array of all used modules.
.PP
\fIarray_in_eval\fR
.IX Subsection "array_in_eval"
.PP
Same as \f(CW\*(C`array\*(C'\fR, except for considering in-eval-context only.
.PP
\fIarray_out_of_eval\fR
.IX Subsection "array_out_of_eval"
.PP
Same as \f(CW\*(C`array\*(C'\fR, except for considering NOT-in-eval-context only.
.PP
\fIarrayref\fR
.IX Subsection "arrayref"
.PP
.Vb 1
\&    my $arrayref = $p\->arrayref;
.Ve
.PP
Returns a reference to an array of all used modules. Surprise!
.PP
\fIarrayref_in_eval\fR
.IX Subsection "arrayref_in_eval"
.PP
Same as \f(CW\*(C`array_ref\*(C'\fR, except for considering in-eval-context only.
.PP
\fIarrayref_out_of_eval\fR
.IX Subsection "arrayref_out_of_eval"
.PP
Same as \f(CW\*(C`array_ref\*(C'\fR, except for considering NOT-in-eval-context only.
.PP
\fIfiles\fR
.IX Subsection "files"
.PP
Returns the number of files parsed by the parser object.
.SH "RE-COMPILING THE GRAMMAR"
.IX Header "RE-COMPILING THE GRAMMAR"
If \- for some reasons \- you need to alter the grammar, edit the file
\&\fIgrammar\fR and afterwards run:
.PP
.Vb 1
\&  perl \-MParse::RecDescent \- grammar Module::ExtractUse::Grammar
.Ve
.PP
Make sure you're in the right directory, i.e. in \fI.../Module/ExtractUse/\fR
.SH "EXPORTS"
.IX Header "EXPORTS"
Nothing.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Parse::RecDescent, Module::Extract::Use, Module::ScanDeps, Module::Info, Module::CPANTS::Analyse, Perl::PrereqScanner, Perl::PrereqScanner::Lite, Perl::PrereqScanner::NotQuiteLite
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Anthony Brummett <https://github.com/brummett> implemented support for Module::Runtime and Class::Load while participating in the \s-1CPAN\s0 Pull Request Challenge <http://cpan-prc.org/>
.IP "\(bu" 4
Jeremy Mates <https://github.com/thrig> fixed some documentation errors
.IP "\(bu" 4
Jonathan Yu provided a nice script, \f(CW\*(C`example/extractuse.pl\*(C'\fR
.PP
If I forgot to mention your contribution, please send an email or open an issue / ticket.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Thomas Klausner <domm@cpan.org>
.IP "\(bu" 4
Kenichi Ishigaki <kishigaki@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Thomas Klausner.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.