CPAN::Inject(3pm)

💖 CPAN::Inject 💖

okay bestie, so this is CPAN::Inject — it lives in the perl 5.32.0 User Contributed Perl Documentation zone and it's literally the base class for injecting distributions into CPAN sources. yes. we're doing surgery on a CPAN mirror. slay.

---

✨ NAME ✨

CPAN::Inject — the base class for injecting distributions into CPAN sources. periodt.

---

🌸 SYNOPSIS 🌸

here's the vibe, copy it exactly, don't be weird about it:

  # Create the injector
  my $cpan = CPAN::Inject->new(
      sources => '/root/.cpan/sources',  # Required field
      author  => 'LOCAL',                # The default
      );

  # Add a file to the user
  $cpan->add( file => 'some/random/Perl-Tarball-1.02.tar.gz' );

  # What would have have to use when installing
  # $path = 'LOCAL/Perl-Tarball-1.02.tar.gz';
  my $path = $cpan->install_path( 'some/random/Perl-Tarball-1.02.tar.gz' );

---

🦋 DESCRIPTION 🦋

so like, storytime. after CPAN::Mini dropped, CPAN::Mini::Inject showed up to shove extra distributions into a minicpan mirror. iconic behaviour honestly.

and even though it was built for minicpan mirrors specifically, the same kind of functionality is reusable in other situations. so CPAN::Inject replicates the basics of that functionality.

specifically 👇 it takes an arbitrary tarball, adds it to the CPAN sources directory for a particular author, and then adds the new file to the CHECKSUMS file.

💀 it does not reimplement the logic to add files to the indexes. that part is not its problem.

the initial use this module was created for was to inject tarballs into the CPAN sources directory for the reserved LOCAL user, so that they can be installed via the CPAN shell, with automated recursion to CPAN dependencies. the way that works is lowkey genius.

but even though the number of functions is limited (currently only add exists, with the others to be added as needed), the implementation is very generic and sub-classable, so it can be reused in other situations. main character energy, honestly.

---

👑 METHODS 👑

🌈 new

  # Create the injector for the default LOCAL author
  $cpan = CPAN::Inject->new(
      sources => '/root/.cpan/sources',
      );

  # Create the injector for a specific author
  $cpan = CPAN::Inject->new(
      sources => '/root/.cpan/sources',
      author  => 'ADAMK',
      );

the new constructor takes a set of named params and creates a cpan injection object. that's it, that's the whole job.

• sources — the compulsory sources 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).

⚠️ to retain the permissions and ownership integrity of the sources tree, you must be the owner of the sources directory in order to inject the distribution tarballs. no owner, no inject. that's the rule bestie.

• author — the optional author param should be the CPAN id of an author. by default, the reserved local CPAN id LOCAL will be used. this author gets used as a default in all further actions.

returns a CPAN::Inject object, or throws an exception on error. 🫶

💜 from_cpan_config

the from_cpan_config constructor loads the CPAN.pm configuration file, and uses the data contained within to specify the sources path for the object. (yes, it's doing the config-reading for you, very generous.)

this constructor is otherwise the same.

returns a CPAN::Inject object on success, or throws an exception on error.

🎀 sources

the sources accessor returns the path to the root of the directory tree. simple. clean. gorgeous.

⭐ author

the author accessor returns the CPAN id for the default author, which will be LOCAL if you did not provide an alternative param to the new constructor.

🔥 add

  # Add a file to the constructor/default author
  $cpan->add( file => 'any/arbitrary/Perl-Tarball-1.01.tar.gz' );

the add method takes a Perl distribution tarball from an arbitrary path, and adds it to the sources path.

the specific location the tarball is copied to will be in the root directory for the author provided to the constructor. so like, always top-level of the author, okay?

returns the install_path value as a convenience, or throws an exception on error.

🌸 remove

  # Remove a distribution from the repository
  $cpan->remove( dist => 'LOCAL/Perl-Tarball-1.01.tar.gz' );

the remove method takes a distribution path and removes it from the sources path. the file is also removed. gone. bye. 💅

does not return anything useful and throws an exception on error.

🧚 author_subpath

  # $path = 'authors/id/L/LO/LOCAL'
  $path = $cpan->author_subpath;

the author_subpath method takes a CPAN author id (or uses the CPAN author id originally provided to the constructor) and returns the relative subpath for the AUTHOR within the sources tree.

returns the subpath as a string.

🦋 author_path

  # $path = '/root/.cpan/sources/authors/id/L/LO/LOCAL'
  $path = $cpan->author_subpath;

the author_path method finds the full path for the root directory for the named author.

returns the path as a string.

🍓 file_path

  # $path = '/root/.cpan/sources/authors/id/L/LO/LOCAL/Perl-Tarball-1.02.tar.gz'
  $path = $cpan->file_path( 'Perl-Tarball-1.02.tar.gz' );
  $path = $cpan->file_path( '/some/random/place/Perl-Tarball-1.02.tar.gz' );

the file_path 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.

when files are copied into the sources directory, they are always copied to the top level of the author root. no nesting, no drama.

returns the path as a string.

💅 install_path

  # $path = 'LOCAL/Perl-Tarball-1.01.tar.gz';
  $path = $cpan->install_path( 'Perl-Tarball-1.01.tar.gz' );
  $path = $cpan->install_path( '/some/random/place/Perl-Tarball-1.02.tar.gz' );

the install_path method returns the path for the distribution as the CPAN shell understands it.

using this path, the CPAN shell can expand it to locate the distribution, and then can install it. that's the whole point bestie, that's the payoff.

returns the path as a string.

---

🫶 SUPPORT 🫶

this module is stored in an Open Repository at the following address.

http://svn.ali.as/cpan/trunk/CPAN-Inject

write access to the repository is made available automatically to any published CPAN author, and to most other volunteers on request. so like, just ask.

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 strongly encouraged to do so, because the author currently maintains over 100 modules and it can take some time to deal with non-Critcal bug reports or patches.

this will guarentee that your issue will be addressed in the next release of the module. ✨

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 CPAN bug tracker.

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPAN-Inject

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.

---

🌈 AUTHOR 🌈

Adam Kennedy <adamk@cpan.org>

---

💖 SEE ALSO 💖

CPAN::Mini::Inject

---

⭐ COPYRIGHT ⭐

Copyright 2006 - 2011 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

---

and that's the whole page bestie 💜 this one's CPAN::Inject(3pm) from the perl v5.32.0 era, dated 2021-01-07 — go forth and inject responsibly, ily 🎀✨