This file is indexed.

/usr/lib/perl5/Moose/Manual/Unsweetened.pod is in libmoose-perl 2.1005-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
package Moose::Manual::Unsweetened;

# ABSTRACT: Moose idioms in plain old Perl 5 without the sugar

__END__

=pod

=head1 NAME

Moose::Manual::Unsweetened - Moose idioms in plain old Perl 5 without the sugar

=head1 VERSION

version 2.1005

=head1 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
I<really> doing for you. This document shows you the translation from
Moose sugar back to plain old Perl 5.

=head1 CLASSES AND ATTRIBUTES

First, we define two very small classes the Moose way.

  package Person;

  use DateTime;
  use DateTime::Format::Natural;
  use Moose;
  use Moose::Util::TypeConstraints;

  has name => (
      is       => 'rw',
      isa      => 'Str',
      required => 1,
  );

  # Moose doesn't know about non-Moose-based classes.
  class_type 'DateTime';

  my $en_parser = DateTime::Format::Natural->new(
      lang      => 'en',
      time_zone => 'UTC',
  );

  coerce 'DateTime'
      => from 'Str'
      => via { $en_parser->parse_datetime($_) };

  has birth_date => (
      is      => 'rw',
      isa     => 'DateTime',
      coerce  => 1,
      handles => { birth_year => 'year' },
  );

  enum 'ShirtSize' => qw( s m l xl xxl );

  has shirt_size => (
      is      => 'rw',
      isa     => 'ShirtSize',
      default => 'l',
  );

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!

  package User;

  use Email::Valid;
  use Moose;
  use Moose::Util::TypeConstraints;

  extends 'Person';

  subtype 'Email'
      => as 'Str'
      => where { Email::Valid->address($_) }
      => message { "$_ is not a valid email address" };

  has email_address => (
      is       => 'rw',
      isa      => 'Email',
      required => 1,
  );

This class subclasses Person to add a single attribute, email address.

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 C<Class::Accessor>.

  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 'name is a required attribute';
      $class->_validate_name( $p{name} );

      exists $p{birth_date}
          or confess 'birth_date is a required attribute';

      $p{birth_date} = $class->_coerce_birth_date( $p{birth_date} );
      $class->_validate_birth_date( $p{birth_date} );

      $p{shirt_size} = 'l'
          unless exists $p{shirt_size}:

      $class->_validate_shirt_size( $p{shirt_size} );

      return bless \%p, $class;
  }

  sub _validate_name {
      shift;
      my $name = shift;

      local $Carp::CarpLevel = $Carp::CarpLevel + 1;

      defined $name
          or confess 'name must be a string';
  }

  {
      my $en_parser = DateTime::Format::Natural->new(
          lang      => 'en',
          time_zone => 'UTC',
      );

      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('DateTime')
          or confess 'birth_date must be a DateTime object';
  }

  sub _validate_shirt_size {
      shift;
      my $shirt_size = shift;

      local $Carp::CarpLevel = $Carp::CarpLevel + 1;

      defined $shirt_size
          or confess 'shirt_size cannot be undef';

      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};
  }

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?").

Also, did you spot the (intentional) bug?

It's in the C<_validate_birth_date()> method. We should check that
the value in C<$birth_date> is actually defined and an object before
we go and call C<isa()> on it! Leaving out those checks means our data
validation code could actually cause our program to die. Oops.

Note that if we add a superclass to Person we'll have to change the
constructor to account for that.

(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!)

Now let's see User:

  package User;

  use strict;
  use warnings;

  use Carp qw( confess );
  use Email::Valid;
  use Scalar::Util qw( blessed );

  use base 'Person';

  sub new {
      my $class = shift;
      my %p = ref $_[0] ? %{ $_[0] } : @_;

      exists $p{email_address}
          or confess 'email_address is a required attribute';
      $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 'email_address must be a string';

      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};
  }

That one was shorter, but it only has one attribute.

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:

  package Person;

  my %Attr = (
      name => {
          required => 1,
          validate => sub { defined $_ },
      },
      birth_date => {
          required => 1,
          validate => sub { blessed $_ && $_->isa('DateTime') },
      },
      shirt_size => {
          required => 1,
          validate => sub { defined $_ && $_ =~ /^(?:s|m|l|xl|xxl)$/i },
      }
  );

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!

Of course, there are CPAN modules that do some of what Moose does,
like C<Class::Accessor>, C<Class::Meta>, 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.

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.

=head1 AUTHOR

Moose is maintained by the Moose Cabal, along with the help of many contributors. See L<Moose/CABAL> and L<Moose/CONTRIBUTORS> for details.

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Infinity Interactive, Inc..

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut