README
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