1Params::Coerce(3) User Contributed Perl Documentation Params::Coerce(3)
2
6 Params::Coerce - Allows your classes to do coercion of parameters
7
9 # Coerce a object of class Foo to a Bar
10 my $bar = Params::Coerce::coerce('Bar', $Foo)
11 # Create a coercion param function
13 use Params::Coerce '_Bar' => 'Bar';
14 my $bar = _Bar($Foo);
15 # Usage when Bar has a 'from' method
17 my $bar = Bar->from($Foo);
18 Real world example using HTML::Location.
20 # My class needs a URI
22 package Web::Spider;
23 use URI;
25 use Params::Coerce 'coerce';
26 sub new {
28 my $class = shift;
29 # Where do we start spidering
31 my $start = coerce('URI', shift) or die "Wasn't passed a URI";
32 bless { root => $start }, $class;
34 }
35 #############################################
37 # Now we can do the following
38 # Pass a URI as normal
40 my $URI = URI->new('http://ali.as/');
41 my $Spider1 = Web::Spider->new( $URI );
42 # We can also pass anything that can be coerced into being a URI
44 my $Website = HTML::Location->new( '/home/adam/public_html', 'http://ali.as' );
45 my $Spider2 = Web::Spider->new( $Website );
46
48 A big part of good API design is that we should be able to be flexible
49 in the ways that we take parameters.
50 Params::Coerce attempts to encourage this, by making it easier to take
52 a variety of different arguments, while adding negligable additional
53 complexity to your code.
54 What is Coercion
56 "Coercion" in computing terms generally referse to "implicit type con‐
58 version". This is where data and object are converted from one type to
59 another behind the scenes, and you just just magically get what you
60 need.
61 The overload pragma, and its string overloading is the form of coercion
63 you are most likely to have encountered in Perl programming. In this
64 case, your object is automatically (within perl itself) coerced into a
65 string.
66 "Params::Coerce" is intended for higher-order coercion between various
68 types of different objects, for use mainly in subroutine and (mostly)
69 method parameters, particularly on external APIs.
70 __as_Another_Class Methods
72 At the heart of "Params::Coerce" is the ability to transform objects
74 from one thing to another. This can be done by a variety of different
75 mechanisms.
76 The prefered mechanism for this is by creating a specially named method
78 in a class that indicates it can be coerced into another type of
79 object.
80 As an example, HTML::Location provides an object method that returns an
82 equivalent URI object.
83 # In the package HTML::Location
85 # Coerce to a URI
87 sub __as_URI {
88 my $self = shift;
89 return URI->new( $self->uri );
90 }
91 __from_Another_Class Methods
93 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
113 not required to load the class you are converting to in the class you
114 are converting from.
115 In the above example, HTML::Location does not have to load the URI
117 class. The need to load the classes for every object we might some day
118 need to be coerced to would result in highly excessive resource usage.
119 Instead, "Params::Coerce" guarentees that the class you are converting
121 to "will" be loaded before it calls the __as_Another_Class method. Of
122 course, in most situations you will have already loaded it for another
123 purpose in either the From or To classes and this won't be an issue.
124 If you make use of some class other than the class you are being
126 coerced to in the __as_Another_Class method, you will need to make sure
127 that is loaded in your code, but it is suggested that you do it at run-
128 time with a "require" if you are not using it already elsewhere.
129 Coercing a Parameter
131 The most explicit way of accessing the coercion functionality is with
133 the Params::Coerce::coerce function. It takes as its first argument the
134 name of the class you wish to coerce to, followed by the parameter to
135 which you wish to apply the coercion.
136 package My::Class;
138 use URI ();
140 use Params::Coerce '_URI' => 'URI';
141 sub new {
143 my $class = shift;
144 # Take a URI argument
146 my $URI = Params::Coerce::coerce('URI', shift) or return;
147 ...
149 }
150 For people doing procedural programming, you may also import this func‐
152 tion.
153 # Import the coerce function
155 use Params::Coerce 'coerce';
156 Please note thatThe "coerce⎪Params::Coerce" function is the only func‐
158 tion that can be imported, and that the two argument pragma (or the
159 passing of two or more arguments to ->import) means something different
160 entirely.
161 Importing Parameter Coercion Methods
163 The second way of using Params::Coerce, and the more common one for
165 Object-Oriented programming, is to create method specifically for tak‐
166 ing parameters in a coercing manner.
167 package My::Class;
169 use URI ();
171 use Params::Coerce '_URI' => 'URI';
172 sub new {
174 my $class = shift;
175 # Take a URI as parameter
177 my $URI1 = $class->_URI(shift) or return;
178 my $URI2 = _URI(shift) or return;
179 ...
180 }
181 The "from" Constructor
183 From version 0.11 of "Params::Coerce", an additional mechanism is
185 available with the importable "from" constructor.
186 package My::Class;
188 use Params::Coerce 'from';
190 package Other::Class;
192 sub method {
194 my $self = shift;
195 my $My = My::Class->from(shift) or die "Bad param";
196 ...
197 }
198 This is mainly a convenience. The above is equivalent to
200 package My::Class;
202 use Params::Coerce 'from' => 'Params::Coerce';
204 In future versions, this "->from" syntax may also tweak the resolution
206 order of the coercion.
207 Chained Coercion
209 While it is intended that Params::Coerce will eventually support coer‐
211 cion using multiple steps, like "<Foo::Bar-"__as_HTML_Loca‐
212 tion->__as_URI>>, it is not currently capable of this. At this time
213 only a single coercion step is supported.
214
216 coerce $class, $param
217 The "coerce" function takes a class name and a single parameter and
219 attempts to coerce the parameter into the intended class, or one of its
220 subclasses.
221 Please note that it is the responsibility of the consuming class to
223 ensure that the class you wish to coerce to is loaded. "coerce" will
224 check this and die is it is not loaded.
225 Returns an instance of the class you specify, or one of its subclasses.
227 Returns "undef" if the parameter cannot be coerced into the class you
228 wish.
229
231 - Write more unit tests
232 - Implement chained coercion
234 - Provide a way to coerce to string, int, etc that is compatible with
236 overload and other types of things.
237
239 Bugs should always be submitted via the CPAN bug tracker
240 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Param-Coerce>
242 For other issues, contact the maintainer
244
246 Adam Kennedy <adamk@cpan.org>
247
249 Copyright 2004 - 2006 Adam Kennedy.
250 This program is free software; you can redistribute it and/or modify it
252 under the same terms as Perl itself.
253 The full text of the license can be found in the LICENSE file included
255 with this module.
256perl v5.8.8 2006-10-10 Params::Coerce(3)