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

SYNOPSIS

9         # Coerce a object of class Foo to a Bar
10         my $bar = Params::Coerce::coerce('Bar', $Foo)
11
12         # Create a coercion param function
13         use Params::Coerce '_Bar' => 'Bar';
14         my $bar = _Bar($Foo);
15
16         # Usage when Bar has a 'from' method
17         my $bar = Bar->from($Foo);
18
19       Real world example using HTML::Location.
20
21         # My class needs a URI
22         package Web::Spider;
23
24         use URI;
25         use Params::Coerce 'coerce';
26
27         sub new {
28             my $class = shift;
29
30             # Where do we start spidering
31             my $start = coerce('URI', shift) or die "Wasn't passed a URI";
32
33             bless { root => $start }, $class;
34         }
35
36         #############################################
37         # Now we can do the following
38
39         # Pass a URI as normal
40         my $URI     = URI->new('http://ali.as/');
41         my $Spider1 = Web::Spider->new( $URI );
42
43         # 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

DESCRIPTION

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
51       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
55   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
61       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
66       "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
70   __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
75       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
79       As an example, HTML::Location provides an object method that returns an
80       equivalent URI object.
81
82         # In the package HTML::Location
83
84         # Coerce to a URI
85         sub __as_URI {
86               my $self = shift;
87               return URI->new( $self->uri );
88         }
89
90   __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
96         # In the package URI
97
98         # Coerce from a HTML::Location
99         sub __from_HTML_Location {
100               my $Location = shift;
101               return URI->new( $Location->uri );
102         }
103
104       "Params::Coerce" will only look for the __from method, if it does not
105       find a __as method.
106
107   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
112       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
116       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
121       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
126   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
132         package My::Class;
133
134         use URI ();
135         use Params::Coerce '_URI' => 'URI';
136
137         sub new {
138               my $class = shift;
139
140               # Take a URI argument
141               my $URI = Params::Coerce::coerce('URI', shift) or return;
142
143               ...
144         }
145
146       For people doing procedural programming, you may also import this
147       function.
148
149         # Import the coerce function
150         use Params::Coerce 'coerce';
151
152       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
157   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
162         package My::Class;
163
164         use URI ();
165         use Params::Coerce '_URI' => 'URI';
166
167         sub new {
168               my $class = shift;
169
170               # Take a URI as parameter
171               my $URI1 = $class->_URI(shift) or return;
172               my $URI2 = _URI(shift) or return;
173               ...
174         }
175
176   The "from" Constructor
177       From version 0.11 of "Params::Coerce", an additional mechanism is
178       available with the importable "from" constructor.
179
180         package My::Class;
181
182         use Params::Coerce 'from';
183
184         package Other::Class;
185
186         sub method {
187               my $self = shift;
188               my $My   = My::Class->from(shift) or die "Bad param";
189               ...
190         }
191
192       This is mainly a convenience. The above is equivalent to
193
194         package My::Class;
195
196         use Params::Coerce 'from' => 'Params::Coerce';
197
198       In future versions, this "->from" syntax may also tweak the resolution
199       order of the coercion.
200
201   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

FUNCTIONS

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
213       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
217       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

TO DO

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

SUPPORT

230       Bugs should always be submitted via the CPAN bug tracker
231
232       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Param-Coerce
233       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Param-Coerce>
234
235       For other issues, contact the maintainer
236

AUTHORS

238       Adam Kennedy <adamk@cpan.org>
239
241       Copyright 2004 - 2006 Adam Kennedy.
242
243       This program is free software; you can redistribute it and/or modify it
244       under the same terms as Perl itself.
245
246       The full text of the license can be found in the LICENSE file included
247       with this module.
248
249
250
251perl v5.12.0                      2006-10-10                 Params::Coerce(3)
Impressum