---
name: "Package::Pkg"
section: "3pm"
platform: "linux"
package: "libpackage-pkg-perl"
version: "0.0020-1.1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Package::Pkg"
---

# Package::Pkg(3pm)

Handy package munging utilities

## NAME

Package::Pkg - Handy package munging utilities

## 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 a collection of useful, miscellaneous package-munging utilities. Functionality is accessed via the imported `"pkg"` keyword, although you can also invoke functions directly from the package (`"Package::Pkg"`)

## 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.