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
57 conversion". This is where data and object are converted from one type
58 to another behind the scenes, and you just just magically get what you
59 need.
60 The overload pragma, and its string overloading is the form of coercion
62 you are most likely to have encountered in Perl programming. In this
63 case, your object is automatically (within perl itself) coerced into a
64 string.
65 "Params::Coerce" is intended for higher-order coercion between various
67 types of different objects, for use mainly in subroutine and (mostly)
68 method parameters, particularly on external APIs.
69 __as_Another_Class Methods
71 At the heart of "Params::Coerce" is the ability to transform objects
72 from one thing to another. This can be done by a variety of different
73 mechanisms.
74 The prefered mechanism for this is by creating a specially named method
76 in a class that indicates it can be coerced into another type of
77 object.
78 As an example, HTML::Location provides an object method that returns an
80 equivalent URI object.
81 # In the package HTML::Location
83 # Coerce to a URI
85 sub __as_URI {
86 my $self = shift;
87 return URI->new( $self->uri );
88 }
89 __from_Another_Class Methods
91 From version 0.04 of "Params::Coerce", you may now also provide
92 __from_Another_Class methods as well. In the above example, rather then
93 having to define a method in HTML::Location, you may instead define one
94 in URI. The following code has an identical effect.
95 # In the package URI
97 # Coerce from a HTML::Location
99 sub __from_HTML_Location {
100 my $Location = shift;
101 return URI->new( $Location->uri );
102 }
103 "Params::Coerce" will only look for the __from method, if it does not
105 find a __as method.
106 Loading Classes
108 One thing to note with the "__as_Another_Class" methods is that you are
109 not required to load the class you are converting to in the class you
110 are converting from.
111 In the above example, HTML::Location does not have to load the URI
113 class. The need to load the classes for every object we might some day
114 need to be coerced to would result in highly excessive resource usage.
115 Instead, "Params::Coerce" guarentees that the class you are converting
117 to "will" be loaded before it calls the __as_Another_Class method. Of
118 course, in most situations you will have already loaded it for another
119 purpose in either the From or To classes and this won't be an issue.
120 If you make use of some class other than the class you are being
122 coerced to in the __as_Another_Class method, you will need to make sure
123 that is loaded in your code, but it is suggested that you do it at run-
124 time with a "require" if you are not using it already elsewhere.
125 Coercing a Parameter
127 The most explicit way of accessing the coercion functionality is with
128 the Params::Coerce::coerce function. It takes as its first argument the
129 name of the class you wish to coerce to, followed by the parameter to
130 which you wish to apply the coercion.
131 package My::Class;
133 use URI ();
135 use Params::Coerce '_URI' => 'URI';
136 sub new {
138 my $class = shift;
139 # Take a URI argument
141 my $URI = Params::Coerce::coerce('URI', shift) or return;
142 ...
144 }
145 For people doing procedural programming, you may also import this
147 function.
148 # Import the coerce function
150 use Params::Coerce 'coerce';
151 Please note thatThe "coerce|Params::Coerce" function is the only
153 function that can be imported, and that the two argument pragma (or the
154 passing of two or more arguments to ->import) means something different
155 entirely.
156 Importing Parameter Coercion Methods
158 The second way of using Params::Coerce, and the more common one for
159 Object-Oriented programming, is to create method specifically for
160 taking parameters in a coercing manner.
161 package My::Class;
163 use URI ();
165 use Params::Coerce '_URI' => 'URI';
166 sub new {
168 my $class = shift;
169 # Take a URI as parameter
171 my $URI1 = $class->_URI(shift) or return;
172 my $URI2 = _URI(shift) or return;
173 ...
174 }
175 The "from" Constructor
177 From version 0.11 of "Params::Coerce", an additional mechanism is
178 available with the importable "from" constructor.
179 package My::Class;
181 use Params::Coerce 'from';
183 package Other::Class;
185 sub method {
187 my $self = shift;
188 my $My = My::Class->from(shift) or die "Bad param";
189 ...
190 }
191 This is mainly a convenience. The above is equivalent to
193 package My::Class;
195 use Params::Coerce 'from' => 'Params::Coerce';
197 In future versions, this "->from" syntax may also tweak the resolution
199 order of the coercion.
200 Chained Coercion
202 While it is intended that Params::Coerce will eventually support
203 coercion using multiple steps, like
204 "<Foo::Bar-"__as_HTML_Location->__as_URI>>, it is not currently capable
205 of this. At this time only a single coercion step is supported.
206
208 coerce $class, $param
209 The "coerce" function takes a class name and a single parameter and
210 attempts to coerce the parameter into the intended class, or one of its
211 subclasses.
212 Please note that it is the responsibility of the consuming class to
214 ensure that the class you wish to coerce to is loaded. "coerce" will
215 check this and die is it is not loaded.
216 Returns an instance of the class you specify, or one of its subclasses.
218 Returns "undef" if the parameter cannot be coerced into the class you
219 wish.
220
222 - Write more unit tests
223 - Implement chained coercion
225 - Provide a way to coerce to string, int, etc that is compatible with
227 overload and other types of things.
228
230 Bugs should always be submitted via the CPAN bug tracker
231 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Param-Coerce
233 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Param-Coerce>
234 For other issues, contact the maintainer
236
238 Adam Kennedy <adamk@cpan.org>
239
241 Copyright 2004 - 2006 Adam Kennedy.
242 This program is free software; you can redistribute it and/or modify it
244 under the same terms as Perl itself.
245 The full text of the license can be found in the LICENSE file included
247 with this module.
248perl v5.12.0 2006-10-10 Params::Coerce(3)