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