| 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.84"; #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 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 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<cpanplus-devel@lists.sourceforge.net> |
| 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: |