/ 
Package-Subroutine-v0.22.1
River stage one • 1 direct dependent • 1 total dependent
/ Package::Subroutine

NAME

Package::Subroutine - minimalistic import/export and other util methods

SYNOPSIS

Exporting functions from a module is very simple.

; package Recipe::Condiment; use Package::Subroutine
; sub import
   { export Package::Subroutine _ => qw/required optional var/ }

You can import too.

; import Package::Subroutine 'Various::Types' => qw/string email/

And you can build a relay for your subroutines.

; package SubRelay

; sub import
    { export Package::Subroutine FooModule => qw/foo fun/
    ; export Package::Subroutine BarPackage => qw/bar geld/
    ; do_export()
    }

To export not directly from import the method export_to_caller exists.

; sub do_export
    { export_to_caller Package::Subroutine(2)->('_' => 'mystuff')
    }

And you can get and compare version numbers with this module.

; say "SOTA" if version Package::Subroutine 'Xpose::Nature' => 0.99

; say "SOTA" if version Package::Subroutine 'Protect::Whales' >= 62.0

Sure, installation of a coderef is possible too.

; install Package::Subroutine 'Cold::Inf' => nose => sub { 'hatchie' }

Test if a subroutine is defined.

; (isdefined Package::Subroutine('Cold::Inf' => 'tissue')||sub{})->()

As a helper exists a method which lists all subroutines in a package.

; print "$_\n" for Package::Subroutine->findsubs('Cold::Inf')

DESCRIPTION

import,mixin and export

This module provides two class methods to transfer subs from one namespace into another. mixin is an alias for import with the addition to import all subroutines from a namespace.

The way this module works is very simple, so it is possible that it does not work for you under all circumstances. Please send a bug report if things go wrong. You are also free to use the long time available and stable alternatives. Anyway I hope this package finds its ecological niche.

A possible use case for this module is an situation where a package decides during load time from where the used functions come from. In such a case Exporter is not a good solution because it is bound to use and @ISA what makes things a little bit harder to change.

The inport or export needs at least two arguments. The first is a package name. Second argument is a list of function names.

It is safest, if the package was loaded before you transfer the subs around.

There is a shortcut for the current namespace included because you shouldn't write

export Package::Subroutine __PACKAGE__ => qw/foo bar/

Things go wrong, because you really export from __PACKAGE__:: namespace and this is seldom what you want. Please use the form from synopsis with one underscore, when the current package is the source for the subroutines.

You can change the name of the sub in the target namespace. To do so, you give a array reference with the sourcename and the targetname instead of the plain string name.

package Here;

export Package::Subroutine There => [loosy => 'groovy'];
# now is There::groovy equal Here::loosy

import Package::Subroutine There => [wild => 'wilder'];
# and There::wild -> Here::wilder

The purpose of mixin is that your code can distinguish between functions and methods. The convention I suggest is to use mixin for methods and import for the rest. Calling mixin without the list of method names imports all subs from the given namespace.

export_to_caller

This method takes the level for the caller function call and returns a code reference which wraps the exporter function curried with the specified target namespace.

export_to

The right tool to export subroutines into an arbitrary namespace. The argument here is a package name, the target for the export. It works like export_to_caller and returns a code reference. These should be called with the source namespace and the subroutine names.

exporter

The methods above are using one function. This function is usable with full qualified name or is simply imported.

It takes three arguments, first is the target namespace, second is the source namespace and the third is a list of method names to move around.

version

print Package::Subroutine->version('Package::Subroutine');

This is a evaled wrapper around UNIVERSAL::VERSION so it will not die. You have seen in synopsis how a check against a version number is performed.

install

This mehod installs a code reference as a subroutine. First argument is the namespace, second the name for the subroutine and third is the coderef.

isdefined

This method returns like UNIVERSAL::can a code reference or undef for a function. As argument is the full quallified function name allowed or a pair of package name and function name.

findsubs

This method returns a list or an array with all defined functions for a given package.

findmethods

Simliar to findsubs but reads all classes in @ISA plus UNIVERSAL. Class::ISA is used for the task to list all subclasses.

Note

I know this package does not much, what is not possible with core functionality or other CPAN modules. But for me it seems to make some things easier to type and hopefully the code a little bit more readable.

Other helper packages

Package::Subroutine::Namespace
Package::Subroutine::Sugar

SEE ALSO

Sub::Install
Exporter
Class::Inspector

The methods method has much more features than findmethods.

CONTRIBUTIONS

Thank you, ysth from perlmonks for your suggestions. Without you this would have never arrived in CPAN. :) (He was also not sure if this should happen anyway.)

LICENSE

Perl has a free license, so this module shares it with this programming language.

Copyleft 2006-2012 by Sebastian Knapp <rock@ccls-online.de>