Where's documentation for import ???

Discussion in 'Perl Misc' started by Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org, May 4, 2004.

  1. 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
    --
     
    Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org, May 4, 2004
    #1
    1. Advertising

  2. Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org

    Ben Morrow Guest

    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
     
    Ben Morrow, May 5, 2004
    #2
    1. Advertising

  3. Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org

    Amanda Guest

    In <c797pt$9si$> Ben Morrow <> writes:

    >Quoth Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org:


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


    >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
    --
    To s&e^n]d me m~a}i]l r%e*m?o\v[e bit from my a|d)d:r{e:s]s.
     
    Amanda, May 5, 2004
    #3
  4. Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org

    Ben Morrow Guest

    Quoth Amanda <aman_DO_da345@al_THE_ter_OBVIOUS_n.org>:
    > In <c797pt$9si$> Ben Morrow <> writes:
    >
    > >Quoth Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org:

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

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


    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

    --
    "The Earth is degenerating these days. Bribery and corruption abound.
    Children no longer mind their parents, every man wants to write a book,
    and it is evident that the end of the world is fast approaching."
    -Assyrian stone tablet, c.2800 BC
     
    Ben Morrow, May 5, 2004
    #4
  5. Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org

    Guest

    Amanda <aman_DO_da345@al_THE_ter_OBVIOUS_n.org> wrote:
    > In <c797pt$9si$> Ben Morrow
    > <> writes:
    >
    > >Quoth Amanda aman_DO_da345@al_THE_ter_OBVIOUS_n.org:

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

    >
    > >I'm not sure... could you explain

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

    --
    -------------------- http://NewsReader.Com/ --------------------
    Usenet Newsgroup Service $9.95/Month 30GB
     
    , May 5, 2004
    #5
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Paul Opal
    Replies:
    12
    Views:
    975
    Paul Opal
    Oct 11, 2004
  2. Bill Janssen

    documentation of import from zip files?

    Bill Janssen, Oct 17, 2003, in forum: Python
    Replies:
    2
    Views:
    288
  3. Cameron Laird
    Replies:
    1
    Views:
    676
    Josiah Carlson
    Apr 3, 2004
  4. Kenneth McDonald
    Replies:
    2
    Views:
    771
  5. Replies:
    1
    Views:
    1,230
    Andy Dingley
    Sep 16, 2006
Loading...

Share This Page