1Params::Coerce(3) User Contributed Perl Documentation Params::Coerce(3)
2
6 Params::Coerce - Allows your classes to do coercion of parameters
7
9 version 0.15
10
12 # Coerce a object of class Foo to a Bar
13 my $bar = Params::Coerce::coerce('Bar', $Foo)
14 # Create a coercion param function
16 use Params::Coerce '_Bar' => 'Bar';
17 my $bar = _Bar($Foo);
18 # Usage when Bar has a 'from' method
20 my $bar = Bar->from($Foo);
21 Real world example using HTML::Location.
23 # My class needs a URI
25 package Web::Spider;
26 use URI;
28 use Params::Coerce 'coerce';
29 sub new {
31 my $class = shift;
32 # Where do we start spidering
34 my $start = coerce('URI', shift) or die "Wasn't passed a URI";
35 bless { root => $start }, $class;
37 }
38 #############################################
40 # Now we can do the following
41 # Pass a URI as normal
43 my $URI = URI->new('http://ali.as/');
44 my $Spider1 = Web::Spider->new( $URI );
45 # 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
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 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 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 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 "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 __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 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 As an example, HTML::Location provides an object method that returns an
83 equivalent URI object.
84 # In the package HTML::Location
86 # Coerce to a URI
88 sub __as_URI {
89 my $self = shift;
90 return URI->new( $self->uri );
91 }
92 __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 # In the package URI
100 # Coerce from a HTML::Location
102 sub __from_HTML_Location {
103 my $Location = shift;
104 return URI->new( $Location->uri );
105 }
106 "Params::Coerce" will only look for the __from method, if it does not
108 find a __as method.
109 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 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 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 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 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 package My::Class;
136 use URI ();
138 use Params::Coerce '_URI' => 'URI';
139 sub new {
141 my $class = shift;
142 # Take a URI argument
144 my $URI = Params::Coerce::coerce('URI', shift) or return;
145 ...
147 }
148 For people doing procedural programming, you may also import this
150 function.
151 # Import the coerce function
153 use Params::Coerce 'coerce';
154 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 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 package My::Class;
165 use URI ();
167 use Params::Coerce '_URI' => 'URI';
168 sub new {
170 my $class = shift;
171 # Take a URI as parameter
173 my $URI1 = $class->_URI(shift) or return;
174 my $URI2 = _URI(shift) or return;
175 ...
176 }
177 The "from" Constructor
179 From version 0.11 of "Params::Coerce", an additional mechanism is
180 available with the importable "from" constructor.
181 package My::Class;
183 use Params::Coerce 'from';
185 package Other::Class;
187 sub method {
189 my $self = shift;
190 my $My = My::Class->from(shift) or die "Bad param";
191 ...
192 }
193 This is mainly a convenience. The above is equivalent to
195 package My::Class;
197 use Params::Coerce 'from' => 'Params::Coerce';
199 In future versions, this "->from" syntax may also tweak the resolution
201 order of the coercion.
202 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
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 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 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
225 - Write more unit tests
226 - Implement chained coercion
228 - Provide a way to coerce to string, int, etc that is compatible with
230 overload and other types of things.
231
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
238 Adam Kennedy <adamk@cpan.org>
239
241 • Karen Etheridge <ether@cpan.org>
242 • Adam Kennedy <adam@ali.as>
244
246 This software is copyright (c) 2004 by Adam Kennedy.
247 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.
250perl v5.34.0 2022-01-21 Params::Coerce(3)