.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Params::Coerce 3pm" .TH Params::Coerce 3pm "2021-01-10" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Params::Coerce \- Allows your classes to do coercion of parameters .SH "VERSION" .IX Header "VERSION" version 0.15 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # Coerce a object of class Foo to a Bar \& my $bar = Params::Coerce::coerce(\*(AqBar\*(Aq, $Foo) \& \& # Create a coercion param function \& use Params::Coerce \*(Aq_Bar\*(Aq => \*(AqBar\*(Aq; \& my $bar = _Bar($Foo); \& \& # Usage when Bar has a \*(Aqfrom\*(Aq method \& my $bar = Bar\->from($Foo); .Ve .PP Real world example using HTML::Location. .PP .Vb 2 \& # My class needs a URI \& package Web::Spider; \& \& use URI; \& use Params::Coerce \*(Aqcoerce\*(Aq; \& \& sub new { \& my $class = shift; \& \& # Where do we start spidering \& my $start = coerce(\*(AqURI\*(Aq, shift) or die "Wasn\*(Aqt passed a URI"; \& \& bless { root => $start }, $class; \& } \& \& ############################################# \& # Now we can do the following \& \& # Pass a URI as normal \& my $URI = URI\->new(\*(Aqhttp://ali.as/\*(Aq); \& my $Spider1 = Web::Spider\->new( $URI ); \& \& # We can also pass anything that can be coerced into being a URI \& my $Website = HTML::Location\->new( \*(Aq/home/adam/public_html\*(Aq, \*(Aqhttp://ali.as\*(Aq ); \& my $Spider2 = Web::Spider\->new( $Website ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A big part of good \s-1API\s0 design is that we should be able to be flexible in the ways that we take parameters. .PP Params::Coerce attempts to encourage this, by making it easier to take a variety of different arguments, while adding negligible additional complexity to your code. .SS "What is Coercion" .IX Subsection "What is Coercion" \&\*(L"Coercion\*(R" in computing terms generally refers to \*(L"implicit type conversion\*(R". This is where data and object are converted from one type to another behind the scenes, and you just just magically get what you need. .PP The overload pragma, and its string overloading is the form of coercion you are most likely to have encountered in Perl programming. In this case, your object is automatically (within perl itself) coerced into a string. .PP \&\f(CW\*(C`Params::Coerce\*(C'\fR is intended for higher-order coercion between various types of different objects, for use mainly in subroutine and (mostly) method parameters, particularly on external APIs. .SS "_\|_as_Another_Class Methods" .IX Subsection "__as_Another_Class Methods" At the heart of \f(CW\*(C`Params::Coerce\*(C'\fR is the ability to transform objects from one thing to another. This can be done by a variety of different mechanisms. .PP The preferred mechanism for this is by creating a specially named method in a class that indicates it can be coerced into another type of object. .PP As an example, HTML::Location provides an object method that returns an equivalent \s-1URI\s0 object. .PP .Vb 1 \& # In the package HTML::Location \& \& # Coerce to a URI \& sub _\|_as_URI { \& my $self = shift; \& return URI\->new( $self\->uri ); \& } .Ve .SS "_\|_from_Another_Class Methods" .IX Subsection "__from_Another_Class Methods" From version 0.04 of \f(CW\*(C`Params::Coerce\*(C'\fR, you may now also provide _\|_from_Another_Class methods as well. In the above example, rather then having to define a method in HTML::Location, you may instead define one in \s-1URI\s0. The following code has an identical effect. .PP .Vb 1 \& # In the package URI \& \& # Coerce from a HTML::Location \& sub _\|_from_HTML_Location { \& my $Location = shift; \& return URI\->new( $Location\->uri ); \& } .Ve .PP \&\f(CW\*(C`Params::Coerce\*(C'\fR will only look for the _\|_from method, if it does not find a _\|_as method. .SS "Loading Classes" .IX Subsection "Loading Classes" One thing to note with the \f(CW\*(C`_\|_as_Another_Class\*(C'\fR methods is that you are \&\fBnot\fR required to load the class you are converting to in the class you are converting from. .PP In the above example, HTML::Location does \fBnot\fR have to load the \s-1URI\s0 class. The need to load the classes for every object we might some day need to be coerced to would result in highly excessive resource usage. .PP Instead, \f(CW\*(C`Params::Coerce\*(C'\fR guarantees that the class you are converting to \&\f(CW\*(C`will\*(C'\fR be loaded before it calls the _\|_as_Another_Class method. Of course, in most situations you will have already loaded it for another purpose in either the From or To classes and this won't be an issue. .PP If you make use of some class \fBother than\fR the class you are being coerced to in the _\|_as_Another_Class method, you will need to make sure that is loaded in your code, but it is suggested that you do it at run-time with a \&\f(CW\*(C`require\*(C'\fR if you are not using it already elsewhere. .SS "Coercing a Parameter" .IX Subsection "Coercing a Parameter" The most explicit way of accessing the coercion functionality is with the Params::Coerce::coerce function. It takes as its first argument the name of the class you wish to coerce \fBto\fR, followed by the parameter to which you wish to apply the coercion. .PP .Vb 1 \& package My::Class; \& \& use URI (); \& use Params::Coerce \*(Aq_URI\*(Aq => \*(AqURI\*(Aq; \& \& sub new { \& my $class = shift; \& \& # Take a URI argument \& my $URI = Params::Coerce::coerce(\*(AqURI\*(Aq, shift) or return; \& \& ... \& } .Ve .PP For people doing procedural programming, you may also import this function. .PP .Vb 2 \& # Import the coerce function \& use Params::Coerce \*(Aqcoerce\*(Aq; .Ve .PP Please note that the \f(CW\*(C`coerce\*(C'\fR function is the \fBonly\fR function that can be imported, and that the two argument pragma (or the passing of two or more arguments to \->import) means something different entirely. .SS "Importing Parameter Coercion Methods" .IX Subsection "Importing Parameter Coercion Methods" The second way of using Params::Coerce, and the more common one for Object-Oriented programming, is to create method specifically for taking parameters in a coercing manner. .PP .Vb 1 \& package My::Class; \& \& use URI (); \& use Params::Coerce \*(Aq_URI\*(Aq => \*(AqURI\*(Aq; \& \& sub new { \& my $class = shift; \& \& # Take a URI as parameter \& my $URI1 = $class\->_URI(shift) or return; \& my $URI2 = _URI(shift) or return; \& ... \& } .Ve .ie n .SS "The ""from"" Constructor" .el .SS "The \f(CWfrom\fP Constructor" .IX Subsection "The from Constructor" From version \f(CW0.11\fR of \f(CW\*(C`Params::Coerce\*(C'\fR, an additional mechanism is available with the importable \f(CW\*(C`from\*(C'\fR constructor. .PP .Vb 1 \& package My::Class; \& \& use Params::Coerce \*(Aqfrom\*(Aq; \& \& package Other::Class; \& \& sub method { \& my $self = shift; \& my $My = My::Class\->from(shift) or die "Bad param"; \& ... \& } .Ve .PP This is mainly a convenience. The above is equivalent to .PP .Vb 1 \& package My::Class; \& \& use Params::Coerce \*(Aqfrom\*(Aq => \*(AqParams::Coerce\*(Aq; .Ve .PP In future versions, this \f(CW\*(C`\->from\*(C'\fR syntax may also tweak the resolution order of the coercion. .SS "Chained Coercion" .IX Subsection "Chained Coercion" While it is intended that Params::Coerce will eventually support coercion using multiple steps, like \f(CW\*(C`_\|_as_URI>>, it is not currently capable of this. At this time only a single coercion step is supported. .SH "NAME" .SH "FUNCTIONS" .IX Header "FUNCTIONS" .ie n .SS "coerce $class, $param" .el .SS "coerce \f(CW$class\fP, \f(CW$param\fP" .IX Subsection "coerce $class, $param" The \f(CW\*(C`coerce\*(C'\fR function takes a class name and a single parameter and attempts to coerce the parameter into the intended class, or one of its subclasses. .PP Please note that it is the responsibility of the consuming class to ensure that the class you wish to coerce to is loaded. \f(CW\*(C`coerce\*(C'\fR will check this and die is it is not loaded. .PP Returns an instance of the class you specify, or one of its subclasses. Returns \f(CW\*(C`undef\*(C'\fR if the parameter cannot be coerced into the class you wish. .SH "TO DO" .IX Header "TO DO" \&\- Write more unit tests .PP \&\- Implement chained coercion .PP \&\- Provide a way to coerce to string, int, etc that is compatible with overload and other types of things. .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted through the \s-1RT\s0 bug tracker (or bug\-Params\-Coerce@rt.cpan.org ). .SH "AUTHOR" .IX Header "AUTHOR" Adam Kennedy .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Karen Etheridge .IP "\(bu" 4 Adam Kennedy .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2004 by Adam Kennedy. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.