.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CPAN::Inject 3pm"
.TH CPAN::Inject 3pm "2021-01-07" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CPAN::Inject \- Base class for injecting distributions into CPAN sources
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  # Create the injector
\&  my $cpan = CPAN::Inject\->new(
\&      sources => \*(Aq/root/.cpan/sources\*(Aq,  # Required field
\&      author  => \*(AqLOCAL\*(Aq,                # The default
\&      );
\&  
\&  # Add a file to the user
\&  $cpan\->add( file => \*(Aqsome/random/Perl\-Tarball\-1.02.tar.gz\*(Aq );
\&  
\&  # What would have have to use when installing
\&  # $path = \*(AqLOCAL/Perl\-Tarball\-1.02.tar.gz\*(Aq;
\&  my $path = $cpan\->install_path( \*(Aqsome/random/Perl\-Tarball\-1.02.tar.gz\*(Aq );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Following the release of CPAN::Mini, the CPAN::Mini::Inject module
was created to add additional distributions into a minicpan mirror.
.PP
While it was created for use with a minicpan mirror, similar
functionality can be reused in other situations.
.PP
\&\fBCPAN::Inject\fR replicates the basics of this functionality.
.PP
Specifically, it takes an arbitrary tarball and adds it to the \s-1CPAN\s0
sources directory for a particular author, and then add the new file
to the \fI\s-1CHECKSUMS\s0\fR file.
.PP
It does not reimplement the logic to add files to the indexes.
.PP
The initial use this module was created for was to inject tarballs into
the \s-1CPAN\s0 sources directory for the reserved \s-1LOCAL\s0 user, so that the can be
installed via the \s-1CPAN\s0 shell, with automated recursion to \s-1CPAN\s0 dependencies.
.PP
But although the number of functions is limited (current only \f(CW\*(C`add\*(C'\fR exists,
with the others to be added as needed) the implementation is very generic
and sub-classable, so that it can be reused in other situations.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 4
\&  # Create the injector for the default LOCAL author
\&  $cpan = CPAN::Inject\->new(
\&      sources => \*(Aq/root/.cpan/sources\*(Aq,
\&      );
\&  
\&  # Create the injector for a specific author
\&  $cpan = CPAN::Inject\->new(
\&      sources => \*(Aq/root/.cpan/sources\*(Aq,
\&      author  => \*(AqADAMK\*(Aq,
\&      );
.Ve
.PP
The \f(CW\*(C`new\*(C'\fR constructor takes a set of named params and create a cpan
injection object.
.PP
* \fBsources\fR \- The compulsory \f(CW\*(C`sources\*(C'\fR param should be the path to a
directory that is the root of a mirror (or a partial mirror such as a
CPAN::Cache or a CPAN::Mini).
.PP
To retain the permissions and ownership integrity of the sources tree,
you must be the owner of the \f(CW\*(C`sources\*(C'\fR directory in order to inject the
distribution tarballs.
.PP
* \fBauthor\fR \- The optional \f(CW\*(C`author\*(C'\fR param should be the \s-1CPAN\s0 id of an
author. By default, the reserved local \s-1CPAN\s0 id \*(L"\s-1LOCAL\*(R"\s0 will be used.
.PP
The author provided will be used as a default in all further actions.
.PP
Returns a \f(CW\*(C`CPAN::Inject\*(C'\fR object, or throws an exception on error.
.SS "from_cpan_config"
.IX Subsection "from_cpan_config"
The \f(CW\*(C`from_cpan_config\*(C'\fR constructor loads the \s-1CPAN\s0.pm configuration file, and
uses the data contained within to specific the sources path for the
object.
.PP
This constructor is otherwise the same.
.PP
Returns a \fBCPAN::Inject\fR object on success, or throws an exception on
error.
.SS "sources"
.IX Subsection "sources"
The \f(CW\*(C`sources\*(C'\fR accessor returns the path to the root of the directory tree.
.SS "author"
.IX Subsection "author"
The \f(CW\*(C`author\*(C'\fR accessor returns the \s-1CPAN\s0 id for the default author which
will be \*(L"\s-1LOCAL\*(R"\s0 if you did not provide an alternative param to the the
\&\f(CW\*(C`new\*(C'\fR constructor.
.SS "add"
.IX Subsection "add"
.Vb 2
\&  # Add a file to the constructor/default author
\&  $cpan\->add( file => \*(Aqany/arbitrary/Perl\-Tarball\-1.01.tar.gz\*(Aq );
.Ve
.PP
The \f(CW\*(C`add\*(C'\fR method takes a Perl distribution tarball from an arbitrary
path, and adds it to the sources path.
.PP
The specific location the tarball is copied to will be in the root
directory for the author provided to the constructor.
.PP
Returns the install_path value as a convenience, or throws an exception
on error.
.SS "remove"
.IX Subsection "remove"
.Vb 2
\&  # Remove a distribution from the repository
\&  $cpan\->remove( dist => \*(AqLOCAL/Perl\-Tarball\-1.01.tar.gz\*(Aq );
.Ve
.PP
The \f(CW\*(C`remove\*(C'\fR method takes a distribution path and removes it from the
sources path. The file is also removed.
.PP
Does not return anything useful and throws an exception on error.
.SS "author_subpath"
.IX Subsection "author_subpath"
.Vb 2
\&  # $path = \*(Aqauthors/id/L/LO/LOCAL\*(Aq
\&  $path = $cpan\->author_subpath;
.Ve
.PP
The \f(CW\*(C`author_subpath\*(C'\fR method takes a \s-1CPAN\s0 author id (or uses the \s-1CPAN\s0
author id originally provided to the constructor) and returns the
relative subpath for the \s-1AUTHOR\s0 within the sources tree.
.PP
Returns the subpath as a string.
.SS "author_path"
.IX Subsection "author_path"
.Vb 2
\&  # $path = \*(Aq/root/.cpan/sources/authors/id/L/LO/LOCAL\*(Aq
\&  $path = $cpan\->author_subpath;
.Ve
.PP
The \f(CW\*(C`author_path\*(C'\fR method finds the full path for the root directory for
the named author.
.PP
Returns the path as a string.
.SS "file_path"
.IX Subsection "file_path"
.Vb 3
\&  # $path = \*(Aq/root/.cpan/sources/authors/id/L/LO/LOCAL/Perl\-Tarball\-1.02.tar.gz\*(Aq
\&  $path = $cpan\->file_path( \*(AqPerl\-Tarball\-1.02.tar.gz\*(Aq );
\&  $path = $cpan\->file_path( \*(Aq/some/random/place/Perl\-Tarball\-1.02.tar.gz\*(Aq );
.Ve
.PP
The \f(CW\*(C`file_path\*(C'\fR method takes the name of a tarball (either just the name
or a full path) and calculates the location that the file will end up at.
.PP
When files are copied into the sources directory, they are always copied
to the top level of the author root.
.PP
Returns the path as a string.
.SS "install_path"
.IX Subsection "install_path"
.Vb 3
\&  # $path = \*(AqLOCAL/Perl\-Tarball\-1.01.tar.gz\*(Aq;
\&  $path = $cpan\->install_path( \*(AqPerl\-Tarball\-1.01.tar.gz\*(Aq );
\&  $path = $cpan\->install_path( \*(Aq/some/random/place/Perl\-Tarball\-1.02.tar.gz\*(Aq );
.Ve
.PP
The \f(CW\*(C`install_path\*(C'\fR method returns the path for the distribution as the
\&\s-1CPAN\s0 shell understands it.
.PP
Using this path, the \s-1CPAN\s0 shell can expand it to locate the
distribution, and then can install it.
.PP
Returns the path as a string.
.SH "SUPPORT"
.IX Header "SUPPORT"
This module is stored in an Open Repository at the following address.
.PP
<http://svn.ali.as/cpan/trunk/CPAN\-Inject>
.PP
Write access to the repository is made available automatically to any
published \s-1CPAN\s0 author, and to most other volunteers on request.
.PP
If you are able to submit your bug report in the form of new (failing)
unit tests, or can apply your fix directly instead of submitting a patch,
you are \fBstrongly\fR encouraged to do so as the author currently maintains
over 100 modules and it can take some time to deal with non-Critcal bug
reports or patches.
.PP
This will guarentee that your issue will be addressed in the next
release of the module.
.PP
If you cannot provide a direct test or fix, or don't have time to do so,
then regular bug reports are still accepted and appreciated via the \s-1CPAN\s0
bug tracker.
.PP
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPAN\-Inject>
.PP
For other issues, for commercial enhancement or support, or to have your
write access enabled for the repository, contact the author at the email
address above.
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CPAN::Mini::Inject
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2006 \- 2011 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.