1NAME 2 ToolSet - Load your commonly-used modules in a single import 3 4VERSION 5 This documentation describes version 1.00. 6 7SYNOPSIS 8 Creating a ToolSet: 9 10 # My/Tools.pm 11 package My::Tools; 12 13 use base 'ToolSet'; 14 15 ToolSet->use_pragma( 'strict' ); 16 ToolSet->use_pragma( 'warnings' ); 17 ToolSet->use_pragma( qw/feature say switch/ ); # perl 5.10 18 19 # define exports from other modules 20 ToolSet->export( 21 'Carp' => undef, # get the defaults 22 'Scalar::Util' => 'refaddr', # or a specific list 23 ); 24 25 # define exports from this module 26 our @EXPORT = qw( shout ); 27 sub shout { print uc shift }; 28 29 1; # modules must return true 30 31 Using a ToolSet: 32 33 # my_script.pl 34 35 use My::Tools; 36 37 # strict is on 38 # warnings are on 39 # Carp and refaddr are imported 40 41 carp "We can carp!"; 42 print refaddr []; 43 shout "We can shout, too!"; 44 45DESCRIPTION 46 ToolSet provides a mechanism for creating logical bundles of modules 47 that can be treated as a single, reusable toolset that is imported as 48 one. Unlike CPAN bundles, which specify modules to be installed 49 together, a toolset specifies modules to be imported together into other 50 code. 51 52 ToolSet is designed to be a superclass -- subclasses will specify 53 specific modules to bundle. ToolSet supports custom import lists for 54 each included module and even supports compile-time pragmas like 55 "strict", "warnings" and "feature". 56 57 A ToolSet module does not physically bundle the component modules, but 58 rather specifies lists of modules to be used together and import 59 specifications for each. By adding the component modules to a 60 prerequisites list in a "Makefile.PL" or "Build.PL" for a ToolSet 61 subclass, an entire dependency chain can be managed as a single unit 62 across scripts or distributions that use the subclass. 63 64INTERFACE 65 Setting up 66 use base 'ToolSet'; 67 68 ToolSet must be used as a base class. 69 70 @EXPORT 71 our @EXPORT = qw( shout }; 72 sub shout { print uc shift } 73 74 Functions defined in the ToolSet subclass can be automatically exported 75 during "use()" by listing them in an @EXPORT array. 76 77 "export" 78 ToolSet->export( 79 'Carp' => undef, 80 'Scalar::Util' => 'refaddr', 81 ); 82 83 Specifies packages and arguments to import via "use()". An argument of 84 "undef" or the empty string calls "use()" with default imports. 85 Arguments should be provided either as a whitespace delimited string or 86 in an anonymous array. An empty anonymous array will be treated like 87 passing the empty list as an argument to "use()". Here are examples of 88 how how specifications will be provided to "use()": 89 90 'Carp' => undef # use Carp; 91 'Carp' => q{} # use Carp; 92 'Carp' => 'carp croak' # use Carp qw( carp croak ); 93 'Carp' => [ '!carp', 'croak' ] # use Carp qw( !carp croak ); 94 'Carp' => [] # use Carp (); 95 96 Elements in an array are passed to "use()" as a white-space separated 97 list, so elements may not themselves contain spaces or unexpected 98 results will occur. 99 100 As of version 1.00, modules may be repeated multiple times. This is 101 useful with modules like autouse. 102 103 ToolSet->export( 104 autouse => [ 'Carp' => qw(carp croak) ], 105 autouse => [ 'Scalar::Util' => qw(refaddr blessed) ], 106 ); 107 108 "use_pragma" 109 ToolSet->use_pragma( 'strict' ); # use strict; 110 ToolSet->use_pragma( 'feature', ':5.10' ); # use feature ':5.10'; 111 112 Specifies a compile-time pragma to enable and optional arguments to that 113 pragma. This must only be used with pragmas that act via the magic $^H 114 or "%^H" variables. It must not be used with modules that have other 115 side-effects during import() such as exporting functions. 116 117 "no_pragma" 118 ToolSet->no_pragma( 'indirect' ); # no indirect; 119 120 Like "use_pragma", but disables a pragma instead. 121 122 If a pragma is specified in both a "use_pragma" and "no_pragma" 123 statement, the "use_pragma" will be executed first. This allow turning 124 on a pragma with default settings and then disabling some of them. 125 126 ToolSet->use_pragma( 'strict' ); 127 ToolSet->no_pragma ( 'strict', 'refs' ); 128 129 "set_feature" (DEPRECATED) 130 See "use_pragma" instead. 131 132 "set_strict" (DEPRECATED) 133 See "use_pragma" instead. 134 135 "set_warnings" (DEPRECATED) 136 See "use_pragma" instead. 137 138DIAGNOSTICS 139 ToolSet will report an error for a module that cannot be found just like 140 an ordinary call to "use()" or "require()". 141 142 Additional error messages include: 143 144 * "Invalid import specification for MODULE" -- an incorrect type was 145 provided for the list to be imported (e.g. a hash reference) 146 147 * "Can't import missing subroutine NAME" -- the named subroutine is 148 listed in @EXPORT, but is not defined in the ToolSet subclass 149 150CONFIGURATION AND ENVIRONMENT 151 ToolSet requires no configuration files or environment variables. 152 153DEPENDENCIES 154 ToolSet requires at least Perl 5.6. ToolSet subclasses will, of course, 155 be dependent on any modules they load. 156 157SEE ALSO 158 Similar functionality is provided by the Toolkit module, though that 159 module requires defining the bundle via text files found within 160 directories in "PERL5LIB" and uses source filtering to insert their 161 contents as files are compiled. 162 163BUGS 164 Please report any bugs or feature using the CPAN Request Tracker. Bugs 165 can be submitted through the web interface at 166 <http://rt.cpan.org/Dist/Display.html?Queue=ToolSet> 167 168 When submitting a bug or request, please include a test-file or a patch 169 to an existing test-file that illustrates the bug or desired feature. 170 171AUTHOR 172 David A. Golden (DAGOLDEN) 173 174COPYRIGHT AND LICENSE 175 Copyright (c) 2005-2008 by David A. Golden. All rights reserved. 176 177 Licensed under Apache License, Version 2.0 (the "License"). You may not 178 use this file except in compliance with the License. A copy of the 179 License was distributed with this file or you may obtain a copy of the 180 License from http://www.apache.org/licenses/LICENSE-2.0 181 182 Files produced as output though the use of this software, shall not be 183 considered Derivative Works, but shall be considered the original work 184 of the Licensor. 185 186 Unless required by applicable law or agreed to in writing, software 187 distributed under the License is distributed on an "AS IS" BASIS, 188 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 189 See the License for the specific language governing permissions and 190 limitations under the License. 191 192