diff options
Diffstat (limited to 'upstream/debian-unstable/man3/Module::Load.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/Module::Load.3perl | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/Module::Load.3perl b/upstream/debian-unstable/man3/Module::Load.3perl new file mode 100644 index 00000000..80230e70 --- /dev/null +++ b/upstream/debian-unstable/man3/Module::Load.3perl @@ -0,0 +1,265 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. 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 "Module::Load 3perl" +.TH Module::Load 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" 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 +Module::Load \- runtime require of both modules and files +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Module::Load; +\& +\& my $module = \*(AqData::Dumper\*(Aq; +\& +\& load Data::Dumper; # loads that module, but not import any functions +\& # \-> cannot use \*(AqDumper\*(Aq function +\& +\& load \*(AqData::Dumper\*(Aq; # ditto +\& load $module # tritto +\& +\& autoload Data::Dumper; # loads that module and imports the default functions +\& # \-> can use \*(AqDumper\*(Aq function +\& +\& my $script = \*(Aqsome/script.pl\*(Aq +\& load $script; +\& load \*(Aqsome/script.pl\*(Aq; # use quotes because of punctuations +\& +\& load thing; # try \*(Aqthing\*(Aq first, then \*(Aqthing.pm\*(Aq +\& +\& load CGI, \*(Aq:all\*(Aq; # like \*(Aquse CGI qw[:standard]\*(Aq +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\f(CW\*(C`Module::Load\*(C'\fR eliminates the need to know whether you are trying +to require either a file or a module. +.PP +If you consult \f(CW\*(C`perldoc \-f require\*(C'\fR you will see that \f(CW\*(C`require\*(C'\fR will +behave differently when given a bareword or a string. +.PP +In the case of a string, \f(CW\*(C`require\*(C'\fR assumes you are wanting to load a +file. But in the case of a bareword, it assumes you mean a module. +.PP +This gives nasty overhead when you are trying to dynamically require +modules at runtime, since you will need to change the module notation +(\f(CW\*(C`Acme::Comment\*(C'\fR) to a file notation fitting the particular platform +you are on. +.PP +\&\f(CW\*(C`Module::Load\*(C'\fR eliminates the need for this overhead and will +just DWYM. +.ie n .SS "Difference between ""load"" and ""autoload""" +.el .SS "Difference between \f(CWload\fP and \f(CWautoload\fP" +.IX Subsection "Difference between load and autoload" +\&\f(CW\*(C`Module::Load\*(C'\fR imports the two functions \- \f(CW\*(C`load\*(C'\fR and \f(CW\*(C`autoload\*(C'\fR +.PP +\&\f(CW\*(C`autoload\*(C'\fR imports the default functions automatically, +but \f(CW\*(C`load\*(C'\fR do not import any functions. +.PP +\&\f(CW\*(C`autoload\*(C'\fR is usable under \f(CW\*(C`BEGIN{};\*(C'\fR. +.PP +Both the functions can import the functions that are specified. +.PP +Following codes are same. +.PP +.Vb 1 +\& load File::Spec::Functions, qw/splitpath/; +\& +\& autoload File::Spec::Functions, qw/splitpath/; +.Ve +.SH FUNCTIONS +.IX Header "FUNCTIONS" +.IP load 4 +.IX Item "load" +Loads a specified module. +.Sp +See "Rules" for detailed loading rule. +.IP autoload 4 +.IX Item "autoload" +Loads a specified module and imports the default functions. +.Sp +Except importing the functions, 'autoload' is same as 'load'. +.IP load_remote 4 +.IX Item "load_remote" +Loads a specified module to the specified package. +.Sp +.Vb 1 +\& use Module::Load \*(Aqload_remote\*(Aq; +\& +\& my $pkg = \*(AqOther::Package\*(Aq; +\& +\& load_remote $pkg, \*(AqData::Dumper\*(Aq; # load a module to \*(AqOther::Package\*(Aq +\& # but do not import \*(AqDumper\*(Aq function +.Ve +.Sp +A module for loading must be quoted. +.Sp +Except specifing the package and quoting module name, +\&'load_remote' is same as 'load'. +.IP autoload_remote 4 +.IX Item "autoload_remote" +Loads a specified module and imports the default functions to the specified package. +.Sp +.Vb 1 +\& use Module::Load \*(Aqautoload_remote\*(Aq; +\& +\& my $pkg = \*(AqOther::Package\*(Aq; +\& +\& autoload_remote $pkg, \*(AqData::Dumper\*(Aq; # load a module to \*(AqOther::Package\*(Aq +\& # and imports \*(AqDumper\*(Aq function +.Ve +.Sp +A module for loading must be quoted. +.Sp +Except specifing the package and quoting module name, +\&'autoload_remote' is same as 'load_remote'. +.SH Rules +.IX Header "Rules" +All functions have the following rules to decide what it thinks +you want: +.IP \(bu 4 +If the argument has any characters in it other than those matching +\&\f(CW\*(C`\ew\*(C'\fR, \f(CW\*(C`:\*(C'\fR or \f(CW\*(C`\*(Aq\*(C'\fR, it must be a file +.IP \(bu 4 +If the argument matches only \f(CW\*(C`[\ew:\*(Aq]\*(C'\fR, it must be a module +.IP \(bu 4 +If the argument matches only \f(CW\*(C`\ew\*(C'\fR, it could either be a module or a +file. We will try to find \f(CW\*(C`file.pm\*(C'\fR first in \f(CW@INC\fR and if that +fails, we will try to find \f(CW\*(C`file\*(C'\fR in \f(CW@INC\fR. If both fail, we die with +the respective error messages. +.SH "IMPORTS THE FUNCTIONS" +.IX Header "IMPORTS THE FUNCTIONS" +\&'load' and 'autoload' are imported by default, but 'load_remote' and +\&'autoload_remote' are not imported. +.PP +To use 'load_remote' or 'autoload_remote', specify at 'use'. +.IP """load"",""autoload"",""load_remote"",""autoload_remote""" 4 +.IX Item """load"",""autoload"",""load_remote"",""autoload_remote""" +Imports the selected functions. +.Sp +.Vb 2 +\& # imports \*(Aqload\*(Aq and \*(Aqautoload\*(Aq (default) +\& use Module::Load; +\& +\& # imports \*(Aqautoload\*(Aq only +\& use Module::Load \*(Aqautoload\*(Aq; +\& +\& # imports \*(Aqautoload\*(Aq and \*(Aqautoload_remote\*(Aq, but don\*(Aqt import \*(Aqload\*(Aq; +\& use Module::Load qw/autoload autoload_remote/; +.Ve +.IP 'all' 4 +.IX Item "'all'" +Imports all the functions. +.Sp +.Vb 1 +\& use Module::Load \*(Aqall\*(Aq; # imports load, autoload, load_remote, autoload_remote +.Ve +.IP '','none',undef 4 +.IX Item "'','none',undef" +Not import any functions (\f(CW\*(C`load\*(C'\fR and \f(CW\*(C`autoload\*(C'\fR are not imported). +.Sp +.Vb 1 +\& use Module::Load \*(Aq\*(Aq; +\& +\& use Module::Load \*(Aqnone\*(Aq; +\& +\& use Module::Load undef; +.Ve +.SH Caveats +.IX Header "Caveats" +Because of a bug in perl (#19213), at least in version 5.6.1, we have +to hardcode the path separator for a require on Win32 to be \f(CW\*(C`/\*(C'\fR, like +on Unix rather than the Win32 \f(CW\*(C`\e\*(C'\fR. Otherwise perl will not read its +own \f(CW%INC\fR accurately double load files if they are required again, or +in the worst case, core dump. +.PP +\&\f(CW\*(C`Module::Load\*(C'\fR cannot do implicit imports, only explicit imports. +(in other words, you always have to specify explicitly what you wish +to import from a module, even if the functions are in that modules' +\&\f(CW@EXPORT\fR) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Module::Runtime provides functions for loading modules, +checking the validity of a module name, +converting a module name to partial \f(CW\*(C`.pm\*(C'\fR path, +and related utility functions. +.PP +"require" in perlfunc <https://metacpan.org/pod/perlfunc#require> +and +"use" in perlfunc <https://metacpan.org/pod/perlfunc#use>. +.PP +Mojo::Loader is a "class loader and plugin framework", +and is included in the +Mojolicious <https://metacpan.org/release/Mojolicious> distribution. +.PP +Module::Loader is a module for finding and loading modules +in a given namespace, inspired by \f(CW\*(C`Mojo::Loader\*(C'\fR. +.SH ACKNOWLEDGEMENTS +.IX Header "ACKNOWLEDGEMENTS" +Thanks to Jonas B. Nielsen for making explicit imports work. +.SH "BUG REPORTS" +.IX Header "BUG REPORTS" +Please report bugs or other issues to <bug\-module\-load@rt.cpan.org>. +.SH AUTHOR +.IX Header "AUTHOR" +This module by Jos Boumans <kane@cpan.org>. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +This library is free software; you may redistribute and/or modify it +under the same terms as Perl itself. |