[Summary view] [Print] [Text view]

   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: