Perl modules, Exporter, and @EXPORT vs. @EXPORT

ibm1620 has asked for the wisdom of the Perl Monks concerning the following question:

@EXPORT contains symbols to always export, and @EXPORT_OK contains symbols to export upon request, according to official doc. (https://perldoc.perl.org/Exporter)

It appears, however, that if a program use's a module and requests symbols from @EXPORT_OK, the symbols in @EXPORT are no longer implicitly imported -- they must be explicitly listed in the use statement.

package Foo;
use v5.36;
use Exporter 'import';
our @EXPORT = qw/always_imported/;
our @EXPORT_OK = qw/optionally_imported/;

sub always_imported {
    say "Always imported.";
}
sub optionally_imported {
    say "Optionally imported.";
}
1;
[download]

Program 1 doesn't request anything in its use statement. Its call to "always_imported" compiles and executes correctly.

#!/usr/bin/env perl
use v5.36;

use Foo;
always_imported; # works
[download]

Program 2 requests an optional symbol in @EXPORT_OK. Its call to "always_imported" no longer compiles, because the symbol wasn't imported.

#!/usr/bin/env perl
use v5.36;

use Foo qw/optionally_imported/;
always_imported; # bareword error ("always_imported" sub not defined)
[download]

I've noted the strong warnings against modules automatically exporting symbols, but I didn't run across anything that described the behavior I'm seeing. Is this working as designed?

Comment on Perl modules, Exporter, and @EXPORT vs. @EXPORT_OK Select or Download Code

Replies are listed 'Best First'.
Re: Perl modules, Exporter, and @EXPORT vs. @EXPORT_OK by choroba (Cardinal) on Jul 23, 2022 at 23:44 UTC
See "How to Import" in Exporter: `use YourModule qw(...);` This imports only the symbols listed by the caller into their namespace. All listed symbols must be in your `@EXPORT` or `@EXPORT_OK`, else an error occurs. The advanced export features of Exporter are accessed like this, but with list entries that are syntactically distinct from symbol names. `map{substr$_->[0],$_->[1]\|\|0,1}[\\|\|{},3],[[]],[ref qr-1,-,-1],[{}],[sub{}^ARGV,3]`	[reply] [d/l] [select]
Re^2: Perl modules, Exporter, and @EXPORT vs. @EXPORT_OK by LanX (Saint) on Jul 23, 2022 at 23:59 UTC
I think it's even clearer seen with the two points before, emphasize added `use YourModule;` This imports all the symbols from YourModule's @EXPORT into the namespace of the use statement. `use YourModule ();` This causes perl to load your module but does not import any symbols. `use YourModule qw(...);` This imports only the symbols listed by the caller into their namespace. All listed symbols must be in your @EXPORT or @EXPORT_OK, else an error occurs. it would be inconsistent with case two with an empty list, if auto-imports were allowed in the third case. edit but I agree with the ibm1620 that `always_imported` is misleading. something like `default_imported` would be better. Probably worth a doc patch. Cheers Rolf _{(addicted to the Perl Programming Language :) Wikisyntax for the Monastery}	[reply] [d/l] [select]
Re^3: Perl modules, Exporter, and @EXPORT vs. @EXPORT_OK by ibm1620 (Hermit) on Jul 24, 2022 at 03:07 UTC
I agree, a phrase like "default import" or "default list of symbols" would help to clarify it, as would stating that the default list is used when -- or only if -- no explicit list is supplied on the 'use' statement. That would help make the point that the word "default" refers to a list, rather than to the entities in the list, if that distinction makes any sense to anyone else :-). I think it's unfortunate that the arrays are named EXPORT and EXPORT_OK, since to me that suggested a "mandatory/optional" relationship. Thanks for the explanation.	[reply]
Re: Perl modules, Exporter, and @EXPORT vs. @EXPORT_OK by ikegami (Patriarch) on Jul 24, 2022 at 20:37 UTC
`@EXPORT` contains symbols to always export No, not at all. As stated in the documentation, The arrays `@EXPORT` and `@EXPORT_OK` in a module hold lists of symbols that are going to be exported into the users name space by default, or which they can request to be exported, respectively. The word "always" is not present anywhere on that page. It says the symbols in `@EXPORT` are exported by default. If you want the symbols in `@EXPORT` plus others, you can use: `use Module; use Module qw( other symbols );` [download] or `use Module qw( :DEFAULT other symbols );` [download]	[reply] [d/l] [select]

edit