1Exporter::Tiny::Manual:U:sQeuricCkoSnttarritb(u3t)ed PerElxpDoorctuemre:n:tTaitniyo:n:Manual::QuickStart(3)
2
3
4

NAME

6       Exporter::Tiny::Manual::QuickStart - the quickest way to get up and
7       running with Exporter::Tiny
8

SYNOPSIS

10          package MyUtils;
11
12          use Exporter::Shiny qw( frobnicate );
13
14          sub frobnicate {
15             ...;   # your code here
16          }
17
18          1;
19
20       Now people can use your module like this:
21
22          use MyUtils "frobnicate";
23
24          frobnicate(42);
25
26       Or like this:
27
28          use MyUtils "frobnicate" => { -as => "frob" };
29
30          frob(42);
31

DESCRIPTION

33       See the synopsis. Yes, it's that simple.
34
35   Next steps
36       Default exports
37
38       Note that the module in the synopsis doesn't export anything by
39       default.  If people load "MyUtils" like this:
40
41          use MyUtils;
42
43       Then they haven't imported any functions. You can specify a default set
44       of functions to be exported like this:
45
46          package MyUtils;
47
48          use Exporter::Shiny qw( frobnicate );
49
50          our @EXPORT = qw( frobnicate );
51
52          sub frobnicate { ... }
53
54          1;
55
56       Or, if you want to be a superstar rock god:
57
58          package MyUtils;
59
60          use Exporter::Shiny our @EXPORT = qw( frobnicate );
61
62          sub frobnicate { ... }
63
64          1;
65
66       Tags
67
68       You can provide tags for people to use:
69
70          package MyUtils;
71
72          use Exporter::Shiny qw( frobnicate red green blue );
73
74          our %EXPORT_TAGS = (
75             utils   => [qw/ frobnicate /],
76             colours => [qw/ red green blue /],
77          );
78
79          sub frobnicate { ... }
80          sub red        { ... }
81          sub green      { ... }
82          sub blue       { ... }
83
84          1;
85
86       And people can now import your functions like this:
87
88          use MyUtils ":colours";
89
90       Or this:
91
92          use MyUtils "-colours";
93
94       Or take advantage of the fact that Perl magically quotes barewords
95       preceded by a hyphen:
96
97          use MyUtils -colours;
98
99       Two tags are automatically defined for you: "-default" (which is just
100       the same as @EXPORT) and "-all" (which is the union of @EXPORT and
101       @EXPORT_OK). If you don't like them, then you can override them:
102
103          our %EXPORT_TAGS = (
104             default => \@some_other_stuff,
105             all     => \@more_stuff,
106          );
107
108       Generators
109
110       Exporting normally just works by copying a sub from your package into
111       your caller's package. But sometimes it's useful instead to generate a
112       custom sub to insert into your caller's package. This is pretty easy to
113       do.
114
115          package MyUtils;
116
117          use Exporter::Shiny qw( frobnicate );
118
119          sub _generate_frobnicate {
120             my ( $me, $name, $args, $globals ) = @_;
121             my $caller = $globals->{into};
122
123             return sub {
124                 ...;  # your code here
125             };
126          }
127
128          1;
129
130       The parameter $me here is a string containing the package name which is
131       being imported from; $caller is the destination package; $name is the
132       name of the sub (in this case "frobnicate"); and $args is a custom
133       argument for this function. (By convention, $args is normally a
134       hashref.)
135
136          # The hashref { foo => 42 } is $args above.
137          #
138          use MyUtils "frobnicate" => { foo => 42 };
139
140   Avoiding Exporter::Shiny
141       Exporter::Shiny is a tiny shim around Exporter::Tiny. It should mostly
142       do what you want, but you may sometimes prefer to use Exporter::Tiny
143       directly.
144
145       The example in the synopsis could have been written as:
146
147          package MyUtils;
148
149          use parent "Exporter::Tiny";
150          our @EXPORT_OK = qw( frobnicate );
151
152          sub frobnicate {
153             ...;   # your code here
154          }
155
156          1;
157
158       What Exporter::Shiny does is mostly just to set @EXPORT_OK for you and
159       set up inheritance from the base class (Exporter::Tiny).
160
161       Exporter::Shiny also sets $INC{'MyUtils.pm'} for you, which in usually
162       makes little difference, but is useful in some edge cases.
163

SEE ALSO

165       Exporter::Shiny, Exporter::Tiny.
166
167       For more advanced information, see Exporter::Tiny::Manual::Exporting.
168

AUTHOR

170       Toby Inkster <tobyink@cpan.org>.
171

173       This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
174
175       This is free software; you can redistribute it and/or modify it under
176       the same terms as the Perl 5 programming language system itself.
177

DISCLAIMER OF WARRANTIES

179       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
180       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
181       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
182
183
184
185perl v5.36.0                      2022-11-E2x1porter::Tiny::Manual::QuickStart(3)
Impressum