File Coverage

lib/CPANPLUS.pm
Criterion Covered Total %
statement 24 50 48.0
branch 0 18 0.0
condition n/a
subroutine 8 12 66.7
pod 4 4 100.0
total 36 84 42.9


line stmt bran cond sub pod time code
1             package CPANPLUS;
2              
3 15     15   276 use strict;
  15         305  
  15         2509  
4 15     15   244 use Carp;
  15         272  
  15         316  
5              
6 15     15   237 use CPANPLUS::Error;
  15         191  
  15         425  
7 15     15   485 use CPANPLUS::Backend;
  15         149  
  15         708  
8              
9 15     15   271 use Locale::Maketext::Simple Class => 'CPANPLUS', Style => 'gettext';
  15         139  
  15         311  
10              
11             BEGIN {
12 15     15   262     use Exporter ();
  15         265  
  15         149  
13 15     15   310     use vars qw( @EXPORT @ISA $VERSION );
  15         141  
  15         261  
14 15     15   367     @EXPORT = qw( shell fetch get install );
15 15         222     @ISA = qw( Exporter );
16 15         275     $VERSION = "0.076"; #have to hardcode or cpan.org gets unhappy
17             }
18              
19             ### purely for backward compatibility, so we can call it from the commandline:
20             ### perl -MCPANPLUS -e 'install Net::SMTP'
21             sub install {
22 0     0 1       my $cpan = CPANPLUS::Backend->new;
23 0 0             my $mod = shift or (
24                                 error(loc("No module specified!")), return
25                             );
26              
27 0 0             if ( ref $mod ) {
28 0                   error( loc( "You passed an object. Use %1 for OO style interaction",
29                                 'CPANPLUS::Backend' ));
30 0                   return;
31              
32                 } else {
33 0 0                 my $obj = $cpan->module_tree($mod) or (
34                                     error(loc("No such module '%1'", $mod)),
35                                     return
36                                 );
37              
38 0                   my $ok = $obj->install;
39              
40 0 0                 $ok
41                         ? msg(loc("Installing of %1 successful", $mod),1)
42                         : msg(loc("Installing of %1 failed", $mod),1);
43              
44 0                   return $ok;
45                 }
46             }
47              
48             ### simply downloads a module and stores it
49             sub fetch {
50 0     0 1       my $cpan = CPANPLUS::Backend->new;
51              
52 0 0             my $mod = shift or (
53                                 error(loc("No module specified!")), return
54                             );
55              
56 0 0             if ( ref $mod ) {
57 0                   error( loc( "You passed an object. Use %1 for OO style interaction",
58                                 'CPANPLUS::Backend' ));
59 0                   return;
60              
61                 } else {
62 0 0                 my $obj = $cpan->module_tree($mod) or (
63                                     error(loc("No such module '%1'", $mod)),
64                                     return
65                                 );
66              
67 0                   my $ok = $obj->fetch( fetchdir => '.' );
68              
69 0 0                 $ok
70                         ? msg(loc("Fetching of %1 successful", $mod),1)
71                         : msg(loc("Fetching of %1 failed", $mod),1);
72              
73 0                   return $ok;
74                 }
75             }
76              
77             ### alias to fetch() due to compatibility with cpan.pm ###
78 0     0 1   sub get { fetch(@_) }
79              
80              
81             ### purely for backwards compatibility, so we can call it from the commandline:
82             ### perl -MCPANPLUS -e 'shell'
83             sub shell {
84 0     0 1       my $option = shift;
85              
86             ### since the user can specify the type of shell they wish to start
87             ### when they call the shell() function, we have to eval the usage
88             ### of CPANPLUS::Shell so we can set up all the checks properly
89 0               eval { require CPANPLUS::Shell; CPANPLUS::Shell->import($option) };
  0            
  0            
90 0 0             die $@ if $@;
91              
92 0               my $cpan = CPANPLUS::Shell->new();
93              
94 0               $cpan->shell();
95             }
96              
97             1;
98              
99             __END__
100            
101             =pod
102            
103             =head1 NAME
104            
105             CPANPLUS - API & CLI access to the CPAN mirrors
106            
107             =head1 SYNOPSIS
108            
109             ### standard invocation from the command line
110             $ cpanp
111             $ cpanp -i Some::Module
112            
113             $ perl -MCPANPLUS -eshell
114             $ perl -MCPANPLUS -e'fetch Some::Module'
115            
116            
117             =head1 DESCRIPTION
118            
119             The C<CPANPLUS> library is an API to the C<CPAN> mirrors and a
120             collection of interactive shells, commandline programs, etc,
121             that use this API.
122            
123             =head1 GUIDE TO DOCUMENTATION
124            
125             =head2 GENERAL USAGE
126            
127             This is the document you are currently reading. It describes
128             basic usage and background information. Its main purpose is to
129             assist the user who wants to learn how to invoke CPANPLUS
130             and install modules from the commandline and to point you
131             to more indepth reading if required.
132            
133             =head2 API REFERENCE
134            
135             The C<CPANPLUS> API is meant to let you programmatically
136             interact with the C<CPAN> mirrors. The documentation in
137             L<CPANPLUS::Backend> shows you how to create an object
138             capable of interacting with those mirrors, letting you
139             create & retrieve module objects.
140             L<CPANPLUS::Module> shows you how you can use these module
141             objects to perform actions like installing and testing.
142            
143             The default shell, documented in L<CPANPLUS::Shell::Default>
144             is also scriptable. You can use its API to dispatch calls
145             from your script to the CPANPLUS Shell.
146            
147             =cut
148            
149             =head1 COMMANDLINE TOOLS
150            
151             =head2 STARTING AN INTERACTIVE SHELL
152            
153             You can start an interactive shell by running either of
154             the two following commands:
155            
156             $ cpanp
157            
158             $ perl -MCPANPLUS -eshell
159            
160             All commans available are listed in the interactive shells
161             help menu. See C<cpanp -h> or L<CPANPLUS::Shell::Default>
162             for instructions on using the default shell.
163            
164             =head2 CHOOSE A SHELL
165            
166             By running C<cpanp> without arguments, you will start up
167             the shell specified in your config, which defaults to
168             L<CPANPLUS::Shell::Default>. There are more shells available.
169             C<CPANPLUS> itself ships with an emulation shell called
170             L<CPANPLUS::Shell::Classic> that looks and feels just like
171             the old C<CPAN.pm> shell.
172            
173             You can start this shell by typing:
174            
175             $ perl -MCPANPLUS -e'shell Classic'
176            
177             Even more shells may be available from C<CPAN>.
178            
179             Note that if you have changed your default shell in your
180             configuration, that shell will be used instead. If for
181             some reason there was an error with your specified shell,
182             you will be given the default shell.
183            
184             =head2 BUILDING PACKAGES
185            
186             C<cpan2dist> is a commandline tool to convert any distribution
187             from C<CPAN> into a package in the format of your choice, like
188             for example C<.deb> or C<FreeBSD ports>.
189            
190             See C<cpan2dist -h> for details.
191            
192            
193             =head1 FUNCTIONS
194            
195             For quick access to common commands, you may use this module,
196             C<CPANPLUS> rather than the full programmatic API situated in
197             C<CPANPLUS::Backend>. This module offers the following functions:
198            
199             =head2 $bool = install( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
200            
201             This function requires the full name of the module, which is case
202             sensitive. The module name can also be provided as a fully
203             qualified file name, beginning with a I</>, relative to
204             the /authors/id directory on a CPAN mirror.
205            
206             It will download, extract and install the module.
207            
208             =head2 $where = fetch( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
209            
210             Like install, fetch needs the full name of a module or the fully
211             qualified file name, and is case sensitive.
212            
213             It will download the specified module to the current directory.
214            
215             =head2 $where = get( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
216            
217             Get is provided as an alias for fetch for compatibility with
218             CPAN.pm.
219            
220             =head2 shell()
221            
222             Shell starts the default CPAN shell. You can also start the shell
223             by using the C<cpanp> command, which will be installed in your
224             perl bin.
225            
226             =head1 FAQ
227            
228             For frequently asked questions and answers, please consult the
229             C<CPANPLUS::FAQ> manual.
230            
231             =head1 AUTHOR
232            
233             This module by
234             Jos Boumans E<lt>kane@cpan.orgE<gt>.
235            
236             =head1 COPYRIGHT
237            
238             The CPAN++ interface (of which this module is a part of) is
239             copyright (c) 2001-2006 Jos Boumans E<lt>kane@cpan.orgE<gt>.
240             All rights reserved.
241            
242             This library is free software;
243             you may redistribute and/or modify it under the same
244             terms as Perl itself.
245            
246             =head1 ACKNOWLEDGEMENTS
247            
248             Please see the F<AUTHORS> file in the CPANPLUS distribution
249             for a list of Credits and Contributors.
250            
251             =head1 SEE ALSO
252            
253             L<CPANPLUS::Shell::Default>, L<CPANPLUS::FAQ>, L<CPANPLUS::Backend>, L<CPANPLUS::Module>, L<cpanp>, L<cpan2dist>
254            
255             =head1 CONTACT INFORMATION
256            
257             =over 4
258            
259             =item * General questions & suggestions:
260             I<cpanplus-info@lists.sourceforge.net>
261            
262             =item * Bug reporting:
263             I<bug-cpanplus@rt.cpan.org>
264            
265             =item * Development list:
266             I<cpanplus-devel@lists.sourceforge.net>
267            
268             =back
269            
270            
271             =cut
272            
273             # Local variables:
274             # c-indentation-style: bsd
275             # c-basic-offset: 4
276             # indent-tabs-mode: nil
277             # End:
278             # vim: expandtab shiftwidth=4:
279