CPAN::Inject(3pm)

1CPAN::Inject(3)       User Contributed Perl Documentation      CPAN::Inject(3)
2
3
4

NAME

6       CPAN::Inject - Base class for injecting distributions into CPAN sources
7

SYNOPSIS

9         # Create the injector
10         my $cpan = CPAN::Inject->new(
11             sources => '/root/.cpan/sources',  # Required field
12             author  => 'LOCAL',                # The default
13             );
14
15         # Add a file to the user
16         $cpan->add( file => 'some/random/Perl-Tarball-1.02.tar.gz' );
17
18         # What would have have to use when installing
19         # $path = 'LOCAL/Perl-Tarball-1.02.tar.gz';
20         my $path = $cpan->install_path( 'some/random/Perl-Tarball-1.02.tar.gz' );
21

DESCRIPTION

23       Following the release of CPAN::Mini, the CPAN::Mini::Inject module was
24       created to add additional distributions into a minicpan mirror.
25
26       While it was created for use with a minicpan mirror, similar
27       functionality can be reused in other situations.
28
29       CPAN::Inject replicates the basics of this functionality.
30
31       Specifically, it takes an arbitrary tarball and adds it to the CPAN
32       sources directory for a particular author, and then add the new file to
33       the CHECKSUMS file.
34
35       It does not reimplement the logic to add files to the indexes.
36
37       The initial use this module was created for was to inject tarballs into
38       the CPAN sources directory for the reserved LOCAL user, so that the can
39       be installed via the CPAN shell, with automated recursion to CPAN
40       dependencies.
41
42       But although the number of functions is limited (current only "add"
43       exists, with the others to be added as needed) the implementation is
44       very generic and sub-classable, so that it can be reused in other
45       situations.
46

METHODS

48   new
49         # Create the injector for the default LOCAL author
50         $cpan = CPAN::Inject->new(
51             sources => '/root/.cpan/sources',
52             );
53
54         # Create the injector for a specific author
55         $cpan = CPAN::Inject->new(
56             sources => '/root/.cpan/sources',
57             author  => 'ADAMK',
58             );
59
60       The "new" constructor takes a set of named params and create a cpan
61       injection object.
62
63       * sources - The compulsory "sources" param should be the path to a
64       directory that is the root of a mirror (or a partial mirror such as a
65       CPAN::Cache or a CPAN::Mini).
66
67       To retain the permissions and ownership integrity of the sources tree,
68       you must be the owner of the "sources" directory in order to inject the
69       distribution tarballs.
70
71       * author - The optional "author" param should be the CPAN id of an
72       author. By default, the reserved local CPAN id "LOCAL" will be used.
73
74       The author provided will be used as a default in all further actions.
75
76       Returns a "CPAN::Inject" object, or throws an exception on error.
77
78   from_cpan_config
79       The "from_cpan_config" constructor loads the CPAN.pm configuration
80       file, and uses the data contained within to specific the sources path
81       for the object.
82
83       This constructor is otherwise the same.
84
85       Returns a CPAN::Inject object on success, or throws an exception on
86       error.
87
88   sources
89       The "sources" accessor returns the path to the root of the directory
90       tree.
91
92   author
93       The "author" accessor returns the CPAN id for the default author which
94       will be "LOCAL" if you did not provide an alternative param to the the
95       "new" constructor.
96
97   add
98         # Add a file to the constructor/default author
99         $cpan->add( file => 'any/arbitrary/Perl-Tarball-1.01.tar.gz' );
100
101       The "add" method takes a Perl distribution tarball from an arbitrary
102       path, and adds it to the sources path.
103
104       The specific location the tarball is copied to will be in the root
105       directory for the author provided to the constructor.
106
107       Returns the install_path value as a convenience, or throws an exception
108       on error.
109
110   remove
111         # Remove a distribution from the repository
112         $cpan->remove( dist => 'LOCAL/Perl-Tarball-1.01.tar.gz' );
113
114       The "remove" method takes a distribution path and removes it from the
115       sources path. The file is also removed.
116
117       Does not return anything useful and throws an exception on error.
118
119   author_subpath
120         # $path = 'authors/id/L/LO/LOCAL'
121         $path = $cpan->author_subpath;
122
123       The "author_subpath" method takes a CPAN author id (or uses the CPAN
124       author id originally provided to the constructor) and returns the
125       relative subpath for the AUTHOR within the sources tree.
126
127       Returns the subpath as a string.
128
129   author_path
130         # $path = '/root/.cpan/sources/authors/id/L/LO/LOCAL'
131         $path = $cpan->author_subpath;
132
133       The "author_path" method finds the full path for the root directory for
134       the named author.
135
136       Returns the path as a string.
137
138   file_path
139         # $path = '/root/.cpan/sources/authors/id/L/LO/LOCAL/Perl-Tarball-1.02.tar.gz'
140         $path = $cpan->file_path( 'Perl-Tarball-1.02.tar.gz' );
141         $path = $cpan->file_path( '/some/random/place/Perl-Tarball-1.02.tar.gz' );
142
143       The "file_path" method takes the name of a tarball (either just the
144       name or a full path) and calculates the location that the file will end
145       up at.
146
147       When files are copied into the sources directory, they are always
148       copied to the top level of the author root.
149
150       Returns the path as a string.
151
152   install_path
153         # $path = 'LOCAL/Perl-Tarball-1.01.tar.gz';
154         $path = $cpan->install_path( 'Perl-Tarball-1.01.tar.gz' );
155         $path = $cpan->install_path( '/some/random/place/Perl-Tarball-1.02.tar.gz' );
156
157       The "install_path" method returns the path for the distribution as the
158       CPAN shell understands it.
159
160       Using this path, the CPAN shell can expand it to locate the
161       distribution, and then can install it.
162
163       Returns the path as a string.
164

SUPPORT

166       This module is stored in an Open Repository at the following address.
167
168       <http://svn.ali.as/cpan/trunk/CPAN-Inject>
169
170       Write access to the repository is made available automatically to any
171       published CPAN author, and to most other volunteers on request.
172
173       If you are able to submit your bug report in the form of new (failing)
174       unit tests, or can apply your fix directly instead of submitting a
175       patch, you are strongly encouraged to do so as the author currently
176       maintains over 100 modules and it can take some time to deal with non-
177       Critcal bug reports or patches.
178
179       This will guarentee that your issue will be addressed in the next
180       release of the module.
181
182       If you cannot provide a direct test or fix, or don't have time to do
183       so, then regular bug reports are still accepted and appreciated via the
184       CPAN bug tracker.
185
186       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPAN-Inject>
187
188       For other issues, for commercial enhancement or support, or to have
189       your write access enabled for the repository, contact the author at the
190       email address above.
191

AUTHOR

193       Adam Kennedy <adamk@cpan.org>
194

COPYRIGHT

199       Copyright 2006 - 2011 Adam Kennedy.
200
201       This program is free software; you can redistribute it and/or modify it
202       under the same terms as Perl itself.
203
204       The full text of the license can be found in the LICENSE file included
205       with this module.
206
207
208
209perl v5.38.0                      2023-07-20                   CPAN::Inject(3)