.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Toolkit 3pm"
.TH Toolkit 3pm "2008-05-29" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Toolkit \- Keep your handy modules organized
.SH "VERSION"
.IX Header "VERSION"
This document describes Toolkit version 0.0.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Toolkit;
\&
\&    # All your favorites are now available
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Toolkit module provides a standard location to store modules that you use
all the time, and then loads them for you automatically. For example, instead
of always writing:
.PP
.Vb 4
\&    use strict;
\&    use warnings;
\&    use Carp;
\&    use Smart::Comments;
.Ve
.PP
in every program/module, you can just write:
.PP
.Vb 1
\&    use Toolkit;
.Ve
.PP
and put all your favorite modules in a file:
.PP
.Vb 1
\&    > cat $PERL5LIB/Toolkit/Macros/ALWAYS/Modules
\&
\&    use strict;
\&    use warnings;
\&    use Carp;
\&    use Smart::Comments;
.Ve
.PP
You can also specify load-on-demand subroutines:
.PP
.Vb 1
\&    > cat $PERL5LIB/Toolkit/Runtime/prompt
\&
\&    use IO::Prompt qw( prompt );
\&
\&    > cat $PERL5LIB/Toolkit/Runtime/say
\&
\&    sub say { print @_, "\en" }
.Ve
.PP
in which case Toolkit will install an \f(CW\*(C`AUTOLOAD\*(C'\fR that installs these
subroutines the first time they're called.
.SH "INTERFACE"
.IX Header "INTERFACE"
Calling:
.PP
.Vb 1
\&    use Toolkit;
.Ve
.PP
with no arguments loads any files in the directories:
.PP
.Vb 2
\&    $PERL5LIB/Toolkit/Macros/ALWAYS/
\&    $PERL5LIB/Toolkit/Macros/DEFAULT/
.Ve
.PP
or any of their subdirectories.
.PP
Calling:
.PP
.Vb 1
\&    use Toolkit qw(foo bar);
.Ve
.PP
any files in the directories:
.PP
.Vb 3
\&    $PERL5LIB/Toolkit/Macros/ALWAYS/
\&    $PERL5LIB/Toolkit/Macros/foo/
\&    $PERL5LIB/Toolkit/Macros/bar/
.Ve
.PP
or any of their subdirectories.
.PP
Using the Toolkit module in any way also installs an \f(CW\*(C`AUTOLOAD\*(C'\fR subroutine
which looks in:
.PP
.Vb 1
\&    $PERL5LIB/Toolkit/Runtime/
.Ve
.PP
for a file of the same name as the subroutine that is being autoloaded. That
is, if you write:
.PP
.Vb 1
\&    use Toolkit;
\&
\&    baz();
.Ve
.PP
Then the module looks for a file:
.PP
.Vb 1
\&    $PERL5LIB/Toolkit/Runtime/baz
.Ve
.PP
and executes it in a special namespace. After the file executes, Toolkit
expects that the special namespace will now have a subroutine of the required
name, which it then calls.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP "Toolkit couldn't open %s" 4
.el .IP "Toolkit couldn't open \f(CW%s\fR" 4
.IX Item "Toolkit couldn't open %s"
You specified a particular macro for Toolkit to load, but it wasn't able to
read the corresponding file. Usually a file permissions problem or a
non-existent macro.
.ie n .IP "Undefined subroutine %s called" 4
.el .IP "Undefined subroutine \f(CW%s\fR called" 4
.IX Item "Undefined subroutine %s called"
You used a subroutine that Toolkit couldn't autoload. Did you misspell
the subroutine name, or fail to install a file of the same name in your
\&\f(CW\*(C`$PERL5LIB/Toolkit/Runtime/\*(C'\fR subdirectory.
.ie n .IP "Toolkit could not load %s\fR (running \f(CW%s didn't install it)." 4
.el .IP "Toolkit could not load \f(CW%s\fR (running \f(CW%s\fR didn't install it)." 4
.IX Item "Toolkit could not load %s (running %s didn't install it)."
You used a subroutine that Toolkit tried to autoload. It found the
corresponding file in the \f(CW\*(C`$PERL5LIB/Toolkit/Runtime/\*(C'\fR subdirectory, but
executing that file didn't produce a subroutine of the correct name.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Toolkit uses the following directories and files to configure its behaviour:
.ie n .IP "$PERL5LIB/Toolkit/Macros/ALWAYS/" 4
.el .IP "\f(CW$PERL5LIB\fR/Toolkit/Macros/ALWAYS/" 4
.IX Item "$PERL5LIB/Toolkit/Macros/ALWAYS/"
Files in this directory are prepended to your source code whenever Toolkit is
used
.ie n .IP "$PERL5LIB/Toolkit/Macros/DEFAULT/" 4
.el .IP "\f(CW$PERL5LIB\fR/Toolkit/Macros/DEFAULT/" 4
.IX Item "$PERL5LIB/Toolkit/Macros/DEFAULT/"
Files in this directory are prepended to your source code whenever Toolkit is
used without arguments
.ie n .IP "$PERL5LIB\fR/Toolkit/Macros/\fIany file name" 4
.el .IP "\f(CW$PERL5LIB\fR/Toolkit/Macros/\fIany file name\fR" 4
.IX Item "$PERL5LIB/Toolkit/Macros/any file name"
These files are prepended to your source code whenever Toolkit is used and
their name is specified after the \f(CW\*(C`use Toolkit\*(C'\fR.
.ie n .IP "$PERL5LIB/Toolkit/Runtime/" 4
.el .IP "\f(CW$PERL5LIB\fR/Toolkit/Runtime/" 4
.IX Item "$PERL5LIB/Toolkit/Runtime/"
Files in this directory are executed to whenever Toolkit is used and a
subroutine of the same name is called. They are expected to define the
required subroutine.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Requires:
.IP "\(bu" 4
File::Spec::Functions
.IP "\(bu" 4
Filter::Simple
.IP "\(bu" 4
version
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-tool\-kit@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Damian Conway  \f(CW\*(C`<DCONWAY@cpan.org>\*(C'\fR
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2005, Damian Conway \f(CW\*(C`<DCONWAY@cpan.org>\*(C'\fR. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
\&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0
\&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0
\&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0
\&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0
\&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0
\&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0
\&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
\&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
\&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0
\&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0,
\&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0
\&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
\&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
\&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
\&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0
\&\s-1SUCH\s0 \s-1DAMAGES\s0.