.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 "Moose::Manual::Unsweetened 3pm" .TH Moose::Manual::Unsweetened 3pm 2024-03-07 "perl v5.38.2" "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 Moose::Manual::Unsweetened \- Moose idioms in plain old Perl 5 without the sugar .SH VERSION .IX Header "VERSION" version 2.2207 .SH DESCRIPTION .IX Header "DESCRIPTION" If you're trying to figure out just what the heck Moose does, and how it saves you time, you might find it helpful to see what Moose is \&\fIreally\fR doing for you. This document shows you the translation from Moose sugar back to plain old Perl 5. .SH "CLASSES AND ATTRIBUTES" .IX Header "CLASSES AND ATTRIBUTES" First, we define two very small classes the Moose way. .PP .Vb 1 \& package Person; \& \& use DateTime; \& use DateTime::Format::Natural; \& use Moose; \& use Moose::Util::TypeConstraints; \& \& has name => ( \& is => \*(Aqrw\*(Aq, \& isa => \*(AqStr\*(Aq, \& required => 1, \& ); \& \& # Moose doesn\*(Aqt know about non\-Moose\-based classes. \& class_type \*(AqDateTime\*(Aq; \& \& my $en_parser = DateTime::Format::Natural\->new( \& lang => \*(Aqen\*(Aq, \& time_zone => \*(AqUTC\*(Aq, \& ); \& \& coerce \*(AqDateTime\*(Aq \& => from \*(AqStr\*(Aq \& => via { $en_parser\->parse_datetime($_) }; \& \& has birth_date => ( \& is => \*(Aqrw\*(Aq, \& isa => \*(AqDateTime\*(Aq, \& coerce => 1, \& handles => { birth_year => \*(Aqyear\*(Aq }, \& ); \& \& enum \*(AqShirtSize\*(Aq => [qw( s m l xl xxl )]; \& \& has shirt_size => ( \& is => \*(Aqrw\*(Aq, \& isa => \*(AqShirtSize\*(Aq, \& default => \*(Aql\*(Aq, \& ); .Ve .PP This is a fairly simple class with three attributes. We also define an enum type to validate t\-shirt sizes because we don't want to end up with something like "blue" for the shirt size! .PP .Vb 1 \& package User; \& \& use Email::Valid; \& use Moose; \& use Moose::Util::TypeConstraints; \& \& extends \*(AqPerson\*(Aq; \& \& subtype \*(AqEmail\*(Aq \& => as \*(AqStr\*(Aq \& => where { Email::Valid\->address($_) } \& => message { "$_ is not a valid email address" }; \& \& has email_address => ( \& is => \*(Aqrw\*(Aq, \& isa => \*(AqEmail\*(Aq, \& required => 1, \& ); .Ve .PP This class subclasses Person to add a single attribute, email address. .PP Now we will show what these classes would look like in plain old Perl 5. For the sake of argument, we won't use any base classes or any helpers like \f(CW\*(C`Class::Accessor\*(C'\fR. .PP .Vb 1 \& package Person; \& \& use strict; \& use warnings; \& \& use Carp qw( confess ); \& use DateTime; \& use DateTime::Format::Natural; \& \& sub new { \& my $class = shift; \& my %p = ref $_[0] ? %{ $_[0] } : @_; \& \& exists $p{name} \& or confess \*(Aqname is a required attribute\*(Aq; \& $class\->_validate_name( $p{name} ); \& \& exists $p{birth_date} \& or confess \*(Aqbirth_date is a required attribute\*(Aq; \& \& $p{birth_date} = $class\->_coerce_birth_date( $p{birth_date} ); \& $class\->_validate_birth_date( $p{birth_date} ); \& \& $p{shirt_size} = \*(Aql\*(Aq \& unless exists $p{shirt_size}; \& \& $class\->_validate_shirt_size( $p{shirt_size} ); \& \& return bless \e%p, $class; \& } \& \& sub _validate_name { \& shift; \& my $name = shift; \& \& local $Carp::CarpLevel = $Carp::CarpLevel + 1; \& \& defined $name \& or confess \*(Aqname must be a string\*(Aq; \& } \& \& { \& my $en_parser = DateTime::Format::Natural\->new( \& lang => \*(Aqen\*(Aq, \& time_zone => \*(AqUTC\*(Aq, \& ); \& \& sub _coerce_birth_date { \& shift; \& my $date = shift; \& \& return $date unless defined $date && ! ref $date; \& \& my $dt = $en_parser\->parse_datetime($date); \& \& return $dt ? $dt : undef; \& } \& } \& \& sub _validate_birth_date { \& shift; \& my $birth_date = shift; \& \& local $Carp::CarpLevel = $Carp::CarpLevel + 1; \& \& $birth_date\->isa(\*(AqDateTime\*(Aq) \& or confess \*(Aqbirth_date must be a DateTime object\*(Aq; \& } \& \& sub _validate_shirt_size { \& shift; \& my $shirt_size = shift; \& \& local $Carp::CarpLevel = $Carp::CarpLevel + 1; \& \& defined $shirt_size \& or confess \*(Aqshirt_size cannot be undef\*(Aq; \& \& my %sizes = map { $_ => 1 } qw( s m l xl xxl ); \& \& $sizes{$shirt_size} \& or confess "$shirt_size is not a valid shirt size (s, m, l, xl, xxl)"; \& } \& \& sub name { \& my $self = shift; \& \& if (@_) { \& $self\->_validate_name( $_[0] ); \& $self\->{name} = $_[0]; \& } \& \& return $self\->{name}; \& } \& \& sub birth_date { \& my $self = shift; \& \& if (@_) { \& my $date = $self\->_coerce_birth_date( $_[0] ); \& $self\->_validate_birth_date( $date ); \& \& $self\->{birth_date} = $date; \& } \& \& return $self\->{birth_date}; \& } \& \& sub birth_year { \& my $self = shift; \& \& return $self\->birth_date\->year; \& } \& \& sub shirt_size { \& my $self = shift; \& \& if (@_) { \& $self\->_validate_shirt_size( $_[0] ); \& $self\->{shirt_size} = $_[0]; \& } \& \& return $self\->{shirt_size}; \& } .Ve .PP Wow, that was a mouthful! One thing to note is just how much space the data validation code consumes. As a result, it's pretty common for Perl 5 programmers to just not bother. Unfortunately, not validating arguments leads to surprises down the line ("why is birth_date an email address?"). .PP Also, did you spot the (intentional) bug? .PP It's in the \f(CW_validate_birth_date()\fR method. We should check that the value in \f(CW$birth_date\fR is actually defined and an object before we go and call \f(CWisa()\fR on it! Leaving out those checks means our data validation code could actually cause our program to die. Oops. .PP Note that if we add a superclass to Person we'll have to change the constructor to account for that. .PP (As an aside, getting all the little details of what Moose does for you just right in this example was really not easy, which emphasizes the point of the example. Moose saves you a lot of work!) .PP Now let's see User: .PP .Vb 1 \& package User; \& \& use strict; \& use warnings; \& \& use Carp qw( confess ); \& use Email::Valid; \& use Scalar::Util qw( blessed ); \& \& use parent \*(AqPerson\*(Aq; \& \& sub new { \& my $class = shift; \& my %p = ref $_[0] ? %{ $_[0] } : @_; \& \& exists $p{email_address} \& or confess \*(Aqemail_address is a required attribute\*(Aq; \& $class\->_validate_email_address( $p{email_address} ); \& \& my $self = $class\->SUPER::new(%p); \& \& $self\->{email_address} = $p{email_address}; \& \& return $self; \& } \& \& sub _validate_email_address { \& shift; \& my $email_address = shift; \& \& local $Carp::CarpLevel = $Carp::CarpLevel + 1; \& \& defined $email_address \& or confess \*(Aqemail_address must be a string\*(Aq; \& \& Email::Valid\->address($email_address) \& or confess "$email_address is not a valid email address"; \& } \& \& sub email_address { \& my $self = shift; \& \& if (@_) { \& $self\->_validate_email_address( $_[0] ); \& $self\->{email_address} = $_[0]; \& } \& \& return $self\->{email_address}; \& } .Ve .PP That one was shorter, but it only has one attribute. .PP Between the two classes, we have a whole lot of code that doesn't do much. We could probably simplify this by defining some sort of "attribute and validation" hash, like this: .PP .Vb 1 \& package Person; \& \& my %Attr = ( \& name => { \& required => 1, \& validate => sub { defined $_ }, \& }, \& birth_date => { \& required => 1, \& validate => sub { blessed $_ && $_\->isa(\*(AqDateTime\*(Aq) }, \& }, \& shirt_size => { \& required => 1, \& validate => sub { defined $_ && $_ =~ /^(?:s|m|l|xl|xxl)$/i }, \& } \& ); .Ve .PP Then we could define a base class that would accept such a definition and do the right thing. Keep that sort of thing up and we're well on our way to writing a half-assed version of Moose! .PP Of course, there are CPAN modules that do some of what Moose does, like \f(CW\*(C`Class::Accessor\*(C'\fR, \f(CW\*(C`Class::Meta\*(C'\fR, and so on. But none of them put together all of Moose's features along with a layer of declarative sugar, nor are these other modules designed for extensibility in the same way as Moose. With Moose, it's easy to write a MooseX module to replace or extend a piece of built-in functionality. .PP Moose is a complete OO package in and of itself, and is part of a rich ecosystem of extensions. It also has an enthusiastic community of users and is being actively maintained and developed. .SH AUTHORS .IX Header "AUTHORS" .IP \(bu 4 Stevan Little .IP \(bu 4 Dave Rolsky .IP \(bu 4 Jesse Luehrs .IP \(bu 4 Shawn M Moore .IP \(bu 4 יובל קוג'מן (Yuval Kogman) .IP \(bu 4 Karen Etheridge .IP \(bu 4 Florian Ragwitz .IP \(bu 4 Hans Dieter Pearcey .IP \(bu 4 Chris Prather .IP \(bu 4 Matt S Trout .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2006 by Infinity Interactive, Inc. .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.