9 use Locale::Maketext::Simple Class => 'CPANPLUS', Style => 'gettext';
13 use vars qw( @EXPORT @ISA $VERSION );
14 @EXPORT = qw( shell fetch get install );
15 @ISA = qw( Exporter );
16 $VERSION = "0.87_02"; #have to hardcode or cpan.org gets unhappy
19 ### purely for backward compatibility, so we can call it from the commandline:
20 ### perl -MCPANPLUS -e 'install Net::SMTP'
22 my $cpan = CPANPLUS::Backend->new;
24 error(loc("No module specified!")), return
28 error( loc( "You passed an object. Use %1 for OO style interaction",
29 'CPANPLUS::Backend' ));
33 my $obj = $cpan->module_tree($mod) or (
34 error(loc("No such module '%1'", $mod)),
38 my $ok = $obj->install;
41 ? msg(loc("Installing of %1 successful", $mod),1)
42 : msg(loc("Installing of %1 failed", $mod),1);
48 ### simply downloads a module and stores it
50 my $cpan = CPANPLUS::Backend->new;
53 error(loc("No module specified!")), return
57 error( loc( "You passed an object. Use %1 for OO style interaction",
58 'CPANPLUS::Backend' ));
62 my $obj = $cpan->module_tree($mod) or (
63 error(loc("No such module '%1'", $mod)),
67 my $ok = $obj->fetch( fetchdir => '.' );
70 ? msg(loc("Fetching of %1 successful", $mod),1)
71 : msg(loc("Fetching of %1 failed", $mod),1);
77 ### alias to fetch() due to compatibility with cpan.pm ###
81 ### purely for backwards compatibility, so we can call it from the commandline:
82 ### perl -MCPANPLUS -e 'shell'
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) };
92 my $cpan = CPANPLUS::Shell->new();
105 CPANPLUS - API & CLI access to the CPAN mirrors
109 ### standard invocation from the command line
111 $ cpanp -i Some::Module
113 $ perl -MCPANPLUS -eshell
114 $ perl -MCPANPLUS -e'fetch Some::Module'
119 The C<CPANPLUS> library is an API to the C<CPAN> mirrors and a
120 collection of interactive shells, commandline programs, etc,
123 =head1 GUIDE TO DOCUMENTATION
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.
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.
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.
149 =head1 COMMANDLINE TOOLS
151 =head2 STARTING AN INTERACTIVE SHELL
153 You can start an interactive shell by running either of
154 the two following commands:
158 $ perl -MCPANPLUS -eshell
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.
164 =head2 CHOOSE A SHELL
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.
173 You can start this shell by typing:
175 $ perl -MCPANPLUS -e'shell Classic'
177 Even more shells may be available from C<CPAN>.
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.
184 =head2 BUILDING PACKAGES
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>.
190 See C<cpan2dist -h> for details.
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:
199 =head2 $bool = install( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
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.
206 It will download, extract and install the module.
208 =head2 $where = fetch( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
210 Like install, fetch needs the full name of a module or the fully
211 qualified file name, and is case sensitive.
213 It will download the specified module to the current directory.
215 =head2 $where = get( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
217 Get is provided as an alias for fetch for compatibility with
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
228 For frequently asked questions and answers, please consult the
229 C<CPANPLUS::FAQ> manual.
233 Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>.
237 This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
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.
244 This library is free software; you may redistribute and/or modify it
245 under the same terms as Perl itself.
249 L<CPANPLUS::Shell::Default>, L<CPANPLUS::FAQ>, L<CPANPLUS::Backend>, L<CPANPLUS::Module>, L<cpanp>, L<cpan2dist>
251 =head1 CONTACT INFORMATION
255 =item * Bug reporting:
256 I<bug-cpanplus@rt.cpan.org>
258 =item * Questions & suggestions:
259 I<cpanplus-devel@lists.sourceforge.net>
267 # c-indentation-style: bsd
269 # indent-tabs-mode: nil
271 # vim: expandtab shiftwidth=4: