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