Commit | Line | Data |
6aaee015 |
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 ); |
feb517da |
16 | $VERSION = "0.90"; #have to hardcode or cpan.org gets unhappy |
6aaee015 |
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: |