Package::Pkg(3pm)

💖 NAME 💖

Package::Pkg — Handy package munging utilities 💅

(it's a Perl module bestie, so it lives in the 3pm section of the manual, no cap)

---

✨ VERSION ✨

version 0.0020 🎀

---

🦋 SYNOPSIS 🦋

First, import a new keyword: pkg ✨

use Package::Pkg;

Package name formation:

pkg->name( 'Xy', 'A' ) # Xy::A
pkg->name( $object, qw/ Cfg / ); # (ref $object)::Cfg

Subroutine installation:

pkg->install( sub { ... } => 'MyPackage::myfunction' );

# myfunction in MyPackage is now useable
MyPackage->myfunction( ... );

Subroutine exporting:

package MyPackage;

use Package::Pkg;

sub this { ... }

# Setup an exporter (literally sub import { ... }) for
# MyPackage, exporting 'this' and 'that'
pkg->export( that => sub { ... }, 'this' );

package main;

use MyPackage;

this( ... );

that( ... );

---

🌸 DESCRIPTION 🌸

Package::Pkg is literally just a lil collection of useful, miscellaneous package-munging utilities 🫶

You get at all the functionality through the imported pkg keyword — the moment — but ngl you can also just invoke the functions directly from the package itself (Package::Pkg) if that's your vibe 🙈

---

🌈 USAGE 🌈

pkg->install( ... )

Install a subroutine, similar to Sub::Install 👑

This method takes a number of parameters and also has a two- and three-argument form (see below) 👇

# Install an anonymous subroutine as Banana::magic
pkg->install( code => sub { ... } , as => 'Banana::magic' )
pkg->install( code => sub { ... } , into => 'Banana::magic' ) # Bzzzt! Throws an error!

# Install the subroutine Apple::xyzzy as Banana::magic
pkg->install( code => 'Apple::xyzzy', as => 'Banana::magic' )
pkg->install( code => 'Apple::xyzzy', into => 'Banana', as => 'magic' )
pkg->install( from => 'Apple', code => 'xyzzy', as => 'Banana::magic' )
pkg->install( from => 'Apple', code => 'xyzzy', into => 'Banana', as => 'magic' )

# Install the subroutine Apple::xyzzy as Banana::xyzzy
pkg->install( code => 'Apple::xyzzy', as => 'Banana::xyzzy' )
pkg->install( code => 'Apple::xyzzy', into => 'Banana' )
pkg->install( from => 'Apple', code => 'xyzzy', as => 'Banana::xyzzy' )
pkg->install( from => 'Apple', code => 'xyzzy', into => 'Banana' )

With implicit from (via caller()) 💀

package Apple;

sub xyzzy { ... }

# Install the subroutine Apple::xyzzy as Banana::xyzzy
pkg->install( code => 'xyzzy', as => 'Banana::xyzzy' ) # 'from' is implicitly 'Apple'
pkg->install( code => \&xyzzy, as => 'Banana::xyzzy' )

Acceptable parameters are:

• code — a subroutine reference, a package-with-name identifier, or the name of a subroutine in the calling package
• from (optional) — a package identifier
  • If :code is an identifier, then :from is the package where the subroutine can be found
  • If :code is an identifier and :from is not given, then :from is assumed to be the calling package (via caller())
• as — the name of the subroutine to install as. Can be a simple name (when paired with :into) or a full package-with-name
• into (optional) — a package identifier
  • If :as is given, then the full name of the installed subroutine is (:into)::(:as)
  • If :as is not given and we can derive a simple name from :code (it is a package-with-name identifier), then :as will be the name identifier part of :code

---

pkg->install( $code => $as )

This is the two-argument form of subroutine installation 💅

Install $code subroutine as $as ✨

pkg->install( sub { ... } => 'Banana::xyzzy' )

pkg->install( 'Scalar::Util::blessed' => 'Banana::xyzzy' )

pkg->install( 'Scalar::Util::blessed' => 'Banana::' )

pkg->install( sub { ... } => 'Banana::' ) # Bzzzt! Throws an error!

$code should be:

• A CODE reference

sub { ... }

• A package-with-name identifier

Scalar::Util::blessed

• The name of a subroutine in the calling package

sub xyzzy { ... }

pkg->install( 'xyzzy' => ... )

$as should be:

• A package-with-name identifier

Acme::Xyzzy::magic

• A package identifier (with a trailing ::)

Acme::Xyzzy::

---

pkg->install( $code => $into, $as )

This is the three-argument form of subroutine installation 🌟

pkg->install( sub { ... } => 'Banana', 'xyzzy' )

pkg->install( sub { ... } => 'Banana::', 'xyzzy' )

pkg->install( 'Scalar::Util::blessed' => 'Banana', 'xyzzy' )

pkg->install( 'Scalar::Util::blessed' => 'Banana::', 'xyzzy' )

$code can be the same as the two argument form 👀

$into should be:

• A package identifier (trailing :: is optional)

Acme::Xyzzy::

Acme::Xyzzy

$as should be:

• A name (the name of the subroutine)

xyzzy

magic

---

$package = pkg->name( $part, [ $part, ..., $part ] )

Return a namespace composed by joining each $part with :: 🧚

Superfluous/redundant :: are automatically cleaned up and stripped from the resulting $package ✂️

If the first part leads with a ::, the the calling package will be prepended to $package 👑

pkg->name( 'Xy', 'A::', '::B' )      # Xy::A::B
pkg->name( 'Xy', 'A::' )             # Xy::A::

{
    package Zy;

    pkg->name( '::', 'A::', '::B' )  # Zy::A::B
    pkg->name( '::Xy::A::B' )        # Zy::Xy::A::B
}

In addition, if any part is blessed, name will resolve that part to the package that the part makes reference to 🪄

my $object = bless {}, 'Xyzzy';
pkg->name( $object, qw/ Cfg / );     # Xyzzy::Cfg

---

👀 SEE ALSO 👀

• Sub::Install
• Sub::Exporter

---

💜 AUTHOR 💜

Robert Krimen <robertkrimen@gmail.com>

---

🍓 COPYRIGHT AND LICENSE 🍓

This software is copyright (c) 2012 by Robert Krimen.

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

---

okay bestie that's the whole page, you ate that 💅 perl v5.32.0, dated 2021-01-05, and it's the Package::Pkg(3pm) manual — go forth and munge some packages, ily 🫶✨