1Params::Coerce(3)     User Contributed Perl Documentation    Params::Coerce(3)
2
3
4

NAME

6       Params::Coerce - Allows your classes to do coercion of parameters
7

VERSION

9       version 0.15
10

SYNOPSIS

12         # Coerce a object of class Foo to a Bar
13         my $bar = Params::Coerce::coerce('Bar', $Foo)
14
15         # Create a coercion param function
16         use Params::Coerce '_Bar' => 'Bar';
17         my $bar = _Bar($Foo);
18
19         # Usage when Bar has a 'from' method
20         my $bar = Bar->from($Foo);
21
22       Real world example using HTML::Location.
23
24         # My class needs a URI
25         package Web::Spider;
26
27         use URI;
28         use Params::Coerce 'coerce';
29
30         sub new {
31             my $class = shift;
32
33             # Where do we start spidering
34             my $start = coerce('URI', shift) or die "Wasn't passed a URI";
35
36             bless { root => $start }, $class;
37         }
38
39         #############################################
40         # Now we can do the following
41
42         # Pass a URI as normal
43         my $URI     = URI->new('http://ali.as/');
44         my $Spider1 = Web::Spider->new( $URI );
45
46         # We can also pass anything that can be coerced into being a URI
47         my $Website = HTML::Location->new( '/home/adam/public_html', 'http://ali.as' );
48         my $Spider2 = Web::Spider->new( $Website );
49

DESCRIPTION

51       A big part of good API design is that we should be able to be flexible
52       in the ways that we take parameters.
53
54       Params::Coerce attempts to encourage this, by making it easier to take
55       a variety of different arguments, while adding negligible additional
56       complexity to your code.
57
58   What is Coercion
59       "Coercion" in computing terms generally refers to "implicit type
60       conversion". This is where data and object are converted from one type
61       to another behind the scenes, and you just just magically get what you
62       need.
63
64       The overload pragma, and its string overloading is the form of coercion
65       you are most likely to have encountered in Perl programming. In this
66       case, your object is automatically (within perl itself) coerced into a
67       string.
68
69       "Params::Coerce" is intended for higher-order coercion between various
70       types of different objects, for use mainly in subroutine and (mostly)
71       method parameters, particularly on external APIs.
72
73   __as_Another_Class Methods
74       At the heart of "Params::Coerce" is the ability to transform objects
75       from one thing to another. This can be done by a variety of different
76       mechanisms.
77
78       The preferred mechanism for this is by creating a specially named
79       method in a class that indicates it can be coerced into another type of
80       object.
81
82       As an example, HTML::Location provides an object method that returns an
83       equivalent URI object.
84
85         # In the package HTML::Location
86
87         # Coerce to a URI
88         sub __as_URI {
89               my $self = shift;
90               return URI->new( $self->uri );
91         }
92
93   __from_Another_Class Methods
94       From version 0.04 of "Params::Coerce", you may now also provide
95       __from_Another_Class methods as well. In the above example, rather then
96       having to define a method in HTML::Location, you may instead define one
97       in URI. The following code has an identical effect.
98
99         # In the package URI
100
101         # Coerce from a HTML::Location
102         sub __from_HTML_Location {
103               my $Location = shift;
104               return URI->new( $Location->uri );
105         }
106
107       "Params::Coerce" will only look for the __from method, if it does not
108       find a __as method.
109
110   Loading Classes
111       One thing to note with the "__as_Another_Class" methods is that you are
112       not required to load the class you are converting to in the class you
113       are converting from.
114
115       In the above example, HTML::Location does not have to load the URI
116       class. The need to load the classes for every object we might some day
117       need to be coerced to would result in highly excessive resource usage.
118
119       Instead, "Params::Coerce" guarantees that the class you are converting
120       to "will" be loaded before it calls the __as_Another_Class method. Of
121       course, in most situations you will have already loaded it for another
122       purpose in either the From or To classes and this won't be an issue.
123
124       If you make use of some class other than the class you are being
125       coerced to in the __as_Another_Class method, you will need to make sure
126       that is loaded in your code, but it is suggested that you do it at run-
127       time with a "require" if you are not using it already elsewhere.
128
129   Coercing a Parameter
130       The most explicit way of accessing the coercion functionality is with
131       the Params::Coerce::coerce function. It takes as its first argument the
132       name of the class you wish to coerce to, followed by the parameter to
133       which you wish to apply the coercion.
134
135         package My::Class;
136
137         use URI ();
138         use Params::Coerce '_URI' => 'URI';
139
140         sub new {
141               my $class = shift;
142
143               # Take a URI argument
144               my $URI = Params::Coerce::coerce('URI', shift) or return;
145
146               ...
147         }
148
149       For people doing procedural programming, you may also import this
150       function.
151
152         # Import the coerce function
153         use Params::Coerce 'coerce';
154
155       Please note that the "coerce" function is the only function that can be
156       imported, and that the two argument pragma (or the passing of two or
157       more arguments to ->import) means something different entirely.
158
159   Importing Parameter Coercion Methods
160       The second way of using Params::Coerce, and the more common one for
161       Object-Oriented programming, is to create method specifically for
162       taking parameters in a coercing manner.
163
164         package My::Class;
165
166         use URI ();
167         use Params::Coerce '_URI' => 'URI';
168
169         sub new {
170               my $class = shift;
171
172               # Take a URI as parameter
173               my $URI1 = $class->_URI(shift) or return;
174               my $URI2 = _URI(shift) or return;
175               ...
176         }
177
178   The "from" Constructor
179       From version 0.11 of "Params::Coerce", an additional mechanism is
180       available with the importable "from" constructor.
181
182         package My::Class;
183
184         use Params::Coerce 'from';
185
186         package Other::Class;
187
188         sub method {
189               my $self = shift;
190               my $My   = My::Class->from(shift) or die "Bad param";
191               ...
192         }
193
194       This is mainly a convenience. The above is equivalent to
195
196         package My::Class;
197
198         use Params::Coerce 'from' => 'Params::Coerce';
199
200       In future versions, this "->from" syntax may also tweak the resolution
201       order of the coercion.
202
203   Chained Coercion
204       While it is intended that Params::Coerce will eventually support
205       coercion using multiple steps, like
206       "<Foo::Bar-"__as_HTML_Location->__as_URI>>, it is not currently capable
207       of this. At this time only a single coercion step is supported.
208

