.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 "Sub::Install 3pm" .TH Sub::Install 3pm "2023-01-05" "perl v5.36.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" Sub::Install \- install subroutines into packages easily .SH "VERSION" .IX Header "VERSION" version 0.929 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Sub::Install; \& \& Sub::Install::install_sub({ \& code => sub { ... }, \& into => $package, \& as => $subname \& }); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module makes it easy to install subroutines into packages without the unsightly mess of \f(CW\*(C`no strict\*(C'\fR or typeglobs lying about where just anyone can see them. .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even an extremely long time ago. It should work on any version of perl released in the last ten years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "install_sub" .IX Subsection "install_sub" .Vb 5 \& Sub::Install::install_sub({ \& code => \e&subroutine, \& into => "Finance::Shady", \& as => \*(Aqlaunder\*(Aq, \& }); .Ve .PP This routine installs a given code reference into a package as a normal subroutine. The above is equivalent to: .PP .Vb 2 \& no strict \*(Aqrefs\*(Aq; \& *{"Finance::Shady" . \*(Aq::\*(Aq . "launder"} = \e&subroutine; .Ve .PP If \f(CW\*(C`into\*(C'\fR is not given, the sub is installed into the calling package. .PP If \f(CW\*(C`code\*(C'\fR is not a code reference, it is looked for as an existing sub in the package named in the \f(CW\*(C`from\*(C'\fR parameter. If \f(CW\*(C`from\*(C'\fR is not given, it will look in the calling package. .PP If \f(CW\*(C`as\*(C'\fR is not given, and if \f(CW\*(C`code\*(C'\fR is a name, \f(CW\*(C`as\*(C'\fR will default to \f(CW\*(C`code\*(C'\fR. If \f(CW\*(C`as\*(C'\fR is not given, but if \f(CW\*(C`code\*(C'\fR is a code ref, Sub::Install will try to find the name of the given code ref and use that as \f(CW\*(C`as\*(C'\fR. .PP That means that this code: .PP .Vb 6 \& Sub::Install::install_sub({ \& code => \*(Aqtwitch\*(Aq, \& from => \*(AqPerson::InPain\*(Aq, \& into => \*(AqPerson::Teenager\*(Aq, \& as => \*(Aqdance\*(Aq, \& }); .Ve .PP is the same as: .PP .Vb 1 \& package Person::Teenager; \& \& Sub::Install::install_sub({ \& code => Person::InPain\->can(\*(Aqtwitch\*(Aq), \& as => \*(Aqdance\*(Aq, \& }); .Ve .SS "reinstall_sub" .IX Subsection "reinstall_sub" This routine behaves exactly like \f(CW"install_sub"\fR, but does not emit a warning if warnings are on and the destination is already defined. .SS "install_installers" .IX Subsection "install_installers" This routine is provided to allow Sub::Install compatibility with Sub::Installer. It installs \f(CW\*(C`install_sub\*(C'\fR and \f(CW\*(C`reinstall_sub\*(C'\fR methods into the package named by its argument. .PP .Vb 2 \& Sub::Install::install_installers(\*(AqCode::Builder\*(Aq); # just for us, please \& Code::Builder\->install_sub({ name => $code_ref }); \& \& Sub::Install::install_installers(\*(AqUNIVERSAL\*(Aq); # feeling lucky, punk? \& Anything::At::All\->install_sub({ name => $code_ref }); .Ve .PP The installed installers are similar, but not identical, to those provided by Sub::Installer. They accept a single hash as an argument. The key/value pairs are used as the \f(CW\*(C`as\*(C'\fR and \f(CW\*(C`code\*(C'\fR parameters to the \f(CW\*(C`install_sub\*(C'\fR routine detailed above. The package name on which the method is called is used as the \&\f(CW\*(C`into\*(C'\fR parameter. .PP Unlike Sub::Installer's \f(CW\*(C`install_sub\*(C'\fR will not eval strings into code, but will look for named code in the calling package. .SH "EXPORTS" .IX Header "EXPORTS" Sub::Install exports \f(CW\*(C`install_sub\*(C'\fR and \f(CW\*(C`reinstall_sub\*(C'\fR only if they are requested. .SS "exporter" .IX Subsection "exporter" Sub::Install has a never-exported subroutine called \f(CW\*(C`exporter\*(C'\fR, which is used to implement its \f(CW\*(C`import\*(C'\fR routine. It takes a hashref of named arguments, only one of which is currently recognize: \f(CW\*(C`exports\*(C'\fR. This must be an arrayref of subroutines to offer for export. .PP This routine is mainly for Sub::Install's own consumption. Instead, consider Sub::Exporter. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "Sub::Installer" 4 .IX Item "Sub::Installer" This module is (obviously) a reaction to Damian Conway's Sub::Installer, which does the same thing, but does it by getting its greasy fingers all over \&\s-1UNIVERSAL.\s0 I was really happy about the idea of making the installation of coderefs less ugly, but I couldn't bring myself to replace the ugliness of typeglobs and loosened strictures with the ugliness of \s-1UNIVERSAL\s0 methods. .IP "Sub::Exporter" 4 .IX Item "Sub::Exporter" This is a complete Exporter.pm replacement, built atop Sub::Install. .SH "EXTRA CREDITS" .IX Header "EXTRA CREDITS" Several of the tests are adapted from tests that shipped with Damian Conway's Sub-Installer distribution. .SH "AUTHOR" .IX Header "AUTHOR" Ricardo \s-1SIGNES\s0 .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Chad Granum .IP "\(bu" 4 David Steinbrunner .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 .IP "\(bu" 4 Ricardo Signes .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2005 by Ricardo \s-1SIGNES.\s0 .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.