Update CPANPLUS to CPAN version 0.9133
[perl.git] / cpan / CPANPLUS / lib / CPANPLUS.pm
1 package CPANPLUS;
2
3 use strict;
4 use Carp;
5
6 use CPANPLUS::Error;
7 use CPANPLUS::Backend;
8
9 use Locale::Maketext::Simple    Class => 'CPANPLUS', Style => 'gettext';
10
11 BEGIN {
12     use Exporter    ();
13     use vars        qw( @EXPORT @ISA $VERSION );
14     @EXPORT     =   qw( shell fetch get install );
15     @ISA        =   qw( Exporter );
16     $VERSION = "0.9133";     #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     my $cpan = CPANPLUS::Backend->new;
23     my $mod = shift or (
24                     error(loc("No module specified!")), return
25                 );
26
27     if ( ref $mod ) {
28         error( loc( "You passed an object. Use %1 for OO style interaction",
29                     'CPANPLUS::Backend' ));
30         return;
31
32     } else {
33         my $obj = $cpan->module_tree($mod) or (
34                         error(loc("No such module '%1'", $mod)),
35                         return
36                     );
37
38         my $ok = $obj->install;
39
40         $ok
41             ? msg(loc("Installing of %1 successful", $mod),1)
42             : msg(loc("Installing of %1 failed", $mod),1);
43
44         return $ok;
45     }
46 }
47
48 ### simply downloads a module and stores it
49 sub fetch {
50     my $cpan = CPANPLUS::Backend->new;
51
52     my $mod = shift or (
53                     error(loc("No module specified!")), return
54                 );
55
56     if ( ref $mod ) {
57         error( loc( "You passed an object. Use %1 for OO style interaction",
58                     'CPANPLUS::Backend' ));
59         return;
60
61     } else {
62         my $obj = $cpan->module_tree($mod) or (
63                         error(loc("No such module '%1'", $mod)),
64                         return
65                     );
66
67         my $ok = $obj->fetch( fetchdir => '.' );
68
69         $ok
70             ? msg(loc("Fetching of %1 successful", $mod),1)
71             : msg(loc("Fetching of %1 failed", $mod),1);
72
73         return $ok;
74     }
75 }
76
77 ### alias to fetch() due to compatibility with cpan.pm ###
78 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     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     eval { require CPANPLUS::Shell; CPANPLUS::Shell->import($option) };
90     die $@ if $@;
91
92     my $cpan = CPANPLUS::Shell->new();
93
94     $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 commands 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 BUG REPORTS
232
233 Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>.
234
235 =head1 AUTHOR
236
237 This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
238
239 =head1 COPYRIGHT
240
241 The CPAN++ interface (of which this module is a part of) is copyright (c)
242 2001 - 2007, Jos Boumans E<lt>kane@cpan.orgE<gt>. All rights reserved.
243
244 This library is free software; you may redistribute and/or modify it
245 under the same terms as Perl itself.
246
247 =head1 SEE ALSO
248
249 L<CPANPLUS::Shell::Default>, L<CPANPLUS::FAQ>, L<CPANPLUS::Backend>, L<CPANPLUS::Module>, L<cpanp>, L<cpan2dist>
250
251 =head1 CONTACT INFORMATION
252
253 =over 4
254
255 =item * Bug reporting:
256 I<bug-cpanplus@rt.cpan.org>
257
258 =item * Questions & suggestions:
259 I<bug-cpanplus@rt.cpan.org>
260
261 =back
262
263
264 =cut
265
266 # Local variables:
267 # c-indentation-style: bsd
268 # c-basic-offset: 4
269 # indent-tabs-mode: nil
270 # End:
271 # vim: expandtab shiftwidth=4: