NAME

Xporter - Alternative Exporter with persistant defaults & auto-ISA

VERSION

Version "0.1.1"

SYNOPIS

In the "Exporting" module:

  { package module_adder [optional version]; 
          use warnings; use strict;
    use mem;                    # to allow using module in same file
    our (@EXPORT, @EXPORT_OK);
    our $lastsum;
    our @lastargs;
    use Xporter(@EXPORT=qw(adder $lastsum @lastargs), 
                        @EXPORT_OK=qw(print_last_result));

    sub adder($$) {@lastargs=@_; $lastsum=$_[0]+$_[1]}
    sub print_last_result () {
      use P;    # using P allows answer printed or as string
      if (@lastargs && defined $lastsum){
        P "%s = %s\n", (join ' + ' , @lastargs), $lastsum;
      }
    }
  }

In use-ing module (same or different file)

  package main;  use warnings; use strict;
  use module_adder qw(print_last_result);

  adder 4,5;

Printing output:

  print_last_result();

  #Result:
  
  4 + 5 = 9

(Or in a test:)

  ok(print_last_result eq "4 + 5 = 9", "a pod test");

DESCRIPTION

Xporter provides EXPORT functionality similar to Exporter with some different rules to simplify common cases.

The primary difference, in Xporter is that the default EXPORT list remains the default EXPORT list unless the user specifically asks for it to not be included, whereas in Exporter, asking for any additional exports from the EXPORT_OK list, clears the default EXPORT list.

Xporter makes it easy to reset or clear the default so that choice is left to the user.

To reset the default EXPORT list to empty, a bare minus ('-') or logical-not sign ('!') is placed as the first parameter in the client's import list.

Example

Suppose a module has exports:

  our (@EXPORT, @EXPORT_OK);
  use Xporter(@EXPORT=qw(one $two %three @four), 
              @EXPORT_OK=qw(&five));

In the using module, to only import symbols 'two' and 'five', one would use:

Example

  use MODULENAME qw(! $two five);

That negates the default EXPORT list, and allows selective import of the values wanted from either, the default EXPORT or the EXPORT_OK lists. Note: modules in the default list don't need to be reiterated in the OK list as they are already assumed to be "OK" to export having been in the default list.

(New in 0.1) It is also possible to negate only 1 item from the default EXPORT list, as well as import optional symbols in 1 statement.

Example

  use MODULENAME qw(!$two five);      #or
  use MODULENAME qw(!two five);

Only export two from the default export list will be excluded. Whereas export five will be added to the list of items to import.

Other functions of Exporter are not currently implemented, though certainly requests and code donations made via the CPAN issue database will be considered if possible.

Types and Type Export

Listing the EXPORT and EXPORT_OK assignments as params to Xporter will allow their types to be available to importing modules at compile time. the mem module was provided as a generic way to force declarations into memory during Perl's initial BEGIN phase so they will be in effect when the program runs.

Version Strings

Version strings in the form of a decimal fraction, (0.001001), a V-String (v1.2.1 with no quotes), or a version string ('1.1.1' or 'v1.1.1') are supported, though note, versions in different formats are not interchangeable. The format specified in a module's documentation should be used.

cpanm Xporter

perl -MCPAN -e shell
install Xporter