ToolSet - Load your commonly-used modules in a single import
version 1.03
Creating a ToolSet:
# My/Tools.pm package My::Tools; use base 'ToolSet'; ToolSet->use_pragma( 'strict' ); ToolSet->use_pragma( 'warnings' ); ToolSet->use_pragma( qw/feature say switch/ ); # perl 5.10 # define exports from other modules ToolSet->export( 'Carp' => undef, # get the defaults 'Scalar::Util' => 'refaddr', # or a specific list ); # define exports from this module our @EXPORT = qw( shout ); sub shout { print uc shift }; 1; # modules must return true
Using a ToolSet:
# my_script.pl use My::Tools; # strict is on # warnings are on # Carp and refaddr are imported carp "We can carp!"; print refaddr []; shout "We can shout, too!";
ToolSet provides a mechanism for creating logical bundles of modules that can be treated as a single, reusable toolset that is imported as one. Unlike CPAN bundles, which specify modules to be installed together, a toolset specifies modules to be imported together into other code.
Toolset is designed to be a superclass -- subclasses will specify specific modules to bundle. ToolSet supports custom import lists for each included module and even supports compile-time pragmas like strict, warnings and feature.
strict
warnings
feature
A ToolSet module does not physically bundle the component modules, but rather specifies lists of modules to be used together and import specifications for each. By adding the component modules to a prerequisites list in a Makefile.PL or Build.PL for a ToolSet subclass, an entire dependency chain can be managed as a single unit across scripts or distributions that use the subclass.
Makefile.PL
Build.PL
use base 'ToolSet';
ToolSet must be used as a base class.
@EXPORT
our @EXPORT = qw( shout }; sub shout { print uc shift }
Functions defined in the ToolSet subclass can be automatically exported during use() by listing them in an @EXPORT array.
use()
export
ToolSet->export( 'Carp' => undef, 'Scalar::Util' => 'refaddr', );
Specifies packages and arguments to import via use(). An argument of undef or the empty string calls use() with default imports. Arguments should be provided either as a whitespace delimited string or in an anonymous array. An empty anonymous array will be treated like passing the empty list as an argument to use(). Here are examples of how how specifications will be provided to use():
undef
'Carp' => undef # use Carp; 'Carp' => q{} # use Carp; 'Carp' => 'carp croak' # use Carp qw( carp croak ); 'Carp' => [ '!carp', 'croak' ] # use Carp qw( !carp croak ); 'Carp' => [] # use Carp ();
Elements in an array are passed to use() as a white-space separated list, so elements may not themselves contain spaces or unexpected results will occur. (But read further below about exact whitespace handling.)
As of version 1.00, modules may be repeated multiple times. This is useful with modules like autouse.
ToolSet->export( autouse => [ 'Carp' => qw(carp croak) ], autouse => [ 'Scalar::Util' => qw(refaddr blessed) ], );
As of version 1.02, if you need exact handling of whitespace, pass a reference to a string and it will be used verbatim:
'Foo' => \'-foo => { bar => "Some thing with spaces" }' # use Foo -foo => { bar => "Some thing with spaces" }'
use_pragma
ToolSet->use_pragma( 'strict' ); # use strict; ToolSet->use_pragma( 'feature', ':5.10' ); # use feature ':5.10';
Specifies a compile-time pragma to enable and optional arguments to that pragma. This must only be used with pragmas that act via the magic $^H or %^H variables. It must not be used with modules that have other side-effects during import() such as exporting functions.
$^H
%^H
no_pragma
ToolSet->no_pragma( 'indirect' ); # no indirect;
Like use_pragma, but disables a pragma instead.
If a pragma is specified in both a use_pragma and no_pragma statement, the use_pragma will be executed first. This allow turning on a pragma with default settings and then disabling some of them.
ToolSet->use_pragma( 'strict' ); ToolSet->no_pragma ( 'strict', 'refs' );
set_feature
See use_pragma instead.
set_strict
set_warnings
ToolSet will report an error for a module that cannot be found just like an ordinary call to use() or require().
require()
Additional error messages include:
"Invalid import specification for MODULE" -- an incorrect type was provided for the list to be imported (e.g. a hash reference)
"Invalid import specification for MODULE"
"Can't import missing subroutine NAME" -- the named subroutine is listed in @EXPORT, but is not defined in the ToolSet subclass
"Can't import missing subroutine NAME"
ToolSet requires no configuration files or environment variables.
ToolSet requires at least Perl 5.6. ToolSet subclasses will, of course, be dependent on any modules they load.
Similar functionality is provided by the Toolkit module, though that module requires defining the bundle via text files found within directories in PERL5LIB and uses source filtering to insert their contents as files are compiled.
PERL5LIB
Please report any bugs or feature requests through the issue tracker at https://github.com/dagolden/ToolSet/issues. You will be notified automatically of any progress on your issue.
This is open source software. The code repository is available for public review and contribution under the terms of the license.
https://github.com/dagolden/ToolSet
git clone https://github.com/dagolden/ToolSet.git
David Golden <dagolden@cpan.org>
Haakon Haegland <Hakon.Hagland@uni.no>
This software is Copyright (c) 2017 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install ToolSet, copy and paste the appropriate command in to your terminal.
cpanm
cpanm ToolSet
CPAN shell
perl -MCPAN -e shell install ToolSet
For more information on module installation, please visit the detailed CPAN module installation guide.