CXC::Exporter::Util

"CXC::Exporter::Util" provides *tag-centric* utilities for modules which
export symbols. It doesn't provide exporting services; its sole purpose
is to manipulate the data structures used by exporting modules which
follow the API provided by Perl's core Exporter module (e.g.
Exporter::Tiny).

In particular, it treats %EXPORT_TAGS as the definitive source for
information about exportable symbols and uses it to generate @EXPORT_OK
and @EXPORT. Consolidation of symbol information in one place avoids
errors of omission.

  Exporting Symbols

At it simplest, the exporting module calls "install_EXPORTS" with a hash
specifying tags and their symbols sets, e.g.,

  package My::Exporter;
  use CXC::Exporter::Util;

  use parent 'Exporter'; # or your favorite compatible exporter

  install_EXPORTS(
            { fruit => [ 'tomato', 'apple' ],
              nut   => [ 'almond', 'walnut' ],
            } );

  sub tomato {...}
  sub apple  {...}
  sub almond {...}
  sub walnut {...}

An importing module could use this via

  use My::ExportingModule ':fruit'; # import tomato, apple
  use My::ExportingModule ':nut';   # import almond, walnut
  use My::ExportingModule ':all';   # import tomato, apple,
                                    #        almond, walnut,

For more complicated setups, %EXPORT_TAGS may be specified first:

  package My::ExportingModule;
  use CXC::Exporter::Util;

  use parent 'Exporter';
  our %EXPORT_TAGS = ( tag => [ 'Symbol1', 'Symbol2' ] );
  install_EXPORTS;

"install_EXPORTS" may be called multiple times

  Exporting Constants

CXC::Exporter::Util provides additional support for creating, organizing
and installing constants via "install_CONSTANTS". Constants are created
via Perl's constant pragma.

"install_CONSTANTS" is passed sets of constants grouped by tags, e.g.:

  install_CONSTANTS( {
        DETECTORS => {
            ACIS => 'ACIS',
            HRC  => 'HRC',
        },

        AGGREGATES => {
            ALL  => 'all',
            NONE => 'none',
            ANY  => 'any',
        },
   });

   # A call to install_EXPORTS (with or without arguments) must follow
   # install_CONSTANTS;
   install_EXPORTS;

For each set an enumerating function is created which returns the set's
values.

In the above example, constant functions "ACIS", "HRC", "ALL", "NONE",
"ANY", tags "detectors" and "aggregates", and constant functions
"DETECTORS" and "AGGREGATES" are created.

The enumerating functions are useful for generating enumerated types via
e.g. Type::Tiny:

  Enum[ DETECTORS ]

or iterating:

  say $_ for DETECTORS;

"install_CONSTANTS" may be called multiple times. If the constants are
used later in the module for other purposes, constant definition should
be done in a BEGIN block:

  BEGIN {
      install_CONSTANTS( {
          CCD => {nCCDColumns  => 1024, minCCDColumn => 0,},
      } );
  }

  install_CONSTANTS( {
      CCD => {
          maxCCDColumn => minCCDColumn + nCCDColumns - 1,
      } }
  );

  install_EXPORTS;

For more complex situations, the lower level "install_constant_tag" and
"install_constant_func" routines may be useful.

INSTALLATION

This is a Perl module distribution. It should be installed with whichever
tool you use to manage your installation of Perl, e.g. any of

  cpanm .
  cpan  .
  cpanp -i .

Consult http://www.cpan.org/modules/INSTALL.html for further instruction.
Should you wish to install this module manually, the procedure is

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

COPYRIGHT AND LICENSE

This software is Copyright (c) 2022 by Smithsonian Astrophysical
Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007