NAME¶

Exporter::Renaming - Allow renaming of symbols on import

SYNOPSIS¶

    # Enable renaming in Exporter
    use Exporter::Renaming;
    # Import File::Find::find as main::search
    use File::Find Renaming => [ find => search];
      
    # Disable renaming
    no Exporter::Renaming

ABSTRACT¶

Allow Renaming of symbols on Import

DESCRIPTION¶

EXAMPLES¶

All examples assume that

    use Exporter::Renaming;

has been called (and that "no Exporter::Renaming" hasn't).

The most obvious application of "Exporter::Renaming" is to solve a name conflict. Suppose our module already defines a function "find", and we want to use the standard "File::Find" module. We could then rename "find" from "File::Find" to "search" in our own module:

    use File::Find Renaming => [ find => 'search' ];

Let's assume the "finddepth" function from File::Find doesn't cause a name conflict, and we want to import it under its original name as well.

This does it in the renaming list:

    use File::Find Renaming => [
        find      => 'search',
        finddepth => undef,
    ];

...as does this, but explicitly:

    use File::Find Renaming => [
        find      => 'search',
        finddepth => 'finddepth',
    ];

...while this uses a regular import:

    use File::Find Renaming => [ find => 'search' ], 'finddepth';

Should you find it annoying that a pedantic module author has chosen to adorn all of the module's exports with a redundant prefix (these things happen), you could do this:

    use Mythical::Graphics::Module Renaming => [
          gfxColor => '%color', # this imports a hash
          gfxPen   => 'pen',
          gfxLine  => 'line',
          # ....
          # etc
    ];

...lower-casing the names as well.

If you need to add clarifying prefixes that a sloppy module author has neglected to provide in the exports (these things happen), you go the other way around:

    use Legendary::Graphics::Module Renaming [
        Color => '%gfxColor',
        Pen => 'gfxPen',
        Line => 'gfxLine',
        # ...
        # etc
    ];

...also lower-casing the initial letters.

If you are confronted with a standard module that uses a slightly non-standard naming convention (it happens), you can rectify the situation:

    use Data::Dumper Renaming => [ Dumper => 'dump' ];

Now you can say "print dump \ %some_hash" instead of "print Dumper ...";

CAVEATS¶

• As has been mentioned in section Operation, no cross-check is done between renaming exports and normal exports that go on in the same "use" statement. This means that a renaming import may later be overwritten by a normal import without a clear indication. This happens when one of the new names given in renaming coincides with one of the original ones imported through normal import.
• "Exporter::Renaming" only affects modules that do standard exporting, that is, modules that inherit their "import" method from Exporter. Modules that use a different "import" method are unaffected and don't understand renaming lists.
• Renaming doesn't affect the name c<caller> sees for a function. This should come as no surprise, since normal export doesn't affect this name either. It is always the (package-qualified) name the function was originally compiled with.

BUGS¶

• The lack of a cross-check between renaming and normal imports is regrettable, but unlikely to be fixed unless Renaming is made part of Exporter. Except for the simplest cases, only Exporter can parse an export list.
• Calls of "use Exporter::Renaming" and "no Exporter::Renaming" don't nest. Instead of switching unconditionally, "no Renaming" should only switch off the behavior if it was off in the corresponding call to "use Exporter::Renaming". A future release may address this.

SEE ALSO¶

Exporter, Perl

AUTHOR¶

Anno Siegel, <siegel@zrz.tu-berlin.de>

ACKNOWLEDGEMENTS¶

Thanks to Avi Finkel (avi@finkel.org) and Simon Cozens (simon@simon-cozens.org) for a discussion of this project on IRC. While brief, their remarks helped me think about things the right way.

COPYRIGHT AND LICENSE¶

Copyright 2003 by Anno Siegel

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.