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;

This results in the definition of

*   the constant functions, i.e.,

      ACIS HRC ALL NONE ANY

    returning their specified values,

*   functions enumerating the constants' values, i.e.

      DETECTORS -> ( 'ACIS', 'HRC' )
      AGGGREGATES -> ( 'all', 'none', 'any' )

*   functions enumerating the constants' names, i.e.

      DETECTORS_NAMES -> ( 'ACIS', 'HRC' )
      AGGGREGATES_NAMES -> ( 'ALL', 'NONE', 'ANY' )

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