Where's documentation for import ???

[Amanda aman_DO_da345]

I am having a *very* hard time understanding the function "use",
at least judging by the many times that it bites me in the rear.
The biggest enigma of all is "import".

Yes, I have read perlfunc on "use" and "import", and I have read
perlmod, and I have read the manpage for Exporter. None of these
documents comes even close to explaining what import is supposed
to do; they don't even explain what import's input and output
signatures are.

Where can I find this information?

Thanks!

Amanda
--

 

[Ben Morrow]

Quoth Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org:

I am having a *very* hard time understanding the function "use",
at least judging by the many times that it bites me in the rear.
The biggest enigma of all is "import".

Yes, I have read perlfunc on "use" and "import", and I have read
perlmod, and I have read the manpage for Exporter. None of these
documents comes even close to explaining what import is supposed
to do; they don't even explain what import's input and output
signatures are.

Where can I find this information?

I'm not sure... could you explain (I'm not being sarky: it is genuinely
useful to know when documentation is unclear) what it is you do not
understand about

use Module LIST;

is in every way equivalent to

BEGIN {
require Module;
Module->import(LIST);
}

(leaving aside for a moment the fact you don't understand import)? Think
of it like a sort-of macro if that makes it easier: it is simply there
to save typing.

Do you understand all three things there: a BEGIN block, require with a
bareword, and a method call? If you don't then read "Package
Constructors and Destructors" in perlmod for BEGIN; perldoc -f require
for require and perlboot for the method call.

Now, import. This is not a Perl builtin at all. It is simply a
convention: whenever a module is used, Perl gives it a chance to set
itself up by calling its 'import' method, if it defines one. It is
perhaps slightly confusing that import is in perlfunc at all: it is just
a sub in the package Module (or some package it inherits from).

You don't really need to know this unless you are writing your own
modules: to use someone else's module you just say

use Module qw/foo bar/;

and that's that. The fact that Perl is calling Module->import(qw/foo
bar/) behind-the-scenes doesn't need to worry you: that's for the module
author (or, if they're sensible and use Exporter or an equivalent, the
author of *that* module) to worry about.

Ben

 

[Amanda]

Quoth Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org:

I'm not sure... could you explain

I thought I was perfectly clear. I want to understand *exactly*
what import is supposed to do. The cute (and/or disingenuous)
answer to this question is "import can do whatever you want it to
do"--i.e. a perfectly worthless API in a nutshell. A less cute,
but almost as worthless, answer would be, "import is supposed to
do what the canonical example of import, namely Exporter's, does".
Unfortunately the Exporter man page does not say a word about what
its import does.

I really don't understand why the Perl documentation has chosen to
be so coy on import; it treats Perl programmers like children who
shouldn't be trusted with such sensitive information (which makes
the ubiquitous little sermons on programmer responsibility all
throughout the documentation all the more annoying). The fact that
import is not a built-in is a technicality. It is every bit as
important as many built-ins (e.g. "use"), and it deserves to be
better documented.

And no, source code is no substitute for documentation (otherwise
many trees should have been saved by never printing the Camel book
and its ilk).

Amanda

 

[Ben Morrow]

I thought I was perfectly clear. I want to understand *exactly*
what import is supposed to do. The cute (and/or disingenuous)
answer to this question is "import can do whatever you want it to
do"--i.e. a perfectly worthless API in a nutshell.

Hmmm. It's correct though: a module's import method can do whatever it
wants. It's inputs are clear: import is passed whatever is given to use.
The only thing that is perhaps unclear is that its output is completely
ignored: only its side-effects matter.

Do you understand the concept of a 'hook', or a 'callback'? This is what
import is: an opportunity for a module to do (whatever it likes) at
'use' time.

A less cute, but almost as worthless, answer would be, "import is
supposed to do what the canonical example of import, namely
Exporter's, does". Unfortunately the Exporter man page does not say a
word about what its import does.

It exports subs into the caller's namespace: that is, if Foo inherits
Exporter's import then after executing

package main;
Foo->import(qw/bar baz/);

the subs Foo::bar and Foo::baz are also available as main::bar and
main::baz.

.. This is by far the most common thing for a module's import to do; it
can do all sorts of other things, though. For instance, strict::import
sets certain perl-internal variables that put the Perl parser into
strict mode.

If you like, import is supposed to do whatever the documentation for the
module states it should do.

Can you give an example of something you are trying to achieve, so we
can show you how to create an import sub that does it?

Ben

 

[ctcgag]

In <[email protected]> Ben Morrow



I thought I was perfectly clear.

You were wrong.

I want to understand *exactly*
what import is supposed to do. The cute (and/or disingenuous)
answer to this question is "import can do whatever you want it to
do"--i.e. a perfectly worthless API in a nutshell.

It seems a bit weird to call import an API. import does exactly what you
tell it to do. Exporter's import does what Exporter's documentation
says it does.

A less cute,
but almost as worthless, answer would be, "import is supposed to
do what the canonical example of import, namely Exporter's, does".
Unfortunately the Exporter man page does not say a word about what
its import does.

The Exporter module implements an "import" method which allows a
module to export functions and variables to its users' namespaces.
Many mod- ules use Exporter rather than implementing their own
"import" method because Exporter provides a highly flexible
interface, with an imple- mentation optimised for the common case.

That seems pretty clear to me.

I really don't understand why the Perl documentation has chosen to
be so coy on import; it treats Perl programmers like children who
shouldn't be trusted with such sensitive information (which makes
the ubiquitous little sermons on programmer responsibility all
throughout the documentation all the more annoying). The fact that
import is not a built-in is a technicality. It is every bit as
important as many built-ins (e.g. "use"), and it deserves to be
better documented.

It is documented perfectly well.

And no, source code is no substitute for documentation (otherwise
many trees should have been saved by never printing the Camel book
and its ilk).

Also, documentation is no substitute for code. If you want to know
exactly what it does, read the source. If you want to know what it is
documented to do, read the documentation. If you don't understand
the documentation, point out what you don't understand; don't lie to
use about what is or isn't in the documentation.

Xho