[Chapter 7] 7.2.15 Exporter - Default Import Method for Modules
Author: Larry Wall, Tom Christiansen & Randal L. Schwartz
Date: 1999-07-02T02:01:58Z

#

| Chapter 7 The Standard Perl Library |

### 7.2.15 Exporter - Default Import Method for Modules

    # in module YourModule.pm:
    package YourModule;
    use Exporter ();
    @ISA = qw(Exporter);

    @EXPORT = qw(...);              # Symbols to export by default.
    @EXPORT_OK = qw(...);           # Symbols to export on request.
    %EXPORT_TAGS = (tag => [...]);  # Define names for sets of symbols.

    # in other files that wish to use YourModule:
    use YourModule;                 # Import default symbols into my package.
    use YourModule qw(...);         # Import listed symbols into my package.
    use YourModule ();              # Do not import any symbols!

Any module may define a class method called `import()`. Perl automatically calls a module's `import()` method when processing the use statement for the module. The module itself doesn't have to define the `import()` method, though. The Exporter module implements a default `import()` method that many modules choose to inherit instead. The Exporter module supplies the customary import semantics, and any other `import()` methods will tend to deviate from the normal import semantics in various (hopefully documented) ways. Now we'll talk about the normal import semantics.

#### 7.2.15.1 Specialized import lists

Ignoring the class name, which is always the first argument to a class method, the arguments that are passed into the `import()` method are known as an import list. Usually the import list is nothing more than a list of subroutine or variable names, but occasionally you may want to get fancy. If the first entry in an import list begins with `!`, `:`, or `/`, the list is treated as a series of specifications that either add to or delete from the list of names to import. They are processed left to right. Specifications are in the form:

Symbol | Meaning
--- | ---
`[!]``name` | This `name` only
`[!]:DEFAULT` | All names in `@EXPORT`
`[!]:``tag` | All names in `$EXPORT_TAGS{``tag``}` anonymous list
`[!]/``pattern``/` | All names in `@EXPORT` and `@EXPORT_OK` that match `pattern`

A leading `!` indicates that matching names should be deleted from the list of names to import. If the first specification is a deletion, it is treated as though preceded by `:DEFAULT`. If you just want to import extra names in addition to the default set, you will still need to include `:DEFAULT` explicitly.

For example, suppose that YourModule.pm says:

    @EXPORT      = qw(A1 A2 A3 A4 A5);
    @EXPORT_OK   = qw(B1 B2 B3 B4 B5);
    %EXPORT_TAGS = (
        T1 => [qw(A1 A2 B1 B2)],
        T2 => [qw(A1 A2 B3 B4)]
    );

Individual names in `EXPORT_TAGS` must also appear in `@EXPORT` or `@EXPORT_OK`. Note that you cannot use the tags directly within either `@EXPORT` or `@EXPORT_OK` (though you could preprocess tags into either of those arrays, and in fact, the `export_tags()` and `export_ok_tags()` functions below do precisely that).

An application using YourModule can then say something like this:

    use YourModule qw(:DEFAULT :T2 !B3 A3);

The `:DEFAULT` adds in `A1`, `A2`, `A3`, `A4`, and `A5`. The `:T2` adds in only `B3` and `B4`, since `A1` and `A2` were already added. The `!B3` then deletes `B3`, and the `A3` does nothing because `A3` was already included. Other examples include:

    use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
    use POSIX  qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);

Remember that most patterns (using `//`) will need to be anchored with a leading ^, for example, `/^EXIT/` rather than `/EXIT/`.

You can say:

    BEGIN { $Exporter::Verbose=1 }

in order to see how the specifications are being processed and what is actually being imported into modules.

#### 7.2.15.2 Module version checking

The Exporter module will convert an attempt to import a number from a module into a call to `$module_name->require_version($value)`. This can be used to validate that the version of the module being used is greater than or equal to the required version. The Exporter module also supplies a default `require_version()` method, which checks the value of `$VERSION` in the exporting module.

Since the default `require_version()` method treats the `$VERSION` number as a simple numeric value, it will regard version 1.10 as lower than 1.9. For this reason it is strongly recommended that the module developer use numbers with at least two decimal places; for example, 1.09.

Prior to release 5.004 or so of Perl, this only worked with modules that use the Exporter module; in particular, this means that you can't check the version of a class module that doesn't require the Exporter module.

#### 7.2.15.3 Managing unknown symbols

In some situations you may want to prevent certain symbols from being exported. Typically this applies to extensions with functions or constants that may not exist on some systems.

The names of any symbols that cannot be exported should be listed in the `@EXPORT_FAIL` array.

If a module attempts to import any of these symbols, the Exporter will give the module an opportunity to handle the situation before generating an error. The Exporter will call an `export_fail()` method with a list of the failed symbols:

    @failed_symbols = $module_name->export_fail(@failed_symbols);

If the `export_fail()` method returns an empty list, then no error is recorded and all requested symbols are exported. If the returned list is not empty, then an error is generated for each symbol and the export fails. The Exporter provides a default `export_fail()` method that simply returns the list unchanged.

Uses for the `export_fail()` method include giving better error messages for some symbols and performing lazy architectural checks. Put more symbols into `@EXPORT_FAIL` by default and then take them out if someone actually tries to use them and an expensive check shows that they are usable on that platform.

#### 7.2.15.4 Tag handling utility functions

Since the symbols listed within `%EXPORT_TAGS` must also appear in either `@EXPORT` or `@EXPORT_OK`, two utility functions are provided that allow you to easily add tagged sets of symbols to `@EXPORT` or `@EXPORT_OK:`

    %EXPORT_TAGS = (Bactrian => [qw(aa bb cc)], Dromedary => [qw(aa cc dd)]);

    Exporter::export_tags('Bactrian');     # add aa, bb and cc to @EXPORT
    Exporter::export_ok_tags('Dromedary'); # add aa, cc and dd to @EXPORT_OK

Any names that are not tags are added to `@EXPORT` or `@EXPORT_OK` unchanged, but will trigger a warning (with -w) to avoid misspelt tag names being silently added to `@EXPORT` or `@EXPORT_OK`. Future versions may regard this as a fatal error.

7.2.14 Env - Import Environment Variables |  | 7.2.16 ExtUtils::Install - Install Files from Here to There