NAME

FUNCTIONS

211   coerce $class, $param
212       The "coerce" function takes a class name and a single parameter and
213       attempts to coerce the parameter into the intended class, or one of its
214       subclasses.
215
216       Please note that it is the responsibility of the consuming class to
217       ensure that the class you wish to coerce to is loaded. "coerce" will
218       check this and die is it is not loaded.
219
220       Returns an instance of the class you specify, or one of its subclasses.
221       Returns "undef" if the parameter cannot be coerced into the class you
222       wish.
223

TO DO

225       - Write more unit tests
226
227       - Implement chained coercion
228
229       - Provide a way to coerce to string, int, etc that is compatible with
230       overload and other types of things.
231

SUPPORT

233       Bugs may be submitted through the RT bug tracker
234       <https://rt.cpan.org/Public/Dist/Display.html?Name=Params-Coerce> (or
235       bug-Params-Coerce@rt.cpan.org <mailto:bug-Params-Coerce@rt.cpan.org>).
236

AUTHOR

238       Adam Kennedy <adamk@cpan.org>
239

CONTRIBUTORS

241       •   Karen Etheridge <ether@cpan.org>
242
243       •   Adam Kennedy <adam@ali.as>
244
246       This software is copyright (c) 2004 by Adam Kennedy.
247
248       This is free software; you can redistribute it and/or modify it under
249       the same terms as the Perl 5 programming language system itself.
250
251
252
253perl v5.36.0                      2023-01-20                 Params::Coerce(3)
Impressum