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.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: