New tlperl part VIII

git-svn-id: svn://tug.org/texlive/trunk@21430 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 271 insertions, 0 deletions

diff --git a/Master/tlpkg/tlperl/lib/CPANPLUS.pm b/Master/tlpkg/tlperl/lib/CPANPLUS.pm
new file mode 100644
index 00000000000..b61771b242c
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/CPANPLUS.pm
@@ -0,0 +1,271 @@
+package CPANPLUS;
+
+use strict;
+use Carp;
+
+use CPANPLUS::Error;
+use CPANPLUS::Backend;
+
+use Locale::Maketext::Simple    Class => 'CPANPLUS', Style => 'gettext';
+
+BEGIN {
+    use Exporter    ();
+    use vars        qw( @EXPORT @ISA $VERSION );
+    @EXPORT     =   qw( shell fetch get install );
+    @ISA        =   qw( Exporter );
+    $VERSION = "0.90";     #have to hardcode or cpan.org gets unhappy
+}
+
+### purely for backward compatibility, so we can call it from the commandline:
+### perl -MCPANPLUS -e 'install Net::SMTP'
+sub install {
+    my $cpan = CPANPLUS::Backend->new;
+    my $mod = shift or (
+                    error(loc("No module specified!")), return
+                );
+
+    if ( ref $mod ) {
+        error( loc( "You passed an object. Use %1 for OO style interaction",
+                    'CPANPLUS::Backend' ));
+        return;
+
+    } else {
+        my $obj = $cpan->module_tree($mod) or (
+                        error(loc("No such module '%1'", $mod)),
+                        return
+                    );
+
+        my $ok = $obj->install;
+
+        $ok
+            ? msg(loc("Installing of %1 successful", $mod),1)
+            : msg(loc("Installing of %1 failed", $mod),1);
+
+        return $ok;
+    }
+}
+
+### simply downloads a module and stores it
+sub fetch {
+    my $cpan = CPANPLUS::Backend->new;
+
+    my $mod = shift or (
+                    error(loc("No module specified!")), return
+                );
+
+    if ( ref $mod ) {
+        error( loc( "You passed an object. Use %1 for OO style interaction",
+                    'CPANPLUS::Backend' ));
+        return;
+
+    } else {
+        my $obj = $cpan->module_tree($mod) or (
+                        error(loc("No such module '%1'", $mod)),
+                        return
+                    );
+
+        my $ok = $obj->fetch( fetchdir => '.' );
+
+        $ok
+            ? msg(loc("Fetching of %1 successful", $mod),1)
+            : msg(loc("Fetching of %1 failed", $mod),1);
+
+        return $ok;
+    }
+}
+
+### alias to fetch() due to compatibility with cpan.pm ###
+sub get { fetch(@_) }
+
+
+### purely for backwards compatibility, so we can call it from the commandline:
+### perl -MCPANPLUS -e 'shell'
+sub shell {
+    my $option  = shift;
+
+    ### since the user can specify the type of shell they wish to start
+    ### when they call the shell() function, we have to eval the usage
+    ### of CPANPLUS::Shell so we can set up all the checks properly
+    eval { require CPANPLUS::Shell; CPANPLUS::Shell->import($option) };
+    die $@ if $@;
+
+    my $cpan = CPANPLUS::Shell->new();
+
+    $cpan->shell();
+}
+
+1;
+
+__END__
+
+=pod
+
+=head1 NAME
+
+CPANPLUS - API & CLI access to the CPAN mirrors
+
+=head1 SYNOPSIS
+
+    ### standard invocation from the command line
+    $ cpanp
+    $ cpanp -i Some::Module
+
+    $ perl -MCPANPLUS -eshell
+    $ perl -MCPANPLUS -e'fetch Some::Module'
+
+    
+=head1 DESCRIPTION
+
+The C<CPANPLUS> library is an API to the C<CPAN> mirrors and a
+collection of interactive shells, commandline programs, etc,
+that use this API.
+
+=head1 GUIDE TO DOCUMENTATION
+
+=head2 GENERAL USAGE
+
+This is the document you are currently reading. It describes 
+basic usage and background information. Its main purpose is to 
+assist the user who wants to learn how to invoke CPANPLUS
+and install modules from the commandline and to point you
+to more indepth reading if required.
+
+=head2 API REFERENCE
+
+The C<CPANPLUS> API is meant to let you programmatically 
+interact with the C<CPAN> mirrors. The documentation in
+L<CPANPLUS::Backend> shows you how to create an object
+capable of interacting with those mirrors, letting you
+create & retrieve module objects.
+L<CPANPLUS::Module> shows you how you can use these module
+objects to perform actions like installing and testing. 
+
+The default shell, documented in L<CPANPLUS::Shell::Default>
+is also scriptable. You can use its API to dispatch calls
+from your script to the CPANPLUS Shell.
+
+=cut
+
+=head1 COMMANDLINE TOOLS
+
+=head2 STARTING AN INTERACTIVE SHELL
+
+You can start an interactive shell by running either of 
+the two following commands:
+
+    $ cpanp
+
+    $ perl -MCPANPLUS -eshell
+
+All commans available are listed in the interactive shells
+help menu. See C<cpanp -h> or L<CPANPLUS::Shell::Default> 
+for instructions on using the default shell.  
+    
+=head2 CHOOSE A SHELL
+
+By running C<cpanp> without arguments, you will start up
+the shell specified in your config, which defaults to 
+L<CPANPLUS::Shell::Default>. There are more shells available.
+C<CPANPLUS> itself ships with an emulation shell called 
+L<CPANPLUS::Shell::Classic> that looks and feels just like 
+the old C<CPAN.pm> shell.
+
+You can start this shell by typing:
+
+    $ perl -MCPANPLUS -e'shell Classic'
+    
+Even more shells may be available from C<CPAN>.    
+
+Note that if you have changed your default shell in your
+configuration, that shell will be used instead. If for 
+some reason there was an error with your specified shell, 
+you will be given the default shell.
+
+=head2 BUILDING PACKAGES
+
+C<cpan2dist> is a commandline tool to convert any distribution 
+from C<CPAN> into a package in the format of your choice, like
+for example C<.deb> or C<FreeBSD ports>. 
+
+See C<cpan2dist -h> for details.
+    
+    
+=head1 FUNCTIONS
+
+For quick access to common commands, you may use this module,
+C<CPANPLUS> rather than the full programmatic API situated in
+C<CPANPLUS::Backend>. This module offers the following functions:
+
+=head2 $bool = install( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
+
+This function requires the full name of the module, which is case
+sensitive.  The module name can also be provided as a fully
+qualified file name, beginning with a I</>, relative to
+the /authors/id directory on a CPAN mirror.
+
+It will download, extract and install the module.
+
+=head2 $where = fetch( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
+
+Like install, fetch needs the full name of a module or the fully
+qualified file name, and is case sensitive.
+
+It will download the specified module to the current directory.
+
+=head2 $where = get( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
+
+Get is provided as an alias for fetch for compatibility with
+CPAN.pm.
+
+=head2 shell()
+
+Shell starts the default CPAN shell.  You can also start the shell
+by using the C<cpanp> command, which will be installed in your
+perl bin.
+
+=head1 FAQ
+
+For frequently asked questions and answers, please consult the
+C<CPANPLUS::FAQ> manual.
+
+=head1 BUG REPORTS
+
+Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>.
+
+=head1 AUTHOR
+
+This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
+
+=head1 COPYRIGHT
+
+The CPAN++ interface (of which this module is a part of) is copyright (c) 
+2001 - 2007, Jos Boumans E<lt>kane@cpan.orgE<gt>. All rights reserved.
+
+This library is free software; you may redistribute and/or modify it 
+under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+L<CPANPLUS::Shell::Default>, L<CPANPLUS::FAQ>, L<CPANPLUS::Backend>, L<CPANPLUS::Module>, L<cpanp>, L<cpan2dist>
+
+=head1 CONTACT INFORMATION
+
+=over 4
+
+=item * Bug reporting:
+I<bug-cpanplus@rt.cpan.org>
+
+=item * Questions & suggestions:
+I<cpanplus-devel@lists.sourceforge.net>
+
+=back
+
+
+=cut
+
+# Local variables:
+# c-indentation-style: bsd
+# c-basic-offset: 4
+# indent-tabs-mode: nil
+# End:
+# vim: expandtab shiftwidth=4: